Specifying the IAM Role to use for Management Components

Prerequisites

To be able to specify the IAM role that the management components should run as your cluster must be set up with the ability to assume IAM roles using one of the following solutions:

Setting IAM Role

Set the AWS_CONTROLLER_IAM_ROLE environment variable to the ARN of the IAM role to use when performing the clusterctl init command.

For example:

export AWS_CONTROLLER_IAM_ROLE=arn:aws:iam::1234567890:role/capa-management-components
clusterctl init --infrastructure=aws

IAM Role Trust Policy

IAM Roles for Service Accounts

When creating the IAM role, the following trust policy will need to be used with the AWS_ACCOUNT_ID, AWS_REGION and OIDC_PROVIDER_ID environment variables replaced.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/oidc.eks.${AWS_REGION}.amazonaws.com/id/${OIDC_PROVIDER_ID}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "ForAnyValue:StringEquals": {
          "oidc.eks.${AWS_REGION}.amazonaws.com/id/${OIDC_PROVIDER_ID}:sub": [
            "system:serviceaccount:capa-system:capa-controller-manager",
            "system:serviceaccount:capi-system:capi-controller-manager",
            "system:serviceaccount:capa-eks-control-plane-system:capa-eks-control-plane-controller-manager",
            "system:serviceaccount:capa-eks-bootstrap-system:capa-eks-bootstrap-controller-manager",
          ]
        }
      }
    }
  ]
}

If you plan to use the controllers.cluster-api-provider-aws.sigs.k8s.io role created by clusterawsadm then you’ll need to add the following to your AWSIAMConfiguration:

apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSIAMConfiguration
spec:
  clusterAPIControllers:
    disabled: false
    trustStatements:
    - Action:
      - "sts:AssumeRoleWithWebIdentity"
      Effect: "Allow"
      Principal:
        Federated:
        - "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/oidc.eks.${AWS_REGION}.amazonaws.com/id/${OIDC_PROVIDER_ID}"
      Condition:
        "ForAnyValue:StringEquals":
          "oidc.eks.${AWS_REGION}.amazonaws.com/id/${OIDC_PROVIDER_ID}:sub":
            - system:serviceaccount:capa-system:capa-controller-manager
            - system:serviceaccount:capa-eks-control-plane-system:capa-eks-control-plane-controller-manager # Include if also using EKS

With this you can then set AWS_CONTROLLER_IAM_ROLE to arn:aws:iam::${AWS_ACCOUNT_ID}:role/controllers.cluster-api-provider-aws.sigs.k8s.io

Kiam / kube2iam

When creating the IAM role, you will need to apply the kubernetes.io/cluster/${CLUSTER_NAME}/role": "enabled" tag to the role and use the following trust policy with the AWS_ACCOUNT_ID and CLUSTER_NAME environment variables correctly replaced.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    },
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${CLUSTER_NAME}.worker-node-role"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

If you plan to use the controllers.cluster-api-provider-aws.sigs.k8s.io role created by clusterawsadm then you’ll need to add the following to your AWSIAMConfiguration:

apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSIAMConfiguration
spec:
  clusterAPIControllers:
    disabled: false
    trustStatements:
      - Action:
        - "sts:AssumeRole"
        Effect: "Allow"
        Principal:
          Service:
          - "ec2.amazonaws.com"
      - Action:
        - "sts:AssumeRole"
        Effect: "Allow"
        Principal:
          AWS:
          - "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${CLUSTER_NAME}.worker-node-role"

With this you can then set AWS_CONTROLLER_IAM_ROLE to arn:aws:iam::${AWS_ACCOUNT_ID}:role/controllers.cluster-api-provider-aws.sigs.k8s.io