|
1 | | -# Kubernetes v1.25: KMS v2 Improvements |
| 1 | +--- |
| 2 | +layout: blog |
| 3 | +title: "Kubernetes 1.25: KMS V2 Improvements" |
| 4 | +date: 2022-09-09 |
| 5 | +slug: kms-v2-improvements |
| 6 | +--- |
2 | 7 |
|
3 | 8 | **Authors:** Anish Ramasekar, Rita Zhang, Mo Khan, and Xander Grzywinski (Microsoft) |
4 | 9 |
|
5 | | -With Kubernetes v1.25, we are introducing a new `v2alpha1` version of the Key Management Service (KMS) API. There are a lot of improvements in the works, and we're excited to be able to start down the path of a new and improved KMS! |
| 10 | +With Kubernetes v1.25, SIG Auth is introducing a new `v2alpha1` version of the Key Management Service (KMS) API. There are a lot of improvements in the works, and we're excited to be able to start down the path of a new and improved KMS! |
6 | 11 |
|
7 | 12 | ## What is KMS? |
8 | | -One of the first things to consider when securing a Kubernetes cluster is encrypting etcd data at rest. KMS provides an interface for a provider to utilize a key stored in an external key service to perform this encryption. |
| 13 | +One of the first things to consider when securing a Kubernetes cluster is encrypting persisted API data at rest. KMS provides an interface for a provider to utilize a key stored in an external key service to perform this encryption. |
9 | 14 |
|
10 | | -KMS v1 has been a feature of Kubernetes since version v1.10, and is currently in beta as of version v1.12. |
| 15 | +Encryption at rest using KMS v1 has been a feature of Kubernetes since version v1.10, and is currently in beta as of version v1.12. |
11 | 16 |
|
12 | 17 | ## What’s new in `v2alpha1`? |
13 | 18 | While the original v1 implementation has been successful in helping Kubernetes users encrypt etcd data, it did fall short in a few key ways: |
14 | 19 |
|
15 | 20 | 1. **Performance:** When starting a cluster, all resources are serially fetched and decrypted to fill the `kube-apiserver` cache. When using a KMS plugin, this can cause slow startup times due to the large number of requests made to the remote vault. In addition, there is the potential to hit API rate limits on external key services depending on how many encrypted resources exist in the cluster. |
16 | | -1. **Rotation:** Currently, rotation of a KMS key is a manual and error-prone process. It can be difficult to determine what encryption keys are in-use on a cluster. |
17 | | -1. **Health Check & Status:** Today the `kube-apiserver` uses encrypt and decrypt calls as a proxy to determine if the KMS plugin is healthy. These operations cost money with cloud services, and do not provide a holistic view of the service's health. |
18 | | -1. **Observability:** Without some kind of trace ID, it's currently difficult to correlate events found in the various logs across `kube-apiserver`, KMS, and KMS plugins. |
| 21 | +1. **Key Rotation:** With KMS v1, rotation of a key-encrypting key is a manual and error-prone process. It can be difficult to determine what encryption keys are in-use on a cluster. |
| 22 | +1. **Health Check & Status:** Before the KMS v2 API, the `kube-apiserver` was forced to make encrypt and decrypt calls as a proxy to determine if the KMS plugin is healthy. With cloud services these operations usually cost actual money with cloud service. Whatever the cost, those operations on their own do not provide a holistic view of the service's health. |
| 23 | +1. **Observability:** Without some kind of trace ID, it's has been difficult to correlate events found in the various logs across `kube-apiserver`, KMS, and KMS plugins. |
19 | 24 |
|
20 | | -The KMS v2 enhancement attempts to address all of these shortcomings (not all planned features are implemented in the initial alpha release in Kubernetes v1.25): |
| 25 | +The KMS v2 enhancement attempts to address all of these shortcomings, though not all planned features are implemented in the initial alpha release. Here are the improvements that arrived in Kubernetes v1.25: |
21 | 26 |
|
22 | | -1. Support KMS plugins that use a key hierarchy to reduce network requests made to the remote vault. To learn more, check out the [details for how a KMS plugin can leverage key hierarchy](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/3299-kms-v2-improvements#key-hierachy). |
| 27 | +1. Support for KMS plugins that use a key hierarchy to reduce network requests made to the remote vault. To learn more, check out the [design details for how a KMS plugin can leverage key hierarchy](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/3299-kms-v2-improvements#key-hierachy). |
23 | 28 | 1. Extra metadata is now tracked to allow a KMS plugin to communicate what key it is currently using with the `kube-apiserver`, allowing for rotation without API server restart. Data stored in etcd follows a more standard proto format to allow external tools to observe its state. To learn more, check out the [details for metadata](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/3299-kms-v2-improvements#metadata). |
24 | 29 | 1. A dedicated status API is used to communicate the health of the KMS plugin with the API server. To learn more, check out the [details for status API](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/3299-kms-v2-improvements#status-api). |
25 | 30 | 1. To improve observability, a new `UID` field is included in `EncryptRequest` and `DecryptRequest` of the v2 API. The UID is generated for each envelope operation. To learn more, check out the [details for observability](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/3299-kms-v2-improvements#Observability). |
26 | 31 |
|
27 | 32 | ### Sequence Diagram |
28 | 33 |
|
29 | 34 | #### Encrypt Request |
30 | | - |
31 | | -```mermaid |
32 | | -sequenceDiagram |
33 | | - participant etcd |
34 | | - participant kubeapiserver |
35 | | - participant kmsplugin |
36 | | - participant externalkms |
37 | | - kubeapiserver->>kmsplugin: encrypt request |
38 | | - alt using key hierarchy |
39 | | - kmsplugin->>kmsplugin: encrypt DEK with local KEK |
40 | | - kmsplugin->>externalkms: encrypt local KEK with remote KEK |
41 | | - externalkms->>kmsplugin: encrypted local KEK |
42 | | - kmsplugin->>kmsplugin: cache encrypted local KEK |
43 | | - kmsplugin->>kubeapiserver: return encrypt response <br/> {"ciphertext": "<encrypted DEK>", key_id: "<remote KEK ID>", <br/> "annotations": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}} |
44 | | - else not using key hierarchy |
45 | | - %% current behavior |
46 | | - kmsplugin->>externalkms: encrypt DEK with remote KEK |
47 | | - externalkms->>kmsplugin: encrypted DEK |
48 | | - kmsplugin->>kubeapiserver: return encrypt response <br/> {"ciphertext": "<encrypted DEK>", key_id: "<remote KEK ID>", "annotations": {}} |
49 | | - end |
50 | | - kubeapiserver->>etcd: store encrypt response and encrypted DEK |
51 | | -``` |
| 35 | +[](https://mermaid.live/edit#pako:eNrNVD1v2zAQ_SsEC0GLkxgt2kEIvEQeCo8tOgkoTuTJIiyRypFMIwj67yUlxx-w0CLoUg0a7t29e3eP5MCFkcgzniSD0splbEhdjS2mGUtLsJiu2Bz4AaSgbNAGZGBpR6oF6p9MYyjmfvj08YvAzzH9CH3HV3eGq6qaqK6C6_U6HccxSQpt8dmjFpgr2BO0hWbh64CcEqoD7Rg6IW-jB18idMoivSAtwK3tGr9XeoHv1SFpaELKDF5R3W02p9qMBWHUd45RFGndnA-NY94qvWcH7FmtkIBE3c_gRPhGsEyWb3fsl3I1a4yAhu22u-XSC6Hn4lPNTEHYGofXHBd1iwJQ_q3zRY0AUeM7Ki93mQV5zpO-WKPtTHCcPZb0sGFDwYMnNVI8HAXPWMEfz53CmjYFX8Ul_1RyAs_Tsq_5BM5EBQetjQOnAnskCsxB1X1UQxod2ntlHibpdwc83LQ6DRU4x3GeDJugM5D-2eokYcITYThXJdbwogy9w8z8H23M_xcbbg04rVHL5VsWr3XGrDOEt8JAy6Ux45-veIvUgpLh8RpipODTOzUrl1iBb8IYhR5Dqu8kONxKFfrwrIJg6oqDd-ZbrwXPHHl8Szo-QMes8Tffb72O) |
52 | 36 | #### Decrypt Request |
53 | | - |
54 | | -```mermaid |
55 | | -sequenceDiagram |
56 | | - participant kubeapiserver |
57 | | - participant kmsplugin |
58 | | - participant externalkms |
59 | | - %% if local KEK in annotations, then using hierarchy |
60 | | - alt encrypted local KEK is in annotations |
61 | | - kubeapiserver->>kmsplugin: decrypt request <br/> {"ciphertext": "<encrypted DEK>", key_id: "<key_id gotten as part of EncryptResponse>", <br/> "annotations": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}} |
62 | | - alt encrypted local KEK in cache |
63 | | - kmsplugin->>kmsplugin: decrypt DEK with local KEK |
64 | | - else encrypted local KEK not in cache |
65 | | - kmsplugin->>externalkms: decrypt local KEK with remote KEK |
66 | | - externalkms->>kmsplugin: decrypted local KEK |
67 | | - kmsplugin->>kmsplugin: decrypt DEK with local KEK |
68 | | - kmsplugin->>kmsplugin: cache decrypted local KEK |
69 | | - end |
70 | | - kmsplugin->>kubeapiserver: return decrypt response <br/> {"plaintext": "<decrypted DEK>", key_id: "<remote KEK ID>", <br/> "annotations": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}} |
71 | | - else encrypted local KEK is not in annotations |
72 | | - kubeapiserver->>kmsplugin: decrypt request <br/> {"ciphertext": "<encrypted DEK>", key_id: "<key_id gotten as part of EncryptResponse>", <br/> "annotations": {}} |
73 | | - kmsplugin->>externalkms: decrypt DEK with remote KEK (same behavior as today) |
74 | | - externalkms->>kmsplugin: decrypted DEK |
75 | | - kmsplugin->>kubeapiserver: return decrypt response <br/> {"plaintext": "<decrypted DEK>", key_id: "<remote KEK ID>", <br/> "annotations": {}} |
76 | | - end |
77 | | -``` |
| 37 | +[](https://mermaid.live/edit#pako:eNrVVU2P0zAQ_SsjoyggdXcrEHuIVr3QHlBvgDhFQtN40lhN7GA7C1GU_47jdOuUhi4HkKCn1DPzPkbPcscyxYklLIo6IYVNoIttQRXFCcQ7NBQvYDz4jFrgriTjKh3EtRYV6vadKpUeel-8eX2f0duh_Vj6RN9tKOd57qHODpfLZdz3fRSl0tDXhmRGa4F7jVUqwf1q1FZkokZp4dDsCGthSD-SnilXpi6bvZCXJUdJWmLpWsZiFIHIoVQZlrDdbEFIQCmVRSuUNAtwfiU0Rsg9FII06qxox0ksHZzMdFtb4lME8xPI2A7nqm9Wq5PMBDh5HNCDc2PhYafvVtClzMkuSA-bSlkCKXsIjOvNdpWyBRyo_SK4L46fsFfWOtVovHVQOWzGqQ9kaieI_NzIkbKpUsfhSJ2w20GslmTJ3Ap1593dHOhwoeLk22H2_ZPVK9uRkGFWUOj0q3laxfxanFX4JmwRcMI4lYZmmZyr32CbBCLwBRDPqqlSls5pPXWYndU9lfPH_F4Z91avk5Pk4c8ZzDScibNsGy0nuRyDE4JZlyjkJJeBdSaXYYHwfv2Xw_fLPLh7eYzEzN38b27n9I49m-P1ZYLhpcGKYEcFPgqlBxlWcWxfTTLyfKzX00z9gzE6hUFytmAV6QoFdy9bNxynzD9iIyOnHJvS0aeyd61NzdHShgurNEtydGFaMGys-tjKjCVWN_TUdHydjl39D0CLbdk) |
78 | 38 |
|
79 | 39 | ## What’s next? |
80 | | -For Kubernetes v1.26, we plan to ship another alpha version. As of right now, the alpha API will be ready to be used by KMS plugin authors. We plan to include a reference plugin implementation with the next release, and you'll be able to try out the feature at that time. |
| 40 | +For Kubernetes v1.26, we expect to ship another alpha version. As of right now, the alpha API will be ready to be used by KMS plugin authors. We hope to include a reference plugin implementation with the next release, and you'll be able to try out the feature at that time. |
81 | 41 |
|
82 | | -You can learn more about KMS v2 by reading the [kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/). You can also follow along on the [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/3299-kms-v2-improvements/README.md) to track progress across the coming Kubernetes releases. |
| 42 | +You can learn more about KMS v2 by reading [Using a KMS provider for data encryption](/docs/tasks/administer-cluster/kms-provider/). You can also follow along on the [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/3299-kms-v2-improvements/#readme) to track progress across the coming Kubernetes releases. |
83 | 43 |
|
84 | 44 | ## How to get involved |
85 | 45 | If you are interested in getting involved in the development of this feature or would like to share feedback, please reach out on the [#sig-auth-kms-dev](https://kubernetes.slack.com/archives/C03035EH4VB) channel on Kubernetes Slack. |
|
0 commit comments