EKS — konfig-konector Docs

EKSCluster # ✅ Working ⏱ async

Creates and manages an EKS control plane. Supports full VPC configuration, control plane logging, envelope encryption, access configuration, Kubernetes network config, and upgrade policy.

⏱ Async — EKS cluster creation takes 10–15 minutes. Controller polls every 30 seconds until the cluster reaches the ACTIVE state.

Spec

Field	Type	Required	Description
clusterName	string	✅	Unique name for the EKS cluster. Immutable after creation.
version	string		Kubernetes version (e.g. `1.30`). Upgrades trigger an async update.
roleArn	string		IAM role ARN for the cluster control plane. Exactly one of `roleArn` or `roleRef.name` required.
roleRef.name	string		Name of the `IAMRole` CR to use as the cluster role.
resourcesVpcConfig.subnetRefs	[]SubnetRef	✅	Subnet CR names or IDs. At least two subnets in different AZs required.
resourcesVpcConfig.securityGroupRefs	[]string		Additional security group CR names for the cluster ENIs.
resourcesVpcConfig.endpointPublicAccess	bool		Allow public access to the Kubernetes API server. Default: true.
resourcesVpcConfig.endpointPrivateAccess	bool		Allow private (VPC-internal) access to the Kubernetes API server. Default: false.
resourcesVpcConfig.publicAccessCidrs	[]string		CIDRs allowed to access the public API endpoint. Default: `["0.0.0.0/0"]`.
logging.enabledTypes	[]string		Control plane log types to send to CloudWatch: `api`, `audit`, `authenticator`, `controllerManager`, `scheduler`.
encryptionConfig.providerKeyArn	string		KMS key ARN for envelope encryption of Kubernetes secrets. Immutable.
encryptionConfig.resources	[]string		Resources to encrypt (typically `["secrets"]`). Immutable.
accessConfig.authenticationMode	string		`API`, `API_AND_CONFIG_MAP`, or `CONFIG_MAP`. Required for `EKSAccessEntry`.
accessConfig.bootstrapClusterCreatorAdminPermissions	bool		Grant the cluster creator cluster-admin permissions via an access entry. Default: true.
kubernetesNetworkConfig.serviceIpv4Cidr	string		CIDR for Kubernetes service IPs (e.g. `172.20.0.0/16`). Immutable.
kubernetesNetworkConfig.ipFamily	string		`ipv4` or `ipv6`. Immutable after creation.
upgradePolicy.supportType	string		`STANDARD` or `EXTENDED` support. Extended support provides longer patch windows. Mutable.
bootstrapSelfManagedAddons	bool		Bootstrap self-managed addons (kube-proxy, CoreDNS, vpc-cni). Default: true. Immutable.
tags	map[string]string		AWS tags applied to the cluster.

Status

Field	Description
clusterArn	The ARN of the EKS cluster.
endpoint	The Kubernetes API server endpoint URL.
version	The current Kubernetes version.
status	Cluster status: `CREATING`, `ACTIVE`, `DELETING`, `FAILED`, `UPDATING`.
certificateAuthority	Base64-encoded certificate authority data for kubeconfig.
oidcIssuer	The OIDC issuer URL for the cluster (use with `IAMOIDCProvider` for IRSA).
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — Basic Cluster

apiVersion: aws.konfig.io/v1alpha1
kind: EKSCluster
metadata:
  name: prod-cluster
  namespace: platform
spec:
  clusterName: prod-cluster
  version: "1.30"
  roleArn: arn:aws:iam::123456789012:role/eks-cluster-role
  resourcesVpcConfig:
    subnetRefs:
      - prod-private-subnet-1a
      - prod-private-subnet-1b
      - prod-private-subnet-1c
    endpointPublicAccess: true
    endpointPrivateAccess: true
    publicAccessCidrs:
      - 203.0.113.0/24
  accessConfig:
    authenticationMode: API_AND_CONFIG_MAP
  tags:
    env: prod

Example — Full-Featured Cluster

apiVersion: aws.konfig.io/v1alpha1
kind: EKSCluster
metadata:
  name: prod-cluster
  namespace: platform
spec:
  clusterName: prod-cluster
  version: "1.30"
  roleArn: arn:aws:iam::123456789012:role/eks-cluster-role
  resourcesVpcConfig:
    subnetRefs:
      - prod-private-subnet-1a
      - prod-private-subnet-1b
    endpointPublicAccess: false
    endpointPrivateAccess: true
  logging:
    enabledTypes:
      - api
      - audit
      - authenticator
  encryptionConfig:
    providerKeyArn: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123
    resources:
      - secrets
  accessConfig:
    authenticationMode: API
    bootstrapClusterCreatorAdminPermissions: true
  kubernetesNetworkConfig:
    serviceIpv4Cidr: 172.20.0.0/16
    ipFamily: ipv4
  upgradePolicy:
    supportType: EXTENDED
  tags:
    env: prod
    criticality: high

