Identity Reference

The identity reference customization allows the user to specify the AWS identity to use when reconciling the cluster. This identity reference can be used to authenticate with AWS services using different identity types such as AWSClusterControllerIdentity, AWSClusterRoleIdentity, or AWSClusterStaticIdentity.

This customization is available for AWS clusters when the provider-specific cluster configuration patch is included in the ClusterClass.

For detailed information about AWS multi-tenancy and identity management, see the Cluster API AWS Multi-tenancy documentation.

Example

To specify the AWS identity reference for an AWS cluster, use the following configuration:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          aws:
            identityRef:
              kind: AWSClusterStaticIdentity
              name: my-aws-identity

Identity Types

The following identity types are supported:

  • AWSClusterControllerIdentity: Uses the default identity for the controller
  • AWSClusterRoleIdentity: Assumes a role using the provided source reference
  • AWSClusterStaticIdentity: Uses static credentials stored in a secret

Example with Different Identity Types

Using AWSClusterRoleIdentity

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          aws:
            identityRef:
              kind: AWSClusterRoleIdentity
              name: my-role-identity

Using AWSClusterStaticIdentity

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          aws:
            identityRef:
              kind: AWSClusterStaticIdentity
              name: my-static-identity

Applying this configuration will result in the following value being set:

  • AWSCluster:

    • spec:
        template:
          spec:
            identityRef:
              kind: AWSClusterStaticIdentity
              name: my-aws-identity
      

Notes

  • If no identity is specified, the default identity for the controller will be used
  • The identity reference must exist in the cluster before creating the cluster
  • For AWSClusterStaticIdentity, the referenced secret must contain the required AWS credentials
  • For AWSClusterRoleIdentity, the role must be properly configured with the necessary permissions

Last modified October 7, 2025: release(main): v0.35.1 (#1343) (e059bb5)