**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.
# EKS Capabilities
**Tip**
Get started: [Create ACK capability](create-ack-capability.md) \$1 [Create Argo CD capability](create-argocd-capability.md) \$1 [Create kro capability](create-kro-capability.md)
Amazon EKS Capabilities is a layered set of fully managed cluster features that help accelerate developer velocity and offload the complexity of building and scaling with Kubernetes. EKS Capabilities are Kubernetes-native features for declarative continuous deployment, AWS resource management, and Kubernetes resource authoring and orchestration, all fully managed by AWS. With EKS Capabilities, you can focus more on building and scaling your workloads, offloading the operational burden of these foundational platform services to AWS. These capabilities run within EKS rather than in your clusters, eliminating the need to install, maintain, and scale critical platform components on your worker nodes.
To get started, you can create one or more EKS Capabilities on a new or existing EKS cluster. To do this, you can use the AWS CLI, the AWS Management Console, EKS APIs, eksctl, or your preferred infrastructure-as-code tools. While EKS Capabilities are designed to work together, they are independent cloud resources that you can pick and choose based on your use case and requirements.
All Kubernetes versions supported by EKS are supported for EKS Capabilities.
**Note**
EKS Capabilities are available in all AWS commercial Regions where Amazon EKS is available. For a list of supported Regions, see [Amazon EKS endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/eks.html) in the AWS General Reference.
## Available Capabilities
### AWS Controllers for Kubernetes (ACK)
ACK enables the management of AWS resources using Kubernetes APIs, allowing you to create and manage S3 buckets, RDS databases, IAM roles, and other AWS resources using Kubernetes custom resources. ACK continuously reconciles your desired state with the actual state in AWS, correcting any drift over time in order to keep your system healthy and your resources configured as specified. You can manage AWS resources alongside your Kubernetes workloads using the same tools and workflows, with support for more than 50 AWS services including S3, RDS, DynamoDB, and Lambda. ACK supports cross-account and cross-region resource management, enabling complex multi-account, multi-cluster system management architectures. ACK supports read-only resources and read-only adoption, facilitating migration from other infrastructure as code tools into your Kubernetes-based systems.
[Learn more about ACK →](ack.md)
### Argo CD
Argo CD implements GitOps-based continuous deployment for your applications, using Git repositories as the source of truth for your workloads and system state. Argo CD automatically syncs application resources to your clusters from your Git repositories, detecting and remediating drift to ensure your deployed applications match your desired state. You can deploy and manage applications across multiple clusters from a single Argo CD instance, with automated deployment from Git repositories whenever changes are committed. Using Argo CD and ACK together provides a foundational GitOps system, simplifying workload dependency management as well as supporting whole-system designs including cluster and infrastructure management at scale. Argo CD integrates with AWS Identity Center for authentication and authorization, and provides a hosted Argo UI for visualizing application health and deployment status.
[Learn more about Argo CD →](argocd.md)
### kro (Kube Resource Orchestrator)
kro enables you to create custom Kubernetes APIs that compose multiple resources into higher-level abstractions, allowing platform teams to define reusable patterns for common resource combinations-cloud building blocks. With kro, you can compose both Kubernetes and AWS resources together into unified abstractions, using simple syntax to enable dynamic configurations and conditional logic. kro enables platform teams to provide self-service capabilities with appropriate guardrails, allowing developers to provision complex infrastructure using simple, purpose-built APIs while maintaining organizational standards and best practices. kro resources are simply Kubernetes resources, and are specified in Kubernetes manifests which can be stored in Git, or pushed to OCI-compatible registries like Amazon ECR for broad organizational distribution.
[Learn more about kro →](kro.md)
## Benefits of EKS Capabilities
EKS Capabilities are fully managed by AWS, eliminating the need for installation, maintenance, and scaling of foundational cluster services. AWS handles security patching, updates, and operational management, freeing your teams to focus on building with AWS rather than on cluster operations. Unlike traditional Kubernetes add-ons that consume cluster resources, capabilities run in EKS rather than on your worker nodes. This frees up cluster capacity and resources for your workloads while minimizing the operational burden of managing in-cluster controllers and other platform components.
With EKS Capabilities, you can manage deployments, AWS resources, custom Kubernetes resources, and compositions using native Kubernetes APIs and tools like `kubectl`. All capabilities operate in the context of your clusters, automatically detecting and correcting configuration drift in both application and cloud infrastructure resources. You can deploy and manage resources across multiple clusters, AWS accounts, and regions from a single control point, simplifying operations in complex, distributed environments.
EKS Capabilities are designed for GitOps workflows, providing declarative, version-controlled infrastructure and application management. Changes flow from Git through the system, providing audit trails, rollback capabilities, and collaboration workflows that integrate with your existing development practices. This Kubernetes-native approach means you don’t need to use multiple tools or manage infrastructure-as-code systems external to your clusters, and there is a single source of truth to refer to. Your desired state, defined in version-controlled Kubernetes declarative configuration, is continuously enforced across your environment.
## Pricing
With EKS Capabilities, there are no upfront commitments or minimum fees. You are charged for each capability resource for each hour it is active on your Amazon EKS cluster. Specific Kubernetes resources managed by EKS Capabilities are also billed at an hourly rate.
For current pricing information, see the [Amazon EKS pricing page](https://aws.amazon.com/eks/pricing/).
**Tip**
You can use AWS Cost Explorer and Cost and Usage Reports to track capability costs separately from other EKS charges. You can tag your capabilities with cluster name, capability type, and other details for cost allocation purposes.
## How EKS Capabilities Work
Each capability is an AWS resource that you create on your EKS cluster. Once created, the capability runs in EKS and is fully managed by AWS.
**Note**
You can create one capability resource of each type (Argo CD, ACK, and kro) for a given cluster. You cannot create multiple capability resources of the same type on the same cluster.
You interact with capabilities in your cluster using standard Kubernetes APIs and tools:
+ Use `kubectl` to apply Kubernetes custom resources
+ Use Git repositories as the source of truth for GitOps workflows
Some capabilities have additional tools supported. For example:
+ Use the Argo CD CLI to configure and manage repositories and clusters in your Argo CD capability
+ Use the Argo CD UI to visualize and manage applications managed by your Argo CD capability
Capabilities are designed to work together but are independent and fully opt-in. You can enable one, two, or all three capabilities based on your needs, and update your configuration as your requirements evolve.
All EKS Compute types are supported for use with EKS Capabilities. For more information, see [Manage compute resources by using nodes](eks-compute.md).
For security configuration and details on IAM roles, see [Security considerations for EKS Capabilities](capabilities-security.md). For multi-cluster architecture patterns, see [EKS Capabilities considerations](capabilities-considerations.md).
## Common Use Cases
**GitOps for Applications and Infrastructure**
Use Argo CD to deploy applications and operational components and ACK to manage cluster configurations and provision infrastructure, both from Git repositories. Your entire stack—applications, databases, storage, and networking—is defined as code and automatically deployed.
Example: A development team pushes changes to Git. Argo CD deploys the updated application, and ACK provisions a new RDS database with the correct configuration. All changes are auditable, reversible, and consistent across environments.
**Platform Engineering with Self-Service**
Use kro to create custom APIs that compose ACK and Kubernetes resources. Platform teams define approved patterns with guardrails. Application teams use simple, high-level APIs to provision complete stacks.
Example: A platform team creates a "WebApplication" API that provisions a Deployment, Service, Ingress, and S3 bucket. Developers use this API without needing to understand the underlying complexity or AWS permissions.
**Multi-Cluster Application Management**
Use Argo CD to deploy applications across multiple EKS clusters in different regions or accounts. Manage all deployments from a single Argo CD instance with consistent policies and workflows.
Example: Deploy the same application to development, staging, and production clusters across multiple regions. Argo CD ensures each environment stays in sync with its corresponding Git branch.
**Multi-Cluster Management**
Use ACK to define and provision EKS clusters, kro to customize cluster configurations with organizational standards, and Argo CD to manage cluster lifecycle and configuration. This provides end-to-end cluster management from creation through ongoing operations.
Example: Define EKS clusters using ACK and kro to provision and manage cluster infrastructure, defining organizational standards for networking, security policies, add-ons and other configuration. Use Argo CD to create and continuously manage clusters, configuration, and Kubernetes version updates across your fleet leveraging consistent standards and automated lifecycle management.
**Migrations and Modernization**
Simplify migration to EKS with native cloud resource provisioning and GitOps workflows. Use ACK to adopt existing AWS resources without recreating them, and Argo CD to operationalize workload deployments from Git.
Example: A team migrating from EC2 to EKS adopts their existing RDS databases and S3 buckets using ACK, then uses Argo CD to deploy containerized applications from Git. The migration path is clear, and operations are standardized from day one.
**Account and Regional Bootstrapping**
Automate infrastructure rollout across accounts and regions using Argo CD and ACK together. Define your infrastructure as code in Git, and let capabilities handle the deployment and management.
Example: A platform team maintains Git repositories defining standard account configurations—VPCs, IAM roles, RDS instances, and monitoring stacks. Argo CD deploys these configurations to new accounts and regions automatically, ensuring consistency and reducing manual setup time from days to minutes.
# Working with capability resources
This topic describes common operations for managing capability resources across all capability types.
## EKS capability resources
EKS capabilities are AWS resources that enable managed functionality on your Amazon EKS cluster. Capabilities run in EKS, eliminating the need to install and maintain controllers and other operational components on your worker nodes. Capabilities are created for a specific EKS cluster, and remain affiliated with that cluster for their entire lifecycle.
Each capability resource has:
+ A unique name within your cluster
+ A capability type (ACK, ARGOCD, or KRO)
+ An Amazon Resource Name (ARN), specifying both name and type
+ A capability IAM role
+ A status that indicates its current state
+ Configuration, both generic and specific to the capability type
## Understanding capability status
Capability resources have a status that indicates their current state. You can view capability status and health in the EKS console or using the AWS CLI.
**Console**:
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name.
1. Choose the **Capabilities** tab to view status for all capabilities.
1. For detailed health information, choose the **Observability** tab, then **Monitor cluster**, then the **Capabilities** tab.
** AWS CLI**:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-capability-name
```
### Capability statuses
**CREATING**: Capability is being set up. You can navigate away from the console—the capability will continue creating in the background.
**ACTIVE**: Capability is running and ready to use. If resources aren’t working as expected, check resource status and IAM permissions. See [Troubleshooting EKS Capabilities](capabilities-troubleshooting.md) for guidance.
**UPDATING**: Configuration changes are being applied. Wait for the status to return to `ACTIVE`.
**DELETING**: Capability is being removed from the cluster.
**CREATE\$1FAILED**: Setup encountered an error. Common causes include:
+ IAM role trust policy incorrect or missing
+ IAM role doesn’t exist or isn’t accessible
+ Cluster access issues
+ Invalid configuration parameters
Check the capability health section for specific error details.
**UPDATE\$1FAILED**: Configuration update failed. Check the capability health section for details and verify IAM permissions.
**Tip**
For detailed troubleshooting guidance, see:
[Troubleshooting EKS Capabilities](capabilities-troubleshooting.md) - General capability troubleshooting
[Troubleshoot issues with ACK capabilities](ack-troubleshooting.md) - ACK-specific issues
[Troubleshoot issues with Argo CD capabilities](argocd-troubleshooting.md) - Argo CD-specific issues
[Troubleshoot issues with kro capabilities](kro-troubleshooting.md) - kro-specific issues
## Create capabilities
To create a capability on your cluster, see the following topics:
+ [Create an ACK capability](create-ack-capability.md) – Create an ACK capability to manage AWS resources using Kubernetes APIs
+ [Create an Argo CD capability](create-argocd-capability.md) – Create an Argo CD capability for GitOps continuous delivery
+ [Create a kro capability](create-kro-capability.md) – Create a kro capability for resource composition and orchestration
## List capabilities
You can list all capability resources on a cluster.
### Console
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. View capability resources under **Managed capabilities**.
### AWS CLI
Use the `list-capabilities` command to view all capabilities on your cluster. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
aws eks list-capabilities \
--region region-code \
--cluster-name my-cluster
```
```
{
"capabilities": [
{
"capabilityName": "my-ack",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"type": "ACK",
"status": "ACTIVE",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-kro",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/kro/my-kro/abc123",
"type": "KRO",
"status": "ACTIVE",
"version": "v0.6.3",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-argocd",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/argocd/my-argocd/abc123",
"type": "ARGOCD",
"status": "ACTIVE",
"version": "3.1.8-eks-1",
"createdAt": "2025-11-21T08:22:28.486000-05:00",
"modifiedAt": "2025-11-21T08:22:28.486000-05:00"
}
]
}
```
## Describe a capability
Get detailed information about a specific capability, including its configuration and status.
### Console
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. Choose the capability you want to view from **Managed capabilities**.
1. View the capability details, including status, configuration, and creation time.
### AWS CLI
Use the `describe-capability` command to view detailed information. Replace *region-code* with the AWS Region that your cluster is in, replace *my-cluster* with the name of your cluster, and replace *capability-name* with the capability name (ack, argocd, or kro).
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
**Example output:**
```
{
"capability": {
"capabilityName": "my-ack",
"capabilityArn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"clusterName": "my-cluster",
"type": "ACK",
"roleArn": "arn:aws:iam::111122223333:role/AmazonEKSCapabilityACKRole",
"status": "ACTIVE",
"configuration": {},
"tags": {},
"health": {
"issues": []
},
"createdAt": "2025-11-19T17:11:30.242000-05:00",
"modifiedAt": "2025-11-19T17:11:30.242000-05:00",
"deletePropagationPolicy": "RETAIN"
}
}
```
## Update the configuration of a capability
You can update certain aspects of a capability’s configuration after creation. The specific configuration options vary by capability type.
**Note**
EKS capability resources are fully managed, including patching and version updates. Updating a capability will update resource configuration and will not result in version updates of the managed capability components.
### AWS CLI
Use the `update-capability` command to modify a capability:
```
aws eks update-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name \
--role-arn arn:aws:iam::[.replaceable]111122223333:role/NewCapabilityRole
```
**Note**
Not all capability properties can be updated after creation. Refer to the capability-specific documentation for details on what can be modified.
## Delete a capability
When you no longer need a capability on your cluster, you can delete the capability resource.
**Important**
**Delete cluster resources before deleting the capability.**
Deleting a capability resource does not automatically delete resources created through that capability:
All Kubernetes Custom Resource Definitions (CRDs) remain installed in your cluster.
ACK resources remain in your cluster, and corresponding AWS resources remain in your account
Argo CD Applications and their Kubernetes resources remain in your cluster
kro ResourceGraphDefinitions and instances remain in your cluster
You should delete these resources before deleting the capability to avoid orphaned resources.
You may optionally choose to retain AWS resources associated with ACK Kubernetes resources. See [ACK considerations](ack-considerations.md)
### Console
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. Select the capability you want to delete from the list of **Managed capabilities**.
1. Choose **Delete capability**.
1. In the confirmation dialog, type the name of the capability to confirm deletion.
1. Choose **Delete**.
### AWS CLI
Use the `delete-capability` command to delete a capability resource:
Replace *region-code* with the AWS Region that your cluster is in, replace *my-cluster* with the name of your cluster, and replace *capability-name* with the capability name to delete.
```
aws eks delete-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
## Next steps
+ [Capability Kubernetes resources](capability-kubernetes-resources.md) – Learn about the Kubernetes resources provided by each capability type
+ [ACK concepts](ack-concepts.md) – Understand ACK concepts and resource lifecycle
+ [Working with Argo CD](working-with-argocd.md) – Working with Argo CD capabilities for GitOps workflows
+ [kro concepts](kro-concepts.md) – Understand kro concepts and resource composition
# Capability Kubernetes resources
After you enable a capability on your cluster, you will most often interact with it by creating and managing Kubernetes custom resources in your cluster. Each capability provides its own set of custom resource definitions (CRDs) that extend the Kubernetes API with capability-specific functionality.
## Argo CD resources
When you enable the Argo CD capability, you can create and manage the following Kubernetes resources:
**Application**
Defines a deployment from a Git repository to a target cluster. `Application` resources specify the source repository, target namespace, and sync policy. You can create up to 1000 `Application` resources per Argo CD capability instance.
**ApplicationSet**
Generates multiple `Application` resources from templates, enabling multi-cluster and multi-environment deployments. `ApplicationSet` resources use generators to create `Application` resources dynamically based on cluster lists, Git directories, or other sources.
**AppProject**
Provides logical grouping and access control for `Application` resources. `AppProject` resources define which repositories, clusters, and namespaces `Application` resources can use, enabling multi-tenancy and security boundaries.
Example `Application` resource:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/org/repo
targetRevision: main
path: manifests
destination:
server: https://kubernetes.default.svc
namespace: production
```
For more information about Argo CD resources and concepts, see [Argo CD concepts](argocd-concepts.md).
## kro resources
When you enable the kro capability, you can create and manage the following Kubernetes resources:
**ResourceGraphDefinition (RGD)**
Defines a custom API that composes multiple Kubernetes and AWS resources into a higher-level abstraction. Platform teams create `ResourceGraphDefinition` resources to provide reusable patterns with guardrails.
**Custom resource instances**
After creating a `ResourceGraphDefinition` resource, you can create instances of the custom API defined by the `ResourceGraphDefinition`. kro automatically creates and manages the resources specified in the `ResourceGraphDefinition`.
Example `ResourceGraphDefinition` resource:
```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: web-application
spec:
schema:
apiVersion: v1alpha1
kind: WebApplication
spec:
name: string
replicas: integer
resources:
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
# ... deployment spec
- id: service
template:
apiVersion: v1
kind: Service
# ... service spec
```
Example `WebApplication` instance:
```
apiVersion: v1alpha1
kind: WebApplication
metadata:
name: my-web-app
namespace: default
spec:
name: my-web-app
replicas: 3
```
When you apply this instance, kro automatically creates the `Deployment` and `Service` resources defined in the `ResourceGraphDefinition`.
For more information about kro resources and concepts, see [kro concepts](kro-concepts.md).
## ACK resources
When you enable the ACK capability, you can create and manage AWS resources using Kubernetes custom resources. ACK provides over 200 CRDs for more than 50 AWS services, allowing you to define AWS resources alongside your Kubernetes workloads, and manage dedicated AWS infrastructure resources with Kubernetes.
Examples of ACK resources:
**S3 Bucket**
`Bucket` resources create and manage Amazon S3 buckets with versioning, encryption, and lifecycle policies.
**RDS DBInstance**
`DBInstance` resources provision and manage Amazon RDS database instances with automated backups and maintenance windows.
**DynamoDB Table**
`Table` resources create and manage DynamoDB tables with provisioned or on-demand capacity.
**IAM Role**
`Role` resources define IAM roles with trust policies and permission policies for AWS service access.
**Lambda Function**
`Function` resources create and manage Lambda functions with code, runtime, and execution role configuration.
Example specification of a `Bucket` resource:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-app-bucket
spec:
name: my-unique-bucket-name-12345
versioning:
status: Enabled
encryption:
rules:
- applyServerSideEncryptionByDefault:
sseAlgorithm: AES256
```
For more information about ACK resources and concepts, see [ACK concepts](ack-concepts.md).
## Resource limits
EKS Capabilities have the following resource limits:
**Argo CD usage limits**:
+ Maximum 1000 `Application` resources per Argo CD capability instance
+ Maximum 100 remote clusters configured per Argo CD capability instance
**Resource configuration limits**:
+ Maximum 150 Kubernetes resources per `Application` resource in Argo CD
+ Maximum 64 Kubernetes resources per `ResourceGraphDefinition` in kro
**Note**
These limits apply to the number of resources managed by each capability instance. If you need higher limits, you can deploy capabilities across multiple clusters.
## Next steps
For capability-specific tasks and advanced configuration, see the following topics:
+ [ACK concepts](ack-concepts.md) – Understand ACK concepts and resource lifecycle
+ [Working with Argo CD](working-with-argocd.md) – Working with Argo CD capabilities for GitOps workflows
+ [kro concepts](kro-concepts.md) – Understand kro concepts and resource composition
# EKS Capabilities considerations
This topic covers important considerations for using EKS Capabilities, including access control design, choosing between EKS Capabilities and self-managed solutions, architectural patterns for multi-cluster deployments, and operational best practices.
## Capability IAM roles and Kubernetes RBAC
Each EKS capability resource has a configured capability IAM role. The capability role is used to grant AWS service permissions for EKS capabilities to act on your behalf. For example, to use the EKS Capability for ACK to manage Amazon S3 Buckets, you will grant S3 Bucket administrative permissions to the capability, enabling it to create and manage buckets.
Once the capability is configured, S3 resources in AWS can be created and managed with Kubernetes custom resources in your cluster. Kubernetes RBAC is the in-cluster access control mechanism for determining which users and groups can create and manage those custom resources. For example, grant specific Kubernetes RBAC users and groups permissions to create and manage `Bucket` resources in namespaces you choose.
In this way, IAM and Kubernetes RBAC are two halves of the end-to-end access control system that governs permissions related to EKS Capabilities and resources. It’s important to design the right combination of IAM permissions and RBAC access policies for your use case.
For additional information on capability IAM roles and Kubernetes permissions, see [Security considerations for EKS Capabilities](capabilities-security.md).
## Multi-cluster architecture patterns
When deploying capabilities across multiple clusters, consider these common architectural patterns:
**Hub and Spoke with centralized management**
Run all three capabilities in a centrally managed cluster to orchestrate workloads and manage cloud infrastructure across multiple workload clusters.
+ Argo CD on the management cluster deploys applications to workload clusters in different regions or accounts
+ ACK on the management cluster provisions AWS resources (RDS, S3, IAM) for all clusters
+ kro on the management cluster creates portable platform abstractions that work across all clusters
This pattern centralizes workload and cloud infrastructure management, and can simplify operations for organizations managing many clusters.
**Decentralized GitOps**
Workloads and cloud infrastructure are managed by capabilities on the same cluster where workloads are running.
+ Argo CD manages application resources on the local cluster.
+ ACK resources are used for cluster and workload needs.
+ kro platform abstractions are installed and orchestrate local resources.
This pattern decentralizes operations, with teams managing their own dedicated platform services in one or more clusters.
**Hub and Spoke with Hybrid ACK Deployment**
Combine centralized and decentralized models, with centralized application deployments and resource management based on scope and ownership.
+ Hub cluster:
+ Argo CD manages GitOps deployments to the local cluster and all remote workload clusters
+ ACK is used on the management cluster for admin-scoped resources (production databases, IAM roles, VPCs)
+ kro is used on the management cluster for reusable platform abstractions
+ Spoke clusters:
+ Workloads are managed via Argo CD on the centralized hub cluster
+ ACK is used locally for workload-scoped resources (S3 buckets, ElastiCache instances, SQS queues)
+ kro is used locally for resource compositions and building block patterns
This pattern separates concerns—platform teams manage critical infrastructure centrally on management clusters, optionally including workload clusters, while application teams specify and manage cloud resources alongside workloads.
**Choosing a Pattern**
Consider these factors when selecting an architecture:
+ **Organizational structure**: Centralized platform teams favor hub patterns; decentralized teams may prefer per-cluster capabilities
+ **Resource scope**: Admin-scoped resources (databases, IAM) often benefit from central management; workload resources (buckets, queues) can be managed locally
+ **Self-service**: Centralized platform teams can author and distribute prescriptive custom resources to enable safe self-service of cloud resources for common workload needs
+ **Cluster fleet management**: Centralized management clusters provide a customer-owned control plane for EKS cluster fleet management, along with other admin-scoped resources
+ **Compliance requirements**: Some organizations require centralized control for audit and governance
+ **Operational complexity**: Fewer capability instances simplify operations but may create bottlenecks
**Note**
You can start with one pattern and evolve to another as your platform matures. Capabilities are independent—you can deploy them differently across clusters based on your needs.
## Comparing EKS Capabilities to self-managed solutions
EKS Capabilities provide fully managed experiences for popular Kubernetes tools and controllers that run in EKS. This differs from self-managed solutions, which you install and operate in your cluster.
### Key Differences
**Deployment and management**
AWS fully manages EKS Capabilities with no installation, configuration, or maintenance of component software required. AWS installs and manages all required Kubernetes Custom Resource Definitions (CRDs) in the cluster automatically.
With self-managed solutions, you install and configure cluster software using Helm charts, kubectl, or other operators. You have full control over the software lifecycle and runtime configuration of your self-managed solutions, providing customizations at any layer of the solution.
**Operations and maintenance**
AWS manages patching and other software lifecycle operations for EKS Capabilities, with automatic updates and security patches. EKS Capabilities are integrated with AWS features for streamlined configurations, provides built-in highly availability and fault tolerance, and eliminates in-cluster troubleshooting of controller workloads.
Self-managed solutions require you to monitor component health and logs, apply security patches and version updates, configure high availability with multiple replicas and pod disruption budgets, troubleshoot and remediate controller workload issues, and manage releases and versions. You have full control over your deployments, but this often requires bespoke solutions for private cluster access and other integrations which must align with organizational standards and security compliance requirements.
**Resource consumption**
EKS Capabilities run in EKS and off of your clusters, freeing up node resources and cluster resources. Capabilities do not use cluster workload resources, do not consume CPU or memory on your worker nodes, scale automatically, and have minimal impact on cluster capacity planning.
Self-managed solutions run controllers and other components on your worker nodes, directly consuming worker node resources, cluster IPs, and other cluster resources. Managing cluster services requires capacity planning for their workloads, and requires planning and configuration of resource requests and limits to manage scaling and high availability requirements.
**Feature support**
As fully managed service features, EKS Capabilities are by their nature opinionated compared to self-managed solutions. While capabilities will support most features and use cases, there will be a difference in coverage when compared to self-managed solutions.
With self-managed solutions, you fully control the configuration, optional features, and other aspects of functionality for your software. You may choose to run your own custom images, customize all aspects of configuration, and fully control your self-managed solution functionality.
**Cost Considerations**
Each EKS capability resource has a related hourly cost, which differs based upon the capability type. Cluster resources managed by the capability also have an associated hourly cost with their own pricing. For more information, see [Amazon EKS pricing](https://aws.amazon.com/eks/pricing/).
Self-managed solutions have no direct costs related to AWS charges, but you pay for cluster compute resources used by controllers and related workloads. Beyond node and cluster resource consumption, the full cost of ownership with self-managed solutions includes operational overhead and expense of maintenance, troubleshooting, and support.
### Choosing between EKS Capabilities and self-managed solutions
**EKS Capabilities** Consider this choice when you want to reduce operational overhead and focus on differentiated value in your software and systems, rather than cluster platform operations for foundational requirements. Use EKS Capabilities when you want to minimize the operational burden of security patches and software lifecycle management, free up node and cluster resources for application workloads, simplify configuration and security management, and benefit from AWS support coverage. EKS Capabilities are ideal for most production use cases and are the recommended approach for new deployments.
**Self-managed solutions** Consider this choice when you require specific Kubernetes resource API versions, custom controller builds, have existing automation and tooling built around self-managed deployments, or need deep customization of controller runtime configurations. Self-managed solutions provide flexibility for specialized use cases, and you have complete control over your deployment and runtime configuration.
**Note**
EKS Capabilities can coexist in your cluster with self-managed solutions, and step-wise migrations are possible to achieve.
### Capability-Specific Comparisons
For detailed comparisons including capability-specific features, upstream differences, and migration paths see:
+ [Comparing EKS Capability for ACK to self-managed ACK](ack-comparison.md)
+ [Comparing EKS Capability for Argo CD to self-managed Argo CD](argocd-comparison.md)
+ [Comparing EKS Capability for kro to self-managed kro](kro-comparison.md)
# Deploy AWS resources from Kubernetes with AWS Controllers for Kubernetes (ACK)
AWS Controllers for Kubernetes (ACK) lets you define and manage AWS service resources directly from Kubernetes. With AWS Controllers for Kubernetes (ACK), you can manage workload resources and cloud infrastructure using Kubernetes custom resources, right alongside your application workloads using familiar Kubernetes APIs and tools.
With EKS Capabilities, ACK is fully managed by AWS, eliminating the need to install, maintain, and scale ACK controllers on your clusters.
## How ACK Works
ACK translates Kubernetes custom resource specifications into AWS API calls. When you create, update, or delete a Kubernetes custom resource representing an AWS service resource, ACK makes the required AWS API calls to create, update, or delete the AWS resource.
Each AWS resource supported by ACK has its own custom resource definition (CRD) that defines the Kubernetes API schema for specifying its configuration. For example, ACK provides CRDs for S3 including buckets, bucket policies, and other S3 resources.
ACK continuously reconciles the state of your AWS resources with the desired state defined in your Kubernetes custom resources. If a resource drifts from its desired state, ACK detects this and takes corrective action to bring it back into alignment. Changes to Kubernetes resources are immediately reflected in AWS resource state, while passive drift detection and remediation of upstream AWS resource changes can take as long as 10 hours (the resync period), but will typically occur much sooner.
**Example S3 Bucket resource manifest**
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-ack-bucket
spec:
name: my-unique-bucket-name
```
When you apply this custom resource to your cluster, ACK creates an Amazon S3 bucket in your account if it does not yet exist. Subsequent changes to this resource, for example specifying a non-default storage tier or adding a policy, will be applied to the S3 resource in AWS. When this resource is deleted from the cluster, the S3 bucket in AWS is deleted by default.
## Benefits of ACK
ACK provides Kubernetes-native AWS resource management, allowing you to manage AWS resources using the same Kubernetes APIs and tools you use for your applications. This unified approach simplifies your infrastructure management workflow by eliminating the need to switch between different tools or learn separate infrastructure-as-code systems. You define your AWS resources declaratively in Kubernetes manifests, enabling GitOps workflows and infrastructure as code practices that integrate seamlessly with your existing development processes.
ACK continuously reconciles the desired state of your AWS resources with their actual state, correcting drift and ensuring consistency across your infrastructure. This continuous reconciliation means that imperative out-of-band changes to AWS resources are automatically reverted to match your declared configuration, maintaining the integrity of your infrastructure as code. You can configure ACK to manage resources across multiple AWS accounts and regions, enabling complex multi-account architectures with no additional tooling.
For organizations migrating from other infrastructure management tools, ACK supports resource adoption, allowing you to bring existing AWS resources under ACK management without recreating them. ACK also provides read-only resources for AWS resource observation without modification access, and annotations to optionally retain AWS resources even when the Kubernetes resource is deleted from the cluster.
To learn more and get started with the EKS Capability for ACK, see [ACK concepts](ack-concepts.md) and [ACK considerations for EKS](ack-considerations.md).
## Supported AWS Services
ACK supports a wide range of AWS services, including but not limited to:
+ Amazon EC2
+ Amazon S3
+ Amazon RDS
+ Amazon DynamoDB
+ Amazon ElastiCache
+ Amazon EKS
+ Amazon SQS
+ Amazon SNS
+ AWS Lambda
+ AWS IAM
All AWS services listed as Generally Available upstream are supported by the EKS Capability for ACK. Refer to the [full list of AWS services supported](https://aws-controllers-k8s.github.io/community/docs/community/services/) for details.
## Integration with Other EKS Managed Capabilities
ACK integrates with other EKS Managed Capabilities.
+ **Argo CD**: Use Argo CD to manage the deployment of ACK resources across multiple clusters, enabling GitOps workflows for your AWS infrastructure.
+ ACK extends the benefits of GitOps when paired with ArgoCD, but ACK does not require integration with git.
+ **kro (Kube Resource Orchestrator)**: Use kro to compose complex resources from ACK resources, creating higher-level abstractions that simplify resource management.
+ You can create composite custom resources with kro that define both Kubernetes resources and AWS resources. Team members can use these custom resources to quickly deploy complex applications.
## Getting Started with ACK
To get started with the EKS Capability for ACK:
1. Create and configure an IAM Capability Role with the necessary permissions for ACK to manage AWS resources on your behalf.
1. [Create an ACK capability resource](create-ack-capability.md) on your EKS cluster through the AWS Console, AWS CLI, or your preferred infrastructure as code tool.
1. Apply Kubernetes custom resources to your cluster to start managing your AWS resources in Kubernetes.
# 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](capability-role.md).
**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](capability-role.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
## Choose your tool
You can create an ACK capability using the AWS Management Console, AWS CLI, or eksctl:
+ [Create an ACK capability using the Console](ack-create-console.md) - Use the Console for a guided experience
+ [Create an ACK capability using the AWS CLI](ack-create-cli.md) - Use the AWS CLI for scripting and automation
+ [Create an ACK capability using eksctl](ack-create-eksctl.md) - Use eksctl for a Kubernetes-native experience
## 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
1. Custom Resource Definitions (CRDs) are installed in your cluster
1. 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](capabilities-security.md))
1. The capability assumes the IAM Capability Role you provide
1. ACK begins watching for its custom resources in your cluster
1. 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](capabilities-security.md).
## Next steps
After creating the ACK capability:
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and get started with AWS resources
+ [ACK concepts](ack-concepts.md) - Learn about reconciliation, field exports, and resource adoption patterns
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions and multi-account patterns
# Create an ACK capability using the Console
This topic describes how to create an AWS Controllers for Kubernetes (ACK) capability using the AWS Management Console.
## Create the ACK capability
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. In the left navigation, choose ** AWS Controllers for Kubernetes (ACK)**.
1. Choose **Create AWS Controllers for Kubernetes capability**.
1. For **IAM Capability Role**:
+ If you already have an IAM Capability Role, select it from the dropdown
+ If you need to create a role, choose **Create admin role**
This opens the IAM console in a new tab with pre-populated trust policy and the `AdministratorAccess` managed policy. You can unselect this policy and add other permissions if you prefer.
After creating the role, return to the EKS console and the role will be automatically selected.
**Important**
The suggested `AdministratorAccess` policy grants broad permissions and is intended to streamline getting started. For production use, replace this with a custom policy that grants only the permissions needed for the specific AWS services you plan to manage with ACK. For guidance on creating least-privilege policies, see [Configure ACK permissions](ack-permissions.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
1. Choose **Create**.
The capability creation process begins.
## Verify the capability is active
1. On the **Capabilities** tab, view the ACK capability status.
1. Wait for the status to change from `CREATING` to `ACTIVE`.
1. Once active, the capability is ready to use.
For information about capability statuses and troubleshooting, see [Working with capability resources](working-with-capabilities.md).
## Verify custom resources are available
After the capability is active, verify that ACK custom resources are available in your cluster.
**Using the console**
1. Navigate to your cluster in the Amazon EKS console
1. Choose the **Resources** tab
1. Choose **Extensions**
1. Choose **CustomResourceDefinitions**
You should see a number of CRDs listed for AWS resources.
**Using kubectl**
```
kubectl api-resources | grep services.k8s.aws
```
You should see a number of APIs listed for AWS resources.
**Note**
The capability for AWS Controllers for Kubernetes will install a number of CRDs for a variety of AWS resources.
## Next steps
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and get started
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions for other AWS services
+ [Working with capability resources](working-with-capabilities.md) - Manage your ACK capability resource
# Create an ACK capability using the AWS CLI
This topic describes how to create an AWS Controllers for Kubernetes (ACK) capability using the AWS CLI.
## Prerequisites
+ ** AWS CLI** – Version `2.12.3` or later. To check your version, run `aws --version`. For more information, see [Installing](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the AWS Command Line Interface User Guide.
+ ** `kubectl` ** – A command line tool for working with Kubernetes clusters. For more information, see [Set up `kubectl` and `eksctl`](install-kubectl.md).
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
Attach the `AdministratorAccess` managed policy to the role:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**Important**
The suggested `AdministratorAccess` policy grants broad permissions and is intended to streamline getting started. For production use, replace this with a custom policy that grants only the permissions needed for the specific AWS services you plan to manage with ACK. For guidance on creating least-privilege policies, see [Configure ACK permissions](ack-permissions.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
## Step 2: Create the ACK capability
Create the ACK capability resource on your cluster. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--delete-propagation-policy RETAIN
```
The command returns immediately, but the capability takes some time to become active as EKS creates the required capability infrastructure and components. EKS will install the Kubernetes Custom Resource Definitions related to this capability in your cluster as it is being created.
**Note**
If you receive an error that the cluster doesn’t exist or you don’t have permissions, verify:
The cluster name is correct
Your AWS CLI is configured for the correct region
You have the required IAM permissions
## Step 3: Verify the capability is active
Wait for the capability to become active. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--query 'capability.status' \
--output text
```
The capability is ready when the status shows `ACTIVE`. Don’t continue to the next step until the status is `ACTIVE`.
You can also view the full capability details:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
```
## Step 4: Verify custom resources are available
After the capability is active, verify that ACK custom resources are available in your cluster:
```
kubectl api-resources | grep services.k8s.aws
```
You should see a number of APIs listed for AWS resources.
**Note**
The capability for AWS Controllers for Kubernetes will install a number of CRDs for a variety of AWS resources.
## Next steps
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and get started
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions for other AWS services
+ [Working with capability resources](working-with-capabilities.md) - Manage your ACK capability resource
# Create an ACK capability using eksctl
This topic describes how to create an AWS Controllers for Kubernetes (ACK) capability using eksctl.
**Note**
The following steps require eksctl version `0.220.0` or later. To check your version, run `eksctl version`.
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
Attach the `AdministratorAccess` managed policy to the role:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**Important**
The suggested `AdministratorAccess` policy grants broad permissions and is intended to streamline getting started. For production use, replace this with a custom policy that grants only the permissions needed for the specific AWS services you plan to manage with ACK. For guidance on creating least-privilege policies, see [Configure ACK permissions](ack-permissions.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
**Important**
This policy grants permissions for S3 bucket management with `"Resource": "*"`, which allows operations on all S3 buckets.
For production use: \$1 Restrict the `Resource` field to specific bucket ARNs or name patterns \$1 Use IAM condition keys to limit access by resource tags \$1 Grant only the minimum permissions needed for your use case
For other AWS services, see [Configure ACK permissions](ack-permissions.md).
Attach the policy to the role:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ACKS3Policy
```
## Step 2: Create the ACK capability
Create the ACK capability using eksctl. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
eksctl create capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--ack-service-controllers s3
```
**Note**
The `--ack-service-controllers` flag is optional. If omitted, ACK enables all available controllers. For better performance and security, consider enabling only the controllers you need. You can specify multiple controllers: `--ack-service-controllers s3,rds,dynamodb`
The command returns immediately, but the capability takes some time to become active.
## Step 3: Verify the capability is active
Check the capability status:
```
eksctl get capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack
```
The capability is ready when the status shows `ACTIVE`.
## Step 4: Verify custom resources are available
After the capability is active, verify that ACK custom resources are available in your cluster:
```
kubectl api-resources | grep services.k8s.aws
```
You should see a number of APIs listed for AWS resources.
**Note**
The capability for AWS Controllers for Kubernetes will install a number of CRDs for a variety of AWS resources.
## Next steps
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and get started
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions for other AWS services
+ [Working with capability resources](working-with-capabilities.md) - Manage your ACK capability resource
# ACK concepts
ACK manages AWS resources through Kubernetes APIs by continuously reconciling the desired state in your manifests with the actual state in AWS. When you create or update a Kubernetes custom resource, ACK makes the necessary AWS API calls to create or modify the corresponding AWS resource, then monitors it for drift and updates the Kubernetes status to reflect the current state. This approach lets you manage infrastructure using familiar Kubernetes tools and workflows while maintaining consistency between your cluster and AWS.
This topic explains the fundamental concepts behind how ACK manages AWS resources through Kubernetes APIs.
## Getting started with ACK
After creating the ACK capability (see [Create an ACK capability](create-ack-capability.md)), you can start managing AWS resources using Kubernetes manifests in your cluster.
As an example, create this S3 bucket manifest in `bucket.yaml`, choosing your own unique bucket name.
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-test-bucket
namespace: default
spec:
name: my-unique-bucket-name-12345
```
Apply the manifest:
```
kubectl apply -f bucket.yaml
```
Check the status:
```
kubectl get bucket my-test-bucket
kubectl describe bucket my-test-bucket
```
Verify the bucket was created in AWS:
```
aws s3 ls | grep my-unique-bucket-name-12345
```
Delete the Kubernetes resource:
```
kubectl delete bucket my-test-bucket
```
Verify the bucket was deleted from AWS:
```
aws s3 ls | grep my-unique-bucket-name-12345
```
The bucket should no longer appear in the list, demonstrating that ACK manages the full lifecycle of AWS resources.
For more information on getting started with ACK, see [Getting Started with ACK](https://aws-controllers-k8s.github.io/community/docs/user-docs/getting-started/).
## Resource lifecycle and reconciliation
ACK uses a continuous reconciliation loop to ensure your AWS resources match the desired state defined in your Kubernetes manifests.
**How reconciliation works**:
1. You create or update a Kubernetes custom resource (for example, an S3 Bucket)
1. ACK detects the change and compares the desired state with the actual state in AWS
1. If they differ, ACK makes AWS API calls to reconcile the difference
1. ACK updates the resource status in Kubernetes to reflect the current state
1. The loop repeats continuously, typically every few hours
Reconciliation is triggered when you create a new Kubernetes resource, update an existing resource’s `spec`, or when ACK detects drift in AWS from manual changes made outside ACK. Additionally, ACK performs periodic reconciliation with a resync period of 10 hours. Changes to Kubernetes resources trigger immediate reconciliation, while passive drift detection of upstream AWS resource changes occurs during the periodic resync.
When working through the getting started example above, ACK performs these steps:
1. Checks if bucket exists in AWS
1. If not, calls `s3:CreateBucket`
1. Updates Kubernetes status with bucket ARN and state
1. Continues monitoring for drift
To learn more about how ACK works, see [ACK Reconciliation](https://aws-controllers-k8s.github.io/community/docs/user-docs/reconciliation/).
## Status conditions
ACK resources use status conditions to communicate their state. Understanding these conditions helps you troubleshoot issues and understand resource health.
+ **Ready**: Indicates the resource is ready to be consumed (standardized Kubernetes condition).
+ **ACK.ResourceSynced**: Indicates the resource spec matches the AWS resource state.
+ **ACK.Terminal**: Indicates an unrecoverable error has occurred.
+ **ACK.Adopted**: Indicates the resource was adopted from an existing AWS resource rather than created new.
+ **ACK.Recoverable**: Indicates a recoverable error that may resolve without updating the spec.
+ **ACK.Advisory**: Provides advisory information about the resource.
+ **ACK.LateInitialized**: Indicates whether late initialization of fields is complete.
+ **ACK.ReferencesResolved**: Indicates whether all `AWSResourceReference` fields have been resolved.
+ **ACK.IAMRoleSelected**: Indicates whether an IAMRoleSelector has been selected to manage this resource.
Check resource status:
```
# Check if resource is ready
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
# Check for terminal errors
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="ACK.Terminal")]}'
```
Example status:
```
status:
conditions:
- type: Ready
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.ResourceSynced
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.Terminal
status: "True"
ackResourceMetadata:
arn: arn:aws:s3:::my-unique-bucket-name
ownerAccountID: "111122223333"
region: us-west-2
```
To learn more about ACK status and conditions, see [ACK Conditions](https://aws-controllers-k8s.github.io/community/docs/user-docs/conditions/).
## Deletion policies
ACK’s deletion policy controls what happens to AWS resources when you delete the Kubernetes resource.
**Delete (default)**
The AWS resource is deleted when you delete the Kubernetes resource: This is the default behavior.
```
# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: temp-bucket
spec:
name: temporary-bucket
```
Deleting this resource deletes the S3 bucket in AWS.
**Retain**
The AWS resource is kept when you delete the Kubernetes resource:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: important-bucket
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
name: production-data-bucket
```
Deleting this resource removes it from Kubernetes but leaves the S3 bucket in AWS.
The `retain` policy is useful for production databases that should outlive the Kubernetes resource, shared resources used by multiple applications, resources with important data that shouldn’t be accidentally deleted, or temporary ACK management where you adopt a resource, configure it, then release it back to manual management.
To learn more about ACK deletion policy, see [ACK Deletion Policy](https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/).
## Resource adoption
Adoption allows you to bring existing AWS resources under ACK management without recreating them.
When to use adoption:
+ Migrating existing infrastructure to ACK management
+ Recovering orphaned AWS resources in case of accidental resource deletion in Kubernetes
+ Importing resources created by other tools (CloudFormation, Terraform)
How adoption works:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
When you create this resource:
1. ACK checks if a bucket with that name exists in AWS
1. If found, ACK adopts it (no API calls to create)
1. ACK reads the current configuration from AWS
1. ACK updates the Kubernetes status to reflect the actual state
1. Future updates reconcile the resource normally
Once adopted, resources are managed like any other ACK resource, and deleting the Kubernetes resource will delete the AWS resource unless you use the `retain` deletion policy.
When adopting resources, the AWS resource must already exist and ACK needs read permissions to discover it. The `adopt-or-create` policy adopts the resource if it exists, or creates it if it doesn’t. This is useful when you want a declarative workflow that works whether the resource exists or not.
To learn more about ACK resource adoption, see [ACK Resource Adoption](https://aws-controllers-k8s.github.io/community/docs/user-docs/adopted-resource/).
## Cross-account and cross-region resources
ACK can manage resources in different AWS accounts and regions from a single cluster.
**Cross-region resource annotations**
You can specify the region of an AWS resource using an annotation:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: eu-bucket
annotations:
services.k8s.aws/region: eu-west-1
spec:
name: my-eu-bucket
```
You can also specify the region of all AWS resources created in a given namespace:
**Namespace annotations**
Set a default region for all resources in a namespace:
```
apiVersion: v1
kind: Namespace
metadata:
name: production
annotations:
services.k8s.aws/default-region: us-west-2
```
Resources created in this namespace use this region unless overridden with a resource-level annotation.
**Cross-account**
Use IAM Role Selectors to map specific IAM roles to namespaces:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: target-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
Resources created in the mapped namespace automatically use the specified role.
To learn more about IAM Role Selectors, see [ACK Cross-Account Resource Management](https://aws-controllers-k8s.github.io/docs/guides/cross-account). For cross-account configuration details, see [Configure ACK permissions](ack-permissions.md).
## Error handling and retry behavior
ACK automatically handles transient errors and retries failed operations.
Retry strategy:
+ Transient errors (rate limiting, temporary service issues, insufficient permissions) trigger automatic retries
+ Exponential backoff prevents overwhelming AWS APIs
+ Maximum retry attempts vary by error type
+ Permanent errors (invalid parameters, resource name conflicts) don’t retry
Check resource status for error details using `kubectl describe`:
```
kubectl describe bucket my-bucket
```
Look for status conditions with error messages, events showing recent reconciliation attempts, and the `message` field in status conditions explaining failures. Common errors include insufficient IAM permissions, resource name conflicts in AWS, invalid configuration values in the `spec`, and exceeded AWS service quotas.
For troubleshooting common errors, see [Troubleshoot issues with ACK capabilities](ack-troubleshooting.md).
## Resource composition with kro
For composing and connecting multiple ACK resources together, use the EKS Capability for kro (Kube Resource Orchestrator). kro provides a declarative way to define groups of resources, passing configuration between resources to manage complex infrastructure patterns simply.
For detailed examples of creating custom resource compositions with ACK resources, see [kro concepts](kro-concepts.md)
## Next steps
+ [ACK considerations for EKS](ack-considerations.md) - EKS-specific patterns and integration strategies
# Configure ACK permissions
ACK requires IAM permissions to create and manage AWS resources on your behalf. This topic explains how IAM works with ACK and provides guidance on configuring permissions for different use cases.
## How IAM works with ACK
ACK uses IAM roles to authenticate with AWS and perform actions on your resources. There are two ways to provide permissions to ACK:
**Capability Role**: The IAM role you provide when creating the ACK capability. This role is used by default for all ACK operations.
**IAM Role Selectors**: Additional IAM roles that can be mapped to specific namespaces or resources. These roles override the Capability Role for resources in their scope.
When ACK needs to create or manage a resource, it determines which IAM role to use:
1. Check if an IAMRoleSelector matches the resource’s namespace
1. If a match is found, assume that IAM role
1. Otherwise, use the Capability Role
This approach enables flexible permission management from simple single-role setups to complex multi-account, multi-team configurations.
## Getting started: Simple permission setup
For development, testing, or simple use cases, you can add all necessary service permissions directly to the Capability Role.
This approach works well when:
+ You’re getting started with ACK
+ All resources are in the same AWS account
+ A single team manages all ACK resources
+ You trust all ACK users to have the same permissions
## Production best practice: IAM Role Selectors
For production environments, use IAM Role Selectors to implement least-privilege access and namespace-level isolation.
When using IAM Role Selectors, the Capability Role only needs `sts:AssumeRole` and `sts:TagSession` permissions to assume the service-specific roles. You don’t need to add any AWS service permissions (like S3 or RDS) to the Capability Role itself—those permissions are granted to the individual IAM roles that the Capability Role assumes.
**Choosing between permission models**:
Use **direct permissions** (adding service permissions to the Capability Role) when:
+ You’re getting started and want the simplest setup
+ All resources are in the same account as your cluster
+ You have administrative, cluster-wide permission requirements
+ All teams can share the same permissions
Use **IAM Role Selectors** when:
+ Managing resources across multiple AWS accounts
+ Different teams or namespaces need different permissions
+ You need fine-grained access control per namespace
+ You want to follow least-privilege security practices
You can start with direct permissions and migrate to IAM Role Selectors later as your requirements grow.
**Why use IAM Role Selectors in production:**
+ **Least privilege**: Each namespace gets only the permissions it needs
+ **Team isolation**: Team A cannot accidentally use Team B’s permissions
+ **Easier auditing**: Clear mapping of which namespace uses which role
+ **Cross-account support**: Required for managing resources in multiple accounts
+ **Separation of concerns**: Different services or environments use different roles
### Basic IAM Role Selector setup
**Step 1: Create a service-specific IAM role**
Create an IAM role with permissions for specific AWS services:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": "*"
}
]
}
```
Configure the trust policy to allow the Capability Role to assume it:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
**Step 2: Grant AssumeRole permission to Capability Role**
Add permission to the Capability Role to assume the service-specific role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::111122223333:role/ACK-S3-Role"
}
]
}
```
**Step 3: Create IAMRoleSelector**
Map the IAM role to a namespace:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: s3-namespace-config
spec:
arn: arn:aws:iam::111122223333:role/ACK-S3-Role
namespaceSelector:
names:
- s3-resources
```
**Step 4: Create resources in the mapped namespace**
Resources in the `s3-resources` namespace automatically use the specified role:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: s3-resources
spec:
name: my-production-bucket
```
## Multi-account management
Use IAM Role Selectors to manage resources across multiple AWS accounts.
**Step 1: Create cross-account IAM role**
In the target account (444455556666), create a role that trusts the source account’s Capability Role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
Attach service-specific permissions to this role.
**Step 2: Grant AssumeRole permission**
In the source account (111122223333), allow the Capability Role to assume the target account role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::444455556666:role/ACKTargetAccountRole"
}
]
}
```
**Step 3: Create IAMRoleSelector**
Map the cross-account role to a namespace:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: production-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
**Step 4: Create resources**
Resources in the `production` namespace are created in the target account:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: production
spec:
name: my-cross-account-bucket
```
## Session tags
The EKS ACK capability automatically sets session tags on all AWS API requests. These tags enable fine-grained access control and auditing by identifying the source of each request.
### Available session tags
The following session tags are included with every AWS API call made by ACK:
| Tag Key | Description |
| --- | --- |
| `eks:eks-capability-arn` | The ARN of the EKS capability making the request |
| `eks:kubernetes-namespace` | The Kubernetes namespace of the resource being managed |
| `eks:kubernetes-api-group` | The Kubernetes API group of the resource (for example, `s3.services.k8s.aws`) |
### Using session tags for access control
You can use these session tags in IAM policy conditions to restrict which resources ACK can manage. This provides an additional layer of security beyond namespace-based IAM Role Selectors.
**Example: Restrict by namespace**
Allow ACK to create S3 buckets only when the request originates from the `production` namespace:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:CreateBucket",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:kubernetes-namespace": "production"
}
}
}
]
}
```
**Example: Restrict by capability**
Allow actions only from a specific ACK capability:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:eks-capability-arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack"
}
}
}
]
}
```
**Note**
Session tags are a difference from self-managed ACK, which does not set these tags by default. This enables more granular access control with the managed capability.
## Advanced IAM Role Selector patterns
For advanced configuration including label selectors, resource-specific role mapping, and additional examples, see [ACK IRSA Documentation](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/).
## Next steps
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and resource lifecycle
+ [ACK concepts](ack-concepts.md) - Learn about resource adoption and deletion policies
+ [Security considerations for EKS Capabilities](capabilities-security.md) - Understand security best practices for capabilities
# ACK considerations for EKS
This topic covers important considerations for using the EKS Capability for ACK, including IAM configuration, multi-account patterns, and integration with other EKS capabilities.
## IAM configuration patterns
The ACK capability uses an IAM Capability Role to authenticate with AWS. Choose the right IAM pattern based on your requirements.
### Simple: Single Capability Role
For development, testing, or simple use cases, grant all necessary permissions directly to the Capability Role.
**When to use**:
+ Getting started with ACK
+ Single-account deployments
+ All resources managed by one team
+ Development and testing environments
**Example**: Add S3 and RDS permissions to your Capability Role with resource tagging conditions:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
}
}
},
{
"Effect": "Allow",
"Action": ["rds:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
},
}
}
]
}
```
This example limits S3 and RDS operations to specific regions and requires RDS resources to have a `ManagedBy: ACK` tag.
### Production: IAM Role Selectors
For production environments, use IAM Role Selectors to implement least-privilege access and namespace-level isolation.
**When to use**:
+ Production environments
+ Multi-team clusters
+ Multi-account resource management
+ Least-privilege security requirements
+ Different services need different permissions
**Benefits**:
+ Each namespace gets only the permissions it needs
+ Team isolation - Team A cannot use Team B’s permissions
+ Easier auditing and compliance
+ Required for cross-account resource management
For detailed IAM Role Selector configuration, see [Configure ACK permissions](ack-permissions.md).
## Integration with other EKS capabilities
### GitOps with Argo CD
Use the EKS Capability for Argo CD to deploy ACK resources from Git repositories, enabling GitOps workflows for infrastructure management.
**Considerations**:
+ Store ACK resources alongside application manifests for end-to-end GitOps
+ Organize by environment, service, or resource type based on your team structure
+ Use Argo CD’s automated sync for continuous reconciliation
+ Enable pruning to automatically remove deleted resources
+ Consider hub-and-spoke patterns for multi-cluster infrastructure management
GitOps provides audit trails, rollback capabilities, and declarative infrastructure management. For more on Argo CD, see [Working with Argo CD](working-with-argocd.md).
### Resource composition with kro
Use the EKS Capability for kro (Kube Resource Orchestrator) to compose multiple ACK resources into higher-level abstractions and custom APIs.
**When to use kro with ACK**:
+ Create reusable patterns for common infrastructure stacks (database \$1 backup \$1 monitoring)
+ Build self-service platforms with simplified APIs for application teams
+ Manage resource dependencies and pass values between resources (S3 bucket ARN to Lambda function)
+ Standardize infrastructure configurations across teams
+ Reduce complexity by hiding implementation details behind custom resources
**Example patterns**:
+ Application stack: S3 bucket \$1 SQS queue \$1 notification configuration
+ Database setup: RDS instance \$1 parameter group \$1 security group \$1 secrets
+ Networking: VPC \$1 subnets \$1 route tables \$1 security groups
kro handles dependency ordering, status propagation, and lifecycle management for composed resources. For more on kro, see [kro concepts](kro-concepts.md).
## Organizing your resources
Organize ACK resources using Kubernetes namespaces and AWS resource tags for better management, access control, and cost tracking.
### Namespace organization
Use Kubernetes namespaces to logically separate ACK resources by environment (production, staging, development), team (platform, data, ml), or application.
**Benefits**:
+ Namespace-scoped RBAC for access control
+ Set default regions per namespace using annotations
+ Easier resource management and cleanup
+ Logical separation aligned with organizational structure
### Resource tagging
The EKS ACK capability automatically applies default tags to all AWS resources it creates. These tags differ from self-managed ACK and provide enhanced traceability.
**Default tags applied by the capability**:
| Tag Key | Description |
| --- | --- |
| `eks:controller-version` | The version of the ACK controller |
| `eks:kubernetes-namespace` | The Kubernetes namespace of the ACK resource |
| `eks:kubernetes-resource-name` | The name of the Kubernetes resource |
| `eks:kubernetes-api-group` | The Kubernetes API group (for example, `s3.services.k8s.aws`) |
| `eks:eks-capability-arn` | The ARN of the EKS ACK capability |
**Note**
Self-managed ACK uses different default tags: `services.k8s.aws/controller-version` and `services.k8s.aws/namespace`. The capability’s tags use the `eks:` prefix for consistency with other EKS features.
**Additional recommended tags**:
Add custom tags for cost allocation, ownership tracking, and organizational purposes:
+ Environment (Production, Staging, Development)
+ Team or department ownership
+ Cost center for billing allocation
+ Application or service name
## Migration from other Infrastructure-as-code tools
Many organizations are finding value in standardizing on Kubernetes beyond their workload orchestration. Migrating infrastructure and AWS resource management to ACK allows you to standardize infrastructure management using Kubernetes APIs alongside your application workloads.
**Benefits of standardizing on Kubernetes for infrastructure**:
+ **Single source of truth**: Manage both applications and infrastructure in Kubernetes, enabling an end-to-end GitOps practice
+ **Unified tooling**: Teams use Kubernetes resources and tooling rather than learning multiple tools and frameworks
+ **Consistent reconciliation**: ACK continuously reconciles AWS resources like Kubernetes does for workloads, detecting and correcting drift compared to imperative tools
+ **Native compositions**: With kro and ACK together, reference AWS resources directly in application and resource manifests, passing connection strings and ARNs between resources
+ **Simplified operations**: One control plane for deployments, rollbacks, and observability across your entire system
ACK supports adopting existing AWS resources without recreating them, enabling zero-downtime migration from CloudFormation, Terraform, or resources external to the cluster.
**Adopt an existing resource**:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
Once adopted, the resource is managed by ACK and can be updated through Kubernetes manifests. You can migrate incrementally, adopting resources as needed while maintaining existing IaC tools for other resources.
ACK also supports read-only resources. For resources managed by other teams or tools that you want to reference but not modify, combine adoption with the `retain` deletion policy and grant only read IAM permissions. This allows applications to discover shared infrastructure (VPCs, IAM roles, KMS keys) through Kubernetes APIs without risking modifications.
For more on resource adoption, see [ACK concepts](ack-concepts.md).
## Deletion policies
Deletion policies control what happens to AWS resources when you delete the corresponding Kubernetes resource. Choose the right policy based on the resource lifecycle and your operational requirements.
### Delete (default)
The AWS resource is deleted when you delete the Kubernetes resource. This maintains consistency between your cluster and AWS, ensuring resources don’t accumulate.
**When to use delete**:
+ Development and testing environments where cleanup is important
+ Ephemeral resources tied to application lifecycle (test databases, temporary buckets)
+ Resources that should not outlive the application (SQS queues, ElastiCache clusters)
+ Cost optimization - automatically clean up unused resources
+ Environments managed with GitOps where resource removal from Git should delete the infrastructure
The default delete policy aligns with Kubernetes' declarative model: what’s in the cluster matches what exists in AWS.
### Retain
The AWS resource is kept when you delete the Kubernetes resource. This protects critical data and allows resources to outlive their Kubernetes representation.
**When to use retain**:
+ Production databases with critical data that must survive cluster changes
+ Long-term storage buckets with compliance or audit requirements
+ Shared resources used by multiple applications or teams
+ Resources being migrated to different management tools
+ Disaster recovery scenarios where you want to preserve infrastructure
+ Resources with complex dependencies that require careful decommissioning
```
apiVersion: rds.services.k8s.aws/v1alpha1
kind: DBInstance
metadata:
name: production-db
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
dbInstanceIdentifier: prod-db
# ... configuration
```
**Important**
Retained resources continue to incur AWS costs and must be manually deleted from AWS when no longer needed. Use resource tagging to track retained resources for cleanup.
For more on deletion policies, see [ACK concepts](ack-concepts.md).
## Upstream documentation
For detailed information on using ACK:
+ [ACK usage guide](https://aws-controllers-k8s.github.io/community/docs/user-docs/usage/) - Creating and managing resources
+ [ACK API reference](https://aws-controllers-k8s.github.io/community/reference/) - Complete API documentation for all services
+ [ACK documentation](https://aws-controllers-k8s.github.io/community/docs/) - Comprehensive user documentation
## Next steps
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions and multi-account patterns
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and resource lifecycle
+ [Troubleshoot issues with ACK capabilities](ack-troubleshooting.md) - Troubleshoot ACK issues
+ [Working with Argo CD](working-with-argocd.md) - Deploy ACK resources with GitOps
+ [kro concepts](kro-concepts.md) - Compose ACK resources into higher-level abstractions
# Troubleshoot issues with ACK capabilities
This topic provides troubleshooting guidance for the EKS Capability for ACK, including capability health checks, resource status verification, and IAM permission issues.
**Note**
EKS Capabilities are fully managed and run outside your cluster. You don’t have access to controller logs or controller namespaces. Troubleshooting focuses on capability health, resource status, and IAM configuration.
## Capability is ACTIVE but resources aren’t being created
If your ACK capability shows `ACTIVE` status but resources aren’t being created in AWS, check the capability health, resource status, and IAM permissions.
**Check capability health**:
You can view capability health and status issues in the EKS console or using the AWS CLI.
**Console**:
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name.
1. Choose the **Observability** tab.
1. Choose **Monitor cluster**.
1. Choose the **Capabilities** tab to view health and status for all capabilities.
** AWS CLI**:
```
# View capability status and health
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
# Look for issues in the health section
```
**Common causes**:
+ **IAM permissions missing**: The Capability Role lacks permissions for the AWS service
+ **Wrong namespace**: Resources created in namespace without proper IAMRoleSelector
+ **Invalid resource spec**: Check resource status conditions for validation errors
+ **API throttling**: AWS API rate limits being hit
+ **Admission webhooks**: Admission webhooks blocking the controller from patching resource status
**Check resource status**:
```
# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default
# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'
# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default
```
**Verify IAM permissions**:
```
# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role
# Get specific policy details
aws iam get-role-policy --role-name my-ack-capability-role --policy-name policy-name
```
## Resources created in AWS but not showing in Kubernetes
ACK only tracks resources it creates through Kubernetes manifests. To manage existing AWS resources with ACK, use the adoption feature.
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
For more on resource adoption, see [ACK concepts](ack-concepts.md).
## Cross-account resources not being created
If resources aren’t being created in a target AWS account when using IAM Role Selectors, verify the trust relationship and IAMRoleSelector configuration.
**Verify trust relationship**:
```
# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'
```
The trust policy must allow the source account’s Capability Role to assume it.
**Confirm IAMRoleSelector configuration**:
```
# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Describe specific selector
kubectl describe iamroleselector my-selector
```
**Verify namespace alignment**:
IAMRoleSelectors are cluster-scoped resources but target specific namespaces. Ensure your ACK resources are in a namespace that matches the IAMRoleSelector’s namespace selector:
```
# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production
# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'
```
**Check IAMRoleSelected condition**:
Verify that the IAMRoleSelector was successfully matched to your resource by checking the `ACK.IAMRoleSelected` condition:
```
# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'
```
If the condition is `False` or missing, the IAMRoleSelector’s namespace selector doesn’t match the resource’s namespace. Verify the selector’s `namespaceSelector` matches your resource’s namespace labels.
**Check Capability Role permissions**:
The Capability Role needs `sts:AssumeRole` and `sts:TagSession` permissions for the target account role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`"
}
]
}
```
For detailed cross-account configuration, see [Configure ACK permissions](ack-permissions.md).
## Next steps
+ [ACK considerations for EKS](ack-considerations.md) - ACK considerations and best practices
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM permissions and multi-account patterns
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and resource lifecycle
+ [Troubleshooting EKS Capabilities](capabilities-troubleshooting.md) - General capability troubleshooting guidance
# Comparing EKS Capability for ACK to self-managed ACK
The EKS Capability for ACK provides the same functionality as self-managed ACK controllers, but with significant operational advantages. For a general comparison of EKS Capabilities vs self-managed solutions, see [EKS Capabilities considerations](capabilities-considerations.md). This topic focuses on ACK-specific differences.
## Differences from upstream ACK
The EKS Capability for ACK is based on upstream ACK controllers but differs in IAM integration.
**IAM Capability Role**: The capability uses a dedicated IAM role with a trust policy that allows the `capabilities.eks.amazonaws.com` service principal, not IRSA (IAM Roles for Service Accounts). You can attach IAM policies directly to the Capability Role with no need to create or annotate Kubernetes service accounts or configure OIDC providers. A best practice for production use cases is to configure service permissions using `IAMRoleSelector`. See [Configure ACK permissions](ack-permissions.md) for more details.
**Session tags**: The managed capability automatically sets session tags on all AWS API requests, enabling fine-grained access control and auditing. Tags include `eks:eks-capability-arn`, `eks:kubernetes-namespace`, and `eks:kubernetes-api-group`. This differs from self-managed ACK, which does not set these tags by default. See [Configure ACK permissions](ack-permissions.md) for details on using session tags in IAM policies.
**Resource tags**: The capability applies different default tags to AWS resources than self-managed ACK. The capability uses `eks:` prefixed tags (such as `eks:kubernetes-namespace`, `eks:eks-capability-arn`) instead of the `services.k8s.aws/` tags used by self-managed ACK. See [ACK considerations for EKS](ack-considerations.md) for the complete list of default resource tags.
**Resource compatibility**: ACK custom resources work identically to upstream ACK with no changes to your ACK resource YAML files. The capability uses the same Kubernetes APIs and CRDs, so tools like `kubectl` work the same way. All GA controllers and resources from upstream ACK are supported.
For complete ACK documentation and service-specific guides, see the [ACK documentation](https://aws-controllers-k8s.github.io/community/).
## Migration path
You can migrate from self-managed ACK to the managed capability with zero downtime:
1. Update your self-managed ACK controller to use `kube-system` for leader election leases, for example:
```
helm upgrade --install ack-s3-controller \
oci://public.ecr.aws/aws-controllers-k8s/s3-chart \
--namespace ack-system \
--set leaderElection.namespace=kube-system
```
This moves the controller’s lease to `kube-system`, allowing the managed capability to coordinate with it.
1. Create the ACK capability on your cluster (see [Create an ACK capability](create-ack-capability.md))
1. The managed capability recognizes existing ACK-managed AWS resources and takes over reconciliation
1. Gradually scale down or remove self-managed controller deployments:
```
helm uninstall ack-s3-controller --namespace ack-system
```
This approach allows both controllers to coexist safely during migration. The managed capability automatically adopts resources previously managed by self-managed controllers, ensuring continuous reconciliation without conflicts.
## Next steps
+ [Create an ACK capability](create-ack-capability.md) - Create an ACK capability resource
+ [ACK concepts](ack-concepts.md) - Understand ACK concepts and resource lifecycle
+ [Configure ACK permissions](ack-permissions.md) - Configure IAM and permissions
# Continuous Deployment with Argo CD
Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. With Argo CD, you can automate the deployment and lifecycle management of your applications across multiple clusters and environments. Argo CD supports multiple source types including Git repositories, Helm registries (HTTP and OCI), and OCI images—providing flexibility for organizations with different security and compliance requirements.
With EKS Capabilities, Argo CD is fully managed by AWS, eliminating the need to install, maintain, and scale Argo CD controllers and their dependencies on your clusters.
## How Argo CD Works
Argo CD follows the GitOps pattern, where your application source (Git repository, Helm registry, or OCI image) is the source of truth for defining the desired application state. When you create an Argo CD `Application` resource, you specify the source containing your application manifests and the target Kubernetes cluster and namespace. Argo CD continuously monitors both the source and the live state in the cluster, automatically synchronizing any changes to ensure the cluster state matches the desired state.
**Note**
With the EKS Capability for Argo CD, the Argo CD software runs in the AWS control plane, not on your worker nodes. This means your worker nodes don’t need direct access to Git repositories or Helm registries—the capability handles source access from the AWS account.
Argo CD provides three primary resource types:
+ **Application**: Defines a deployment from a Git repository to a target cluster
+ **ApplicationSet**: Generates multiple Applications from templates for multi-cluster deployments
+ **AppProject**: Provides logical grouping and access control for Applications
**Example: Creating an Argo CD Application**
The following example shows how to create an Argo CD `Application` resource:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
```
**Note**
Use `destination.name` with the cluster name you used when registering the cluster (like `in-cluster` for the local cluster). The `destination.server` field also works with EKS cluster ARNs, but using cluster names is recommended for better readability.
## Benefits of Argo CD
Argo CD implements a GitOps workflow where you define your application configurations in Git repositories and Argo CD automatically syncs your applications to match the desired state. This Git-centric approach provides a complete audit trail of all changes, enables easy rollbacks, and integrates naturally with your existing code review and approval processes. Argo CD automatically detects and reconciles drift between the desired state in Git and the actual state in your clusters, ensuring your deployments remain consistent with your declared configuration.
With Argo CD, you can deploy and manage applications across multiple clusters from a single Argo CD instance, simplifying operations in multi-cluster and multi-region environments. The Argo CD UI provides visualization and monitoring capabilities, allowing you to view the deployment status, health, and history of your applications. The UI integrates with AWS Identity Center (formerly AWS SSO) for seamless authentication and authorization, enabling you to control access using your existing identity management infrastructure.
As part of EKS Managed Capabilities, Argo CD is fully managed by AWS, eliminating the need to install, configure, and maintain Argo CD infrastructure. AWS handles scaling, patching, and operational management, allowing your teams to focus on application delivery rather than tool maintenance.
## Integration with AWS Identity Center
EKS Managed Capabilities provides direct integration between Argo CD and AWS Identity Center, enabling seamless authentication and authorization for your users. When you enable the Argo CD capability, you can configure AWS Identity Center integration to map Identity Center groups and users to Argo CD RBAC roles, allowing you to control who can access and manage applications in Argo CD.
## Integration with Other EKS Managed Capabilities
Argo CD integrates with other EKS Managed Capabilities.
+ ** AWS Controllers for Kubernetes (ACK)**: Use Argo CD to manage the deployment of ACK resources across multiple clusters, enabling GitOps workflows for your AWS infrastructure.
+ **kro (Kube Resource Orchestrator)**: Use Argo CD to deploy kro compositions across multiple clusters, enabling consistent resource composition across your Kubernetes estate.
## Getting Started with Argo CD
To get started with the EKS Capability for Argo CD:
1. Create and configure an IAM Capability Role with the necessary permissions for Argo CD to access your sources and manage applications.
1. [Create an Argo CD capability resource](create-argocd-capability.md) on your EKS cluster through the AWS Console, AWS CLI, or your preferred infrastructure as code tool.
1. Configure repository access and register clusters for application deployment.
1. Create Application resources to deploy your applications from your declarative sources.
# Create an Argo CD capability
This topic explains how to create an Argo CD capability on your Amazon EKS cluster.
## Prerequisites
Before creating an Argo CD capability, ensure you have:
+ An existing Amazon EKS cluster running a supported Kubernetes version (all versions in standard and extended support are supported)
+ ** AWS Identity Center configured** - Required for Argo CD authentication (local users are not supported)
+ An IAM Capability Role with permissions for Argo CD
+ Sufficient IAM permissions to create capability resources on EKS clusters
+ `kubectl` configured to communicate with your cluster
+ (Optional) The Argo CD CLI installed for easier cluster and repository management
+ (For CLI/eksctl) The appropriate CLI tool installed and configured
For instructions on creating the IAM Capability Role, see [Amazon EKS capability IAM role](capability-role.md). For Identity Center setup, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html).
**Important**
The IAM Capability Role you provide determines which AWS resources Argo CD can access. This includes Git repository access via CodeConnections and secrets in Secrets Manager. For guidance on creating an appropriate role with least-privilege permissions, see [Amazon EKS capability IAM role](capability-role.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
## Choose your tool
You can create an Argo CD capability using the AWS Management Console, AWS CLI, or eksctl:
+ [Create an Argo CD capability using the Console](argocd-create-console.md) - Use the Console for a guided experience
+ [Create an Argo CD capability using the AWS CLI](argocd-create-cli.md) - Use the AWS CLI for scripting and automation
+ [Create an Argo CD capability using eksctl](argocd-create-eksctl.md) - Use eksctl for a Kubernetes-native experience
## What happens when you create an Argo CD capability
When you create an Argo CD capability:
1. EKS creates the Argo CD capability service in the AWS control plane
1. Custom Resource Definitions (CRDs) are installed in your cluster
1. 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](capabilities-security.md))
1. Argo CD begins watching for its custom resources (Applications, ApplicationSets, AppProjects)
1. The capability status changes from `CREATING` to `ACTIVE`
1. The Argo CD UI becomes accessible through its URL
Once active, you can create Argo CD Applications in your cluster to deploy from your declarative sources.
**Note**
The automatically created access entry does not grant permissions to deploy applications to clusters. To deploy applications, you must configure additional Kubernetes RBAC permissions for each target cluster. See [Register target clusters](argocd-register-clusters.md) for details on registering clusters and configuring access.
## Next steps
After creating the Argo CD capability:
+ [Argo CD concepts](argocd-concepts.md) - Learn about GitOps principles, sync policies, and multi-cluster patterns
+ [Working with Argo CD](working-with-argocd.md) - Configure repository access, register target clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Explore multi-cluster architecture patterns and advanced configuration
# Create an Argo CD capability using the Console
This topic describes how to create an Argo CD capability using the AWS Management Console.
## Prerequisites
+ ** AWS Identity Center configured** – Argo CD requires AWS Identity Center for authentication. Local users are not supported. If you don’t have AWS Identity Center set up, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) to create an Identity Center instance, and [Add users](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) and [Add groups](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) to create users and groups for Argo CD access.
## Create the Argo CD capability
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. In the left navigation, choose **Argo CD**.
1. Choose **Create Argo CD capability**.
1. For **IAM Capability Role**:
+ If you already have an IAM Capability Role, select it from the dropdown
+ If you need to create a role, choose **Create Argo CD role**
This opens the IAM console in a new tab with pre-populated trust policy and full read access to Secrets Manager. No other permissions are added by default, but you can add them if needed. If you plan to use CodeCommit repositories or other AWS services, add the appropriate permissions before creating the role.
After creating the role, return to the EKS console and the role will be automatically selected.
**Note**
If you plan to use the optional integrations with AWS Secrets Manager or AWS CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
1. Configure AWS Identity Center integration:
1. Select **Enable AWS Identity Center integration**.
1. Choose your Identity Center instance from the dropdown.
1. Configure role mappings for RBAC by assigning users or groups to Argo CD roles (ADMIN, EDITOR, or VIEWER)
1. Choose **Create**.
The capability creation process begins.
## Verify the capability is active
1. On the **Capabilities** tab, view the Argo CD capability status.
1. Wait for the status to change from `CREATING` to `ACTIVE`.
1. Once active, the capability is ready to use.
For information about capability statuses and troubleshooting, see [Working with capability resources](working-with-capabilities.md).
## Access the Argo CD UI
After the capability is active, you can access the Argo CD UI:
1. On the Argo CD capability page, choose **Open Argo CD UI**.
1. The Argo CD UI opens in a new browser tab.
1. You can now create Applications and manage deployments through the UI.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Configure repositories, register clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Multi-cluster architecture and advanced configuration
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Create an Argo CD capability using the AWS CLI
This topic describes how to create an Argo CD capability using the AWS CLI.
## Prerequisites
+ ** AWS CLI** – Version `2.12.3` or later. To check your version, run `aws --version`. For more information, see [Installing](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the AWS Command Line Interface User Guide.
+ ** `kubectl` ** – A command line tool for working with Kubernetes clusters. For more information, see [Set up `kubectl` and `eksctl`](install-kubectl.md).
+ ** AWS Identity Center configured** – Argo CD requires AWS Identity Center for authentication. Local users are not supported. If you don’t have AWS Identity Center set up, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) to create an Identity Center instance, and [Add users](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) and [Add groups](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) to create users and groups for Argo CD access.
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**Note**
If you plan to use the optional integrations with AWS Secrets Manager or AWS CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
## Step 2: Create the Argo CD capability
Create the Argo CD capability resource on your cluster.
First, set environment variables for your Identity Center configuration:
```
# Get your Identity Center instance ARN (replace region if your IDC instance is in a different region)
export IDC_INSTANCE_ARN=$(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].InstanceArn' --output text)
# Get a user ID for RBAC mapping (replace with your username and region if needed)
export IDC_USER_ID=$(aws identitystore list-users \
--region [.replaceable]`region` \
--identity-store-id $(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text)
echo "IDC_INSTANCE_ARN=$IDC_INSTANCE_ARN"
echo "IDC_USER_ID=$IDC_USER_ID"
```
Create the capability with Identity Center integration. Replace *region-code* with the AWS Region where your cluster is located and *my-cluster* with your cluster name and *idc-region-code* with the region code where you IAM Identity Center has been configured:
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--type ARGOCD \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ArgoCDCapabilityRole \
--delete-propagation-policy RETAIN \
--configuration '{
"argoCd": {
"awsIdc": {
"idcInstanceArn": "'$IDC_INSTANCE_ARN'",
"idcRegion": "'[.replaceable]`idc-region-code`'"
},
"rbacRoleMappings": [{
"role": "ADMIN",
"identities": [{
"id": "'$IDC_USER_ID'",
"type": "SSO_USER"
}]
}]
}
}'
```
The command returns immediately, but the capability takes some time to become active as EKS creates the required capability infrastructure and components. EKS will install the Kubernetes Custom Resource Definitions related to this capability in your cluster as it is being created.
**Note**
If you receive an error that the cluster doesn’t exist or you don’t have permissions, verify:
The cluster name is correct
Your AWS CLI is configured for the correct region
You have the required IAM permissions
## Step 3: Verify the capability is active
Wait for the capability to become active. Replace *region-code* with the AWS Region where your cluster is located and *my-cluster* with your cluster name.
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--query 'capability.status' \
--output text
```
The capability is ready when the status shows `ACTIVE`. Don’t continue to the next step until the status is `ACTIVE`.
You can also view the full capability details:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd
```
## Step 4: Verify custom resources are available
After the capability is active, verify that Argo CD custom resources are available in your cluster:
```
kubectl api-resources | grep argoproj.io
```
You should see `Application` and `ApplicationSet` resource types listed.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Configure repositories, register clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Multi-cluster architecture and advanced configuration
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Create an Argo CD capability using eksctl
This topic describes how to create an Argo CD capability using eksctl.
**Note**
The following steps require eksctl version `0.220.0` or later. To check your version, run `eksctl version`.
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**Note**
For this basic setup, no additional IAM policies are needed. If you plan to use Secrets Manager for repository credentials or CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
## Step 2: Get your AWS Identity Center configuration
Get your Identity Center instance ARN and user ID for RBAC configuration:
```
# Get your Identity Center instance ARN
aws sso-admin list-instances --query 'Instances[0].InstanceArn' --output text
# Get a user ID for admin access (replace 'your-username' with your Identity Center username)
aws identitystore list-users \
--identity-store-id $(aws sso-admin list-instances --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text
```
Note these values - you’ll need them in the next step.
## Step 3: Create an eksctl configuration file
Create a file named `argocd-capability.yaml` with the following content. Replace the placeholder values with your cluster’s name, cluster’s region, IAM role ARN, Identity Center instance ARN, Identity Center region, and user ID:
```
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: my-cluster
region: cluster-region-code
capabilities:
- name: my-argocd
type: ARGOCD
roleArn: arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole
deletePropagationPolicy: RETAIN
configuration:
argocd:
awsIdc:
idcInstanceArn: arn:aws:sso:::instance/ssoins-123abc
idcRegion: idc-region-code
rbacRoleMappings:
- role: ADMIN
identities:
- id: 38414300-1041-708a-01af-5422d6091e34
type: SSO_USER
```
**Note**
You can add multiple users or groups to the RBAC mappings. For groups, use `type: SSO_GROUP` and provide the group ID. Available roles are `ADMIN`, `EDITOR`, and `VIEWER`.
## Step 4: Create the Argo CD capability
Apply the configuration file:
```
eksctl create capability -f argocd-capability.yaml
```
The command returns immediately, but the capability takes some time to become active.
## Step 5: Verify the capability is active
Check the capability status. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
eksctl get capability \
--region region-code \
--cluster my-cluster \
--name my-argocd
```
The capability is ready when the status shows `ACTIVE`.
## Step 6: Verify custom resources are available
After the capability is active, verify that Argo CD custom resources are available in your cluster:
```
kubectl api-resources | grep argoproj.io
```
You should see `Application` and `ApplicationSet` resource types listed.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Learn how to create and manage Argo CD Applications
+ [Argo CD considerations](argocd-considerations.md) - Configure SSO and multi-cluster access
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Argo CD concepts
Argo CD implements GitOps by treating Git as the single source of truth for your application deployments. This topic walks through a practical example, then explains the core concepts you need to understand when working with the EKS Capability for Argo CD.
## Getting started with Argo CD
After creating the Argo CD capability (see [Create an Argo CD capability](create-argocd-capability.md)), you can start deploying applications. This example walks through registering a cluster and creating an Application.
### Step 1: Set up
**Register your cluster** (required)
Register the cluster where you want to deploy applications. For this example, we’ll register the same cluster where Argo CD is running (you can use the name `in-cluster` for compatibility with most Argo CD examples):
```
# Get your cluster ARN
CLUSTER_ARN=$(aws eks describe-cluster \
--name my-cluster \
--query 'cluster.arn' \
--output text)
# Register the cluster using Argo CD CLI
argocd cluster add $CLUSTER_ARN \
--aws-cluster-name $CLUSTER_ARN \
--name in-cluster \
--project default
```
**Note**
For information about configuring the Argo CD CLI to work with the Argo CD capability in EKS, see [Using the Argo CD CLI with the managed capability](argocd-comparison.md#argocd-cli-configuration).
Alternatively, register the cluster using a Kubernetes Secret (see [Register target clusters](argocd-register-clusters.md) for details).
**Configure repository access** (optional)
This example uses a public GitHub repository, so no repository configuration is required. For private repositories, configure access using AWS Secrets Manager, CodeConnections, or Kubernetes Secrets (see [Configure repository access](argocd-configure-repositories.md) for details).
For AWS services (ECR for Helm charts, CodeConnections, and CodeCommit), you can reference them directly in Application resources without creating a Repository. The Capability Role must have the required IAM permissions. See [Configure repository access](argocd-configure-repositories.md) for details.
### Step 2: Create an Application
Create this Application manifest in `my-app.yaml`:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
```
Apply the Application:
```
kubectl apply -f my-app.yaml
```
After applying this Application, Argo CD: 1. Syncs the application from Git to your cluster (initial deployment) 2. Monitors the Git repository for changes 3. Automatically syncs subsequent changes to your cluster 4. Detects and corrects any drift from the desired state 5. Provides health status and sync history in the UI
View the application status:
```
kubectl get application guestbook -n argocd
```
You can also view the application using the Argo CD CLI or the Argo CD UI (accessible from the EKS console under your cluster’s Capabilities tab).
**Note**
When using the Argo CD CLI with the managed capability, specify applications with the namespace prefix: `argocd app get argocd/guestbook`.
**Note**
Use the cluster name in `destination.name` (the name you used when registering the cluster). The managed capability does not support the local in-cluster default (`kubernetes.default.svc`).
## Core concepts
### GitOps principles and source types
Argo CD implements GitOps, where your application source is the single source of truth for deployments:
+ **Declarative** - Desired state is declared using YAML manifests, Helm charts, or Kustomize overlays
+ **Versioned** - Every change is tracked with complete audit trail
+ **Automated** - Argo CD continuously monitors sources and automatically syncs changes
+ **Self-healing** - Detects and corrects drift between desired and actual cluster state
**Supported source types**:
+ **Git repositories** - GitHub, GitLab, Bitbucket, CodeCommit (HTTPS, SSH, or CodeConnections)
+ **Helm registries** - HTTP registries (like `https://aws.github.io/eks-charts`) and OCI registries (like `public.ecr.aws`)
+ **OCI images** - Container images containing manifests or Helm charts (like `oci://registry-1.docker.io/user/my-app`)
This flexibility allows organizations to choose sources that meet their security and compliance requirements. For example, organizations that restrict Git access from clusters can use ECR for Helm charts or OCI images.
For more information, see [Application Sources](https://argo-cd.readthedocs.io/en/stable/user-guide/application-sources/) in the Argo CD documentation.
### Sync and reconciliation
Argo CD continuously monitors your sources and clusters to detect and correct differences:
1. Polls sources for changes (default: every 6 minutes)
1. Compares desired state with cluster state
1. Marks applications as `Synced` or `OutOfSync`
1. Syncs changes automatically (if configured) or waits for manual approval
1. Monitors resource health after sync
**Sync waves** control resource creation order using annotations:
```
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Default if not specified
```
Resources are applied in wave order (lower numbers first, including negative numbers like `-1`). Wave `0` is the default if not specified. This allows you to create dependencies like namespaces (wave `-1`) before deployments (wave `0`) before services (wave `1`).
**Self-healing** automatically reverts manual changes:
```
spec:
syncPolicy:
automated:
selfHeal: true
```
**Note**
The managed capability uses annotation-based resource tracking (not label-based) for better compatibility with Kubernetes conventions and other tools.
For detailed information about sync phases, hooks, and advanced patterns, see the [Argo CD sync documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/).
### Application health
Argo CD monitors the health of all resources in your application:
**Health statuses**: \$1 **Healthy** - All resources running as expected \$1 **Progressing** - Resources being created or updated \$1 **Degraded** - Some resources not healthy (pods crashing, jobs failing) \$1 **Suspended** - Application intentionally paused \$1 **Missing** - Resources defined in Git not present in cluster
Argo CD has built-in health checks for common Kubernetes resources (Deployments, StatefulSets, Jobs, etc.) and supports custom health checks for CRDs.
Application health is determined by all its resources - if any resource is `Degraded`, the application is `Degraded`.
For more information, see [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/) in the Argo CD documentation.
### Multi-cluster patterns
Argo CD supports two main deployment patterns:
**Hub-and-spoke** - Run Argo CD on a dedicated management cluster that deploys to multiple workload clusters: \$1 Centralized control and visibility \$1 Consistent policies across all clusters \$1 One Argo CD instance to manage \$1 Clear separation between control plane and workloads
**Per-cluster** - Run Argo CD on each cluster, managing only that cluster’s applications: \$1 Cluster separation (one failure doesn’t affect others) \$1 Simpler networking (no cross-cluster communication) \$1 Easier initial setup (no cluster registration)
Choose hub-and-spoke for platform teams managing many clusters, or per-cluster for independent teams or when clusters must be fully isolated.
For detailed multi-cluster configuration, see [Argo CD considerations](argocd-considerations.md).
### Projects
Projects provide logical grouping and access control for Applications:
+ **Source restrictions** - Limit which Git repositories can be used
+ **Destination restrictions** - Limit which clusters and namespaces can be targeted
+ **Resource restrictions** - Limit which Kubernetes resource types can be deployed
+ **RBAC integration** - Map projects to AWS Identity Center user and group IDs
Applications belong to a single project. If not specified, they use the `default` project, which has no restrictions by default. For production use, edit the `default` project to restrict access and create new projects with appropriate restrictions.
For project configuration and RBAC patterns, see [Configure Argo CD permissions](argocd-permissions.md).
### Sync options
Fine-tune sync behavior with common options:
+ `CreateNamespace=true` - Automatically create destination namespace
+ `ServerSideApply=true` - Use server-side apply for better conflict resolution
+ `SkipDryRunOnMissingResource=true` - Skip dry run when CRDs don’t exist yet (useful for kro instances)
```
spec:
syncPolicy:
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
- SkipDryRunOnMissingResource=true
```
For a complete list of sync options, see the [Argo CD sync options documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/).
## Next steps
+ [Configure repository access](argocd-configure-repositories.md) - Configure Git repository access
+ [Register target clusters](argocd-register-clusters.md) - Register target clusters for deployment
+ [Create Applications](argocd-create-application.md) - Create your first Application
+ [Argo CD considerations](argocd-considerations.md) - EKS-specific patterns, Identity Center integration, and multi-cluster configuration
+ [Argo CD Documentation](https://argo-cd.readthedocs.io/en/stable/) - Comprehensive Argo CD documentation including sync hooks, health checks, and advanced patterns
# Configure Argo CD permissions
The Argo CD managed capability integrates with AWS Identity Center for authentication and uses built-in RBAC roles for authorization. This topic explains how to configure permissions for users and teams.
## How permissions work with Argo CD
The Argo CD capability uses AWS Identity Center for authentication and provides three built-in RBAC roles for authorization.
When a user accesses Argo CD:
1. They authenticate using AWS Identity Center (which can federate to your corporate identity provider)
1. AWS Identity Center provides user and group information to Argo CD
1. Argo CD maps users and groups to RBAC roles based on your configuration
1. Users see only the applications and resources they have permission to access
## Built-in RBAC roles
The Argo CD capability provides three built-in roles that you map to AWS Identity Center users and groups. These are **globally scoped roles** that control access to Argo CD resources like projects, clusters, and repositories.
**Important**
Global roles control access to Argo CD itself, not to project-scoped resources like Applications. EDITOR and VIEWER users cannot see or manage Applications by default—they need project roles to access project-scoped resources. See [Project roles and project-scoped access](#project-roles) for details on granting access to Applications and other project-scoped resources.
**ADMIN**
Full access to all Argo CD resources and settings:
+ Create, update, and delete Applications and ApplicationSets in any project
+ Manage Argo CD configuration
+ Register and manage deployment target clusters
+ Configure repository access
+ Create and manage projects
+ View all application status and history
+ List and access all clusters and repositories
**EDITOR**
Can update projects and configure project roles, but cannot change global Argo CD settings:
+ Update existing projects (cannot create or delete projects)
+ Configure project roles and permissions
+ View GPG keys and certificates
+ Cannot change global Argo CD configuration
+ Cannot manage clusters or repositories directly
+ Cannot see or manage Applications without project roles
**VIEWER**
Read-only access to Argo CD resources:
+ View project configurations
+ List all projects (including projects the user is not assigned to)
+ View GPG keys and certificates
+ Cannot list clusters or repositories
+ Cannot make any changes
+ Cannot see or manage Applications without project roles
**Note**
To grant EDITOR or VIEWER users access to Applications, an ADMIN or EDITOR must create project roles that map Identity Center groups to specific permissions within a project.
## Project roles and project-scoped access
Global roles (ADMIN, EDITOR, VIEWER) control access to Argo CD itself. Project roles control access to resources and capabilities within a specific project, including:
+ **Resources**: Applications, ApplicationSets, repository credentials, cluster credentials
+ **Capabilities**: Log access, exec access to application pods
**Understanding the two-level permission model**:
+ **Global scope**: Built-in roles determine what users can do with projects, clusters, repositories, and Argo CD settings
+ **Project scope**: Project roles determine what users can do with resources and capabilities within a specific project
This means:
+ ADMIN users can access all project resources and capabilities without additional configuration
+ EDITOR and VIEWER users must be granted project roles to access project resources and capabilities
+ EDITOR users can create project roles to grant themselves and others access within projects they can update
**Example workflow**:
1. An ADMIN maps an Identity Center group to the EDITOR role globally
1. An ADMIN creates a project for a team
1. The EDITOR configures project roles within that project to grant team members access to project-scoped resources
1. Team members (who may have VIEWER global role) can now see and manage Applications in that project based on their project role permissions
For details on configuring project roles, see [Project-based access control](#_project_based_access_control).
## Configure role mappings
Map AWS Identity Center users and groups to Argo CD roles when creating or updating the capability.
**Example role mapping**:
```
{
"rbacRoleMapping": {
"ADMIN": ["AdminGroup", "alice@example.com"],
"EDITOR": ["DeveloperGroup", "DevOpsTeam"],
"VIEWER": ["ReadOnlyGroup", "bob@example.com"]
}
}
```
**Note**
Role names are case-sensitive and must be uppercase (ADMIN, EDITOR, VIEWER).
**Important**
EKS Capabilities integration with AWS Identity Center supports up to 1,000 identities per Argo CD capability. An identity can be a user or a group.
**Update role mappings**:
```
aws eks update-capability \
--region us-east-1 \
--cluster-name cluster \
--capability-name capname \
--endpoint "https://eks.ap-northeast-2.amazonaws.com" \
--role-arn "arn:aws:iam::[.replaceable]111122223333:role/[.replaceable]`EKSCapabilityRole`" \
--configuration '{
"argoCd": {
"rbacRoleMappings": {
"addOrUpdateRoleMappings": [
{
"role": "ADMIN",
"identities": [
{ "id": "686103e0-f051-7068-b225-e6392b959d9e", "type": "SSO_USER" }
]
}
]
}
}
}'
```
## Admin account usage
The admin account is designed for initial setup and administrative tasks like registering clusters and configuring repositories.
**When admin account is appropriate**:
+ Initial capability setup and configuration
+ Solo development or quick demonstrations
+ Administrative tasks (cluster registration, repository configuration, project creation)
**Best practices for admin account**:
+ Don’t commit account tokens to version control
+ Rotate tokens immediately if exposed
+ Limit account token usage to setup and administrative tasks
+ Set short expiration times (maximum 12 hours)
+ Only 5 account tokens can be created at any given time
**When to use project-based access instead**:
+ Shared development environments with multiple users
+ Any environment that resembles production
+ When you need audit trails of who performed actions
+ When you need to enforce resource restrictions or access boundaries
For production environments and multi-user scenarios, use project-based access control with dedicated RBAC roles mapped to AWS Identity Center groups.
## Project-based access control
Use Argo CD Projects (AppProject) to provide fine-grained access control and resource isolation for teams.
**Important**
Before assigning users or groups to project-specific roles, you must first map them to a global Argo CD role (ADMIN, EDITOR, or VIEWER) in the capability configuration. Users cannot access Argo CD without a global role mapping, even if they’re assigned to project roles.
Consider mapping users to the VIEWER role globally, then grant additional permissions through project-specific roles. This provides baseline access while allowing fine-grained control at the project level.
Projects provide:
+ **Source restrictions**: Limit which Git repositories can be used
+ **Destination restrictions**: Limit which clusters and namespaces can be targeted
+ **Resource restrictions**: Limit which Kubernetes resource types can be deployed
+ **RBAC integration**: Map projects to AWS Identity Center groups or Argo CD roles
**Example project for team isolation**:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
description: Team A applications
# Required: Specify which namespaces this project watches for Applications
sourceNamespaces:
- argocd
# Source restrictions
sourceRepos:
- https://github.com/myorg/team-a-apps
# Destination restrictions
destinations:
- namespace: team-a-*
server: arn:aws:eks:us-west-2:111122223333:cluster/production
# Resource restrictions
clusterResourceWhitelist:
- group: ''
kind: Namespace
namespaceResourceWhitelist:
- group: 'apps'
kind: Deployment
- group: ''
kind: Service
- group: ''
kind: ConfigMap
```
### Source namespaces
When using the EKS Argo CD capability, the `spec.sourceNamespaces` field is required in AppProject definitions. This field specifies which namespace can contain Applications or ApplicationSets that reference this project.
**Important**
The EKS Argo CD capability only supports a single namespace for Applications and ApplicationSets—the namespace you specified when creating the capability (typically `argocd`). This differs from open source Argo CD which supports multiple namespaces.
**AppProject configuration**
All AppProjects must include the capability’s configured namespace in `sourceNamespaces`:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a-project
namespace: argocd
spec:
description: Applications for Team A
# Required: Specify the capability's configured namespace (configuration.argoCd.namespace)
sourceNamespaces:
- argocd # Must match your capability's namespace configuration
# Source repositories this project can deploy from
sourceRepos:
- 'https://github.com/my-org/team-a-*'
# Destination restrictions
destinations:
- namespace: 'team-a-*'
server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
```
**Note**
If you omit the capability’s namespace from `sourceNamespaces`, Applications or ApplicationSets in that namespace cannot reference this project, resulting in deployment failures.
**Assign users to projects**:
Project roles grant EDITOR and VIEWER users access to project resources (Applications, ApplicationSets, repository and cluster credentials) and capabilities (logs, exec). Without project roles, these users cannot access these resources even if they have global role access.
ADMIN users have access to all Applications without needing project roles.
**Example: Granting Application access to team members**
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
# ... project configuration ...
sourceNamespaces:
- argocd
# Project roles grant Application-level access
roles:
- name: developer
description: Team A developers - can manage Applications
policies:
- p, proj:team-a:developer, applications, *, team-a/*, allow
- p, proj:team-a:developer, clusters, get, *, allow # See cluster names in UI
groups:
- 686103e0-f051-7068-b225-e6392b959d9e # Identity Center group ID
- name: viewer
description: Team A viewers - read-only Application access
policies:
- p, proj:team-a:viewer, applications, get, team-a/*, allow
- p, proj:team-a:viewer, clusters, get, *, allow # See cluster names in UI
groups:
- 786203e0-f051-7068-b225-e6392b959d9f # Identity Center group ID
```
**Note**
Include `clusters, get, *, allow` in project roles to allow users to see cluster names in the UI. Without this permission, the destination cluster displays as "unknown".
**Understanding project role policies**:
The policy format is: `p, proj::, , ,