DOCSEARCHbyAlgolia
Submit Docs

AWS Controllers for Kubernetes (ACK) Documentation

repository·main·Indexed 25 days ago

https://github.com/aws-controllers-k8s/community

AWS Controllers for Kubernetes (ACK) is an open-source project that extends the Kubernetes API to manage AWS resources. It allows developers to provision and manage AWS services, such as RDS, SQS, and S3, using standard Kubernetes manifests and Custom Resource Definitions (CRDs). The documentation covers installation via Helm, the resource lifecycle, deprecation policies, and a list of available service controllers.

Tokens
66.2K
Snippets
166
Records
296
Agent score
82%

What's inside AWS Controllers for Kubernetes (ACK)

  1. Overview of AWS Controllers for Kubernetes (ACK)

    main
    AWS Controllers for Kubernetes (ACK) allows you to define and manage AWS service resources directly from a Kubernetes cluster using Custom Resource Definitions (CRDs) and custom controllers. This enables you to provision managed services like databases, message queues, and object stores as part of your Kubernetes application lifecycle, providing a unified way to manage applications and their AWS dependencies.

  2. Understand ACK Resource Definition and API Inference

    main

    ACK resources are automatically generated from AWS API model files (JSON files containing Actions and Shapes). The code generator identifies which AWS operations become Kubernetes Custom Resource Definitions (CRDs) by looking for operations that start with Create followed by a singular noun (e.g., CreateBucket becomes a Bucket resource).

    An ACK resource consists of two primary parts:

    1. Spec: Defines the desired state, derived from the Input shape of the Create operation.
    2. Status: Defines the observed state, derived from the Output shape of the Create operation.

    The OpenAPIv3 Validating Schema for these CRDs is generated using the controller-gen crd CLI command.

  3. Understand the ACK release deliverables

    main

    ACK releases consist of two primary deliverables shipped to users:

    1. Controller container image: The packaged controller used in Kubernetes environments.
    2. Helm chart release: The package used for deploying the controller via Helm.

    Container images are built using a base image defined in the project's code (linked to the code-generator Dockerfile) and environment variables/images defined in the test-infra Prow jobs.

  4. Understand the relationship between ACK and cdk8s

    main

    ACK and cdk8s are complementary tools:

    • cdk8s is a framework used to define Kubernetes applications and reusable abstractions (including Custom Resources) using programming languages.
    • ACK controllers watch for specific Custom Resources (CRs).

    Workflow: You can use cdk8s to generate the Kubernetes resources, and ACK will then use those resources to provision the corresponding AWS infrastructure.

  5. Understand the IAM Role Selector design

    main

    The IAM Role Selector is a proposed redesign of the current Cross Account Resource Management (CARM) mechanism in AWS Controllers for Kubernetes (ACK). While CARM was focused on cross-account management, the IAM Role Selector is designed for general "multi-role" usage, allowing different resources to interact with AWS services using different IAM roles.

    Key Improvements over CARM:

    • Typed Configuration: Moves away from untyped ConfigMaps and annotations to improve tooling support and error feedback.
    • Dynamic Selection: Replaces hard-coded namespace mappings with selectors, allowing for more dynamic configuration.
    • Simplified Semantics: Removes the confusing requirement of mapping roles to arbitrary "account ID" strings.

    Core Requirements:

    • Feature Parity with CARM: Supports mapping IAM roles to specific namespaces and scoping roles to specific ACK services.
    • Role Chaining: Supports multi-role assumption/role chaining for both cross-account and same-account usage.
    • Extensibility: Designed to eventually support resource-level IAM role selection (though this is out of scope for the initial implementation).

  7. Understand the Kubernetes Resource Model (KRM) in ACK

    main

    ACK resources follow the Kubernetes Resource Model (KRM). An ACK Object consists of metadata and a Spec field representing the desired state.

    An Object includes:

    • GroupVersionKind (GVK): Defines the API version and resource type (e.g., s3.services.k8s.aws/v1alpha1:Bucket).
    • Metadata: Contains the Name, Namespace, Labels, and Annotations.
    • Spec: A struct containing the desired state of the resource. Fields in the Spec are mapped to AWS API parameters (e.g., Spec.Name might be passed to a CreateBucket API call).

    Users interact with these objects using YAML manifests via CLI tools like kubectl.

    apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: my-amazing-bucket
  annotations:
    pronounced-as: boo-kay
