From 300da63eede387b78336109e56bdcb21ac39cd56 Mon Sep 17 00:00:00 2001 From: joneszc Date: Thu, 24 Oct 2024 13:17:46 -0400 Subject: [PATCH 1/9] add documentation for amazon_web_services.eks_kms_arn config option --- .../advanced-provider-configuration.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 2126e5c5c..0908fefb5 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -98,6 +98,26 @@ amazon_web_services: permissions_boundary: arn:aws:iam::01234567890:policy/ ``` +### EKS KMS ARN (Optional) + +AWS Key Management Service (KMS) keys can provide envelope encryption of Kubernetes secrets stored in +Amazon Elastic Kubernetes Service (EKS). Kubernetes secrets store sensitive information (e.g. passwords, +credentials, TLS keys, etc.). Kubernetes stores all secret object data within etcd and all etcd volumes +used by Amazon EKS are encrypted at the disk-level using AWS-managed encryption keys. The benefit of +specifying a user-managed KMS key for EKS is adding a level of envelope encryption to apply a security +best practice of [defense-in-depth strategy](https://aws.amazon.com/blogs/containers/using-eks-encryption-provider-support-for-defense-in-depth/) by encrypting the Kubernetes secrets store with a KMS key +that the user manages. + +Nebari supports setting an existing KMS key while deploying Nebari to implement encryption of secrets +created in Nebari's EKS cluster. The KMS key must be a `Symmetric` key set to `encrypt and decrypt` data. +Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. + +```yaml +amazon_web_services: + # the arn for the AWS Key Management Service key + eks_kms_arn: 'arn:aws:kms:us-west-2:01234567890:key/' +``` + From c669ff04be5b4fc27d5b451bcf991622479c4a9d Mon Sep 17 00:00:00 2001 From: joneszc Date: Mon, 28 Oct 2024 15:13:59 -0400 Subject: [PATCH 2/9] add warning statement in docs for amazon_web_services.eks_kms_arn config option --- docs/docs/explanations/advanced-provider-configuration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 0908fefb5..6d3db24fe 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -110,6 +110,12 @@ that the user manages. Nebari supports setting an existing KMS key while deploying Nebari to implement encryption of secrets created in Nebari's EKS cluster. The KMS key must be a `Symmetric` key set to `encrypt and decrypt` data. + +Warning: Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an +irreversible action, and if the KMS key used for envelope encrption of secrets is ever deleted, then +there is no way to recover the EKS cluster. +Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. + Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. ```yaml From 2bbe698ea4826607c9d450401d4c81e5c73c3fa6 Mon Sep 17 00:00:00 2001 From: joneszc Date: Mon, 28 Oct 2024 15:18:00 -0400 Subject: [PATCH 3/9] add warning statement in docs for amazon_web_services.eks_kms_arn config option --- docs/docs/explanations/advanced-provider-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 6d3db24fe..80df12b04 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -112,7 +112,7 @@ Nebari supports setting an existing KMS key while deploying Nebari to implement created in Nebari's EKS cluster. The KMS key must be a `Symmetric` key set to `encrypt and decrypt` data. Warning: Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an -irreversible action, and if the KMS key used for envelope encrption of secrets is ever deleted, then +irreversible action, and if the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover the EKS cluster. Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. From 96f1ef1c114eb0ca4a0a7ad4861e59a4dd7e395a Mon Sep 17 00:00:00 2001 From: joneszc Date: Thu, 31 Oct 2024 15:59:16 -0400 Subject: [PATCH 4/9] add note in docs for amazon_web_services.eks_kms_arn config to apply encryption --- docs/docs/explanations/advanced-provider-configuration.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 80df12b04..b07609579 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -114,6 +114,13 @@ created in Nebari's EKS cluster. The KMS key must be a `Symmetric` key set to `e Warning: Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an irreversible action, and if the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover the EKS cluster. +Additionally, if you try to change the KMS key in use for cluster encryption, by setting a different +key ARN and re-deploying Nebari, the re-deploy should succeed but the KMS key used for encryption will +not actually change the cluster config and the original key will remain set. + +Note: After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the +new key by running the following command: +`kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - kms-encryption-timestamp="time value"` Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. From 57abcbb8f8717c0f2e4ad00acacc152acfd974b2 Mon Sep 17 00:00:00 2001 From: joneszc Date: Mon, 4 Nov 2024 10:08:24 -0500 Subject: [PATCH 5/9] add admonitions in docs for amazon_web_services.eks_kms_arn config option --- .../advanced-provider-configuration.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index b07609579..6f52931c1 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -109,16 +109,23 @@ best practice of [defense-in-depth strategy](https://aws.amazon.com/blogs/contai that the user manages. Nebari supports setting an existing KMS key while deploying Nebari to implement encryption of secrets -created in Nebari's EKS cluster. The KMS key must be a `Symmetric` key set to `encrypt and decrypt` data. +created in Nebari's EKS cluster. The KMS key must be a **Symmetric** key set to **encrypt and decrypt** data. -Warning: Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an -irreversible action, and if the KMS key used for envelope encryption of secrets is ever deleted, then -there is no way to recover the EKS cluster. -Additionally, if you try to change the KMS key in use for cluster encryption, by setting a different -key ARN and re-deploying Nebari, the re-deploy should succeed but the KMS key used for encryption will -not actually change the cluster config and the original key will remain set. +:::warning +Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an +_irreversible_ action and re-deploying Nebari to try to remove a previously set `eks_kms_arn` will fail. +On the other hand, if you try to change the KMS key in use for cluster encryption, by re-deploying Nebari +after setting a _different_ key ARN, the re-deploy should succeed but the KMS key used for encryption will +not actually change in the cluster config and the original key will remain set. The integrity of a faulty +deployment can be restored, following a failed re-deploy attempt to remove a previously set KMS key, by +simply re-deploying Nebari while ensuring `eks_kms_arn` is set to the original KMS key ARN. + +:::danger +If the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover +the EKS cluster. -Note: After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the +:::note +After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the new key by running the following command: `kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - kms-encryption-timestamp="time value"` Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. From 55f83940ebb63bc8dc1cbb1b7f5f589f49ce3c63 Mon Sep 17 00:00:00 2001 From: joneszc Date: Mon, 4 Nov 2024 10:11:29 -0500 Subject: [PATCH 6/9] add admonitions in docs for amazon_web_services.eks_kms_arn config option --- docs/docs/explanations/advanced-provider-configuration.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 6f52931c1..e665361eb 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -119,16 +119,19 @@ after setting a _different_ key ARN, the re-deploy should succeed but the KMS ke not actually change in the cluster config and the original key will remain set. The integrity of a faulty deployment can be restored, following a failed re-deploy attempt to remove a previously set KMS key, by simply re-deploying Nebari while ensuring `eks_kms_arn` is set to the original KMS key ARN. +::: :::danger If the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover the EKS cluster. +::: :::note After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the new key by running the following command: `kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - kms-encryption-timestamp="time value"` Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. +::: Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. From 61e400684e75a94ce9a0b27806b21757414fd643 Mon Sep 17 00:00:00 2001 From: joneszc Date: Mon, 4 Nov 2024 10:15:11 -0500 Subject: [PATCH 7/9] add admonitions in docs for amazon_web_services.eks_kms_arn config option --- docs/docs/explanations/advanced-provider-configuration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index e665361eb..81933004c 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -112,6 +112,7 @@ Nebari supports setting an existing KMS key while deploying Nebari to implement created in Nebari's EKS cluster. The KMS key must be a **Symmetric** key set to **encrypt and decrypt** data. :::warning + Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an _irreversible_ action and re-deploying Nebari to try to remove a previously set `eks_kms_arn` will fail. On the other hand, if you try to change the KMS key in use for cluster encryption, by re-deploying Nebari @@ -119,18 +120,23 @@ after setting a _different_ key ARN, the re-deploy should succeed but the KMS ke not actually change in the cluster config and the original key will remain set. The integrity of a faulty deployment can be restored, following a failed re-deploy attempt to remove a previously set KMS key, by simply re-deploying Nebari while ensuring `eks_kms_arn` is set to the original KMS key ARN. + ::: :::danger + If the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover the EKS cluster. + ::: :::note + After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the new key by running the following command: `kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - kms-encryption-timestamp="time value"` Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information. + ::: Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. From f5c04751c03a69f215f8bccf4151a70d9acb87fc Mon Sep 17 00:00:00 2001 From: "Vinicius D. Cerutti" <51954708+viniciusdc@users.noreply.github.com> Date: Fri, 8 Nov 2024 11:24:13 -0300 Subject: [PATCH 8/9] Minor re-wording for better cohesiveness --- .../explanations/advanced-provider-configuration.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index 619c89c4d..d4fbca0b2 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -100,13 +100,10 @@ amazon_web_services: ### EKS KMS ARN (Optional) -AWS Key Management Service (KMS) keys can provide envelope encryption of Kubernetes secrets stored in -Amazon Elastic Kubernetes Service (EKS). Kubernetes secrets store sensitive information (e.g. passwords, -credentials, TLS keys, etc.). Kubernetes stores all secret object data within etcd and all etcd volumes -used by Amazon EKS are encrypted at the disk-level using AWS-managed encryption keys. The benefit of -specifying a user-managed KMS key for EKS is adding a level of envelope encryption to apply a security -best practice of [defense-in-depth strategy](https://aws.amazon.com/blogs/containers/using-eks-encryption-provider-support-for-defense-in-depth/) by encrypting the Kubernetes secrets store with a KMS key -that the user manages. +You can use AWS Key Management Service (KMS) to enhance security by encrypting Kubernetes secrets in +Amazon Elastic Kubernetes Service (EKS). This approach adds an extra layer of protection for sensitive +information, like passwords, credentials, and TLS keys, by applying user-managed encryption keys to Kubernetes +secrets, supporting a [defense-in-depth strategy](https://aws.amazon.com/blogs/containers/using-eks-encryption-provider-support-for-defense-in-depth/). Nebari supports setting an existing KMS key while deploying Nebari to implement encryption of secrets created in Nebari's EKS cluster. The KMS key must be a **Symmetric** key set to **encrypt and decrypt** data. From b4813c45c105566932781d48f15397da04aa2a26 Mon Sep 17 00:00:00 2001 From: Z <87147088+joneszc@users.noreply.github.com> Date: Fri, 8 Nov 2024 11:52:42 -0500 Subject: [PATCH 9/9] reformat to pass prettier --check --- docs/docs/explanations/advanced-provider-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index d4fbca0b2..aad9a8483 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -101,7 +101,7 @@ amazon_web_services: ### EKS KMS ARN (Optional) You can use AWS Key Management Service (KMS) to enhance security by encrypting Kubernetes secrets in -Amazon Elastic Kubernetes Service (EKS). This approach adds an extra layer of protection for sensitive +Amazon Elastic Kubernetes Service (EKS). This approach adds an extra layer of protection for sensitive information, like passwords, credentials, and TLS keys, by applying user-managed encryption keys to Kubernetes secrets, supporting a [defense-in-depth strategy](https://aws.amazon.com/blogs/containers/using-eks-encryption-provider-support-for-defense-in-depth/). @@ -135,7 +135,7 @@ Here is an example of how you would set KMS key ARN in `nebari-config.yaml`. ```yaml amazon_web_services: # the arn for the AWS Key Management Service key - eks_kms_arn: 'arn:aws:kms:us-west-2:01234567890:key/' + eks_kms_arn: "arn:aws:kms:us-west-2:01234567890:key/" ``` ### Launch Templates (Optional)