or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alb-controller.mdauth.mdcluster.mdfargate.mdindex.mdkubectl-provider.mdkubernetes-resources.mdnode-groups.mdservice-accounts.mdutilities.md
tile.json

alb-controller.mddocs/

Load Balancer Controller

AWS Load Balancer Controller installation and configuration for ingress and service load balancing with Application Load Balancers (ALB) and Network Load Balancers (NLB).

Capabilities

AlbController Class

Install and configure AWS Load Balancer Controller on EKS clusters.

/**
 * Install AWS Load Balancer Controller on EKS clusters
 */
class AlbController extends Construct {
  constructor(scope: Construct, id: string, props: AlbControllerProps);
  
  /** Create ALB controller with default configuration */
  static create(scope: Construct, props: AlbControllerProps): AlbController;
}

/**
 * ALB controller properties
 */
interface AlbControllerProps extends AlbControllerOptions {
  /** EKS cluster */
  readonly cluster: ICluster;
}

/**
 * ALB controller configuration options
 */
interface AlbControllerOptions {
  /** Controller version */
  readonly version?: AlbControllerVersion;
  /** Helm chart repository */
  readonly repository?: string;
  /** Kubernetes namespace */
  readonly namespace?: string;
  /** Service account name */
  readonly serviceAccountName?: string;
  /** Controller policy */
  readonly policy?: any;
}

Usage Examples:

import * as eks from "@aws-cdk/aws-eks";

// Basic ALB controller installation
const albController = eks.AlbController.create(this, {
  cluster: cluster,
  version: eks.AlbControllerVersion.V2_4_1,
});

// Advanced ALB controller configuration
const customAlbController = new eks.AlbController(this, "CustomAlbController", {
  cluster: cluster,
  version: eks.AlbControllerVersion.V2_4_1,
  namespace: "aws-load-balancer-controller",
  serviceAccountName: "aws-load-balancer-controller-sa",
});

AlbControllerVersion Class

AWS Load Balancer Controller version management.

/**
 * AWS Load Balancer Controller version management
 */
class AlbControllerVersion {
  /** Create custom version */
  static of(version: string): AlbControllerVersion;
  
  /** Version 2.0.0 */
  static readonly V2_0_0: AlbControllerVersion;
  /** Version 2.0.1 */
  static readonly V2_0_1: AlbControllerVersion;
  /** Version 2.1.0 */
  static readonly V2_1_0: AlbControllerVersion;
  /** Version 2.1.1 */
  static readonly V2_1_1: AlbControllerVersion;
  /** Version 2.1.2 */
  static readonly V2_1_2: AlbControllerVersion;
  /** Version 2.1.3 */
  static readonly V2_1_3: AlbControllerVersion;
  /** Version 2.2.0 */
  static readonly V2_2_0: AlbControllerVersion;
  /** Version 2.2.1 */
  static readonly V2_2_1: AlbControllerVersion;
  /** Version 2.2.2 */
  static readonly V2_2_2: AlbControllerVersion;
  /** Version 2.2.3 */
  static readonly V2_2_3: AlbControllerVersion;
  /** Version 2.2.4 */
  static readonly V2_2_4: AlbControllerVersion;
  /** Version 2.3.0 */
  static readonly V2_3_0: AlbControllerVersion;
  /** Version 2.3.1 */
  static readonly V2_3_1: AlbControllerVersion;
  /** Version 2.4.1 */
  static readonly V2_4_1: AlbControllerVersion;
}

Load Balancer Schemes

/**
 * Application Load Balancer scheme
 */
enum AlbScheme {
  /** Internal load balancer */
  INTERNAL = "internal",
  /** Internet-facing load balancer */
  INTERNET_FACING = "internet-facing"
}

Ingress Usage

Once the ALB controller is installed, you can create ingress resources:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: webapp-ingress
  namespace: default
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-west-2:123456789012:certificate/12345678-1234-1234-1234-123456789012
spec:
  rules:
    - host: webapp.example.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: webapp-service
              port:
                number: 80

CDK Ingress Example:

// Deploy application with ingress
cluster.addManifest("WebAppWithIngress",
  // Deployment
  {
    apiVersion: "apps/v1",
    kind: "Deployment",
    metadata: { name: "webapp", namespace: "default" },
    spec: {
      replicas: 3,
      selector: { matchLabels: { app: "webapp" } },
      template: {
        metadata: { labels: { app: "webapp" } },
        spec: {
          containers: [{
            name: "app",
            image: "nginx:alpine",
            ports: [{ containerPort: 80 }],
          }],
        },
      },
    },
  },
  // Service
  {
    apiVersion: "v1",
    kind: "Service", 
    metadata: { name: "webapp-service", namespace: "default" },
    spec: {
      selector: { app: "webapp" },
      ports: [{ port: 80, targetPort: 80 }],
      type: "ClusterIP",
    },
  },
  // Ingress
  {
    apiVersion: "networking.k8s.io/v1",
    kind: "Ingress",
    metadata: {
      name: "webapp-ingress",
      namespace: "default",
      annotations: {
        "kubernetes.io/ingress.class": "alb",
        "alb.ingress.kubernetes.io/scheme": "internet-facing",
        "alb.ingress.kubernetes.io/target-type": "ip",
        "alb.ingress.kubernetes.io/healthcheck-path": "/health",
      },
    },
    spec: {
      rules: [{
        host: "webapp.example.com",
        http: {
          paths: [{
            path: "/",
            pathType: "Prefix",
            backend: {
              service: {
                name: "webapp-service",
                port: { number: 80 },
              },
            },
          }],
        },
      }],
    },
  }
);

