forked from pivotal-cf/docs-ops-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsecure-si-creds.html.md.erb
147 lines (107 loc) · 8.75 KB
/
secure-si-creds.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
---
title: Securing Services Instance Credentials with Runtime CredHub
owner: CredHub
---
This topic describes how <%= vars.first_product_name %> operators can ensure service instance credentials are securely stored in CredHub.
* **What is runtime CredHub?**
* The Pivotal Application Service (PAS) tile includes its own CredHub component, separate from the CredHub component included with the BOSH Director tile. For more information about this centralized credential management component, see the [CredHub](../credhub/index.html) documentation.
* **What is runtime CredHub used for?**
* Runtime CredHub exists to securely store service instance credentials. Previously, <%= vars.product_name %> could only use the Cloud Controller database for storing these credentials.
* **What are service instance credentials**?
* When developers want their app to use a service, such as those provided by the Spring Cloud Services tile for <%= vars.product_name %>, they must bind their app to an instance of that service. Service bindings include credentials that developers can use to access the service from their app. For more information, see [Binding Credentials](../services/binding-credentials.html).
* **How can I ensure that service instance credentials are stored in runtime CredHub?**
* You must configure PAS to enable this functionality by following the procedure below. Not all services support the use of runtime CredHub.
* **Can I use runtime CredHub to store service instance credentials if some of my services do not support the use of runtime CredHub?**
* PAS supports both services that do and do not use runtime CredHub. Services that do not use runtime CredHub continue to pass their credentials to the Cloud Controller database.
* **Can I rotate service instance credentials in runtime CredHub?**
* Runtime CredHub supports credential rotation. For more information, see [Rotating Runtime CredHub Encryption Keys](../opsguide/credential-rotation.html).
## <a id='services'></a> <%= vars.product_name %> Services that Use Secure Binding Credentials
The procedures in this document are only effective for services that support storing their instance credentials in runtime CredHub. To learn whether a service supports this feature, see the table below or the documentation for that service.
[//]: # (add RabbitMQ for <%= vars.product_name %> v1.12 and later when avail)
<table id='service-table' border="1" class="nice" >
<tr>
<th>Service</th>
<th>Versions with Secure Binding Credentials</th>
<th>Pivotal Network Listing</th>
</tr>
<tr>
<td>CredHub Service Broker for <%= vars.product_name %></td>
<td>All</td>
<td><a href="https://network.pivotal.io/products/credhub-service-broker">CredHub Service Broker for <%= vars.product_name %></a></td>
</tr>
<tr>
<td>MySQL for <%= vars.product_name %> v2</td>
<td>v2.3 and later (available to user groups only)</td>
<td><a href="https://network.pivotal.io/products/pivotal-mysql">MySQL for <%= vars.product_name %> v2</a></td>
</tr>
<tr>
<td>Spring Cloud Services for <%= vars.product_name %></td>
<td>v1.5 and later</td>
<td><a href="https://network.pivotal.io/products/p-spring-cloud-services">Spring Cloud Services for <%= vars.product_name %></a></td>
</tr>
<tr>
<td>RabbitMQ for <%= vars.product_name %></td>
<td>v1.12 and later</td>
<td><a href="https://network.pivotal.io/products/p-rabbitmq">RabbitMQ for <%= vars.product_name %></a></td>
</tr>
<tr>
<td>Redis for <%= vars.product_name %></td>
<td>v1.13 and later</td>
<td><a href="https://network.pivotal.io/products/p-redis">Redis for <%= vars.product_name %></a></td>
</tr>
</table>
## <a id='prereq'></a> Prerequisites
<p class="note breaking"><strong>Breaking Change</strong>: If you opt out of the <a href="http://docs.pivotal.io/pivotalcf/2-0/pcf-release-notes/runtime-rn.html#bosh-dns">BOSH DNS feature</a>, your <%= vars.product_name %> deployment cannot support Secure Service Instance Credentials.</p>
Runtime CredHub allows you to use one or more Hardware Security Modules (HSMs) to store encryption keys. If you wish to use an HSM with CredHub, you must configure the HSM before completing the procedures below. For more information, see [Preparing CredHub HSMs for Configuration](../customizing/hsm-config.html).
## <a id='pas-config'></a> Step 1: Configure the PAS Tile
To configure the PAS tile to support securing service instance credentials in CredHub, you need to:
* In the **CredHub** pane, provide at least one encryption key. CredHub supports multiple encryption key providers.
* In the **Resource Config** pane, set the number of **CredHub** instances to at least one.
CredHub configuration options include:
* Internal or external databases
* Encryption keys stored internally, externally in a Hardware Security Module (HSM), or both
To configure the PAS tile, follow the instructions in [Configuring PAS](../customizing/configure-pas.html).
## <a id='asgs'></a> Step 2: Create Application Security Groups
Application Security Groups (ASGs) are network policy rules specifying protocols, ports, and IP ranges that apply to outbound network connections initiated from apps. You must follow the steps below to ensure the ASGs for your deployment allow apps to communicate with the runtime CredHub API.
<p class="note"><strong>Note</strong>: The default ASGs in <%= vars.product_name %> allow apps running on your deployment to send traffic to almost any IP address. This step is only required if your ASGs restrict network access from apps to the network that PAS runs on, as documented in <a href="./app-sec-groups.html">Restricting App Access to Internal <%= vars.product_name %> Components</a>.</p>
1. From the PAS tile, click **Assign AZs and Networks** and record the selected Network where the tile is installed.
1. From the BOSH Director tile, within the **Settings** tab, click **Create Networks**.
1. In the **Networks** section, click the name of the PAS network to expand it.
1. Record the CIDR for the PAS network.
1. Create a file named `runtime-credhub.json` for specifying your ASG rules. Copy the content below into the file. Replace `YOUR-PAS-CIDR` with the CIDR you recorded in the previous step.
```
[
{
"protocol": "tcp",
"destination": "YOUR-PAS-CIDR",
"ports": "8844"
}
]
```
1. Run the following command to create an ASG that allows apps to access the CredHub API:
<pre class="terminal">
$ cf create-security-group runtime-credhub ~/workspace/runtime-credhub runtime-credhub.json
</pre>
1. Bind this ASG to your deployment or the specific space in which you want apps to access CredHub. For more information about binding ASGs, see [Bind ASGs](../concepts/asg.html#binding-groups). Ensure that apps deployed as part of the service tile installation process have access to CredHub in addition to the apps pushed to the platform by developers. For example, the Spring Cloud Services tile deploys the `spring-cloud-broker` app to the `p-spring-cloud-services` space of the `system` org.
1. Restart apps for the ASGs to take effect. Optionally, you can use the [app-restarter cf CLI plugin](https://github.com/cloudfoundry-incubator/app-restarter) to restart all apps in a particular space, org, or deployment.
## <a id='service-instances'></a> Step 3: Unbind and Rebind Service Instances
For any service instance bindings that existed before runtime CredHub was supported for that service, you must work with your developers to unbind and rebind the service instances to their apps. If you do not unbind and rebind the service, apps continue functioning as normal and fetching credentials from the Cloud Controller database.
<p class="note"><strong>Note</strong>: This step is not required for bindings created after you installed the new version of the service tile that supports CredHub and you completed the procedures in steps 1 and 2 of this topic.</p>
1. Unbind the service instance from the app:
<pre class="terminal">
$ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
</pre>
1. Rebind the service instance to the app:
<pre class="terminal">
$ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
</pre>
1. Review the `VCAP_SERVICES` environment variable to verify that the new service instance binding includes CredHub pointers:
<pre class="terminal">
$ cf env YOUR-APP
</pre>
See the [VCAP_SERVICES](../devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) section of _Cloud Foundry Environment Variables_ for help parsing the output of the `cf-env` command.
1. Restart the app to apply the service instance binding:
<pre class="terminal">
$ cf restart YOUR-APP
</pre>
If you run `cf-env` again, you can see the `VCAP-SERVICES` environment variable now contains the credentials for the service instance binding.