{"id":13646170,"url":"https://github.com/kubernetes-sigs/aws-encryption-provider","last_synced_at":"2025-08-07T23:56:39.358Z","repository":{"id":30535280,"uuid":"124666563","full_name":"kubernetes-sigs/aws-encryption-provider","owner":"kubernetes-sigs","description":"APIServer encryption provider, backed by AWS KMS","archived":false,"fork":false,"pushed_at":"2025-04-16T16:41:07.000Z","size":8029,"stargazers_count":220,"open_issues_count":3,"forks_count":82,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-17T00:40:26.246Z","etag":null,"topics":["k8s-sig-aws"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubernetes-sigs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_CONTACTS","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-10T15:05:11.000Z","updated_at":"2025-04-16T16:41:12.000Z","dependencies_parsed_at":"2023-01-14T17:10:06.558Z","dependency_job_id":"4977caaf-9b6b-467d-a2d1-c4cd7db08ffb","html_url":"https://github.com/kubernetes-sigs/aws-encryption-provider","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-encryption-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-encryption-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-encryption-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-encryption-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubernetes-sigs","download_url":"https://codeload.github.com/kubernetes-sigs/aws-encryption-provider/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250100634,"owners_count":21374977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["k8s-sig-aws"],"created_at":"2024-08-02T01:02:49.776Z","updated_at":"2025-04-21T17:32:13.382Z","avatar_url":"https://github.com/kubernetes-sigs.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# AWS Encryption Provider\n\n[![GoDoc](https://godoc.org/sigs.k8s.io/aws-encryption-provider?status.svg)](https://godoc.org/sigs.k8s.io/aws-encryption-provider)\n[![sig-aws-encryption-provider/verify](https://testgrid.k8s.io/q/summary/sig-aws-encryption-provider/verify/tests_status?style=svg)](https://testgrid.k8s.io/sig-aws-encryption-provider#verify)\n[![sig-aws-encryption-provider/unit-test](https://testgrid.k8s.io/q/summary/sig-aws-encryption-provider/unit-test/tests_status?style=svg)](https://testgrid.k8s.io/sig-aws-encryption-provider#unit-test)\n\nThis repository is an implementation of the kube-apiserver [encryption provider](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/), backed by AWS KMS.\n\n## Use with Kubernetes\n\n### Assumptions\n\nThe following guide makes several assumptions:\n\n* You have an AWS account and permission to manage KMS keys\n* You have management access to a Kubernetes API server\n* You have already read the Kubernetes documentation page [Encrypting Secret Data at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)\n* You have already read the Kubernetes documentation page [Using a KMS provider for data encryption](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/)\n* The AWS KMS encryption provider will need AWS credentials configured in order to call KMS APIs. You can read more about providing credentials by reading the [AWS SDK documentation](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials) on configuring your application.\n\n### Setup\n\nFirst you'll need to create a KMS master key. For more details you can read the [KMS documentation on creating a key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). Check the [KMS pricing page](https://aws.amazon.com/kms/pricing/) for up-to-date pricing information.\n\n```bash\nKEY_ID=$(aws kms create-key --query KeyMetadata.KeyId --output text)\naws kms describe-key --key-id $KEY_ID\n{\n    \"KeyMetadata\": {\n        \"Origin\": \"AWS_KMS\",\n        \"KeyId\": \"1234abcd-12ab-34cd-56ef-1234567890ab\",\n        \"Description\": \"\",\n        \"KeyManager\": \"CUSTOMER\",\n        \"Enabled\": true,\n        \"KeyUsage\": \"ENCRYPT_DECRYPT\",\n        \"KeyState\": \"Enabled\",\n        \"CreationDate\": 1502910355.475,\n        \"Arn\": \"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\",\n        \"AWSAccountId\": \"111122223333\"\n    }\n}\n```\n\nKey aliases can be used but it is not recommended. An alias can be updated to a new key, which would break how this encryption provider works. As a result all secrets encrypted before the alias update will become unreadable.\n\n### Deploy the aws-encryption-provider plugin\n\nWhile there are numerous ways you could deploy the aws-encryption-provider\nplugin, the simplest way for most installations would be a static pod on the\nsame node as each Kubernetes API server. Below is an example pod spec, and you\nwill need to replace the image, key ARN, and region to fit your requirements.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: aws-encryption-provider\n  namespace: kube-system\nspec:\n  containers:\n  - image: 111122223333.dkr.ecr.us-west-2.amazonaws.com/aws-encryption-provider:v0.0.1\n    name: aws-encryption-provider\n    command:\n    - /aws-encryption-provider\n    - --key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\n    - --region=us-west-2\n    - --listen=/var/run/kmsplugin/socket.sock\n    ports:\n    - containerPort: 8080\n      protocol: TCP\n    livenessProbe:\n      httpGet:\n        path: /healthz\n        port: 8080\n    volumeMounts:\n    - mountPath: /var/run/kmsplugin\n      name: var-run-kmsplugin\n  volumes:\n  - name: var-run-kmsplugin\n    hostPath:\n      path: /var/run/kmsplugin\n      type: DirectoryOrCreate\n```\n\nOnce you have deployed the encryption provider on all the same nodes as your API\nservers, you will need to update the kube-apiserver to use the encryption\nprovider by setting the `--encryption-provider-config` flag and with the path to\nyour encryption configuration file. Below is an example:\n\n```yaml\napiVersion: apiserver.config.k8s.io/v1\nkind: EncryptionConfiguration\nresources:\n  - resources:\n    - secrets\n    providers:\n    - kms:\n        name: aws-encryption-provider\n        endpoint: unix:///var/run/kmsplugin/socket.sock\n        cachesize: 1000\n        timeout: 3s\n    - identity: {}\n```\n\nDon't forget, you'll need to mount the directory containing the unix socket that\nthe KMS server is listening on into the kube-apiserver.\n\n### Bootstrap during cluster creation (kops)\nTo use encryption provider during cluster creation, you need to ensure that its running\nbefore starting kube-apiserver. For that you need to perform the following high level steps.\n\nNote: These steps have been verified with [kops](https://github.com/kubernetes/kops) but\nit should be similar to any other cluster bootstrapping tool.\n\nFor exact kops instructions see `KOPS.md`.\n\n#### Run aws-encryption-provider as static pod\nYou need to have encryption provider running before kube-apiserver, and to do that you can\nuse [static pods](https://kubernetes.io/docs/tasks/administer-cluster/static-pod/) functionality. For kops, static pod manifests are available at `/etc/kubernetes/manifests`. You can further use kops file assets functionality to drop\nthe pod spec file in that directory.\n\n#### Use Host Network for aws-encryption-provider\nAs the CNI plugin is not yet available, you need to add `hostNetwork: true` to pod spec.\n\n#### Update health port for aws-encryption-provider\nWhen using hostNetwork, the port `8080` used by aws-encryption-provider conflicts with\nkube-apiserver which also requires the same port. To fix this, add `-health-port=:8083`\nto args section of pod spec above. Also change the port in `containerPort` and `livenessProbe`\nsections.\n\n#### Add /var/run/kmsplugin hostMount to api server spec\nUse kops lifecycle hook to run a script/container that can update the kube-apiserver\nmanifest (available at /etc/kubernetes/manifests) to add `/var/run/kmsplugin` as hostMount.\n\n#### Permissions\nEnsure master IAM role has permissions to encrypt/decrypt using the kms. You can achieve this\nusing additionalIAMPolicies functionality of kops.\n\nAfter above changes, the modified pod-spec would look like:\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: aws-encryption-provider\n  namespace: kube-system\nspec:\n  containers:\n  - image: 111122223333.dkr.ecr.us-west-2.amazonaws.com/aws-encryption-provider:v0.0.1\n    name: aws-encryption-provider\n    command:\n    - /aws-encryption-provider\n    - --key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\n    - --region=us-west-2\n    - --listen=/var/run/kmsplugin/socket.sock\n    - --health-port=:8083\n    ports:\n    - containerPort: 8083\n      protocol: TCP\n    livenessProbe:\n      httpGet:\n        path: /healthz\n        port: 8083\n    volumeMounts:\n    - mountPath: /var/run/kmsplugin\n      name: var-run-kmsplugin\n  hostNetwork: true\n  volumes:\n  - name: var-run-kmsplugin\n    hostPath:\n      path: /var/run/kmsplugin\n      type: DirectoryOrCreate\n```\n\n### Check that the provider plugin is working\n- First we create a secret: `kubectl create secret generic secret1 -n default --from-literal=mykey=mydata`\n- Then we exec into the etcd-server: `kubectl exec -it -n kube-system $(kubectl get pods -n kube-system | grep etcd-manager-main | awk '{print $1}') bash`\n- `cd /opt/etcd-v3.3.10-linux-amd64/`\n- Then check the contents of our secret in etcd store by running the following:\n```\nETCDCTL_API=3 etcdctl \\\n    --key /rootfs/etc/kubernetes/pki/kube-apiserver/etcd-client.key \\\n    --cert  /rootfs/etc/kubernetes/pki/kube-apiserver/etcd-client.crt \\\n    --cacert /rootfs/etc/kubernetes/pki/kube-apiserver/etcd-ca.crt  \\\n    --endpoints \"https://etcd-a.internal.${CLUSTER}:4001\" get /registry/secrets/default/secret1\n```\n\u0026nbsp;\u0026nbsp;\u0026nbsp;-- output should be something like:\n```\n0m`�He.0�cryption-provider:�1x��%�B���#JP��J���*ȝ���΂@\\n�96�^��ۦ�~0| *�H��\n                    `q�*�J�.P��;\u0026~��o#�O�8m��-\u003e8L��0�C3���A7�����~���f�V�ܬ���X��_��`�H#�D��z)+�81��qW��y��`�q��}1\u003cLF, ��N��p����i*�aC#E�߸�s������s��l�?�a\n�AźR������.��8H�4�O\n```\n\n### Rotation\n\nIf you have configured your KMS master key (CMK) to have rotation enabled, AWS will\nupdate the CMK's backing encryption key every year. (You can read more about\nautomatic key rotation at [the KMS documentation\npage](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html))\nIf you are using the aws-encryption-provider with an existing master key, but\nwant to update your cluster to use a new KMS master key, you can by roughly\nfollowing the below procedure. Be sure to read the Kubernetes documentation on\n[rotating a decryption key](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#rotating-a-decryption-key),\nas all of those steps apply to this process.\n\n#### Option 1 - Use single encryption provider\n\nUpdate the encryption provider for each API server to set additional `key`, `listen`,\nand optionally `encryption-context` fields. The number of `key` and `listen` fields\nadded must be equivalent. These fields will be associated with each other based on\nthe order they were added. For example, the first `key`, `listen`, and\n`encryption-context` fields will all be associated with each other, while the next\noccurance of each of them will be associated together.\n\nNote: `key` and `listen` fields support a comma-separated list of values as an alternative\nto using multiple `key` and `listen` fields for each value. However, `encryption-context`\ndoes not support a comma-separated list to distinguish between multiple keys and must use\na separate field for each.\n\nBelow is an example of the updated `command` field in the encryption provider pod spec.\n\n```yaml\n    command:\n    - /aws-encryption-provider\n    - --key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\n    - --listen=/var/run/kmsplugin/socket.sock\n    - --encryption-context=context=mycontextforkey1\n    - --key=arn:aws:kms:us-west-2:111122223333:key/4321abcd-12ab-34cd-56ef-1234567890ba\n    - --listen=/var/run/kmsplugin/socket2.sock\n    - --encryption-context=context=mycontextforkey2\n    - --region=us-west-2\n    - --health-port=:8083\n```\n\nBelow is an axample encryption configuration file using the new key.\n\n```yaml\napiVersion: apiserver.config.k8s.io/v1\nkind: EncryptionConfiguration\nresources:\n  - resources:\n    - secrets\n    providers:\n    # using old key\n    - kms:\n        name: aws-encryption-provider\n        endpoint: unix:///var/run/kmsplugin/socket.sock\n        cachesize: 1000\n        timeout: 3s\n    # using new key\n    - kms:\n        apiVersion: v2\n        name: aws-encryption-provider-2\n        endpoint: unix:///var/run/kmsplugin/socket2.sock\n    - identity: {}\n```\n\n\n#### Option 2 - Use two encryption providers\n\nYou will need to run two encryption providers on each API server using different\nkeys, and you must configure them to each use a different value for the `name`\nfield and each provider must listen on a different unix socket. Below is an\nexample encryption configuration file for all API servers prior to using the new\nkey.\n\n```yaml\napiVersion: apiserver.config.k8s.io/v1\nkind: EncryptionConfiguration\nresources:\n  - resources:\n    - secrets\n    providers:\n    # provider using old key\n    - kms:\n        name: aws-encryption-provider\n        endpoint: unix:///var/run/kmsplugin/socket.sock\n        cachesize: 1000\n        timeout: 3s\n    # provider using new Key\n    - kms:\n        name: aws-encryption-provider-2\n        endpoint: unix:///var/run/kmsplugin/socket2.sock\n        cachesize: 1000\n        timeout: 3s\n    - identity: {}\n```\n\nAfter all API servers have been restarted and are able to decrypt using the\nnew key, you can switch the order of the providers with the new key at the\nbeginning of the list and the old key below it. After all secrets have been\nre-encrypted with the new key, you can remove the encryption provider using the\nold key from the list.\n\n## Community, discussion, contribution, and support\n\nLearn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).\n\nYou can reach the maintainers of this project at:\n\n- [Slack](http://slack.k8s.io/)\n- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-aws)\n\n### Code of conduct\n\nParticipation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes-sigs%2Faws-encryption-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubernetes-sigs%2Faws-encryption-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes-sigs%2Faws-encryption-provider/lists"}