Notes

Either roleArn or roleRef.name is required. The role must have the AmazonEKSClusterPolicy managed policy attached.
kubernetesNetworkConfig.ipFamily and kubernetesNetworkConfig.serviceIpv4Cidr are immutable after creation.
upgradePolicy.supportType is mutable and can be changed without recreating the cluster.
The oidcIssuer in status is used to create an IAMOIDCProvider CR for IRSA (IAM Roles for Service Accounts).

Deletion

Prerequisite deletions required. Delete all EKSNodeGroup, EKSFargateProfile, and EKSAddon CRs before deleting the cluster. Cluster deletion takes 10–15 minutes.

EKSNodeGroup # ✅ Working ⏱ async

Creates and manages an EKS managed node group. Supports scaling configuration, instance types, AMI type, capacity type, taints, labels, launch templates, and node repair.

⏱ Async — node group creation and scaling takes 3–5 minutes. Controller polls every 20 seconds until the node group reaches the ACTIVE state.

Spec

Field	Type	Required	Description
clusterName	string	✅	EKS cluster name. Mutually exclusive with `clusterRef.name`.
clusterRef.name	string		Name of the `EKSCluster` CR (alternative to `clusterName`).
nodegroupName	string	✅	Name of the node group. Immutable after creation.
nodeRoleArn	string		IAM role ARN for EC2 instances. One of `nodeRoleArn` or `nodeRoleRef.name` required.
nodeRoleRef.name	string		Name of the `IAMRole` CR.
subnetRefs	[]SubnetRef	✅	Subnet CR names or IDs. Place in private subnets for production.
scalingConfig.minSize	int32	✅	Minimum number of nodes.
scalingConfig.maxSize	int32	✅	Maximum number of nodes.
scalingConfig.desiredSize	int32	✅	Desired number of nodes. Managed by cluster autoscaler in autoscaled setups.
instanceTypes	[]string		EC2 instance types (e.g. `["m5.xlarge", "m5a.xlarge"]`). Immutable.
amiType	string		AMI type: `AL2_x86_64`, `AL2_x86_64_GPU`, `AL2_ARM_64`, `AL2023_x86_64_STANDARD`, etc. Immutable.
capacityType	string		`ON_DEMAND` or `SPOT`. Immutable. Default: `ON_DEMAND`.
diskSize	int32		Root EBS disk size in GiB. Immutable when using a launch template.
labels	map[string]string		Kubernetes labels to apply to nodes.
taints	[]Taint		Kubernetes taints to apply to nodes.
taints[].key	string		Taint key.
taints[].value	string		Taint value.
taints[].effect	string		`NO_SCHEDULE`, `NO_EXECUTE`, or `PREFER_NO_SCHEDULE`.
updateConfig.maxUnavailable	int32		Maximum number of unavailable nodes during updates.
updateConfig.maxUnavailablePercentage	int32		Maximum percentage of unavailable nodes during updates.
launchTemplate.name	string		Launch template name.
launchTemplate.id	string		Launch template ID (alternative to name).
launchTemplate.version	string		Launch template version.
releaseVersion	string		AMI release version (e.g. `1.30.0-20240514`).
version	string		Kubernetes version for the node group. Defaults to cluster version.
remoteAccess.ec2SshKey	string		EC2 key pair name for SSH access.
remoteAccess.sourceSecurityGroupRefs	[]string		Security groups allowed SSH access to nodes.
nodeRepairConfig.enabled	bool		Enable automatic node repair. Unhealthy nodes are automatically replaced.
tags	map[string]string		AWS tags applied to the node group and EC2 instances.

Status

Field	Description
nodegroupArn	The ARN of the node group.
status	Current status: `CREATING`, `ACTIVE`, `UPDATING`, `DELETING`, `DEGRADED`.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — Basic Worker Nodes

apiVersion: aws.konfig.io/v1alpha1
kind: EKSNodeGroup
metadata:
  name: prod-workers
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  nodegroupName: prod-workers
  nodeRoleArn: arn:aws:iam::123456789012:role/eks-node-role
  subnetRefs:
    - prod-private-subnet-1a
    - prod-private-subnet-1b
  scalingConfig:
    minSize: 2
    maxSize: 10
    desiredSize: 3
  instanceTypes:
    - m5.xlarge
  amiType: AL2023_x86_64_STANDARD
  capacityType: ON_DEMAND
  diskSize: 50
  tags:
    env: prod

