Skip to content

Commit 5415725

Browse files
vineet-gargvineet-garg
committed
Kms provider doc
* issue# 7399, Create KMS-provider.md and update encrypt-data.md
1 parent 7518121 commit 5415725

File tree

3 files changed

+185
-1
lines changed

3 files changed

+185
-1
lines changed

‎_data/tasks.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ toc:
150150
- docs/tasks/administer-cluster/reserve-compute-resources.md
151151
- docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md
152152
- docs/tasks/administer-cluster/declare-network-policy.md
153+
- docs/tasks/administer-cluster/kms-provider.md
153154
- title: Install Network Policy Provider
154155
section:
155156
- docs/tasks/administer-cluster/calico-network-policy.md

‎docs/tasks/administer-cluster/encrypt-data.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,8 @@ Name | Encryption | Strength | Speed | Key Length | Other Considerations
7878
`identity` | None | N/A | N/A | N/A | Resources written as-is without encryption. When set as the first provider, the resource will be decrypted as new values are written.
7979
`aescbc` | AES-CBC with PKCS#7 padding | Strongest | Fast | 32-byte | The recommended choice for encryption at rest but may be slightly slower than `secretbox`.
8080
`secretbox` | XSalsa20 and Poly1305 | Strong | Faster | 32-byte | A newer standard and may not be considered acceptable in environments that require high levels of review.
81-
`aesgcm` | AES-GCM with random nonce | Must be rotated every 200k writes | Fastest | 16, 24, or 32-byte | Is not recommended for use except when an automated key rotation scheme is implemented.
81+
`aesgcm` | AES-GCM with random nonce | Must be rotated every 200k writes | Fastest | 16, 24, or 32-byte | Is not recommended for use except when an automated key rotation scheme is implemented.
82+
`kms` | Data is encrypted using AES-CBC with PKCS#7 padding, DEKs are encrypted according to configuration in KMS | Strongest, new DEK is generated for each encryption | Fast | 32-bytes for data, Key length for encrypting DEKs is configured in kms | [Configure the KMS provider](/docs/tasks/administer-cluster/kms-provider/)
8283

8384
Each provider supports multiple keys - the keys are tried in order for decryption, and if the provider
8485
is the first provider, the first key is used for encryption.

