forked from pivotal-cf/docs-ops-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrotate-ccdb-key.html.md.erb
102 lines (70 loc) · 5.45 KB
/
rotate-ccdb-key.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
---
title: Rotating the Cloud Controller Database Encryption Key
owner: CAPI
---
This topic describes how to rotate the Cloud Controller database (CCDB) encryption key.
## <a id="overview"></a> Overview
The Cloud Controller is the primary API of Pivotal Application Service (PAS). It has its own database, the CCDB, in which it stores information about objects in PAS such as apps. The CCDB encryption key is used to encrypt sensitive data at rest in the CCDB such as app environment variables.
The CCDB encryption key is automatically generated when you first deploy PAS. You can rotate the CCDB encryption key as described in this topic. For example, you may want to perform this procedure if your existing key is leaked.
## <a id="rotate"></a> Rotate the CCDB Encryption Key
<p class="note warning"><strong>Warning</strong>: Do not modify the <strong>Cloud Controller DB Encryption Key</strong> field in the PAS tile. This field is only for use when restoring PAS from a backup. If you modify this value at a time other than restore, commands such as <code>cf push</code> may fail. Instead, change keys using the <strong>Encryption key ledger</strong> as described below.</p>
To rotate the CCDB encryption key, do the following:
1. Navigate to the PAS tile in Ops Manager and select the **Cloud Controller** pane.
1. Review the **Encryption key ledger** field. If you previously added a key and selected the **Primary** checkbox, deselect the checkbox. The PAS deploy fails if there is more than one key with the **Primary** checkbox selected.
1. In the **Encryption key ledger** field, do the following:
<p class="note"><strong>Note</strong>: Do not remove any existing keys until after you complete the last step of this procedure. This causes the PAS deploy to fail.</p>
1. Click **Add**.
1. Enter values for **Encryption key label** and **Encryption key**.
1. Select the checkbox to mark this as your **Primary** key.
1. Click **Save**.
1. Select the **Errands** pane.
1. Set the **Rotate CC Database Key** errand to **On**.
1. Click **Save**.
1. Redeploy PAS. Once PAS deploys and the errand runs successfully, you can remove any previously specified CCDB encryption keys in the ledger.
## <a id="troubleshoot"></a> Troubleshoot Failed Rotation
This section describes how to troubleshoot errors that you may encounter while rotating the CCDB encryption key.
### <a id="values-changed"></a> Error: Encryption key(s) have had their values changed
<table>
<tr>
<th>Error</th>
<td>The PAS deploy fails a Cloud Controller error. The Cloud Controller logs include the following message: <code>Encryption key(s) mykey have had their values changed. Label and value pairs should not change, rather a new label and value pair should be added.</code></td>
</tr>
<tr>
<th>Cause</th>
<td> PAS does not support editing key names or values in the ledger. A previously existing key was edited in the PAS UI. For example, a key with the name <code>key-name</code> previously had the value <code>key-value-1</code> and now it is <code>key-value-2</code>.</td>
</tr>
<tr>
<th>Solution</th>
<td>Replace the value for the key with its original value and follow the rotation procedure to add a new key. <br>You may need to find the original value of the key using the steps in <a href="#view">View Encryption Keys</a>.</td>
</tr>
</table>
### <a id=""></a> Error: Encryption key(s) are still in use but not present in 'cc.database_encryption.keys'
<table>
<tr>
<th>Error</th>
<td>The PAS deploy fails with a Cloud Controller error. The Cloud Controller logs include the following message: <code>Encryption key(s) mykey are still in use but not present in 'cc.database_encryption.keys'</code></td>
</tr>
<tr>
<th>Cause</th>
<td>A previous key was removed from the ledger in the PAS UI before the key rotation errand ran.</td>
</tr>
<tr>
<th>Solution</th>
<td>Add the previously used key back to the ledger and redeploy PAS. <br>You may need to find the value of the previously used key using the steps in <a href="#view">View Encryption Keys</a>.
</td>
</tr>
</table>
### <a id="view"></a> View Encryption Keys
The section describes how to retrieve the value of an existing or previous encryption key. You may need to do this when troubleshooting a failed key rotation.
#### <a id="actual-installation"></a> Ops Manager actual-installation.yml
The Ops Manager `actual-installation.yml` file shows properties from the most recent successful deploy. To view the encryption keys listed in this file, do the following:
1. Follow the steps in <a href="../customizing/modify-ops-man.html#installation">Modify the Installation Files</a> to decrypt the <code>actual-installation.yml</code> file.
1. Open the <code>actual-installation.yml</code> file and view the <code>cloud_controller_encryption_keys</code> property.
#### <a id="credhub"></a> CredHub
To view current and previous encryption keys using CredHub, do the following:
1. Follow the steps in the article <a href="https://community.pivotal.io/s/article/How-to-Access-CredHub-with-the-CredHub-CLI">How to access CredHub with the CredHub CLI</a> to log in to the CredHub CLI.
1. Run the following command to view the five most recent encryption keys:
<pre>credhub get -n /opsmgr/PAS-GUID/cloud_controller/INDEX/encryption_keys --versions=5</pre>
Where:
* <code>PAS-GUID</code> is the GUID of your PAS BOSH deployment.
* <code>INDEX</code> is the zero-based index of the key. This corresponds to the order of the **Encryption key ledger** in the Ops Manager UI.