spec:
  name: my-amazing-bucket

  8. Understand ACK drift detection and remediation

    main

    ACK controllers detect 'drift'—when an actor other than the controller (such as a person or another program) modifies an AWS resource—by periodically comparing the actual state of the resource in AWS against the desired state defined in Kubernetes.

    By default, ACK controllers attempt to detect drift once every 10 hours after a resource has been marked with the ResourceSynced = true condition. If a difference is detected, the controller initiates a reconciliation loop to return the resource to its desired state.

  9. Understand the ACK platform code generation pipeline

    main

    The ACK platform uses a code generation pipeline to transform aws-sdk shapes into Kubernetes resources. The process involves several stages:

    1. API Inference: Discovering the structure of API resources and their relationships.
    2. Model Generation: The model command takes aws-sdk and generator.yaml (represented as ackgenconfig) as input to produce an ackmodel (serialized JSON).
    3. Code Generation: Downstream commands like apis and controller consume the ackmodel to generate the final Go code.

    Key terminology:

    • ackgenconfig: The internal representation of generator.yaml used as input to the code-generator.
    • ackmodel: The output of the API inference stage, containing discovered CRDs and fields.
    • shape: The original AWS SDK models, operations, and structs.

  10. Understand the ACK resource lifecycle

    main

    AWS Controllers for Kubernetes (ACK) allows you to manage AWS resources by describing their desired state using Kubernetes Custom Resources (CRs).

    The workflow follows these steps:

    1. Manifest Submission: A user issues a kubectl apply command with a manifest describing the AWS resource (e.g., Kind: s3.services.k8s.aws/Bucket).
    2. API Validation: The Kubernetes API server validates the user's permissions and the manifest's format, then stores the CR in etcd.
    3. Controller Notification: The specific ACK service controller (running as a Pod) is notified of the new CR.
    4. AWS Provisioning: The ACK controller calls the corresponding AWS API (e.g., S3 CreateBucket) to provision the resource.
    5. Status Update: The controller updates the CR's Status field in the Kubernetes API with information returned from the AWS API.

  11. Understand AWS credential determination in ACK

    main

    ACK service controllers use the aws-sdk-go library to communicate with AWS APIs. When a controller starts, it creates an aws-sdk-go Session object which automatically looks for credentials in a specific order:

    1. AWS_PROFILE: If set, the controller uses the specified profile from the configured credentials file.
    2. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: If both are set as environment variables, they are used.
    3. AWS_WEB_IDENTITY_TOKEN_FILE: If set, the controller loads credentials from the JSON web token (JWT) in the file pointed to by this variable. This is the standard mechanism for IAM Roles for Service Accounts (IRSA).
    4. Shared Credentials File: If no other method is found, the controller looks for a credentials file at the location specified by AWS_SHARED_CREDENTIALS_FILE (or $HOME/.aws/credentials if the variable is unset) and uses the [default] profile.

  12. Compare ACK EKS controller with Kubernetes Cluster API

    main

    The ACK service controller for EKS is not a replacement for Kubernetes Cluster API (CAPI). They serve different purposes:

    FeatureKubernetes Cluster API (CAPI)ACK EKS Controller
    Design GoalGeneric way to create K8s clusters anywhere.Built directly from the EKS API spec for AWS.
    Source of TruthInfrastructure (VPC, etc.) is managed via CAPI.Managed via AWS/EKS APIs.
    FlexibilityAbstracted for general Kubernetes clusters.Full EKS API flexibility (Managed Node Groups, Fargate).
    IAM ScopeRequires broad permissions (CAPA) to provision VPC, gateways, etc.Can be scoped to specific ACK controllers.
    ServicesOften relies on services running inside the cluster (metrics/logging).Can leverage AWS services like CloudWatch.