Example — Full-Featured with Taints and Node Repair

apiVersion: aws.konfig.io/v1alpha1
kind: EKSNodeGroup
metadata:
  name: prod-gpu-workers
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  nodegroupName: prod-gpu-workers
  nodeRoleArn: arn:aws:iam::123456789012:role/eks-node-role
  subnetRefs:
    - prod-private-subnet-1a
  scalingConfig:
    minSize: 0
    maxSize: 5
    desiredSize: 1
  instanceTypes:
    - g4dn.xlarge
    - g4dn.2xlarge
  amiType: AL2_x86_64_GPU
  capacityType: ON_DEMAND
  labels:
    workload-type: gpu
    env: prod
  taints:
    - key: nvidia.com/gpu
      value: present
      effect: NO_SCHEDULE
  updateConfig:
    maxUnavailable: 1
  nodeRepairConfig:
    enabled: true
  tags:
    env: prod
    workload: gpu

Deletion

Async (3–5 minutes). EKS drains pods from nodes (respecting PodDisruptionBudgets), terminates the EC2 instances, and deletes the node group. The CR remains until AWS confirms full deletion.

EKSAddon # ✅ Working

Creates and manages an EKS cluster addon (e.g. vpc-cni, kube-proxy, coredns, ebs-csi-driver, eks-pod-identity-agent). Can adopt pre-existing addons.

Spec

Field	Type	Required	Description
clusterName	string		EKS cluster name. Mutually exclusive with `clusterRef.name`.
clusterRef.name	string		Name of the `EKSCluster` CR. One of these is required.
addonName	string	✅	Addon name (e.g. `vpc-cni`, `coredns`, `kube-proxy`, `aws-ebs-csi-driver`, `eks-pod-identity-agent`).
addonVersion	string		Addon version. If omitted, defaults to the latest recommended version.
serviceAccountRoleArn	string		IAM role ARN for the addon's service account (IRSA). Mutually exclusive with `serviceAccountRoleRef.name`.
serviceAccountRoleRef.name	string		Name of the `IAMRole` CR for the addon's service account.
resolveConflicts	string		Conflict resolution on install: `OVERWRITE`, `NONE`, or `PRESERVE`. Default: `OVERWRITE`.
configurationValues	string		JSON configuration override for the addon (addon-specific settings).
tags	map[string]string		AWS tags applied to the addon.

Status

Field	Description
addonArn	The ARN of the addon.
addonVersion	The installed addon version.
status	Addon status: `CREATING`, `ACTIVE`, `DEGRADED`, `UPDATING`.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — vpc-cni Addon

apiVersion: aws.konfig.io/v1alpha1
kind: EKSAddon
metadata:
  name: prod-vpc-cni
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  addonName: vpc-cni
  resolveConflicts: OVERWRITE
  tags:
    env: prod

Example — ebs-csi-driver with IRSA

apiVersion: aws.konfig.io/v1alpha1
kind: EKSAddon
metadata:
  name: prod-ebs-csi-driver
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  addonName: aws-ebs-csi-driver
  addonVersion: v1.26.0-eksbuild.1
  serviceAccountRoleRef:
    name: ebs-csi-controller-role
  resolveConflicts: OVERWRITE
  tags:
    env: prod

Deletion

Immediate. The addon is removed from the cluster. The addon's Kubernetes resources (DaemonSets, Deployments) are deleted.

EKSFargateProfile # ✅ Working ⏱ async

Creates a Fargate profile defining which pods run on AWS Fargate rather than EC2 nodes. Pod selection is based on namespace and optional label selectors.

⏱ Async — Fargate profile creation and deletion takes approximately 2 minutes. Controller polls every 15 seconds.

Spec

Field	Type	Required	Description
clusterName	string		EKS cluster name. One of `clusterName` or `clusterRef.name` required.
clusterRef.name	string		Name of the `EKSCluster` CR.
fargateProfileName	string	✅	Name of the Fargate profile. Immutable after creation.
podExecutionRoleArn	string		IAM role ARN for Fargate pod execution. One of this or `podExecutionRoleRef.name` required.
podExecutionRoleRef.name	string		Name of the `IAMRole` CR for pod execution.
subnetRefs	[]SubnetRef		Private subnet CR names or IDs. Fargate pods require private subnets.
selectors	[]Selector	✅	Pod selection criteria. At least one selector required.
selectors[].namespace	string	✅	Kubernetes namespace to match.
selectors[].labels	map[string]string		Optional label selectors. All labels must match.
tags	map[string]string		AWS tags applied to the Fargate profile.

