Create an ACK capability - Amazon EKS
PrerequisitesChoose your toolWhat happens when you create an ACK capabilityACK capability configuration optionsNext steps
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Create an ACK capability

This chapter explains how to create an ACK capability on your Amazon EKS cluster.

Prerequisites

Before creating an ACK capability, ensure you have:

  • An Amazon EKS cluster

  • An IAM Capability Role with permissions for ACK to manage AWS resources

  • Sufficient IAM permissions to create capability resources on EKS clusters

  • The appropriate CLI tool installed and configured, or access to the EKS Console

For instructions on creating the IAM Capability Role, see Amazon EKS capability IAM role.

Important

ACK is an infrastructure management capability that grants the ability to create, modify, and delete AWS resources. This is an admin-scoped capability that should be carefully controlled. Anyone with permission to create Kubernetes resources in your cluster can effectively create AWS resources through ACK, subject to the IAM Capability Role permissions. The IAM Capability Role you provide determines which AWS resources ACK can create and manage. For guidance on creating an appropriate role with least-privilege permissions, see Amazon EKS capability IAM role and Security considerations for EKS Capabilities.

Choose your tool

You can create an ACK capability using the AWS Management Console, AWS CLI, or eksctl:

What happens when you create an ACK capability

When you create an ACK capability:

  1. EKS creates the ACK capability service and configures it to monitor and manage resources in your cluster

  2. Custom Resource Definitions (CRDs) are installed in your cluster

  3. An access entry is automatically created for your IAM Capability Role with capability-specific access entry policies that grant baseline Kubernetes permissions (see Security considerations for EKS Capabilities)

  4. The capability assumes the IAM Capability Role you provide

  5. ACK begins watching for its custom resources in your cluster

  6. The capability status changes from CREATING to ACTIVE

Once active, you can create ACK custom resources in your cluster to manage AWS resources.

Note

The automatically created access entry includes the AmazonEKSACKPolicy which grants ACK permissions to manage AWS resources. Some ACK resources that reference Kubernetes secrets (such as RDS databases with passwords) require additional access entry policies. To learn more about access entries and how to configure additional permissions, see Security considerations for EKS Capabilities.

ACK capability configuration options

ACK capabilities accept optional type-specific settings in the ack object of the capability configuration. These settings are optional. If you omit the configuration when you create a capability, cross-namespace references are disabled and all supported ACK service controllers run. You can set these options when you create a capability with the AWS Management Console, the AWS CLI, the AWS API, or AWS CloudFormation, and you can change them later with the update-capability command. For the steps to set these options at creation, see Create an ACK capability using the AWS CLI or Create an ACK capability using the Console. To change them on an existing capability, see Update ACK capability configuration.

The ack configuration object supports the following fields.

Field Type Description

enableCrossNamespace

Boolean

Controls whether ACK controllers resolve resource references to resources in a different Kubernetes namespace. Cross-namespace references are disabled by default. Set this field to true if you want references to resolve across namespaces. When the field is false, references must stay in the same namespace, and ACK reports out-of-namespace references as unresolved. When you create a capability without this field, the capability is created with the field set to false, and describe-capability returns false. For more information, see Cross-namespace resource references.

disabledServices

Array of strings

A list of ACK service names whose controllers are turned off for this capability, for example s3, ec2, or iam. The controller for a disabled service does not run, and resources of that service are not reconciled until you re-enable the service by removing it from the list. Each service name is lowercase alphanumeric and is 1–63 characters long. The list can contain up to 200 service names. When you create a capability without this field or with an empty list, all supported ACK service controllers run.
Note

Capabilities that were resolving cross-namespace references before enableCrossNamespace became available have the field set to true, so their behavior doesn’t change. Capabilities that you create now have cross-namespace references disabled unless you set the field to true.

Whether the capability installs a disabled service’s custom resource definitions (CRDs) depends on when you turn the service off:

  • If you turn a service off when you create the capability, the capability doesn’t install that service’s CRDs at all.

  • If you turn a service off after creation, the CRDs that the capability already installed remain in your cluster.

Shared CRDs in the services.k8s.aws group are always installed and can’t be turned off.

Turning services off is how you run the capability alongside ACK controllers that you manage yourself, either while you migrate to the capability one service at a time, or to keep a particular service self-managed for the long term. For the recommended procedure, see Coexist with self-managed controllers (recommended).

Note

On update-capability, disabledServices replaces the previous list instead of merging with it:

  • Omit the field to leave the previous list unchanged.

  • Specify a list to replace the previous list entirely, so include every service that you want turned off.

  • To turn all services back on, specify an empty list.

To turn a single service back on, specify the list of services that you want to remain turned off, without that service.

Note

A service name that doesn’t correspond to a supported ACK service is ignored rather than rejected. The request succeeds and the name is stored, but no service is turned off for it. As a result, a misspelled name silently leaves that service running. Check your spelling carefully, because describe-capability returns the list exactly as you supplied it and doesn’t identify unrecognized names.

To confirm that a service is actually turned off, verify that its resources are no longer reconciled. A resource that you create for a turned-off service gets no status conditions at all, and no AWS resource is created for it.

Important

Turning off a service doesn’t delete anything, and AWS doesn’t check whether the capability is currently managing resources of that service before turning it off. The Kubernetes custom resources and the AWS resources that they represent both remain, but nothing reconciles them, so the AWS resources can drift from the state that’s declared in your cluster.

Neither retention setting applies while a service is turned off:

  • deletePropagationPolicy is set on the capability and takes effect only when you delete the capability.

  • The services.k8s.aws/deletion-policy annotation is set on an individual resource and takes effect only when a running controller processes the deletion of that Kubernetes resource. For more information, see ACK considerations for EKS.

If you delete a Kubernetes resource while its service is turned off, no controller is running to process the resource’s finalizer. The resource stays in the Terminating state indefinitely and its AWS resource is never deleted, even if you set services.k8s.aws/deletion-policy to delete. Re-enable the service before you delete its resources, or delete the resources before you turn the service off. To recover a resource that is already stuck, see Troubleshoot issues with ACK capabilities.

Creating a resource while its service is turned off also has no effect, because no controller processes it. No AWS resource is created, and the Kubernetes resource stays unreconciled until you re-enable the service.

Next steps

After creating the ACK capability: