update docs for KMSv2 and KMSv2KDF stable
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>pull/43398/head
Anish Ramasekar
parent
9e36b6ca44
commit
8598729e5d
|
|
@ -120,9 +120,6 @@ For a reference to old feature gates that are removed, please refer to
|
|||
| `JobPodFailurePolicy` | `true` | Beta | 1.26 | |
|
||||
| `JobPodReplacementPolicy` | `false` | Alpha | 1.28 | 1.28 |
|
||||
| `JobPodReplacementPolicy` | `true` | Beta | 1.29 | |
|
||||
| `KMSv2` | `false` | Alpha | 1.25 | 1.26 |
|
||||
| `KMSv2` | `true` | Beta | 1.27 | |
|
||||
| `KMSv2KDF` | `false` | Beta | 1.28 | |
|
||||
| `KubeProxyDrainingTerminatingNodes` | `false` | Alpha | 1.28 | |
|
||||
| `KubeletCgroupDriverFromCRI` | `false` | Alpha | 1.28 | |
|
||||
| `KubeletInUserNamespace` | `false` | Alpha | 1.22 | |
|
||||
|
|
@ -274,7 +271,13 @@ For a reference to old feature gates that are removed, please refer to
|
|||
| `JobTrackingWithFinalizers` | `false` | Beta | 1.23 | 1.24 |
|
||||
| `JobTrackingWithFinalizers` | `true` | Beta | 1.25 | 1.25 |
|
||||
| `JobTrackingWithFinalizers` | `true` | GA | 1.26 | |
|
||||
| `KMSv1` | `true` | Deprecated | 1.28 | |
|
||||
| `KMSv1` | `true` | Deprecated | 1.28 | 1.29 |
|
||||
| `KMSv1` | `false` | Deprecated | 1.29 | |
|
||||
| `KMSv2` | `false` | Alpha | 1.25 | 1.26 |
|
||||
| `KMSv2` | `true` | Beta | 1.27 | 1.28 |
|
||||
| `KMSv2` | `true` | GA | 1.29 | |
|
||||
| `KMSv2KDF` | `false` | Beta | 1.28 | 1.29 |
|
||||
| `KMSv2KDF` | `true` | GA | 1.29 | |
|
||||
| `KubeletPodResources` | `false` | Alpha | 1.13 | 1.14 |
|
||||
| `KubeletPodResources` | `true` | Beta | 1.15 | 1.27 |
|
||||
| `KubeletPodResources` | `true` | GA | 1.28 | |
|
||||
|
|
|
|||
|
|
@ -248,7 +248,7 @@ The following table describes each available provider.
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th rowspan="2" scope="row"><tt>kms</tt> v2 <em>(beta)</em></th>
|
||||
<th rowspan="2" scope="row"><tt>kms</tt> v2 </th>
|
||||
<td>Uses envelope encryption scheme with DEK per API server.</td>
|
||||
<td>Strongest</td>
|
||||
<td>Fast</td>
|
||||
|
|
@ -259,14 +259,10 @@ The following table describes each available provider.
|
|||
Data is encrypted by data encryption keys (DEKs) using AES-GCM; DEKs
|
||||
are encrypted by key encryption keys (KEKs) according to configuration
|
||||
in Key Management Service (KMS).
|
||||
Kubernetes defaults to generating a new DEK at API server startup, which is then
|
||||
reused for object encryption.
|
||||
If you enable the <tt>KMSv2KDF</tt>
|
||||
<a href="/docs/reference/command-line-tools-reference/feature-gates/">feature gate</a>,
|
||||
Kubernetes instead generates a new DEK per encryption from a secret seed.
|
||||
Whichever approach you configure, the DEK or seed is also rotated whenever the KEK is rotated.<br/>
|
||||
Kubernetes generates a new DEK per encryption from a secret seed.
|
||||
The seed is rotated whenever the KEK is rotated.<br/>
|
||||
A good choice if using a third party tool for key management.
|
||||
Available in beta from Kubernetes v1.27.
|
||||
Available in stable from Kubernetes v1.29.
|
||||
<br />
|
||||
Read how to <a href="/docs/tasks/administer-cluster/kms-provider#configuring-the-kms-provider-kms-v2">configure the KMS V2 provider</a>.
|
||||
</td>
|
||||
|
|
@ -538,4 +534,3 @@ To allow automatic reloading, configure the API server to run with:
|
|||
|
||||
* Read about [decrypting data that are already stored at rest](/docs/tasks/administer-cluster/decrypt-data/)
|
||||
* Learn more about the [EncryptionConfiguration configuration API (v1)](/docs/reference/config-api/apiserver-encryption.v1/).
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ weight: 370
|
|||
<!-- overview -->
|
||||
This page shows how to configure a Key Management Service (KMS) provider and plugin to enable secret data encryption.
|
||||
In Kubernetes {{< skew currentVersion >}} there are two versions of KMS at-rest encryption.
|
||||
You should use KMS v2 if feasible because KMS v1 is deprecated (since Kubernetes v1.28).
|
||||
You should use KMS v2 if feasible because KMS v1 is deprecated (since Kubernetes v1.28) and disabled by default (since Kubernetes v1.29).
|
||||
However, you should also read and observe the **Caution** notices in this page that highlight specific
|
||||
cases when you must not use KMS v2. KMS v2 offers significantly better performance characteristics than KMS v1.
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ you have selected. Kubernetes recommends using KMS v2.
|
|||
(if you are running a different version of Kubernetes that also supports the v2 KMS
|
||||
API, switch to the documentation for that version of Kubernetes).
|
||||
- If you selected KMS API v1 to support clusters prior to version v1.27
|
||||
or if you have a legacy KMS plugin that only supports KMS v1,
|
||||
or if you have a legacy KMS plugin that only supports KMS v1,
|
||||
any supported Kubernetes version will work. This API is deprecated as of Kubernetes v1.28.
|
||||
Kubernetes does not recommend the use of this API.
|
||||
|
||||
|
|
@ -35,18 +35,17 @@ you have selected. Kubernetes recommends using KMS v2.
|
|||
|
||||
* Kubernetes version 1.10.0 or later is required
|
||||
|
||||
* For version 1.29 and later, the feature is disabled by default.
|
||||
To enable the feature, set `--feature-gates=KMSv1=true` to configure a KMS v1 provider.
|
||||
|
||||
* Your cluster must use etcd v3 or later
|
||||
|
||||
### KMS v2
|
||||
{{< feature-state for_k8s_version="v1.27" state="beta" >}}
|
||||
{{< feature-state for_k8s_version="v1.29" state="stable" >}}
|
||||
|
||||
* For version 1.25 and 1.26, enabling the feature via kube-apiserver feature gate is required.
|
||||
Set `--feature-gates=KMSv2=true` to configure a KMS v2 provider.
|
||||
For environments where all API servers are running version 1.28 or later, and you do not require the ability
|
||||
to downgrade to Kubernetes v1.27, you can enable the `KMSv2KDF` feature gate (a beta feature) for more
|
||||
robust data encryption key generation. The Kubernetes project recommends enabling KMS v2 KDF if those
|
||||
preconditions are met.
|
||||
|
||||
|
||||
* Your cluster must use etcd v3 or later
|
||||
|
||||
{{< caution >}}
|
||||
|
|
@ -56,8 +55,9 @@ enabled will result in data loss.
|
|||
|
||||
---
|
||||
|
||||
Running mixed API server versions with some servers at v1.27, and others at v1.28 _with the
|
||||
`KMSv2KDF` feature gate enabled_ is **not supported** - and is likely to result in data loss.
|
||||
`KMSv2KDF` feature gate is enabled by default in v1.29 and cannot be disabled.
|
||||
Running mixed API server versions with some servers at v1.28 _with the `KMSv2KDF` feature gate disabled_,
|
||||
and others at v1.29 is **not supported** - and is likely to result in data loss.
|
||||
{{< /caution >}}
|
||||
|
||||
<!-- steps -->
|
||||
|
|
@ -68,47 +68,16 @@ The DEKs are encrypted with a key encryption key (KEK) that is stored and manage
|
|||
|
||||
With KMS v1, a new DEK is generated for each encryption.
|
||||
|
||||
With KMS v2, there are two ways for the API server to generate a DEK.
|
||||
Kubernetes defaults to generating a new DEK at API server startup, which is then reused
|
||||
for resource encryption. However, if you use KMS v2 _and_ enable the `KMSv2KDF`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/), then
|
||||
Kubernetes instead generates a new DEK **per encryption**: the API server uses a
|
||||
With KMS v2, a new DEK is generated **per encryption**: the API server uses a
|
||||
_key derivation function_ to generate single use data encryption keys from a secret seed
|
||||
combined with some random data.
|
||||
Whichever approach you configure, the DEK or seed is also rotated whenever the KEK is rotated
|
||||
The seed is rotated whenever the KEK is rotated
|
||||
(see `Understanding key_id and Key Rotation` section below for more details).
|
||||
|
||||
The KMS provider uses gRPC to communicate with a specific KMS plugin over a UNIX domain socket.
|
||||
The KMS plugin, which is implemented as a gRPC server and deployed on the same host(s)
|
||||
as the Kubernetes control plane, is responsible for all communication with the remote KMS.
|
||||
|
||||
{{< caution >}}
|
||||
|
||||
If you are running virtual machine (VM) based nodes that leverage VM state store with this feature,
|
||||
using KMS v2 is **insecure** and an information security risk unless you also explicitly enable
|
||||
the `KMSv2KDF`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
|
||||
|
||||
With KMS v2, the API server uses AES-GCM with a 12 byte nonce (8 byte atomic counter and 4 bytes random data) for encryption.
|
||||
The following issues could occur if the VM is saved and restored:
|
||||
|
||||
1. The counter value may be lost or corrupted if the VM is saved in an inconsistent state or restored improperly.
|
||||
This can lead to a situation where the same counter value is used twice, resulting in the same nonce being used
|
||||
for two different messages.
|
||||
2. If the VM is restored to a previous state, the counter value may be set back to its previous value,
|
||||
resulting in the same nonce being used again.
|
||||
|
||||
Although both of these cases are partially mitigated by the 4 byte random nonce, this can compromise
|
||||
the security of the encryption.
|
||||
|
||||
If you have enabled the `KMSv2KDF`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) _and_ are using KMS v2
|
||||
(not KMS v1), the API server generates single use data encryption keys from a secret seed.
|
||||
This eliminates the need for a counter based nonce while avoiding nonce collision concerns.
|
||||
It also removes any specific concerns with using KMS v2 and VM state store.
|
||||
|
||||
{{< /caution >}}
|
||||
|
||||
## Configuring the KMS provider
|
||||
|
||||
To configure a KMS provider on the API server, include a provider of type `kms` in the
|
||||
|
|
@ -197,9 +166,9 @@ Then use the functions and data structures in the stub file to develop the serve
|
|||
|
||||
##### KMS v2 {#developing-a-kms-plugin-gRPC-server-notes-kms-v2}
|
||||
|
||||
* KMS plugin version: `v2beta1`
|
||||
* KMS plugin version: `v2`
|
||||
|
||||
In response to procedure call `Status`, a compatible KMS plugin should return `v2beta1` as `StatusResponse.version`,
|
||||
In response to procedure call `Status`, a compatible KMS plugin should return `v2` as `StatusResponse.version`,
|
||||
"ok" as `StatusResponse.healthz` and a `key_id` (remote KMS KEK ID) as `StatusResponse.key_id`.
|
||||
|
||||
The API server polls the `Status` procedure call approximately every minute when everything is healthy,
|
||||
|
|
@ -258,20 +227,20 @@ Then use the functions and data structures in the stub file to develop the serve
|
|||
API server restart is required to perform KEK rotation.
|
||||
|
||||
{{< caution >}}
|
||||
Because you don't control the number of writes performed with the DEK,
|
||||
Because you don't control the number of writes performed with the DEK,
|
||||
the Kubernetes project recommends rotating the KEK at least every 90 days.
|
||||
{{< /caution >}}
|
||||
|
||||
* protocol: UNIX domain socket (`unix`)
|
||||
|
||||
The plugin is implemented as a gRPC server that listens at UNIX domain socket.
|
||||
The plugin deployment should create a file on the file system to run the gRPC unix domain socket connection.
|
||||
The API server (gRPC client) is configured with the KMS provider (gRPC server) unix
|
||||
domain socket endpoint in order to communicate with it.
|
||||
An abstract Linux socket may be used by starting the endpoint with `/@`, i.e. `unix:///@foo`.
|
||||
Care must be taken when using this type of socket as they do not have concept of ACL
|
||||
(unlike traditional file based sockets).
|
||||
However, they are subject to Linux networking namespace, so will only be accessible to
|
||||
The plugin is implemented as a gRPC server that listens at UNIX domain socket.
|
||||
The plugin deployment should create a file on the file system to run the gRPC unix domain socket connection.
|
||||
The API server (gRPC client) is configured with the KMS provider (gRPC server) unix
|
||||
domain socket endpoint in order to communicate with it.
|
||||
An abstract Linux socket may be used by starting the endpoint with `/@`, i.e. `unix:///@foo`.
|
||||
Care must be taken when using this type of socket as they do not have concept of ACL
|
||||
(unlike traditional file based sockets).
|
||||
However, they are subject to Linux networking namespace, so will only be accessible to
|
||||
containers within the same pod unless host networking is used.
|
||||
|
||||
### Integrating a KMS plugin with the remote KMS
|
||||
|
|
|
|||
Loading…
Reference in New Issue