Per-Pod Image Pull Permissions in EKS: Mastering ECR Policies
In a world where security and resource management are paramount, per-pod image pull permissions on Amazon EKS provide a robust solution. This feature allows you to define repository permissions at the pod level, minimizing the risk of unauthorized access and ensuring that only the right teams can pull the images they need.
The mechanism relies on a combination of IAM Roles for Service Accounts (IRSA) and the ecr-credential-provider. You start by creating a pull IAM role for each team, with an OpenID Connect (OIDC) trust policy that scopes to the team's service accounts. When a pod is created, it includes the eks.amazonaws.com/ecr-role-arn annotation, pointing to the corresponding IAM role. The kubelet then projects a service account token to the ecr-credential-provider, which authenticates with ECR using the team’s IAM role. If the ECR resource policy allows the role, the image pull succeeds; otherwise, it fails with a 403 Forbidden error.
To implement this effectively, ensure you are using EKS version 1.35 or later, as this version fully supports the feature. Additionally, be prepared with the necessary AWS permissions to create resources like VPCs, EKS, ECR, and IAM. This setup not only streamlines image management but also enhances security by enforcing strict access controls based on team roles.
Key takeaways
- →Create a pull IAM role per team to manage image access effectively.
- →Use the eks.amazonaws.com/ecr-role-arn annotation for pod-level permissions.
- →Ensure your EKS cluster is version 1.35 or later for full functionality.
- →Leverage the ecr-credential-provider for seamless authentication with ECR.
Why it matters
Implementing per-pod image pull permissions significantly reduces the risk of unauthorized image access, enhancing security in multi-tenant environments. This control is crucial for organizations managing sensitive workloads across different teams.
Code examples
git clone https://github.com/aws-samples/sample-ecr-per-pod-permission
cd sample-ecr-per-pod-permission./scripts/create-infra.sh1cat > /etc/eks/image-credential-provider/config.json <<'CONFIG'
2{
3 "apiVersion": "kubelet.config.k8s.io/v1",
4 "kind": "CredentialProviderConfig",
5 "providers": [
6 {
7 "name": "ecr-credential-provider",
8 "matchImages": [
9 "*.dkr.ecr.*.amazonaws.com",
10 "*.dkr-ecr.*.on.aws",
11 "*.dkr.ecr.*.amazonaws.com.cn",
12 "*.dkr-ecr.*.on.amazonwebservices.com.cn",
13 "*.dkr.ecr-fips.*.amazonaws.com",
14 "*.dkr-ecr-fips.*.on.aws",
15 "*.dkr.ecr.*.c2s.ic.gov",
16 "*.dkr.ecr.*.sc2s.sgov.gov",
17 "*.dkr.ecr.*.cloud.adc-e.uk",
18 "*.dkr.ecr.*.csp.hci.ic.gov",
19 "*.dkr.ecr.*.amazonaws.eu",
20 "public.ecr.aws",
21 "ecr-public.aws.com"
22 ],
23 "defaultCacheDuration": "12h0m0s",
24 "apiVersion": "credentialprovider.kubelet.k8s.io/v1",
25 "tokenAttributes": {
26 "serviceAccountTokenAudience": "sts.amazonaws.com",
27 "cacheType": "ServiceAccount",
28 "requireServiceAccount": false,
29 "optionalServiceWhen NOT to use this
The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.
Want the complete reference?
Read official docsIndustry-standard certifications built by the people behind Linux and Kubernetes. Earn the CKA — the gold standard Kubernetes administrator cert. OpsCanary readers get 30% off year-round with code OPSCANARY3.
Get CKA certified →Navigating NIS2 and DORA Ownership in Kubernetes Teams
Understanding who owns NIS2 and DORA regulations on your Kubernetes platform team is crucial for compliance and security. The traceability chain involves specific roles across risk, legal, and security teams, alongside your platform and application teams. Get ready to clarify responsibilities and streamline your compliance efforts.
Guardrails, Not Gates: Rethinking Policy in Kubernetes
In a world where developer experience clashes with security, adopting a guardrail approach can transform your platform team's policies. Instead of blocking progress, guardrails guide developers while ensuring compliance. Learn how to implement validation effectively with Kyverno's enforcement settings.
Security Slam 2026: Elevate Your Kubernetes Security Posture
Get ready for Security Slam 2026, a 30-day virtual event designed to boost your project's security hygiene. Leverage OpenSSF projects and engage with advisors in a dedicated CNCF Slack channel to tackle security challenges tailored to your maturity level.
Get the daily digest
One email. 5 articles. Every morning.
No spam. Unsubscribe anytime.