{"id":13612425,"url":"https://github.com/aws/amazon-eks-pod-identity-webhook","last_synced_at":"2026-04-01T20:18:21.039Z","repository":{"id":36645923,"uuid":"191973776","full_name":"aws/amazon-eks-pod-identity-webhook","owner":"aws","description":"Amazon EKS Pod Identity Webhook","archived":false,"fork":false,"pushed_at":"2025-05-01T17:28:36.000Z","size":16251,"stargazers_count":640,"open_issues_count":97,"forks_count":178,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-05-08T00:07:54.434Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/aws.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-14T16:19:25.000Z","updated_at":"2025-04-28T23:19:56.000Z","dependencies_parsed_at":"2024-01-14T09:58:17.065Z","dependency_job_id":"b086cb76-ccdb-4e93-9c50-bd359745f2aa","html_url":"https://github.com/aws/amazon-eks-pod-identity-webhook","commit_stats":{"total_commits":142,"total_committers":55,"mean_commits":2.581818181818182,"dds":0.9225352112676056,"last_synced_commit":"ac3554488585c1a35bea552f771ef3bd4e6e0ddd"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-eks-pod-identity-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-eks-pod-identity-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-eks-pod-identity-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-eks-pod-identity-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/amazon-eks-pod-identity-webhook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149958,"owners_count":22022851,"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":[],"created_at":"2024-08-01T20:00:29.657Z","updated_at":"2026-04-01T20:18:21.031Z","avatar_url":"https://github.com/aws.png","language":"Go","funding_links":[],"categories":["HarmonyOS","Go"],"sub_categories":["Windows Manager"],"readme":"![build](https://github.com/aws/amazon-eks-pod-identity-webhook/workflows/build/badge.svg)\n\n# Amazon EKS Pod Identity Webhook\n\nThis webhook is for mutating pods that will require AWS IAM access.\n\n## Note\nAfter version v0.3.0, `--in-cluster=true` no longer works and is deprecated.  Please use `--in-cluster=false`\nand manage the cluster certificate with cert-manager or some other external certificate provisioning system.\nThis is because certificates using the `legacy-unknown` signer are no longer signed when using the v1\ncertificates API.\n\n## EKS Walkthrough\n\n1. [Create an OIDC provider][1] in IAM for your cluster. You can find the OIDC\n   discovery endpoint by describing your EKS cluster.\n    ```bash\n    aws eks describe-cluster --name $CLUSTER_NAME --query cluster.identity.oidc\n    ```\n    And enter \"sts.amazonaws.com\" as the client-id\n2. Create an IAM role for your pods and [modify the trust policy][2] to allow\n   your pod's service account to use the role:\n    ```json\n    {\n     \"Version\": \"2012-10-17\",\n     \"Statement\": [\n      {\n       \"Effect\": \"Allow\",\n       \"Principal\": {\n        \"Federated\": \"arn:aws:iam::111122223333:oidc-provider/oidc.REGION.eks.amazonaws.com/CLUSTER_ID\"\n       },\n       \"Action\": \"sts:AssumeRoleWithWebIdentity\",\n       \"Condition\": {\n        \"__doc_comment\": \"scope the role to the service account (optional)\",\n        \"StringEquals\": {\n         \"oidc.REGION.eks.amazonaws.com/CLUSTER_ID:sub\": \"system:serviceaccount:default:my-serviceaccount\"\n        },\n        \"__doc_comment\": \"scope the role to a namespace (optional)\",\n        \"StringLike\": {\n         \"oidc.REGION.eks.amazonaws.com/CLUSTER_ID:sub\": \"system:serviceaccount:default:*\"\n        }\n       }\n      }\n     ]\n    }\n    ```\n3. Modify your pod's service account to be annotated with the ARN of the role\n   you want the pod to use\n    ```yaml\n    apiVersion: v1\n    kind: ServiceAccount\n    metadata:\n      name: my-serviceaccount\n      namespace: default\n      annotations:\n        eks.amazonaws.com/role-arn: \"arn:aws:iam::111122223333:role/s3-reader\"\n        # optional: Defaults to \"sts.amazonaws.com\" if not set\n        eks.amazonaws.com/audience: \"sts.amazonaws.com\"\n        # optional: When set to \"true\", adds AWS_STS_REGIONAL_ENDPOINTS env var\n        #   to containers\n        eks.amazonaws.com/sts-regional-endpoints: \"true\"\n        # optional: Defaults to 86400 for expirationSeconds if not set\n        #   Note: This value can be overwritten if specified in the pod \n        #         annotation as shown in the next step.\n        eks.amazonaws.com/token-expiration: \"86400\"\n    ```\n4. All new pods launched using this Service Account will be modified to use\n   IAM for pods. Below is an example pod spec with the environment variables and\n   volume fields added by the webhook.\n    ```yaml\n    apiVersion: v1\n    kind: Pod\n    metadata:\n      name: my-pod\n      namespace: default\n      annotations:\n        # optional: A comma-separated list of initContainers and container names\n        #   to skip adding volumes and environment variables\n        eks.amazonaws.com/skip-containers: \"init-first,sidecar\"\n        # optional: Defaults to 86400, or value specified in ServiceAccount\n        #   annotation as shown in previous step, for expirationSeconds if not set\n        eks.amazonaws.com/token-expiration: \"86400\"\n    spec:\n      serviceAccountName: my-serviceaccount\n      initContainers:\n      - name: init-first\n        image: container-image:version\n      containers:\n      - name: sidecar\n        image: container-image:version\n      - name: container-name\n        image: container-image:version\n    ### Everything below is added by the webhook ###\n        env:\n        - name: AWS_DEFAULT_REGION\n          value: us-west-2\n        - name: AWS_REGION\n          value: us-west-2\n        - name: AWS_ROLE_ARN\n          value: \"arn:aws:iam::111122223333:role/s3-reader\"\n        - name: AWS_WEB_IDENTITY_TOKEN_FILE\n          value: \"/var/run/secrets/eks.amazonaws.com/serviceaccount/token\"\n        - name: AWS_STS_REGIONAL_ENDPOINTS\n          value: \"regional\"\n        volumeMounts:\n        - mountPath: \"/var/run/secrets/eks.amazonaws.com/serviceaccount/\"\n          name: aws-token\n      volumes:\n      - name: aws-token\n        projected:\n          sources:\n          - serviceAccountToken:\n              audience: \"sts.amazonaws.com\"\n              expirationSeconds: 86400\n              path: token\n    ```\n\n### Usage with Windows container workloads\n\nTo ensure workloads are scheduled on windows nodes have the right environment variables, they must have a `nodeSelector` targeting windows it must run on.  Workloads targeting windows nodes using `nodeAffinity` are currently not supported.\n```yaml\n  nodeSelector:\n    beta.kubernetes.io/os: windows\n```\n\nOr for Kubernetes 1.14+\n\n```yaml\n  nodeSelector:\n    kubernetes.io/os: windows\n```\n\n\n\n[1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html\n[2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html\n\n### Usage with non-root container user\n\nWhen running a container with a non-root user, you need to give the container access to the token file by setting the `fsGroup` field in the `securityContext` object.\n\n## Usage\n\n```\nUsage of amazon-eks-pod-identity-webhook:\n      --add_dir_header                       If true, adds the file directory to the header\n      --alsologtostderr                      log to standard error as well as files\n      --annotation-prefix string             The Service Account annotation to look for (default \"eks.amazonaws.com\")\n      --aws-default-region string            If set, AWS_DEFAULT_REGION and AWS_REGION will be set to this value in mutated containers\n      --enable-debugging-handlers            Enable debugging handlers. Currently /debug/alpha/cache is supported\n      --in-cluster                           Use in-cluster authentication and certificate request API (default true)\n      --kube-api string                      (out-of-cluster) The url to the API server\n      --kubeconfig string                    (out-of-cluster) Absolute path to the API server kubeconfig file\n      --log_backtrace_at traceLocation       when logging hits line file:N, emit a stack trace (default :0)\n      --log_dir string                       If non-empty, write log files in this directory\n      --log_file string                      If non-empty, use this log file\n      --log_file_max_size uint               Defines the maximum size a log file can grow to. Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)\n      --logtostderr                          log to standard error instead of files (default true)\n      --metrics-port int                     Port to listen on for metrics (http) (default 9999)\n      --namespace string                     (in-cluster) The namespace name this webhook, the TLS secret, and configmap resides in (default \"eks\")\n      --port int                             Port to listen on (default 443)\n      --service-name string                  (in-cluster) The service name fronting this webhook (default \"pod-identity-webhook\")\n      --service-account-lookup-grace-period  The grace period for service account to be available in cache before not mutating a pod. Set to 0 to deactivate waiting. Carefully use higher values as it may have significant impact on Kubernetes' pod scheduling performance. (default 100ms)\n      --skip_headers                         If true, avoid header prefixes in the log messages\n      --skip_log_headers                     If true, avoid headers when opening log files\n      --stderrthreshold severity             logs at or above this threshold go to stderr (default 2)\n      --sts-regional-endpoint false          Whether to inject the AWS_STS_REGIONAL_ENDPOINTS=regional env var in mutated pods. Defaults to false.\n      --tls-cert string                      (out-of-cluster) TLS certificate file path (default \"/etc/webhook/certs/tls.crt\")\n      --tls-key string                       (out-of-cluster) TLS key file path (default \"/etc/webhook/certs/tls.key\")\n      --tls-secret string                    (in-cluster) The secret name for storing the TLS serving cert (default \"pod-identity-webhook\")\n      --token-audience string                The default audience for tokens. Can be overridden by annotation (default \"sts.amazonaws.com\")\n      --token-expiration int                 The token expiration (default 86400)\n      --token-mount-path string              The path to mount tokens (default \"/var/run/secrets/eks.amazonaws.com/serviceaccount\")\n  -v, --v Level                              number for the log level verbosity\n      --version                              Display the version and exit\n      --vmodule moduleSpec                   comma-separated list of pattern=N settings for file-filtered logging\n      --watch-config-map                     Enables watching serviceaccounts that are configured through the pod-identity-webhook configmap instead of using annotations\n```\n\n### AWS_DEFAULT_REGION Injection\n\nWhen the `aws-default-region` flag is set this webhook will inject `AWS_DEFAULT_REGION` and `AWS_REGION` in mutated containers if `AWS_DEFAULT_REGION` and `AWS_REGION` are not already set.\n\n### AWS_STS_REGIONAL_ENDPOINTS Injection\n\nWhen the `sts-regional-endpoint` flag is set to `true`, the webhook will\ninject the environment variable `AWS_STS_REGIONAL_ENDPOINTS` with the value set\nto `regional`. This environment variable will configure the AWS SDKs to perform\nthe `sts:AssumeRoleWithWebIdentity` call to get credentials from the regional\nendpoint, instead of the global endpoint in `us-east-1`. This is desirable in\nalmost all cases, unless the STS regional endpoint is [disabled in your\naccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html).\n\nYou can also enable this per-service account with the annotation\n`eks.amazonaws.com/sts-regional-endpoints` set to `\"true\"`.\n\n### pod-identity-webhook ConfigMap\n\nThe purpose of the `pod-identity-webhook` ConfigMap is to simplify the mapping of IAM roles and ServiceAccount\nwhen using tools/installers like [kOps](https://kops.sigs.k8s.io/) that directly manage IAM roles and trust policies. When using these tools,\nusers do not need to configure annotations on the ServiceAccounts as the tools already know the relationship can relay it to the webhook.\n\nWhen the `watch-config-map` flag is set to `true`, the webhook will watch the\n`pod-identity-webhook` ConfigMap in the namespace configured by the `--namespace` flag\nfor additional ServiceAccounts. The webhook will mutate Pods configured to use these\nServiceAccounts even if they have no annotations.\n\nShould the same ServiceAccount both be referenced both in the ConfigMap and have annotations, the annotations takes presedence. \n\nHere is an example ConfigMap:\n\n```\napiVersion: v1\ndata:\n  config: '{\"default/myserviceaccount\":{\"RoleARN\":\"arn:aws-test:iam::123456789012:role/myserviceaccount.default.sa.minimal.example.com\",\"Audience\":\"amazonaws.com\",\"UseRegionalSTS\":true,\"TokenExpiration\":0},\"myapp/myotherserviceaccount\":{\"RoleARN\":\"arn:aws-test:iam::123456789012:role/myotherserviceaccount.myapp.sa.minimal.example.com\",\"Audience\":\"amazonaws.com\",\"UseRegionalSTS\":true,\"TokenExpiration\":0},\"test-*/myserviceaccount\":{\"RoleARN\":\"arn:aws-test:iam::123456789012:role/myserviceaccount.test-wildcard.sa.minimal.example.com\",\"Audience\":\"amazonaws.com\",\"UseRegionalSTS\":true,\"TokenExpiration\":0}}'\nkind: ConfigMap\nmetadata:\n  annotations:\n    prometheus.io/port: \"443\"\n    prometheus.io/scheme: https\n    prometheus.io/scrape: \"true\"\n  creationTimestamp: null\n  name: pod-identity-webhook\n  namespace: kube-system\n```\n\n\n## Container Images\n\nContainer images for amazon-eks-pod-identity-webhook can be found on [ECR](https://gallery.ecr.aws/eks/amazon-eks-pod-identity-webhook).\n\n## Installation\n\n### Pre-requisites\n\nYou must install cert-manager as it is a pre-requisite for below deployments. (See [cert-manager installation](https://cert-manager.io/docs/installation/))\n\n### In-cluster\n\nYou can use the provided configuration files in the `deploy` directory, along with the provided `Makefile`.\n\n```\nmake cluster-up IMAGE=amazon/amazon-eks-pod-identity-webhook:latest\n```\n\nThis will:\n* Create a service account, role, cluster-role, role-binding, and cluster-role-binding that the deployment requires\n* Create the deployment, service, ClusterIssuer, certificate, and mutating webhook in the cluster\n* Use `in-cluster=false` so that the webhook reloads certificates from the filesystem rather than creating CSRs to request certificates (using CSRs is now deprecated and will not work versions later than v0.3.0).\n\nFor self-hosted API server configuration, see see [SELF_HOSTED_SETUP.md](/SELF_HOSTED_SETUP.md)\n\n### On API server\nTODO\n\n### Notes\nWith the upgrade to client-go 1.18, certificate_manager_server_expiration_seconds metric has been removed by an upstream commit kubernetes/kubernetes#85874.\nA new metric certificate_manager_server_rotation_seconds is added which tracks the time a certificate was valid before getting rotated.\n\n## Code of Conduct\nSee [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n\n## License\nApache 2.0 - Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSee [LICENSE](LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-eks-pod-identity-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Famazon-eks-pod-identity-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-eks-pod-identity-webhook/lists"}