Service Load Balancer Integration

The ALB controller also supports service-type load balancers:

apiVersion: v1
kind: Service
metadata:
  name: nlb-service
  namespace: default
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
    service.beta.kubernetes.io/aws-load-balancer-scheme: "internal"
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "tcp"
spec:
  selector:
    app: webapp
  ports:
    - port: 80
      targetPort: 80
      protocol: TCP
  type: LoadBalancer

Common Annotations

Ingress Annotations:

interface IngressAnnotations {
  /** Ingress class */
  "kubernetes.io/ingress.class": "alb";
  /** Load balancer scheme */
  "alb.ingress.kubernetes.io/scheme": "internet-facing" | "internal";
  /** Target type */
  "alb.ingress.kubernetes.io/target-type": "ip" | "instance";
  /** Listen ports */
  "alb.ingress.kubernetes.io/listen-ports"?: string;
  /** SSL certificate ARN */
  "alb.ingress.kubernetes.io/certificate-arn"?: string;
  /** SSL policy */
  "alb.ingress.kubernetes.io/ssl-policy"?: string;
  /** Health check path */
  "alb.ingress.kubernetes.io/healthcheck-path"?: string;
  /** Health check interval */
  "alb.ingress.kubernetes.io/healthcheck-interval-seconds"?: string;
  /** Health check timeout */
  "alb.ingress.kubernetes.io/healthcheck-timeout-seconds"?: string;
  /** Success codes */
  "alb.ingress.kubernetes.io/success-codes"?: string;
  /** Load balancer attributes */
  "alb.ingress.kubernetes.io/load-balancer-attributes"?: string;
  /** Target group attributes */
  "alb.ingress.kubernetes.io/target-group-attributes"?: string;
  /** Subnets */
  "alb.ingress.kubernetes.io/subnets"?: string;
  /** Security groups */
  "alb.ingress.kubernetes.io/security-groups"?: string;
  /** Tags */
  "alb.ingress.kubernetes.io/tags"?: string;
}

Service Annotations:

interface ServiceAnnotations {
  /** Load balancer type */
  "service.beta.kubernetes.io/aws-load-balancer-type": "nlb" | "alb";
  /** Load balancer scheme */
  "service.beta.kubernetes.io/aws-load-balancer-scheme": "internet-facing" | "internal";
  /** Backend protocol */
  "service.beta.kubernetes.io/aws-load-balancer-backend-protocol": "tcp" | "http" | "https";
  /** Cross zone load balancing */
  "service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled": "true" | "false";
  /** SSL certificate */
  "service.beta.kubernetes.io/aws-load-balancer-ssl-cert"?: string;
  /** SSL ports */
  "service.beta.kubernetes.io/aws-load-balancer-ssl-ports"?: string;
  /** Connection draining timeout */
  "service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout"?: string;
  /** Connection idle timeout */
  "service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout"?: string;
  /** Additional resource tags */
  "service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags"?: string;
}

Best Practices

  1. Use Target Type IP: For better integration with Fargate and security groups
  2. Health Checks: Configure appropriate health check paths and intervals
  3. SSL Termination: Use ACM certificates for HTTPS termination
  4. Security Groups: Configure security groups appropriately for ingress traffic
  5. Resource Tags: Use tags for cost allocation and resource management
// Best practice example: Production-ready ingress
cluster.addManifest("ProdIngress", {
  apiVersion: "networking.k8s.io/v1",
  kind: "Ingress",
  metadata: {
    name: "prod-ingress",
    namespace: "production",
    annotations: {
      "kubernetes.io/ingress.class": "alb",
      "alb.ingress.kubernetes.io/scheme": "internet-facing",
      "alb.ingress.kubernetes.io/target-type": "ip",
      "alb.ingress.kubernetes.io/listen-ports": '[{"HTTPS": 443}]',
      "alb.ingress.kubernetes.io/certificate-arn": "arn:aws:acm:us-west-2:123456789012:certificate/12345678-1234-1234-1234-123456789012",
      "alb.ingress.kubernetes.io/ssl-policy": "ELBSecurityPolicy-TLS-1-2-2017-01",
      "alb.ingress.kubernetes.io/healthcheck-path": "/health",
      "alb.ingress.kubernetes.io/healthcheck-interval-seconds": "30",
      "alb.ingress.kubernetes.io/healthcheck-timeout-seconds": "5",
      "alb.ingress.kubernetes.io/success-codes": "200",
      "alb.ingress.kubernetes.io/load-balancer-attributes": "idle_timeout.timeout_seconds=60,routing.http2.enabled=true",
      "alb.ingress.kubernetes.io/tags": "Environment=production,Application=webapp",
    },
  },
  spec: {
    rules: [{
      host: "api.example.com",
      http: {
        paths: [{
          path: "/",
          pathType: "Prefix", 
          backend: {
            service: {
              name: "api-service",
              port: { number: 80 },
            },
          },
        }],
      },
    }],
  },
});