Change:
kind: EncryptionConfiguration resources: - resources: <del> - secrets </del> <ins> - secrets </ins> providers: <del> - aescbc: keys: - name: key1 secret: <BASE 64 ENCODED SECRET> - identity: {} </del> <ins> - aescbc: keys: - name: key1 secret: <BASE 64 ENCODED SECRET> - identity: {} </ins> ``` <del> To create a new secret perform the following steps: </del> <ins> To create a new Secret, perform the following steps: </ins> <del> 1. Generate a 32 byte random key and base64 encode it. If you're on Linux or macOS, run the following command: </del> <ins> 1. Generate a 32-byte random key and base64 encode it. If you're on Linux or macOS, run the following command: </ins> ```shell head -c 32 /dev/urandom | base64 ``` <del> 2. Place that value in the secret field. 3. Set the `--encryption-provider-config` flag on the `kube-apiserver` to point to the location of the config file. 4. Restart your API server. </del> <ins> 1. Place that value in the `secret` field of the `EncryptionConfiguration` struct. 1. Set the `--encryption-provider-config` flag on the `kube-apiserver` to point to the location of the config file. 1. Restart your API server. </ins> {{< caution >}} <del> Your config file contains keys that can decrypt content in etcd, so you must properly restrict permissions on your masters so only the user who runs the kube-apiserver can read it. </del> <ins> Your config file contains keys that can decrypt the contents in etcd, so you must properly restrict permissions on your control-plane nodes so only the user who runs the `kube-apiserver` can read it. </ins> {{< /caution >}} ## Verifying that data is encrypted Data is encrypted when written to etcd. After restarting your `kube-apiserver`, any newly created or <del> updated secret should be encrypted when stored. To check, you can use the `etcdctl` command line program to retrieve the contents of your secret. </del> <ins> updated Secret should be encrypted when stored. To check this, you can use the `etcdctl` command line program to retrieve the contents of your Secret. </ins> <del> 1. Create a new secret called `secret1` in the `default` namespace: </del> <ins> 1. Create a new Secret called `secret1` in the `default` namespace: </ins> ```shell kubectl create secret generic secret1 -n default --from-literal=mykey=mydata ``` <del> 2. Using the etcdctl commandline, read that secret out of etcd: </del> <ins> 1. Using the `etcdctl` command line, read that Secret out of etcd: </ins> `ETCDCTL_API=3 etcdctl get /registry/secrets/default/secret1 [...] | hexdump -C` where `[...]` must be the additional arguments for connecting to the etcd server. <del> 3. Verify the stored secret is prefixed with `k8s:enc:aescbc:v1:` which indicates the `aescbc` provider has encrypted the resulting data. </del> <ins> 1. Verify the stored Secret is prefixed with `k8s:enc:aescbc:v1:` which indicates the `aescbc` provider has encrypted the resulting data. </ins> <del> 4. Verify the secret is correctly decrypted when retrieved via the API: </del> <ins> 1. Verify the Secret is correctly decrypted when retrieved via the API: </ins> ```shell kubectl describe secret secret1 -n default ``` <del> should match `mykey: bXlkYXRh`, mydata is encoded, check [decoding a secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret) to completely decode the secret. </del> <ins> The output should contain `mykey: bXlkYXRh`, with contents of `mydata` encoded, check [decoding a Secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret) to completely decode the Secret. </ins> <del> ## Ensure all secrets are encrypted </del> <ins> ## Ensure all Secrets are encrypted </ins> <del> Since secrets are encrypted on write, performing an update on a secret will encrypt that content. </del> <ins> Since Secrets are encrypted on write, performing an update on a Secret will encrypt that content. </ins> ```shell kubectl get secrets --all-namespaces -o json | kubectl replace -f - ``` <del> The command above reads all secrets and then updates them to apply server side encryption. </del> <ins> The command above reads all Secrets and then updates them to apply server side encryption. </ins> {{< note >}} 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. {{< /note >}} ## Rotating a decryption key <del> Changing the secret without incurring downtime requires a multi step operation, especially in the presence of a highly available deployment where multiple `kube-apiserver` processes are running. </del> <ins> Changing a Secret without incurring downtime requires a multi-step operation, especially in the presence of a highly-available deployment where multiple `kube-apiserver` processes are running. </ins> 1. Generate a new key and add it as the second key entry for the current provider on all servers <del> 2. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key 3. Make the new key the first entry in the `keys` array so that it is used for encryption in the config 4. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key 5. Run `kubectl get secrets --all-namespaces -o json | kubectl replace -f -` to encrypt all existing secrets with the new key 6. Remove the old decryption key from the config after you back up etcd with the new key in use and update all secrets With a single `kube-apiserver`, step 2 may be skipped. </del> <ins> 1. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key 1. Make the new key the first entry in the `keys` array so that it is used for encryption in the config 1. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key 1. Run `kubectl get secrets --all-namespaces -o json | kubectl replace -f -` to encrypt all existing Secrets with the new key 1. Remove the old decryption key from the config after you have backed up etcd with the new key in use and updated all Secrets When running a single `kube-apiserver` instance, step 2 may be skipped. </ins> ## Decrypting all data <del> To disable encryption at rest place the `identity` provider as the first entry in the config: </del> <ins> To disable encryption at rest, place the `identity` provider as the first entry in the config and restart all `kube-apiserver` processes. </ins> ```yaml apiVersion: apiserver.config.k8s.io/v1 kind: EncryptionConfiguration resources: - resources: <del> - secrets </del> <ins> - secrets </ins> providers: <del> - identity: {} - aescbc: keys: - name: key1 secret: <BASE 64 ENCODED SECRET> </del> <ins> - identity: {} - aescbc: keys: - name: key1 secret: <BASE 64 ENCODED SECRET> </ins> ``` <del> and restart all `kube-apiserver` processes. Then run: </del> <ins> Then run the following command to force decrypt all Secrets: </ins> ```shell kubectl get secrets --all-namespaces -o json | kubectl replace -f - ``` <del> to force all secrets to be decrypted. </del> <ins> ## {{% heading "whatsnext" %}} * Learn more about the [EncryptionConfiguration configuration API (v1)](/docs/reference/config-api/apiserver-encryption.v1/). </ins>

Discussion:
This is a Feature Request <!-- Please only use this template for submitting feature/enhancement requests --<!-- See for guidance on writing an actionable issue description. --What would you like to be Within add a new generated page that documents the format for an encryption configuration. Update to hyperlink to that new reference Why is this needed Within , there is a configuration format for the API server, EncryptionConfiguration. At the moment that format is not documented in Readers may want to look up what that format covers. Comments /sig api-machinery /sig auth /kind feature /language en
/triage accepted
/assign This file is already generated in the generator. All we need to do is to copy it to the website repo.