{"id":17881942,"url":"https://github.com/ayoul3/asm-webhook","last_synced_at":"2026-04-12T17:51:26.559Z","repository":{"id":144356631,"uuid":"336763464","full_name":"ayoul3/asm-webhook","owner":"ayoul3","description":"Kubernetes mutating webhook for fetching secrets from SecretsManager at runtime","archived":false,"fork":false,"pushed_at":"2021-03-07T21:36:58.000Z","size":7943,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-08T16:14:44.126Z","etag":null,"topics":["aws","container","docker","eks","kubernetes","secretsmanager"],"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/ayoul3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-07T10:54:26.000Z","updated_at":"2024-07-16T13:15:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"f1b03a67-d453-4aac-9b7e-c643e7e05de9","html_url":"https://github.com/ayoul3/asm-webhook","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoul3%2Fasm-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoul3%2Fasm-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoul3%2Fasm-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoul3%2Fasm-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayoul3","download_url":"https://codeload.github.com/ayoul3/asm-webhook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246922248,"owners_count":20855345,"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":["aws","container","docker","eks","kubernetes","secretsmanager"],"created_at":"2024-10-28T12:46:17.108Z","updated_at":"2026-04-12T17:51:21.512Z","avatar_url":"https://github.com/ayoul3.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ASM Webhook\n\n\u003cp align=\"center\"\u003e\n\n  \u003ca target=\"_blank\" href=\"https://github.com/ayoul3/asm-webhook/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/ayoul3/asm-webhook\" alt=\"Build release\"\u003e\n  \u003c/a\u003e\n\n  \u003ca target=\"_blank\" href=\"https://hub.docker.com/repository/docker/ayoul3/asm-webhook\"\u003e\n    \u003cimg src=\"https://img.shields.io/docker/automated/ayoul3/asm-webhook\" alt=\"GoDoc\"\u003e\n  \u003c/a\u003e\n\n\u003c/p\u003e\n\nasm-webhook is a mutating Webhook designed to dynamically fetch secrets from SecretsManager and inject them as env variables in pods.\n\nIt is heavily inspired by the great [Banzai Vaults](https://github.com/banzaicloud/bank-vaults/tree/master/charts/vault-secrets-webhook) that supports Vault.\n\n## How does it work?\n1. Interception\n\nA mutating webhook will intercept all pod submissions bearing the annotation `asm-webhook:\"true\"`.\n\n2. Validation\n\nIt will go through all its environment variables and secrets looking for SecretsManager ARNs. If found, the Pod will be mutated.\n\n3. Mutation\n\nAn init container `ayoul3/asm-env` is injected which copies its main binary `asm-env` to a volume `/asm` shared with the other containers in the pod.\n\n4. Execution\n\nThe command of the container is overwritten so that it first starts a binary `asm-env` that will decrypt SecretsManager secrets. After which it will start the original command with its arguments.\n\n\n```yaml\nCommand: sh\nArgs:\n - -c\n - trap 'exit' TERM; while :; do sleep 1; echo decrypted $KEY_ID; done\n```\nbecomes:\n```yaml\nCommand: /asm/asm-env\nArgs:\n - sh\n - -c\n - trap 'exit' TERM; while :; do sleep 1; echo decrypted $KEY_ID; done\n```\n\n## Install\nMost default values work just fine if you want to test on minikube.\nOn an EKS cluster change at least the roleArn in `./chart/values.yaml` to point to an IAM role **capable of pulling ECR images**:\n```yaml\nserviceAccountName: webhook\nroleArn: \"arn:aws:iam::1111111111111:role/webhook\"\n```\n\nOnce you're done, execute the `generate.sh` script to provision certificates used by the webhook:\n\n```bash\n./generate.sh\n```\nThis command will prepare certificates and store them a `secret` resource in Kube that will be mounted and used by the Webhook.\n\nIf everything goes alright, you can then deploy the chart using helm:\n```bash\nhelm upgrade --install asm-webhook ./chart\n```\n\nCheck that the webhook is running:\n```bash\n$ kubectl get mutatingwebhookconfigurations\n\nNAME                      WEBHOOKS   AGE\nasm-webhook.default.svc   1          17s\n\n$ k get deployments\n\nNAME          READY   UP-TO-DATE   AVAILABLE   AGE\nasm-webhook   1/1     1            1           17s\n...snip...\n```\n\nTry deploying [pod.yaml](./sample/pod.yaml) file to test your webhook. Make sure to put in a proper secret ARN.\n\n## Test\nTo test that your installation succeeded, try submitting the sample pod in the sample folder.\n**First change the serviceaccount and the secret's ID to match your setup.**\n```bash\n$ kubectl deploy -f sample/pod.yaml -n default\npod \"asm-sample-pod\" created\n\n$ kubectl logs asm-sample-pod\n\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Preparing env variables\"\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Decrypting key ID arn:aws:secretsmanager:eu-west-1:111111111111:secret:/key1-mIdVIP#password\"\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Setting secret value in env var KEY_ID\"\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Looking for nested key password in secret arn:aws:secretsmanager:eu-west-1:111111111111:secret:/key1-mIdVIP#password\"\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Found nested key password in secret arn:aws:secretsmanager:eu-west-1:111111111111:secret:/key1-mIdVIP#password\"\ntime=\"2021-02-14T13:39:45Z\" level=debug msg=\"Found absolute path /bin/sh\"\ndecrypted value password\n```\n\n## Usage\n\nAdd the following label to the pods or deployments you wish to send to the webhook:\n```yaml\nmetadata:\n  labels:\n    asm-webhook: \"true\"\n  ...\n  env:\n    - name: KEY_ID\n      value: arn:aws:secretsmanager:us-east-1:111111111111:secret:key-us-cmo1Hc\n```\nIt's the service account of the pod that will fetch the secret so make sure to give it proper access rights.\nCheck the [pod.yaml](./sample/pod.yaml) file for a full example\n\n## Prerequisites\n\nIt is the pod that fetches its own secrets, so obviously it needs to use a service account mapped to an IAM role capable of reading such secrets. You can read more about it [here](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html) and find an actual example [here](https://aws.amazon.com/blogs/containers/aws-secrets-controller-poc/).\n\nThe webhook needs a service account capable of getting container manifest from the registry hosting the container image.  This capability is only used when the submitted container lacks the `command` argument.\n\nIf you are using ECR, grant read-only access to the role mapped to the service account `webhook`.\nThe default `AmazonEC2ContainerRegistryReadOnly` works just fine.\n\nYou can put any value if you only use public images, or you always specify the command argument for your containers.\n\n\n## Secret formats\nSecrets stored in SecretsManager can be of two formats:\n* Simple strings\n* Flat JSON\nYou can specify which JSON key to fetch by adding it after the character **#**.\n\nIf the secret `arn:aws:secretsmanager:us-east-1:111111111111:secret:key-us-cmo1Hc` contains  `{\"user\":\"test\", \"password\": \"secret\"}` then you can choose to only fetch the password key as such:\n```yaml\nDB_PASS: arn:aws:secretsmanager:us-east-1:886477354405:secret:key-us-cmo1Hc#password\n```\n*Nested keys are not supported at the moment.*\n\n## Annotations\n\nThe webhook supports the following annotations at the pod level:\n| Tables                              | Decription    | Value    |\n| ----------------------------------- |:-------------:| :----------:|\n| asm.webhook.debug                   | Activate debug logs for the webhook handler of this pod | false/true\n| asm.webhook.asm-env.image           | image of the init container to inject      | `ayoul3/asm-env:latest`\n| asm.webhook.asm-env.path            | path to binary inside the init container that will fetch secrets     | /app/\n| asm.webhook.asm-env.bin             | name of the binary that will fetch secrets       | asm-env\n| asm.webhook.asm-env.mountPath       | mount path where containers will find this binary      | /asm/\n| asm.webhook.asm-env.skip-cert-check | skip certificate check when contacting SecretsManager. Useful for bare pods without `ca-certificates` package      | false\n\n## asm-env\n\nasm-env binary is maintained as a [separate project](https://github.com/ayoul3/asm-env).\n\n## Monitoring\n\nThe webhook exposes Prometheus metrics on `/metrics`. A [grafana dashboard](https://grafana.com/grafana/dashboards/13685) is also available courtesy of Xabier Larrakoetxea.\n\n\n## Credit\n[Banzai Vaults](https://github.com/banzaicloud/bank-vaults/tree/master/charts/vault-secrets-webhook)\n[Kubewebhook](https://github.com/slok/kubewebhook)\n\n## Author\nAyoub Elaassal","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoul3%2Fasm-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayoul3%2Fasm-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoul3%2Fasm-webhook/lists"}