‎docs/tasks/administer-cluster/kms-provider.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
approvers:
3+
- smarterclayton
4+
title: Using a KMS provider for data encryption
5+
---
6+
{% capture overview %}
7+
This page shows how to configure a Key Management Service (KMS) provider and plugin to enable secret data encryption.
8+
{% endcapture %}
9+
10+
{% capture prerequisites %}
11+
12+
* {% include task-tutorial-prereqs.md %}
13+
14+
* Kubernetes version 1.10.0 or later is required
15+
16+
* etcd v3 or later is required
17+
18+
*The KMS provider is alpha in Kubernetes version 1.10.0, which means that it may change without notice. You may be required to decrypt your data prior to upgrading to 1.11.0
19+
20+
{% endcapture %}
21+
22+
{% capture steps %}
23+
24+
The KMS encryption provider uses an envelope encryption scheme to encrypt data in etcd. The Key encryption keys (KEKs) are
25+
stored and managed in a remote KMS. The KMS provider uses gRPC to communicate with a specific KMS
26+
plugin. The KMS plugin, which is implemented as a gRPC server and deployed on the same host(s) as the Kubernetes master(s), is responsible for all communication with the remote KMS.
27+
28+
## Configuring the KMS provider
29+
30+
To configure a KMS provider on the API server, include a provider of type kms in the providers array in the encryption configuration file and set the following properties:
31+
32+
* `name`: Display name of the KMS plugin.
33+
* `endpoint`: Listen address of the gRPC server (KMS plugin). The endpoint is a UNIX domain socket connection.
34+
* `cachesize`: Number of data encryption keys (DEKs) to be cached in the clear. DEKs are used in Envelope encryption.
35+
36+
See [Understanding the encryption at rest configuration.](/docs/tasks/administer-cluster/encrypt-data)
37+
38+
## Implementing a KMS plugin
39+
40+
To implement a KMS plugin, you can develop a new plugin gRPC server or enable a KMS plugin already provided by your cloud provider. You then integrate the plugin with the remote KMS and deploy it on the Kubernetes master.
41+
42+
### Enabling the KMS supported by your cloud provider
43+
Refer to your cloud provider for instructions on enabling the cloud provider-specific KMS plugin.
44+
45+
### Developing a KMS plugin gRPC server
46+
You can develop a KMS plugin gRPC server using a stub file available for Go. For other languages, you use a proto file to create a stub file that you can use to develop the gRPC server code.
47+
48+
* Using Go: Use the functions and data structures in the stub file: [service.pb.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/v1beta1/service.pb.go) to develop the gRPC server code
49+
50+
* Using languages other than Go: Use the protoc compiler with the proto file: [service.proto](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/v1beta1/service.proto) to generate a stub file for the specific language
51+
52+
Then use the functions and data structures in the stub file to develop the server code.
53+
54+
**Notes:**
55+
56+
* kms plugin version: `v1beta1`
57+
58+
In response to procedure call Version, a compatible KMS plugin should return v1beta1 as VersionResponse.version
59+
60+
* message version: `v1beta1`
61+
62+
All messages from KMS provider have the version field set to current version v1beta1
63+
64+
* protocol: UNIX domain socket (`unix`)
65+
66+
The gRPC server should listen at UNIX domain socket
67+
68+
### Integrating a KMS plugin with the remote KMS
69+
The KMS plugin can communicate with the remote KMS using any protocol supported by the KMS.
70+
All configuration data, including authentication credentials the KMS plugin uses to communicate with the remote KMS,
71+
are stored and managed by the KMS plugin independently. The KMS plugin can encode the ciphertext with additional metadata that may be required before sending it to the KMS for decryption.
72+
73+
### Deploying the KMS plugin
74+
Ensure that the KMS plugin runs on the same host(s) as the Kubernetes master(s).
75+
76+
## Encrypting your data with the KMS provider
77+
To encrypt the data:
78+
79+
1. Create a new encryption configuration file using the appropriate properties for the KMS provider:
80+
81+
```yaml
82+
kind: EncryptionConfig
83+
apiVersion: v1
84+
resources:
85+
- resources:
86+
- secrets
87+
providers:
88+
- kms:
89+
name: <display name of the KMS plugin>
90+
endpoint: <UNIX domain socket listen address of the gRPC server (KMS plugin)>
91+
cachesize: <number of data encryption keys (DEKs) to be cached in the clear>
92+
- identity: {}
93+
```
94+
95+
2. Set the `--experimental-encryption-provider-config` flag on the kube-apiserver to point to the location of the configuration file.
96+
3. Restart your API server.
97+
98+
## Verifying that the data is encrypted
99+
Data is encrypted when written to etcd. After restarting your kube-apiserver, any newly created or updated secret should be encrypted when stored. To verify, you can use the etcdctl command line program to retrieve the contents of your secret.
100+
101+
1. Create a new secret called secret1 in the default namespace:
102+
```
103+
kubectl create secret generic secret1 -n default --from-literal=mykey=mydata
104+
```
105+
2. Using the etcdctl command line, read that secret out of etcd:
106+
```
107+
ETCDCTL_API=3 etcdctl get /kubernetes.io/secrets/default/secret1 [...] | hexdump -C
108+
```
109+
where [...] must be the additional arguments for connecting to the etcd server.
110+
111+
3. Verify the stored secret is prefixed with `k8s:enc:kms:v1:`, which indicates that the KMS provider has encrypted the resulting data.
112+
113+
4. Verify that the secret is correctly decrypted when retrieved via the API:
114+
```
115+
kubectl describe secret secret1 -n default
116+
```
117+
should match `mykey: mydata`
118+
119+
## Ensuring all secrets are encrypted
120+
Because secrets are encrypted on write, performing an update on a secret encrypts that content.
121+
122+
The following command reads all secrets and then updates them to apply server side encryption. If an error occurs due to a conflicting write, retry the command. For larger clusters, you may wish to subdivide the secrets by namespace or script an update.
123+
```
124+
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
125+
```
126+
127+
## Switching from a local encryption provider to the KMS provider
128+
To switch from a local encryption provider to the KMS provider and re-encrypt all of the secrets:
129+
130+
1. Add the KMS provider as the first entry in the configuration file as shown in the following example.
131+
132+
```yaml
133+
kind: EncryptionConfig
134+
apiVersion: v1
135+
resources:
136+
- resources:
137+
- secrets
138+
providers:
139+
- kms:
140+
name : <display name of the KMS plugin>
141+
endpoint: <UNIX domain socket listen address of the gRPC server (KMS plugin)>
142+
cachesize: <number of data encryption keys (DEKs) to be cached in the clear>
143+
- aescbc:
144+
keys:
145+
- name: key1
146+
secret: <BASE 64 ENCODED SECRET>
147+
```
148+
149+
2. Restart all kube-apiserver processes.
150+
151+
3. Run the following command to force all secrets to be re-encrypted using the KMS provider.
152+
153+
```
154+
kubectl get secrets --all-namespaces -o json| kubectl replace -f -
155+
```
156+
157+
## Decrypting your data
158+
To disable encryption at rest:
159+
160+
1. Place the identity provider as the first entry in the configuration file:
161+
162+
```yaml
163+
kind: EncryptionConfig
164+
apiVersion: v1
165+
resources:
166+
- resources:
167+
- secrets
168+
providers:
169+
- identity: {}
170+
- kms:
171+
name : <display name for the KMS plugin>
172+
endpoint: <unix domain socket listen address of the gRPC server (KMS plugin)>
173+
cachesize: <number of data encryption keys (DEKs) to be cached in clear>
174+
```
175+
2. Restart all kube-apiserver processes.
176+
3. Run the following command to force all secrets to be decrypted.
177+
```
178+
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
179+
```
180+
{% endcapture %}
181+
182+
{% include templates/task.md %}

0 commit comments

Comments
 (0)