Securing AWS IAM access in Kubernetes

Dennis Bell
Nov 28, 2017 · 6 min read

At Merapar we regularly deploy Kubernetes on AWS and leverage IAM roles so our microservices can gain access to AWS services, such as DynamoDB, S3, Route53, etc. Because we want to follow the security principle of least privilege, we don’t want every microservice to have the same IAM permissions. This blog illustrates how fine grained AWS IAM roles at the pod or container level can be assigned with Kubernetes.

There are several possible approaches to managing credentials for access to AWS services:

Kubernetes Secrets seems to be ideal as it is all managed within Kubernetes, however because the secrets are only base64 encoded, you need to be careful when storing sensitive credentials. Base64 is as easily decoded as it is encoded! It is not the best place to store credentials for AWS services for example. Also bear in mind that statically configuring AWS user credentials would in most situations not meet security requirements for key rotation.

AWS IAM roles can help us here. What are IAM roles? Here is the AWS description:

“An IAM role is similar to a user, in that it is an AWS identity with permission policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it. Also, a role does not have standard long-term credentials (password or access keys) associated with it. Instead, if a user assumes a role, temporary security credentials are created dynamically and provided to the user.”

Obviously, you can assign a global IAM role to a Kubernetes node which is the union of all IAM roles required by all containers and pods running in the Kubernetes cluster. From a security standpoint, this is probably not an acceptable solution because a global IAM role can be inherited by all pods and containers running in the cluster.

Consider the following example: We can assign IAM roles to Kubernetes nodes, and give access for the Kubernetes Pods hosting the Storage Service access to the IAM role for AWS S3 Access. However, as it is assigned to the node, other services running on that node can also access the same roles and gain access, like the Web Service.

Default behavior when assigning IAM roles to Kubernetes nodes.

So instead of assigning IAM roles to nodes we should assign roles to Kubernetes Pods, and depending on the IAM Role linked to a Kubernetes Pods they have certain privileges, like read access DynamoDB or read/write access on a particular S3 bucket.

At this stage, Kubernetes does not natively support AWS IAM roles and permissions. Hence you need to give a special consideration to how you want to provide IAM permissions to your nodes, pods, and containers.

We found our solution in Kube2IAM (

“Kube2IAM’s solution is to redirect the traffic that is going to the ec2 metadata API for docker containers to a container running on each instance, make a call to the AWS API to retrieve temporary credentials and return these to the caller. Other calls will be proxied to the ec2 metadata API. This container will need to run with host networking enabled so that it can call the ec2 metadata API itself.”

The results is that each service gets its own fine grained IAM role (or shares an IAM Role) with certain privileges.

There is a more privileged intermediate Kube2IAM role, which is used by Kube2IAM to assume the more fine grained roles and obtain temporary credentials for the pods. The key to assigning these fine grained roles is that IAM role for the S3 Bucket has a two-way trust relationship with the Kube2IAM role.

Kube2IAM in Kubernetes IAM role overview.

Lets look in more detail at the roles and how they link together…

S3 Bucket role & Policy

Here is the IAM Policy attached to the S3 Bucket role:

And the trust relationships for this role:

Kube2IAM role & Policy

The policy of the Kube2IAM role looks like:

And the Trust relationships:

Note that the Kube2IAM role has a trust relationship with both the other fine grained roles that will be assumed and also with the EC2 instances. This way the Kube2IAM becomes the linking pin between Kubernetes Service role and the EC2 instance which gives access to the Amazon SDK endpoint used to obtain rotating credentials.

In order for Kube2IAM to assign a role to a specific pod, you add an annotation with the role that you want to assume.

Here is an example of a Kubernetes pod definition:

Restricting EC2 metadata API access

To avoid containers bypassing the Kube2IAM container and getting credentials for the privileged intermediate Kube2IAM role, the IP table policies must be adjusted.

To prevent containers from directly accessing the ec2 metadata API and gaining unwanted access to AWS resources, the traffic to must be proxied for all docker containers.

The iptables config would look like this:

This rule can be added automatically by the Kube2IAM container. This is achieved by setting --iptables=true, setting the HOST_IP environment variable, and running the container in a privileged security context.

For the Kube2IAM container we use a Kubernetes DaemonSet, so they are always scheduled on the Kubernetes Nodes. We need an instance of the container on each node so that requests from the other pods on that node are intercepted.

More details can be found in the docs in the Kube2IAM repository.


In summary it works like this, where the Kube2IAM acts as a kind of proxy, using the Kube2IAM role.

IAM role access management overview.

Kube2IAM is an awesome add-on for Kubernetes clusters running on AWS. It secures the access by granting containers IAM roles and enforcing their access privilege through role annotations.


Techblog of Merapar

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store