Status

Field	Description
fargateProfileArn	The ARN of the Fargate profile.
status	Current status: `CREATING`, `ACTIVE`, `DELETING`, `CREATE_FAILED`.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example

apiVersion: aws.konfig.io/v1alpha1
kind: EKSFargateProfile
metadata:
  name: prod-fargate-profile
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  fargateProfileName: prod-serverless
  podExecutionRoleArn: arn:aws:iam::123456789012:role/eks-fargate-pod-execution-role
  subnetRefs:
    - prod-private-subnet-1a
    - prod-private-subnet-1b
  selectors:
    - namespace: serverless-workloads
    - namespace: kube-system
      labels:
        k8s-app: kube-dns
  tags:
    env: prod

Notes

Fargate pods must run in private subnets. Public subnet placement is not supported.
Selectors and subnets are mostly immutable after creation. To change them, delete and recreate the profile.
The pod execution role must have the AmazonEKSFargatePodExecutionRolePolicy managed policy attached.

Deletion

Async (~2 minutes). Running pods matched by this profile are terminated. The profile is fully deleted after AWS confirms deletion.

EKSAccessEntry # ✅ Working

Maps an IAM principal (role or user) to Kubernetes RBAC groups or EKS access policies. Requires the cluster to use API or API_AND_CONFIG_MAP authentication mode.

Spec

Field	Type	Description
clusterName	string	EKS cluster name. One of `clusterName` or `clusterRef.name` required.
clusterRef.name	string	Name of the `EKSCluster` CR.
principalArn	string	IAM principal ARN (role or user). One of `principalArn` or `principalRef.name` required.
principalRef.name	string	Name of the `IAMRole` CR.
type	string	Entry type: `STANDARD`, `FARGATE_LINUX`, `EC2_LINUX`, or `EC2_WINDOWS`. Default: `STANDARD`.
kubernetesGroups	[]string	Kubernetes RBAC groups to add the principal to (e.g. `["system:masters"]`).
username	string	Kubernetes username for the principal. Defaults to the IAM principal ARN.
accessPolicies	[]AccessPolicy	EKS access policies to associate with this entry.
accessPolicies[].policyArn	string	ARN of the EKS access policy.
accessPolicies[].accessScope.type	string	`cluster` for cluster-wide access, `namespace` for namespace-scoped access.
accessPolicies[].accessScope.namespaces	[]string	Namespaces to scope access to (when type is `namespace`).
tags	map[string]string	AWS tags applied to the access entry.

Common Access Policy ARNs

Policy	ARN	Description
AmazonEKSClusterAdminPolicy	`arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy`	Full cluster-admin access.
AmazonEKSAdminPolicy	`arn:aws:eks::aws:cluster-access-policy/AmazonEKSAdminPolicy`	Admin access, cluster-scoped.
AmazonEKSEditPolicy	`arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy`	Edit access to workload resources.
AmazonEKSViewPolicy	`arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy`	Read-only view access.

Status

Field	Description
accessEntryArn	The ARN of the access entry.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — Cluster Admin Access

apiVersion: aws.konfig.io/v1alpha1
kind: EKSAccessEntry
metadata:
  name: platform-team-admin
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  principalArn: arn:aws:iam::123456789012:role/platform-team-role
  type: STANDARD
  accessPolicies:
    - policyArn: arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy
      accessScope:
        type: cluster
  tags:
    team: platform

Example — Namespace-Scoped Edit for CI Role

apiVersion: aws.konfig.io/v1alpha1
kind: EKSAccessEntry
metadata:
  name: ci-deploy-access
  namespace: platform
spec:
  clusterRef:
    name: prod-cluster
  principalArn: arn:aws:iam::123456789012:role/ci-deploy-role
  type: STANDARD
  accessPolicies:
    - policyArn: arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy
      accessScope:
        type: namespace
        namespaces:
          - my-app
          - my-app-staging
  tags:
    purpose: ci-cd

Notes

The EKS cluster must be configured with accessConfig.authenticationMode: API or API_AND_CONFIG_MAP for access entries to work.
Access entries replace the need to manually manage the aws-auth ConfigMap for IAM principals.
For EC2 node role principals, use type: EC2_LINUX or EC2_WINDOWS instead of STANDARD.

Deletion

Immediate. The access entry and associated policy associations are deleted. The IAM principal loses access to the cluster.