Amazon Elastic Kubernetes Service (EKS) Integration

​

Overview

​

Cluster Driver

ClusterDriverEKS = "EKS"

​

Configuration Spec

​

Cluster Spec Fields

spec:
  eksConfig:
    amazonCredentialSecret: string    # Reference to AWS credential secret
    displayName: string               # EKS cluster name
    region: string                    # AWS region (e.g., us-west-2)
    kubernetesVersion: string         # Kubernetes version
    imported: bool                    # Whether cluster is imported

​

Authentication Configuration

eksConfig:
  amazonCredentialSecret: string      # Secret containing AWS credentials

• amazonec2credentialConfig-accessKey: AWS access key ID
• amazonec2credentialConfig-secretKey: AWS secret access key

​

Networking Configuration

eksConfig:
  subnets: []string                   # VPC subnet IDs
  securityGroups: []string            # Security group IDs
  serviceRole: string                 # IAM service role ARN
  publicAccess: bool                  # Enable public API endpoint
  privateAccess: bool                 # Enable private API endpoint
  publicAccessSources: []string       # CIDR blocks for API access

• VPC (Virtual Network)
• Subnets across availability zones
• Security groups
• Internet gateway and route tables

​

Node Group Configuration

eksConfig:
  nodeGroups:
    - nodegroupName: string           # Node group name
      desiredSize: int                # Desired number of nodes
      minSize: int                    # Minimum nodes
      maxSize: int                    # Maximum nodes
      diskSize: int                   # EBS volume size (GB)
      instanceType: string            # EC2 instance type
      labels: {}                      # Kubernetes labels
      tags: {}                        # AWS resource tags
      ec2SshKey: string              # SSH key name
      subnets: []string              # Subnet IDs for node group
      version: string                # Kubernetes version
      launchTemplate:                # Launch template configuration
        name: string
        id: string
        version: int
      requestSpotInstances: bool     # Use spot instances
      spotInstanceTypes: []string    # Spot instance types

​

Security Configuration

eksConfig:
  secretsEncryption: bool            # Enable secrets encryption
  kmsKey: string                     # KMS key ARN for encryption
  loggingTypes: []string             # CloudWatch logging types
                                     # Options: api, audit, authenticator,
                                     #          controllerManager, scheduler

​

Advanced Features

eksConfig:
  tags: {}                           # Cluster resource tags
  ebsCSIDriver: bool                 # Enable EBS CSI driver addon
  ipFamily: string                   # IPv4 or IPv6

​

EKS Operator Integration

​

Lifecycle Management

​

Creating Phase

• Cluster resources are being provisioned in AWS
• ClusterConditionProvisioned set to Unknown
• Upstream spec is initialized

​

Active Phase

• Cluster is provisioned and running
• Service account token is generated
• Network details are copied to cluster status
• ClusterConditionProvisioned set to True

​

Updating Phase

• Cluster configuration is being updated
• ClusterConditionUpdated set to Unknown
• Changes are synchronized to EKSClusterConfig CRD

​

EKSClusterConfig Custom Resource

apiVersion: eks.cattle.io/v1
kind: EKSClusterConfig
metadata:
  name: cluster-name
  namespace: cattle-global-data
spec:
  # Mirrors cluster.spec.eksConfig

​

Cluster Status

status:
  driver: EKS
  eksStatus:
    upstreamSpec:                     # Upstream EKS configuration
    virtualNetwork: string            # VPC ID
    subnets: []string                 # Subnet IDs
    securityGroups: []string          # Security group IDs
    privateRequiresTunnel: bool       # Tunnel requirement for private API
    managedLaunchTemplateID: string   # Launch template ID
    managedLaunchTemplateVersions: {} # Launch template versions per node group
    generatedNodeRole: string         # Auto-generated node IAM role

​

Authentication & API Access

​

AWS IAM Authenticator

import "sigs.k8s.io/aws-iam-authenticator/pkg/token"

// Generate token for EKS cluster authentication
token, err := generator.GetWithOptions(&token.GetTokenOptions{
    Session:   awsSession,
    ClusterID: clusterName,
})

​

REST Config

• EKS API endpoint
• CA certificate (base64 decoded)
• IAM authenticator bearer token

​

Private Cluster Support

​

Tunnel Detection

1. DNS Resolution Fails: Requires tunnel
2. Connection Timeout: Requires tunnel
3. Connection Succeeds: Direct access possible

​

Service Account Token Generation

• If direct access: Token generated immediately
• If tunnel required: Wait for cluster agent deployment
• Token stored in secret: cluster.Status.ServiceAccountTokenSecret

​

Node Group Requirements

• ClusterConditionWaiting set to False
• Message: “Cluster must have at least one managed nodegroup or one self-managed node.”

​

Provisioning Workflow

1. Create Cluster Object: Define cluster with spec.eksConfig
2. Credential Validation: Validate AWS credentials
3. CRD Creation: EKSClusterConfig CRD is created
4. Resource Provisioning: EKS operator provisions:
   • EKS control plane
   • VPC and networking (if not provided)
   • Node groups
   • Security groups
5. Status Synchronization: Network details copied to cluster status
6. Service Account: Generate and store service account token
7. Agent Deployment: Rancher cluster agent deployed
8. Active State: Cluster ready for workloads

​

Importing Existing Clusters

spec:
  eksConfig:
    imported: true
    amazonCredentialSecret: "cattle-global-data:cc-xxxxx"
    displayName: "existing-cluster"
    region: "us-west-2"

• Rancher registers the cluster without modification
• Node groups are discovered from AWS
• ClusterConditionPending transitions from Unknown to True

​

Launch Templates

• Managed Launch Template ID: Shared template ID
• Template Versions: Per-node-group version mapping

​

Best Practices

​

Networking

• Use private subnets for worker nodes
• Enable both public and private API access during setup
• Use publicAccessSources to restrict API access
• Ensure subnet has sufficient IP addresses for pod networking

​

Security

• Enable secrets encryption with KMS
• Enable CloudWatch logging for audit trails
• Use IAM roles for service accounts (IRSA)
• Rotate AWS credentials regularly
• Use private clusters when possible

​

Node Groups

• Use managed node groups for simplified management
• Enable autoscaling for dynamic workloads
• Use multiple node groups for different instance types
• Consider spot instances for cost optimization

​

High Availability

• Deploy across multiple availability zones
• Use subnets in different AZs
• Configure appropriate node group sizes

​

Troubleshooting

​

403 Access Denied

• eks:* permissions for EKS operations
• ec2:* for networking resources
• iam:PassRole for service roles

​

Node Group Not Creating

• Node IAM role has required policies
• Subnets have available IP addresses
• Security groups allow required traffic
• Launch template configuration is valid

​

Agent Not Deploying

• Verify privateRequiresTunnel status
• Check if import command was executed
• Ensure at least one node group exists

​

Update Failures

• Check EKSClusterConfig status.failureMessage
• Verify node group versions are compatible
• Ensure Kubernetes version upgrades are incremental

​

Related Resources

• Amazon EKS Documentation
• EKS Best Practices Guide
• EKS Operator GitHub
• AWS IAM Authenticator

​

API Reference

​

Cluster Type Definition

type ClusterSpec struct {
    EKSConfig *eksv1.EKSClusterConfigSpec `json:"eksConfig,omitempty"`
    // ... other fields
}

​

Controller Registration