diff --git a/.gitignore b/.gitignore index e51f77e8f..a4d20af83 100755 --- a/.gitignore +++ b/.gitignore @@ -80,4 +80,3 @@ build vale/styles/AsciiDoc/ vale/styles/RedHat/ .amazonq/ -.kiro-project/ diff --git a/build-info.xml b/build-info.xml index 727110dc6..a0d5e5d52 100755 --- a/build-info.xml +++ b/build-info.xml @@ -38,6 +38,9 @@ doc-history + + 1 + diff --git a/check_xrefs.py b/check_xrefs.py new file mode 100755 index 000000000..fdf8ab81e --- /dev/null +++ b/check_xrefs.py @@ -0,0 +1,301 @@ +#!/usr/bin/env python3 +""" +AsciiDoc Cross-Reference Checker + +This script analyzes all .adoc files in a directory to find broken cross-references. +It supports both xref: and <<>> syntax and checks against explicit and auto-generated section IDs. +""" + +import re +import os +from pathlib import Path +from concurrent.futures import ProcessPoolExecutor, as_completed +from collections import defaultdict +from dataclasses import dataclass +from typing import Set, List, Tuple +import sys + + +@dataclass +class XRefInfo: + """Information about a cross-reference""" + file_path: str + line_number: int + xref_id: str + xref_type: str # 'xref' or 'angle_bracket' + + +@dataclass +class FileAnalysis: + """Analysis results for a single file""" + file_path: str + section_ids: Set[str] + xrefs: List[XRefInfo] + errors: List[str] + + +def normalize_id(text: str) -> str: + """ + Normalize a section header to an auto-generated ID. + Based on AsciiDoc rules with idseparator: - + """ + # Convert to lowercase + text = text.lower() + # Remove formatting and special chars, replace spaces with hyphens + text = re.sub(r'[^\w\s-]', '', text) + text = re.sub(r'\s+', '-', text) + # Remove multiple consecutive hyphens + text = re.sub(r'-+', '-', text) + # Remove leading/trailing hyphens + text = text.strip('-') + return text + + +def extract_section_ids(content: str, lines: List[str]) -> Set[str]: + """ + Extract all section IDs from file content. + Supports: + - [[id]] syntax (standalone or inline) + - [#id] syntax (standalone or inline) + - Auto-generated IDs from section headers + """ + section_ids = set() + + # Pattern for explicit [[id]] or [[id,title]] syntax (standalone or inline) + # This pattern works for both "[[id]]" on its own line and "=== Title [[id]]" inline + explicit_bracket_pattern = re.compile(r'\[\[([^\]]+)\]\]') + for match in explicit_bracket_pattern.finditer(content): + # Handle [[id,title]] syntax - ID is the part before the comma + id_text = match.group(1) + section_id = id_text.split(',')[0].strip() + section_ids.add(section_id) + + # Pattern for [#id] syntax (standalone or inline) + explicit_hash_pattern = re.compile(r'\[#([^\]]+)\]') + for match in explicit_hash_pattern.finditer(content): + section_id = match.group(1).split(',')[0].strip() + section_ids.add(section_id) + + # Pattern for section headers (=, ==, ===, etc.) + # Auto-generate IDs from section titles + section_header_pattern = re.compile(r'^(=+)\s+(.+)$', re.MULTILINE) + for match in section_header_pattern.finditer(content): + header_text = match.group(2).strip() + # Remove inline IDs like [[id]] or [#id] from the header text before auto-generating ID + header_text = re.sub(r'\[\[[^\]]+\]\]', '', header_text) + header_text = re.sub(r'\[#[^\]]+\]', '', header_text) + # Remove inline formatting like *bold*, _italic_, etc. + header_text = re.sub(r'\*\*?([^*]+)\*\*?', r'\1', header_text) + header_text = re.sub(r'__?([^_]+)__?', r'\1', header_text) + header_text = re.sub(r'`([^`]+)`', r'\1', header_text) + # Remove links + header_text = re.sub(r'https?://[^\s\[]+', '', header_text) + header_text = re.sub(r'link:[^\[]+\[[^\]]*\]', '', header_text) + + auto_id = normalize_id(header_text) + if auto_id: + section_ids.add(auto_id) + + return section_ids + + +def extract_xrefs(content: str, file_path: str) -> List[XRefInfo]: + """ + Extract all cross-references from file content. + Supports: + - xref:id[...] syntax + - <> syntax + - <> syntax + """ + xrefs = [] + lines = content.split('\n') + + # Pattern for xref:id[...] syntax + xref_pattern = re.compile(r'xref:([a-zA-Z0-9_-]+)(?:\[[^\]]*\])?') + + # Pattern for <> or <> syntax + angle_bracket_pattern = re.compile(r'<<([a-zA-Z0-9_-]+)(?:,[^>]*)?>>') + + for line_num, line in enumerate(lines, 1): + # Find xref: references + for match in xref_pattern.finditer(line): + xref_id = match.group(1) + xrefs.append(XRefInfo( + file_path=file_path, + line_number=line_num, + xref_id=xref_id, + xref_type='xref' + )) + + # Find <<>> references + for match in angle_bracket_pattern.finditer(line): + xref_id = match.group(1) + xrefs.append(XRefInfo( + file_path=file_path, + line_number=line_num, + xref_id=xref_id, + xref_type='angle_bracket' + )) + + return xrefs + + +def analyze_file(file_path: Path) -> FileAnalysis: + """ + Analyze a single .adoc file for section IDs and cross-references. + """ + errors = [] + + try: + with open(file_path, 'r', encoding='utf-8') as f: + content = f.read() + lines = content.split('\n') + + section_ids = extract_section_ids(content, lines) + xrefs = extract_xrefs(content, str(file_path)) + + return FileAnalysis( + file_path=str(file_path), + section_ids=section_ids, + xrefs=xrefs, + errors=errors + ) + + except Exception as e: + errors.append(f"Error reading {file_path}: {str(e)}") + return FileAnalysis( + file_path=str(file_path), + section_ids=set(), + xrefs=[], + errors=errors + ) + + +def find_adoc_files(directory: str) -> List[Path]: + """Find all .adoc files in the directory recursively.""" + path = Path(directory) + return list(path.rglob('*.adoc')) + + +def main(): + """Main function to orchestrate the cross-reference checking.""" + + # Configuration + directory = 'latest/ug/' + + if not os.path.exists(directory): + print(f"Error: Directory '{directory}' not found") + sys.exit(1) + + print(f"Analyzing .adoc files in {directory}...") + + # Find all .adoc files + adoc_files = find_adoc_files(directory) + print(f"Found {len(adoc_files)} .adoc files") + + # Analyze files in parallel + all_section_ids = defaultdict(set) # id -> set of files that define it + all_xrefs = [] + file_errors = [] + + print("\nAnalyzing files in parallel...") + + with ProcessPoolExecutor() as executor: + # Submit all files for analysis + future_to_file = { + executor.submit(analyze_file, file_path): file_path + for file_path in adoc_files + } + + # Collect results as they complete + completed = 0 + for future in as_completed(future_to_file): + completed += 1 + if completed % 50 == 0: + print(f" Processed {completed}/{len(adoc_files)} files...") + + try: + result = future.result() + + # Collect section IDs + for section_id in result.section_ids: + all_section_ids[section_id].add(result.file_path) + + # Collect xrefs + all_xrefs.extend(result.xrefs) + + # Collect errors + if result.errors: + file_errors.extend(result.errors) + + except Exception as e: + file_path = future_to_file[future] + file_errors.append(f"Error processing {file_path}: {str(e)}") + + print(f" Processed {len(adoc_files)}/{len(adoc_files)} files") + + # Report file processing errors + if file_errors: + print("\n" + "="*80) + print("FILE PROCESSING ERRORS") + print("="*80) + for error in file_errors: + print(f" {error}") + + # Check for broken xrefs + print("\n" + "="*80) + print("CHECKING CROSS-REFERENCES") + print("="*80) + print(f"Total section IDs found: {len(all_section_ids)}") + print(f"Total xrefs found: {len(all_xrefs)}") + + broken_xrefs = [] + for xref in all_xrefs: + if xref.xref_id not in all_section_ids: + broken_xrefs.append(xref) + + # Report results + print("\n" + "="*80) + print("RESULTS") + print("="*80) + + if not broken_xrefs: + print("✓ No broken cross-references found!") + else: + print(f"✗ Found {len(broken_xrefs)} broken cross-references:\n") + + # Group by file for better readability + broken_by_file = defaultdict(list) + for xref in broken_xrefs: + broken_by_file[xref.file_path].append(xref) + + for file_path in sorted(broken_by_file.keys()): + print(f"\n{file_path}:") + for xref in sorted(broken_by_file[file_path], key=lambda x: x.line_number): + xref_syntax = f"xref:{xref.xref_id}[...]" if xref.xref_type == 'xref' else f"<<{xref.xref_id}>>" + print(f" Line {xref.line_number}: {xref_syntax}") + + # Summary statistics + print("\n" + "="*80) + print("SUMMARY") + print("="*80) + print(f"Files analyzed: {len(adoc_files)}") + print(f"Section IDs found: {len(all_section_ids)}") + print(f"Cross-references found: {len(all_xrefs)}") + print(f"Broken cross-references: {len(broken_xrefs)}") + + # Check for duplicate section IDs + duplicates = {id: files for id, files in all_section_ids.items() if len(files) > 1} + if duplicates: + print(f"\n⚠ Warning: Found {len(duplicates)} duplicate section IDs:") + for section_id, files in sorted(duplicates.items()): + print(f"\n ID '{section_id}' defined in {len(files)} files:") + for file_path in sorted(files): + print(f" - {file_path}") + + # Exit with error code if broken xrefs found + sys.exit(1 if broken_xrefs else 0) + + +if __name__ == '__main__': + main() diff --git a/latest/ug/automode/auto-configure-alb.adoc b/latest/ug/automode/auto-configure-alb.adoc index ea45d0c8b..839f435ec 100644 --- a/latest/ug/automode/auto-configure-alb.adoc +++ b/latest/ug/automode/auto-configure-alb.adoc @@ -291,6 +291,4 @@ The following tables provide a detailed comparison of changes in IngressClassPar | `elbv2.k8s.aws/v1beta1` | `eks.amazonaws.com/v1` | API version change | `spec.targetType` optional | `spec.targetType` required | Explicit target type specification | `spec.networking.ingress.from` | Not supported | No longer supports NLB without security groups -|=== - -To use the custom TargetGroupBinding feature, you must tag the target group with the eks:eks-cluster-name tag with cluster name to grant the controller the necessary IAM permissions. Be aware that the controller will delete the target group when the TargetGroupBinding resource or the cluster is deleted. \ No newline at end of file +|=== \ No newline at end of file diff --git a/latest/ug/automode/auto-configure-nlb.adoc b/latest/ug/automode/auto-configure-nlb.adoc index d8c46bca4..2f1858290 100644 --- a/latest/ug/automode/auto-configure-nlb.adoc +++ b/latest/ug/automode/auto-configure-nlb.adoc @@ -134,15 +134,15 @@ When migrating to EKS Auto Mode for load balancing, several changes in service a | `service.beta.kubernetes.io/load-balancer-source-ranges` | Not supported | Use `spec.loadBalancerSourceRanges` on Service | `service.beta.kubernetes.io/aws-load-balancer-type` | Not supported | Use `spec.loadBalancerClass` on Service | `service.beta.kubernetes.io/aws-load-balancer-internal` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-scheme` -| `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-target-group-attributes` instead | Various load balancer attributes | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` +| `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` instead | `service.beta.kubernetes.io/aws-load-balancer-access-log-enabled` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` instead | `service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` instead | `service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` instead | `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled` | Not supported | Use `service.beta.kubernetes.io/aws-load-balancer-attributes` instead |=== -To migrate from deprecated load balancer attribute annotations, consolidate these settings into the `service.beta.kubernetes.io/aws-load-balancer-attributes` annotation. This annotation accepts a comma-separated list of key-value pairs for various load balancer attributes. For example, to specify access logging, and cross-zone load balancing, use the following format: +To migrate from deprecated load balancer attribute annotations, consolidate these settings into the `service.beta.kubernetes.io/aws-load-balancer-attributes` annotation. This annotation accepts a comma-separated list of key-value pairs for various load balancer attributes. For example, to specify proxy protocol, access logging, and cross-zone load balancing, use the following format: ```yaml service.beta.kubernetes.io/aws-load-balancer-attributes: access_logs.s3.enabled=true,access_logs.s3.bucket=my-bucket,access_logs.s3.prefix=my-prefix,load_balancing.cross_zone.enabled=true @@ -159,5 +159,3 @@ This consolidated format provides a more consistent and flexible way to configur | `spec.targetType` optional | `spec.targetType` required | Explicit target type specification | `spec.networking.ingress.from` | Not supported | No longer supports NLB without security groups |=== - -Note: To use the custom TargetGroupBinding feature, you must tag the target group with the `eks:eks-cluster-name` tag with cluster name to grant the controller the necessary IAM permissions. Be aware that the controller will delete the target group when the TargetGroupBinding resource or the cluster is deleted. \ No newline at end of file diff --git a/latest/ug/automode/auto-controls.adoc b/latest/ug/automode/auto-controls.adoc index 7d1ac679c..9ab42b6b0 100644 --- a/latest/ug/automode/auto-controls.adoc +++ b/latest/ug/automode/auto-controls.adoc @@ -33,16 +33,18 @@ include::iam_snippet:b3fc497a-510a-4dcf-8f20-f6a340f72dfd[] |{aws} Region |Account |af-south-1 |471112993317 |ap-east-1 |590183728416 +|ap-east-2 |381492200852 |ap-northeast-1 |851725346105 |ap-northeast-2 |992382805010 |ap-northeast-3 |891377407544 |ap-south-1 |975049899075 |ap-south-2 |590183737426 |ap-southeast-1 |339712723301 -|ap-southeast-2 |58264376476 +|ap-southeast-2 |058264376476 |ap-southeast-3 |471112941769 |ap-southeast-4 |590183863144 |ap-southeast-5 |654654202513 +|ap-southeast-6 |905418310314 |ap-southeast-7 |533267217478 |ca-central-1 |992382439851 |ca-west-1 |767397959864 diff --git a/latest/ug/automode/auto-net-pol.adoc b/latest/ug/automode/auto-net-pol.adoc index 02d8f4045..e9611415c 100644 --- a/latest/ug/automode/auto-net-pol.adoc +++ b/latest/ug/automode/auto-net-pol.adoc @@ -7,44 +7,14 @@ include::../attributes.txt[] //add to ToC -== Overview +Network policies allow you to control traffic flow at the IP address or port level within your Amazon EKS cluster. This topic explains how to enable and use network policies with EKS Auto Mode. -As customers scale their application environments using EKS, network traffic isolation becomes increasingly fundamental for preventing unauthorized access to resources inside and outside the cluster. This is especially important in a multi-tenant environment with multiple unrelated workloads running side by side in the cluster. Kubernetes network policies enable you to enhance the network security posture for your Kubernetes workloads, and their integrations with cluster-external endpoints. EKS Auto Mode supports different types of network policies. - -=== Layer 3 and 4 isolation - -Standard Kubernetes network policies operate at layers 3 and 4 of the OSI network model and allow you to control traffic flow at the IP address or port level within your Amazon EKS cluster. - -==== Use cases -* Segment network traffic between workloads to ensure that only related applications can talk to each other. -* Isolate tenants at the namespace level using policies to enforce network separation. - -=== DNS-based enforcement - -Customers typically deploy workloads in EKS that are part of a broader distributed environment, some of which have to communicate with systems and services outside the cluster (northbound traffic). These systems and services can be in the {aws} cloud or outside {aws} altogether. Domain Name System (DNS) based policies allow you to strengthen your security posture by adopting a more stable and predictable approach for preventing unauthorized access from pods to cluster-external resources or endpoints. This mechanism eliminates the need to manually track and allow list specific IP addresses. By securing resources with a DNS-based approach, you also have more flexibility to update external infrastructure without having to relax your security posture or modify network policies amid changes to upstream servers and hosts. You can filter egress traffic to external endpoints using either a Fully Qualified Domain Name (FQDN), or a matching pattern for a DNS domain name. This gives you the added flexibility of extending access to multiple subdomains associated with a particular cluster-external endpoint. - -==== Use cases -* Standardize on a DNS-based approach for filtering access from a Kubernetes environment to cluster-external endpoints. -* Secure access to {aws} services in a multi-tenant environment. -* Manage network access from pods to on-prem workloads in your Hybrid cloud environments. - -=== Admin (or cluster-scoped) rules - -In some cases, like multi-tenant scenarios, customers may have the requirement to enforce a network security standard that applies to the whole cluster. Instead of repetitively defining and maintaining a distinct policy for each namespace, you can use a single policy to centrally manage network access controls for different workloads in the cluster, irrespective of their namespace. These types of policies allow you to extend the scope of enforcement for your network filtering rules applied at layer 3, layer 4, and when using DNS rules. - -==== Use cases -* Centrally manage network access controls for all (or a subset of) workloads in your EKS cluster. -* Define a default network security posture across the cluster. -* Extend organizational security standards to the scope of the cluster in a more operationally efficient way. - -== Getting started - -=== Prerequisites +== Prerequisites * An Amazon EKS cluster with EKS Auto Mode enabled * kubectl configured to connect to your cluster -=== Step 1: Enable Network Policy Controller +== Step 1: Enable Network Policy Controller To use network policies with EKS Auto Mode, you first need to enable the Network Policy Controller by applying a ConfigMap to your cluster. @@ -65,7 +35,7 @@ data: kubectl apply -f enable-network-policy.yaml ``` -=== Step 2: Enable Network Policies in Node Class +== Step 2: Enable Network Policies in Node Class Before you can use network policies, you need to ensure that your Node Class is configured to support them. Follow these steps: @@ -97,126 +67,6 @@ kubectl get nodeclass network-policy-enabled Once your nodes are using this Node Class, they will be able to enforce network policies. You can now proceed to create and apply network policies to control traffic within your cluster. For all the node class configuration options, see <>. -=== Step 3: Create and test network policies - -Your EKS Auto Mode cluster is now configured to support Kubernetes network policies. You can test this with the <>. - -== How does it work? - -=== DNS-based network policy - -image::images/apply-dns-policy-1.png[Illustration of workflow when a DNS-based policy is applied in EKS Auto] -image::images/apply-dns-policy-2.png[llustration of workflow when a DNS-based policy is applied in EKS Auto] - -. The platform team applies a DNS-based policy to the EKS cluster. -. The Network Policy Controller is responsible for monitoring the creation of policies within the cluster and then reconciling policy endpoints. In this use case, the network policy controller instructs the node agent to filter DNS requests based on the allow-listed domains in the created policy. Domain names are allow-listed using the FQDN or a domain names that matches a pattern defined in the Kubernetes resource configuration. -. Workload A attempts to resolve the IP for a cluster-external endpoint. The DNS request first goes through a proxy that filters such requests based on the allow list applied through the network policy. -. Once the DNS request goes through the DNS filter allow list, it is proxied to CoreDNS, -. CoreDNS in turn sends the request to the External DNS Resolver (Amazon Route 53 Resolver) to get the list of IP address behind the domain name. -. The resolved IPs with TTL are returned in the response to the DNS request. These IPs are then written in an eBPF map which is used in the next step for IP layer enforcement. -. The eBPF probes attached to the Pod veth interface will then filter egress traffic from Workload A to the cluster-external endpoint based on the rules in place. This ensures pods can only send cluster-external traffic to the IPs of allow listed domains. The validity of these IPs is based on the TTL retrieved from the External DNS Resolver (Amazon Route 53 Resolver). - -==== Using the Application Network Policy -The `ApplicationNetworkPolicy` combines the capabilities of standard Kubernetes network policies with DNS based filtering at a namespace level using a single Custom Resource Definition (CRD). Therefore, the `ApplicationNetworkPolicy` can be used for: - -. Defining restrictions at layers 3 and 4 of the network stack using IP blocks and port numbers. -. Defining rules that operate at layer 7 of the network stack and letting you filter traffic based on FQDNs. - -*Important note*: DNS based rules defined using the `ApplicationNetworkPolicy` are only applicable to workloads running in EKS Auto Mode-launched EC2 instances. - -==== Example - -You have a workload in your EKS Auto Mode cluster that needs to communicate with an application on-prem which is behind a load balancer with a DNS name. You could achieve this using the following network policy: - -[source,yaml] ----- -apiVersion: networking.k8s.aws/v1alpha1 -kind: ApplicationNetworkPolicy -metadata: - name: my-onprem-app-egress - namespace: galaxy -spec: - podSelector: - matchLabels: - role: backend - policyTypes: - - Egress - egress: - - to: - - domainNames: - - "myapp.mydomain.com" - ports: - - protocol: TCP - port: 8080 ----- - -At the Kubernetes network level, this would allow egress from any pods in the "galaxy" namespace labelled with `role: backend` to connect to the domain name *myapp.mydomain.com* on TCP port 8080. In addition, you would need to setup the network connectivity for egress traffic from your VPC to your corporate data center. - -image::images/eks-auto-to-on-prem.png[llustration of workload in EKS Auto communicating with applications on prem] - -=== Admin (or cluster) network policy - -image::images/evaluation-order.png[llustration of the evaluation order for network policies in EKS] - -==== Using the Cluster Network Policy - -When using a `ClusterNetworkPolicy`, the Admin tier policies are evaluated first and cannot be overridden. When the Admin tier policies have been evaluated, the standard namespace scoped policies are used to execute the applied network segmentation rules. This can be accomplished by using either `ApplicationNetworkPolicy` or `NetworkPolicy`. Lastly, the Baseline tier rules that define the default network restrictions for cluster workloads will be enforced. These Baseline tier rules *can* be overridden by the namespace scoped policies if needed. - -==== Example - -You have an application in your cluster that you want to isolate from other tenant workloads. You can explicitly block cluster traffic from other namespaces to prevent network access to the sensitive workload namespace. - -[source,yaml] ----- -apiVersion: networking.k8s.aws/v1alpha1 -kind: ClusterNetworkPolicy -metadata: - name: protect-sensitive-workload -spec: - tier: Admin - priority: 10 - subject: - namespaces: - matchLabels: - kubernetes.io/metadata.name: earth - ingress: - - action: Deny - from: - - namespaces: - matchLabels: {} # Match all namespaces. - name: select-all-deny-all ----- - -== Considerations - -=== Understand policy evaluation order - -The network policy capabilities supported in EKS are evaluated in a specific order to ensure predictable and secure traffic management. Therefore, it's important to understand the evaluation flow to design an effective network security posture for your environment. - -. *Admin tier policies (evaluated first)*: All Admin tier ClusterNetworkPolicies are evaluated before any other policies. Within the Admin tier, policies are processed in priority order (lowest priority number first). The action type determines what happens next. - * *Deny action (highest precedence)*: When an Admin policy with a Deny action matches traffic, that traffic is immediately blocked regardless of any other policies. No further ClusterNetworkPolicy or NetworkPolicy rules are processed. This ensures that organization-wide security controls cannot be overridden by namespace-level policies. - * *Allow action*: After Deny rules are evaluated, Admin policies with Allow actions are processed in priority order (lowest priority number first). When an Allow action matches, the traffic is accepted and no further policy evaluation occurs. These policies can grant access across multiple namespaces based on label selectors, providing centralized control over which workloads can access specific resources. - * *Pass action*: Pass actions in Admin tier policies delegate decision-making to lower tiers. When traffic matches a Pass rule, evaluation skips all remaining Admin tier rules for that traffic and proceeds directly to the NetworkPolicy tier. This allows administrators to explicitly delegate control for certain traffic patterns to application teams. For example, you might use Pass rules to delegate intra-namespace traffic management to namespace administrators while maintaining strict controls over external access. -. *Network policy tier*: If no Admin tier policy matches with Deny or Allow, or if a Pass action was matched, namespace-scoped ApplicationNetworkPolicy and traditional NetworkPolicy resources are evaluated next. These policies provide fine-grained control within individual namespaces and are managed by application teams. Namespace-scoped policies can only be more restrictive than Admin policies. They cannot override an Admin policy's Deny decision, but they can further restrict traffic that was allowed or passed by Admin policies. -. *Baseline tier Admin policies*: If no Admin or namespace-scoped policies match the traffic, Baseline tier ClusterNetworkPolicies are evaluated. These provide default security postures that can be overridden by namespace-scoped policies, allowing administrators to set organization-wide defaults while giving teams flexibility to customize as needed. Baseline policies are evaluated in priority order (lowest priority number first). -. *Default deny (if no policies match)*: This deny-by-default behavior ensures that only explicitly permitted connections are allowed, maintaining a strong security posture. - -=== Applying the principle of least privilege - -* *Start with restrictive policies and gradually add permissions as needed* - Begin by implementing deny-by-default policies at the cluster level, then incrementally add allow rules as you validate legitimate connectivity requirements. This approach forces teams to explicitly justify each external connection, creating a more secure and auditable environment. -* *Regularly audit and remove unused policy rules* - Network policies can accumulate over time as applications evolve, leaving behind obsolete rules that unnecessarily expand your attack surface. Implement a regular review process to identify and remove policy rules that are no longer needed, ensuring your security posture remains tight and maintainable. -* *Use specific domain names rather than broad patterns when possible* - While wildcard patterns like `*.amazonaws.com` provide convenience, they also grant access to a wide range of services. Whenever feasible, specify exact domain names like `s3.us-west-2.amazonaws.com` to limit access to only the specific services your applications require, reducing the risk of lateral movement if a workload is compromised. - -=== Using DNS-based policies in EKS - -* DNS based rules defined using the `ApplicationNetworkPolicy` are only applicable to workloads running in EKS Auto Mode-launched EC2 instances. If you are running a mixed mode cluster (consisting of both EKS Auto and non EKS Auto worker nodes), your DNS-based rules are only effective in the EKS Auto mode worker nodes (EC2 managed instances). - -=== Validating your DNS policies - -* *Use staging clusters that mirror production network topology for testing* - Your staging environment should replicate the network architecture, external dependencies, and connectivity patterns of production to ensure accurate policy testing. This includes matching VPC configurations, DNS resolution behavior, and access to the same external services your production workloads require. -* *Implement automated testing for critical network paths* - Build automated tests that validate connectivity to essential external services as part of your CI/CD pipeline. These tests should verify that legitimate traffic flows are permitted while unauthorized connections are blocked, providing continuous validation that your network policies maintain the correct security posture as your infrastructure evolves. -* *Monitor application behavior after policy changes* - After deploying new or modified network policies to production, closely monitor application logs, error rates, and performance metrics to quickly identify any connectivity issues. Establish clear rollback procedures so you can rapidly revert policy changes if they cause unexpected application behavior or service disruptions. - -=== Interaction with Amazon Route 53 DNS firewall +== Step 3: Create and test network policies -EKS Admin and Network policies are evaluated first at the pod level when traffic is initiated. If an EKS network policy allows egress to a specific domain, the pod then performs a DNS query that reaches the Route 53 Resolver. At this point, Route 53 DNS Firewall rules are evaluated. If DNS Firewall blocks the domain query, DNS resolution fails and the connection cannot be established, even though the EKS network policy allowed it. This creates complementary security layers: EKS DNS-based network policies provide pod-level egress control for application-specific access requirements and multi-tenant security boundaries, while DNS Firewall provides VPC-wide protection against known malicious domains and enforces organization-wide blocklists. \ No newline at end of file +Your EKS Auto Mode cluster is now configured to support Kubernetes network policies. You can test this with the <>. \ No newline at end of file diff --git a/latest/ug/book.adoc b/latest/ug/book.adoc index 260a4825a..8568d7f51 100644 --- a/latest/ug/book.adoc +++ b/latest/ug/book.adoc @@ -58,8 +58,6 @@ include::networking/eks-networking.adoc[leveloffset=+1] include::workloads/eks-workloads.adoc[leveloffset=+1] -include::capabilities/capabilities.adoc[leveloffset=+1] - include::cluster-management/eks-managing.adoc[leveloffset=+1] include::security/security.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/ack-comparison.adoc b/latest/ug/capabilities/ack-comparison.adoc deleted file mode 100644 index 9297dbd66..000000000 --- a/latest/ug/capabilities/ack-comparison.adoc +++ /dev/null @@ -1,67 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-comparison] -= Comparing EKS Capability for ACK to self-managed ACK -:info_titleabbrev: Comparison to self-managed - -[abstract] --- -Understand the differences between the EKS Capability for ACK and self-managed ACK controllers. --- - -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 <>. -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 <> for more details. - -*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 https://aws-controllers-k8s.github.io/community/[ACK documentation^]. - - -== Migration path - -You can migrate from self-managed ACK to the managed capability with zero downtime: - -. Update your self-managed ACK controller to use `kube-system` for leader election leases, for example: -+ -[source,bash] ----- -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. - -. Create the ACK capability on your cluster (see <>) - -. The managed capability recognizes existing ACK-managed {aws} resources and takes over reconciliation - -. Gradually scale down or remove self-managed controller deployments: -+ -[source,bash] ----- -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 resource -* <> - Understand ACK concepts and resource lifecycle -* <> - Configure IAM and permissions diff --git a/latest/ug/capabilities/ack-concepts.adoc b/latest/ug/capabilities/ack-concepts.adoc deleted file mode 100644 index fe3110568..000000000 --- a/latest/ug/capabilities/ack-concepts.adoc +++ /dev/null @@ -1,326 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-concepts] -= ACK concepts -:info_titleabbrev: ACK concepts - -[abstract] --- -Understand core ACK concepts including resource lifecycle, reconciliation, status conditions, and resource ownership. --- - -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 <>), 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. - -[source,yaml,subs="verbatim,attributes,quotes"] ----- -apiVersion: s3.services.k8s.aws/v1alpha1 -kind: Bucket -metadata: - name: my-test-bucket - namespace: default -spec: - name: [.replaceable]`my-unique-bucket-name-12345` ----- - -Apply the manifest: - -[source,bash] ----- -kubectl apply -f bucket.yaml ----- - -Check the status: - -[source,bash] ----- -kubectl get bucket my-test-bucket -kubectl describe bucket my-test-bucket ----- - -Verify the bucket was created in {aws}: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws s3 ls | grep [.replaceable]`my-unique-bucket-name-12345` ----- - -Delete the Kubernetes resource: - -[source,bash] ----- -kubectl delete bucket my-test-bucket ----- - -Verify the bucket was deleted from {aws}: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws s3 ls | grep [.replaceable]`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 link:https://aws-controllers-k8s.github.io/community/docs/user-docs/getting-started/[Getting Started with ACK^]. - -== 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*: - -. You create or update a Kubernetes custom resource (for example, an S3 Bucket) -. ACK detects the change and compares the desired state with the actual state in {aws} -. If they differ, ACK makes {aws} API calls to reconcile the difference -. ACK updates the resource status in Kubernetes to reflect the current state -. 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: - -. Checks if bucket exists in {aws} -. If not, calls `s3:CreateBucket` -. Updates Kubernetes status with bucket ARN and state -. Continues monitoring for drift - -To learn more about how ACK works, see link:https://aws-controllers-k8s.github.io/community/docs/user-docs/reconciliation/[ACK 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: - -[source,bash] ----- -# 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: - -[source,yaml] ----- -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 link:https://aws-controllers-k8s.github.io/community/docs/user-docs/conditions/[ACK 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. - -[source,yaml] ----- -# 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: - -[source,yaml] ----- -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 link:https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/[ACK 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: - -[source,yaml] ----- -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: - -. ACK checks if a bucket with that name exists in {aws} -. If found, ACK adopts it (no API calls to create) -. ACK reads the current configuration from {aws} -. ACK updates the Kubernetes status to reflect the actual state -. 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 link:https://aws-controllers-k8s.github.io/community/docs/user-docs/adopted-resource/[ACK Resource Adoption^]. - -== 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: - -[source,yaml] ----- -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: - -[source,yaml] ----- -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: - -[source,yaml] ----- -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 link:https://aws-controllers-k8s.github.io/docs/guides/cross-account[ACK Cross-Account Resource Management^]. -For cross-account configuration details, see <>. - -== 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`: - -[source,bash] ----- -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 <>. - -== 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 <> - - -== Next steps - -* <> - EKS-specific patterns and integration strategies \ No newline at end of file diff --git a/latest/ug/capabilities/ack-considerations.adoc b/latest/ug/capabilities/ack-considerations.adoc deleted file mode 100644 index e54e549f0..000000000 --- a/latest/ug/capabilities/ack-considerations.adoc +++ /dev/null @@ -1,259 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-considerations] -= ACK considerations for EKS -:info_titleabbrev: Considerations - -[abstract] --- -Plan your ACK deployment with EKS-specific patterns, IAM configuration, and integration strategies. --- - -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: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "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 <>. - - -== 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 <>. - -=== 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 + backup + 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 + SQS queue + notification configuration -* Database setup: RDS instance + parameter group + security group + secrets -* Networking: VPC + subnets + route tables + security groups - -kro handles dependency ordering, status propagation, and lifecycle management for composed resources. -For more on kro, see <>. - -== 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 - -EKS automatically applies tags to {aws} resources managed by ACK, including the capability resource ARN. -Add additional tags for cost allocation, ownership tracking, and organizational purposes. - -*Recommended tags*: - -* Environment (Production, Staging, Development) -* Team or department ownership -* Cost center for billing allocation -* Application or service name -* ManagedBy: ACK (to identify ACK-managed resources) - - -== 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*: - -[source,yaml] ----- -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 <>. - -== 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 - -[source,yaml] ----- -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 <>. - -== Upstream documentation - -For detailed information on using ACK: - -* https://aws-controllers-k8s.github.io/community/docs/user-docs/usage/[ACK usage guide^] - Creating and managing resources -* https://aws-controllers-k8s.github.io/community/reference/[ACK API reference^] - Complete API documentation for all services -* https://aws-controllers-k8s.github.io/community/docs/[ACK documentation^] - Comprehensive user documentation - -== Next steps - -* <> - Configure IAM permissions and multi-account patterns -* <> - Understand ACK concepts and resource lifecycle -* <> - Troubleshoot ACK issues -* <> - Deploy ACK resources with GitOps -* <> - Compose ACK resources into higher-level abstractions diff --git a/latest/ug/capabilities/ack-create-cli.adoc b/latest/ug/capabilities/ack-create-cli.adoc deleted file mode 100644 index 3f0bd9b22..000000000 --- a/latest/ug/capabilities/ack-create-cli.adoc +++ /dev/null @@ -1,141 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-create-cli] -= Create an ACK capability using the {aws} CLI -:info_titleabbrev: {aws} CLI - -This topic describes how to create an {aws} Controllers for Kubernetes (ACK) capability using the {aws} CLI. - -== Prerequisites - -* *{aws} CLI* – Version `{auto-cli-v2-version}` or later. To check your version, run `aws --version`. For more information, see link:cli/latest/userguide/cli-chap-install.html[Installing, updating, and uninstalling the {aws} CLI,type="documentation"] in the {aws} Command Line Interface User Guide. -* *`kubectl`* – A command line tool for working with Kubernetes clusters. For more information, see <>. - -== Step 1: Create an IAM Capability Role - -Create a trust policy file: - -[source,bash,subs="verbatim,attributes"] ----- -cat > ack-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -aws iam create-role \ - --role-name ACKCapabilityRole \ - --assume-role-policy-document file://ack-trust-policy.json ----- - -Attach the `AdministratorAccess` managed policy to the role: - -[source,bash,subs="verbatim,attributes"] ----- -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 <> and <>. -==== - -== Step 2: Create the ACK capability - -Create the ACK capability resource on your cluster. Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks create-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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 [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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: - -[source,bash,subs="verbatim,attributes"] ----- -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 - -* <> - Understand ACK concepts and get started -* <> - Configure IAM permissions for other {aws} services -* <> - Manage your ACK capability resource diff --git a/latest/ug/capabilities/ack-create-console.adoc b/latest/ug/capabilities/ack-create-console.adoc deleted file mode 100644 index d3767b418..000000000 --- a/latest/ug/capabilities/ack-create-console.adoc +++ /dev/null @@ -1,83 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-create-console] -= Create an ACK capability using the Console -:info_titleabbrev: Console - -This topic describes how to create an {aws} Controllers for Kubernetes (ACK) capability using the {aws-management-console}. - -== Create the ACK capability - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. - -. Select your cluster name to open the cluster detail page. - -. Choose the *Capabilities* tab. - -. In the left navigation, choose *{aws} Controllers for Kubernetes (ACK)*. - -. Choose *Create {aws} Controllers for Kubernetes capability*. - -. 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 <> and <>. -==== - -. Choose *Create*. - -The capability creation process begins. - -== Verify the capability is active - -. On the *Capabilities* tab, view the ACK capability status. - -. Wait for the status to change from `CREATING` to `ACTIVE`. - -. Once active, the capability is ready to use. - -For information about capability statuses and troubleshooting, see <>. - -== Verify custom resources are available - -After the capability is active, verify that ACK custom resources are available in your cluster. - -*Using the console* - -. Navigate to your cluster in the Amazon EKS console -. Choose the *Resources* tab -. Choose *Extensions* -. Choose *CustomResourceDefinitions* - -You should see a number of CRDs listed for {aws} resources. - -*Using kubectl* - -[source,bash,subs="verbatim,attributes"] ----- -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 - -* <> - Understand ACK concepts and get started -* <> - Configure IAM permissions for other {aws} services -* <> - Manage your ACK capability resource diff --git a/latest/ug/capabilities/ack-create-eksctl.adoc b/latest/ug/capabilities/ack-create-eksctl.adoc deleted file mode 100644 index 090d2b6d8..000000000 --- a/latest/ug/capabilities/ack-create-eksctl.adoc +++ /dev/null @@ -1,147 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-create-eksctl] -= Create an ACK capability using eksctl -:info_titleabbrev: 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: - -[source,bash,subs="verbatim,attributes"] ----- -cat > ack-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -aws iam create-role \ - --role-name ACKCapabilityRole \ - --assume-role-policy-document file://ack-trust-policy.json ----- - -Attach the `AdministratorAccess` managed policy to the role: - -[source,bash,subs="verbatim,attributes"] ----- -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 <> and <>. -==== - -[IMPORTANT] -==== -This policy grants permissions for S3 bucket management with `"Resource": "*"`, which allows operations on all S3 buckets. - -For production use: -* Restrict the `Resource` field to specific bucket ARNs or name patterns -* Use IAM condition keys to limit access by resource tags -* Grant only the minimum permissions needed for your use case - -For other {aws} services, see <>. -==== - -Attach the policy to the role: - -[source,bash,subs="verbatim,attributes"] ----- -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 [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes"] ----- -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: - -[source,bash,subs="verbatim,attributes"] ----- -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: - -[source,bash,subs="verbatim,attributes"] ----- -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 - -* <> - Understand ACK concepts and get started -* <> - Configure IAM permissions for other {aws} services -* <> - Manage your ACK capability resource diff --git a/latest/ug/capabilities/ack-permissions.adoc b/latest/ug/capabilities/ack-permissions.adoc deleted file mode 100644 index 41e36e3ab..000000000 --- a/latest/ug/capabilities/ack-permissions.adoc +++ /dev/null @@ -1,255 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-permissions] -= Configure ACK permissions -:info_titleabbrev: Configure permissions - -[abstract] --- -Configure IAM permissions for ACK to manage {aws} resources using Capability Roles and IAM Role Selectors. --- - -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: - -. Check if an IAMRoleSelector matches the resource's namespace -. If a match is found, assume that IAM role -. 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` permission 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: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:*" - ], - "Resource": "*" - } - ] -} ----- - -Configure the trust policy to allow the Capability Role to assume it: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole" - }, - "Action": "sts:AssumeRole" - } - ] -} ----- - -*Step 2: Grant AssumeRole permission to Capability Role* - -Add permission to the Capability Role to assume the service-specific role: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam::111122223333:role/ACK-S3-Role" - } - ] -} ----- - -*Step 3: Create IAMRoleSelector* - -Map the IAM role to a namespace: - -[source,yaml] ----- -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: - -[source,yaml] ----- -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: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole" - }, - "Action": "sts:AssumeRole" - } - ] -} ----- - -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: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam::444455556666:role/ACKTargetAccountRole" - } - ] -} ----- - -*Step 3: Create IAMRoleSelector* - -Map the cross-account role to a namespace: - -[source,yaml] ----- -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: - -[source,yaml] ----- -apiVersion: s3.services.k8s.aws/v1alpha1 -kind: Bucket -metadata: - name: my-bucket - namespace: production -spec: - name: my-cross-account-bucket ----- - - -== Advanced IAM Role Selector patterns - -For advanced configuration including label selectors, resource-specific role mapping, and additional examples, see link:https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/[ACK IRSA Documentation^]. - -== Next steps - -* <> - Understand ACK concepts and resource lifecycle -* <> - Learn about resource adoption and deletion policies -* <> - Understand security best practices for capabilities diff --git a/latest/ug/capabilities/ack-troubleshooting.adoc b/latest/ug/capabilities/ack-troubleshooting.adoc deleted file mode 100644 index d4275a285..000000000 --- a/latest/ug/capabilities/ack-troubleshooting.adoc +++ /dev/null @@ -1,184 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack-troubleshooting] -= Troubleshoot issues with ACK capabilities -:info_titleabbrev: Troubleshooting - -[abstract] --- -Diagnose and resolve common issues with the EKS Capability for ACK. --- - -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*: - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name. -. Choose the *Observability* tab. -. Choose *Monitor cluster*. -. Choose the *Capabilities* tab to view health and status for all capabilities. - -*{aws} CLI*: - -[source,bash] ----- -# 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*: - -[source,bash] ----- -# 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*: - -[source,bash,subs="verbatim,quotes"] ----- -# View the Capability Role's policies -aws iam list-attached-role-policies --role-name [.replaceable]`my-ack-capability-role` -aws iam list-role-policies --role-name [.replaceable]`my-ack-capability-role` - -# Get specific policy details -aws iam get-role-policy --role-name [.replaceable]`my-ack-capability-role` --policy-name [.replaceable]`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. - -[source,yaml] ----- -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 <>. - -== 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*: - -[source,bash,subs="verbatim,quotes"] ----- -# Check the trust policy in the target account role -aws iam get-role --role-name [.replaceable]`cross-account-ack-role` --query 'Role.AssumeRolePolicyDocument' ----- - -The trust policy must allow the source account's Capability Role to assume it. - -*Confirm IAMRoleSelector configuration*: - -[source,bash] ----- -# 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: - -[source,bash,subs="verbatim,quotes"] ----- -# Check resource namespace -kubectl get bucket [.replaceable]`my-cross-account-bucket` -n [.replaceable]`production` - -# List all IAMRoleSelectors (cluster-scoped) -kubectl get iamroleselector - -# Check which namespace the selector targets -kubectl get iamroleselector [.replaceable]`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: - -[source,bash,subs="verbatim,quotes"] ----- -# Check if IAMRoleSelector was matched -kubectl get bucket [.replaceable]`my-cross-account-bucket` -n [.replaceable]`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` permission for the target account role: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`" - } - ] -} ----- - -For detailed cross-account configuration, see <>. - -== Next steps - -* <> - ACK considerations and best practices -* <> - Configure IAM permissions and multi-account patterns -* <> - Understand ACK concepts and resource lifecycle -* <> - General capability troubleshooting guidance diff --git a/latest/ug/capabilities/ack.adoc b/latest/ug/capabilities/ack.adoc deleted file mode 100644 index badc624d0..000000000 --- a/latest/ug/capabilities/ack.adoc +++ /dev/null @@ -1,106 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ack] -= Deploy {aws} resources from Kubernetes with {aws} Controllers for Kubernetes (ACK) -:info_titleabbrev: {aws} Controllers for Kubernetes - -[abstract] --- -Manage {aws} resources natively in Kubernetes with {aws} Controllers for Kubernetes (ACK), a fully managed capability of Amazon EKS. --- - -{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* - -[source,yaml,subs="verbatim,attributes,quotes"] ----- -apiVersion: s3.services.k8s.aws/v1alpha1 -kind: Bucket -metadata: - name: my-ack-bucket -spec: - name: [.replaceable]`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 <> and <>. - -== 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 https://aws-controllers-k8s.github.io/community/docs/community/services/[full list of {aws} services supported] 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: - -. Create and configure an IAM Capability Role with the necessary permissions for ACK to manage {aws} resources on your behalf. -. <> on your EKS cluster through the {aws} Console, {aws} CLI, or your preferred infrastructure as code tool. -. Apply Kubernetes custom resources to your cluster to start managing your {aws} resources in Kubernetes. - -include::create-ack-capability.adoc[leveloffset=+1] - -include::ack-concepts.adoc[leveloffset=+1] - -include::ack-permissions.adoc[leveloffset=+1] - -include::ack-considerations.adoc[leveloffset=+1] - -include::ack-troubleshooting.adoc[leveloffset=+1] - -include::ack-comparison.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/argocd-applicationsets.adoc b/latest/ug/capabilities/argocd-applicationsets.adoc deleted file mode 100644 index dae02562a..000000000 --- a/latest/ug/capabilities/argocd-applicationsets.adoc +++ /dev/null @@ -1,339 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-applicationsets] -= Use ApplicationSets -:info_titleabbrev: ApplicationSets - -[abstract] --- -Deploy applications across multiple environments or clusters using ApplicationSet templates and generators. --- - -ApplicationSets generate multiple Applications from templates, enabling you to deploy the same application across multiple clusters, environments, or namespaces with a single resource definition. - -== Prerequisites - -* An EKS cluster with the Argo CD capability created -* Multiple target clusters registered (see <>) -* Repository access configured (see <>) -* `kubectl` configured to communicate with your cluster - -== How ApplicationSets work - -ApplicationSets use generators to produce parameters, then apply those parameters to an Application template. -Each set of generated parameters creates one Application. - -Common generators for EKS deployments: - -* *List generator* - Explicitly define clusters and parameters for each environment -* *Cluster generator* - Automatically deploy to all registered clusters -* *Git generator* - Generate Applications from repository structure -* *Matrix generator* - Combine generators for multi-dimensional deployments - -For complete generator reference, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/[ApplicationSet Documentation^]. - -== List generator - -Deploy to multiple clusters with explicit configuration: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: guestbook-all-clusters - namespace: argocd -spec: - generators: - - list: - elements: - - cluster: arn:aws:eks:us-west-2:111122223333:cluster/dev-cluster - environment: dev - replicas: "2" - - cluster: arn:aws:eks:us-west-2:111122223333:cluster/staging-cluster - environment: staging - replicas: "3" - - cluster: arn:aws:eks:us-west-2:111122223333:cluster/prod-cluster - environment: prod - replicas: "5" - template: - metadata: - name: 'guestbook-{{environment}}' - spec: - project: default - source: - repoURL: https://github.com/example/guestbook - targetRevision: HEAD - path: 'overlays/{{environment}}' - destination: - server: '{{cluster}}' - namespace: guestbook - syncPolicy: - automated: - prune: true - selfHeal: true ----- - -[NOTE] -==== -Use EKS cluster ARNs in the `server` field when targeting registered EKS clusters. -You can also use cluster names with `destination.name` instead of `destination.server`. -==== - -This creates three Applications: `guestbook-dev`, `guestbook-staging`, and `guestbook-prod`. - -== Cluster generator - -Deploy to all registered clusters automatically: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: cluster-addons - namespace: argocd -spec: - generators: - - clusters: {} - template: - metadata: - name: '{{name}}-addons' - spec: - project: default - source: - repoURL: https://github.com/example/cluster-addons - targetRevision: HEAD - path: addons - destination: - server: '{{server}}' - namespace: kube-system - syncPolicy: - automated: - prune: true - selfHeal: true ----- - -This automatically creates an Application for each registered cluster. - -*Filter clusters*: - -[source,yaml] ----- -spec: - generators: - - clusters: - selector: - matchLabels: - environment: production ----- - -== Git generators - -Git generators create Applications based on repository structure: - -* *Directory generator* - Deploy each directory as a separate Application (useful for microservices) -* *File generator* - Generate Applications from parameter files (useful for multi-tenant deployments) - -*Example: Microservices deployment* - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: microservices - namespace: argocd -spec: - generators: - - git: - repoURL: https://github.com/example/microservices - revision: HEAD - directories: - - path: services/* - template: - metadata: - name: '{{path.basename}}' - spec: - project: default - source: - repoURL: https://github.com/example/microservices - targetRevision: HEAD - path: '{{path}}' - destination: - server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster - namespace: '{{path.basename}}' - syncPolicy: - automated: - prune: true - selfHeal: true - syncOptions: - - CreateNamespace=true ----- - -For details on Git generators and file-based configuration, see link:https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Git/[Git Generator] in the Argo CD documentation. - -== Matrix generator - -Combine multiple generators to deploy across multiple dimensions (environments × clusters): - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: multi-env-multi-cluster - namespace: argocd -spec: - generators: - - matrix: - generators: - - list: - elements: - - environment: dev - - environment: staging - - environment: prod - - clusters: - selector: - matchLabels: - region: us-west-2 - template: - metadata: - name: 'app-{{environment}}-{{name}}' - spec: - project: default - source: - repoURL: https://github.com/example/app - targetRevision: HEAD - path: 'overlays/{{environment}}' - destination: - server: '{{server}}' - namespace: 'app-{{environment}}' ----- - -For details on combining generators, see link:https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Matrix/[Matrix Generator] in the Argo CD documentation. - -== Progressive rollout - -Deploy to environments sequentially with different sync policies: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: progressive-rollout - namespace: argocd -spec: - generators: - - list: - elements: - - environment: dev - autoSync: "true" - - environment: staging - autoSync: "true" - - environment: prod - autoSync: "false" - template: - metadata: - name: 'app-{{environment}}' - spec: - project: default - source: - repoURL: https://github.com/example/app - targetRevision: HEAD - path: 'overlays/{{environment}}' - destination: - server: arn:aws:eks:us-west-2:111122223333:cluster/{{environment}}-cluster - namespace: app - syncPolicy: - automated: - prune: true - selfHeal: '{{autoSync}}' ----- - -Dev and staging sync automatically, while production requires manual approval. - -== Multi-region deployment - -Deploy to clusters across multiple regions: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: ApplicationSet -metadata: - name: global-app - namespace: argocd -spec: - generators: - - list: - elements: - - cluster: arn:aws:eks:us-west-2:111122223333:cluster/prod-us-west - region: us-west-2 - - cluster: arn:aws:eks:us-east-1:111122223333:cluster/prod-us-east - region: us-east-1 - - cluster: arn:aws:eks:eu-west-1:111122223333:cluster/prod-eu-west - region: eu-west-1 - template: - metadata: - name: 'app-{{region}}' - spec: - project: default - source: - repoURL: https://github.com/example/app - targetRevision: HEAD - path: kubernetes - helm: - parameters: - - name: region - value: '{{region}}' - destination: - server: '{{cluster}}' - namespace: app - syncPolicy: - automated: - prune: true - selfHeal: true ----- - -== Manage ApplicationSets - -*View ApplicationSets and generated Applications*: - -[source,bash] ----- -kubectl get applicationsets -n argocd -kubectl get applications -n argocd -l argocd.argoproj.io/application-set-name= ----- - -*Update an ApplicationSet*: - -Modify the ApplicationSet spec and reapply. -Argo CD automatically updates all generated Applications: - -[source,bash] ----- -kubectl apply -f applicationset.yaml ----- - -*Delete an ApplicationSet*: - -[source,bash] ----- -kubectl delete applicationset -n argocd ----- - -[WARNING] -==== -Deleting an ApplicationSet deletes all generated Applications. -If those Applications have `prune: true`, their resources will also be deleted from target clusters. -==== - -== Additional resources - -* <> - Organize ApplicationSets with Projects -* <> - Understand Application configuration -* link:https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/[ApplicationSet Documentation^] - Complete generator reference and patterns -* link:https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/[Generator Reference^] - Detailed generator specifications diff --git a/latest/ug/capabilities/argocd-comparison.adoc b/latest/ug/capabilities/argocd-comparison.adoc deleted file mode 100644 index c38db40ac..000000000 --- a/latest/ug/capabilities/argocd-comparison.adoc +++ /dev/null @@ -1,144 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-comparison] -= Comparing EKS Capability for Argo CD to self-managed Argo CD -:info_titleabbrev: Comparison to self-managed - -[abstract] --- -Understand the differences between the EKS Capability for Argo CD and self-managed Argo CD installations. -This comparison helps you choose the right deployment model for your GitOps workflows. --- - -The EKS Capability for Argo CD provides a fully managed Argo CD experience that runs in EKS. -For a general comparison of EKS Capabilities vs self-managed solutions, see <>. -This topic focuses on Argo CD-specific differences, including authentication, multi-cluster management, and upstream feature support. - -== Differences from upstream Argo CD - -The EKS Capability for Argo CD is based on upstream Argo CD but differs in how it's accessed, configured, and integrated with {aws} services. - -*RBAC and authentication*: The capability comes with three RBAC roles (admin, editor, viewer) and uses {aws} Identity Center for authentication instead of Argo CD's built-in authentication. Configure role mappings through the capability's `rbacRoleMapping` parameter to map Identity Center groups to Argo CD roles, not through Argo CD's `argocd-rbac-cm` ConfigMap. The Argo CD UI is hosted with its own direct URL (find it in the EKS console under your cluster's Capabilities tab), and API access uses {aws} authentication and authorization through IAM. - -*Cluster configuration*: The capability does not automatically configure local cluster or hub-and-spoke topologies. You configure your deployment target clusters and EKS access entries. The capability supports only Amazon EKS clusters as deployment targets using EKS cluster ARNs (not Kubernetes API server URLs). The capability does not automatically add the local cluster (`kubernetes.default.svc`) as a deployment target—to deploy to the same cluster where the capability is created, explicitly register that cluster using its ARN. - -*Simplified remote cluster access*: The capability simplifies multi-cluster deployments by using EKS Access Entries to grant Argo CD access to remote clusters, eliminating the need to configure IAM Roles for Service Accounts (IRSA) or set up cross-account IAM role assumptions. The capability also provides transparent access to fully private EKS clusters without requiring VPC peering or specialized networking configuration—{aws} manages connectivity between the Argo CD capability and private remote clusters automatically. - -*Direct {aws} service integration*: The capability provides direct integration with {aws} services through the Capability Role's IAM permissions. You can reference CodeCommit repositories, ECR Helm charts, and CodeConnections directly in Application resources without creating Repository configurations. This simplifies authentication and eliminates the need to manage separate credentials for {aws} services. See <> for details. - -*Namespace support*: The capability initially supports deploying applications to a single namespace, which you specify when creating the capability. Support for applications in multiple namespaces may be added in future releases. - -*Unsupported features*: The following features are not available in the managed capability: - -* Config Management Plugins (CMPs) for custom manifest generation -* Custom Lua scripts for resource health assessment (built-in health checks for standard resources are supported) -* The Notifications controller -* Argo CD Image Updater -* Custom SSO providers (only {aws} Identity Center is supported, including third-party federated identity through {aws} Identity Center) -* UI extensions and custom banners -* Direct access to `argocd-cm`, `argocd-params`, and other configuration ConfigMaps - -*Compatibility*: Applications and ApplicationSets work identically to upstream Argo CD with no changes to your manifests. The capability uses the same Kubernetes APIs and CRDs, so tools like `kubectl` work the same way. The capability fully supports Applications and ApplicationSets, GitOps workflows with automatic sync, multi-cluster deployments, sync policies (automated, prune, self-heal), sync waves and hooks, health assessment for standard Kubernetes resources, rollback capabilities, Git repository sources (HTTPS and SSH), Helm, Kustomize, and plain YAML manifests, GitHub app credentials, projects for multi-tenancy, and resource exclusions and inclusions. - - -[#argocd-cli-configuration] -== Using the Argo CD CLI with the managed capability - -The Argo CD CLI works the same as upstream Argo CD for most operations, but authentication and cluster registration differ. - -=== Prerequisites - -Install the Argo CD CLI following the https://argo-cd.readthedocs.io/en/stable/cli_installation/[upstream installation instructions^]. - -=== Configuration - -Configure the CLI using environment variables: - -. Get the Argo CD server URL from the EKS console (under your cluster's *Capabilities* tab), or using the {aws} CLI: -+ -[source,bash,subs="verbatim,attributes,quotes"] ----- -export ARGOCD_SERVER=$(aws eks describe-capability \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name [.replaceable]`my-argocd` \ - --query 'capability.configuration.argoCd.serverUrl' \ - --output text \ - --region [.replaceable]`region-code`) ----- - -. Generate an account token from the Argo CD UI (*Settings* → *Accounts* → *admin* → *Generate New Token*), then set it as an environment variable: -+ -[source,bash] ----- -export ARGOCD_AUTH_TOKEN="your-token-here" ----- - -[IMPORTANT] -==== -This configuration uses the admin account token for initial setup and development workflows. -For production use cases, use project-scoped roles and tokens to follow the principle of least privilege. -For more information about configuring project roles and RBAC, see <>. -==== - - -. Set the required gRPC option: -+ -[source,bash] ----- -export ARGOCD_OPTS="--grpc-web" ----- - -With these environment variables set, you can use the Argo CD CLI without the `argocd login` command. - -=== Key differences - -The managed capability has the following CLI limitations: - -* `argocd admin` commands are not supported (they require direct pod access) -* `argocd login` is not supported (use account or project tokens instead) -* `argocd cluster add` requires the `--aws-cluster-name` flag with the EKS cluster ARN - -=== Example: Register a cluster - -Register an EKS cluster for application deployment: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -# Get the cluster ARN -CLUSTER_ARN=$(aws eks describe-cluster \ - --name [.replaceable]`my-cluster` \ - --query 'cluster.arn' \ - --output text) - -# Register the cluster -argocd cluster add $CLUSTER_ARN \ - --aws-cluster-name $CLUSTER_ARN \ - --name in-cluster \ - --project default ----- - -For complete Argo CD CLI documentation, see the https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/[Argo CD CLI reference^]. - -== Migration Path - -You can migrate from self-managed Argo CD to the managed capability: - -. Review your current Argo CD configuration for unsupported features (Notifications controller, CMPs, custom health checks) -. Scale your self-managed Argo CD controllers to zero replicas -. Create an Argo CD capability resource on your cluster -. Export your existing Applications, ApplicationSets, and AppProjects -. Migrate repository credentials, cluster secrets, and repository credential templates (repocreds) -. If using GPG keys, TLS certificates, or SSH known hosts, migrate these configurations as well -. Update `destination.server` fields to use cluster names or EKS cluster ARNs -. Apply them to the managed Argo CD instance -. Verify applications are syncing correctly -. Decommission your self-managed Argo CD installation - -The managed capability uses the same Argo CD APIs and resource definitions, so your existing manifests work with minimal modification. - -== Next steps - -* <> - Create an Argo CD capability resource -* <> - Deploy your first application -* <> - Configure {aws} Identity Center integration diff --git a/latest/ug/capabilities/argocd-concepts.adoc b/latest/ug/capabilities/argocd-concepts.adoc deleted file mode 100644 index b9640ad88..000000000 --- a/latest/ug/capabilities/argocd-concepts.adoc +++ /dev/null @@ -1,274 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-concepts] -= Argo CD concepts -:info_titleabbrev: Argo CD concepts - -[abstract] --- -Learn Argo CD fundamentals through a practical example, then explore core concepts including GitOps principles, sync behavior, and multi-cluster patterns. --- - -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 <>), 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): - -[source,bash] ----- -# 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 <>. -==== - -Alternatively, register the cluster using a Kubernetes Secret (see <> 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 <> 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 <> for details. - -=== Step 2: Create an Application - -Create this Application manifest in `my-app.yaml`: - -[source,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: - -[source,bash] ----- -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: - -[source,bash] ----- -kubectl get application guestbook -n argocd ----- - -You can also view the application using the Argo CD CLI (`argocd app get guestbook`) or the Argo CD UI (accessible from the EKS console under your cluster's Capabilities tab). - -[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 link:https://argo-cd.readthedocs.io/en/stable/user-guide/application-sources/[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) -2. Compares desired state with cluster state -3. Marks applications as `Synced` or `OutOfSync` -4. Syncs changes automatically (if configured) or waits for manual approval -5. Monitors resource health after sync - -*Sync waves* control resource creation order using annotations: - -[source,yaml] ----- -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`). -This allows you to create dependencies like namespaces (wave `-1`) before deployments (wave `0`). - -*Self-healing* automatically reverts manual changes: - -[source,yaml] ----- -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 https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/[Argo CD sync documentation^]. - -=== Application health - -Argo CD monitors the health of all resources in your application: - -*Health statuses*: -* *Healthy* - All resources running as expected -* *Progressing* - Resources being created or updated -* *Degraded* - Some resources not healthy (pods crashing, jobs failing) -* *Suspended* - Application intentionally paused -* *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 link:https://argo-cd.readthedocs.io/en/stable/operator-manual/health/[Resource 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: -* Centralized control and visibility -* Consistent policies across all clusters -* One Argo CD instance to manage -* Clear separation between control plane and workloads - -*Per-cluster* - Run Argo CD on each cluster, managing only that cluster's applications: -* Cluster separation (one failure doesn't affect others) -* Simpler networking (no cross-cluster communication) -* 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 <>. - -=== 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 - -All Applications belong to a project. If not specified, they use the `default` project (which has no restrictions). For production, create projects with appropriate restrictions. - -For project configuration and RBAC patterns, see <>. - -=== Repository organization - -Most teams use directory-based organization with Kustomize overlays or Helm values files for different environments: - -[source,text] ----- -my-app/ -├── base/ -│ ├── deployment.yaml -│ └── service.yaml -└── overlays/ - ├── dev/ - │ └── kustomization.yaml - ├── staging/ - │ └── kustomization.yaml - └── prod/ - └── kustomization.yaml ----- - -This approach provides flexibility and clarity while keeping all environment configurations in a single repository. - -For detailed repository structure patterns and best practices, see the https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/[Argo CD best practices documentation^]. - -=== 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) - -[source,yaml] ----- -spec: - syncPolicy: - syncOptions: - - CreateNamespace=true - - ServerSideApply=true ----- - -For a complete list of sync options, see the https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/[Argo CD sync options documentation^]. - -== Next steps - -* <> - Configure Git repository access -* <> - Register target clusters for deployment -* <> - Create your first Application -* <> - EKS-specific patterns, Identity Center integration, and multi-cluster configuration -* link:https://argo-cd.readthedocs.io/en/stable/[Argo CD Documentation^] - Comprehensive Argo CD documentation including sync hooks, health checks, and advanced patterns diff --git a/latest/ug/capabilities/argocd-configure-repositories.adoc b/latest/ug/capabilities/argocd-configure-repositories.adoc deleted file mode 100644 index 7c7d3739d..000000000 --- a/latest/ug/capabilities/argocd-configure-repositories.adoc +++ /dev/null @@ -1,466 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-configure-repositories] -= Configure repository access -:info_titleabbrev: Configure repositories - -[abstract] --- -Configure Argo CD to access your Git repositories using various authentication methods. --- - -Before deploying applications, configure Argo CD to access your Git repositories and Helm chart registries. -Argo CD supports multiple authentication methods for GitHub, GitLab, Bitbucket, {aws} CodeCommit, and {aws} ECR. - -[NOTE] -==== -For direct {aws} service integrations (ECR Helm charts, CodeCommit repositories, and CodeConnections), you can reference them directly in Application resources without creating Repository configurations. -The Capability Role must have the required IAM permissions. -See <> for details. -==== - -== Prerequisites - -* An EKS cluster with the Argo CD capability created -* Git repositories containing Kubernetes manifests -* `kubectl` configured to communicate with your cluster - -[NOTE] -==== -For credential reuse across multiple repositories, you can use repository credential templates (repocreds). For more information, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/[Private Repositories^] in the Argo CD documentation. -==== - -== Authentication methods - -[cols="1,2,2",options="header"] -|=== -|Method -|Use Case -|IAM Permissions Required - -3+^|*Direct integration with {aws} services* - -|CodeCommit -|Direct integration with {aws} CodeCommit Git repositories. No Repository configuration needed. -|`codecommit:GitPull` - -|CodeConnections -|Connect to GitHub, GitLab, or Bitbucket with managed authentication. Requires connection setup. -|`codeconnections:UseConnection` - -|ECR Helm Charts -|Direct integration with {aws} ECR for OCI Helm charts. No Repository configuration needed. -|`ecr:GetAuthorizationToken`, `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer` - -3+^|*Repository configuration with credentials* - -|{aws} Secrets Manager (Username/Token) -|Store personal access tokens or passwords -|`secretsmanager:GetSecretValue` - -|{aws} Secrets Manager (SSH Key) -|Use SSH key authentication -|`secretsmanager:GetSecretValue` - -|{aws} Secrets Manager (GitHub App) -|GitHub App authentication with private key -|`secretsmanager:GetSecretValue` - -|Kubernetes Secret -|Standard Argo CD method using in-cluster secrets -|None (trust policy only) -|=== - -== Direct access to {aws} services - -For {aws} services, you can reference them directly in Application resources without creating Repository configurations. -The Capability Role must have the required IAM permissions. - -=== CodeCommit repositories - -Reference CodeCommit repositories directly in Applications: - -[source,yaml,subs="verbatim,quotes"] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app - namespace: argocd -spec: - source: - repoURL: https://git-codecommit.[.replaceable]`region`.amazonaws.com/v1/repos/[.replaceable]`repository-name` - targetRevision: main - path: kubernetes/manifests ----- - -Required Capability Role permissions: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "codecommit:GitPull", - "Resource": "arn:aws:codecommit:region:account-id:repository-name" - } - ] -} ----- - -=== CodeConnections - -Reference GitHub, GitLab, or Bitbucket repositories through CodeConnections. -The repository URL format is derived from the CodeConnections connection ARN. - -The repository URL format is: -[source,yaml,subs="verbatim,quotes"] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app - namespace: argocd -spec: - source: - repoURL: https://codeconnections.[.replaceable]`region`.amazonaws.com/git-http/[.replaceable]`account-id`/[.replaceable]`region`/[.replaceable]`connection-id`/[.replaceable]`owner`/[.replaceable]`repository`.git - targetRevision: main - path: kubernetes/manifests ----- - -Required Capability Role permissions: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "codeconnections:UseConnection", - "Resource": "arn:aws:codeconnections:region:account-id:connection/connection-id" - } - ] -} ----- - -=== ECR Helm charts - -ECR stores Helm charts as OCI artifacts. Argo CD supports two ways to reference them: - -*Helm format* (recommended for Helm charts): - -[source,yaml,subs="verbatim,quotes"] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app-helm - namespace: argocd -spec: - source: - repoURL: [.replaceable]`account-id`.dkr.ecr.[.replaceable]`region`.amazonaws.com/[.replaceable]`repository-name` - targetRevision: [.replaceable]`chart-version` - chart: [.replaceable]`chart-name` - helm: - valueFiles: - - values.yaml ----- - -Note: Do not include the `oci://` prefix when using Helm format. Use the `chart` field to specify the chart name. - -*OCI format* (for OCI artifacts with Kubernetes manifests): - -[source,yaml,subs="verbatim,quotes"] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app-oci - namespace: argocd -spec: - source: - repoURL: oci://[.replaceable]`account-id`.dkr.ecr.[.replaceable]`region`.amazonaws.com/[.replaceable]`repository-name` - targetRevision: [.replaceable]`artifact-version` - path: [.replaceable]`path-to-manifests` ----- - -Note: Include the `oci://` prefix when using OCI format. Use the `path` field instead of `chart`. - -Required Capability Role permissions: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ecr:GetAuthorizationToken", - "ecr:BatchGetImage", - "ecr:GetDownloadUrlForLayer" - ], - "Resource": "*" - } - ] -} ----- - -== Using {aws} Secrets Manager - -Store repository credentials in Secrets Manager and reference them in Argo CD Repository configurations. - -=== Username and token authentication - -For HTTPS repositories with personal access tokens or passwords: - -*Create the secret in Secrets Manager*: - -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/my-repo \ - --description "GitHub credentials for Argo CD" \ - --secret-string '{"username":"your-username","token":"your-personal-access-token"}' ----- - -*Optional TLS client certificate fields* (for private Git servers): - -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/my-private-repo \ - --secret-string '{ - "username":"your-username", - "token":"your-token", - "tlsClientCertData":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi4uLgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t", - "tlsClientCertKey":"LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi4uLgotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0t" - }' ----- - -[NOTE] -==== -The `tlsClientCertData` and `tlsClientCertKey` values must be base64 encoded. -==== - -*Create a Repository Secret referencing Secrets Manager*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: my-repo - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: https://github.com/your-org/your-repo - secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-AbCdEf - project: default ----- - -=== SSH key authentication - -For SSH-based Git access, store the private key as plaintext (not JSON): - -*Create the secret with SSH private key*: - -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/my-repo-ssh \ - --description "SSH key for Argo CD" \ - --secret-string "-----BEGIN OPENSSH PRIVATE KEY----- -b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn -... ------END OPENSSH PRIVATE KEY-----" ----- - -*Create a Repository Secret for SSH*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: my-repo-ssh - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: git@github.com:your-org/your-repo.git - secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-ssh-AbCdEf - project: default ----- - -=== GitHub App authentication - -For GitHub App authentication with a private key: - -*Create the secret with GitHub App credentials*: - -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/github-app \ - --description "GitHub App credentials for Argo CD" \ - --secret-string '{ - "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=", - "githubAppID":"123456", - "githubAppInstallationID":"12345678" - }' ----- - -[NOTE] -==== -The `githubAppPrivateKeySecret` value must be base64 encoded. -==== - -*Optional field for GitHub Enterprise*: - -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/github-enterprise-app \ - --secret-string '{ - "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=", - "githubAppID":"123456", - "githubAppInstallationID":"12345678", - "githubAppEnterpriseBaseUrl":"https://github.example.com/api/v3" - }' ----- - -*Create a Repository Secret for GitHub App*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: my-repo-github-app - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: https://github.com/your-org/your-repo - secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/github-app-AbCdEf - project: default ----- - -[IMPORTANT] -==== -Ensure your IAM Capability Role has `secretsmanager:GetSecretValue` permissions for the secrets you create. -See <> for IAM policy configuration. -==== - -== Using {aws} CodeConnections - -For CodeConnections integration, see <>. - -CodeConnections provides managed authentication for GitHub, GitLab, and Bitbucket without storing credentials. - -== Using Kubernetes Secrets - -Store credentials directly in Kubernetes using the standard Argo CD method. - -*For HTTPS with personal access token*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: my-repo - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: https://github.com/your-org/your-repo - username: your-username - password: your-personal-access-token ----- - -*For SSH*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: my-repo-ssh - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: git@github.com:your-org/your-repo.git - sshPrivateKey: | - -----BEGIN OPENSSH PRIVATE KEY----- - ... your private key ... - -----END OPENSSH PRIVATE KEY----- ----- - -== Public repositories - -No additional configuration needed for public repositories: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: public-app - namespace: argocd -spec: - source: - repoURL: https://github.com/argoproj/argocd-example-apps - targetRevision: HEAD - path: guestbook - # ... rest of configuration ----- - -== CodeCommit repositories - -For {aws} CodeCommit, grant your IAM Capability Role CodeCommit permissions (`codecommit:GitPull`). - -Configure the repository: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: codecommit-repo - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: https://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo - project: default ----- - -For detailed IAM policy configuration, see <>. - -== Verify repository connection - -Check connection status through the Argo CD UI under Settings → Repositories. -The UI shows connection status and any authentication errors. - -Repository Secrets do not include status information. - -== Additional resources - -* <> - Register target clusters for deployments -* <> - Create your first Application -* <> - IAM permissions and security configuration -* link:https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/[Private Repositories^] - Upstream repository configuration reference diff --git a/latest/ug/capabilities/argocd-considerations.adoc b/latest/ug/capabilities/argocd-considerations.adoc deleted file mode 100644 index 3039da9eb..000000000 --- a/latest/ug/capabilities/argocd-considerations.adoc +++ /dev/null @@ -1,362 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-considerations] -= Argo CD considerations -:info_titleabbrev: Argo CD considerations - -[abstract] --- -Plan your Argo CD deployment, configure IAM permissions, set up authentication with {aws} Identity Center, and enable multi-cluster deployments. --- - -This topic covers important considerations for using the EKS Capability for Argo CD, including planning, permissions, authentication, and multi-cluster deployment patterns. - -== Planning - -Before deploying Argo CD, consider the following: - -*Repository strategy*: Determine where your application manifests will be stored (CodeCommit, GitHub, GitLab, Bitbucket). -Plan your repository structure and branching strategy for different environments. - -*Authentication method*: Decide whether to use {aws} Identity Center for SSO or manage Argo CD users directly. -SSO is recommended for production environments. - -*RBAC strategy*: Plan which teams or users should have admin, editor, or viewer access. -Map these to {aws} Identity Center groups or Argo CD roles. - -*Multi-cluster architecture*: Determine if you'll manage multiple clusters from a single Argo CD instance. -Consider using a dedicated management cluster for Argo CD. - -*Application organization*: Plan how you'll structure Applications and ApplicationSets. -Consider using projects to organize applications by team or environment. - -*Sync policies*: Decide whether applications should sync automatically or require manual approval. -Automated sync is common for development, manual for production. - -== Permissions - -For detailed information about IAM Capability Roles, trust policies, and security best practices, see <> and <>. - -=== IAM Capability Role overview - -When you create an Argo CD capability resource, you provide an IAM Capability Role. -Unlike ACK, Argo CD primarily manages Kubernetes resources, not {aws} resources directly. -However, the IAM role is required for: - -* Accessing private Git repositories in CodeCommit -* Integrating with {aws} Identity Center for authentication -* Accessing secrets in {aws} Secrets Manager (if configured) -* Cross-cluster deployments to other EKS clusters - -=== CodeCommit integration - -If you're using CodeCommit repositories, attach a policy with read permissions: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "codecommit:GitPull" - ], - "Resource": "*" - } - ] -} ----- - -[IMPORTANT] -==== -For production use, restrict the `Resource` field to specific repository ARNs instead of using `"*"`. - -Example: -[source,json] ----- -"Resource": "arn:aws:codecommit:us-west-2:111122223333:my-app-repo" ----- - -This limits Argo CD's access to only the repositories it needs to manage. -==== - -=== Secrets Manager integration - -If you're storing repository credentials in Secrets Manager, attach a policy with read permissions: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "secretsmanager:GetSecretValue", - "secretsmanager:DescribeSecret" - ], - "Resource": "arn:aws:secretsmanager:*:*:secret:argocd/*" - } - ] -} ----- - -=== Basic setup - -For basic Argo CD functionality with public Git repositories, no additional IAM policies are required beyond the trust policy. - -== Authentication - -=== {aws} Identity Center integration - -The Argo CD managed capability integrates directly with {aws} Identity Center (formerly {aws} SSO), enabling you to use your existing identity provider for authentication. - -When you configure {aws} Identity Center integration: - -. Users access the Argo CD UI through the EKS console -. They authenticate using {aws} Identity Center (which can federate to your corporate identity provider) -. {aws} Identity Center provides user and group information to Argo CD -. Argo CD maps users and groups to RBAC roles based on your configuration -. Users see only the applications and resources they have permission to access - -=== Simplifying access with Identity Center permission sets - -{aws} Identity Center provides two distinct authentication paths when working with Argo CD: - -*Argo CD API authentication*: Identity Center provides SSO authentication to the Argo CD UI and API. -This is configured through the Argo CD capability's RBAC role mappings. - -*EKS cluster access*: The Argo CD capability uses the customer-provided IAM role to authenticate with EKS clusters through access entries. -These access entries can be manually configured to add or remove permissions. - -You can use link:singlesignon/latest/userguide/howtocreatepermissionset.html[Identity Center permission sets,type="documentation"] to simplify identity management by allowing a single identity to access both Argo CD and EKS clusters. -This reduces overhead by requiring you to manage only one identity across both systems, rather than maintaining separate credentials for Argo CD access and cluster access. - -=== RBAC role mappings - -Argo CD has built-in roles that you can map to {aws} Identity Center users and groups: - -*ADMIN*: Full access to all applications and settings. -Can create, update, and delete applications. -Can manage Argo CD configuration. - -*EDITOR*: Can create and modify applications. -Cannot change Argo CD settings or delete applications. - -*VIEWER*: Read-only access to applications. -Can view application status and history. -Cannot make changes. - -[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. -==== - -== Multi-cluster deployments - -The Argo CD managed capability supports multi-cluster deployments, enabling you to manage applications across development, staging, and production clusters from a single Argo CD instance. - -=== How multi-cluster works - -When you register additional clusters with Argo CD: - -. You create cluster secrets that reference target EKS clusters by ARN -. You create Applications or ApplicationSets that target different clusters -. Argo CD connects to each cluster to deploy applications and watch resources -. You view and manage all clusters from a single Argo CD UI - -=== Prerequisites for multi-cluster - -Before registering additional clusters: - -* Create an Access Entry on the target cluster for the Argo CD capability role -* Ensure network connectivity between the Argo CD capability and target clusters -* Verify IAM permissions to access the target clusters - -=== Register a cluster - -Register clusters using Kubernetes Secrets in the `argocd` namespace. - -Get the target cluster ARN. Replace [.replaceable]`region-code` with the {aws} Region that your target cluster is in and replace [.replaceable]`target-cluster` with the name of your target cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-cluster \ - --region [.replaceable]`region-code` \ - --name [.replaceable]`target-cluster` \ - --query 'cluster.arn' \ - --output text ----- - -Create a cluster secret using the cluster ARN: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: target-cluster - namespace: argocd - labels: - argocd.argoproj.io/secret-type: cluster -type: Opaque -stringData: - name: target-cluster - server: arn:aws:eks:us-west-2:111122223333:cluster/target-cluster - project: default ----- - -[IMPORTANT] -==== -Use the EKS cluster ARN in the `server` field, not the Kubernetes API server URL. -The managed capability requires ARNs to identify target clusters. -==== - -Apply the secret: - -[source,bash] ----- -kubectl apply -f cluster-secret.yaml ----- - -=== Configure Access Entry on target cluster - -The target cluster must have an Access Entry that grants the Argo CD capability role permission to deploy applications. Replace [.replaceable]`region-code` with the {aws} Region that your target cluster is in, replace [.replaceable]`target-cluster` with the name of your target cluster, and replace the ARN with your Argo CD capability role ARN. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks create-access-entry \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`target-cluster` \ - --principal-arn arn:aws:iam::[.replaceable]`111122223333`:role/[.replaceable]`ArgoCDCapabilityRole` \ - --type STANDARD \ - --kubernetes-groups system:masters ----- - -[NOTE] -==== -For production use, consider using more restrictive Kubernetes groups instead of `system:masters`. -==== - -=== Private cluster access - -The Argo CD managed capability can deploy to fully private EKS clusters without requiring VPC peering or specialized networking configuration. -{aws} manages connectivity between the Argo CD capability and private remote clusters automatically. - -=== Cross-account deployments - -For cross-account deployments, add the Argo CD IAM Capability Role from the source account to the target cluster's EKS Access Entry: - -. In the target account, create an Access Entry on the target EKS cluster -. Use the Argo CD IAM Capability Role ARN from the source account as the principal -. Configure appropriate Kubernetes RBAC permissions for the Access Entry -. Register the target cluster in Argo CD using its EKS cluster ARN - -No additional IAM role creation or trust policy configuration is required—EKS Access Entries handle cross-account access. - -== Best practices - -*Use declarative sources as the source of truth*: Store all your application manifests in Git repositories, Helm registries, or OCI images, enabling version control, audit trails, and collaboration. - -*Implement proper RBAC*: Use {aws} Identity Center integration to control who can access and manage applications in Argo CD. -Argo CD supports fine-grained access control to resources within Applications (Deployments, Pods, ConfigMaps, Secrets). - -*Use ApplicationSets for multi-environment deployments*: Use ApplicationSets to deploy applications across multiple clusters or namespaces with different configurations. - -== Lifecycle management - -=== Application sync policies - -Control how Argo CD syncs applications: - -*Manual sync*: Applications require manual approval to sync changes. -Recommended for *production* environments. - -*Automatic sync*: Applications automatically sync when Git changes are detected. -Common for development and staging environments. - -*Self-healing*: Automatically revert manual changes made to the cluster. -Ensures cluster state matches Git. - -*Pruning*: Automatically delete resources removed from Git. -Use with caution as this can delete resources. - -=== Application health - -Argo CD continuously monitors application health: - -* *Healthy*: All resources are running as expected -* *Progressing*: Resources are being created or updated -* *Degraded*: Some resources are not healthy -* *Suspended*: Application is paused -* *Missing*: Resources are missing from the cluster - -=== Sync windows - -Configure sync windows to control when applications can be synced: - -* Allow syncs only during maintenance windows -* Block syncs during business hours -* Schedule automatic syncs for specific times -* Use sync windows for break-glass scenarios where you need to temporarily stop all syncs - -== Webhook configuration for faster sync - -By default, Argo CD polls Git repositories every 6 minutes to detect changes. -For more responsive deployments, configure Git webhooks to trigger immediate syncs when changes are pushed. - -Webhooks provide several benefits: - -* Immediate sync response when code is pushed (seconds vs minutes) -* Reduced polling overhead and improved system performance -* More efficient use of API rate limits -* Better user experience with faster feedback - -=== Webhook endpoint - -The Argo CD capability provides a webhook endpoint for receiving Git notifications. -Find the webhook URL in the EKS console under your cluster's Capabilities tab, or retrieve it using the {aws} CLI: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name [.replaceable]`my-argocd` \ - --query 'capability.configuration.argoCd.webhookUrl' \ - --output text \ - --region [.replaceable]`region-code` ----- - -=== Configure webhooks by Git provider - -*GitHub*: In your repository settings, add a webhook with the Argo CD webhook URL. -Set the content type to `application/json` and select "Just the push event". - -*GitLab*: In your project settings, add a webhook with the Argo CD webhook URL. -Enable "Push events" and optionally "Tag push events". - -*Bitbucket*: In your repository settings, add a webhook with the Argo CD webhook URL. -Select "Repository push" as the trigger. - -*CodeCommit*: Create an Amazon EventBridge rule that triggers on CodeCommit repository state changes and sends notifications to the Argo CD webhook endpoint. - -For detailed webhook configuration instructions, see link:https://argo-cd.readthedocs.io/en/stable/operator-manual/webhook/[Argo CD Webhook Configuration^]. - -[NOTE] -==== -Webhooks complement polling—they don't replace it. -Argo CD continues to poll repositories as a fallback mechanism in case webhook notifications are missed. -==== - -== Next steps - -* <> - Learn how to create and manage Argo CD Applications -* <> - Troubleshoot Argo CD issues -* <> - Manage your Argo CD capability resource diff --git a/latest/ug/capabilities/argocd-create-application.adoc b/latest/ug/capabilities/argocd-create-application.adoc deleted file mode 100644 index aa4bb3912..000000000 --- a/latest/ug/capabilities/argocd-create-application.adoc +++ /dev/null @@ -1,372 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-create-application] -= Create Applications -:info_titleabbrev: Create Applications - -[abstract] --- -Create Argo CD Applications to deploy from Git repositories with automated or manual sync. --- - -Applications represent deployments in target clusters. -Each Application defines a source (Git repository) and destination (cluster and namespace). -When applied, Argo CD will create the resources specified by manifests in the Git repository to the namespace in the cluster. -Applications often specify workload deployments, but they can manage any Kubernetes resources available in the destination cluster. - -== Prerequisites - -* An EKS cluster with the Argo CD capability created -* Repository access configured (see <>) -* Target cluster registered (see <>) -* `kubectl` configured to communicate with your cluster - -== Create a basic Application - -Define an Application that deploys from a Git repository: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: guestbook - namespace: argocd -spec: - project: default - source: - repoURL: https://github.com/argoproj/argocd-example-apps - targetRevision: HEAD - path: guestbook - destination: - server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster - namespace: default ----- - -[IMPORTANT] -==== -Use the EKS cluster ARN in the `destination.server` field, not the Kubernetes API server URL. -The managed capability requires ARNs to identify clusters. -==== - -Apply the Application: - -[source,bash] ----- -kubectl apply -f application.yaml ----- - -View the Application status: - -[source,bash] ----- -kubectl get application guestbook -n argocd ----- - -== Source configuration - -*Git repository*: - -[source,yaml] ----- -spec: - source: - repoURL: https://github.com/example/my-app - targetRevision: main - path: kubernetes/manifests ----- - -*Specific Git tag or commit*: - -[source,yaml] ----- -spec: - source: - targetRevision: v1.2.0 # or commit SHA ----- - -*Helm chart*: - -[source,yaml] ----- -spec: - source: - repoURL: https://github.com/example/helm-charts - targetRevision: main - path: charts/my-app - helm: - valueFiles: - - values.yaml - parameters: - - name: image.tag - value: v1.2.0 ----- - -*Helm chart from ECR*: - -[source,yaml,subs="verbatim,quotes"] ----- -spec: - source: - repoURL: oci://[.replaceable]`account-id`.dkr.ecr.[.replaceable]`region`.amazonaws.com/[.replaceable]`repository-name` - targetRevision: [.replaceable]`chart-version` - chart: [.replaceable]`chart-name` ----- - -If the Capability Role has the required ECR permissions, the repository is used directly and no Repository configuration is required. -See <> for details. - -*Git repository from CodeCommit*: - -[source,yaml,subs="verbatim,quotes"] ----- -spec: - source: - repoURL: https://git-codecommit.[.replaceable]`region`.amazonaws.com/v1/repos/[.replaceable]`repository-name` - targetRevision: main - path: kubernetes/manifests ----- - -If the Capability Role has the required CodeCommit permissions, the repository is used directly and no Repository configuration is required. -See <> for details. - -*Git repository from CodeConnections*: - -[source,yaml,subs="verbatim,quotes"] ----- -spec: - source: - repoURL: https://codeconnections.[.replaceable]`region`.amazonaws.com/git-http/[.replaceable]`account-id`/[.replaceable]`region`/[.replaceable]`connection-id`/[.replaceable]`owner`/[.replaceable]`repository`.git - targetRevision: main - path: kubernetes/manifests ----- - -The repository URL format is derived from the CodeConnections connection ARN. -If the Capability Role has the required CodeConnections permissions and a connection is configured, the repository is used directly and no Repository configuration is required. -See <> for details. - -*Kustomize*: - -[source,yaml] ----- -spec: - source: - repoURL: https://github.com/example/kustomize-app - targetRevision: main - path: overlays/production - kustomize: - namePrefix: prod- ----- - -== Sync policies - -Control how Argo CD syncs applications. - -*Manual sync (default)*: - -Applications require manual approval to sync: - -[source,yaml] ----- -spec: - syncPolicy: {} # No automated sync ----- - -Manually trigger sync: - -[source,bash] ----- -kubectl patch application guestbook -n argocd \ - --type merge \ - --patch '{"operation": {"initiatedBy": {"username": "admin"}, "sync": {}}}' ----- - -*Automatic sync*: - -Applications automatically sync when Git changes are detected: - -[source,yaml] ----- -spec: - syncPolicy: - automated: {} ----- - -*Self-healing*: - -Automatically revert manual changes to the cluster: - -[source,yaml] ----- -spec: - syncPolicy: - automated: - selfHeal: true ----- - -When enabled, Argo CD reverts any manual changes made directly to the cluster, ensuring Git remains the source of truth. - -*Pruning*: - -Automatically delete resources removed from Git: - -[source,yaml] ----- -spec: - syncPolicy: - automated: - prune: true ----- - -[WARNING] -==== -Pruning will delete resources from your cluster. -Use with caution in production environments. -==== - -*Combined automated sync*: - -[source,yaml] ----- -spec: - syncPolicy: - automated: - prune: true - selfHeal: true - syncOptions: - - CreateNamespace=true ----- - -== Sync options - -Additional sync configuration: - -*Create namespace if it doesn't exist*: - -[source,yaml] ----- -spec: - syncPolicy: - syncOptions: - - CreateNamespace=true ----- - -*Validate resources before applying*: - -[source,yaml] ----- -spec: - syncPolicy: - syncOptions: - - Validate=true ----- - -*Apply out of sync only*: - -[source,yaml] ----- -spec: - syncPolicy: - syncOptions: - - ApplyOutOfSyncOnly=true ----- - -== Advanced sync features - -Argo CD supports advanced sync features for complex deployments: - -* *Sync waves* - Control resource creation order with `argocd.argoproj.io/sync-wave` annotations -* *Sync hooks* - Run jobs before or after sync with `argocd.argoproj.io/hook` annotations (PreSync, PostSync, SyncFail) -* *Resource health assessment* - Custom health checks for application-specific resources - -For details, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/[Sync Waves] and link:https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/[Resource Hooks] in the Argo CD documentation. - -== Ignore differences - -Prevent Argo CD from syncing specific fields that are managed by other controllers (like HPA managing replicas): - -[source,yaml] ----- -spec: - ignoreDifferences: - - group: apps - kind: Deployment - jsonPointers: - - /spec/replicas ----- - -For details on ignore patterns and field exclusions, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/[Diffing Customization] in the Argo CD documentation. - -== Multi-environment deployment - -Deploy the same application to multiple environments: - -*Development*: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app-dev - namespace: argocd -spec: - project: default - source: - repoURL: https://github.com/example/my-app - targetRevision: develop - path: overlays/development - destination: - server: arn:aws:eks:us-west-2:111122223333:cluster/dev-cluster - namespace: my-app ----- - -*Production*: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app-prod - namespace: argocd -spec: - project: default - source: - repoURL: https://github.com/example/my-app - targetRevision: main - path: overlays/production - destination: - server: arn:aws:eks:us-west-2:111122223333:cluster/prod-cluster - namespace: my-app - syncPolicy: - automated: - prune: true - selfHeal: true ----- - -== Monitor and manage Applications - -*View Application status*: - -[source,bash] ----- -kubectl get application my-app -n argocd ----- - -*Access the Argo CD UI*: - -Open the Argo CD UI through the EKS console to view application topology, sync status, resource health, and deployment history. -See <> for UI access instructions. - -*Rollback Applications*: - -Rollback to a previous revision using the Argo CD UI or by updating the `targetRevision` in the Application spec to a previous Git commit or tag. - -== Additional resources - -* <> - Organize applications with Projects for multi-tenant environments -* <> - Deploy to multiple clusters with templates -* link:https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/[Application Specification^] - Complete Application API reference -* link:https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/[Sync Options^] - Advanced sync configuration diff --git a/latest/ug/capabilities/argocd-create-cli.adoc b/latest/ug/capabilities/argocd-create-cli.adoc deleted file mode 100644 index d12748cab..000000000 --- a/latest/ug/capabilities/argocd-create-cli.adoc +++ /dev/null @@ -1,162 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-create-cli] -= Create an Argo CD capability using the {aws} CLI -:info_titleabbrev: {aws} CLI - -This topic describes how to create an Argo CD capability using the {aws} CLI. - -== Prerequisites - -* *{aws} CLI* – Version `{auto-cli-v2-version}` or later. To check your version, run `aws --version`. For more information, see link:cli/latest/userguide/cli-chap-install.html[Installing, updating, and uninstalling the {aws} CLI,type="documentation"] in the {aws} Command Line Interface User Guide. -* *`kubectl`* – A command line tool for working with Kubernetes clusters. For more information, see <>. -* *{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 link:singlesignon/latest/userguide/getting-started.html[Getting started with {aws} Identity Center,type="documentation"] to create an Identity Center instance, and link:singlesignon/latest/userguide/addusers.html[Add users,type="documentation"] and link:singlesignon/latest/userguide/addgroups.html[Add groups,type="documentation"] to create users and groups for Argo CD access. - -== Step 1: Create an IAM Capability Role - -Create a trust policy file: - -[source,bash,subs="verbatim,attributes"] ----- -cat > argocd-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -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 <> and <>. -==== - -== 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: - -[source,bash,subs="verbatim,attributes"] ----- -# 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 [.replaceable]`region-code` with the {aws} Region where your cluster is located and [.replaceable]`my-cluster` with your cluster name: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks create-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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]`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 [.replaceable]`region-code` with the {aws} Region where your cluster is located and [.replaceable]`my-cluster` with your cluster name. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`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: - -[source,bash,subs="verbatim,attributes"] ----- -kubectl api-resources | grep argoproj.io ----- - -You should see `Application` and `ApplicationSet` resource types listed. - -== Next steps - -* <> - Configure repositories, register clusters, and create Applications - -* <> - Multi-cluster architecture and advanced configuration -* <> - Manage your Argo CD capability resource diff --git a/latest/ug/capabilities/argocd-create-console.adoc b/latest/ug/capabilities/argocd-create-console.adoc deleted file mode 100644 index e96a49b80..000000000 --- a/latest/ug/capabilities/argocd-create-console.adoc +++ /dev/null @@ -1,78 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-create-console] -= Create an Argo CD capability using the Console -:info_titleabbrev: 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 link:singlesignon/latest/userguide/getting-started.html[Getting started with {aws} Identity Center,type="documentation"] to create an Identity Center instance, and link:singlesignon/latest/userguide/addusers.html[Add users,type="documentation"] and link:singlesignon/latest/userguide/addgroups.html[Add groups,type="documentation"] to create users and groups for Argo CD access. - -== Create the Argo CD capability - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. - -. Select your cluster name to open the cluster detail page. - -. Choose the *Capabilities* tab. - -. In the left navigation, choose *Argo CD*. - -. Choose *Create Argo CD capability*. - -. 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 <> and <>. -==== - -. Configure {aws} Identity Center integration: -+ -.. Select *Enable {aws} Identity Center integration*. -.. Choose your Identity Center instance from the dropdown. -.. Configure role mappings for RBAC by assigning users or groups to Argo CD roles (ADMIN, EDITOR, or VIEWER) - -. Choose *Create*. - -The capability creation process begins. - -== Verify the capability is active - -. On the *Capabilities* tab, view the Argo CD capability status. - -. Wait for the status to change from `CREATING` to `ACTIVE`. - -. Once active, the capability is ready to use. - -For information about capability statuses and troubleshooting, see <>. - -== Access the Argo CD UI - -After the capability is active, you can access the Argo CD UI: - -. On the Argo CD capability page, choose *Open Argo CD UI*. - -. The Argo CD UI opens in a new browser tab. - -. You can now create Applications and manage deployments through the UI. - -== Next steps - -* <> - Configure repositories, register clusters, and create Applications - -* <> - Multi-cluster architecture and advanced configuration -* <> - Manage your Argo CD capability resource diff --git a/latest/ug/capabilities/argocd-create-eksctl.adoc b/latest/ug/capabilities/argocd-create-eksctl.adoc deleted file mode 100644 index 5df460c74..000000000 --- a/latest/ug/capabilities/argocd-create-eksctl.adoc +++ /dev/null @@ -1,155 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-create-eksctl] -= Create an Argo CD capability using eksctl -:info_titleabbrev: 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: - -[source,bash,subs="verbatim,attributes"] ----- -cat > argocd-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -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 <> and <>. -==== - -== Step 2: Get your {aws} Identity Center configuration - -Get your Identity Center instance ARN and user ID for RBAC configuration: - -[source,bash,subs="verbatim,attributes"] ----- -# Get your Identity Center instance ARN -aws sso-admin list-instances --query 'Instances[0].InstanceArn' --output text - -# Get your Identity Center region -aws sso-admin list-instances --query 'Instances[0].IdentityStoreId' --output text | cut -d'/' -f1 - -# 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 name, region, IAM role ARN, Identity Center instance ARN, Identity Center region, and user ID: - -[source,yaml,subs="verbatim,attributes,quotes"] ----- -apiVersion: eksctl.io/v1alpha5 -kind: ClusterConfig - -metadata: - name: [.replaceable]`my-cluster` - region: [.replaceable]`region-code` - -capabilities: - - name: my-argocd - type: ARGOCD - roleArn: arn:aws:iam::[.replaceable]`111122223333`:role/ArgoCDCapabilityRole - configuration: - argocd: - awsIdc: - idcInstanceArn: [.replaceable]`arn:aws:sso:::instance/ssoins-123abc` - idcRegion: [.replaceable]`idc-region-code` - rbacRoleMappings: - - role: ADMIN - identities: - - id: [.replaceable]`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: - -[source,bash,subs="verbatim,attributes"] ----- -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 [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -eksctl get capability \ - --region [.replaceable]`region-code` \ - --cluster [.replaceable]`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: - -[source,bash,subs="verbatim,attributes"] ----- -kubectl api-resources | grep argoproj.io ----- - -You should see `Application` and `ApplicationSet` resource types listed. - -== Next steps - -* <> - Learn how to create and manage Argo CD Applications -* <> - Configure SSO and multi-cluster access -* <> - Manage your Argo CD capability resource diff --git a/latest/ug/capabilities/argocd-permissions.adoc b/latest/ug/capabilities/argocd-permissions.adoc deleted file mode 100644 index d07bc6ab3..000000000 --- a/latest/ug/capabilities/argocd-permissions.adoc +++ /dev/null @@ -1,344 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-permissions] -= Configure Argo CD permissions -:info_titleabbrev: Configure permissions - -[abstract] --- -Configure authentication and authorization for Argo CD using {aws} Identity Center integration and project-based access control. --- - -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: - -. They authenticate using {aws} Identity Center (which can federate to your corporate identity provider) -. {aws} Identity Center provides user and group information to Argo CD -. Argo CD maps users and groups to RBAC roles based on your configuration -. 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. - -*ADMIN* - -Full access to all applications and settings: - -* Create, update, and delete applications and ApplicationSets -* Manage Argo CD configuration -* Register and manage deployment target clusters -* Configure repository access -* Manage projects -* View all application status and history - -*EDITOR* - -Can create and modify applications but cannot change Argo CD settings: - -* Create and update applications and ApplicationSets -* Sync and refresh applications -* View application status and history -* Cannot delete applications -* Cannot change Argo CD configuration -* Cannot manage clusters or repositories - -*VIEWER* - -Read-only access to applications: - -* View application status and history -* View application manifests and resources -* Cannot make any changes -* Cannot sync or refresh applications - -== Configure role mappings - -Map {aws} Identity Center users and groups to Argo CD roles when creating or updating the capability. - -*Example role mapping*: - -[source,json,subs="verbatim,attributes"] ----- -{ - "rbacRoleMapping": {{tcx5-waiver} - "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*: - -[source,bash,subs="verbatim,quotes"] ----- -aws eksfe update-capability \ - --region [.replaceable]`us-east-1` \ - --cluster-name [.replaceable]`cluster` \ - --capability-name [.replaceable]`capname` \ - --endpoint "https://eks.[.replaceable]`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. - -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*: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: team-a - namespace: argocd -spec: - description: Team A applications - - # 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 ----- - -*Assign users to projects*: - -Users with EDITOR or VIEWER roles can be restricted to specific projects. -ADMIN users have access to all projects. - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: team-a -spec: - # ... project configuration ... - - # Map Identity Center groups to project roles - roles: - - name: developer - description: Team A developers - policies: - - p, proj:team-a:developer, applications, *, team-a/*, allow - groups: - - TeamADevelopers - - - name: viewer - description: Team A viewers - policies: - - p, proj:team-a:viewer, applications, get, team-a/*, allow - groups: - - TeamAViewers ----- - -== Common permission patterns - -*Pattern 1: Admin team with full access* - -[source,json,subs="verbatim,attributes"] ----- -{ - "rbacRoleMapping": {{tcx5-waiver} - "ADMIN": ["PlatformTeam", "SRETeam"] - } -} ----- - -*Pattern 2: Developers can deploy, others can view* - -[source,json,subs="verbatim,attributes"] ----- -{ - "rbacRoleMapping": {{tcx5-waiver} - "ADMIN": ["PlatformTeam"], - "EDITOR": ["DevelopmentTeam", "DevOpsTeam"], - "VIEWER": ["AllEmployees"] - } -} ----- - -*Pattern 3: Team-based isolation with projects* - -. Map all developers to EDITOR role -. Create separate AppProjects for each team -. Use project roles to restrict access to team-specific applications - -[source,json,subs="verbatim,attributes"] ----- -{ - "rbacRoleMapping": {{tcx5-waiver} - "ADMIN": ["PlatformTeam"], - "EDITOR": ["AllDevelopers"] - } -} ----- - -Then create projects with team-specific restrictions and role mappings. - -== Best practices - -*Use groups instead of individual users*: Map {aws} Identity Center groups to Argo CD roles rather than individual users for easier management. - -*Start with least privilege*: Begin with VIEWER access and grant EDITOR or ADMIN as needed. - -*Use projects for team isolation*: Create separate AppProjects for different teams or environments to enforce boundaries. - -*Leverage Identity Center federation*: Configure {aws} Identity Center to federate with your corporate identity provider for centralized user management. - -*Regular access reviews*: Periodically review role mappings and project assignments to ensure appropriate access levels. - -*Limit cluster access*: Remember that Argo CD RBAC controls access to Argo CD resources and operations, but does not correspond to Kubernetes RBAC. Users with Argo CD access can deploy applications to clusters that Argo CD has access to. Limit which clusters Argo CD can access and use project destination restrictions to control where applications can be deployed. - -== {aws} service permissions - -To use {aws} services directly in Application resources (without creating Repository resources), attach the required IAM permissions to the Capability Role. - -*ECR for Helm charts*: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ecr:GetAuthorizationToken", - "ecr:BatchCheckLayerAvailability", - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage" - ], - "Resource": "*" - } - ] -} ----- - -*CodeCommit repositories*: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "codecommit:GitPull" - ], - "Resource": "arn:aws:codecommit:region:account-id:repository-name" - } - ] -} ----- - -*CodeConnections (GitHub, GitLab, Bitbucket)*: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "codeconnections:UseConnection" - ], - "Resource": "arn:aws:codeconnections:region:account-id:connection/connection-id" - } - ] -} ----- - -See <> for details on using these integrations. - -== Next steps - -* <> - Learn how to create applications and manage deployments -* <> - Understand Argo CD concepts including Projects -* <> - Review security best practices for capabilities diff --git a/latest/ug/capabilities/argocd-projects.adoc b/latest/ug/capabilities/argocd-projects.adoc deleted file mode 100644 index 44ef6fe43..000000000 --- a/latest/ug/capabilities/argocd-projects.adoc +++ /dev/null @@ -1,318 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-projects] -= Working with Argo CD Projects -:info_titleabbrev: Projects - -[abstract] --- -Use Argo CD Projects to organize applications and enforce security boundaries for multi-tenant environments. --- - -Argo CD Projects (AppProject) provide logical grouping and access control for Applications. -Projects define which Git repositories, target clusters, and namespaces Applications can use, enabling multi-tenancy and security boundaries in shared Argo CD instances. - -== When to use Projects - -Use Projects to: - -* Separate applications by team, environment, or business unit -* Restrict which repositories teams can deploy from -* Limit which clusters and namespaces teams can deploy to -* Enforce resource quotas and allowed resource types -* Provide self-service application deployment with guardrails - -== Default Project - -Every Argo CD capability includes a `default` project that allows access to all repositories, clusters, and namespaces. -While useful for initial testing, create dedicated projects with explicit restrictions for production use. - -For details on the default project configuration and how to restrict it, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#the-default-project[The Default Project] in the Argo CD documentation. - -== Create a Project - -Create a Project by applying an `AppProject` resource to your cluster. - -*Example: Team-specific Project* - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: team-a - namespace: argocd -spec: - description: Applications for Team A - - # Source repositories this project can deploy from - sourceRepos: - - 'https://github.com/my-org/team-a-*' - - 'https://github.com/my-org/shared-libs' - - # Destination clusters and namespaces - destinations: - - name: dev-cluster - namespace: team-a-dev - - name: prod-cluster - namespace: team-a-prod - - # Allowed resource types - clusterResourceWhitelist: - - group: '' - kind: Namespace - - namespaceResourceWhitelist: - - group: 'apps' - kind: Deployment - - group: '' - kind: Service - - group: '' - kind: ConfigMap ----- - -Apply the Project: - -[source,bash] ----- -kubectl apply -f team-a-project.yaml ----- - -== Project configuration - -=== Source repositories - -Control which Git repositories Applications in this project can use: - -[source,yaml] ----- -spec: - sourceRepos: - - 'https://github.com/my-org/app-*' # Wildcard pattern - - 'https://github.com/my-org/infra' # Specific repo ----- - -You can use wildcards and negation patterns (`!` prefix) to allow or deny specific repositories. -For details, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#managing-projects[Managing Projects] in the Argo CD documentation. - -=== Destination restrictions - -Limit where Applications can deploy: - -[source,yaml] ----- -spec: - destinations: - - name: prod-cluster # Specific cluster by name - namespace: production - - name: '*' # Any cluster - namespace: team-a-* # Namespace pattern ----- - -[IMPORTANT] -==== -Use specific cluster names and namespace patterns rather than wildcards for production Projects. -This prevents accidental deployments to unauthorized clusters or namespaces. -==== - -You can use wildcards and negation patterns to control destinations. -For details, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#managing-projects[Managing Projects] in the Argo CD documentation. - -=== Resource restrictions - -Control which Kubernetes resource types can be deployed: - -*Cluster-scoped resources*: - -[source,yaml] ----- -spec: - clusterResourceWhitelist: - - group: '' - kind: Namespace - - group: 'rbac.authorization.k8s.io' - kind: Role ----- - -*Namespace-scoped resources*: - -[source,yaml] ----- -spec: - namespaceResourceWhitelist: - - group: 'apps' - kind: Deployment - - group: '' - kind: Service - - group: '' - kind: ConfigMap - - group: 's3.services.k8s.aws' - kind: Bucket ----- - -Use blacklists to deny specific resources: - -[source,yaml] ----- -spec: - namespaceResourceBlacklist: - - group: '' - kind: Secret # Prevent direct Secret creation ----- - -== Assign Applications to Projects - -When creating an Application, specify the project in the `spec.project` field: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: my-app - namespace: argocd -spec: - project: team-a # Assign to team-a project - source: - repoURL: https://github.com/my-org/my-app - path: manifests - destination: - name: prod-cluster - namespace: team-a-prod ----- - -Applications without a specified project use the `default` project. - -== Project roles and RBAC - -Projects can define custom roles for fine-grained access control. -Map project roles to {aws} Identity Center users and groups in your capability configuration to control who can sync, update, or delete applications. - -*Example: Project with developer and admin roles* - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: team-a - namespace: argocd -spec: - sourceRepos: - - '*' - destinations: - - name: '*' - namespace: 'team-a-*' - - roles: - - name: developer - description: Developers can sync applications - policies: - - p, proj:team-a:developer, applications, sync, team-a/*, allow - - p, proj:team-a:developer, applications, get, team-a/*, allow - groups: - - team-a-developers - - - name: admin - description: Admins have full access - policies: - - p, proj:team-a:admin, applications, *, team-a/*, allow - groups: - - team-a-admins ----- - -For details on project roles, JWT tokens for CI/CD pipelines, and RBAC configuration, see link:https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#project-roles[Project Roles] in the Argo CD documentation. - -== Common patterns - -=== Environment-based Projects - -Create separate projects for each environment: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: production - namespace: argocd -spec: - sourceRepos: - - 'https://github.com/my-org/*' - destinations: - - name: prod-cluster - namespace: '*' - # Strict resource controls for production - clusterResourceWhitelist: [] - namespaceResourceWhitelist: - - group: 'apps' - kind: Deployment - - group: '' - kind: Service ----- - -=== Team-based Projects - -Isolate teams with dedicated projects: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: platform-team - namespace: argocd -spec: - sourceRepos: - - 'https://github.com/my-org/platform-*' - destinations: - - name: '*' - namespace: 'platform-*' - # Platform team can manage cluster resources - clusterResourceWhitelist: - - group: '*' - kind: '*' ----- - -=== Multi-cluster Projects - -Deploy to multiple clusters with consistent policies: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: global-app - namespace: argocd -spec: - sourceRepos: - - 'https://github.com/my-org/global-app' - destinations: - - name: us-west-cluster - namespace: app - - name: eu-west-cluster - namespace: app - - name: ap-south-cluster - namespace: app ----- - -== Best practices - -*Start with restrictive Projects*: Begin with narrow permissions and expand as needed rather than starting with broad access. - -*Use namespace patterns*: Leverage wildcards in namespace restrictions (like `team-a-*`) to allow flexibility while maintaining boundaries. - -*Separate production Projects*: Use dedicated Projects for production with stricter controls and manual sync policies. - -*Document Project purposes*: Use the `description` field to explain what each Project is for and who should use it. - -*Review Project permissions regularly*: Audit Projects periodically to ensure restrictions still align with team needs and security requirements. - -== Additional resources - -* <> - Configure RBAC and Identity Center integration -* <> - Create Applications within Projects -* <> - Use ApplicationSets with Projects for multi-cluster deployments -* link:https://argo-cd.readthedocs.io/en/stable/user-guide/projects/[Argo CD Projects Documentation^] - Complete upstream reference diff --git a/latest/ug/capabilities/argocd-register-clusters.adoc b/latest/ug/capabilities/argocd-register-clusters.adoc deleted file mode 100644 index 0ca0c1dc1..000000000 --- a/latest/ug/capabilities/argocd-register-clusters.adoc +++ /dev/null @@ -1,206 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-register-clusters] -= Register target clusters -:info_titleabbrev: Register clusters - -[abstract] --- -Register Kubernetes clusters where Argo CD will deploy applications. --- - -Register clusters to enable Argo CD to deploy applications to them. -You can register the same cluster where Argo CD is running (local cluster) or remote clusters in different accounts or regions. - -== Prerequisites - -* An EKS cluster with the Argo CD capability created -* `kubectl` configured to communicate with your cluster -* For remote clusters: appropriate IAM permissions and access entries - -== Register the local cluster - -To deploy applications to the same cluster where Argo CD is running, register it as a deployment target. - -[NOTE] -==== -The Argo CD capability does not automatically register the local cluster. -You must explicitly register it to deploy applications to the same cluster. -==== - -*Using the Argo CD CLI*: - -[source,bash] ----- -argocd cluster add \ - --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/my-cluster \ - --name local-cluster ----- - -*Using a Kubernetes Secret*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: local-cluster - namespace: argocd - labels: - argocd.argoproj.io/secret-type: cluster -stringData: - name: local-cluster - server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster - project: default ----- - -Apply the configuration: - -[source,bash] ----- -kubectl apply -f local-cluster.yaml ----- - -[NOTE] -==== -Use the EKS cluster ARN in the `server` field, not the Kubernetes API server URL. -The managed capability requires ARNs to identify clusters. -The default `kubernetes.default.svc` is not supported. -==== - -== Register remote clusters - -To deploy to remote clusters, you must: - -1. Create an access entry on the remote cluster for your Argo CD IAM Capability Role -2. Associate an access policy with appropriate permissions -3. Register the cluster in Argo CD - -*Step 1: Create the access entry on the remote cluster* - -Replace [.replaceable]`region-code` with the {aws} Region that your remote cluster is in, replace [.replaceable]`remote-cluster` with the name of your remote cluster, and replace the ARN with your Argo CD capability role ARN. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks create-access-entry \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`remote-cluster` \ - --principal-arn arn:aws:iam::[.replaceable]`111122223333`:role/[.replaceable]`ArgoCDCapabilityRole` \ - --type STANDARD ----- - -*Step 2: Associate an access policy* - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks associate-access-policy \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`remote-cluster` \ - --principal-arn arn:aws:iam::[.replaceable]`111122223333`:role/[.replaceable]`ArgoCDCapabilityRole` \ - --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ - --access-scope type=cluster ----- - -[NOTE] -==== -For production environments, consider using more restrictive access policies. -See <> for least-privilege configurations. -==== - -*Step 3: Register the cluster in Argo CD* - -*Using the Argo CD CLI*: - -[source,bash] ----- -argocd cluster add \ - --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster \ - --name remote-cluster ----- - -*Using a Kubernetes Secret*: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: remote-cluster - namespace: argocd - labels: - argocd.argoproj.io/secret-type: cluster -stringData: - name: remote-cluster - server: arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster - project: default ----- - -Apply the configuration: - -[source,bash] ----- -kubectl apply -f remote-cluster.yaml ----- - -== Cross-account and cross-region clusters - -To deploy to clusters in different {aws} accounts or regions: - -. Add the Argo CD Capability Role as an access entry on the remote cluster -. Associate the appropriate access policy (typically `AmazonEKSClusterAdminPolicy`) -. Register the cluster using its full ARN (which includes the region) - -The cluster ARN format includes the region, so there's no difference between cross-account and cross-region registration—both use the same process. - -For detailed cross-account configuration including trust policies and IAM permissions, see <>. - -== Verify cluster registration - -View registered clusters: - -[source,bash] ----- -kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=cluster ----- - -Or check cluster status in the Argo CD UI under Settings → Clusters. - -== Private clusters - -The Argo CD capability provides transparent access to fully private EKS clusters without requiring VPC peering or specialized networking configuration. - -{aws} manages connectivity between the Argo CD capability and private remote clusters automatically. - -Simply register the private cluster using its ARN—no additional networking setup required. - -== Restrict cluster access with Projects - -Use Projects to control which clusters Applications can deploy to: - -[source,yaml] ----- -apiVersion: argoproj.io/v1alpha1 -kind: AppProject -metadata: - name: production - namespace: argocd -spec: - destinations: - - server: arn:aws:eks:us-west-2:111122223333:cluster/prod-cluster - namespace: '*' - - server: arn:aws:eks:eu-west-1:111122223333:cluster/prod-eu-cluster - namespace: '*' - sourceRepos: - - 'https://github.com/example/production-apps' ----- - -For details, see <>. - -== Additional resources - -* <> - Organize applications and enforce security boundaries -* <> - Deploy your first application -* <> - Deploy to multiple clusters with ApplicationSets -* <> - Multi-cluster patterns and cross-account setup -* link:https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#clusters[Declarative Cluster Setup^] - Upstream cluster configuration reference diff --git a/latest/ug/capabilities/argocd-troubleshooting.adoc b/latest/ug/capabilities/argocd-troubleshooting.adoc deleted file mode 100644 index ac08632e0..000000000 --- a/latest/ug/capabilities/argocd-troubleshooting.adoc +++ /dev/null @@ -1,204 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd-troubleshooting] -= Troubleshoot issues with Argo CD capabilities -:info_titleabbrev: Troubleshooting - -[abstract] --- -Diagnose and resolve common issues with the EKS Capability for Argo CD. --- - -This topic provides troubleshooting guidance for the EKS Capability for Argo CD, including capability health checks, application sync issues, repository authentication, and multi-cluster deployments. - -[NOTE] -==== -EKS Capabilities are fully managed and run outside your cluster. -You don't have access to Argo CD server logs or the `argocd` namespace. -Troubleshooting focuses on capability health, application status, and configuration. -==== - -== Capability is ACTIVE but applications aren't syncing - -If your Argo CD capability shows `ACTIVE` status but applications aren't syncing, check the capability health and application status. - -*Check capability health*: - -You can view capability health and status issues in the EKS console or using the {aws} CLI. - -*Console*: - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name. -. Choose the *Observability* tab. -. Choose *Monitor cluster*. -. Choose the *Capabilities* tab to view health and status for all capabilities. - -*{aws} CLI*: - -[source,bash] ----- -# View capability status and health -aws eks describe-capability \ - --region region-code \ - --cluster-name my-cluster \ - --capability-name my-argocd - -# Look for issues in the health section ----- - -*Common causes*: - -* *Repository not configured*: Git repository not added to Argo CD -* *Authentication failed*: SSH key, token, or CodeCommit credentials invalid -* *Application not created*: No Application resources exist in the cluster -* *Sync policy*: Manual sync required (auto-sync not enabled) -* *IAM permissions*: Missing permissions for CodeCommit or Secrets Manager - -*Check application status*: - -[source,bash] ----- -# List applications -kubectl get application -n argocd - -# View sync status -kubectl get application my-app -n argocd -o jsonpath='{.status.sync.status}' - -# View application health -kubectl get application my-app -n argocd -o jsonpath='{.status.health}' ----- - -*Check application conditions*: - -[source,bash] ----- -# Describe application to see detailed status -kubectl describe application my-app -n argocd - -# View application health -kubectl get application my-app -n argocd -o jsonpath='{.status.health}' ----- - -== Applications stuck in "Progressing" state - -If an application shows `Progressing` but never reaches `Healthy`, check the application's resource status and events. - -*Check resource health*: - -[source,bash] ----- -# View application resources -kubectl get application my-app -n argocd -o jsonpath='{.status.resources}' - -# Check for unhealthy resources -kubectl describe application my-app -n argocd | grep -A 10 "Health Status" ----- - -*Common causes*: - -* *Deployment not ready*: Pods failing to start or readiness probes failing -* *Resource dependencies*: Resources waiting for other resources to be ready -* *Image pull errors*: Container images not accessible -* *Insufficient resources*: Cluster lacks CPU or memory for pods - -*Verify target cluster configuration* (for multi-cluster setups): - -[source,bash,subs="verbatim,quotes"] ----- -# List registered clusters -kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster - -# View cluster secret details -kubectl get secret [.replaceable]`cluster-secret-name` -n argocd -o yaml ----- - -== Repository authentication failures - -If Argo CD cannot access your Git repositories, verify the authentication configuration. - -*For CodeCommit repositories*: - -Verify the IAM Capability Role has CodeCommit permissions: - -[source,bash,subs="verbatim,quotes"] ----- -# View IAM policies -aws iam list-attached-role-policies --role-name [.replaceable]`my-argocd-capability-role` -aws iam list-role-policies --role-name [.replaceable]`my-argocd-capability-role` - -# Get specific policy details -aws iam get-role-policy --role-name [.replaceable]`my-argocd-capability-role` --policy-name [.replaceable]`policy-name` ----- - -The role needs `codecommit:GitPull` permission for the repositories. - -*For private Git repositories*: - -Verify repository credentials are correctly configured: - -[source,bash,subs="verbatim,quotes"] ----- -# Check repository secret exists -kubectl get secret -n argocd [.replaceable]`repo-secret-name` -o yaml ----- - -Ensure the secret contains the correct authentication credentials (SSH key, token, or username/password). - -*For repositories using Secrets Manager*: - -[source,bash,subs="verbatim,quotes"] ----- -# Verify IAM Capability Role has Secrets Manager permissions -aws iam list-attached-role-policies --role-name [.replaceable]`my-argocd-capability-role` - -# Test secret retrieval -aws secretsmanager get-secret-value --secret-id [.replaceable]`arn:aws:secretsmanager:region-code:111122223333:secret:my-secret` ----- - -== Multi-cluster deployment issues - -If applications aren't deploying to remote clusters, verify the cluster registration and access configuration. - -*Check cluster registration*: - -[source,bash] ----- -# List registered clusters -kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster - -# Verify cluster secret format -kubectl get secret CLUSTER_SECRET_NAME -n argocd -o yaml ----- - -Ensure the `server` field contains the EKS cluster ARN, not the Kubernetes API URL. - -*Verify target cluster Access Entry*: - -On the target cluster, check that the Argo CD Capability Role has an Access Entry: - -[source,bash,subs="verbatim,quotes"] ----- -# List access entries (run on target cluster or use AWS CLI) -aws eks list-access-entries --cluster-name [.replaceable]`target-cluster` - -# Describe specific access entry -aws eks describe-access-entry \ - --cluster-name [.replaceable]`target-cluster` \ - --principal-arn arn:aws:iam::[.replaceable]`111122223333`:role/[.replaceable]`my-argocd-capability-role` ----- - -*Check IAM permissions for cross-account*: - -For cross-account deployments, verify the Argo CD Capability Role has an Access Entry on the target cluster. -The managed capability uses EKS Access Entries for cross-account access, not IAM role assumption. - -For more on multi-cluster configuration, see <>. - -== Next steps - -* <> - Argo CD considerations and best practices -* <> - Create and manage Argo CD Applications -* <> - Configure multi-cluster deployments -* <> - General capability troubleshooting guidance diff --git a/latest/ug/capabilities/argocd.adoc b/latest/ug/capabilities/argocd.adoc deleted file mode 100644 index 6d2ec0b29..000000000 --- a/latest/ug/capabilities/argocd.adoc +++ /dev/null @@ -1,113 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#argocd] -= Continuous Deployment with Argo CD -:info_titleabbrev: Argo CD - -[abstract] --- -Implement GitOps-based continuous deployment with Argo CD, a fully managed capability of Amazon EKS. --- - -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: - -[source,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: my-cluster - namespace: guestbook - syncPolicy: - automated: - prune: true - selfHeal: true ----- - - - -== 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: - -. Create and configure an IAM Capability Role with the necessary permissions for Argo CD to access your Git repositories and manage applications. -. <> on your EKS cluster through the {aws} Console, {aws} CLI, or your preferred infrastructure as code tool. -. Configure repository access and register clusters for application deployment. -. Create Application resources to deploy your applications from Git repositories. - -include::create-argocd-capability.adoc[leveloffset=+1] - -include::argocd-concepts.adoc[leveloffset=+1] - -include::argocd-permissions.adoc[leveloffset=+1] - -include::working-with-argocd.adoc[leveloffset=+1] - -include::argocd-considerations.adoc[leveloffset=+1] - -include::argocd-troubleshooting.adoc[leveloffset=+1] - -include::argocd-comparison.adoc[leveloffset=+1] - - diff --git a/latest/ug/capabilities/capabilities-considerations.adoc b/latest/ug/capabilities/capabilities-considerations.adoc deleted file mode 100644 index c88e7d62f..000000000 --- a/latest/ug/capabilities/capabilities-considerations.adoc +++ /dev/null @@ -1,157 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#capabilities-considerations] -= EKS Capabilities considerations -:info_titleabbrev: Considerations - -[abstract] --- -Plan your EKS Capabilities deployment with guidance on choosing between managed and self-managed solutions, multi-cluster architecture patterns, and operational 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 <>. - - -== 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 https://aws.amazon.com/eks/pricing/[Amazon 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: - -* <> -* <> -* <> diff --git a/latest/ug/capabilities/capabilities-troubleshooting.adoc b/latest/ug/capabilities/capabilities-troubleshooting.adoc deleted file mode 100644 index 6857a7566..000000000 --- a/latest/ug/capabilities/capabilities-troubleshooting.adoc +++ /dev/null @@ -1,245 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#capabilities-troubleshooting] -= Troubleshooting EKS Capabilities -:info_titleabbrev: Troubleshoot capabilities - -[abstract] --- -Diagnose and resolve common issues with EKS Capabilities. --- - -This topic provides general troubleshooting guidance for EKS Capabilities, including capability health checks, common issues, and links to capability-specific troubleshooting. - -[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 configuration. -==== - -== General troubleshooting approach - -When troubleshooting EKS Capabilities, follow this general approach: - -. *Check capability health*: Use `aws eks describe-capability` to view the capability status and health issues -. *Verify resource status*: Check the Kubernetes resources (CRDs) you created for status conditions and events -. *Review IAM permissions*: Ensure the Capability Role has the necessary permissions -. *Check configuration*: Verify capability-specific configuration is correct - -== Check capability health - -All EKS Capabilities provide health information through the EKS console and the `describe-capability` API. - -*Console*: - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name. -. Choose the *Observability* tab. -. Choose *Monitor cluster*. -. Choose the *Capabilities* tab to view health and status for all capabilities. - -The Capabilities tab shows: - -* Capability name and type -* Current status -* Health issues, with description - -*{aws} CLI*: - -[source,bash] ----- -aws eks describe-capability \ - --region region-code \ - --cluster-name my-cluster \ - --capability-name my-capability-name ----- - -The response includes: - -* *status*: Current capability state (`CREATING`, `ACTIVE`, `UPDATING`, `DELETING`, `CREATE_FAILED`, `UPDATE_FAILED`) -* *health*: Health information including any issues detected by the capability - -== Common capability statuses - -*CREATING*: Capability is being set up. - -*ACTIVE*: Capability is running and ready to use. If resources aren't working as expected, check resource status and IAM permissions. - -*UPDATING*: Configuration changes are being applied. Wait for the status to return to `ACTIVE`. - -*CREATE_FAILED* or *UPDATE_FAILED*: Setup or update encountered an error. Check the health section for details. Common causes: - -* IAM role trust policy incorrect or missing -* IAM role doesn't exist or isn't accessible -* Cluster access issues -* Invalid configuration parameters - -== Verify Kubernetes resource status - -EKS Capabilities create and manage Kubernetes Custom Resource Definitions (CRDs) in your cluster. -When troubleshooting, check the status of the resources you created: - -[source,bash,subs="verbatim,quotes"] ----- -# List resources of a specific type -kubectl get [.replaceable]`resource-kind` -A - -# Describe a specific resource to see conditions and events -kubectl describe [.replaceable]`resource-kind` [.replaceable]`resource-name` -n [.replaceable]`namespace` - -# View resource status conditions -kubectl get [.replaceable]`resource-kind` [.replaceable]`resource-name` -n [.replaceable]`namespace` -o jsonpath='{.status.conditions}' - -# View events related to the resource -kubectl get events --field-selector involvedObject.name=[.replaceable]`resource-name` -n [.replaceable]`namespace` ----- - -Resource status conditions provide information about: - -* Whether the resource is ready -* Any errors encountered -* Current reconciliation state - -== Review IAM permissions and cluster access - -Many capability issues stem from IAM permission problems or missing cluster access configuration. Verify both the Capability Role permissions and cluster access entries. - -=== Check IAM role permissions - -Verify the Capability Role has the necessary permissions: - -[source,bash,subs="verbatim,quotes"] ----- -# List attached managed policies -aws iam list-attached-role-policies --role-name [.replaceable]`my-capability-role` - -# List inline policies -aws iam list-role-policies --role-name [.replaceable]`my-capability-role` - -# Get specific policy details -aws iam get-role-policy --role-name [.replaceable]`my-capability-role` --policy-name [.replaceable]`policy-name` - -# View the role's trust policy -aws iam get-role --role-name [.replaceable]`my-capability-role` --query 'Role.AssumeRolePolicyDocument' ----- - -The trust policy must allow the `capabilities.eks.amazonaws.com` service principal: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": "sts:AssumeRole" - } - ] -} ----- - -=== Check EKS Access Entries and Access Policies - -All capabilities require proper EKS Access Entries and Access Policies on the cluster where they operate. - -*Verify Access Entry exists*: - -[source,bash,subs="verbatim,quotes"] ----- -aws eks list-access-entries \ - --cluster-name [.replaceable]`my-cluster` \ - --region [.replaceable]`region-code` ----- - -Look for the Capability Role ARN in the list. If missing, the capability cannot access the cluster. - -*Check Access Policies attached to the entry*: - -[source,bash,subs="verbatim,quotes"] ----- -aws eks list-associated-access-policies \ - --cluster-name [.replaceable]`my-cluster` \ - --principal-arn [.replaceable]`arn:aws:iam::111122223333:role/my-capability-role` \ - --region [.replaceable]`region-code` ----- - -All capabilities require appropriate Access Policies: - -* *ACK*: Needs permissions to create and manage Kubernetes resources -* *kro*: Needs permissions to create and manage Kubernetes resources -* *Argo CD*: Needs permissions to create and manage Applications, and requires Access Entries on remote target clusters for multi-cluster deployments - -*For Argo CD multi-cluster deployments*: - -If deploying to remote clusters, verify the Capability Role has an Access Entry on each target cluster: - -[source,bash,subs="verbatim,quotes"] ----- -# Check Access Entry on target cluster -aws eks describe-access-entry \ - --cluster-name [.replaceable]`target-cluster` \ - --principal-arn [.replaceable]`arn:aws:iam::111122223333:role/argocd-capability-role` \ - --region [.replaceable]`region-code` ----- - -If the Access Entry is missing on a target cluster, Argo CD cannot deploy applications to it. -See <> for configuration details. - -== Capability-specific troubleshooting - -For detailed troubleshooting guidance specific to each capability type: - -* <> - Troubleshoot ACK resource creation, IAM permissions, and cross-account access -* <> - Troubleshoot application sync, repository authentication, and multi-cluster deployments -* <> - Troubleshoot ResourceGraphDefinitions, CEL expressions, and RBAC permissions - -== Common issues across all capabilities - -=== Capability stuck in CREATING state - -If a capability remains in `CREATING` state for longer than expected: - -. Check the capability health for specific issues in the console (*Observability* > *Monitor cluster* > *Capabilities* tab) or using the {aws} CLI: -+ -[source,bash] ----- -aws eks describe-capability \ - --region region-code \ - --cluster-name my-cluster \ - --capability-name my-capability-name \ - --query 'capability.health' ----- - -. Verify the IAM role exists and has the correct trust policy -. Ensure your cluster is accessible and healthy -. Check for any cluster-level issues that might prevent capability setup - -=== Resources not being created or updated - -If the capability is `ACTIVE` but resources aren't being created or updated: - -. Check the resource status for error conditions -. Verify IAM permissions for the specific {aws} services (ACK) or repositories (Argo CD) -. Check RBAC permissions for creating underlying resources (kro) -. Review resource specifications for validation errors - -=== Capability health shows issues - -If `describe-capability` shows health issues: - -. Read the issue descriptions carefully—they often indicate the specific problem -. Address the root cause (IAM permissions, configuration errors, etc.) -. The capability will automatically recover once the issue is resolved - -== Next steps - -* <> - Manage capability resources -* <> - ACK-specific troubleshooting -* <> - Argo CD-specific troubleshooting -* <> - kro-specific troubleshooting -* <> - Security best practices for capabilities diff --git a/latest/ug/capabilities/capabilities.adoc b/latest/ug/capabilities/capabilities.adoc deleted file mode 100644 index cb24fd50d..000000000 --- a/latest/ug/capabilities/capabilities.adoc +++ /dev/null @@ -1,193 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#capabilities] -= EKS Capabilities -:info_titleabbrev: EKS Capabilities - -[abstract] --- -Accelerate developer velocity and simplify Kubernetes operations with fully managed capabilities that run in EKS. --- - -[TIP] -==== -Get started: <> | <> | <> -==== - -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 link:general/latest/gr/eks.html[Amazon EKS endpoints and quotas,type="documentation"] 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. - -<> - -=== 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. - -<> - -=== 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. - -<> - -== 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 https://aws.amazon.com/eks/pricing/[Amazon EKS pricing page^]. - -[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 <>. - -For security configuration and details on IAM roles, see <>. -For multi-cluster architecture patterns, see <>. - -== 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. - - -include::working-with-capabilities.adoc[leveloffset=+1] - -include::capability-kubernetes-resources.adoc[leveloffset=+1] - -include::capabilities-considerations.adoc[leveloffset=+1] - -include::ack.adoc[leveloffset=+1] - -include::argocd.adoc[leveloffset=+1] - -include::kro.adoc[leveloffset=+1] - -include::capabilities-troubleshooting.adoc[leveloffset=+1] - - diff --git a/latest/ug/capabilities/capability-kubernetes-resources.adoc b/latest/ug/capabilities/capability-kubernetes-resources.adoc deleted file mode 100644 index 0b16976bb..000000000 --- a/latest/ug/capabilities/capability-kubernetes-resources.adoc +++ /dev/null @@ -1,165 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#capability-kubernetes-resources] -= Capability Kubernetes resources -:info_titleabbrev: Kubernetes resources - -[abstract] --- -Learn about the Kubernetes custom resources provided by each EKS capability type and how to use them in your clusters. --- - -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: - -[source,yaml] ----- -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 <>. - -== 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: - -[source,yaml] ----- -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: - -[source,yaml] ----- -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 <>. - -== 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: - -[source,yaml] ----- -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 <>. - -== 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 64 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: - -* <> – Understand ACK concepts and resource lifecycle -* <> – Working with Argo CD capabilities for GitOps workflows -* <> – Understand kro concepts and resource composition diff --git a/latest/ug/capabilities/create-ack-capability.adoc b/latest/ug/capabilities/create-ack-capability.adoc deleted file mode 100644 index b4046458f..000000000 --- a/latest/ug/capabilities/create-ack-capability.adoc +++ /dev/null @@ -1,67 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#create-ack-capability] -= Create an ACK capability -:info_titleabbrev: Create ACK capability - -[abstract] --- -Learn how to create an {aws} Controllers for Kubernetes (ACK) capability on your Amazon EKS cluster using the Console, {aws} CLI, or eksctl. --- - -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 <>. - -[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 <> and <>. -==== - -== Choose your tool - -You can create an ACK capability using the {aws-management-console}, {aws} CLI, or eksctl: - -* <> - Use the Console for a guided experience -* <> - Use the {aws} CLI for scripting and automation -* <> - Use eksctl for a Kubernetes-native experience - -== What happens when you create an ACK capability - -When you create an ACK capability: - -. EKS creates the ACK capability service and configures it to monitor and manage resources in your cluster -. Custom Resource Definitions (CRDs) are installed in your cluster -. The capability assumes the IAM Capability Role you provide -. ACK begins watching for its custom resources in your cluster -. The capability status changes from `CREATING` to `ACTIVE` - -Once active, you can create ACK custom resources in your cluster to manage {aws} resources. - -== Next steps - -After creating the ACK capability: - -* <> - Understand ACK concepts and get started with {aws} resources -* <> - Learn about reconciliation, field exports, and resource adoption patterns -* <> - Configure IAM permissions and multi-account patterns - -include::ack-create-console.adoc[leveloffset=+1] - -include::ack-create-cli.adoc[leveloffset=+1] - -include::ack-create-eksctl.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/create-argocd-capability.adoc b/latest/ug/capabilities/create-argocd-capability.adoc deleted file mode 100644 index 0bc09105b..000000000 --- a/latest/ug/capabilities/create-argocd-capability.adoc +++ /dev/null @@ -1,70 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#create-argocd-capability] -= Create an Argo CD capability -:info_titleabbrev: Create Argo CD capability - -[abstract] --- -Learn how to create an Argo CD capability on your Amazon EKS cluster using the Console, {aws} CLI, or eksctl. --- - -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 <>. -For Identity Center setup, see link:singlesignon/latest/userguide/getting-started.html[Getting started with {aws} Identity Center,type="documentation"]. - -[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 <> and <>. -==== - -== Choose your tool - -You can create an Argo CD capability using the {aws-management-console}, {aws} CLI, or eksctl: - -* <> - Use the Console for a guided experience -* <> - Use the {aws} CLI for scripting and automation -* <> - Use eksctl for a Kubernetes-native experience - -== What happens when you create an Argo CD capability - -When you create an Argo CD capability: - -. EKS creates the Argo CD capability service and configures it to monitor and manage resources in your cluster -. Custom Resource Definitions (CRDs) are installed in your cluster -. The capability assumes the IAM Capability Role you provide -. Argo CD begins watching for its custom resources -. The capability status changes from `CREATING` to `ACTIVE` -. The Argo CD UI becomes accessible through its endpoint - -Once active, you can create Argo CD Applications in your cluster to deploy from Git repositories. - -== Next steps - -After creating the Argo CD capability: - -* <> - Configure repository access, register target clusters, and create Applications -* <> - Learn about GitOps principles, sync policies, and multi-cluster patterns -* <> - Explore multi-cluster architecture patterns and advanced configuration - -include::argocd-create-console.adoc[leveloffset=+1] - -include::argocd-create-cli.adoc[leveloffset=+1] - -include::argocd-create-eksctl.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/create-kro-capability.adoc b/latest/ug/capabilities/create-kro-capability.adoc deleted file mode 100644 index a764c7bc0..000000000 --- a/latest/ug/capabilities/create-kro-capability.adoc +++ /dev/null @@ -1,62 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#create-kro-capability] -= Create a kro capability -:info_titleabbrev: Create kro capability - -[abstract] --- -Learn how to create a kro (Kube Resource Orchestrator) capability on your Amazon EKS cluster using the Console, {aws} CLI, or eksctl. --- - -This topic explains how to create a kro capability on your Amazon EKS cluster. - -== Prerequisites - -Before creating a kro capability, ensure you have: - -* An existing Amazon EKS cluster running a supported Kubernetes version (all versions in standard and extended support are supported) -* Sufficient IAM permissions to create capability resources on EKS clusters -* (For CLI/eksctl) The appropriate CLI tool installed and configured - -[NOTE] -==== -Unlike ACK and Argo CD, kro does not require additional IAM permissions beyond the trust policy. -kro operates entirely within your cluster and does not make {aws} API calls. -However, you still need to provide an IAM Capability Role with the appropriate trust policy. -For information about configuring Kubernetes RBAC permissions for kro, see <>. -==== - -== Choose your tool - -You can create a kro capability using the {aws-management-console}, {aws} CLI, or eksctl: - -* <> - Use the Console for a guided experience -* <> - Use the {aws} CLI for scripting and automation -* <> - Use eksctl for a Kubernetes-native experience - -== What happens when you create a kro capability - -When you create a kro capability: - -. EKS creates the kro capability service and configures it to monitor and manage resources in your cluster -. Custom Resource Definitions (CRDs) are installed in your cluster -. The capability assumes the IAM Capability Role you provide (used only for the trust relationship) -. kro begins watching for `ResourceGraphDefinition` resources and their instances -. The capability status changes from `CREATING` to `ACTIVE` - -Once active, you can create ResourceGraphDefinitions to define custom APIs and create instances of those APIs. - -== Next steps - -After creating the kro capability: - -* <> - Understand kro concepts and resource composition -* <> - Learn about SimpleSchema, CEL expressions, and resource composition patterns - -include::kro-create-console.adoc[leveloffset=+1] - -include::kro-create-cli.adoc[leveloffset=+1] - -include::kro-create-eksctl.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/images b/latest/ug/capabilities/images deleted file mode 120000 index 5e6757319..000000000 --- a/latest/ug/capabilities/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/latest/ug/capabilities/kro-comparison.adoc b/latest/ug/capabilities/kro-comparison.adoc deleted file mode 100644 index 02c0f36c3..000000000 --- a/latest/ug/capabilities/kro-comparison.adoc +++ /dev/null @@ -1,62 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-comparison] -= Comparing EKS Capability for kro to self-managed kro -:info_titleabbrev: Comparison to self-managed - -[abstract] --- -Understand the differences between the EKS Capability for kro and self-managed kro. --- - -The EKS Capability for kro provides the same functionality as self-managed kro, but with significant operational advantages. -For a general comparison of EKS Capabilities vs self-managed solutions, see <>. - -The EKS Capability for kro uses the same upstream kro controllers and is fully compatible with upstream kro. -ResourceGraphDefinitions, CEL expressions, and resource composition work identically. -For complete kro documentation and examples, see the https://kro.run/docs/overview[kro documentation^]. - - - -== Migration path - -You can migrate from self-managed kro to the managed capability with zero downtime. - -[IMPORTANT] -==== -Before migrating, ensure your self-managed kro controller is running the same version as the EKS Capability for kro. -Check the capability version in the EKS console or using `aws eks describe-capability`, then upgrade your self-managed installation to match. -This prevents compatibility issues during the migration. -==== - -. Update your self-managed kro controller to use `kube-system` for leader election leases: -+ -[source,bash] ----- -helm upgrade --install kro \ - oci://ghcr.io/awslabs/kro/kro-chart \ - --namespace kro \ - --set leaderElection.namespace=kube-system ----- -+ -This moves the controller's lease to `kube-system`, allowing the managed capability to coordinate with it. - -. Create the kro capability on your cluster (see <>) - -. The managed capability recognizes existing ResourceGraphDefinitions and instances, taking over reconciliation - -. Gradually scale down or remove self-managed kro deployments: -+ -[source,bash] ----- -helm uninstall kro --namespace kro ----- - -This approach allows both controllers to coexist safely during migration. -The managed capability automatically adopts ResourceGraphDefinitions and instances previously managed by self-managed kro, ensuring continuous reconciliation without conflicts. - -== Next steps - -* <> - Create a kro capability resource -* <> - Understand kro concepts and resource composition diff --git a/latest/ug/capabilities/kro-concepts.adoc b/latest/ug/capabilities/kro-concepts.adoc deleted file mode 100644 index 337fd86b3..000000000 --- a/latest/ug/capabilities/kro-concepts.adoc +++ /dev/null @@ -1,332 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-concepts] -= kro concepts -:info_titleabbrev: kro concepts - -[abstract] --- -Learn kro fundamentals through a practical example, then explore core concepts including SimpleSchema, CEL expressions, and resource composition. --- - -kro enables platform teams to create custom Kubernetes APIs that compose multiple resources into higher-level abstractions. -This topic walks through a practical example, then explains the core concepts you need to understand when working with the EKS Capability for kro. - -== Getting started with kro - -After creating the kro capability (see <>), you can start creating custom APIs using ResourceGraphDefinitions in your cluster. - -Here's a complete example that creates a simple web application abstraction: - -[source,yaml] ----- -apiVersion: kro.run/v1alpha1 -kind: ResourceGraphDefinition -metadata: - name: webapplication -spec: - schema: - apiVersion: v1alpha1 - kind: WebApplication - group: kro.run - spec: - name: string | required=true - image: string | default="nginx:latest" - replicas: integer | default=3 - resources: - - id: deployment - template: - apiVersion: apps/v1 - kind: Deployment - metadata: - name: ${schema.spec.name} - spec: - replicas: ${schema.spec.replicas} - selector: - matchLabels: - app: ${schema.spec.name} - template: - metadata: - labels: - app: ${schema.spec.name} - spec: - containers: - - name: app - image: ${schema.spec.image} - ports: - - containerPort: 80 - - id: service - template: - apiVersion: v1 - kind: Service - metadata: - name: ${schema.spec.name} - spec: - selector: - app: ${schema.spec.name} - ports: - - protocol: TCP - port: 80 - targetPort: 80 ----- - -After applying this ResourceGraphDefinition, application teams can create web applications using your simplified API: - -[source,yaml] ----- -apiVersion: kro.run/v1alpha1 -kind: WebApplication -metadata: - name: my-app -spec: - name: my-app - replicas: 5 ----- - -kro automatically creates the Deployment and Service with the appropriate configuration. -Since `image` isn't specified, it uses the default value `nginx:latest` from the schema. - -== Core concepts - -[IMPORTANT] -==== -kro validates ResourceGraphDefinitions at creation time, not at runtime. -When you create an RGD, kro validates CEL syntax, type-checks expressions against actual Kubernetes schemas, verifies field existence, and detects circular dependencies. -This means errors are caught immediately when you create the RGD, before any instances are deployed. -==== - -=== ResourceGraphDefinition - -A ResourceGraphDefinition (RGD) defines a custom Kubernetes API by specifying: - -* *Schema* - The API structure using SimpleSchema format (field names, types, defaults, validation) -* *Resources* - Templates for the underlying Kubernetes or {aws} resources to create -* *Dependencies* - How resources relate to each other (automatically detected from field references) - -When you apply an RGD, kro registers a new Custom Resource Definition (CRD) in your cluster. -Application teams can then create instances of your custom API, and kro handles creating and managing all the underlying resources. - -For more information, see link:https://kro.run/docs/concepts/rgd/overview/[ResourceGraphDefinition Overview^] in the kro documentation. - -=== SimpleSchema format - -SimpleSchema provides a simplified way to define API schemas without requiring OpenAPI knowledge: - -[source,yaml] ----- -schema: - apiVersion: v1alpha1 - kind: Database - spec: - name: string | required=true description="Database name" - size: string | default="small" enum=small,medium,large - replicas: integer | default=1 minimum=1 maximum=5 ----- - -SimpleSchema supports `string`, `integer`, `boolean`, and `number` types with constraints like `required`, `default`, `minimum`/`maximum`, `enum`, and `pattern`. - -For more information, see link:https://kro.run/docs/concepts/rgd/schema/[SimpleSchema^] in the kro documentation. - -=== CEL expressions - -kro uses Common Expression Language (CEL) to reference values dynamically and add conditional logic. -CEL expressions are wrapped in `${` and `}` and can be used in two ways: - -*Standalone expressions* - The entire field value is a single expression: - -[source,yaml] ----- -spec: - replicas: ${schema.spec.replicaCount} # Expression returns integer - labels: ${schema.spec.labelMap} # Expression returns object ----- - -The expression result replaces the entire field value and must match the field's expected type. - -*String templates* - One or more expressions embedded in a string: - -[source,yaml] ----- -metadata: - name: "${schema.spec.prefix}-${schema.spec.name}" # Multiple expressions - annotation: "Created by ${schema.spec.owner}" # Single expression in string ----- - -All expressions in string templates must return strings. -Use `string()` to convert other types: `"replicas-${string(schema.spec.count)}"`. - -*Field references* - Access instance spec values using `schema.spec`: - -[source,yaml] ----- -template: - metadata: - name: ${schema.spec.name}-deployment - namespace: ${schema.metadata.namespace} # Can also reference metadata - spec: - replicas: ${schema.spec.replicas} ----- - -*Optional field access* - Use `?` for fields that might not exist: - -[source,yaml] ----- -# For ConfigMaps or Secrets with unknown structure -value: ${configmap.data.?DATABASE_URL} - -# For optional status fields -ready: ${deployment.status.?readyReplicas > 0} ----- - -If the field doesn't exist, the expression returns `null` instead of failing. - -*Conditional resources* - Include resources only when conditions are met: - -[source,yaml] ----- -resources: -- id: ingress - includeWhen: - - ${schema.spec.enableIngress == true} - template: - # ... ingress configuration ----- - -The `includeWhen` field accepts a list of boolean expressions. -All conditions must be true for the resource to be created. -Currently, `includeWhen` can only reference `schema.spec` fields. - -*Transformations* - Transform values using ternary operators and functions: - -[source,yaml] ----- -template: - spec: - resources: - requests: - memory: ${schema.spec.size == "small" ? "512Mi" : "2Gi"} - - # String concatenation - image: ${schema.spec.registry + "/" + schema.spec.imageName} - - # Type conversion - port: ${string(schema.spec.portNumber)} ----- - -*Cross-resource references* - Reference values from other resources: - -[source,yaml] ----- -resources: -- id: bucket - template: - apiVersion: s3.services.k8s.aws/v1alpha1 - kind: Bucket - spec: - name: ${schema.spec.name}-data - -- id: configmap - template: - apiVersion: v1 - kind: ConfigMap - data: - BUCKET_NAME: ${bucket.spec.name} - BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn} ----- - -When you reference another resource in a CEL expression, it automatically creates a dependency. -kro ensures the referenced resource is created first. - -For more information, see link:https://kro.run/docs/concepts/rgd/cel-expressions/[CEL Expressions^] in the kro documentation. - -=== Resource dependencies - -kro automatically infers dependencies from CEL expressions—you don't specify the order, you describe relationships. -When one resource references another using a CEL expression, kro creates a dependency and determines the correct creation order. - -[source,yaml] ----- -resources: -- id: bucket - template: - apiVersion: s3.services.k8s.aws/v1alpha1 - kind: Bucket - spec: - name: ${schema.spec.name}-data - -- id: notification - template: - apiVersion: s3.services.k8s.aws/v1alpha1 - kind: BucketNotification - spec: - bucket: ${bucket.spec.name} # Creates dependency: notification depends on bucket ----- - -The expression `${bucket.spec.name}` creates a dependency. -kro builds a directed acyclic graph (DAG) of all resources and their dependencies, then computes a topological order for creation. - -*Creation order*: Resources are created in topological order (dependencies first). - -*Parallel creation*: Resources with no dependencies are created simultaneously. - -*Deletion order*: Resources are deleted in reverse topological order (dependents first). - -*Circular dependencies*: Not allowed—kro rejects ResourceGraphDefinitions with circular dependencies during validation. - -You can view the computed creation order: - -[source,bash] ----- -kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}' ----- - -For more information, see link:https://kro.run/docs/concepts/rgd/dependencies-ordering/[Graph inference^] in the kro documentation. - -== Composing with ACK - -kro works seamlessly with the EKS Capability for ACK to compose {aws} resources with Kubernetes resources: - -[source,yaml] ----- -resources: -# Create {aws} S3 bucket with ACK -- id: bucket - template: - apiVersion: s3.services.k8s.aws/v1alpha1 - kind: Bucket - spec: - name: ${schema.spec.name}-files - -# Inject bucket details into Kubernetes ConfigMap -- id: config - template: - apiVersion: v1 - kind: ConfigMap - data: - BUCKET_NAME: ${bucket.spec.name} - BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn} - -# Use ConfigMap in application deployment -- id: deployment - template: - apiVersion: apps/v1 - kind: Deployment - spec: - template: - spec: - containers: - - name: app - envFrom: - - configMapRef: - name: ${config.metadata.name} ----- - -This pattern lets you create {aws} resources, extract their details (ARNs, URLs, endpoints), and inject them into your application configuration—all managed as a single unit. - -For more composition patterns and advanced examples, see <>. - -== Next steps - -* <> - Learn about EKS-specific patterns, RBAC, and integration with ACK and Argo CD -* link:https://kro.run/docs/overview[kro Documentation^] - Comprehensive kro documentation including advanced CEL expressions, validation patterns, and troubleshooting diff --git a/latest/ug/capabilities/kro-considerations.adoc b/latest/ug/capabilities/kro-considerations.adoc deleted file mode 100644 index 40f5df419..000000000 --- a/latest/ug/capabilities/kro-considerations.adoc +++ /dev/null @@ -1,208 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-considerations] -= kro considerations for EKS -:info_titleabbrev: Considerations - -[abstract] --- -Plan your kro deployment with EKS-specific patterns, RBAC configuration, and integration strategies. --- - -This topic covers important considerations for using the EKS Capability for kro, including when to use resource composition, RBAC patterns, and integration with other EKS capabilities. - -== When to use kro - -kro is designed for creating reusable infrastructure patterns and custom APIs that simplify complex resource management. - -*Use kro when you need to*: - -* Create self-service platforms with simplified APIs for application teams -* Standardize infrastructure patterns across teams (database + backup + monitoring) -* Manage resource dependencies and pass values between resources -* Build custom abstractions that hide implementation complexity -* Compose multiple ACK resources into higher-level building blocks -* Enable GitOps workflows for complex infrastructure stacks - -*Don't use kro when*: - -* Managing simple, standalone resources (use ACK or Kubernetes resources directly) -* You need dynamic runtime logic (kro is declarative, not imperative) -* Resources don't have dependencies or shared configuration - -kro excels at creating "paved paths" - opinionated, reusable patterns that make it easy for teams to deploy complex infrastructure correctly. - -== RBAC patterns - -kro enables separation of concerns between platform teams who create ResourceGraphDefinitions and application teams who create instances. - -=== Platform team responsibilities - -Platform teams create and maintain ResourceGraphDefinitions (RGDs) that define custom APIs. - -*Permissions needed*: - -* Create, update, delete ResourceGraphDefinitions -* Manage underlying resource types (Deployments, Services, ACK resources) -* Access to all namespaces where RGDs will be used - -*Example ClusterRole for platform team*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: platform-kro-admin -rules: -- apiGroups: ["kro.run"] - resources: ["resourcegraphdefinitions"] - verbs: ["*"] -- apiGroups: ["*"] - resources: ["*"] - verbs: ["get", "list", "watch"] ----- - -For detailed RBAC configuration, see <>. - -=== Application team responsibilities - -Application teams create instances of custom resources defined by RGDs without needing to understand the underlying complexity. - -*Permissions needed*: - -* Create, update, delete instances of custom resources -* Read access to their namespace -* No access to underlying resources or RGDs - -*Benefits*: - -* Teams use simple, high-level APIs -* Platform teams control implementation details -* Reduced risk of misconfiguration -* Faster onboarding for new team members - -== Integration with other EKS capabilities - -=== Composing ACK resources - -kro is particularly powerful when combined with ACK to create infrastructure patterns. - -*Common patterns*: - -* **Application with storage**: S3 bucket + SQS queue + notification configuration -* **Database stack**: RDS instance + parameter group + security group + Secrets Manager secret -* **Networking**: VPC + subnets + route tables + security groups + NAT gateways -* **Compute with storage**: EC2 instance + EBS volumes + IAM instance profile - -kro handles dependency ordering, passes values between resources (like ARNs and connection strings), and manages the full lifecycle as a single unit. - -For examples of composing ACK resources, see <>. - -=== GitOps with Argo CD - -Use the EKS Capability for Argo CD to deploy both RGDs and instances from Git repositories. - -*Repository organization*: - -* **Platform repo**: Contains ResourceGraphDefinitions managed by platform team -* **Application repos**: Contain instances of custom resources managed by app teams -* **Shared repo**: Contains both RGDs and instances for smaller organizations - -*Considerations*: - -* Deploy RGDs before instances (Argo CD sync waves can help) -* Use separate Argo CD Projects for platform and application teams -* Platform team controls RGD repository access -* Application teams have read-only access to RGD definitions - -For more on Argo CD, see <>. - -== Organizing ResourceGraphDefinitions - -Organize RGDs by purpose, complexity, and ownership. - -*By purpose*: - -* **Infrastructure**: Database stacks, networking, storage -* **Application**: Web apps, APIs, batch jobs -* **Platform**: Shared services, monitoring, logging - -*By complexity*: - -* **Simple**: 2-3 resources with minimal dependencies -* **Moderate**: 5-10 resources with some dependencies -* **Complex**: 10+ resources with complex dependencies - -*Naming conventions*: - -* Use descriptive names: `webapp-with-database`, `s3-notification-queue` -* Include version in name for breaking changes: `webapp-v2` -* Use consistent prefixes for related RGDs: `platform-*`, `app-*` - -*Namespace strategy*: - -* RGDs are cluster-scoped (not namespaced) -* Instances are namespaced -* Use namespace selectors in RGDs to control where instances can be created - -== Versioning and updates - -Plan for RGD evolution and instance migration. - -*RGD updates*: - -* **Non-breaking changes**: Update RGD in place (add optional fields, new resources with includeWhen) -* **Breaking changes**: Create new RGD with different name (webapp-v2) -* **Deprecation**: Mark old RGDs with annotations, communicate migration timeline - -*Instance migration*: - -* Create new instances with updated RGD -* Validate new instances work correctly -* Delete old instances -* kro handles underlying resource updates automatically - -*Best practices*: - -* Test RGD changes in non-production environments first -* Use semantic versioning in RGD names for major changes -* Document breaking changes and migration paths -* Provide migration examples for application teams - -== Validation and testing - -Validate RGDs before deploying to production. - -*Validation strategies*: - -* **Schema validation**: kro validates RGD structure automatically -* **Dry-run instances**: Create test instances in development namespaces -* **Integration tests**: Verify composed resources work together -* **Policy enforcement**: Use admission controllers to enforce organizational standards - -*Common issues to test*: - -* Resource dependencies and ordering -* Value passing between resources (CEL expressions) -* Conditional resource inclusion (includeWhen) -* Status propagation from underlying resources -* RBAC permissions for instance creation - -== Upstream documentation - -For detailed information on using kro: - -* link:https://kro.run/docs/guides/getting-started[Getting Started with kro^] - Creating ResourceGraphDefinitions -* link:https://kro.run/docs/concepts/cel[CEL Expressions^] - Writing CEL expressions -* link:https://kro.run/docs/guides/[kro Guides^] - Advanced composition patterns -* link:https://kro.run/docs/troubleshooting[Troubleshooting^] - Troubleshooting and debugging - -== Next steps - -* <> - Configure RBAC for platform and application teams -* <> - Understand kro concepts and resource lifecycle -* <> - Troubleshoot kro issues -* <> - Learn about ACK resources for composition -* <> - Deploy RGDs and instances with GitOps diff --git a/latest/ug/capabilities/kro-create-cli.adoc b/latest/ug/capabilities/kro-create-cli.adoc deleted file mode 100644 index 542aead0c..000000000 --- a/latest/ug/capabilities/kro-create-cli.adoc +++ /dev/null @@ -1,162 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-create-cli] -= Create a kro capability using the {aws} CLI -:info_titleabbrev: {aws} CLI - -This topic describes how to create a kro (Kube Resource Orchestrator) capability using the {aws} CLI. - -== Prerequisites - -* *{aws} CLI* – Version `{auto-cli-v2-version}` or later. To check your version, run `aws --version`. For more information, see link:cli/latest/userguide/cli-chap-install.html[Installing, updating, and uninstalling the {aws} CLI,type="documentation"] in the {aws} Command Line Interface User Guide. -* *`kubectl`* – A command line tool for working with Kubernetes clusters. For more information, see <>. - -== Step 1: Create an IAM Capability Role - -Create a trust policy file: - -[source,bash,subs="verbatim,attributes"] ----- -cat > kro-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -aws iam create-role \ - --role-name KROCapabilityRole \ - --assume-role-policy-document file://kro-trust-policy.json ----- - -[NOTE] -==== -Unlike ACK and Argo CD, kro does not require additional IAM permissions. -kro operates entirely within your cluster and does not make {aws} API calls. -The role is only needed to establish the trust relationship with the EKS capabilities service. -==== - -== Step 2: Create the kro capability - -Create the kro capability resource on your cluster. Replace [.replaceable]`region-code` with the {aws} Region where your cluster is located (such as `us-west-2`) and [.replaceable]`my-cluster` with your cluster name. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks create-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name my-kro \ - --type KRO \ - --role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/KROCapabilityRole \ - --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 [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name my-kro \ - --query 'capability.status' \ - --output text ----- - -The capability is ready when the status shows `ACTIVE`. - -You can also view the full capability details: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name my-kro ----- - -== Step 4: Grant permissions to manage Kubernetes resources - -By default, kro can only create and manage ResourceGraphDefinitions and their instances. -To allow kro to create and manage the underlying Kubernetes resources defined in your ResourceGraphDefinitions, associate the `AmazonEKSClusterAdminPolicy` access policy with the capability's access entry. - -Get the capability role ARN: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -CAPABILITY_ROLE_ARN=$(aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name my-kro \ - --query 'capability.roleArn' \ - --output text) ----- - -Associate the cluster admin policy: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks associate-access-policy \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --principal-arn $CAPABILITY_ROLE_ARN \ - --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ - --access-scope type=cluster ----- - -[IMPORTANT] -==== -The `AmazonEKSClusterAdminPolicy` grants broad permissions to create and manage all Kubernetes resources and is intended to streamline getting started. -For production use, create more restrictive RBAC policies that grant only the permissions needed for the specific resources your ResourceGraphDefinitions will manage. -For guidance on configuring least-privilege permissions, see <> and <>. -==== - -== Step 5: Verify custom resources are available - -After the capability is active, verify that kro custom resources are available in your cluster: - -[source,bash,subs="verbatim,attributes"] ----- -kubectl api-resources | grep kro.run ----- - -You should see the `ResourceGraphDefinition` resource type listed. - -== Next steps - -* <> - Understand kro concepts and resource composition -* <> - Learn about SimpleSchema, CEL expressions, and composition patterns -* <> - Manage your kro capability resource diff --git a/latest/ug/capabilities/kro-create-console.adoc b/latest/ug/capabilities/kro-create-console.adoc deleted file mode 100644 index be931e094..000000000 --- a/latest/ug/capabilities/kro-create-console.adoc +++ /dev/null @@ -1,104 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-create-console] -= Create a kro capability using the Console -:info_titleabbrev: Console - -This topic describes how to create a kro (Kube Resource Orchestrator) capability using the {aws-management-console}. - -== Create the kro capability - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. - -. Select your cluster name to open the cluster detail page. - -. Choose the *Capabilities* tab. - -. In the left navigation, choose *kro (Kube Resource Orchestrator)*. - -. Choose *Create kro capability*. - -. 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 kro role* -+ -This opens the IAM console in a new tab with pre-populated trust policy. -The role requires no additional IAM permissions since kro operates entirely within your cluster. -+ -After creating the role, return to the EKS console and the role will be automatically selected. -+ -[NOTE] -==== -Unlike ACK and Argo CD, kro does not require additional IAM permissions beyond the trust policy. -kro operates entirely within your cluster and does not make {aws} API calls. -==== - -. Choose *Create*. - -The capability creation process begins. - -== Verify the capability is active - -. On the *Capabilities* tab, view the kro capability status. - -. Wait for the status to change from `CREATING` to `ACTIVE`. - -. Once active, the capability is ready to use. - -For information about capability statuses and troubleshooting, see <>. - -== Grant permissions to manage Kubernetes resources - -By default, kro can only create and manage ResourceGraphDefinitions and their instances. -To allow kro to create and manage the underlying Kubernetes resources defined in your ResourceGraphDefinitions, associate the `AmazonEKSClusterAdminPolicy` access policy with the capability's access entry. - -. In the EKS console, navigate to your cluster's *Access* tab. - -. Under *Access entries*, find the entry for your kro capability role (it will have the role ARN you created earlier). - -. Choose the access entry to open its details. - -. In the *Access policies* section, choose *Associate access policy*. - -. Select `AmazonEKSClusterAdminPolicy` from the policy list. - -. For *Access scope*, select *Cluster*. - -. Choose *Associate*. - -[IMPORTANT] -==== -The `AmazonEKSClusterAdminPolicy` grants broad permissions to create and manage all Kubernetes resources and is intended to streamline getting started. -For production use, create more restrictive RBAC policies that grant only the permissions needed for the specific resources your ResourceGraphDefinitions will manage. -For guidance on configuring least-privilege permissions, see <> and <>. -==== - -== Verify custom resources are available - -After the capability is active, verify that kro custom resources are available in your cluster. - -*Using the console* - -. Navigate to your cluster in the Amazon EKS console -. Choose the *Resources* tab -. Choose *Extensions* -. Choose *CustomResourceDefinitions* - -You should see the `ResourceGraphDefinition` resource type listed. - -*Using kubectl* - -[source,bash,subs="verbatim,attributes"] ----- -kubectl api-resources | grep kro.run ----- - -You should see the `ResourceGraphDefinition` resource type listed. - -== Next steps - -* <> - Understand kro concepts and resource composition -* <> - Learn about SimpleSchema, CEL expressions, and composition patterns -* <> - Manage your kro capability resource diff --git a/latest/ug/capabilities/kro-create-eksctl.adoc b/latest/ug/capabilities/kro-create-eksctl.adoc deleted file mode 100644 index f8f1c8a64..000000000 --- a/latest/ug/capabilities/kro-create-eksctl.adoc +++ /dev/null @@ -1,139 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-create-eksctl] -= Create a kro capability using eksctl -:info_titleabbrev: eksctl - -This topic describes how to create a kro (Kube Resource Orchestrator) 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: - -[source,bash,subs="verbatim,attributes"] ----- -cat > kro-trust-policy.json << 'EOF' -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} -EOF ----- - -Create the IAM role: - -[source,bash,subs="verbatim,attributes"] ----- -aws iam create-role \ - --role-name KROCapabilityRole \ - --assume-role-policy-document file://kro-trust-policy.json ----- - -[NOTE] -==== -Unlike ACK and Argo CD, kro does not require additional IAM permissions beyond the trust policy. -kro operates entirely within your cluster and does not make {aws} API calls. -==== - -== Step 2: Create the kro capability - -Create the kro capability using eksctl. -Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -eksctl create capability \ - --region [.replaceable]`region-code` \ - --cluster [.replaceable]`my-cluster` \ - --name my-kro \ - --type KRO \ - --role-arn arn:aws:iam::[.replaceable]`111122223333`:role/KROCapabilityRole ----- - -The command returns immediately, but the capability takes some time to become active. - -== Step 3: Verify the capability is active - -Check the capability status. -Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -eksctl get capability \ - --region [.replaceable]`region-code` \ - --cluster [.replaceable]`my-cluster` \ - --name my-kro ----- - -The capability is ready when the status shows `ACTIVE`. - -== Step 4: Grant permissions to manage Kubernetes resources - -By default, kro can only create and manage ResourceGraphDefinitions and their instances. -To allow kro to create and manage the underlying Kubernetes resources defined in your ResourceGraphDefinitions, associate the `AmazonEKSClusterAdminPolicy` access policy with the capability's access entry. - -Get the capability role ARN: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -CAPABILITY_ROLE_ARN=$(aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster [.replaceable]`my-cluster` \ - --name my-kro \ - --query 'capability.roleArn' \ - --output text) ----- - -Associate the cluster admin policy: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks associate-access-policy \ - --region [.replaceable]`region-code` \ - --cluster [.replaceable]`my-cluster` \ - --principal-arn $CAPABILITY_ROLE_ARN \ - --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ - --access-scope type=cluster ----- - -[IMPORTANT] -==== -The `AmazonEKSClusterAdminPolicy` grants broad permissions to create and manage all Kubernetes resources and is intended to streamline getting started. -For production use, create more restrictive RBAC policies that grant only the permissions needed for the specific resources your ResourceGraphDefinitions will manage. -For guidance on configuring least-privilege permissions, see <> and <>. -==== - -== Step 5: Verify custom resources are available - -After the capability is active, verify that kro custom resources are available in your cluster: - -[source,bash,subs="verbatim,attributes"] ----- -kubectl api-resources | grep kro.run ----- - -You should see the `ResourceGraphDefinition` resource type listed. - -== Next steps - -* <> - Understand kro concepts and resource composition -* <> - Learn about SimpleSchema, CEL expressions, and composition patterns -* <> - Manage your kro capability resource diff --git a/latest/ug/capabilities/kro-permissions.adoc b/latest/ug/capabilities/kro-permissions.adoc deleted file mode 100644 index 1db9e4d97..000000000 --- a/latest/ug/capabilities/kro-permissions.adoc +++ /dev/null @@ -1,211 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-permissions] -= Configure kro permissions -:info_titleabbrev: Configure permissions - -[abstract] --- -Configure Kubernetes RBAC permissions to control access to kro ResourceGraphDefinitions and custom resource instances. --- - -Unlike ACK and Argo CD, kro does not require IAM permissions. -kro operates entirely within your Kubernetes cluster and does not make {aws} API calls. -Control access to kro resources using standard Kubernetes RBAC. - -== How permissions work with kro - -kro uses two types of Kubernetes resources with different scopes: - -*ResourceGraphDefinitions*: Cluster-scoped resources that define custom APIs. -Typically managed by platform teams who design and maintain organizational standards. - -*Instances*: Namespace-scoped custom resources created from ResourceGraphDefinitions. -Can be created by application teams with appropriate RBAC permissions. - -By default, the kro capability has permissions to manage ResourceGraphDefinitions and their instances through the `AmazonEKSKROPolicy` access entry policy. -However, kro requires additional permissions to create and manage the underlying Kubernetes resources defined in your ResourceGraphDefinitions (such as Deployments, Services, or ACK resources). -You must grant these permissions through access entry policies or Kubernetes RBAC. -For details on granting these permissions, see <>. - -== Platform team permissions - -Platform teams need permissions to create and manage ResourceGraphDefinitions. - -*Example ClusterRole for platform teams*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: kro-platform-admin -rules: -- apiGroups: ["kro.run"] - resources: ["resourcegraphdefinitions"] - verbs: ["*"] ----- - -*Bind to platform team members*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: platform-team-kro-admin -subjects: -- kind: Group - name: platform-team - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: kro-platform-admin - apiGroup: rbac.authorization.k8s.io ----- - -== Application team permissions - -Application teams need permissions to create instances of custom resources in their namespaces. - -*Example Role for application teams*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: kro-app-developer - namespace: my-app -rules: -- apiGroups: ["kro.run"] - resources: ["webapps", "databases"] - verbs: ["create", "get", "list", "update", "delete", "patch"] ----- - -*Bind to application team members*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: app-team-kro-developer - namespace: my-app -subjects: -- kind: Group - name: app-team - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: Role - name: kro-app-developer - apiGroup: rbac.authorization.k8s.io ----- - -[NOTE] -==== -The API group in the Role (`kro.run` in this example) must match the `apiVersion` defined in your ResourceGraphDefinition's schema. -==== - -== Read-only access - -Grant read-only access to view ResourceGraphDefinitions and instances without modification permissions. - -*Read-only ClusterRole*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: kro-viewer -rules: -- apiGroups: ["kro.run"] - resources: ["resourcegraphdefinitions"] - verbs: ["get", "list", "watch"] ----- - -*Read-only Role for instances*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: kro-instance-viewer - namespace: my-app -rules: -- apiGroups: ["kro.run"] - resources: ["webapps", "databases"] - verbs: ["get", "list", "watch"] ----- - -== Multi-namespace access - -Grant application teams access to multiple namespaces using ClusterRoles with RoleBindings. - -*ClusterRole for multi-namespace access*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: kro-multi-namespace-developer -rules: -- apiGroups: ["kro.run"] - resources: ["webapps"] - verbs: ["create", "get", "list", "update", "delete"] ----- - -*Bind to specific namespaces*: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: app-team-dev-access - namespace: development -subjects: -- kind: Group - name: app-team - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: kro-multi-namespace-developer - apiGroup: rbac.authorization.k8s.io ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: app-team-staging-access - namespace: staging -subjects: -- kind: Group - name: app-team - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: kro-multi-namespace-developer - apiGroup: rbac.authorization.k8s.io ----- - -== Best practices - -*Principle of least privilege*: Grant only the minimum permissions needed for each team's responsibilities. - -*Use groups instead of individual users*: Bind roles to groups rather than individual users for easier management. - -*Separate platform and application concerns*: Platform teams manage ResourceGraphDefinitions, application teams manage instances. - -*Namespace isolation*: Use namespaces to isolate different teams or environments, with RBAC controlling access to each namespace. - -*Read-only access for auditing*: Provide read-only access to security and compliance teams for auditing purposes. - -== Next steps - -* <> - Understand kro concepts and resource composition -* <> - Understand SimpleSchema, CEL expressions, and composition patterns -* <> - Review security best practices for capabilities diff --git a/latest/ug/capabilities/kro-troubleshooting.adoc b/latest/ug/capabilities/kro-troubleshooting.adoc deleted file mode 100644 index a7dfb1bb8..000000000 --- a/latest/ug/capabilities/kro-troubleshooting.adoc +++ /dev/null @@ -1,276 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro-troubleshooting] -= Troubleshoot issues with kro capabilities -:info_titleabbrev: Troubleshooting - -[abstract] --- -Diagnose and resolve common issues with the EKS Capability for kro. --- - -This topic provides troubleshooting guidance for the EKS Capability for kro, including capability health checks, RBAC permissions, CEL expression errors, and resource composition issues. - -[NOTE] -==== -EKS Capabilities are fully managed and run outside your cluster. -You don't have access to controller logs or the `kro-system` namespace. -Troubleshooting focuses on capability health, RBAC configuration, and resource status. -==== - -== Capability is ACTIVE but ResourceGraphDefinitions aren't working - -If your kro capability shows `ACTIVE` status but ResourceGraphDefinitions aren't creating underlying resources, check the capability health, RBAC permissions, and resource status. - -*Check capability health*: - -You can view capability health and status issues in the EKS console or using the {aws} CLI. - -*Console*: - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name. -. Choose the *Observability* tab. -. Choose *Monitor cluster*. -. Choose the *Capabilities* tab to view health and status for all capabilities. - -*{aws} CLI*: - -[source,bash] ----- -# View capability status and health -aws eks describe-capability \ - --region region-code \ - --cluster-name my-cluster \ - --capability-name my-kro - -# Look for issues in the health section ----- - -*Common causes*: - -* *RBAC permissions missing*: kro lacks permissions to create underlying Kubernetes resources -* *Invalid CEL expressions*: Syntax errors in ResourceGraphDefinition -* *Resource dependencies*: Dependent resources not ready -* *Schema validation*: Instance doesn't match RGD schema requirements - -*Verify RBAC permissions*: - -[source,bash] ----- -# Check if capability has cluster admin policy -kubectl get accessentry -A | grep kro ----- - -If the capability doesn't have the required permissions, associate the `AmazonEKSClusterAdminPolicy` with the kro capability's access entry, or create more restrictive RBAC policies for production use. -See <> for details. - -*Check ResourceGraphDefinition status*: - -[source,bash] ----- -# List all RGDs -kubectl get resourcegraphdefinition - -# Describe specific RGD -kubectl describe resourcegraphdefinition my-rgd - -# Check for validation errors -kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions}' ----- - -ResourceGraphDefinitions have three key status conditions: - -* `ResourceGraphAccepted` - Whether the RGD passed validation (CEL syntax, type checking, field existence) -* `KindReady` - Whether the CRD for your custom API was generated and registered -* `ControllerReady` - Whether kro is actively watching for instances of your custom API - -If `ResourceGraphAccepted` is `False`, check the condition message for validation errors like unknown fields, type mismatches, or circular dependencies. - -== Instances created but underlying resources not appearing - -If custom resource instances exist but the underlying Kubernetes resources (Deployments, Services, ConfigMaps) aren't being created, verify kro has permissions and check for composition errors. - -*Check instance status*: - -[source,bash,subs="verbatim,quotes"] ----- -# Describe the instance (replace with your custom resource kind and name) -kubectl describe [.replaceable]`custom-kind` [.replaceable]`my-instance` - -# View instance events -kubectl get events --field-selector involvedObject.name=[.replaceable]`my-instance` - -# Check instance status conditions -kubectl get [.replaceable]`custom-kind` [.replaceable]`my-instance` -o jsonpath='{.status.conditions}' - -# Check instance state -kubectl get [.replaceable]`custom-kind` [.replaceable]`my-instance` -o jsonpath='{.status.state}' ----- - -Instances have a `state` field showing high-level status: - -* `ACTIVE` - Instance is successfully running -* `IN_PROGRESS` - Instance is being processed or reconciled -* `FAILED` - Instance failed to reconcile -* `DELETING` - Instance is being deleted -* `ERROR` - An error occurred during processing - -Instances also have four status conditions: - -* `InstanceManaged` - Finalizers and labels are properly set -* `GraphResolved` - Runtime graph created and resources resolved -* `ResourcesReady` - All resources created and ready -* `Ready` - Overall instance health (only becomes `True` when all sub-conditions are `True`) - -Focus on the `Ready` condition to determine instance health. -If `Ready` is `False`, check the sub-conditions to identify which phase failed. - -*Verify RBAC permissions*: - -The kro capability needs permissions to create the underlying Kubernetes resources defined in your ResourceGraphDefinitions. - -[source,bash] ----- -# Check if the capability has the AmazonEKSClusterAdminPolicy -kubectl get accessentry -A | grep kro ----- - -If permissions are missing, associate the `AmazonEKSClusterAdminPolicy` with the kro capability's access entry, or create more restrictive RBAC policies for production use. -See <> for details. - -== CEL expression errors - -CEL expression errors are caught at ResourceGraphDefinition creation time, not when instances are created. -kro validates all CEL syntax, type-checks expressions against Kubernetes schemas, and verifies field existence when you create the RGD. - -*Common CEL validation errors*: - -* *Undefined field reference*: Referencing a field that doesn't exist in the schema or resource -* *Type mismatch*: Expression returns wrong type (e.g., string where integer expected) -* *Invalid syntax*: Missing brackets, quotes, or operators in CEL expression -* *Unknown resource type*: Referencing a CRD that doesn't exist in the cluster - -*Check RGD validation status*: - -[source,bash,subs="verbatim,quotes"] ----- -# Check if RGD was accepted -kubectl get resourcegraphdefinition [.replaceable]`my-rgd` -o jsonpath='{.status.conditions[?(@.type=="ResourceGraphAccepted")]}' - -# View detailed validation errors -kubectl describe resourcegraphdefinition [.replaceable]`my-rgd` ----- - -If `ResourceGraphAccepted` is `False`, the condition message contains the validation error. - -*Example valid CEL expressions*: - -[source,yaml] ----- -# Reference schema field -${schema.spec.appName} - -# Conditional expression -${schema.spec.replicas > 1} - -# String template (expressions must return strings) -name: "${schema.spec.appName}-service" - -# Standalone expression (can be any type) -replicas: ${schema.spec.replicaCount} - -# Resource reference -${deployment.status.availableReplicas} - -# Optional field access (returns null if field doesn't exist) -${configmap.data.?DATABASE_URL} ----- - -== Resource dependencies not resolving - -kro automatically infers dependencies from CEL expressions and creates resources in the correct order. -If resources aren't being created as expected, check the dependency order and resource readiness. - -*View computed creation order*: - -[source,bash,subs="verbatim,quotes"] ----- -# See the order kro will create resources -kubectl get resourcegraphdefinition [.replaceable]`my-rgd` -o jsonpath='{.status.topologicalOrder}' ----- - -This shows the computed order based on CEL expression references between resources. - -*Check resource readiness*: - -[source,bash,subs="verbatim,quotes"] ----- -# View instance status to see which resources are ready -kubectl get [.replaceable]`custom-kind` [.replaceable]`my-instance` -o jsonpath='{.status}' - -# Check specific resource status -kubectl get deployment [.replaceable]`my-deployment` -o jsonpath='{.status.conditions}' ----- - -*Verify readyWhen conditions (if used)*: - -The `readyWhen` field is optional. -If not specified, resources are considered ready immediately after creation. -If you've defined `readyWhen` conditions, verify they correctly check for resource readiness: - -[source,yaml] ----- -resources: - - id: deployment - readyWhen: - - ${deployment.status.availableReplicas == deployment.spec.replicas} ----- - -*Check resource events*: - -[source,bash,subs="verbatim,quotes"] ----- -# View events for the underlying resources -kubectl get events -n [.replaceable]`namespace` --sort-by='.lastTimestamp' ----- - -== Schema validation failures - -If instances fail to create due to schema validation errors, verify the instance matches the RGD schema requirements. - -*Check validation errors*: - -[source,bash,subs="verbatim,quotes"] ----- -# Attempt to create instance and view error -kubectl apply -f instance.yaml - -# View existing instance validation status -kubectl describe [.replaceable]`custom-kind` [.replaceable]`my-instance` | grep -A 5 "Validation" ----- - -*Common validation issues*: - -* *Required fields missing*: Instance doesn't provide all required schema fields -* *Type mismatch*: Providing string where integer is expected -* *Invalid enum value*: Using value not in allowed list -* *Pattern mismatch*: String doesn't match regex pattern - -*Review RGD schema*: - -[source,bash,subs="verbatim,quotes"] ----- -# View the schema definition -kubectl get resourcegraphdefinition [.replaceable]`my-rgd` -o jsonpath='{.spec.schema}' ----- - -Ensure your instance provides all required fields with correct types. - -== Next steps - -* <> - kro considerations and best practices -* <> - Configure RBAC for platform and application teams -* <> - Understand kro concepts and resource lifecycle -* <> - General capability troubleshooting guidance diff --git a/latest/ug/capabilities/kro.adoc b/latest/ug/capabilities/kro.adoc deleted file mode 100644 index 89fdab9e2..000000000 --- a/latest/ug/capabilities/kro.adoc +++ /dev/null @@ -1,113 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#kro] -= Resource Composition with kro (Kube Resource Orchestrator) -:info_titleabbrev: kro - -[abstract] --- -Simplify resource management with kro (Kube Resource Orchestrator), a fully managed capability of Amazon EKS for Kubernetes resource composition and orchestration. --- - -*kro (Kube Resource Orchestrator)* is an open-source, Kubernetes-native project that allows you to define custom Kubernetes APIs using simple and straightforward configuration. -With kro, you can easily configure new custom APIs that create a group of Kubernetes objects and the logical operations between them. - -With EKS Capabilities, kro is fully managed by {aws}, eliminating the need to install, maintain, and scale kro controllers on your clusters. - - -== How kro Works - -kro introduces a Custom Resource Definition (CRD) called `ResourceGraphDefinition` (RGD) that enables simple and streamlined creation of custom Kubernetes APIs. -When you create a `ResourceGraphDefinition`, kro uses native Kubernetes extensions to create and manage new APIs in your cluster. -From this single resource specification, kro will create and register a new CRD for you based on your specification and will adapt to manage your newly defined custom resources. - -RGDs can include multiple resources, and kro will determine interdependencies and resource ordering, so you don't have to. -You can use simple syntax to inject configuration from one resource to another, greatly simplifying compositions and removing the need for "glue" operators in your cluster. -With kro, your custom resources can include native Kubernetes resources as well as any Custom Resource Definitions (CRDs) installed in the cluster. - -kro supports a single primary resource type: - -* *ResourceGraphDefinition (RGD)*: Defines a Kubernetes custom resource, encapsulating one or more underlying native or custom Kubernetes resources - -In addition to this resource, kro will create and manage the lifecycle of your custom resources created with it, as well as all of their constituent resources. - -kro integrates seamlessly with {aws} Controllers for Kubernetes (ACK), allowing you to compose workload resources with {aws} resources to create higher-level abstractions. -This enables you to create your own cloud building blocks, simplifying resource management and enabling reusable patterns with default and immutable configuration settings based on your organizational standards. - -== Benefits of kro - -kro enables platform teams to create custom Kubernetes APIs that compose multiple resources into higher-level abstractions. -This simplifies resource management by allowing developers to deploy complex applications using simple, standardized, and versioned custom resources. -You define reusable patterns for common resource combinations, enabling consistent resource creation across your organization. - -kro uses link:https://kubernetes.io/docs/reference/using-api/cel/[Common Expression Language (CEL) in Kubernetes] for passing values between resources and incorporating conditional logic, providing flexibility in resource composition. -You can compose both Kubernetes resources and {aws} resources managed by ACK into unified custom APIs, enabling complete application and infrastructure definitions. - -kro supports declarative configuration through Kubernetes manifests, enabling GitOps workflows and infrastructure as code practices that integrate seamlessly with your existing development processes. -As part of EKS Managed Capabilities, kro is fully managed by {aws}, eliminating the need to install, configure, and maintain kro controllers on your clusters. - -*Example: Creating a ResourceGraphDefinition* - -The following example shows a simple `ResourceGraphDefinition` that creates a web application with a Deployment and Service: - -[source,yaml] ----- -apiVersion: kro.run/v1alpha1 -kind: ResourceGraphDefinition -metadata: - name: web-application -spec: - schema: - apiVersion: v1alpha1 - kind: WebApplication - spec: - name: string - replicas: integer | default=3 - resources: - - id: deployment - template: - apiVersion: apps/v1 - kind: Deployment - metadata: - name: ${schema.spec.name} - spec: - replicas: ${schema.spec.replicas} - - id: service - template: - apiVersion: v1 - kind: Service - metadata: - name: ${schema.spec.name} ----- - -When users create instances of the `WebApplication` custom resource, kro automatically creates the corresponding Deployment and Service resources, managing their lifecycle along with the custom resource. - -== Integration with Other EKS Managed Capabilities - -kro integrates with other EKS Managed Capabilities. - -* *{aws} Controllers for Kubernetes (ACK)*: Use kro to compose ACK resources into higher-level abstractions, simplifying {aws} resource management. -* *Argo CD*: Use Argo CD to manage the deployment of kro custom resources across multiple clusters, enabling GitOps workflows for your platform building blocks and application stacks. - -== Getting Started with kro - -To get started with the EKS Capability for kro: - -. <> on your EKS cluster through the {aws} Console, {aws} CLI, or your preferred infrastructure as code tool. -. Create ResourceGraphDefinitions (RGDs) that define your custom APIs and resource compositions. -. Apply instances of your custom resources to provision and manage the underlying Kubernetes and {aws} resources. - -include::create-kro-capability.adoc[leveloffset=+1] - -include::kro-concepts.adoc[leveloffset=+1] - -include::kro-permissions.adoc[leveloffset=+1] - -include::kro-considerations.adoc[leveloffset=+1] - -include::kro-troubleshooting.adoc[leveloffset=+1] - -include::kro-comparison.adoc[leveloffset=+1] - - diff --git a/latest/ug/capabilities/working-with-argocd.adoc b/latest/ug/capabilities/working-with-argocd.adoc deleted file mode 100644 index b20cdfe4c..000000000 --- a/latest/ug/capabilities/working-with-argocd.adoc +++ /dev/null @@ -1,67 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#working-with-argocd] -= Working with Argo CD -:info_titleabbrev: Working with Argo CD - -[abstract] --- -Deploy and manage applications using GitOps with the Argo CD managed capability. --- - -With Argo CD, you define applications in Git repositories and Argo CD automatically syncs them to your Kubernetes clusters. -This enables declarative, version-controlled application deployment with automated drift detection. - -== Prerequisites - -Before working with Argo CD, you need: - -* An EKS cluster with the Argo CD capability created (see <>) -* A Git repository containing Kubernetes manifests -* `kubectl` configured to communicate with your cluster - -== Common tasks - -The following topics guide you through common Argo CD tasks: - -*<>* - Configure Argo CD to access your Git repositories using {aws} Secrets Manager, {aws} CodeConnections, or Kubernetes Secrets. - -*<>* - Register target clusters where Argo CD will deploy applications. - -*<>* - Organize applications and enforce security boundaries using Projects for multi-tenant environments. - -*<>* - Create Applications that deploy from Git repositories with automated or manual sync policies. - -*<>* - Use ApplicationSets to deploy applications across multiple environments or clusters using templates and generators. - -== Access the Argo CD UI - -Access the Argo CD UI through the EKS console: - -. Open the Amazon EKS console -. Select your cluster -. Choose the *Capabilities* tab -. Choose *Argo CD* -. Choose *Open Argo CD UI* - -The UI provides visual application topology, sync status and history, resource health and events, manual sync controls, and application management. - -== Upstream documentation - -For detailed information about Argo CD features: - -* https://argo-cd.readthedocs.io/[Argo CD Documentation^] - Complete user guide -* https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/[Application Spec^] - Full Application API reference -* https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/[ApplicationSet Guide^] - ApplicationSet patterns and examples -* https://github.com/argoproj/argo-cd[Argo CD GitHub^] - Source code and examples - -include::argocd-configure-repositories.adoc[leveloffset=+1] - -include::argocd-register-clusters.adoc[leveloffset=+1] - -include::argocd-projects.adoc[leveloffset=+1] - -include::argocd-create-application.adoc[leveloffset=+1] - -include::argocd-applicationsets.adoc[leveloffset=+1] diff --git a/latest/ug/capabilities/working-with-capabilities.adoc b/latest/ug/capabilities/working-with-capabilities.adoc deleted file mode 100644 index 30902947e..000000000 --- a/latest/ug/capabilities/working-with-capabilities.adoc +++ /dev/null @@ -1,281 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#working-with-capabilities] -= Working with capability resources -:info_titleabbrev: Working with capabilities - -[abstract] --- -Learn how to manage capability resources on your Amazon EKS clusters, including listing, describing, updating, and deleting capabilities. --- - -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*: - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name. -. Choose the *Capabilities* tab to view status for all capabilities. -. For detailed health information, choose the *Observability* tab, then *Monitor cluster*, then the *Capabilities* tab. - -*{aws} CLI*: - -[source,bash] ----- -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 <> 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_FAILED*: 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_FAILED*: Configuration update failed. -Check the capability health section for details and verify IAM permissions. - -[TIP] -==== -For detailed troubleshooting guidance, see: - -* <> - General capability troubleshooting -* <> - ACK-specific issues -* <> - Argo CD-specific issues -* <> - kro-specific issues -==== - -== Create capabilities - -To create a capability on your cluster, see the following topics: - -* <> – Create an ACK capability to manage {aws} resources using Kubernetes APIs -* <> – Create an Argo CD capability for GitOps continuous delivery -* <> – Create a kro capability for resource composition and orchestration - - -== List capabilities - -You can list all capability resources on a cluster. - -=== Console - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name to open the cluster detail page. -. Choose the *Capabilities* tab. -. View capability resources under *Managed capabilities*. - -=== {aws} CLI - -Use the `list-capabilities` command to view all capabilities on your cluster. Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in and replace [.replaceable]`my-cluster` with the name of your cluster. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks list-capabilities \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` ----- - -[source,json] ----- -{ - "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 - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name to open the cluster detail page. -. Choose the *Capabilities* tab. -. Choose the capability you want to view from *Managed capabilities*. -. View the capability details, including status, configuration, and creation time. - -=== {aws} CLI - -Use the `describe-capability` command to view detailed information. Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in, replace [.replaceable]`my-cluster` with the name of your cluster, and replace [.replaceable]`capability-name` with the capability name (ack, argocd, or kro). - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks describe-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name [.replaceable]`capability-name` ----- - -*Example output:* - -[source,json] ----- -{ - "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: - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks update-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name [.replaceable]`capability-name` \ - --role-arn arn:aws:iam::[.replaceable]`111122223333`:role/[.replaceable]`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 <> -==== - -=== Console - -. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters. -. Select your cluster name to open the cluster detail page. -. Choose the *Capabilities* tab. -. Select the capability you want to delete from the list of *Managed capabilities*. -. Choose *Delete capability*. -. In the confirmation dialog, type the name of the capability to confirm deletion. -. Choose *Delete*. - -=== {aws} CLI - -Use the `delete-capability` command to delete a capability resource: - -Replace [.replaceable]`region-code` with the {aws} Region that your cluster is in, replace [.replaceable]`my-cluster` with the name of your cluster, and replace [.replaceable]`capability-name` with the capability name to delete. - -[source,bash,subs="verbatim,attributes,quotes"] ----- -aws eks delete-capability \ - --region [.replaceable]`region-code` \ - --cluster-name [.replaceable]`my-cluster` \ - --capability-name [.replaceable]`capability-name` ----- - -== Next steps - -* <> – Learn about the Kubernetes resources provided by each capability type -* <> – Understand ACK concepts and resource lifecycle -* <> – Working with Argo CD capabilities for GitOps workflows -* <> – Understand kro concepts and resource composition diff --git a/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc b/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc index a77fd9c36..3bcea18c6 100644 --- a/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc +++ b/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc @@ -47,4 +47,4 @@ You see the Kubecost Overview page in your browser. It might take 5–10 minutes * *Cost allocation* – View monthly Amazon EKS costs and cumulative costs for each of your namespaces and other dimensions over the past seven days. This is helpful for understanding which parts of your application are contributing to Amazon EKS spend. -* *Assets* – View the costs of the {aws} infrastructure assets that are associated with your Amazon EKS resources. \ No newline at end of file +* *Assets* – View the costs of the {aws} infrastructure assets that are associated with your Amazon EKS resources. diff --git a/latest/ug/doc-history.adoc b/latest/ug/doc-history.adoc index 945be0bd4..345716976 100644 --- a/latest/ug/doc-history.adoc +++ b/latest/ug/doc-history.adoc @@ -19,14 +19,6 @@ https://docs.aws.amazon.com/eks/latest/userguide/doc-history.rss [.updates] == Updates -[.update,date="2025-11-30"] -=== Amazon EKS Capabilities -[.update-ulink] -link:eks/latest/userguide/capabilities.html[type="documentation"] - -Amazon EKS now provides fully managed cluster capabilities with EKS Capabilities, with support for declarative continuous deployment with support for Argo CD, {aws} resource management with support for {aws} Controllers for Kubernetes, and Kubernetes resource composition and orchestration with support for Kube Resource Orchestrator. - - [.update,date="2025-11-21"] === New {aws} managed policy [.update-ulink] diff --git a/latest/ug/images/apply-dns-policy-1.png b/latest/ug/images/apply-dns-policy-1.png deleted file mode 100644 index 6aa1ed987..000000000 Binary files a/latest/ug/images/apply-dns-policy-1.png and /dev/null differ diff --git a/latest/ug/images/apply-dns-policy-2.png b/latest/ug/images/apply-dns-policy-2.png deleted file mode 100644 index 4bd265077..000000000 Binary files a/latest/ug/images/apply-dns-policy-2.png and /dev/null differ diff --git a/latest/ug/images/eks-auto-to-on-prem.png b/latest/ug/images/eks-auto-to-on-prem.png deleted file mode 100644 index ff2b043a6..000000000 Binary files a/latest/ug/images/eks-auto-to-on-prem.png and /dev/null differ diff --git a/latest/ug/images/eksc-overview.png b/latest/ug/images/eksc-overview.png deleted file mode 100644 index 51ba99247..000000000 Binary files a/latest/ug/images/eksc-overview.png and /dev/null differ diff --git a/latest/ug/images/evaluation-order.png b/latest/ug/images/evaluation-order.png deleted file mode 100644 index 2c6bc1006..000000000 Binary files a/latest/ug/images/evaluation-order.png and /dev/null differ diff --git a/latest/ug/integrations/eks-integrations.adoc b/latest/ug/integrations/eks-integrations.adoc index 706a0507f..310d852d5 100644 --- a/latest/ug/integrations/eks-integrations.adoc +++ b/latest/ug/integrations/eks-integrations.adoc @@ -9,22 +9,18 @@ In addition to the services covered in other sections, Amazon EKS works with mor [.topiclist] [[Topic List]] -include::integration-backup.adoc[leveloffset=+1] - include::creating-resources-with-cloudformation.adoc[leveloffset=+1] -include::integration-codeconnections.adoc[leveloffset=+1] - include::integration-detective.adoc[leveloffset=+1] include::integration-guardduty.adoc[leveloffset=+1] -include::local-zones.adoc[leveloffset=+1] - include::integration-resilience-hub.adoc[leveloffset=+1] -include::integration-secrets-manager.adoc[leveloffset=+1] - include::integration-securitylake.adoc[leveloffset=+1] include::integration-vpc-lattice.adoc[leveloffset=+1] + +include::local-zones.adoc[leveloffset=+1] + +include::integration-backup.adoc[leveloffset=+1] \ No newline at end of file diff --git a/latest/ug/integrations/integration-codeconnections.adoc b/latest/ug/integrations/integration-codeconnections.adoc deleted file mode 100644 index b8c0495eb..000000000 --- a/latest/ug/integrations/integration-codeconnections.adoc +++ /dev/null @@ -1,67 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#integration-codeconnections] -= Connect to Git repositories with {aws} CodeConnections -:info_titleabbrev: {aws} CodeConnections - -[abstract] --- -{aws} CodeConnections provides secure authentication to third-party Git repositories like GitHub, GitLab, and Bitbucket. --- - -link:dtconsole/latest/userguide/welcome-connections.html[{aws} CodeConnections,type="documentation"] provides a secure way to connect {aws} services to third-party source code repositories. -{aws} CodeConnections supports GitHub, GitLab, Bitbucket, and link:dtconsole/latest/userguide/supported-versions-connections.html[other providers,type="documentation"]. -To learn more and get started, see link:dtconsole/latest/userguide/connections.html[Working with connections,type="documentation"]. - -[#integration-codeconnections-use] -== Use {aws} CodeConnections with Argo CD - -When using the EKS capability for Argo CD, you can choose to use {aws} CodeConnections to enable secure authentication to Git repositories without managing long-lived credentials or personal access tokens. -{aws} CodeConnections handles the OAuth authentication flow and manages the connection to your Git provider, providing a secure and manageable approach to accessing your GitOps repositories and application manifests stored in third-party Git providers. - -*Prerequisites* - -* An Amazon EKS cluster with the Argo CD capability created -* A connection created in {aws} CodeConnections to your Git provider -* IAM permissions configured for Argo CD to use the connection - -*To configure CodeConnections for Argo CD repository access* - -. Create a connection in the CodeConnections console: -.. Open the link:https://console.aws.amazon.com/codesuite/settings/connections[CodeConnections console^]. -.. Choose *Create connection*. -.. Select your provider (GitHub, GitLab, or Bitbucket) and follow the authentication flow. -.. Note the connection ARN for use in your Argo CD configuration. - -. Ensure the Argo CD capability role has permissions to use the connection with a resource-based policy: -+ -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "codeconnections:UseConnection", - "codeconnections:GetConnection" - ], - "Resource": "arn:aws:codeconnections:region:account-id:connection/connection-id" - } - ] -} ----- - -. Configure Argo CD to reference the CodeConnections resource when adding a repository, using the CodeConnections resource endpoint as the repository url. The Argo CD capability uses the connection to authenticate to your Git provider without requiring long-lived credentials. - -[#integration-codeconnections-considerations] -== Considerations for using CodeConnections with Argo CD - -When using {aws} CodeConnections with the EKS Capability for Argo CD, keep the following in mind: - -* The CodeConnections connection must be in the same {aws} Region as your EKS cluster -* The Argo CD capability role must have `codeconnections:UseConnection` and `codeconnections:GetConnection` permissions -* CodeConnections manages the OAuth flow and credential lifecycle automatically - -For more information about configuring repository access with Argo CD, see <>. diff --git a/latest/ug/integrations/integration-secrets-manager.adoc b/latest/ug/integrations/integration-secrets-manager.adoc deleted file mode 100644 index bd0e5f749..000000000 --- a/latest/ug/integrations/integration-secrets-manager.adoc +++ /dev/null @@ -1,102 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#integration-secrets-manager] -= Manage application secrets with {aws} Secrets Manager -:info_titleabbrev: {aws} Secrets Manager - -[abstract] --- -{aws} Secrets Manager helps you manage, access, and rotate credentials, API keys, and other secrets throughout their lifecycle. --- - -link:secrets-manager/[{aws} Secrets Manager,type="marketing"] helps you manage, access, and rotate credentials, API keys, and other secrets throughout their lifecycle. -With Secrets Manager, you can secure and manage secrets used to access resources in {aws}, on third-party services, and on-premises. -For more information, see the link:secretsmanager/latest/userguide/intro.html[{aws} Secrets Manager User Guide,type="documentation"]. - -When using the EKS Capability for Argo CD, Secrets Manager provides a secure way to store and retrieve Git repository credentials without hardcoding sensitive data in your Argo CD configuration and resources. -This integration is particularly useful for managing private repository access tokens and SSH keys used by Argo CD to sync applications from Git repositories. - -[#integration-secrets-manager-use] -== Use {aws} Secrets Manager with Argo CD - -When using the EKS Capability for Argo CD, you can store Git repository credentials in Secrets Manager and configure Argo CD to retrieve them. -This approach is more secure than storing credentials directly in Argo CD configuration or using long-lived personal access tokens. - -*Prerequisites* - -* An Amazon EKS cluster with the Argo CD capability enabled -* Git repository credentials stored in {aws} Secrets Manager -* IAM permissions configured for Argo CD to access Secrets Manager - -*To configure Argo CD to use Secrets Manager for repository credentials* - -. Store your Git credentials in Secrets Manager. For example, to store a GitHub personal access token: -+ -[source,bash] ----- -aws secretsmanager create-secret \ - --name argocd/github-token \ - --secret-string '{"username":"git","password":"ghp_xxxxxxxxxxxx"}' ----- - -. Ensure the Argo CD capability role has permissions to retrieve the secret: -+ -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "secretsmanager:GetSecretValue", - "secretsmanager:DescribeSecret" - ], - "Resource": "arn:aws:secretsmanager:region:account-id:secret:argocd/github-token*" - }, - { - "Effect": "Allow", - "Action": [ - "kms:Decrypt" - ], - "Resource": "arn:aws:kms:region:account-id:key/*", - "Condition": { - "StringLike": { - "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:region:account-id:secret:argocd/*", - "kms:ViaService": "secretsmanager.*.amazonaws.com" - } - } - } - ] -} ----- -+ -[NOTE] -==== -The KMS decrypt permission is required because Secrets Manager encrypts all secrets using {aws} KMS. -The condition restricts decryption to only secrets with the `argocd/` prefix. -If you use the default {aws} managed key for Secrets Manager, this permission is sufficient. -For customer managed KMS keys, update the `Resource` field with your specific key ARN. -==== - -. Configure Argo CD to use the credentials from Secrets Manager. For information about syncing secrets from Secrets Manager into Kubernetes secrets that Argo CD can reference, see link:https://argo-cd.readthedocs.io/en/stable/operator-manual/secret-management/[Secret Management^] in the Argo CD documentation. - -. Create an Argo CD repository configuration that references the secret ARN: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: private-repo - namespace: argocd - labels: - argocd.argoproj.io/secret-type: repository -stringData: - type: git - url: https://github.com/org/repo - secretArn: arn:aws:secretsmanager:region:account-id:secret:argocd/github-token ----- - -For more information about configuring repository access with Argo CD, see <>. diff --git a/latest/ug/manage-access/k8s-access/access-policy-reference.adoc b/latest/ug/manage-access/k8s-access/access-policy-reference.adoc index 1b27ae1b6..70beb8e31 100644 --- a/latest/ug/manage-access/k8s-access/access-policy-reference.adoc +++ b/latest/ug/manage-access/k8s-access/access-policy-reference.adoc @@ -389,7 +389,7 @@ This policy includes the following permissions that allow Amazon EKS components Each component uses a dedicated service account and is restricted to only the permissions required for its specific function. -If you manually specify a Node IAM role in a NodeClass, you need to create an Access Entry that associates the new Node IAM role with this Access Policy. +If you manually specifiy a Node IAM role in a NodeClass, you need to create an Access Entry that associates the new Node IAM role with this Access Policy. == AmazonEKSBlockStoragePolicy @@ -697,227 +697,6 @@ This policy grants the permissions necessary for {aws} Backup to manage and rest |`list`, `get`, `create` |=== -== AmazonEKSACKPolicy - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AmazonEKSACKPolicy` - -This policy grants permissions necessary for the {aws} Controllers for Kubernetes (ACK) capability to manage {aws} resources from Kubernetes. -The policy includes the following permissions: - -ACK Custom Resource Management: - -- Full access to all ACK service custom resources across 50+ {aws} services including S3, RDS, DynamoDB, Lambda, EC2, and more. -- Create, read, update, and delete ACK custom resource definitions. - -Namespace Access: - -- Read access to namespaces for resource organization. - -Leader Election: - -- Create and read coordination leases for leader election. -- Update and delete specific ACK service controller leases. - -Event Management: - -- Create and patch events for ACK operations. - -This policy is designed to support comprehensive {aws} resource management through Kubernetes APIs. -Amazon EKS automatically creates an access entry with this access policy for the capability IAM role that you supply when the ACK capability is created. - -[%header,cols="3"] -|=== -|Kubernetes API groups -|Kubernetes resources -|Kubernetes verbs (permissions) - - -| -|`namespaces` -|`get`, `watch`, `list` - -|`services.k8s.aws`, `acm.services.k8s.aws`, `acmpca.services.k8s.aws`, `apigateway.services.k8s.aws`, `apigatewayv2.services.k8s.aws`, `applicationautoscaling.services.k8s.aws`, `athena.services.k8s.aws`, `bedrock.services.k8s.aws`, `bedrockagent.services.k8s.aws`, `bedrockagentcorecontrol.services.k8s.aws`, `cloudfront.services.k8s.aws`, `cloudtrail.services.k8s.aws`, `cloudwatch.services.k8s.aws`, `cloudwatchlogs.services.k8s.aws`, `codeartifact.services.k8s.aws`, `cognitoidentityprovider.services.k8s.aws`, `documentdb.services.k8s.aws`, `dynamodb.services.k8s.aws`, `ec2.services.k8s.aws`, `ecr.services.k8s.aws`, `ecrpublic.services.k8s.aws`, `ecs.services.k8s.aws`, `efs.services.k8s.aws`, `eks.services.k8s.aws`, `elasticache.services.k8s.aws`, `elbv2.services.k8s.aws`, `emrcontainers.services.k8s.aws`, `eventbridge.services.k8s.aws`, `iam.services.k8s.aws`, `kafka.services.k8s.aws`, `keyspaces.services.k8s.aws`, `kinesis.services.k8s.aws`, `kms.services.k8s.aws`, `lambda.services.k8s.aws`, `memorydb.services.k8s.aws`, `mq.services.k8s.aws`, `networkfirewall.services.k8s.aws`, `opensearchservice.services.k8s.aws`, `organizations.services.k8s.aws`, `pipes.services.k8s.aws`, `prometheusservice.services.k8s.aws`, `ram.services.k8s.aws`, `rds.services.k8s.aws`, `recyclebin.services.k8s.aws`, `route53.services.k8s.aws`, `route53resolver.services.k8s.aws`, `s3.services.k8s.aws`, `s3control.services.k8s.aws`, `sagemaker.services.k8s.aws`, `secretsmanager.services.k8s.aws`, `ses.services.k8s.aws`, `sfn.services.k8s.aws`, `sns.services.k8s.aws`, `sqs.services.k8s.aws`, `ssm.services.k8s.aws`, `wafv2.services.k8s.aws` -|`{asterisk}` -|`{asterisk}` - -|`coordination.k8s.io` -|`leases` -|`create`, `get`, `list`, `watch` - -|`coordination.k8s.io` -|`leases` (specific ACK service controller leases only) -|`delete`, `update`, `patch` - -| -|`events` -|`create`, `patch` - -|`apiextensions.k8s.io` -|`customresourcedefinitions` -|`{asterisk}` - -|=== - -== AmazonEKSArgoCDClusterPolicy - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AmazonEKSArgoCDClusterPolicy` - -This policy grants cluster-level permissions necessary for the Argo CD capability to discover resources and manage cluster-scoped objects. -The policy includes the following permissions: - -Namespace Management: - -- Create, read, update, and delete namespaces for application namespace management. - -Custom Resource Definition Management: - -- Manage Argo CD-specific CRDs (Applications, AppProjects, ApplicationSets). - -API Discovery: - -- Read access to Kubernetes API endpoints for resource discovery. - -This policy is designed to support cluster-level Argo CD operations including namespace management and CRD installation. -Amazon EKS automatically creates an access entry with this access policy for the capability IAM role that you supply when the Argo CD capability is created. - -[%header,cols="4"] -|=== -|Kubernetes API groups -|Kubernetes nonResourceURLs -|Kubernetes resources -|Kubernetes verbs (permissions) - - -| -| -|`namespaces` -|`create`, `get`, `update`, `patch`, `delete` - -|`apiextensions.k8s.io` -| -|`customresourcedefinitions` -|`create` - -|`apiextensions.k8s.io` -| -|`customresourcedefinitions` (Argo CD CRDs only) -|`get`, `update`, `patch`, `delete` - -| -|`/api`, `/api/{asterisk}`, `/apis`, `/apis/{asterisk}` -| -|`get` - -|=== - -== AmazonEKSArgoCDPolicy - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AmazonEKSArgoCDPolicy` - -This policy grants namespace-level permissions necessary for the Argo CD capability to deploy and manage applications. -The policy includes the following permissions: - -Secret Management: - -- Full access to secrets for Git credentials and cluster secrets. - -ConfigMap Access: - -- Read access to ConfigMaps to send warnings if customers try to use unsupported Argo CD ConfigMaps. - -Event Management: - -- Read and create events for application lifecycle tracking. - -Argo CD Resource Management: - -- Full access to Applications, ApplicationSets, and AppProjects. -- Manage finalizers and status for Argo CD resources. - -This policy is designed to support namespace-level Argo CD operations including application deployment and management. -Amazon EKS automatically creates an access entry with this access policy for the capability IAM role that you supply when the Argo CD capability is created, scoped to the Argo CD namespace. - -[%header,cols="3"] -|=== -|Kubernetes API groups -|Kubernetes resources -|Kubernetes verbs (permissions) - - -| -|`secrets` -|`{asterisk}` - -| -|`configmaps` -|`get`, `list`, `watch` - -| -|`events` -|`get`, `list`, `watch`, `patch`, `create` - -|`argoproj.io` -|`applications`, `applications/finalizers`, `applications/status`, `applicationsets`, `applicationsets/finalizers`, `applicationsets/status`, `appprojects`, `appprojects/finalizers`, `appprojects/status` -|`{asterisk}` - -|=== - -== AmazonEKSKROPolicy - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AmazonEKSKROPolicy` - -This policy grants permissions necessary for the kro (Kube Resource Orchestrator) capability to create and manage custom Kubernetes APIs. -The policy includes the following permissions: - -kro Resource Management: - -- Full access to all kro resources including ResourceGraphDefinitions and custom resource instances. - -Custom Resource Definition Management: - -- Create, read, update, and delete CRDs for custom APIs defined by ResourceGraphDefinitions. - -Leader Election: - -- Create and read coordination leases for leader election. -- Update and delete the kro controller lease. - -Event Management: - -- Create and patch events for kro operations. - -This policy is designed to support comprehensive resource composition and custom API management through kro. -Amazon EKS automatically creates an access entry with this access policy for the capability IAM role that you supply when the kro capability is created. - -[%header,cols="3"] -|=== -|Kubernetes API groups -|Kubernetes resources -|Kubernetes verbs (permissions) - - -|`kro.run` -|`{asterisk}` -|`{asterisk}` - -|`apiextensions.k8s.io` -|`customresourcedefinitions` -|`{asterisk}` - -|`coordination.k8s.io` -|`leases` -|`create`, `get`, `list`, `watch` - -|`coordination.k8s.io` -|`leases` (kro controller lease only) -|`delete`, `update`, `patch` - -| -|`events` -|`create`, `patch` - -|=== - [#access-policy-updates] == Access policy updates @@ -929,10 +708,6 @@ View details about updates to access policies, since they were introduced. For a |Description |Date -|Add policies for EKS Capabilities -|Publish `AmazonEKSACKPolicy`, `AmazonEKSArgoCDClusterPolicy`, `AmazonEKSArgoCDPolicy`, and `AmazonEKSKROPolicy` for managing EKS Capabilities -|November 22, 2025 - |Add `AmazonEKSSecretReaderPolicy` |Add a new policy for read-only access to secrets |November 6, 2025 diff --git a/latest/ug/ml/machine-learning-on-eks.adoc b/latest/ug/ml/machine-learning-on-eks.adoc index cabbd5232..1aec2b1c5 100644 --- a/latest/ug/ml/machine-learning-on-eks.adoc +++ b/latest/ug/ml/machine-learning-on-eks.adoc @@ -40,7 +40,7 @@ These workloads benefit from dynamic scaling with https://karpenter.sh/[Karpente https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html[Amazon ECR Pull Through Cache (PTC)] accelerates model updates, and https://aws.amazon.com/bottlerocket/[Bottlerocket] data volumes with https://docs.aws.amazon.com/ebs/latest/userguide/what-is-ebs.html[Amazon EBS]-optimized volumes ensure fast data access. -* **General model training:** Organizations leverage EKS to train complex models on large datasets over extended periods using the https://www.kubeflow.org/docs/components/trainer/[Kubeflow Training Operator], +* **General model training:** Organizations leverage EKS to train complex models on large datasets over extended periods using the https://www.kubeflow.org/docs/components/trainer/[Kubeflow Training Operator (KRO)], https://docs.ray.io/en/latest/serve/index.html[Ray Serve], and https://pytorch.org/docs/stable/distributed.elastic.html[Torch Distributed Elastic] on https://aws.amazon.com/ec2/instance-types/p4/[Amazon EC2 P4d] and https://aws.amazon.com/ec2/instance-types/trn1/[Amazon EC2 Trn1] instances. These workloads are supported by batch scheduling with tools like https://volcano.sh/en/#home_slider[Volcano], https://yunikorn.apache.org/[Yunikorn], diff --git a/latest/ug/ml/ml-compute-management.adoc b/latest/ug/ml/ml-compute-management.adoc index df1c8d7b7..5bdb62f06 100644 --- a/latest/ug/ml/ml-compute-management.adoc +++ b/latest/ug/ml/ml-compute-management.adoc @@ -18,3 +18,5 @@ This section is designed to help you manage compute resources for machine learni include::capacity-blocks-mng.adoc[leveloffset=+1] include::capacity-blocks.adoc[leveloffset=+1] + +include::ml-eks-nvidia-ultraserver.adoc[leveloffset=+1] \ No newline at end of file diff --git a/latest/ug/ml/ml-eks-nvidia-ultraserver.adoc b/latest/ug/ml/ml-eks-nvidia-ultraserver.adoc new file mode 100644 index 000000000..6ce624ce9 --- /dev/null +++ b/latest/ug/ml/ml-eks-nvidia-ultraserver.adoc @@ -0,0 +1,407 @@ +include::../attributes.txt[] + +[.topic] +[#ml-eks-nvidia-ultraserver] += Use P6e-GB200 UltraServers with Amazon EKS +:info_titleabbrev: Use P6e-GB200 with EKS + +[abstract] +-- +Learn how to use the Amazon EC2 P6e-GB200 UltraServers with Amazon EKS, accelerated by NVIDIA GB200 NVL72 +-- + +This topic describes how to configure and use Amazon EKS with P6e-GB200 UltraServers. The `p6e-gb200.36xlarge` instance type with 4 NVIDIA Blackwell GPUs is only available as P6e-GB200 UltraServers. There are two types of P6e-GB200 UltraServers. The `u-p6e-gb200x36` UltraServer has 9 `p6e-gb200.36xlarge` instances and the `u-p6e-gb200x72` UltraServer has 18 `p6e-gb200.36xlarge` instances. + +To learn more, see the https://aws.amazon.com/ec2/instance-types/p6/[Amazon EC2 P6e-GB200 UltraServers webpage]. + +[#nvidia-ultraserver-considerations] +== Considerations + +* Amazon EKS supports P6e-GB200 UltraServers for Kubernetes versions 1.33 and above. This Kubernetes version release provides support for https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/[Dynamic Resource Allocation] (DRA), enabled by default in EKS and in the https://docs.aws.amazon.com/eks/latest/userguide/ml-eks-optimized-ami.html[AL2023 EKS-optimized accelerated AMIs]. DRA is a requirement to use the P6e-GB200 UltraServers with EKS. DRA is not supported in Karpenter or EKS Auto Mode, and it is recommended to use EKS self-managed node groups or EKS managed node groups when using the P6e-GB200 UltraServers with EKS. +* P6e-GB200 UltraServers are made available through https://aws.amazon.com/ec2/capacityblocks/[EC2 Capacity Blocks for ML]. See <> for information on how to launch EKS nodes with Capacity Blocks. +* When using EKS managed node groups with Capacity Blocks, you must use custom launch templates. When upgrading EKS managed node groups with P6e-GB200 UltraServers, you must set the desired size of the node group to `0` before upgrading. +* It is recommended to use the AL2023 ARM NVIDIA variant of the EKS-optimized accelerated AMIs. This AMI includes the required node components and configuration to work with P6e-GB200 UltraServers. If you decide to build your own AMI, you are responsible for installing and validating the compatibility of the node and system software, including drivers. For more information, see <>. +* It is recommend to use EKS-optimized AMI release `v20251103` or later, which includes NVIDIA driver version 580. This NVIDIA driver version enables Coherent Driver-Based Memory Memory (CDMM) to address potential memory over-reporting. When CDMM is enabled, the following capabilities are not supported: NVIDIA Multi-Instance GPU (MIG) and vGPU. For more information on CDMM, see https://nvdam.widen.net/s/gpqp6wmz7s/cuda-whitepaper--cdmm-pdf[NVIDIA Coherent Driver-based Memory Management (CDMM)]. +* When using the https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/overview.html[NVIDIA GPU operator] with the EKS-optimized AL2023 NVIDIA AMI, you must disable the operator installation of the driver and toolkit, as these are already included in the AMI. The EKS-optimized AL2023 NVIDIA AMIs do not include the NVIDIA Kubernetes device plugin or the NVIDIA DRA driver, and these must be installed separately. +* Each `p6e-gb200.36xlarge` instance can be configured with up to 17 network cards and can leverage EFA for communication between UltraServers. Workload network traffic can cross UltraServers, but for highest performance it is recommended to schedule workloads in the same UltraServer leveraging IMEX for intra-UltraServer GPU communication. For more information, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-acc-inst-types.html#efa-for-p6e[EFA configuration for P6e-GB200 instances]. +* Each `p6e-gb200.36xlarge` instance has 3x 7.5TB https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html[instance store storage]. By default, the EKS-optimized AMI does not format and mount the instance stores. The node’s ephemeral storage can be shared among pods that request ephemeral storage and container images that are downloaded to the node. If using the AL2023 EKS-optimized AMI, this can be configured as part of the nodes bootstrap in the user data by setting the instance local storage policy in https://docs.aws.amazon.com/eks/latest/eksctl/node-bootstrapping.html#configuring-the-bootstrapping-process[NodeConfig] to RAID0. Setting to RAID0 stripes the instance stores and configures the container runtime and kubelet to make use of this ephemeral storage. + +[#nvidia-ultraserver-components] +== Components + +The following components are recommended for running workloads on EKS with the P6e-GB200 UltraServers. You can optionally use the https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest/overview.html[NVIDIA GPU operator] to install the NVIDIA node components. When using the NVIDIA GPU operator with the EKS-optimized AL2023 NVIDIA AMI, you must disable the operator installation of the driver and toolkit, as these are already included in the AMI. + +[%header,cols="1,2"] +|=== +|Stack | Component + +.8+| EKS-optimized accelerated AMI +| Kernel 6.12 +| NVIDIA GPU driver +| NVIDIA CUDA user mode driver +| NVIDIA container toolkit +| NVIDIA fabric manager +| NVIDIA IMEX driver +| NVIDIA NVLink Subnet Manager +| EFA driver +.6+| Components running on node +| VPC CNI +| EFA device plugin +| NVIDIA K8s device plugin +| NVIDIA DRA driver +| NVIDIA Node Feature Discovery (NFD) +| NVIDIA GPU Feature Discovery (GFD) +|=== + +The node components in the table above perform the following functions: + +* *VPC CNI*: Allocates VPC IPs as the primary network interface for pods running on EKS +* *EFA device plugin*: Allocates EFA devices as secondary networks for pods running on EKS. Responsible for network traffic across P6e-GB200 UltraServers. For multi-node workloads, for GPU-to-GPU within an UltraServer can flow over multi-node NVLink. +* *NVIDIA Kubernetes device plugin*: Allocates GPUs as devices for pods running on EKS. It is recommended to use the NVIDIA Kubernetes device plugin until the NVIDIA DRA driver GPU allocation functionality graduates from experimental. See the https://github.com/NVIDIA/k8s-dra-driver-gpu/releases[NVIDIA DRA driver releases] for updated information. +* *NVIDIA DRA driver*: Enables ComputeDomain custom resources that facilitate creation of IMEX domains that follow workloads running on P6e-GB200 UltraServers. +** The ComputeDomain resource describes an Internode Memory Exchange (IMEX) domain. When workloads with a ResourceClaim for a ComputeDomain are deployed to the cluster, the NVIDIA DRA driver automatically creates an IMEX DaemonSet that runs on matching nodes and establishes the IMEX channel(s) between the nodes before the workload is started. To learn more about IMEX, see https://docs.nvidia.com/multi-node-nvlink-systems/imex-guide/overview.html[overview of NVIDIA IMEX for multi-node NVLink systems]. +** The NVIDIA DRA driver uses a clique ID label (`nvidia.com/gpu.clique`) applied by NVIDIA GFD that relays the knowledge of the network topology and NVLink domain. +** It is a best practice to create a ComputeDomain per workload job. +* *NVIDIA Node Feature Discovery (NFD)*: Required dependency for GFD to apply node labels based on discovered node-level attributes. +* *NVIDIA GPU Feature Discovery (GFD)*: Applies an NVIDIA standard topology label called `nvidia.com/gpu.clique` to the nodes. Nodes within the same `nvidia.com/gpu.clique` have multi-node NVLink-reachability, and you can use pod affinities in your application to schedule pods to the same NVlink domain. + +[#nvidia-ultraserver-procedure] +== Procedure + +The following section assumes you have an EKS cluster running Kubernetes version 1.33 or above with one or more node groups with P6e-GB200 UltraServers running the AL2023 ARM NVIDIA EKS-optimized accelerated AMI. See the links in <> for the prerequisite steps for EKS self-managed nodes and managed node groups. + +The following procedure uses the components below. + +[%header,cols="2,1,4"] +|=== +| Name | Version |Description + +| NVIDIA GPU Operator +| 25.3.4+ +| For lifecycle management of required plugins such as NVIDIA Kubernetes device plugin and NFD/GFD. + +| NVIDIA DRA Drivers +| 25.8.0+ +| For ComputeDomain CRDs and IMEX domain management. + +| EFA Device Plugin +| 0.5.14+ +| For cross-UltraServer communication. + +|=== + +[#nvidia-ultraserver-gpu-operator] +== Install NVIDIA GPU operator + +The NVIDIA GPU operator simplifies the management of components required to use GPUs in Kubernetes clusters. As the NVIDIA GPU driver and container toolkit are installed as part of the EKS-optimized accelerated AMI, these must be set to `false` in the Helm values configuration. + +. Create a Helm values file named `gpu-operator-values.yaml` with the following configuration. ++ +[source,yaml,subs="verbatim,attributes"] +---- +devicePlugin: + enabled: true +nfd: + enabled: true +gfd: + enabled: true +driver: + enabled: false +toolkit: + enabled: false +migManager: + enabled: false +---- ++ +. Install the NVIDIA GPU operator for your cluster using the `gpu-operator-values.yaml` file you created in the previous step. ++ +[source,bash] +---- +helm repo add nvidia https://helm.ngc.nvidia.com/nvidia +helm repo update +---- ++ +[source,bash] +---- +helm install gpu-operator nvidia/gpu-operator \ + --namespace gpu-operator \ + --create-namespace \ + --version v25.3.4 \ + --values gpu-operator-values.yaml +---- + +[#nvidia-ultraserver-dra-driver] +== Install NVIDIA DRA driver + +As of NVIDIA GPU operator version `v25.3.4`, the NVIDIA DRA driver must be installed separately. It is recommended to track the NVIDIA GPU operator https://github.com/NVIDIA/gpu-operator/releases[release notes] as this may change in a future release. + +. Create a Helm values file named `dra-values.yaml` with the following configuration. Note the `nodeAffinity` and `tolerations` that configures the DRA driver to deploy only on nodes with an NVIDIA GPU. ++ +[source,yaml,subs="verbatim,attributes"] +---- +resources: + gpus: + enabled: false # set to false to disable experimental gpu support + computeDomains: + enabled: true + +controller: + nodeSelector: null + affinity: null + tolerations: [] + +kubeletPlugin: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: "nvidia.com/gpu.present" + operator: In + values: + - "true" + tolerations: + - key: "nvidia.com/gpu" + operator: Exists + effect: NoSchedule +---- ++ +. Install the NVIDIA DRA driver for your cluster using the `dra-values.yaml` file you created in the previous step. ++ +[source,bash] +---- +helm repo add nvidia https://helm.ngc.nvidia.com/nvidia +helm repo update +---- ++ +[source,bash] +---- +helm install nvidia-dra-driver-gpu nvidia/nvidia-dra-driver-gpu \ + --version="25.8.0" \ + --namespace nvidia-dra-driver-gpu \ + --create-namespace \ + -f dra-values.yaml +---- ++ +. After installation, the DRA driver creates `DeviceClass` resources that enable Kubernetes to understand and allocate `ComputeDomain` resources, making the IMEX management possible for distributed GPU workloads on P6e-GB200 UltraServers. ++ +Confirm the DRA resources are available with the following commands. ++ +[source,bash] +---- +kubectl api-resources | grep resource.k8s.io +---- ++ +[source,bash] +---- +deviceclasses resource.k8s.io/v1 false DeviceClass +resourceclaims resource.k8s.io/v1 true ResourceClaim +resourceclaimtemplates resource.k8s.io/v1 true ResourceClaimTemplate +resourceslices resource.k8s.io/v1 false ResourceSlice +---- ++ +[source,bash] +---- +kubectl get deviceclasses +---- ++ +[source,bash] +---- +NAME +compute-domain-daemon.nvidia.com +compute-domain-default-channel.nvidia.com +---- + +[#nvidia-ultraserver-efa-plugin] +== Install the EFA device plugin + +To use EFA communication between UltraServers, you must install the Kubernetes device plugin for EFA. P6e-GB200 instances can be configured with up to https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-acc-inst-types.html#efa-for-p6e[17 network cards] and the primary NCI (index 0) must be of type `interface` and supports up to 100 Gbps of ENA bandwidth. Configure your EFA and ENA interfaces as per your requirements during node provisioning. Review the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-acc-inst-types.html#efa-for-p6e[EFA configuration for a P6e-GB200 instances {aws} documentation] for more details on EFA configuration. + +. Create a Helm values file named `efa-values.yaml` with the following configuration. ++ +[source,yaml,subs="verbatim,attributes"] +---- +tolerations: + - key: nvidia.com/gpu + operator: Exists + effect: NoSchedule +---- ++ +. Install the NVIDIA DRA operator for your cluster using the `dra-values.yaml` file you created in the previous step. ++ +[source,bash] +---- +helm repo add eks https://aws.github.io/eks-charts +helm repo update +---- ++ +[source,bash] +---- +helm install efa eks/aws-efa-k8s-device-plugin -n kube-system \ + --version="0.5.14" \ + -f efa-values.yaml +---- ++ +As an example, if you configured your instances with 1 efa-only interface in each https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-acc-inst-types.html#efa-for-p6e[NCI group], when describing a node, it is expected to see 4 allocatable EFA devices per node. ++ +[source,bash] +---- +kubectl describe node/ +---- ++ +[source,yaml,subs="verbatim,attributes"] +---- +Capacity: + ... + vpc.amazonaws.com/efa: 4 +Allocatable: + ... + vpc.amazonaws.com/efa: 4 +---- + +[#nvidia-ultraserver-imex-nvlink] +== Validate IMEX over Multi-Node NVLink + +For a multi-node NVLINK NCCL test and other micro-benchmarks review the https://github.com/aws-samples/awsome-distributed-training/tree/main/micro-benchmarks/nccl-tests[awesome-distributed-training] GitHub repository. The following steps show how to run a multi-node NVLink test with nvbandwidth. + +. To run a multi-node bandwidth test across two nodes in the NVL72 domain, first install the MPI operator: ++ +[source,bash] +---- +kubectl create -f https://github.com/kubeflow/mpi-operator/releases/download/v0.7.0/mpi-operator.yaml +---- ++ +. Create a Helm values file named `nvbandwidth-test-job.yaml` that defines the test manifest. Note the `nvidia.com/gpu.clique` pod affinity to schedule the workers in the same NVLink domain which has Multi-Node NVLink reachability. ++ +As of NVIDIA DRA Driver version `v25.8.0` ComputeDomains are elastic and `.spec.numNodes` can be set to `0` in the ComputeDomain definition. Review the latest https://github.com/NVIDIA/k8s-dra-driver-gpu[NVIDIA DRA Driver release notes] for updates. ++ +[source,yaml,subs="verbatim,attributes"] +---- +--- +apiVersion: resource.nvidia.com/v1beta1 +kind: ComputeDomain +metadata: + name: nvbandwidth-test-compute-domain +spec: + numNodes: 0 # This can be set to 0 from NVIDIA DRA Driver version v25.8.0+ + channel: + resourceClaimTemplate: + name: nvbandwidth-test-compute-domain-channel + +--- +apiVersion: kubeflow.org/v2beta1 +kind: MPIJob +metadata: + name: nvbandwidth-test +spec: + slotsPerWorker: 4 # 4 GPUs per worker node + launcherCreationPolicy: WaitForWorkersReady + runPolicy: + cleanPodPolicy: Running + sshAuthMountPath: /home/mpiuser/.ssh + mpiReplicaSpecs: + Launcher: + replicas: 1 + template: + metadata: + labels: + nvbandwidth-test-replica: mpi-launcher + spec: + containers: + - image: ghcr.io/nvidia/k8s-samples:nvbandwidth-v0.7-8d103163 + name: mpi-launcher + securityContext: + runAsUser: 1000 + command: + - mpirun + args: + - --bind-to + - core + - --map-by + - ppr:4:node + - -np + - "8" + - --report-bindings + - -q + - nvbandwidth + - -t + - multinode_device_to_device_memcpy_read_ce + Worker: + replicas: 2 # 2 worker nodes + template: + metadata: + labels: + nvbandwidth-test-replica: mpi-worker + spec: + affinity: + podAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: nvbandwidth-test-replica + operator: In + values: + - mpi-worker + topologyKey: nvidia.com/gpu.clique + containers: + - image: ghcr.io/nvidia/k8s-samples:nvbandwidth-v0.7-8d103163 + name: mpi-worker + securityContext: + runAsUser: 1000 + env: + command: + - /usr/sbin/sshd + args: + - -De + - -f + - /home/mpiuser/.sshd_config + resources: + limits: + nvidia.com/gpu: 4 # Request 4 GPUs per worker + claims: + - name: compute-domain-channel # Link to IMEX channel + resourceClaims: + - name: compute-domain-channel + resourceClaimTemplateName: nvbandwidth-test-compute-domain-channel +---- ++ +. Create the ComputeDomain and start the job with the following command. ++ +[source,bash] +---- +kubectl apply -f nvbandwidth-test-job.yaml +---- ++ +. ComputeDomain creation, you can see the workload's ComputeDomain has two nodes: ++ +[source,bash] +---- +kubectl get computedomains.resource.nvidia.com -o yaml +---- ++ +[source,bash] +---- +status: + nodes: + - cliqueID: . + ipAddress: + name: + - cliqueID: . + ipAddress: + name: + status: Ready +---- ++ +. Review the results of the job with the following command. ++ +[source,bash] +---- +kubectl logs --tail=-1 -l job-name=nvbandwidth-test-launcher +---- ++ +. When the test is complete, delete it with the following command. ++ +[source,bash] +---- +kubectl delete -f nvbandwidth-test-job.yaml +---- \ No newline at end of file diff --git a/latest/ug/ml/ml-eks-optimized-ami.adoc b/latest/ug/ml/ml-eks-optimized-ami.adoc index b1513dcc5..5f0060883 100644 --- a/latest/ug/ml/ml-eks-optimized-ami.adoc +++ b/latest/ug/ml/ml-eks-optimized-ami.adoc @@ -14,7 +14,7 @@ The table below shows the supported GPU instance types for each EKS-optimized ac |EKS AMI variant | EC2 instance types |AL2023 x86_64 NVIDIA -|p6-b300, p6-b200, p5, p5e, p5en, p4d, p4de, p3, p3dn, gr6, g6, g6e, g6f, gr6f, g5, g4dn +|p6-b200, p5, p5e, p5en, p4d, p4de, p3, p3dn, gr6, g6, g6e, g6f, gr6f, g5, g4dn |AL2023 ARM NVIDIA |p6e-gb200, g5g @@ -23,7 +23,7 @@ The table below shows the supported GPU instance types for each EKS-optimized ac |inf1, inf2, trn1, trn2 |Bottlerocket x86_64 aws-k8s-nvidia -|p6-b300, p6-b200, p5, p5e, p5en, p4d, p4de, p3, p3dn, gr6, g6, g6e, g6f, gr6f, g5, g4dn +|p6-b200, p5, p5e, p5en, p4d, p4de, p3, p3dn, gr6, g6, g6e, g6f, gr6f, g5, g4dn |Bottlerocket aarch64/arm64 aws-k8s-nvidia |g5g @@ -59,9 +59,9 @@ In addition to the standard EKS AMI components, the EKS-optimized AL2023 NVIDIA For details on the NVIDIA CUDA user mode driver and the CUDA runtime/libraries used within application containers, see the https://docs.nvidia.com/deploy/cuda-compatibility/why-cuda-compatibility.html#why-cuda-compatibility[NVIDIA documentation]. The CUDA version shown from `nvidia-smi` is the version of the NVIDIA CUDA user mode driver installed on the host, which must be compatible with the CUDA runtime/libraries used in application containers. -The EKS-optimized AL2023 NVIDIA AMIs support kernel 6.12 for Kubernetes versions 1.33 and above, and the NVIDIA driver 580 version for all Kubernetes versions. The NVIDIA 580 driver is required to use CUDA 13+. +To track the status of the EKS-optimized NVIDIA AMIs upgrade to NVIDIA driver 580 version, see https://github.com/awslabs/amazon-eks-ami/issues/2470[GitHub issue #2470]. The NVIDIA 580 driver is required to use CUDA 13+. -See the EKS-optimized https://github.com/awslabs/amazon-eks-ami/releases[AL2023 releases] on GitHub for details of the component versions included in the AMIs. See the EKS AL2023 NVIDIA AMI https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/provisioners/install-nvidia-driver.sh[installation script] and https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/runtime/gpu/nvidia-kmod-load.sh[kernel loading script] for details on how the EKS AMIs configure the NVIDIA dependencies. You can find the list of installed packages and their versions on a running EC2 instance with the `dnf list installed` command. +See the EKS AL2023 NVIDIA AMI https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/provisioners/install-nvidia-driver.sh[installation script] and https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2023/runtime/gpu/nvidia-kmod-load.sh[kernel loading script] for details on how the EKS AMIs configure the NVIDIA dependencies. See the EKS-optimized https://github.com/awslabs/amazon-eks-ami/releases[AL2023 releases] on GitHub to see the component versions included in the AMIs. You can find the list of installed packages and their versions on a running EC2 instance with the `dnf list installed` command. When building custom AMIs with the EKS-optimized AMIs as the base, it is not recommended or supported to run an operating system upgrade (ie. `dnf upgrade`) or upgrade any of the Kubernetes or GPU packages that are included in the EKS-optimized AMIs, as this risks breaking component compatibility. If you do upgrade the operating system or packages that are included in the EKS-optimized AMIs, it is recommended to thoroughly test in a development or staging environment before deploying to production. @@ -86,7 +86,7 @@ In addition to the standard EKS AMI components, the EKS-optimized Bottlerocket N For details on the NVIDIA CUDA user mode driver and the CUDA runtime/libraries used within application containers, see the https://docs.nvidia.com/deploy/cuda-compatibility/why-cuda-compatibility.html#why-cuda-compatibility[NVIDIA documentation]. The CUDA version shown from `nvidia-smi` is the version of the NVIDIA CUDA user mode driver installed on the host, which must be compatible with the CUDA runtime/libraries used in application containers. -See the Bottlerocket Version Information in the https://bottlerocket.dev/en/[Bottlerocket documentation] for details on the installed packages and their versions. The EKS-optimized Bottlerocket NVIDIA AMIs support kernel 6.12 for Kubernetes versions 1.33 and above, and the NVIDIA driver 580 version for Kubernetes versions 1.34 and above. The NVIDIA 580 driver is required to use CUDA 13+. +See the Bottlerocket Version Information in the https://bottlerocket.dev/en/[Bottlerocket documentation] for details on the installed packages and their versions. The EKS-optimized Bottlerocket NVIDIA AMIs support kernel 6.12 and NVIDIA driver 580 version for Kubernetes versions 1.33 and above. The NVIDIA 580 driver is required to use CUDA 13+. [#eks-amis-neuron] == EKS-optimized Neuron AMIs diff --git a/latest/ug/ml/ml-realtime-inference-llm-inference-vllm.adoc b/latest/ug/ml/ml-realtime-inference-llm-inference-vllm.adoc index a58846940..1055cb450 100644 --- a/latest/ug/ml/ml-realtime-inference-llm-inference-vllm.adoc +++ b/latest/ug/ml/ml-realtime-inference-llm-inference-vllm.adoc @@ -163,9 +163,30 @@ Create an IAM policy to allow the S3 mount point to read from your S3 bucket: [source,bash] ---- +cat < s3-policy.json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:GetObjectVersion", + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": [ + "arn:aws:s3:::${BUCKET_NAME}", + "arn:aws:s3:::${BUCKET_NAME}/*" + ] + } + ] +} +EOF + aws iam create-policy \ --policy-name S3BucketAccess-${BUCKET_NAME} \ - --policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"s3:GetObject\", \"s3:GetObjectVersion\", \"s3:ListBucket\", \"s3:GetBucketLocation\"], \"Resource\": [\"arn:aws:s3:::${BUCKET_NAME}\", \"arn:aws:s3:::${BUCKET_NAME}/*\"]}]}" + --policy-document file://s3-policy.json ---- Find the IAM role name used by the S3 Mountpoint CSI Driver by checking S3 CSI Driver service account annotations: diff --git a/latest/ug/networking/cni-increase-ip-addresses-procedure.adoc b/latest/ug/networking/cni-increase-ip-addresses-procedure.adoc index 6922f5b90..f7edf81bd 100644 --- a/latest/ug/networking/cni-increase-ip-addresses-procedure.adoc +++ b/latest/ug/networking/cni-increase-ip-addresses-procedure.adoc @@ -78,25 +78,13 @@ kubectl set env ds aws-node -n kube-system WARM_IP_TARGET=5 ---- kubectl set env ds aws-node -n kube-system MINIMUM_IP_TARGET=2 ---- -. Create one of the following types of node groups with at least one Amazon EC2 Nitro Amazon Linux 2023 instance type. For a list of Nitro instance types, see link:AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances[Instances built on the Nitro System,type="documentation"] in the Amazon EC2 User Guide. This capability is not supported on Windows. For the options that include [.replaceable]`110`, replace it with either the value from step 3 (recommended), or your own value. +. Create one of the following types of node groups with at least one Amazon EC2 Nitro Amazon Linux 2 instance type. For a list of Nitro instance types, see link:AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances[Instances built on the Nitro System,type="documentation"] in the Amazon EC2 User Guide. This capability is not supported on Windows. For the options that include [.replaceable]`110`, replace it with either the value from step 3 (recommended), or your own value. + -*** *Self-managed* – Deploy the node group using the instructions in <>. Before creating the CloudFormation stack, open the template file and adjust the `UserData` in the `NodeLaunchTemplate` to be like the following +*** *Self-managed* – Deploy the node group using the instructions in <>. Specify the following text for the *BootstrapArguments* parameter. + [source,bash,subs="verbatim,attributes"] ---- -... - apiVersion: node.eks.aws/v1alpha1 - kind: NodeConfig - spec: - cluster: - name: ${ClusterName} - apiServerEndpoint: ${ApiServerEndpoint} - certificateAuthority: ${CertificateAuthorityData} - cidr: ${ServiceCidr} - kubelet: - config: - maxPods: 110 -... +--use-max-pods false --kubelet-extra-args '--max-pods=110' ---- + If you're using `eksctl` to create the node group, you can use the following command. @@ -108,29 +96,13 @@ eksctl create nodegroup --cluster my-cluster --managed=false --max-pods-per-node *** *Managed* – Deploy your node group using one of the following options: + **** *Without a launch template or with a launch template without an AMI ID specified* – Complete the procedure in <>. Managed node groups automatically calculates the Amazon EKS recommended `max-pods` value for you. -**** *With a launch template with a specified AMI ID* – In your launch template, specify an Amazon EKS optimized AMI ID, or a custom AMI built off the Amazon EKS optimized AMI, then <> and provide the following user data in the launch template. This user data passes a `NodeConfig` object to be read by the `nodeadm` tool on the node. For more information about `nodeadm`, see https://awslabs.github.io/amazon-eks-ami/nodeadm[the nodeadm documentation]. +**** *With a launch template with a specified AMI ID* – In your launch template, specify an Amazon EKS optimized AMI ID, or a custom AMI built off the Amazon EKS optimized AMI, then <> and provide the following user data in the launch template. This user data passes arguments into the `bootstrap.sh` file. For more information about the bootstrap file, see https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap.sh] on GitHub. + [source,bash,subs="verbatim,attributes"] ---- -MIME-Version: 1.0 -Content-Type: multipart/mixed; boundary="//" - ---// -Content-Type: application/node.eks.aws - ---- -apiVersion: node.eks.aws/v1alpha1 -kind: NodeConfig -spec: - cluster: - apiServerEndpoint: [.replaceable]`my-cluster` - certificateAuthority: [.replaceable]`LS0t...` - cidr: [.replaceable]`10.100.0.0/16` - name: [.replaceable]`my-cluster - kubelet: - config: - maxPods: [.replaceable]`110` ---//-- +/etc/eks/bootstrap.sh my-cluster \ + --use-max-pods false \ + --kubelet-extra-args '--max-pods=110' ---- + If you're using `eksctl` to create the node group, you can use the following command. diff --git a/latest/ug/networking/cni-ipv6.adoc b/latest/ug/networking/cni-ipv6.adoc index a002af826..629619c11 100644 --- a/latest/ug/networking/cni-ipv6.adoc +++ b/latest/ug/networking/cni-ipv6.adoc @@ -55,5 +55,18 @@ The following are considerations for using the feature: * *Set up load balancer*: Use version `2.3.1` or later of the {aws} Load Balancer Controller to load balance HTTP applications using the <> or network traffic using the <> to `IPv6` Pods with either load balancer in IP mode, but not instance mode. For more information, see <>. * *Add `IPv6` IAM policy*: You must attach an `IPv6` IAM policy to your node IAM or CNI IAM role. Between the two, we recommend that you attach it to a CNI IAM role. For more information, see <> and <>. * *Evaluate all components*: Perform a thorough evaluation of your applications, Amazon EKS add-ons, and {aws} services that you integrate with before deploying `IPv6` clusters. This is to ensure that everything works as expected with `IPv6`. +* *Add `BootstrapArguments` self-managed node groups*: When creating a self-managed node group in a cluster that uses the `IPv6` family, user-data must include the following `BootstrapArguments` for the https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap.sh] file that runs at node start up. Replace [.replaceable]`your-cidr` with the `IPv6` CIDR range of your cluster's VPC. ++ +[source,bash,subs="verbatim,attributes"] +---- +--ip-family ipv6 --service-ipv6-cidr your-cidr +---- ++ +If you don't know the `IPv6` `CIDR` range for your cluster, you can see it with the following command (requires the {aws} CLI version `2.4.9` or later). ++ +[source,bash,subs="verbatim,attributes"] +---- +aws eks describe-cluster --name my-cluster --query cluster.kubernetesNetworkConfig.serviceIpv6Cidr --output text +---- include::deploy-ipv6-cluster.adoc[leveloffset=+1] diff --git a/latest/ug/networking/cni-network-policy-configure.adoc b/latest/ug/networking/cni-network-policy-configure.adoc index ed6dcc913..470e40ae5 100644 --- a/latest/ug/networking/cni-network-policy-configure.adoc +++ b/latest/ug/networking/cni-network-policy-configure.adoc @@ -51,14 +51,14 @@ aws eks describe-cluster --name my-cluster --query cluster.version --output text [#cni-network-policy-minimum-vpc] === Minimum VPC CNI version -To create both standard Kubernetes network policies and admin network policies, you need to run version `1.21` of the VPC CNI plugin. You can see which version that you currently have with the following command. +Version `1.14` or later of the Amazon VPC CNI plugin for Kubernetes on your cluster. You can see which version that you currently have with the following command. [source,shell,subs="verbatim,attributes"] ---- kubectl describe daemonset aws-node --namespace kube-system | grep amazon-k8s-cni: | cut -d : -f 3 ---- -If your version is earlier than `1.21`, see <> to upgrade to version `1.21` or later. +If your version is earlier than `1.14`, see <> to upgrade to version `1.14` or later. [#cni-network-policy-minimum-linux] === Minimum Linux kernel version @@ -86,7 +86,7 @@ env: [#enable-network-policy-parameter] == Step 2: Enable the network policy parameter for the add-on -The network policy feature uses port `8162` on the node for metrics by default. Also, the feature uses port `8163` for health probes. If you run another application on the nodes or inside pods that needs to use these ports, the app fails to run. From VPC CNI version `v1.14.1` or later, you can change these ports. +The network policy feature uses port `8162` on the node for metrics by default. Also, the feature used port `8163` for health probes. If you run another application on the nodes or inside pods that needs to use these ports, the app fails to run. In VPC CNI version `v1.14.1` or later, you can change these ports. Use the following procedure to enable the network policy parameter for the add-on. @@ -274,6 +274,6 @@ There are 2 containers in the `aws-node` pods in versions `1.14` and later. In p You can now deploy Kubernetes network policies to your cluster. -To implement Kubernetes network policies, you can create Kubernetes `NetworkPolicy` or `ClusterNetworkPolicy` objects and deploy them to your cluster. `NetworkPolicy` objects are scoped to a namespace, while `ClusterNetworkPolicy` objects can be scoped to the whole cluster or multiple namespaces. You implement policies to allow or deny traffic between Pods based on label selectors, namespaces, and IP address ranges. For more information about creating `NetworkPolicy` objects, see https://kubernetes.io/docs/concepts/services-networking/network-policies/#networkpolicy-resource[Network Policies] in the Kubernetes documentation. +To implement Kubernetes network policies you create Kubernetes `NetworkPolicy` objects and deploy them to your cluster. `NetworkPolicy` objects are scoped to a namespace. You implement policies to allow or deny traffic between Pods based on label selectors, namespaces, and IP address ranges. For more information about creating `NetworkPolicy` objects, see https://kubernetes.io/docs/concepts/services-networking/network-policies/#networkpolicy-resource[Network Policies] in the Kubernetes documentation. Enforcement of Kubernetes `NetworkPolicy` objects is implemented using the Extended Berkeley Packet Filter (eBPF). Relative to `iptables` based implementations, it offers lower latency and performance characteristics, including reduced CPU utilization and avoiding sequential lookups. Additionally, eBPF probes provide access to context rich data that helps debug complex kernel level issues and improve observability. Amazon EKS supports an eBPF-based exporter that leverages the probes to log policy results on each node and export the data to external log collectors to aid in debugging. For more information, see the https://ebpf.io/what-is-ebpf/#what-is-ebpf[eBPF documentation]. diff --git a/latest/ug/networking/cni-network-policy.adoc b/latest/ug/networking/cni-network-policy.adoc index fe011a472..a0abee69e 100644 --- a/latest/ug/networking/cni-network-policy.adoc +++ b/latest/ug/networking/cni-network-policy.adoc @@ -10,113 +10,18 @@ include::../attributes.txt[] Learn how to configure your Amazon EKS cluster to use Kubernetes network policies with the Amazon VPC CNI plugin. Control network traffic to and from pods using network policies for enhanced security. Covers network policy considerations, requirements, setup instructions, and troubleshooting tips. -- -== Overview - -By default, there are no restrictions in Kubernetes for IP addresses, ports, or connections between any Pods in your cluster or between your Pods and resources in any other network. You can use Kubernetes _network policy_ to restrict network traffic to and from your Pods. For more information, see https://kubernetes.io/docs/concepts/services-networking/network-policies/[Network Policies] in the Kubernetes documentation. - -== Standard network policy - -You can use the standard `NetworkPolicy` to segment pod-to-pod traffic in the cluster. These network policies operate at layers 3 and 4 of the OSI network model, allowing you to control traffic flow at the IP address or port level within your Amazon EKS cluster. Standard network policies are scoped to the namespace level. - -==== Use cases - -* Segment network traffic between workloads to ensure that only related applications can talk to each other. -* Isolate tenants at the namespace level using policies to enforce network separation. - -==== Example - -In the policy below, egress traffic from the _webapp_ pods in the _sun_ namespace is restricted. - -[source,yaml] ----- -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: webapp-egress-policy - namespace: sun -spec: - podSelector: - matchLabels: - role: webapp - policyTypes: - - Egress - egress: - - to: - - namespaceSelector: - matchLabels: - name: moon - podSelector: - matchLabels: - role: frontend - ports: - - protocol: TCP - port: 8080 - - to: - - namespaceSelector: - matchLabels: - name: stars - podSelector: - matchLabels: - role: frontend - ports: - - protocol: TCP - port: 8080 ----- - -The policy applies to pods with the label `role: webapp` in the `sun` namespace. - -* Allowed traffic: Pods with the label `role: frontend` in the `moon` namespace on TCP port `8080` -* Allowed traffic: Pods with the label role: frontend in the `stars` namespace on TCP port `8080` -* Blocked traffic: All other outbound traffic from `webapp` pods is implicitly denied - -== Admin (or cluster) network policy - -image::images/evaluation-order.png[llustration of the evaluation order for network policies in EKS] - -You can use the `ClusterNetworkPolicy` to enforce a network security standard that applies to the whole cluster. Instead of repetitively defining and maintaining a distinct policy for each namespace, you can use a single policy to centrally manage network access controls for different workloads in the cluster, irrespective of their namespace. - -==== Use cases - -* Centrally manage network access controls for all (or a subset of) workloads in your EKS cluster. - -* Define a default network security posture across the cluster. - -* Extend organizational security standards to the scope of the cluster in a more operationally efficient way. - -==== Example - -In the policy below, you can explicitly block cluster traffic from other namespaces to prevent network access to a sensitive workload namespace. - -[source,yaml] ----- -apiVersion: networking.k8s.aws/v1alpha1 -kind: ClusterNetworkPolicy -metadata: - name: protect-sensitive-workload -spec: - tier: Admin - priority: 10 - subject: - namespaces: - matchLabels: - kubernetes.io/metadata.name: earth - ingress: - - action: Deny - from: - - namespaces: - matchLabels: {} # Match all namespaces. - name: select-all-deny-all ----- - -== Important notes - -Network policies in the Amazon VPC CNI plugin for Kubernetes are supported in the configurations listed below. - -* Version 1.21.0 (or later) of Amazon VPC CNI plugin for both standard and admin network policies. +By default, there are no restrictions in Kubernetes for IP addresses, ports, or connections between any Pods in your cluster or between your Pods and resources in any other network. You can use Kubernetes _network policy_ to restrict network traffic to and from your Pods. For more information, see https://kubernetes.io/docs/concepts/services-networking/network-policies/[Network Policies] in the Kubernetes documentation. + +If you have version `1.13` or earlier of the Amazon VPC CNI plugin for Kubernetes on your cluster, you need to implement a third party solution to apply Kubernetes network policies to your cluster. Version `1.14` or later of the plugin can implement network policies, so you don't need to use a third party solution. In this topic, you learn how to configure your cluster to use Kubernetes network policy on your cluster without using a third party add-on. + +Network policies in the Amazon VPC CNI plugin for Kubernetes are supported in the following configurations. + +* Version 1.14 or later of the Amazon VPC CNI plugin for Kubernetes on your cluster. * Cluster configured for `IPv4` or `IPv6` addresses. * You can use network policies with <>. With network policies, you can control all in-cluster communication. With security groups for Pods, you can control access to {aws} services from applications within a Pod. * You can use network policies with _custom networking_ and _prefix delegation_. + [#cni-network-policy-considerations] == Considerations @@ -132,16 +37,6 @@ Network policies in the Amazon VPC CNI plugin for Kubernetes are supported in th * The maximum number of combinations of ports and protocols for a single IP address range (CIDR) is 24 across all of your network policies. Selectors such as `namespaceSelector` resolve to one or more CIDRs. If multiple selectors resolve to a single CIDR or you specify the same direct CIDR multiple times in the same or different network policies, these all count toward this limit. * For any of your Kubernetes services, the service port must be the same as the container port. If you're using named ports, use the same name in the service spec too. -*Admin Network Policies* - -. *Admin tier policies (evaluated first)*: All Admin tier ClusterNetworkPolicies are evaluated before any other policies. Within the Admin tier, policies are processed in priority order (lowest priority number first). The action type determines what happens next. - * *Deny action (highest precedence)*: When an Admin policy with a Deny action matches traffic, that traffic is immediately blocked regardless of any other policies. No further ClusterNetworkPolicy or NetworkPolicy rules are processed. This ensures that organization-wide security controls cannot be overridden by namespace-level policies. - * *Allow action*: After Deny rules are evaluated, Admin policies with Allow actions are processed in priority order (lowest priority number first). When an Allow action matches, the traffic is accepted and no further policy evaluation occurs. These policies can grant access across multiple namespaces based on label selectors, providing centralized control over which workloads can access specific resources. - * *Pass action*: Pass actions in Admin tier policies delegate decision-making to lower tiers. When traffic matches a Pass rule, evaluation skips all remaining Admin tier rules for that traffic and proceeds directly to the NetworkPolicy tier. This allows administrators to explicitly delegate control for certain traffic patterns to application teams. For example, you might use Pass rules to delegate intra-namespace traffic management to namespace administrators while maintaining strict controls over external access. -. *Network policy tier*: If no Admin tier policy matches with Deny or Allow, or if a Pass action was matched, namespace-scoped NetworkPolicy resources are evaluated next. These policies provide fine-grained control within individual namespaces and are managed by application teams. Namespace-scoped policies can only be more restrictive than Admin policies. They cannot override an Admin policy's Deny decision, but they can further restrict traffic that was allowed or passed by Admin policies. -. *Baseline tier Admin policies*: If no Admin or namespace-scoped policies match the traffic, Baseline tier ClusterNetworkPolicies are evaluated. These provide default security postures that can be overridden by namespace-scoped policies, allowing administrators to set organization-wide defaults while giving teams flexibility to customize as needed. Baseline policies are evaluated in priority order (lowest priority number first). -. *Default deny (if no policies match)*: This deny-by-default behavior ensures that only explicitly permitted connections are allowed, maintaining a strong security posture. - *Migration* * If your cluster is currently using a third party solution to manage Kubernetes network policies, you can use those same policies with the Amazon VPC CNI plugin for Kubernetes. However you must remove your existing solution so that it isn't managing the same policies. diff --git a/latest/ug/nodes/al2023.adoc b/latest/ug/nodes/al2023.adoc index 1509e51e3..110382ccd 100644 --- a/latest/ug/nodes/al2023.adoc +++ b/latest/ug/nodes/al2023.adoc @@ -10,12 +10,7 @@ include::../attributes.txt[] AL2023 is a new Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. -- -[WARNING] -==== -Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher. -==== - -AL2023 is a Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. It's the next generation of Amazon Linux from Amazon Web Services and is available across all supported Amazon EKS versions. +The Amazon EKS optimized AMIs are available in two families based on AL2 and AL2023. AL2023 is a new Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. It's the next generation of Amazon Linux from Amazon Web Services and is available across all supported Amazon EKS versions. AL2023 offers several improvements over AL2. For a full comparison, see link:linux/al2023/ug/compare-with-al2.html[Comparing AL2 and Amazon Linux 2023,type="documentation"] in the _Amazon Linux 2023 User Guide_. Several packages have been added, upgraded, and removed from AL2. It's highly recommended to test your applications with AL2023 before upgrading. For a list of all package changes in AL2023, see link:linux/al2023/release-notes/compare-packages.html[Package changes in Amazon Linux 2023,type="documentation"] in the _Amazon Linux 2023 Release Notes_. diff --git a/latest/ug/nodes/eks-ami-build-scripts.adoc b/latest/ug/nodes/eks-ami-build-scripts.adoc index 428526e2d..daa908bed 100644 --- a/latest/ug/nodes/eks-ami-build-scripts.adoc +++ b/latest/ug/nodes/eks-ami-build-scripts.adoc @@ -11,12 +11,12 @@ include::../attributes.txt[] Amazon Elastic Kubernetes Service (Amazon EKS) has open-source scripts that are used to build the Amazon EKS optimized AMI. -- -[WARNING] +[IMPORTANT] ==== -Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher. +Amazon EKS will no longer publish EKS-optimized Amazon Linux 2 (AL2) AMIs after November 26th, 2025. Additionally, Kubernetes version `1.32` is the last version for which Amazon EKS will release AL2 AMIs. From version `1.33` onwards, Amazon EKS will continue to release AL2023 and Bottlerocket based AMIs. For more information, see <>. ==== -Amazon EKS provides open-source build scripts in the https://github.com/awslabs/amazon-eks-ami[Amazon EKS AMI Build Specification] repository that you can use to view the configurations for `kubelet`, the runtime, the {aws} IAM Authenticator for Kubernetes, and build your own AL-based AMI from scratch. +The Amazon EKS-optimized Amazon Linux (AL) AMIs are built on top of AL2 and AL2023, specifically for use as nodes in Amazon EKS clusters. Amazon EKS provides open-source build scripts in the https://github.com/awslabs/amazon-eks-ami[Amazon EKS AMI Build Specification] repository that you can use to view the configurations for `kubelet`, the runtime, the {aws} IAM Authenticator for Kubernetes, and build your own AL-based AMI from scratch. This repository contains the specialized https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap script for AL2] and https://awslabs.github.io/amazon-eks-ami/nodeadm/[nodeadm tool for AL2023] that runs at boot time. These scripts configure your instance's certificate data, control plane endpoint, cluster name, and more. The scripts are considered the source of truth for Amazon EKS-optimized AMI builds, so you can follow the GitHub repository to monitor changes to our AMIs. diff --git a/latest/ug/nodes/eks-ami-deprecation-faqs.adoc b/latest/ug/nodes/eks-ami-deprecation-faqs.adoc index 253aec23e..4fd83bf96 100644 --- a/latest/ug/nodes/eks-ami-deprecation-faqs.adoc +++ b/latest/ug/nodes/eks-ami-deprecation-faqs.adoc @@ -10,11 +10,6 @@ include::../attributes.txt[] This document outlines the End of Support (EOS) information for Amazon EKS AL2-optimized and AL2-accelerated AMIs. -- -[WARNING] -==== -Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher. -==== - {aws} will end support for EKS AL2-optimized and AL2-accelerated AMIs, effective November 26, 2025. While you can continue using EKS AL2 AMIs after the end-of-support (EOS) date (November 26, 2025), EKS will no longer release any new Kubernetes versions or updates to AL2 AMIs, including minor releases, patches, and bug fixes after this date. We recommend upgrading to Amazon Linux 2023 (AL2023) or Bottlerocket AMIs: * AL2023 enables a secure-by-default approach with preconfigured security policies, SELinux in permissive mode, IMDSv2-only mode enabled by default, optimized boot times, and improved package management for enhanced security and performance, well-suited for infrastructure requiring significant customizations like direct OS-level access or extensive node changes. To learn more, see https://aws.amazon.com/linux/amazon-linux-2023/faqs/[AL2023 FAQs] or view our detailed migration guidance at <>. @@ -93,12 +88,12 @@ Kubernetes version 1.32 is the last version for which Amazon EKS will release AL |https://docs.nvidia.com/deploy/cuda-compatibility/why-cuda-compatibility.html#why-cuda-compatibility[CUDA user mode driver] |12.x -|12.x,13.x +|12.x |12.x,13.x |NVIDIA GPU Driver |R570 -|R580 +|R570 |R570, R580 |{aws} Neuron Driver diff --git a/latest/ug/nodes/eks-optimized-ami.adoc b/latest/ug/nodes/eks-optimized-ami.adoc index c18e6c0f2..e5e01e221 100644 --- a/latest/ug/nodes/eks-optimized-ami.adoc +++ b/latest/ug/nodes/eks-optimized-ami.adoc @@ -7,22 +7,30 @@ include::../attributes.txt[] [abstract] -- -Select an Amazon EKS-optimized Amazon Linux AMI to provision your cluster nodes with support for standard, accelerated, and Arm-based architectures. +The Amazon EKS-optimized Amazon Linux AMIs are built on top of Amazon Linux 2 (AL2) and Amazon Linux 2023 (AL2023). They are configured to serve as the base images for Amazon EKS nodes. -- -Amazon Elastic Kubernetes Service (Amazon EKS) provides specialized Amazon Machine Images (AMIs) optimized for running Kubernetes worker nodes. These EKS-optimized Amazon Linux (AL) AMIs are pre-configured with essential components—such as `kubelet`, the AWS IAM Authenticator, and `containerd`—to ensure seamless integration and security within your clusters. This guide details the available AMI versions and outlines specialized options for accelerated computing and Arm-based architectures. +The Amazon EKS-optimized Amazon Linux AMIs are built on top of Amazon Linux 2 (AL2) and Amazon Linux 2023 (AL2023). They are configured to serve as the base images for Amazon EKS nodes. The AMIs are configured to work with Amazon EKS and they include the following components: + +* `kubelet` +* {aws} IAM Authenticator +* `containerd` + +[NOTE] +==== -[#ami-considerations] -== Considerations * You can track security or privacy events for Amazon Linux at the https://alas.aws.amazon.com/[Amazon Linux security center] by choosing the tab for your desired version. You can also subscribe to the applicable RSS feed. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue. * Before deploying an accelerated or Arm AMI, review the information in <> and <>. * Amazon EC2 `P2` instances aren't supported on Amazon EKS because they require `NVIDIA` driver version 470 or earlier. -* Any newly created managed node groups in clusters on version `1.30` or newer will automatically default to using AL2023 as the node operating system. +* Any newly created managed node groups in clusters on version `1.30` or newer will automatically default to using AL2023 as the node operating system. Previously, new node groups would default to AL2. You can continue to use AL2 by choosing it as the AMI type when creating a new node group. +* Amazon EKS will no longer publish EKS-optimized Amazon Linux 2 (AL2) AMIs after November 26th, 2025. Additionally, Kubernetes version `1.32` is the last version for which Amazon EKS will release AL2 AMIs. From version `1.33` onwards, Amazon EKS will continue to release AL2023 and Bottlerocket based AMIs. + +==== [#gpu-ami] == Amazon EKS-optimized accelerated Amazon Linux AMIs -Amazon EKS-optimized accelerated Amazon Linux (AL) AMIs are built on top of the standard EKS-optimized Amazon Linux AMIs. They are configured to serve as optional images for Amazon EKS nodes to support GPU, link:machine-learning/inferentia/[Inferentia,type="marketing"], and link:machine-learning/trainium/[Trainium,type="marketing"] based workloads. +The Amazon EKS-optimized accelerated Amazon Linux AMIs are built on top of the standard Amazon EKS-optimized Amazon Linux AMIs. They are configured to serve as optional images for Amazon EKS nodes to support GPU, link:machine-learning/inferentia/[Inferentia,type="marketing"], and link:machine-learning/trainium/[Trainium,type="marketing"] based workloads. For more information, see <>. diff --git a/latest/ug/nodes/hybrid-nodes-add-ons.adoc b/latest/ug/nodes/hybrid-nodes-add-ons.adoc index 62bbef0c3..67f0b6085 100644 --- a/latest/ug/nodes/hybrid-nodes-add-ons.adoc +++ b/latest/ug/nodes/hybrid-nodes-add-ons.adoc @@ -177,7 +177,7 @@ spec: + This will configure `nodeadm` to create a credentials file to be configured on the node under `/eks-hybrid/.aws/credentials`, which will be used by `eks-pod-identity-agent` pods. This credentials file will contain temporary {aws} credentials that will be refreshed periodically. + -. After you update the `nodeadm` config on _each_ node, run the following `nodeadm init` command with your `nodeConfig.yaml` to join your hybrid nodes to your Amazon EKS cluster. If your nodes have joined the cluster previous, still run the `nodeadm init` command again. +. After you update the `nodeadm` config on _each_ node, run the following `nodeadm init` command with your `nodeConfig.yaml` to join your hybrid nodes to your Amazon EKS cluster. If your nodes have joined the cluster previous, still run the `init` command again. + [source,bash,subs="verbatim,attributes"] ---- diff --git a/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc b/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc index 1d85997ba..6171a21d2 100644 --- a/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc +++ b/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc @@ -58,11 +58,21 @@ region = "" enabled = true cache-duration = "12h" image-patterns = [ - "\*.dkr.ecr.*.amazonaws.com", - "\*.dkr.ecr.*.amazonaws.com.cn", - "\*.dkr.ecr.*.amazonaws.eu", - "\*.dkr.ecr-fips.*.amazonaws.com", - "\*.dkr.ecr-fips.*.amazonaws.eu", + "*.dkr.ecr.*.amazonaws.com", + "*.dkr.ecr.*.amazonaws.com.cn", + "*.dkr.ecr.*.amazonaws.eu", + "", + "", + "*.dkr.ecr-fips.*.amazonaws.com", + "*.dkr.ecr-fips.*.amazonaws.eu", + "", + "", + "", + "", + "", + "", + "", + "", "public.ecr.aws" ] @@ -137,11 +147,21 @@ config = "" enabled = true cache-duration = "12h" image-patterns = [ - "\*.dkr.ecr.*.amazonaws.com", - "\*.dkr.ecr.*.amazonaws.com.cn", - "\*.dkr.ecr.*.amazonaws.eu", - "\*.dkr.ecr-fips.*.amazonaws.com", - "\*.dkr.ecr-fips.*.amazonaws.eu", + "*.dkr.ecr.*.amazonaws.com", + "*.dkr.ecr.*.amazonaws.com.cn", + "*.dkr.ecr.*.amazonaws.eu", + "", + "", + "*.dkr.ecr-fips.*.amazonaws.com", + "*.dkr.ecr-fips.*.amazonaws.eu", + "", + "", + "", + "", + "", + "", + "", + "", "public.ecr.aws" ] diff --git a/latest/ug/nodes/hybrid-nodes-creds.adoc b/latest/ug/nodes/hybrid-nodes-creds.adoc index 451abdf48..a1a663778 100644 --- a/latest/ug/nodes/hybrid-nodes-creds.adoc +++ b/latest/ug/nodes/hybrid-nodes-creds.adoc @@ -23,11 +23,10 @@ Before you can connect hybrid nodes to your Amazon EKS cluster, you must create The Hybrid Nodes IAM role must have the following permissions. -* Permissions for `nodeadm` to use the `eks:DescribeCluster` action to gather information about the cluster to which you want to connect hybrid nodes. If you do not enable the `eks:DescribeCluster` action, then you must pass your Kubernetes API endpoint, cluster CA bundle, and service IPv4 CIDR in the node configuration you pass to the `nodeadm init` command. -* Permissions for `nodeadm` to use the `eks:ListAccessEntries` action to list the access entries on the cluster to which you want to connect hybrid nodes. If you do not enable the `eks:ListAccessEntries` action, then you must pass the `--skip cluster-access-validation` flag when you run the `nodeadm init` command. +* Permissions for `nodeadm` to use the `eks:DescribeCluster` action to gather information about the cluster used for connecting hybrid nodes to the cluster. If you do not enable the `eks:DescribeCluster` action, then you must pass your Kubernetes API endpoint, cluster CA bundle, and service IPv4 CIDR in the node configuration you pass to `nodeadm` when you run `nodeadm` init. * Permissions for the kubelet to use container images from Amazon Elastic Container Registry (Amazon ECR) as defined in the link:aws-managed-policy/latest/reference/AmazonEC2ContainerRegistryPullOnly.html[AmazonEC2ContainerRegistryPullOnly,type="documentation"] policy. -* If using {aws} SSM, permissions for `nodeadm init` to use {aws} SSM hybrid activations as defined in the +* If using {aws} SSM, permissions for `nodeadm` init to use {aws} SSM hybrid activations as defined in the link:aws-managed-policy/latest/reference/AmazonSSMManagedInstanceCore.html[,AmazonSSMManagedInstanceCore,type="documentation"] policy. * If using {aws} SSM, permissions to use the `ssm:DeregisterManagedInstance` action and `ssm:DescribeInstanceInformation` action for `nodeadm uninstall` to deregister instances. * (Optional) Permissions for the Amazon EKS Pod Identity Agent to use the `eks-auth:AssumeRoleForPodIdentity` action to retrieve credentials for pods. diff --git a/latest/ug/nodes/hybrid-nodes-troubleshooting.adoc b/latest/ug/nodes/hybrid-nodes-troubleshooting.adoc index b368d5b52..415b1c190 100644 --- a/latest/ug/nodes/hybrid-nodes-troubleshooting.adoc +++ b/latest/ug/nodes/hybrid-nodes-troubleshooting.adoc @@ -77,22 +77,13 @@ When running `nodeadm init`, if you see errors related to `operation error` or ` *Hybrid Nodes IAM role missing permissions for the `eks:DescribeCluster` action* -When running `nodeadm init`, `nodeadm` attempts to gather information about your EKS cluster by calling the EKS `DescribeCluster` action. If your Hybrid Nodes IAM role does not have permission for the `eks:DescribeCluster` action, then you must pass your Kubernetes API endpoint, cluster CA bundle, and service IPv4 CIDR in the node configuration you pass to `nodeadm` when you run `nodeadm init`. For more information on the required permissions for the Hybrid Nodes IAM role, see <>. +When running `nodeadm init`, `nodeadm` attempts to gather information about your EKS cluster by calling Describe Cluster. If your Hybrid Nodes IAM role does not have permission for the `eks:DescribeCluster` action. For more information on the required permissions for the Hybrid Nodes IAM role, see <>. [source,bash,subs="verbatim,attributes"] ---- "msg":"Command failed","error":"operation error EKS: DescribeCluster, https response error StatusCode: 403 ... AccessDeniedException" ---- -*Hybrid Nodes IAM role missing permissions for the `eks:ListAccessEntries` action* - -When running `nodeadm init`, `nodeadm` attempts to validate whether your EKS cluster has an access entry of type `HYBRID_LINUX` associated with the Hybrid Nodes IAM role by calling the EKS `ListAccessEntries` action. If your Hybrid Nodes IAM role does not have permission for the `eks:ListAccessEntries` action, then you must pass the `--skip cluster-access-validation` flag when you run the `nodeadm init` command. For more information on the required permissions for the Hybrid Nodes IAM role, see <>. - -[source,bash,subs="verbatim,attributes"] ----- -"msg":"Command failed","error":"operation error EKS: ListAccessEntries, https response error StatusCode: 403 ... AccessDeniedException" ----- - *Node IP not in remote node network CIDR* When running `nodeadm init`, you might encounter an error if the node's IP address is not within the specified remote node network CIDRs. The error will look similar to the following example: diff --git a/latest/ug/nodes/launch-templates.adoc b/latest/ug/nodes/launch-templates.adoc index 4450fdb8e..136fea7bf 100644 --- a/latest/ug/nodes/launch-templates.adoc +++ b/latest/ug/nodes/launch-templates.adoc @@ -10,7 +10,12 @@ include::../attributes.txt[] For the highest level of customization, you can deploy managed nodes using your own launch template and a custom AMI. -- -For the highest level of customization, you can deploy managed nodes with your own launch template based on the steps on this page. Using a launch template allows capabilities such as to provide bootstrap arguments during deployment of a node (e.g., extra https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/[kubelet] arguments), assign IP addresses to Pods from a different CIDR block than the IP address assigned to the node, deploy your own custom AMI to nodes, or deploy your own custom CNI to nodes. +For the highest level of customization, you can deploy managed nodes using your own launch template. Using a launch template allows capabilities such as the following: + +* Provide bootstrap arguments at deployment of a node, such as extra https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/[kubelet] arguments. +* Assign IP addresses to Pods from a different CIDR block than the IP address assigned to the node. +* Deploy your own custom AMI to nodes. +* Deploy your own custom CNI to nodes. When you give your own launch template upon first creating a managed node group, you will also have greater flexibility later. As long as you deploy a managed node group with your own launch template, you can iteratively update it with a different version of the same launch template. When you update your node group to a different version of your launch template, all nodes in the group are recycled to match the new configuration of the specified launch template version. @@ -54,13 +59,7 @@ a|*Application and OS Images (Amazon Machine Image)* under *Launch template cont * Using a custom AMI. If you specify an AMI that doesn't meet the requirements listed in <>, the node group deployment will fail. -* Want to provide user data to provide arguments to the `bootstrap.sh` file included with an Amazon EKS optimized AMI. You can enable your instances to assign a significantly higher number of IP addresses to Pods, assign IP addresses to Pods from a different CIDR block than the instance's, or deploy a private cluster without outbound internet access. For more information, see the following topics: - -+ -** <> -** <> -** <> -** <> +* Want to provide additional arguments to the NodeConfig specification of an Amazon EKS optimized AMI. For more information, see https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfig[NodeConfig API reference] and https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/examples/[NodeConfig examples]. |*Disk size* under *Node group compute configuration* on *Set compute and scaling configuration* page – Console displays *Specified in launch template*. diff --git a/latest/ug/nodes/launch-workers.adoc b/latest/ug/nodes/launch-workers.adoc index 9d99015ef..3fd6b3aa4 100644 --- a/latest/ug/nodes/launch-workers.adoc +++ b/latest/ug/nodes/launch-workers.adoc @@ -96,7 +96,7 @@ For more information, see https://aws.github.io/aws-eks-best-practices/security/ + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-26/amazon-eks-nodegroup.yaml +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2022-12-23/amazon-eks-nodegroup.yaml ---- . Wait for your cluster status to show as `ACTIVE`. If you launch your nodes before the cluster is active, the nodes fail to register with the cluster and you will have to relaunch them. . Open the link:cloudformation/[{aws} CloudFormation console,type="console"]. @@ -116,24 +116,31 @@ The following steps show one operation to retrieve the applicable group. .. Choose the name of the cluster. .. Choose the *Networking* tab. .. Use the *Additional security groups* value as a reference when selecting from the *ClusterControlPlaneSecurityGroup* dropdown list. -** *ApiServerEndpoint*: Enter the API Server Endpoint for your EKS Cluster. This can be found in the Details section of the EKS Cluster Console -** *CertificateAuthorityData*: Enter the base64 encoded Certificate Authority data which can also be found in the EKS Cluster Console's Deatils section. -** *ServiceCidr*: Enter the CIDR range used for allocating IP addresses to Kubernetes services within the cluster. This is found within the networking tab of the EKS Cluster Console. -** *AuthenticationMode*: Select the Authentication Mode in use in the EKS Cluster by reviewing the access tab within the EKS Cluster Console. ** *NodeGroupName*: Enter a name for your node group. This name can be used later to identify the Auto Scaling node group that's created for your nodes. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. ** *NodeAutoScalingGroupMinSize*: Enter the minimum number of nodes that your node Auto Scaling group can scale in to. ** *NodeAutoScalingGroupDesiredCapacity*: Enter the desired number of nodes to scale to when your stack is created. ** *NodeAutoScalingGroupMaxSize*: Enter the maximum number of nodes that your node Auto Scaling group can scale out to. ** *NodeInstanceType*: Choose an instance type for your nodes. For more information, see <>. -** *NodeImageIdSSMParam*: Pre-populated with the Amazon EC2 Systems Manager parameter of a recent Amazon EKS optimized Amazon Linux 2023 AMI for a variable Kubernetes version. To use a different Kubernetes minor version supported with Amazon EKS, replace [.replaceable]`1.XX` with a different link:eks/latest/userguide/kubernetes-versions.html[supported version,type="documentation"]. We recommend specifying the same Kubernetes version as your cluster. +** *NodeImageIdSSMParam*: Pre-populated with the Amazon EC2 Systems Manager parameter of a recent Amazon EKS optimized AMI for a variable Kubernetes version. To use a different Kubernetes minor version supported with Amazon EKS, replace [.replaceable]`1.XX` with a different link:eks/latest/userguide/kubernetes-versions.html[supported version,type="documentation"]. We recommend specifying the same Kubernetes version as your cluster. + -You can also replace [.replaceable]`amazon-linux-2023` with a different AMI type. For more information, see <>. +You can also replace [.replaceable]`amazon-linux-2` with a different AMI type. For more information, see <>. + -NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security or privacy events for Amazon Linux 2023 at the https://alas.aws.amazon.com/alas2023.html[Amazon Linux Security Center] or subscribe to the associated https://alas.aws.amazon.com/AL2023/alas.rss[RSS feed]. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue. +NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security or privacy events for Amazon Linux 2 at the https://alas.aws.amazon.com/alas2.html[Amazon Linux Security Center] or subscribe to the associated https://alas.aws.amazon.com/AL2/alas.rss[RSS feed]. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue. ** *NodeImageId*: (Optional) If you're using your own custom AMI (instead of an Amazon EKS optimized AMI), enter a node AMI ID for your {aws} Region. If you specify a value here, it overrides any values in the *NodeImageIdSSMParam* field. ** *NodeVolumeSize*: Specify a root volume size for your nodes, in GiB. ** *NodeVolumeType*: Specify a root volume type for your nodes. ** *KeyName*: Enter the name of an Amazon EC2 SSH key pair that you can use to connect using SSH into your nodes with after they launch. If you don't already have an Amazon EC2 key pair, you can create one in the {aws-management-console}. For more information, see link:AWSEC2/latest/UserGuide/ec2-key-pairs.html[Amazon EC2 key pairs,type="documentation"] in the _Amazon EC2 User Guide_. ++ +NOTE: If you don't provide a key pair here, the {aws} CloudFormation stack creation fails. +** *BootstrapArguments*: Specify any optional arguments to pass to the node bootstrap script, such as extra `kubelet` arguments. For more information, view the https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap script usage information] on GitHub. ++ +To deploy a node group that: ++ +*** can assign a significantly higher number of IP addresses to Pods than the default configuration, see <>. +*** can assign `IPv4` addresses to Pods from a different CIDR block than that of the instance, see <>. +*** can assign `IPv6` addresses to Pods and services, see <>. +*** don't have outbound internet access, see <>. +** *DisableIMDSv1*: By default, each node supports the Instance Metadata Service Version 1 (IMDSv1) and IMDSv2. You can disable IMDSv1. To prevent future nodes and Pods in the node group from using MDSv1, set *DisableIMDSv1* to *true*. For more information about IMDS, see link:AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html[Configuring the instance metadata service,type="documentation"]. For more information about restricting access to it on your nodes, see https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node[Restrict access to the instance profile assigned to the worker node]. ** *VpcId*: Enter the ID for the <> that you created. ** *Subnets*: Choose the subnets that you created for your VPC. If you created your VPC using the steps that are described in <>, specify only the private subnets within the VPC for your nodes to launch into. You can see which subnets are private by opening each subnet link from the *Networking* tab of your cluster. + @@ -145,14 +152,14 @@ NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security ==== . Select your desired choices on the *Configure stack options* page, and then choose *Next*. . Select the check box to the left of *I acknowledge that {aws} CloudFormation might create IAM resources.*, and then choose *Create stack*. -. When your stack has finished creating, select it in the console and choose *Outputs*. If you are using the `EKS API` or `EKS API and ConfigMap` Authentication Modes, this is the last step. -. If you are using the `ConfigMap` Authentication Mode, record the *NodeInstanceRole* for the node group that was created. +. When your stack has finished creating, select it in the console and choose *Outputs*. +. Record the *NodeInstanceRole* for the node group that was created. You need this when you configure your Amazon EKS nodes. *Step 2: Enable nodes to join your cluster* [NOTE] ==== -The following two steps are only needed if using the Configmap Authentication Mode within the EKS Cluster. Additionally, if you launched nodes inside a private VPC without outbound internet access, make sure to enable nodes to join your cluster from within the VPC. +If you launched nodes inside a private VPC without outbound internet access, make sure to enable nodes to join your cluster from within the VPC. ==== . Check to see if you already have an `aws-auth` `ConfigMap`. diff --git a/latest/ug/nodes/managed-node-groups.adoc b/latest/ug/nodes/managed-node-groups.adoc index b2cba52c9..c933d94db 100644 --- a/latest/ug/nodes/managed-node-groups.adoc +++ b/latest/ug/nodes/managed-node-groups.adoc @@ -107,8 +107,6 @@ To increase the number of Spot capacity pools available for allocating capacity ** If a Spot two-minute interruption notice arrives before the replacement Spot node is in a `Ready` state, Amazon EKS starts draining the Spot node that received the rebalance recommendation. Amazon EKS drains the node on a best-effort basis. As a result, there's no guarantee that Amazon EKS will wait for the replacement node to join the cluster before draining the existing node. ** When a replacement Spot node is bootstrapped and in the `Ready` state on Kubernetes, Amazon EKS cordons and drains the Spot node that received the rebalance recommendation. Cordoning the Spot node ensures that the service controller doesn't send any new requests to this Spot node. It also removes it from its list of healthy, active Spot nodes. Draining the Spot node ensures that running Pods are evicted gracefully. * Amazon EKS adds the following Kubernetes label to all nodes in your managed node group that specifies the capacity type: `eks.amazonaws.com/capacityType: SPOT`. You can use this label to schedule fault tolerant applications on Spot nodes. -+ -IMPORTANT: EC2 issues a https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-instance-termination-notices.html[Spot interruption notice] two minutes prior to terminating your Spot Instance. However, Pods on Spot nodes may not receive the full 2-minute window for graceful shutdown. When EC2 issues the notice, there is a delay before Amazon EKS begins evicting Pods. Evictions occur sequentially to protect the Kubernetes API server, so during multiple simultaneous Spot reclamations, some Pods may receive delayed eviction notices. Pods may be forcibly terminated without receiving termination signals, particularly on nodes with high Pod density, during concurrent reclamations, or when using long termination grace periods. For Spot workloads, we recommend designing applications to be interruption-tolerant, using termination grace periods of 30 seconds or less, avoiding long-running preStop hooks, and monitoring Pod eviction metrics to understand actual grace periods in your clusters. For workloads requiring guaranteed graceful termination, we recommend using On-Demand capacity instead. When deciding whether to deploy a node group with On-Demand or Spot capacity, you should consider the following conditions: diff --git a/latest/ug/nodes/managed-node-update-behavior.adoc b/latest/ug/nodes/managed-node-update-behavior.adoc index 01179d4fa..d3633efcd 100644 --- a/latest/ug/nodes/managed-node-update-behavior.adoc +++ b/latest/ug/nodes/managed-node-update-behavior.adoc @@ -70,7 +70,7 @@ Custom user data can sometimes break the bootstrap process. This scenario can le *Any changes which make a node unhealthy or not ready*:: Node disk pressure, memory pressure, and similar conditions can lead to a node not going to `Ready` state. -*Each node most bootstrap within 15 minutes*:: +*Each node must bootstrap within 15 minutes*:: If any node takes more than 15 minutes to bootstrap and join the cluster, it will cause the upgrade to time out. This is the total runtime for bootstrapping a new node measured from when a new node is required to when it joins the cluster. When upgrading a managed node group, the time counter starts as soon as the Auto Scaling Group size increases. diff --git a/latest/ug/nodes/retrieve-ami-id.adoc b/latest/ug/nodes/retrieve-ami-id.adoc index 4bac972a3..405e28712 100644 --- a/latest/ug/nodes/retrieve-ami-id.adoc +++ b/latest/ug/nodes/retrieve-ami-id.adoc @@ -22,6 +22,9 @@ You can retrieve the image ID of the latest recommended Amazon EKS optimized Ama ** Use [.replaceable]`amazon-linux-2023/x86_64/nvidia` for the latest approved AL2023 NVIDIA `x86` based instances. ** Use [.replaceable]`amazon-linux-2023/arm64/nvidia` for the latest approved AL2023 NVIDIA `arm64` based instances. ** Use [.replaceable]`amazon-linux-2023/x86_64/neuron` for the latest AL2023 link:machine-learning/neuron/[{aws} Neuron,type="marketing"] instances. +** Use [.replaceable]`amazon-linux-2` for Amazon Linux 2 (AL2) `x86` based instances. +** Use [.replaceable]`amazon-linux-2-arm64` for AL2 ARM instances, such as link:ec2/graviton/[{aws} Graviton,type="marketing"] based instances. +** Use [.replaceable]`amazon-linux-2-gpu` for AL2 link:AWSEC2/latest/UserGuide/accelerated-computing-instances.html[hardware accelerated,type="documentation"] `x86` based instances for NVIDIA GPU, link:machine-learning/inferentia/[Inferentia,type="marketing"], and link:machine-learning/trainium/[Trainium,type="marketing"] based workloads. * Replace `` with an link:general/latest/gr/eks.html[Amazon EKS supported {aws} Region,type="documentation"] for which you want the AMI ID. [source,bash,subs="verbatim,attributes"] diff --git a/latest/ug/nodes/worker.adoc b/latest/ug/nodes/worker.adoc index 8771d1924..df2e29237 100644 --- a/latest/ug/nodes/worker.adoc +++ b/latest/ug/nodes/worker.adoc @@ -14,7 +14,7 @@ A cluster contains one or more Amazon EC2 nodes that Pods are scheduled on. Amaz A cluster can contain several node groups. Each node group contains one or more nodes that are deployed in an link:autoscaling/ec2/userguide/AutoScalingGroup.html[Amazon EC2 Auto Scaling group,type="documentation"]. The instance type of the nodes within the group can vary, such as when using link:AWSEC2/latest/UserGuide/ec2-fleet-attribute-based-instance-type-selection.html[attribute-based instance type selection,type="documentation"] with https://karpenter.sh/[Karpenter]. All instances in a node group must use the <>. -Amazon EKS provides specialized Amazon Machine Images (AMIs) that are called Amazon EKS optimized AMIs. The AMIs are configured to work with Amazon EKS. Their components include `containerd`, `kubelet`, and the {aws} IAM Authenticator. The AMIs also contain a specialized https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap script] that allows it to discover and connect to your cluster's control plane automatically. +Amazon EKS provides specialized Amazon Machine Images (AMIs) that are called Amazon EKS optimized AMIs. The AMIs are configured to work with Amazon EKS. Their components include `containerd`, `kubelet`, and the {aws} IAM Authenticator. The AMIs use https://awslabs.github.io/amazon-eks-ami/nodeadm[nodeadm], a tool that automatically connects nodes to your cluster's control plane and configures `kubelet` and `containerd`. If you restrict access to the public endpoint of your cluster using CIDR blocks, we recommend that you also enable private endpoint access. This is so that nodes can communicate with the cluster. Without the private endpoint enabled, the CIDR blocks that you specify for public access must include the egress sources from your VPC. For more information, see <>. diff --git a/latest/ug/observability/container-network-observability.adoc b/latest/ug/observability/container-network-observability.adoc index a6e980779..ebafcaea5 100644 --- a/latest/ug/observability/container-network-observability.adoc +++ b/latest/ug/observability/container-network-observability.adoc @@ -41,7 +41,6 @@ When using Network Flow Monitor in EKS, you can maintain your existing observabi . As mentioned above, if you enable Container Network Observability from the EKS console, the underlying NFM resource dependencies (Scope and Monitor) will be automatically created on your behalf, and you will be guided through the installation process of the EKS add-on for NFM. . If you want to enable this feature using Infrastructure as Code (IaC) like Terraform, you will have to define the following dependencies in your IaC: NFM Scope, NFM Monitor, EKS add-on for NFM. In addition, you'll have to grant the https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchNetworkFlowMonitorAgentPublishPolicy.html[relevant permissions] to the EKS add-on using https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html[Pod Identity] or https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html[IAM roles for service accounts (IRSA)]. . You must be running a minimum version of 1.1.0 for the NFM agent's EKS add-on. -. You have to use v6.21.0 or higher of the https://github.com/hashicorp/terraform-provider-aws[Terraform {aws} Provider] for support of Network Flow Monitor resources. === Required IAM permissions @@ -406,7 +405,4 @@ image::images/cluster-view.png[Illustration of flow table in cluster view] * Supported system metrics are in OpenMetrics format, and can be directly scraped from the Network Flow Monitor (NFM) agent. * To enable Container Network Observability in EKS using Infrastructure as Code (IaC) like https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkflowmonitor_monitor[Terraform], you need to have these dependencies defined and created in your configurations: NFM scope, NFM monitor and the NFM agent. * Network Flow Monitor supports up to approximately 5 million flows per minute. This is approximately 5,000 EC2 instances (EKS worker nodes) with the Network Flow Monitor agent installed. Installing agents on more than 5000 instances may affect monitoring performance until additional capacity is available. -* You must be running a minimum version of 1.1.0 for the NFM agent's EKS add-on. -* You have to use v6.21.0 or higher of the https://github.com/hashicorp/terraform-provider-aws[Terraform {aws} Provider] for support of Network Flow Monitor resources. -* To enrich the network flows with pod metadata, your pods should be running in their own isolated network namespace, not the host network namespace. - +* You must be running a minimum version of 1.1.0 for the NFM agent's EKS add-on. \ No newline at end of file diff --git a/latest/ug/observability/observability-dashboard.adoc b/latest/ug/observability/observability-dashboard.adoc index 49275eb31..ee07e806b 100644 --- a/latest/ug/observability/observability-dashboard.adoc +++ b/latest/ug/observability/observability-dashboard.adoc @@ -115,13 +115,4 @@ The Amazon EKS node monitoring agent automatically reads node logs to detect hea When you refresh the page, any resolved issues will disappear from the list. If auto repair is enabled, you could temporarily see some health issues that will be resolved without action from you. Issues that are not supported by auto repair may require manual action from you depending on the type. -For node health issues to be reported, your cluster must use Amazon EKS Auto Mode or have the node monitoring agent add-on. For more information, see <>. - -[#observability-capabilities] -== EKS Capabilities - -The *Capabilities* section shows the status and health of your EKS Capability resources in the cluster. -Health and status notifications for both capabilities and their managed Kubernetes resources in your cluster can be monitored here. -When you refresh the page, any resolved issues will disappear from the list. - -For more information, see <>. \ No newline at end of file +For node health issues to be reported, your cluster must use Amazon EKS Auto Mode or have the node monitoring agent add-on. For more information, see <>. \ No newline at end of file diff --git a/latest/ug/outposts/eks-outposts-self-managed-nodes.adoc b/latest/ug/outposts/eks-outposts-self-managed-nodes.adoc index 780d7b988..37b1da142 100644 --- a/latest/ug/outposts/eks-outposts-self-managed-nodes.adoc +++ b/latest/ug/outposts/eks-outposts-self-managed-nodes.adoc @@ -12,13 +12,13 @@ Learn how to launch Auto Scaling groups of Amazon Linux nodes on an Outpost that [IMPORTANT] ==== -Amazon EKS Local Clusters on Outposts only supports nodes created from the following Amazon EKS-optimized Amazon Linux 2023 AMIs: +Amazon EKS Local Clusters on Outposts only supports nodes created from the following Amazon EKS-optimized Amazon Linux 2 AMIs: -* Standard Amazon Linux 2023 (`amazon-linux-2023/x86_64/standard`) -* Accelerated Nvidia Amazon Linux 2023 (`amazon-linux-2023/x86_64/nvidia`) -* Accelerated Neuron Amazon Linux 2023 (`amazon-linux-2023/x86_64/neuron`) +* Standard Amazon Linux 2 (`amazon-linux-2`) +* GPU-enabled Amazon Linux 2 (`amazon-linux-2-gpu`) +* Arm64-based Amazon Linux 2 (`amazon-linux-2-arm64`) -{aws} ended support for EKS AL2-optimized and AL2-accelerated AMIs, effective November 26, 2025. While you can continue using EKS AL2 AMIs after the end-of-support (EOS) date (November 26, 2025), EKS will no longer release any new Kubernetes versions or updates to AL2 AMIs, including minor releases, patches, and bug fixes after this date. See link:https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html[this] for more information on AL2 deprecation. +Nodes on Local Clusters that run Amazon Linux 2023 (AL2023) AMIs aren't supported and fail to join the cluster. ==== This topic describes how you can launch Auto Scaling groups of Amazon Linux nodes on an Outpost that register with your Amazon EKS cluster. The cluster can be on the {aws} Cloud or on an Outpost. @@ -50,7 +50,7 @@ You can create a self-managed node group for local cluster with the following to . Install version `{eksctl-min-version}` or later of the `eksctl` command line tool installed on your device or {aws} CloudShell. To install or update `eksctl`, see https://eksctl.io/installation[Installation] in the `eksctl` documentation. + . If your cluster is on the {aws} Cloud and the *AmazonEKS_CNI_Policy* managed IAM policy is attached to your <>, we recommend assigning it to an IAM role that you associate to the Kubernetes `aws-node` service account instead. For more information, see <>. If your cluster in on your Outpost, the policy must be attached to your node role. -. The following command creates a node group in an existing cluster. The cluster must have been created using `eksctl`. Replace [.replaceable]`al-nodes` with a name for your node group. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. Replace [.replaceable]`my-cluster` with the name of your cluster. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in. If your cluster exists on an Outpost, replace [.replaceable]`id` with the ID of an Outpost subnet. If your cluster exists on the {aws} Cloud, replace [.replaceable]`id` with the ID of a subnet that you didn't specify when you created your cluster. Replace the remaining example values with your own values. The nodes are created with the same Kubernetes version as the control plane, by default. +. The following command creates a node group in an existing cluster. The cluster must have been created using `eksctl`. Replace [.replaceable]`al-nodes` with a name for your node group. The node group name can't be longer than 63 characters. It must start with letter or digit, but can also include hyphens and underscores for the remaining characters. Replace [.replaceable]`my-cluster` with the name of your cluster. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in. If your cluster exists on an Outpost, replace [.replaceable]`id` with the ID of an Outpost subnet. If your cluster exists on the {aws} Cloud, replace [.replaceable]`id` with the ID of a subnet that you didn't specify when you created your cluster. Replace [.replaceable]`instance-type` with an instance type supported by your Outpost. Replace the remaining example values with your own values. The nodes are created with the same Kubernetes version as the control plane, by default. + Replace [.replaceable]`instance-type` with an instance type available on your Outpost. + @@ -61,9 +61,7 @@ Create your node group with the following command. [source,bash,subs="verbatim,attributes"] ---- eksctl create nodegroup --cluster my-cluster --name al-nodes --node-type instance-type \ - --nodes 3 --nodes-min 1 --nodes-max 4 --managed=false \ - --node-volume-type gp2 --subnet-ids subnet-id \ - --node-ami-family AmazonLinux2023 + --nodes 3 --nodes-min 1 --nodes-max 4 --managed=false --node-volume-type gp2 --subnet-ids subnet-id ---- + If your cluster is deployed on the {aws} Cloud: @@ -91,7 +89,7 @@ For a complete list of all available options and defaults, see https://eksctl.io + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-24/amazon-eks-outpost-nodegroup.yaml +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2022-12-23/amazon-eks-nodegroup.yaml ---- . Open the link:cloudformation/[{aws} CloudFormation console,type="console"]. . Choose *Create stack* and then select *With new resources (standard)*. @@ -99,11 +97,7 @@ curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-24/ . On the *Specify stack details* page, enter the following parameters accordingly, and then choose *Next*: + ** *Stack name*: Choose a stack name for your {aws} CloudFormation stack. For example, you can call it [.replaceable]`al-nodes`. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the {aws} Region and {aws} account that you're creating the cluster in. -** *ApiServerEndpoint*: Enter the Kubernetes API Server endpoint, visible in EKS console or via DescribeCluster API. ** *ClusterName*: Enter the name of your cluster. If this name doesn't match your cluster name, your nodes can't join the cluster. -** *ClusterId*: Enter the id assigned to the cluster by EKS service. Visible via DescribeCluster API. If this id doesn't match your cluster id, your nodes can't join the cluster. -** *CertificateAuthority*: Enter base64 encoded string of the Kubernetes Certificate Authority. Visible in EKS console or via DescribeCluster API. -** *ServiceCidr*: Enter the Kubernetes Services CIDR. Visible in EKS console or via DescribeCluster API. ** *ClusterControlPlaneSecurityGroup*: Choose the *SecurityGroups* value from the {aws} CloudFormation output that you generated when you created your <>. + The following steps show one operation to retrieve the applicable group. @@ -119,7 +113,7 @@ The following steps show one operation to retrieve the applicable group. ** *NodeInstanceType*: Choose an instance type for your nodes. If your cluster is running on the {aws} Cloud, then for more information, see <>. If your cluster is running on an Outpost, then you can only select an instance type that is available on your Outpost. ** *NodeImageIdSSMParam*: Pre-populated with the Amazon EC2 Systems Manager parameter of a recent Amazon EKS optimized AMI for a variable Kubernetes version. To use a different Kubernetes minor version supported with Amazon EKS, replace [.replaceable]`1.XX` with a different link:eks/latest/userguide/kubernetes-versions.html[supported version,type="documentation"]. We recommend specifying the same Kubernetes version as your cluster. + -To use an Amazon EKS optimized accelerated AMI, update [.replaceable]`NodeImageIdSSMParam` value to the desired SSM parameter. See how to retrieve EKS AMI IDs from SSM link:eks/latest/userguide/retrieve-ami-id.html[here,type="documentation"]. +To use an Amazon EKS optimized accelerated AMI, replace [.replaceable]`amazon-linux-2` with `amazon-linux-2-gpu`. To use an Amazon EKS optimized Arm AMI, replace [.replaceable]`amazon-linux-2` with `amazon-linux-2-arm64`. + NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security or privacy events for Amazon Linux at the https://alas.aws.amazon.com/[Amazon Linux security center] by choosing the tab for your desired version. You can also subscribe to the applicable RSS feed. Security and privacy events include an overview of the issue, what packages are affected, and how to update your instances to correct the issue. ** *NodeImageId*: (Optional) If you're using your own custom AMI (instead of an Amazon EKS optimized AMI), enter a node AMI ID for your {aws} Region. If you specify a value here, it overrides any values in the *NodeImageIdSSMParam* field. @@ -128,6 +122,23 @@ NOTE: The Amazon EKS node AMIs are based on Amazon Linux. You can track security ** *KeyName*: Enter the name of an Amazon EC2 SSH key pair that you can use to connect using SSH into your nodes with after they launch. If you don't already have an Amazon EC2 key pair, you can create one in the {aws-management-console}. For more information, see link:AWSEC2/latest/UserGuide/ec2-key-pairs.html[Amazon EC2 key pairs,type="documentation"] in the _Amazon EC2 User Guide_. + NOTE: If you don't provide a key pair here, the {aws} CloudFormation stack creation fails. +** *BootstrapArguments*: There are several optional arguments that you can pass to your nodes. For more information, view the https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh[bootstrap script usage information] on GitHub. If you're adding nodes to an Amazon EKS Local Cluster on {aws} Outposts (where the Kubernetes control plane instances run on {aws} Outposts) and the cluster doesn't have ingress and egress internet connection (also known as private clusters), then you must provide the following bootstrap arguments (as a single line). ++ +[source,bash,subs="verbatim,attributes"] +---- +--b64-cluster-ca ${CLUSTER_CA} --apiserver-endpoint https://${APISERVER_ENDPOINT} --enable-local-outpost true --cluster-id ${CLUSTER_ID} +---- +To retrieve the values for `CLUSTER_CA`, `APISERVER_ENDPOINT`, and `CLUSTER_ID` of your Amazon EKS local cluster, run the following {aws} CLI commands. Replace cluster-name with the name of your cluster and region (for example, us-east-1) with your cluster's {aws} Region. ++ +[source,bash,subs="verbatim,attributes"] +---- +echo "CLUSTER_CA=$(aws eks describe-cluster --name cluster-name --region region --query cluster.certificateAuthority.data --output text)" + +echo "APISERVER_ENDPOINT=$(aws eks describe-cluster --name cluster-name --region region --query cluster.endpoint --output text)" + +echo "CLUSTER_ID=$(aws eks describe-cluster --name cluster-name --region region --query cluster.id --output text)" +---- + ** *DisableIMDSv1*: By default, each node supports the Instance Metadata Service Version 1 (IMDSv1) and IMDSv2. You can disable IMDSv1. To prevent future nodes and Pods in the node group from using IMDSv1, set *DisableIMDSv1* to *true*. For more information about IMDS, see link:AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html[Configuring the instance metadata service,type="documentation"]. For more information about restricting access to it on your nodes, see https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node[Restrict access to the instance profile assigned to the worker node]. ** *VpcId*: Enter the ID for the <> that you created. Before choosing a VPC, review <>. diff --git a/latest/ug/quickstart.adoc b/latest/ug/quickstart.adoc index 623076f11..3640ed608 100644 --- a/latest/ug/quickstart.adoc +++ b/latest/ug/quickstart.adoc @@ -10,10 +10,9 @@ include::attributes.txt[] Deploy a game application and persist its data on Amazon EKS -- -This quickstart tutorial guides you through the steps to deploy the 2048 game sample application and persist its data on an Amazon EKS Auto Mode cluster using https://eksctl.io/[eksctl]. +This quickstart tutorial guides you through the steps to deploy the 2048 game sample application and persist its data on an Amazon EKS Auto Mode cluster using https://eksctl.io/[eksctl]. -<> simplifies cluster management by automating routine tasks like block storage, networking, load balancing, and compute autoscaling. -During setup, it handles creating nodes with EC2 managed instances, application load balancers, and EBS volumes. +<> simplifies cluster management by automating routine tasks like block storage, networking, load balancing, and compute autoscaling. During setup, it handles creating nodes with EC2 managed instances, application load balancers, and EBS volumes. In summary, you'll deploy a sample workload with the custom annotations needed for seamless integration with {aws} services. @@ -21,10 +20,9 @@ In summary, you'll deploy a sample workload with the custom annotations needed f Using the `eksctl` cluster template that follows, you'll build a cluster with EKS Auto Mode for automated node provisioning. -- *VPC Configuration*: When using the eksctl cluster template that follows, eksctl automatically creates an IPv4 Virtual Private Cloud (VPC) for the cluster. -By default, eksctl configures a VPC that addresses all networking requirements, in addition to creating both public and private endpoints. +- *VPC Configuration*: When using the eksctl cluster template that follows, eksctl automatically creates an IPv4 Virtual Private Cloud (VPC) for the cluster. By default, eksctl configures a VPC that addresses all networking requirements, in addition to creating both public and private endpoints. - *Instance Management*: EKS Auto Mode dynamically adds or removes nodes in your EKS cluster based on the demands of your Kubernetes applications. -- *Data Persistence*: Use the block storage capability of EKS Auto Mode to ensure the persistence of application data, even in scenarios involving pod restarts or failures. +- *Data Persistence*: Use the block storage capability of EKS Auto Mode to ensure the persistence of application data, even in scenarios involving pod restarts or failures. - *External App Access*: Use the load balancing capability of EKS Auto Mode to dynamically provision an Application Load Balancer (ALB). == Prerequisites @@ -38,8 +36,7 @@ Before you start, make sure you have performed the following tasks: In this section, you'll create a cluster using EKS Auto Mode for dynamic node provisioning. -Create a `cluster-config.yaml` file and paste the following contents into it. -Replace `region-code` with a valid Region (e.g., `us-east-1`). +Create a `cluster-config.yaml` file and paste the following contents into it. Replace `region-code` with a valid Region (e.g., `us-east-1`). ```yaml apiVersion: eksctl.io/v1alpha5 @@ -68,10 +65,7 @@ If you do not use eksctl to create the cluster, you need to manually tag the VPC == Create IngressClass -Create a Kubernetes `IngressClass` for EKS Auto Mode. -The IngressClass defines how EKS Auto Mode handles Ingress resources. -This step configures the load balancing capability of EKS Auto Mode. -When you create Ingress resources for your applications, EKS Auto Mode uses this IngressClass to automatically provision and manage load balancers, integrating your Kubernetes applications with {aws} load balancing services. +Create a Kubernetes `IngressClass` for EKS Auto Mode. The IngressClass defines how EKS Auto Mode handles Ingress resources. This step configures the load balancing capability of EKS Auto Mode. When you create Ingress resources for your applications, EKS Auto Mode uses this IngressClass to automatically provision and manage load balancers, integrating your Kubernetes applications with {aws} load balancing services. Save the following yaml file as `ingressclass.yaml`: @@ -94,9 +88,7 @@ kubectl apply -f ingressclass.yaml == Deploy the 2048 game sample application -In this section, we walk you through the steps to deploy the popular "`2048 game`" as a sample application within the cluster. -The provided manifest includes custom annotations for the Application Load Balancer (ALB). -These annotations integrate with and instruct EKS to handle incoming HTTP traffic as "internet-facing" and route it to the appropriate service in the `game-2048` namespace using the target type "ip". +In this section, we walk you through the steps to deploy the popular "`2048 game`" as a sample application within the cluster. The provided manifest includes custom annotations for the Application Load Balancer (ALB). These annotations integrate with and instruct the EKS to handle incoming HTTP traffic as "internet-facing" and route it to the appropriate service in the `game-2048` namespace using the target type "ip". [NOTE] ==== @@ -123,9 +115,7 @@ namespace/game-2048 created kubectl apply -n game-2048 -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.8.0/docs/examples/2048/2048_full.yaml ---- + -This manifest sets up a Kubernetes Deployment, Service, and Ingress for the `game-2048` namespace, creating the necessary resources to deploy and expose the `game-2048` application within the cluster. -It includes the creation of a service named `service-2048` that exposes the deployment on port `80`, and an Ingress resource named `ingress-2048` that defines routing rules for incoming HTTP traffic and annotations for an internet-facing Application Load Balancer (ALB). -You should see the following response output: +This manifest sets up a Kubernetes Deployment, Service, and Ingress for the `game-2048` namespace, creating the necessary resources to deploy and expose the `game-2048` application within the cluster. It includes the creation of a service named `service-2048` that exposes the deployment on port `80`, and an Ingress resource named `ingress-2048` that defines routing rules for incoming HTTP traffic and annotations for an internet-facing Application Load Balancer (ALB). You should see the following response output: + [source,bash,subs="verbatim,attributes"] ---- @@ -265,11 +255,11 @@ You should see the following response output: deployment.apps/deployment-2048 configured ---- -With these steps, your 2048 game on the cluster is now set up to persist data using the block storage capability of Amazon EKS Auto Mode. -This ensures that your game progress and data are safe even in the event of pod or node failures. +With these steps, your 2048 game on the cluster is now set up to persist data using the block storage capability of Amazon EKS Auto Mode. This ensures that your game progress and data are safe even in the event of pod or node failures. If you liked this tutorial, let us know by providing feedback so we're able to provide you with more use case-specific quickstart tutorials like this one. + == Clean up To avoid incurring future charges, you need to delete the associated CloudFormation stack manually to delete all resources created during this guide, including the VPC network. diff --git a/latest/ug/related-projects.adoc b/latest/ug/related-projects.adoc index d95b268cd..66a5ed7a7 100644 --- a/latest/ug/related-projects.adoc +++ b/latest/ug/related-projects.adoc @@ -14,32 +14,17 @@ These open-source projects extend the functionality of Kubernetes clusters runni [#oss-scope] == Support for software deployed to EKS -When reviewing the Amazon EKS docs, you'll encounter references to various open-source tools and software throughout our procedures and examples. These tools include the https://github.com/kubernetes-sigs/metrics-server[Kubernetes Metrics Server] and https://cert-manager.io/[Cert Manager.] +When reviewing the Amazon EKS docs, you'll encounter references to various open-source tools and software throughout our procedures and examples. These tools include the https://github.com/kubernetes-sigs/metrics-server[Kubernetes Metrics Server] and https://cert-manager.io/[Cert Manager.] -Please note that any third-party or open-source software you choose to deploy falls outside the scope of your {aws} Support Agreements. -A benefit of using Kubernetes is the active open source community. -We recommend working directly with the relevant open-source communities and project maintainers to establish appropriate support channels for such components. -For more information, see the https://www.cncf.io/projects/[graduated and incubating projects] associated with the Cloud Native Computing Foundation (CNCF). +Please note that any third-party or open-source software you choose to deploy falls outside the scope of your {aws} Support Agreements. A benefit of using Kubernetes is the active open source community. We recommend working directly with the relevant open-source communities and project maintainers to establish appropriate support channels for such components. For more information, see the https://www.cncf.io/projects/[graduated and incubating projects] associated with the Cloud Native Computing Foundation (CNCF). -The Kubernetes ecosystem includes numerous projects and components that come with different levels of community support, response times, and intended use cases. -When implementing these technologies alongside EKS, ensure you understand the support matrix for each component. +The Kubernetes ecosystem includes numerous projects and components that come with different levels of community support, response times, and intended use cases. When implementing these technologies alongside EKS, ensure you understand the support matrix for each component. -{aws} maintains the open-source components we integrate into the EKS control plane. -This includes our comprehensive security pipeline covering build verification, vulnerability scanning, validation testing, and patch management for all container images and binaries we distribute. -For example, {aws} is responsible for the https://kubernetes.io/docs/concepts/architecture/#kube-apiserver[Kubernetes API Server]. -The Kubernetes API server is covered by link:eks/sla/["Amazon EKS Service Level Agreement",type="marketing"]. -You can use your link:premiumsupport/plans/["Amazon Web Services Support Plan",type="marketing"] to resolve issues with the Kubernetes API server, or get general guidance. +{aws} maintains the open-source components we integrate into the EKS control plane. This includes our comprehensive security pipeline covering build verification, vulnerability scanning, validation testing, and patch management for all container images and binaries we distribute. For example, {aws} is responsible for the https://kubernetes.io/docs/concepts/architecture/#kube-apiserver[Kubernetes API Server]. The Kubernetes API server is covered by link:eks/sla/["Amazon EKS Service Level Agreement",type="marketing"]. You can use your link:premiumsupport/plans/["Amazon Web Services Support Plan",type="marketing"] to resolve issues with the Kubernetes API server, or get general guidance. -You need to carefully review the support offered for various Amazon EKS Add-ons. -{aws} add-ons are the only type of Amazon EKS add-on that are fully supported by {aws}. -{aws} Marketplace add-ons are primarily supported by {aws} Partners. -Community add-ons receive basic lifecycle support from {aws}. -For more information, see xref:addon-support[add-on Support.] +You need to carefully review the support offered for various Amazon EKS Add-ons. {aws} add-ons are the only type of Amazon EKS add-on that are fully supported by {aws}. {aws} Marketplace add-ons are primarily supported by {aws} Partners. Community add-ons receive basic lifecycle support from {aws}. For more information, see xref:addon-support[add-on Support.] -Every EKS add-on, irrespective of the type, receives basic lifecycle support from EKS including Marketplace add-ons. -Basic lifecycle support includes installing and uninstalling the add-on. -For more information on the types of Amazon EKS Add-ons available and the associated levels of support, see xref:addon-support[Scope of Support for Amazon EKS add-ons.] -To view add-ons fully supported by {aws}, see xref:workloads-add-ons-available-eks[Amazon Web Services add-ons.] +Every EKS add-ons, irrespective of the type, receives basic lifecycle support from EKS including Marketplace add-ons. Basic lifecycle support includes installing and uninstalling the add-on. For more information on the types of Amazon EKS Add-ons available and the associated levels of support, see xref:addon-support[Scope of Support for Amazon EKS add-ons.] To view add-ons fully supported by {aws}, see xref:workloads-add-ons-available-eks[Amazon Web Services add-ons.] * For more information about our security practices and support boundaries, see xref:security[Security in Amazon EKS.] * For more information about community and {aws} marketplace add-ons available through Amazon EKS Add-ons, see xref:addon-support["EKS Add-ons Support",type="documentation"]. @@ -62,48 +47,20 @@ Related management tools for Amazon EKS and Kubernetes clusters. [#related-aws-controllers] -=== {aws} Controllers for Kubernetes +=== {aws} controllers for Kubernetes With {aws} Controllers for Kubernetes, you can create and manage {aws} resources directly from your Kubernetes cluster. -Available in <>. -* https://aws-controllers-k8s.github.io/community/[Project URL] -* {aws} open source blog: link:opensource/aws-service-operator-kubernetes-available[{aws} service operator for Kubernetes now available,type="blog"] - - -[#related-kro] -=== kro (Kube Resource Orchestrator) - -kro enables you to create custom Kubernetes APIs that compose multiple resources into higher-level abstractions. -Platform teams can define reusable patterns with guardrails, while application teams use simple, high-level APIs to provision and manage resources. - -Available in <>. - - -* https://kro.run/[Project URL] -* https://kro.run/docs/[Project documentation] - -[#related-argocd] -=== Argo CD - -Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. -It continuously monitors your Git repositories and automatically syncs changes to your clusters. - -Available in <>. - - -* https://argo-cd.readthedocs.io/[Project URL] -* https://argo-cd.readthedocs.io/en/stable/[Project documentation] +* https://github.com/aws-controllers-k8s/[Project URL] +* {aws} open source blog: link:opensource/aws-service-operator-kubernetes-available[{aws} service operator for Kubernetes now available,type="blog"] [#related-flux-cd] === Flux CD -Flux is a tool that you can use to manage your cluster configuration using Git. -It uses an operator in the cluster to trigger deployments inside of Kubernetes. -For more information about operators, see https://operatorhub.io/[OperatorHub.io] on GitHub. +Flux is a tool that you can use to manage your cluster configuration using Git. It uses an operator in the cluster to trigger deployments inside of Kubernetes. For more information about operators, see https://operatorhub.io/[OperatorHub.io] on GitHub. @@ -114,8 +71,7 @@ For more information about operators, see https://operatorhub.io/[OperatorHub.io [#related-cdk] === CDK for Kubernetes -With the CDK for Kubernetes (cdk8s), you can define Kubernetes apps and components using familiar programming languages. -cdk8s apps synthesize into standard Kubernetes manifests, which can be applied to any Kubernetes cluster. +With the CDK for Kubernetes (cdk8s), you can define Kubernetes apps and components using familiar programming languages. cdk8s apps synthesize into standard Kubernetes manifests, which can be applied to any Kubernetes cluster. @@ -132,8 +88,7 @@ Related networking projects for Amazon EKS and Kubernetes clusters. [#related-vpc-cni-k8s] === Amazon VPC CNI plugin for Kubernetes -Amazon EKS supports native VPC networking through the Amazon VPC CNI plugin for Kubernetes. -The plugin assigns an IP address from your VPC to each Pod. +Amazon EKS supports native VPC networking through the Amazon VPC CNI plugin for Kubernetes. The plugin assigns an IP address from your VPC to each Pod. @@ -144,9 +99,7 @@ The plugin assigns an IP address from your VPC to each Pod. [#related-alb-ingress-controller] === {aws} Load Balancer Controller for Kubernetes -The {aws} Load Balancer Controller helps manage {aws} Elastic Load Balancers for a Kubernetes cluster. -It satisfies Kubernetes Ingress resources by provisioning {aws} Application Load Balancers. -It satisfies Kubernetes service resources by provisioning {aws} Network Load Balancers. +The {aws} Load Balancer Controller helps manage {aws} Elastic Load Balancers for a Kubernetes cluster. It satisfies Kubernetes Ingress resources by provisioning {aws} Application Load Balancers. It satisfies Kubernetes service resources by provisioning {aws} Network Load Balancers. @@ -242,7 +195,7 @@ Prometheus is an open-source systems monitoring and alerting toolkit. [#related-cicd] == Continuous integration / continuous deployment -Related imperative CI/CD projects for Amazon EKS and Kubernetes clusters. +Related CI/CD projects for Amazon EKS and Kubernetes clusters. [#related-jenkinsx] === Jenkins X diff --git a/latest/ug/security/capabilities-security.adoc b/latest/ug/security/capabilities-security.adoc deleted file mode 100644 index 6f5a2de80..000000000 --- a/latest/ug/security/capabilities-security.adoc +++ /dev/null @@ -1,270 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#capabilities-security] -= Security considerations for EKS Capabilities -:info_titleabbrev: Considerations for EKS Capabilities - -[abstract] --- -Plan your EKS Capabilities deployment with security best practices, IAM configuration, and multi-cluster architecture patterns. --- - -This topic covers important security considerations for EKS Capabilities, including IAM role configuration, Kubernetes permissions, and architectural patterns for multi-cluster deployments and cross-account {aws} resource management. - -EKS Capabilities use a combination of IAM roles, EKS access entries, and Kubernetes RBAC to provide secure access to {aws} services, in-cluster Kubernetes resources, and integrations with {aws} CodeConnections, {aws} Secrets Manager, and other {aws} services. - -== Capability IAM role - -When you create a capability, you provide an IAM capability role that EKS uses to perform actions on your behalf. This role must: - -* Be in the same {aws} account as the cluster and capability resource -* Have a trust policy allowing the `capabilities.eks.amazonaws.com` service principal to assume the role -* Have IAM permissions appropriate for the capability type and use case, depending on your requirements. For detailed information about required IAM permissions, see <>, <>, and <> - -It is a best practice to consider the scope of privileges required for your specific use case and grant only those permissions necessary to meet your requirements. -For example, when using the EKS Capability for Kube Resource Orchestrator, no IAM permissions may be required, while when using the EKS Capability for {aws} Controllers for Kubernetes you may grant full access to one or more {aws} services. - - -[IMPORTANT] -==== -While some use cases may warrant the use of broad administrative privileges, follow the principle of least privilege by granting only the minimum IAM permissions required for your specific use case, restricting access to specific resources using ARNs and condition keys rather than using wildcard permissions. -==== - -For detailed information about creating and configuring capability IAM roles, see <>. - -== EKS access entries - -When you create a capability with an IAM role, Amazon EKS automatically creates an access entry for that role on your cluster. -This access entry grants the capability baseline Kubernetes permissions to function. - -[NOTE] -==== -Access entries are created for the cluster where the capability is created. -For Argo CD deployments to remote clusters, you must create access entries on those clusters with appropriate permissions for the Argo CD capability to deploy and manage applications. -==== - -The access entry includes: - -* The IAM role ARN as the principal -* Capability-specific access entry policies that grant baseline Kubernetes permissions -* Appropriate scope (cluster-wide or namespace-scoped) based on the capability type - -[NOTE] -==== -For Argo CD, namespace-scoped permissions are granted to the namespace specified in the capability configuration (defaults to `argocd`). -==== - -**Default access entry policies by capability** - -Each capability type grants the capability role the required permissions, setting different default access entry policies as follows: - -*kro*:: -* `arn:aws:eks::aws:cluster-access-policy/AmazonEKSKROPolicy` (cluster-scoped) -+ -Grants permissions to watch and manage ResourceGraphDefinitions and create instances of custom resources defined by RGDs. - -*ACK*:: -* `arn:aws:eks::aws:cluster-access-policy/AmazonEKSACKPolicy` (cluster-scoped) -+ -Grants permissions to create, read, update, and delete ACK custom resources across all namespaces. - -*Argo CD*:: -* `arn:aws:eks::aws:cluster-access-policy/AmazonEKSArgoCDClusterPolicy` (cluster-scoped) -+ -Grants cluster-level permissions for Argo CD to discover resources and manage cluster-scoped objects. -* `arn:aws:eks::aws:cluster-access-policy/AmazonEKSArgoCDPolicy` (namespace-scoped) -+ -Grants namespace-level permissions for Argo CD to deploy and manage applications. Scoped to the namespace specified in the capability configuration (defaults to `argocd`). - -See <> for more detailed information. - -[#additional-kubernetes-permissions] -== Additional Kubernetes permissions - -Some capabilities may require additional Kubernetes permissions beyond the default access entry policies. You can grant these permissions using either: - -* *Access entry policies*: Associate additional managed policies to the access entry -* *Kubernetes RBAC*: Create `Role` or `ClusterRole` bindings for the capability's Kubernetes user - -**ACK secret reader permissions** - -Some ACK controllers need to read Kubernetes secrets to retrieve sensitive data like database passwords. The following ACK controllers require secret read access: - -* `acm`, `acmpca`, `documentdb`, `memorydb`, `mq`, `rds`, `secretsmanager` - -To grant secret read permissions: - -. Associate the `arn:aws:eks::aws:cluster-access-policy/AmazonEKSSecretReaderPolicy` access entry policy to the capability's access entry -. Scope the policy to specific namespaces where ACK resources will reference secrets, or grant cluster-wide access - -[IMPORTANT] -==== -Secret read permissions are scoped to the namespaces you specify when associating the access entry policy. This allows you to limit which secrets the capability can access. -==== - -[[kro-resource-permissions]] -**kro arbitrary resource permissions** - -kro requires permissions to create and manage the resources defined in your ResourceGraphDefinitions. By default, kro can only watch and manage RGDs themselves. - -To grant kro permissions to create resources: - -*Option 1: Access entry policies* - -Associate pre-defined access entry policies like `AmazonEKSAdminPolicy` or `AmazonEKSEditPolicy` to the capability's access entry. - -*Option 2: Kubernetes RBAC* - -Create a `ClusterRoleBinding` that grants the capability's Kubernetes user the necessary permissions: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: kro-cluster-admin -subjects: -- kind: User - name: arn:aws:sts::111122223333:assumed-role/my-kro-role/kro - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: cluster-admin - apiGroup: rbac.authorization.k8s.io ----- - -[NOTE] -==== -The Kubernetes user name for kro follows the pattern: `arn:aws:sts::ACCOUNT_ID:assumed-role/ROLE_NAME/kro` - -The session name `/kro` is automatically set by the EKS kro capability. -==== - -== IAM permissions required by capability - -*kro (Kube Resource Orchestrator)*:: No IAM permissions required. You can create a capability role with no attached policies. kro only requires Kubernetes RBAC permissions. - -*ACK ({aws} Controllers for Kubernetes)*:: Requires permissions to manage the {aws} resources that ACK will create and manage. You should scope permissions to specific services, actions, and resources based on your requirements. For detailed information about configuring ACK permissions, including production best practices with IAM Role Selectors, see <>. - -*Argo CD*:: No IAM permissions are required by default. Optional permissions may be needed for: -+ -* {aws} Secrets Manager: If storing Git repository credentials in Secrets Manager -* {aws} CodeConnections: If using CodeConnections for Git repository authentication -* Amazon ECR: If using Helm charts stored in OCI format in Amazon ECR - -== Security best practices - -=== IAM least privilege - -Grant your capability resources only the permissions required for your use case. -This does not mean you cannot grant broad administrative permissions to your capabilities if required. -In such cases, you should govern access to those resources appropriately. - -*Capability roles*: - -* *ACK*: When possible, limit IAM permissions to specific {aws} services and resources your teams need, based on use case and requirements -* *Argo CD*: Restrict access to specific Git repositories and Kubernetes namespaces -* *kro*: Requires a capability role for the trust policy, but no IAM permissions are needed (uses cluster RBAC only) - -*Example*: Instead of `"Resource": "*"`, specify patterns for specific resources or groups of resources. - -[source,json] ----- -"Resource": [ - "arn:aws:s3:::my-app-*", - "arn:aws:rds:us-west-2:111122223333:db:prod-*" -] ----- - -Use IAM condition keys to further restrict access: - -[source,json] ----- -"Condition": { - "StringEquals": { - "aws:ResourceTag/Environment": "production" - } -} ----- - -For additional IAM configuration information, see the considerations section for each capability. - -=== Namespace isolation for Argo CD secrets - -The managed Argo CD capability has access to all Kubernetes secrets within its configured namespace (default: `argocd`). -To maintain optimal security posture, follow these namespace isolation practices: - -* Keep only Argo CD-relevant secrets within the Argo CD namespace -* Avoid storing unrelated application secrets in the same namespace as Argo CD -* Use separate namespaces for application secrets that are not required for Argo CD operations - -This isolation ensures that Argo CD's secret access is limited to only the credentials it needs for Git repository authentication and other Argo CD-specific operations. - -=== Kubernetes RBAC - -Control which users and service accounts can create and manage capability resources. -It is a best practice to deploy capability resources in dedicated namespaces with appropriate RBAC policies. - -Example: RBAC Role to work with ACK, allowing for S3 Bucket resource management in the `app-team` namespace: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: ack-s3-manager - namespace: app-team -rules: -- apiGroups: ["s3.services.k8s.aws"] - resources: ["buckets"] - verbs: ["get", "list", "create", "update", "delete"] ----- - -=== Audit logging - -*CloudTrail*: All EKS Capability API operations (create, update, delete) are logged to {aws} CloudTrail. - -Enable CloudTrail logging to track: - -* Who created or modified capabilities -* When capability configurations changed -* What capability roles are in use - -=== Network access and VPC endpoints - -==== Private Argo CD API access - -You can restrict access to the Argo CD API server by associating one or more VPC endpoints with the hosted Argo CD endpoint. -This enables private connectivity to the Argo CD UI and API from within your VPC without traversing the public internet. - -[NOTE] -==== -VPC endpoints connected to hosted Argo CD API endpoints (using eks-capabilities.[.replaceable]``region``.amazonaws.com) do not support VPC endpoint policies. -==== - -==== Deploying to private clusters - -The Argo CD capability can deploy applications to fully private EKS clusters, providing a significant operational benefit by eliminating the need for VPC peering or complex networking configurations. -However, when designing this architecture, consider that Argo CD will pull configuration from Git repositories (which may be public) and apply it to your private clusters. - -Ensure you: - -* Use private Git repositories for sensitive workloads -* Implement proper Git repository access controls and authentication -* Review and approve changes through pull requests before merging -* Consider using Argo CD's sync windows to control when deployments can occur -* Monitor Argo CD audit logs for unauthorized configuration changes - -=== Compliance - -EKS Capabilities are fully managed and have the compliance certifications of Amazon EKS. - -For current compliance information, see https://aws.amazon.com/compliance/services-in-scope/[{aws} Services in Scope by Compliance Program^]. - -== Next steps - -* <> - Configure IAM permissions for ACK -* <> - Configure Kubernetes RBAC for kro -* <> - Configure Identity Center integration for Argo CD -* <> - Troubleshoot security and permission issues \ No newline at end of file diff --git a/latest/ug/security/iam-reference/capability-role.adoc b/latest/ug/security/iam-reference/capability-role.adoc deleted file mode 100644 index e36343271..000000000 --- a/latest/ug/security/iam-reference/capability-role.adoc +++ /dev/null @@ -1,213 +0,0 @@ -include::../../attributes.txt[] - -[.topic] -[#capability-role] -= Amazon EKS capability IAM role -:info_titleabbrev: Capability IAM role - -[abstract] --- -Learn how to create and configure the required {aws} Identity and Access Management role for Amazon EKS capabilities to manage {aws} resources and access Kubernetes resources. --- - -EKS Capabilities require a capability IAM role (or capability role) to be configured. -Capabilities use this role to perform actions on {aws} services and to access Kubernetes resources in your cluster through automatically created access entries. - -Before you can specify a capability role during capability creation, you must create the IAM role with the appropriate trust policy and permissions for the capability type. -Once this IAM role is created, it can be reused for any number of capability resources. - -== Capability role requirements - -The capability role must meet the following requirements: - -* The role must be in the same {aws} account as the cluster and capability resource -* The role must have a trust policy that allows the EKS capabilities service to assume the role -* The role must have permissions appropriate for the capability type and use case requirements (see <>) - -[#capability-trust-policy] -== Trust policy for capability roles - -All capability roles must include the following trust policy: - -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "capabilities.eks.amazonaws.com" - }, - "Action": [ - "sts:AssumeRole", - "sts:TagSession" - ] - } - ] -} ----- - -This trust policy allows EKS to: - -* Assume the role to perform {aws} API operations -* Tag sessions for audit and tracking purposes - -[#capability-permissions] -== Permissions by capability type - -The IAM permissions required depend on which capability you're using and your deployment model. - -[NOTE] -==== -For production deployments using IAM Role Selectors with ACK, or when using kro or Argo CD without {aws} service integration, the Capability Role may not require any IAM permissions beyond the trust policy. -==== - -*kro (Kube Resource Orchestrator)*:: No IAM permissions are required. You can create a capability role with no attached policies. kro only requires Kubernetes RBAC permissions to create and manage Kubernetes resources. - -*{aws} Controllers for Kubernetes (ACK)*:: ACK supports two permission models: -+ -* *Simple setup (development/testing)*: Add {aws} service permissions directly to the Capability Role. This works well for getting started, single-account deployments, or when all users need the same permissions. -+ -* *Production best practice*: Use IAM Role Selectors to implement least-privilege access. With this approach, the Capability Role only needs `sts:AssumeRole` permission to assume service-specific roles. You don't add {aws} service permissions (like S3 or RDS) to the Capability Role itself—those permissions are granted to individual IAM roles that are mapped to specific namespaces. -+ -IAM Role Selectors enable: -+ -** Namespace-level permission isolation -** Cross-account resource management -** Team-specific IAM roles -** Least-privilege security model -+ -Example Capability Role policy for IAM Role Selector approach: -+ -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": [ - "arn:aws:iam::111122223333:role/ACK-S3-Role", - "arn:aws:iam::111122223333:role/ACK-RDS-Role", - "arn:aws:iam::444455556666:role/ACKCrossAccountRole" - ] - } - ] -} ----- -+ -For detailed ACK permission configuration including IAM Role Selectors, see <>. - -*Argo CD*:: No IAM permissions required by default. Optional permissions may be needed for: -+ -* *{aws} Secrets Manager*: If using Secrets Manager to store Git repository credentials -* *{aws} CodeConnections*: If using CodeConnections for Git repository authentication -+ -Example policy for Secrets Manager and CodeConnections: -+ -[source,json,subs="verbatim,attributes"] ----- -{ - "Version": "2012-10-17",{tcx5-waiver} - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "secretsmanager:GetSecretValue", - "secretsmanager:DescribeSecret" - ], - "Resource": "arn:aws:secretsmanager:region:account-id:secret:argocd/*" - }, - { - "Effect": "Allow", - "Action": [ - "codeconnections:UseConnection", - "codeconnections:GetConnection" - ], - "Resource": "arn:aws:codeconnections:region:account-id:connection/*" - } - ] -} ----- -+ -For detailed Argo CD permission requirements, see <>. - - -[#check-capability-role] -== Check for an existing capability role - -You can use the following procedure to check if your account already has a capability IAM role suitable for your use case. - -. Open the IAM console at https://console.aws.amazon.com/iam/. -. In the left navigation pane, choose *Roles*. -. Search the list of roles for your capability role name (for example, `ACKCapabilityRole` or `ArgoCDCapabilityRole`). -. If a role exists, select it to view the attached policies and trust relationship. -. Choose *Trust relationships*, and then choose *Edit trust policy*. -. Verify that the trust relationship matches the <>. If it doesn't match, update the trust policy. -. Choose *Permissions* and verify that the role has the appropriate permissions for your capability type and use case. - -[#create-capability-role] -== Creating a capability IAM role - -You can use the {aws-management-console} or the {aws} CLI to create a capability role. - -**{aws-management-console}**:: -.. Open the IAM console at https://console.aws.amazon.com/iam/. -.. Choose *Roles*, then *Create role*. -.. Under *Trusted entity type*, select *Custom trust policy*. -.. Copy and paste the <> into the trust policy editor. -.. Choose *Next*. -.. On the *Add permissions* tab, select or create policies appropriate for your capability type (see <>). For kro, you can skip this step. -.. Choose *Next*. -.. For *Role name*, enter a unique name for your role, such as `ACKCapabilityRole`, `ArgoCDCapabilityRole`, or `kroCapabilityRole`. -.. For *Description*, enter descriptive text such as `Amazon EKS - ACK capability role`. -.. Choose *Create role*. - -**{aws} CLI**:: -.. Copy the <> to a file named `capability-trust-policy.json`. -.. Create the role. Replace `ACKCapabilityRole` with your desired role name. -+ -[source,bash] ----- -aws iam create-role \ - --role-name ACKCapabilityRole \ - --assume-role-policy-document file://capability-trust-policy.json ----- -.. Attach the required IAM policies to the role. For ACK, attach policies for the {aws} services you want to manage. For Argo CD, attach policies for Secrets Manager or CodeConnections if needed. For kro, you can skip this step. -+ -Example for ACK with S3 permissions: -+ -[source,bash] ----- -aws iam put-role-policy \ - --role-name ACKCapabilityRole \ - --policy-name S3Management \ - --policy-document file://s3-policy.json ----- - -[#troubleshooting-capability-role] -== Troubleshooting capability role issues - -*Capability creation fails with "Invalid IAM role"*:: -Verify that: -+ -* The role exists in the same account as the cluster -* The trust policy matches the <> -* You have `iam:PassRole` permission for the role - -*Capability shows permission errors*:: -Verify that: -+ -* The role has the necessary IAM permissions for the capability type -* The access entry exists on the cluster for the role -* Additional Kubernetes permissions are configured if required (see <>) - -*ACK resources fail with "permission denied" errors*:: -Verify that: -+ -* The role has the necessary IAM permissions for your use case -* For ACK controllers that reference secrets, ensure you've associated the `AmazonEKSSecretReaderPolicy` access entry policy scoped to the appropriate namespaces. - -For more troubleshooting guidance, see <>. \ No newline at end of file diff --git a/latest/ug/security/iam-reference/security-iam.adoc b/latest/ug/security/iam-reference/security-iam.adoc index af938a22f..daeb4f56d 100644 --- a/latest/ug/security/iam-reference/security-iam.adoc +++ b/latest/ug/security/iam-reference/security-iam.adoc @@ -27,11 +27,9 @@ include::auto-cluster-iam-role.adoc[leveloffset=+1] include::auto-create-node-role.adoc[leveloffset=+1] -include::capability-role.adoc[leveloffset=+1] - [abstract] -- -How to authenticate requests and manage access to your Amazon EKS resources. +How to authenticate requests and manage access your Amazon EKS resources. -- {aws} Identity and Access Management (IAM) is an {aws} service that helps an administrator securely control access to {aws} resources. IAM administrators control who can be _authenticated_ (signed in) and _authorized_ (have permissions) to use Amazon EKS resources. IAM is an {aws} service that you can use with no additional charge. diff --git a/latest/ug/security/security.adoc b/latest/ug/security/security.adoc index dcc1d503a..e2e536162 100644 --- a/latest/ug/security/security.adoc +++ b/latest/ug/security/security.adoc @@ -53,6 +53,4 @@ include::security-k8s.adoc[leveloffset=+1] include::auto-security.adoc[leveloffset=+1] -include::capabilities-security.adoc[leveloffset=+1] - include::iam-reference/security-iam.adoc[leveloffset=+1] diff --git a/latest/ug/storage/fsx-csi-tuning-non-efa.adoc b/latest/ug/storage/fsx-csi-tuning-non-efa.adoc index cce905209..ec9904420 100644 --- a/latest/ug/storage/fsx-csi-tuning-non-efa.adoc +++ b/latest/ug/storage/fsx-csi-tuning-non-efa.adoc @@ -32,7 +32,7 @@ The example script defined in this topic performs these operations: === `# 1. Install Lustre client` -* Automatically detects your Amazon Linux (AL) OS version. +* Automatically detects your OS version: Amazon Linux 2 (AL2) or Amazon Linux 2023 (AL2023). * Installs the appropriate Lustre client package. === `# 2. Apply network and RPC tunings` @@ -74,7 +74,7 @@ The example script defined in this topic performs these operations: === `# 8. Setup persistence` * You must adjust the values for your environment in this section as well. -* Automatically detects your OS version (AL2023) to determine which `Systemd` service to apply. +* Automatically detects your OS version (AL2 or AL2023) to determine which `Systemd` service to apply. * System starts. * `Systemd` starts `lustre-tunings` service (due to `WantedBy=multi-user.target`). * Service runs `apply_lustre_tunings.sh` which: diff --git a/latest/ug/versioning/kubernetes-versions-extended.adoc b/latest/ug/versioning/kubernetes-versions-extended.adoc index b9d911c56..c8620934a 100644 --- a/latest/ug/versioning/kubernetes-versions-extended.adoc +++ b/latest/ug/versioning/kubernetes-versions-extended.adoc @@ -14,34 +14,22 @@ Amazon EKS supports Kubernetes versions longer than they are supported upstream, This topic gives important changes to be aware of for each [.noloc]`Kubernetes` version in extended support. When upgrading, carefully review the changes that have occurred between the old and new versions for your cluster. -[#kubernetes-1-31] -== Kubernetes 1.31 +[#kubernetes-1-30] +== Kubernetes 1.30 -Kubernetes `1.31` is now available in Amazon EKS. For more information about Kubernetes `1.31`, see the https://kubernetes.io/blog/2024/08/13/kubernetes-v1-31-release/[official release announcement]. +Kubernetes `1.30` is now available in Amazon EKS. For more information about Kubernetes `1.30`, see the https://kubernetes.io/blog/2024/04/17/kubernetes-v1-30-release/[official release announcement]. [IMPORTANT] ==== -* The kubelet flag `--keep-terminated-pod-volumes` deprecated since 2017 has been removed as part of the version `1.31` release. This change impacts how terminated pod volumes are handled by the kubelet. If you are using this flag in your node configurations, you must update your bootstrap scripts and launch templates to remove it before upgrading. +* Starting with Amazon EKS version `1.30` or newer, any newly created managed node groups will automatically default to using Amazon Linux 2023 (AL2023) as the node operating system. Previously, new node groups would default to Amazon Linux 2 (AL2). You can continue to use AL2 by choosing it as the AMI type when creating a new node group. +** For information about migrating from AL2 to AL2023, see <>. +** For more information about Amazon Linux, see link:linux/al2023/ug/compare-with-al2.html[Comparing AL2 and AL2023,type="documentation"] in the Amazon Linux User Guide. +** For more information about specifiying the operating system for a managed node group, see <>. ==== -* The beta `VolumeAttributesClass` feature gate and API resource is enabled in Amazon EKS version `1.31`. This feature allows cluster operators to modify mutable properties of Persistent Volumes (PVs) managed by compatible CSI Drivers, including the Amazon EBS CSI Driver. To leverage this feature, ensure that your CSI Driver supports the `VolumeAttributesClass` feature (for the Amazon EBS CSI Driver, upgrade to version `1.35.0` or later to automatically enable the feature). You will be able to create `VolumeAttributesClass` objects to define the desired volume attributes, such as volume type and throughput, and associate them with your Persistent Volume Claims (PVCs). See the https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/[official Kubernetes documentation] as well as the documentation of your CSI driver for more information. -** For more information about the Amazon EBS CSI Driver, see <>. -* Kubernetes support for https://apparmor.net/[AppArmor] has graduated to stable and is now generally available for public use. This feature allows you to protect your containers with AppArmor by setting the `appArmorProfile.type` field in the container's `securityContext`. Prior to Kubernetes version `1.30`, AppArmor was controlled by annotations. Starting with version `1.30`, it is controlled using fields. To leverage this feature, we recommend migrating away from annotations and using the `appArmorProfile.type` field to ensure that your workloads are compatible. -* The PersistentVolume last phase transition time feature has graduated to stable and is now generally available for public use in Kubernetes version `1.31`. This feature introduces a new field, `.status.lastTransitionTime`, in the PersistentVolumeStatus, which provides a timestamp of when a PersistentVolume last transitioned to a different phase. This enhancement allows for better tracking and management of PersistentVolumes, particularly in scenarios where understanding the lifecycle of volumes is important. - -For the complete Kubernetes `1.31` changelog, see https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.31.md - - -[#kubernetes-1-30] -== Kubernetes 1.30 - -Kubernetes `1.30` is now available in Amazon EKS. For more information about Kubernetes `1.30`, see the https://kubernetes.io/blog/2024/04/17/kubernetes-v1-30-release/[official release announcement]. - - -* Starting with Amazon EKS version `1.30` or newer, any newly created managed node groups will automatically default to using Amazon Linux 2023 (AL2023) as the node operating system. For more information about specifiying the operating system for a managed node group, see <>. * With Amazon EKS `1.30`, the `topology.k8s.aws/zone-id` label is added to worker nodes. You can use Availability Zone IDs (AZ IDs) to determine the location of resources in one account relative to the resources in another account. For more information, see link:ram/latest/userguide/working-with-az-ids.html[Availability Zone IDs for your {aws} resources,type="documentation"] in the _{aws} RAM User Guide_. * Starting with `1.30`, Amazon EKS no longer includes the `default` annotation on the `gp2 StorageClass` resource applied to newly created clusters. This has no impact if you are referencing this storage class by name. You must take action if you were relying on having a default `StorageClass` in the cluster. You should reference the `StorageClass` by the name `gp2`. Alternatively, you can deploy the Amazon EBS recommended default storage class by setting the `defaultStorageClass.enabled` parameter to true when installing version `1.31.0` or later of the `aws-ebs-csi-driver add-on`. * The minimum required IAM policy for the Amazon EKS cluster IAM role has changed. The action `ec2:DescribeAvailabilityZones` is required. For more information, see <>. @@ -72,3 +60,16 @@ kubectl get cm kube-apiserver-legacy-service-account-token-tracking -n kube-syst ---- For the complete Kubernetes `1.29` changelog, see https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.29.md#changelog-since-v1280. + +[#kubernetes-1-28] +== Kubernetes 1.28 + +Kubernetes `1.28` is now available in Amazon EKS. For more information about Kubernetes `1.28`, see the https://kubernetes.io/blog/2023/08/15/kubernetes-v1-28-release/[official release announcement]. + + + +* Kubernetes `v1.28` expanded the supported skew between core node and control plane components by one minor version, from `n-2` to `n-3`, so that node components (``kubelet`` and `kube-proxy`) for the oldest supported minor version can work with control plane components (``kube-apiserver``, `kube-scheduler`, `kube-controller-manager`, `cloud-controller-manager`) for the newest supported minor version. +* Metrics `force_delete_pods_total` and `force_delete_pod_errors_total` in the `Pod GC Controller` are enhanced to account for all forceful pods deletion. A reason is added to the metric to indicate whether the pod is forcefully deleted because it's terminated, orphaned, terminating with the out-of-service taint, or terminating and unscheduled. +* The `PersistentVolume (PV)` controller has been modified to automatically assign a default `StorageClass` to any unbound `PersistentVolumeClaim` with the `storageClassName` not set. Additionally, the `PersistentVolumeClaim` admission validation mechanism within the API server has been adjusted to allow changing values from an unset state to an actual `StorageClass` name. + +For the complete Kubernetes `1.28` changelog, see https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.28.md#changelog-since-v1270. diff --git a/latest/ug/versioning/kubernetes-versions-standard.adoc b/latest/ug/versioning/kubernetes-versions-standard.adoc index 33e07d4fe..06af6276b 100644 --- a/latest/ug/versioning/kubernetes-versions-standard.adoc +++ b/latest/ug/versioning/kubernetes-versions-standard.adoc @@ -113,5 +113,33 @@ The `public-info-viewer` RBAC role continues to apply for the health check endpo [#al2-ami-deprecation] === Amazon Linux 2 AMI deprecation -Kubernetes version `1.32` is the last version for which Amazon EKS released AL2 AMIs. From version `1.33` onwards, Amazon EKS will continue to release AL2023 and Bottlerocket based AMIs. For more information, see <>. +For Kubernetes versions 1.33 and later, EKS will not provide pre-built optimized Amazon Linux 2 (AL2) Amazon Machine Images (AMIs). +{aws} suggests adopting EKS Auto Mode, or migrating to a more recent operating system, such as Amazon Linux 2023 (AL2023) or Bottlerocket. + +- <> +- <> +- <> + +NOTE: This update applies to EKS-optimized AL2 AMIs. For more information about the operating system itself, see link:amazon-linux-2/faqs/[Amazon Linux 2 FAQs,type="marketing"]. + + +[#kubernetes-1-31] +== Kubernetes 1.31 + +Kubernetes `1.31` is now available in Amazon EKS. For more information about Kubernetes `1.31`, see the https://kubernetes.io/blog/2024/08/13/kubernetes-v1-31-release/[official release announcement]. + +[IMPORTANT] +==== + + +* The kubelet flag `--keep-terminated-pod-volumes` deprecated since 2017 has been removed as part of the version `1.31` release. This change impacts how terminated pod volumes are handled by the kubelet. If you are using this flag in your node configurations, you must update your bootstrap scripts and launch templates to remove it before upgrading. + +==== + +* The beta `VolumeAttributesClass` feature gate and API resource is enabled in Amazon EKS version `1.31`. This feature allows cluster operators to modify mutable properties of Persistent Volumes (PVs) managed by compatible CSI Drivers, including the Amazon EBS CSI Driver. To leverage this feature, ensure that your CSI Driver supports the `VolumeAttributesClass` feature (for the Amazon EBS CSI Driver, upgrade to version `1.35.0` or later to automatically enable the feature). You will be able to create `VolumeAttributesClass` objects to define the desired volume attributes, such as volume type and throughput, and associate them with your Persistent Volume Claims (PVCs). See the https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/[official Kubernetes documentation] as well as the documentation of your CSI driver for more information. +** For more information about the Amazon EBS CSI Driver, see <>. +* Kubernetes support for https://apparmor.net/[AppArmor] has graduated to stable and is now generally available for public use. This feature allows you to protect your containers with AppArmor by setting the `appArmorProfile.type` field in the container's `securityContext`. Prior to Kubernetes version `1.30`, AppArmor was controlled by annotations. Starting with version `1.30`, it is controlled using fields. To leverage this feature, we recommend migrating away from annotations and using the `appArmorProfile.type` field to ensure that your workloads are compatible. +* The PersistentVolume last phase transition time feature has graduated to stable and is now generally available for public use in Kubernetes version `1.31`. This feature introduces a new field, `.status.lastTransitionTime`, in the PersistentVolumeStatus, which provides a timestamp of when a PersistentVolume last transitioned to a different phase. This enhancement allows for better tracking and management of PersistentVolumes, particularly in scenarios where understanding the lifecycle of volumes is important. + +For the complete Kubernetes `1.31` changelog, see https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.31.md diff --git a/latest/ug/versioning/kubernetes-versions.adoc b/latest/ug/versioning/kubernetes-versions.adoc index a112f10a7..8ec407b4f 100644 --- a/latest/ug/versioning/kubernetes-versions.adoc +++ b/latest/ug/versioning/kubernetes-versions.adoc @@ -32,6 +32,7 @@ The following Kubernetes versions are currently available in Amazon EKS standard * `1.34` * `1.33` * `1.32` +* `1.31` For important changes to be aware of for each version in standard support, see link:eks/latest/userguide/kubernetes-versions-standard.html[Kubernetes versions standard support,type="documentation"]. @@ -41,9 +42,9 @@ For important changes to be aware of for each version in standard support, see l The following Kubernetes versions are currently available in Amazon EKS extended support: -* `1.31` * `1.30` * `1.29` +* `1.28` For important changes to be aware of for each version in extended support, see link:eks/latest/userguide/kubernetes-versions-extended.html[Kubernetes versions extended support,type="documentation"]. @@ -108,6 +109,12 @@ https://github.com/awsdocs/amazon-eks-user-guide/commits/mainline/latest/ug/clus |March 23, 2025 |March 23, 2026 +|`1.28` +|August 15, 2023 +|September 26, 2023 +|November 26, 2024 +|November 26, 2025 + |=== [#version-cli] diff --git a/latest/ug/versioning/platform-versions.adoc b/latest/ug/versioning/platform-versions.adoc index ac2a0f5b0..aaf417e9e 100644 --- a/latest/ug/versioning/platform-versions.adoc +++ b/latest/ug/versioning/platform-versions.adoc @@ -51,31 +51,6 @@ The following admission controllers are enabled for all `1.34` platform versions | Release notes | Release date -| `1.34.1` -| `eks.9` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.34.1` -| `eks.8` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.34.1` -| `eks.7` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.34.1` -| `eks.6` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.34.1` -| `eks.5` -| New platform version with security fixes and enhancements. -| October 15, 2025 - | `1.34.1` | `eks.4` | Initial release of Kubernetes version `1.34` for EKS. For more information, see <>. @@ -97,76 +72,6 @@ The following admission controllers are enabled for all `1.33` platform versions | Release notes | Release date -| `1.33.5` -| `eks.23` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.33.5` -| `eks.22` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.33.5` -| `eks.21` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.33.5` -| `eks.20` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.33.5` -| `eks.19` -| New platform version with security fixes and enhancements. -| October 28, 2025 - -| `1.33.5` -| `eks.18` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.33.5` -| `eks.17` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.33.5` -| `eks.16` -| New platform version with security fixes and enhancements. -| October 2, 2025 - -| `1.33.4` -| `eks.15` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.33.4` -| `eks.14` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.33.4` -| `eks.13` -| New platform version with security fixes and enhancements. -| September 16, 2025 - -| `1.33.4` -| `eks.12` -| New platform version with security fixes and enhancements. -| September 5, 2025 - -| `1.33.3` -| `eks.11` -| New platform version with security fixes and enhancements. -| August 25, 2025 - -| `1.33.3` -| `eks.10` -| New platform version with security fixes and enhancements. -| August 17, 2025 - | `1.33.2` | `eks.9` | New platform version with security fixes and enhancements. 1.33 `eks.7` and 1.33 `eks.8` were discarded internally and never released. @@ -202,76 +107,6 @@ The following admission controllers are enabled for all `1.32` platform versions | Release notes | Release date -| `1.32.9` -| `eks.30` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.32.9` -| `eks.29` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.32.9` -| `eks.28` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.32.9` -| `eks.27` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.32.9` -| `eks.26` -| New platform version with security fixes and enhancements. -| October 28, 2025 - -| `1.32.9` -| `eks.25` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.32.9` -| `eks.24` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.32.9` -| `eks.23` -| New platform version with security fixes and enhancements. -| October 2, 2025 - -| `1.32.8` -| `eks.22` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.32.8` -| `eks.21` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.32.8` -| `eks.20` -| New platform version with security fixes and enhancements. -| September 16, 2025 - -| `1.32.8` -| `eks.19` -| New platform version with security fixes and enhancements. -| September 5, 2025 - -| `1.32.7` -| `eks.18` -| New platform version with security fixes and enhancements. -| August 25, 2025 - -| `1.32.7` -| `eks.17` -| New platform version with security fixes and enhancements. -| August 17, 2025 - | `1.32.6` | `eks.16` | New platform version with security fixes and enhancements. 1.32 `eks.14` and 1.32 `eks.15` were discarded internally and never released. @@ -351,76 +186,6 @@ The following admission controllers are enabled for all `1.31` platform versions | Release notes | Release date -| `1.31.13` -| `eks.46` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.31.13` -| `eks.45` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.31.13` -| `eks.44` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.31.13` -| `eks.43` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.31.13` -| `eks.42` -| New platform version with security fixes and enhancements. -| October 28, 2025 - -| `1.31.13` -| `eks.41` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.31.13` -| `eks.40` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.31.13` -| `eks.39` -| New platform version with security fixes and enhancements. -| October 2, 2025 - -| `1.31.12` -| `eks.38` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.31.12` -| `eks.37` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.31.12` -| `eks.36` -| New platform version with security fixes and enhancements. -| September 16, 2025 - -| `1.31.12` -| `eks.35` -| New platform version with security fixes and enhancements. -| September 5, 2025 - -| `1.31.11` -| `eks.34` -| New platform version with security fixes and enhancements. -| August 25, 2025 - -| `1.31.11` -| `eks.33` -| New platform version with security fixes and enhancements. -| August 17, 2025 - | `1.31.10` | `eks.32` | New platform version with security fixes and enhancements. 1.31 `eks.30` and 1.31 `eks.31` were discarded internally and never released. @@ -521,76 +286,6 @@ The following admission controllers are enabled for all `1.30` platform versions | Release notes | Release date -| `1.30.14` -| `eks.54` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.30.14` -| `eks.53` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.30.14` -| `eks.52` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.30.14` -| `eks.51` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.30.14` -| `eks.50` -| New platform version with security fixes and enhancements. -| October 28, 2025 - -| `1.30.14` -| `eks.49` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.30.14` -| `eks.48` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.30.14` -| `eks.47` -| New platform version with security fixes and enhancements. -| October 2, 2025 - -| `1.30.14` -| `eks.46` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.30.14` -| `eks.45` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.30.14` -| `eks.44` -| New platform version with security fixes and enhancements. -| September 16, 2025 - -| `1.30.14` -| `eks.43` -| New platform version with security fixes and enhancements. -| September 5, 2025 - -| `1.30.14` -| `eks.42` -| New platform version with security fixes and enhancements. -| August 25, 2025 - -| `1.30.14` -| `eks.41` -| New platform version with security fixes and enhancements. -| August 17, 2025 - | `1.30.14` | `eks.40` | New platform version with security fixes and enhancements. 1.30 `eks.38` and 1.30 `eks.39` were discarded internally and never released. @@ -725,76 +420,6 @@ The following admission controllers are enabled for all `1.29` platform versions | Release notes | Release date -| `1.29.15` -| `eks.57` -| New platform version with security fixes and enhancements. -| November 18, 2025 - -| `1.29.15` -| `eks.56` -| New platform version with security fixes and enhancements. -| November 17, 2025 - -| `1.29.15` -| `eks.55` -| New platform version with security fixes and enhancements. -| November 6, 2025 - -| `1.29.15` -| `eks.54` -| New platform version with security fixes and enhancements. -| October 30, 2025 - -| `1.29.15` -| `eks.53` -| New platform version with security fixes and enhancements. -| October 28, 2025 - -| `1.29.15` -| `eks.52` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.29.15` -| `eks.51` -| New platform version with security fixes and enhancements. -| October 15, 2025 - -| `1.29.15` -| `eks.50` -| New platform version with security fixes and enhancements. -| October 2, 2025 - -| `1.29.15` -| `eks.49` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.29.15` -| `eks.48` -| New platform version with security fixes and enhancements. -| September 29, 2025 - -| `1.29.15` -| `eks.47` -| New platform version with security fixes and enhancements. -| September 16, 2025 - -| `1.29.15` -| `eks.46` -| New platform version with security fixes and enhancements. -| September 5, 2025 - -| `1.29.15` -| `eks.45` -| New platform version with security fixes and enhancements. -| August 25, 2025 - -| `1.29.15` -| `eks.44` -| New platform version with security fixes and enhancements. -| August 17, 2025 - | `1.29.15` | `eks.43` | New platform version with security fixes and enhancements. 1.29 `eks.41` and 1.29 `eks.42` were discarded internally and never released. @@ -947,7 +572,193 @@ The following admission controllers are enabled for all `1.29` platform versions | January 23, 2024 |=== +[#platform-versions-1-28] +== Kubernetes version `1.28` + +The following admission controllers are enabled for all `1.28` platform versions: `NodeRestriction`, `ExtendedResourceToleration`, `NamespaceLifecycle`, `LimitRanger`, `ServiceAccount`, `TaintNodesByCondition`, `PodSecurity`, `Priority`, `DefaultTolerationSeconds`, `DefaultStorageClass`, `StorageObjectInUseProtection`, `PersistentVolumeClaimResize`, `RuntimeClass`, `CertificateApproval`, `CertificateSigning`, `CertificateSubjectRestriction`, `DefaultIngressClass`, `MutatingAdmissionWebhook`, `ValidatingAdmissionWebhook`, `ResourceQuota`. + +[%header,cols="4"] +|=== +| Kubernetes version +| EKS platform version +| Release notes +| Release date + +| `1.28.15` +| `eks.49` +| New platform version with security fixes and enhancements. 1.28 `eks.47` and 1.28 `eks.48` were discarded internally and never released. +| July 30, 2025 + +| `1.28.15` +| `eks.46` +| New platform version with security fixes and enhancements. +| June 26, 2025 + +| `1.28.15` +| `eks.45` +| New platform version with security fixes and enhancements. +| June 11, 2025 + +| `1.28.15` +| `eks.44` +| New platform version with security fixes and enhancements. +| May 30. 2025 + +| `1.28.15` +| `eks.43` +| New platform version with security fixes and enhancements. +| May 16, 2025 + +| `1.28.15` +| `eks.42` +| New platform version with security fixes and enhancements. +| April 29, 2025 + +| `1.28.15` +| `eks.41` +| New platform version with security fixes and enhancements. +| April 18, 2025 + +| `1.28.15` +| `eks.40` +| New platform version with security fixes and enhancements. +| April 18, 2025 + +| `1.28.15` +| `eks.39` +| New platform version with security fixes and enhancements. +| April 2, 2025 + +| `1.28.15` +| `eks.38` +| New platform version with security fixes and enhancements. +| March 17, 2025 + +| `1.28.15` +| `eks.37` +| New platform version with security fixes and enhancements. +| March 4, 2025 + +| `1.28.15` +| `eks.36` +| New platform version with security fixes and enhancements. +| February 24, 2025 + +| `1.28.15` +| `eks.34` +| New platform version with security fixes and enhancements. +| January 17, 2025 + +| `1.28.15` +| `eks.33` +| New platform version with security fixes and enhancements. +| January 3, 2025 + +| `1.28.15` +| `eks.32` +| New platform version with security fixes and enhancements. +| December 13, 2024 + +| `1.28.15` +| `eks.31` +| New platform version with security fixes and enhancements. +| December 13, 2024 + +| `1.28.15` +| `eks.30` +| New platform version with security fixes and enhancements. +| December 13, 2024 + +| `1.28.15` +| `eks.29` +| New platform version with Amazon EKS Hybrid Nodes support and enhancements to control plane observability. See <> and see link:containers/amazon-eks-enhances-kubernetes-control-plane-observability/[Amazon EKS enhances performance observability,type="blog"], respectively. +| November 15, 2024 + +| `1.28.14` +| `eks.23` +| New platform version with security fixes and enhancements. +| October 21, 2024 + +| `1.28.13` +| `eks.19` +| New platform version with security fixes and enhancements. +| September 3, 2024 +| `1.28.12` +| `eks.18` +| New platform version with security fixes and enhancements. +| August 28, 2024 + +| `1.28.11` +| `eks.17` +| New platform version with security fixes and enhancements. +| August 9, 2024 + +| `1.28.11` +| `eks.16` +| New platform version with security fixes and enhancements. +| July 2, 2024 + +| `1.28.9` +| `eks.13` +| New platform version with CoreDNS autoscaling, security fixes and enhancements. For more information about CoreDNS autoscaling, see <>. +| May 16, 2024 + +| `1.28.8` +| `eks.12` +| New platform version with security fixes and enhancements. +| April 18, 2024 + +| `1.28.7` +| `eks.11` +| New platform version with security fixes and enhancements. +| March 29, 2024 + +| `1.28.7` +| `eks.10` +| New platform version with security fixes and enhancements. +| March 20, 2024 + +| `1.28.6` +| `eks.9` +| New platform version with security fixes and enhancements. +| March 12, 2024 + +| `1.28.5` +| `eks.7` +| New platform version with security fixes and enhancements. +| January 17, 2024 + +| `1.28.4` +| `eks.6` +| New platform version with <>, security fixes and enhancements. +| December 14, 2023 + +| `1.28.4` +| `eks.5` +| New platform version with security fixes and enhancements. +| December 12, 2023 + +| `1.28.3` +| `eks.4` +| New platform version with <>, security fixes and enhancements. +| November 10, 2023 + +| `1.28.3` +| `eks.3` +| New platform version with security fixes and enhancements. +| November 3, 2023 + +| `1.28.2` +| `eks.2` +| New platform version with security fixes and enhancements. +| October 16, 2023 + +| `1.28.1` +| `eks.1` +| Initial release of Kubernetes version `1.28` for EKS. For more information, see <>. +| September 26, 2023 +|=== [#get-platform-version] == Get current platform version diff --git a/latest/ug/what-is/common-use-cases.adoc b/latest/ug/what-is/common-use-cases.adoc index 96cf1c6f9..62a98729e 100644 --- a/latest/ug/what-is/common-use-cases.adoc +++ b/latest/ug/what-is/common-use-cases.adoc @@ -22,9 +22,8 @@ Using link:elasticloadbalancing/[Elastic Load Balancing,type="marketing"], you c Use Kubernetes service discovery features with link:cloud-map/[{aws} Cloud Map,type="marketing"] or link:vpc/lattice/[Amazon VPC Lattice,type="marketing"] to build resilient systems. -*Automating software release processes*:: -Manage continuous integration and continuous deployment (CI/CD) pipelines that simplify the process of automated building, testing, and deployment of applications. -For declarative continuous deployment, see <>. +*Automating software release process*:: +Manage continuous integration and continuous deployment (CICD) pipelines that simplify the process of automated building, testing, and deployment of applications. *Running serverless applications*:: @@ -35,7 +34,7 @@ Use link:fargate/[{aws} Fargate,type="marketing"] with Amazon EKS to run serverl Amazon EKS is compatible with popular machine learning frameworks such as https://www.tensorflow.org/[TensorFlow], https://mxnet.apache.org/[MXNet], and https://pytorch.org/[PyTorch]. With GPU support, you can handle even complex machine learning tasks effectively. -*Deploying consistently on-premises and in the cloud*:: +*Deploying consistently on premises and in the cloud*:: To simplify running Kubernetes in on-premises environments, you can use the same Amazon EKS clusters, features, and tools to run self-managed nodes on <> or can use <> with your own infrastructure. For self-contained, air-gapped environments, you can use link:eks/eks-anywhere/[Amazon EKS Anywhere,type="marketing"] to automate Kubernetes cluster lifecycle management on your own infrastructure. @@ -43,11 +42,5 @@ To simplify running Kubernetes in on-premises environments, you can use the same Utilize link:ec2/spot/[Spot Instances,type="marketing"] to run your batch processing and big data workloads such as link:emr/details/hadoop/what-is-hadoop/[Apache Hadoop,type="marketing"] and link:big-data/what-is-spark/[Spark,type="marketing"], at a fraction of the cost. This lets you take advantage of unused Amazon EC2 capacity at discounted prices. -*Managing {aws} resources from Kubernetes*:: -Use <> to create and manage {aws} resources directly from your Kubernetes cluster using native Kubernetes APIs. - -*Building platform engineering abstractions*:: -Create custom Kubernetes APIs that compose multiple resources into higher-level abstractions using <>. - -*Securing applications and ensuring compliance*:: +*Securing application and ensuring compliance*:: Implement strong security practices and maintain compliance with Amazon EKS, which integrates with {aws} security services such as link:iam/[{aws} Identity and Access Management,type="marketing"] (IAM), link:vpc/[Amazon Virtual Private Cloud,type="marketing"] (Amazon VPC), and link:kms/[{aws} Key Management Service,type="marketing"] ({aws} KMS). This ensures data privacy and protection as per industry standards. \ No newline at end of file diff --git a/latest/ug/what-is/eks-architecture.adoc b/latest/ug/what-is/eks-architecture.adoc index ad2c3482b..6679097ab 100644 --- a/latest/ug/what-is/eks-architecture.adoc +++ b/latest/ug/what-is/eks-architecture.adoc @@ -28,7 +28,7 @@ Amazon EKS actively monitors and adjusts control plane instances to maintain pea *Resilience*:: -If a control plane instance falters, Amazon EKS quickly replaces it, using a different Availability Zone if needed. +If a control plane instance falters, Amazon EKS quickly replaces it, using different Availability Zone if needed. *Consistent uptime*:: @@ -60,26 +60,4 @@ https://karpenter.sh/[Karpenter] is a flexible, high-performance Kubernetes clus <> offer full control over your Amazon EC2 instances within an Amazon EKS cluster. You are in charge of managing, scaling, and maintaining the nodes, giving you total control over the underlying infrastructure. This option is suitable for users who need granular control and customization of their nodes and are ready to invest time in managing and maintaining their infrastructure. *Amazon EKS Hybrid Nodes*:: -With <>, you can use your on-premises and edge infrastructure as nodes in Amazon EKS clusters. Amazon EKS Hybrid Nodes unifies Kubernetes management across environments and offloads Kubernetes control plane management to {aws} for your on-premises and edge applications. - - -[#eks-capabilities] -== EKS Capabilities - -Amazon EKS provides fully managed cluster capabilities, installing and managing Kubernetes APIs (with Kubernetes Custom Resource Definitions) in your cluster while operating controllers and other components in {aws}-owned infrastructure, separate from your cluster. -EKS provides automated patching, scaling, and monitoring of these capabilities, fully managing their lifecycle to reduce the burden of operating in-cluster services for workload orchestration, {aws} resource management, and more. - -EKS provides the following capability types: - -*{aws} Controllers for Kubernetes (ACK)*:: -<> enables you to manage {aws} resources using Kubernetes APIs, allowing you to define S3 buckets, RDS databases, IAM roles, and other {aws} resources as Kubernetes custom resources. -You can manage {aws} resources alongside your Kubernetes workloads using the same tools and workflows, with support for 50+ {aws} services including S3, RDS, DynamoDB, and Lambda. - -*Argo CD*:: -<> implements GitOps-based continuous deployment for your application workloads, {aws} resources, and cluster configuration, using Git repositories as the source of truth. -Argo CD automatically syncs your clusters with your Git repositories and detects drift, continuously reconciling to ensure your deployed applications and resources match your desired state in version control. -You can use Argo CD to manage applications on a given cluster, or deploy and manage applications across multiple clusters from a single Argo CD resource, with automated deployment from Git repositories whenever changes are committed. - -*kro (Kube Resource Orchestrator)*:: -<> 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. -This 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. \ No newline at end of file +With <>, you can use your on-premises and edge infrastructure as nodes in Amazon EKS clusters. Amazon EKS Hybrid Nodes unifies Kubernetes management across environments and offloads Kubernetes control plane management to {aws} for your on-premises and edge applications. \ No newline at end of file diff --git a/latest/ug/what-is/what-is-eks.adoc b/latest/ug/what-is/what-is-eks.adoc index 787012915..401123ef0 100644 --- a/latest/ug/what-is/what-is-eks.adoc +++ b/latest/ug/what-is/what-is-eks.adoc @@ -35,26 +35,9 @@ The following diagram illustrates how Amazon EKS integrates your Kubernetes clus image::images/whatis.png[Amazon EKS standard and EKS Auto Mode,scaledwidth=100%] -Amazon EKS helps you remove friction and accelerate time to production, improve performance, availability and resiliency, and enhance system security. +Amazon EKS helps you accelerate time to production, improve performance, availability and resiliency, and enhance system security. For more information, see https://aws.amazon.com/eks/[Amazon Elastic Kubernetes Service]. - -== Building and scaling with Kubernetes: Amazon EKS Capabilities - -Amazon EKS not only helps you build and manage clusters, it helps you build and scale application systems with Kubernetes. -<> are fully managed cluster services that extend your cluster's functionality with hands-free Kubernetes-native tools, including: - -* **Argo CD**: Argo CD provides declarative, GitOps-based continuous deployment for your workloads, {aws} resources, and cloud infrastructure. - -* **{aws} Controllers for Kubernetes (ACK)**: ACK enables Kubernetes-native creation and lifecycle management of {aws} resources, unifying workload orchestration and Infrastructure-as-code workflows. - -* **kro (Kube Resource Orchestrator)**: kro extends native Kubernetes features to simplify custom resource creation, orchestration, and compositions, giving you the tools to create your own customized cloud building blocks. - -EKS Capabilities are cloud resources that minimize the operational burden of installing, maintaining, and scaling these foundational platform components in your clusters, letting you focus on building software rather than cluster platform operations. - -To learn more, see <>. - - [#eks-features] == Features of Amazon EKS Amazon EKS provides the following high-level features: @@ -86,11 +69,6 @@ Monitoring tools include <>, <>, < and <>. For more information on dashboards, metrics servers, and other tools, see <> and <>. -*Cluster capabilities*:: -EKS provides managed cluster capabilities for continuous deployment, cloud resource management, and resource composition based on open source innovations. -EKS installs Kubernetes APIs in your clusters, but controllers and other components run in EKS and are fully managed, providing automated patching, scaling, and monitoring. -For more information, see <>. - *Kubernetes compatibility and support*:: Amazon EKS is certified Kubernetes-conformant, so you can deploy Kubernetes-compatible applications without refactoring and use Kubernetes community tooling and plugins. @@ -136,7 +114,7 @@ When using Amazon EKS, you pay separately for the {aws} resources you use to run Visit the respective pricing pages of the {aws} services you are using with your Kubernetes applications for detailed pricing information. -* For Amazon EKS cluster, Amazon EKS Auto Mode, Amazon EKS Capabilities, and Amazon EKS Hybrid Nodes pricing, see link:eks/pricing/[Amazon EKS Pricing,type="marketing"]. +* For Amazon EKS cluster, Amazon EKS Auto Mode, and Amazon EKS Hybrid Nodes pricing, see link:eks/pricing/[Amazon EKS Pricing,type="marketing"]. * For Amazon EC2 pricing, see link:ec2/pricing/on-demand/[Amazon EC2 On-Demand Pricing,type="marketing"] and link:ec2/spot/pricing/[Amazon EC2 Spot Pricing,type="marketing"]. * For {aws} Fargate pricing, see link:fargate/pricing[{aws} Fargate Pricing,type="marketing"]. * You can use your savings plans for compute used in Amazon EKS clusters. For more information, see link:savingsplans/pricing/[Pricing with Savings Plans,type="marketing"]. diff --git a/latest/ug/workloads/addons-removed.xml.bak b/latest/ug/workloads/addons-removed.xml.bak new file mode 100644 index 000000000..f5387bf82 --- /dev/null +++ b/latest/ug/workloads/addons-removed.xml.bak @@ -0,0 +1,206 @@ + + + + %xinclude; + + %phrases-shared; + + %phrases-eks; + + ]> + + +
+ + <noloc>Datree Free</noloc> + + + + Publisher &endash; + Datree + + + Name &endash; + datree.engine-free + + + Version &endash; + 1.0.1-rc.1 + + + Namespace &endash; + datree + + + Service account name &endash; A service + account isn't used with this add-on. + + + &AWS; managed &IAM; policy &endash; A + managed policy isn't used with this add-on. + + + Custom &IAM; permissions &endash; Custom + permissions aren't used with this add-on + + + Setup and usage instructions &endash; + None. + + +
+
+ + <noloc>Datree Pro</noloc> + + + + Publisher &endash; + Datree + + + Name &endash; + datree.engine-pro + + + Version &endash; + 1.0.2-rc.1 + + + Namespace &endash; + datree + + + Service account name &endash; TBD. + + + &AWS; managed &IAM; policy &endash; AWSLicenseManagerConsumptionPolicy + + + Command to create required &IAM; role + &endash; The following command requires that you have an &IAM; &OIDClong; + (&OIDC;) provider for your cluster. To determine whether you have one, or to + create one, see . + Replace my-cluster with the name of your cluster + and my-datree-pro-role with the name for your + role. This command requires that you have &eksctl; installed on your device. If you need to use a + different tool to create the role and annotate the &k8s; service account, + see . + eksctl create iamserviceaccount &;#8211;-name tbd &;#8211;-namespace datree &;#8211;-cluster my-cluster &;#8211;-role-name "my-datree-pro-role" \ + &;#8211;-role-only &;#8211;-attach-policy-arn ®ion-arn;iam::aws:policy/service-role/AWSLicenseManagerConsumptionPolicy &;#8211;-approve + + + + Custom &IAM; permissions &endash; Custom + permissions aren't used with this add-on. + + + Setup and usage instructions &endash; + None. + + +
+
+ + <noloc>HAProxy</noloc> + + + + Publisher &endash; TBD + + + Name &endash; TBD + + + Version &endash; TBD + + + Namespace &endash; TBD + + + Service account name &endash; TBD. + + + &AWS; managed &IAM; policy &endash; + TBD + + + Custom &IAM; permissions &endash; + TBD + + + Setup and usage instructions &endash; + TBD. + + +
+
+ + <noloc>Kyverno Enterprise</noloc> + + + + Publisher &endash; + Nirmata + + + Name &endash; + nirmata_kyverno + + + Namespace &endash; + kyverno + + + Service account name &endash; + kyverno + + + &AWS; managed &IAM; policy &endash; + AWSLicenseManagerConsumptionPolicy + + + Command to create required &IAM; role + &endash; The following command requires that you have an &IAM; + &OIDClong; (&OIDC;) provider for your cluster. To determine whether you + have one, or to create one, see . Replace + my-cluster with the name of your cluster + and my-kyverno-role with the name for your + role. This command requires that you have &eksctl; installed on your device. If you need to + use a different tool to create the role and annotate the &k8s; service + account, see . + eksctl create iamserviceaccount --name kyverno --namespace kyverno --cluster my-cluster --role-name my-kyverno-role \ + --role-only --attach-policy-arn ®ion-arn;iam::aws:policy/service-role/AWSLicenseManagerConsumptionPolicy --approve + + + + Custom &IAM; permissions &endash; + Custom permissions aren't used with this add-on. + + + Setup and usage instructions &endash; + See Nirmata Kyverno + Enterprise in the Nirmata + documenation. + + +
+ + + \ No newline at end of file diff --git a/latest/ug/workloads/workloads-add-ons-available-eks.adoc b/latest/ug/workloads/workloads-add-ons-available-eks.adoc index f0385a7e9..4e97cfa30 100644 --- a/latest/ug/workloads/workloads-add-ons-available-eks.adoc +++ b/latest/ug/workloads/workloads-add-ons-available-eks.adoc @@ -7,10 +7,10 @@ include::../attributes.txt[] [abstract] -- -Learn about the available Amazon EKS add-ons from {aws}. +Learn about the availabe Amazon EKS add-ons from {aws}. -- -The following Amazon EKS add-ons are available to create on your cluster. You can view the most current list of available add-ons using `eksctl`, the {aws-management-console}, or the {aws} CLI. To see all available add-ons or to install an add-on, see <>. If an add-on requires IAM permissions, then you must have an IAM OpenID Connect (OIDC) provider for your cluster. To determine whether you have one, or to create one, see <>. You can create or delete an add-on after you've installed it. For more information, see <> or <>. For more information about considerations specific to running EKS add-ons with Amazon EKS Hybrid Nodes, see <>. +The following Amazon EKS add-ons are available to create on your cluster. You can view the most current list of available add-ons using `eksctl`, the {aws-management-console}, or the {aws} CLI. To see all available add-ons or to install an add-on, see <>. If an add-on requires IAM permissions, then you must have an IAM OpenID Connect (OIDC) provider for your cluster. To determine whether you have one, or to create one, see <>. You can an create or delete an add-on after you've installed it. For more information, see <> or <>. For more information about considerations specific to running EKS add-ons with Amazon EKS Hybrid Nodes, see <>. You can use any of the following Amazon EKS add-ons. @@ -457,7 +457,7 @@ The operator also works with HyperPod's health monitoring and observability func The Amazon EKS add-on name is `amazon-sagemaker-hyperpod-training-operator`. -For more information, see link:sagemaker/latest/dg/sagemaker-eks-operator.html[Using the HyperPod training operator,type="documentation"] in the _Amazon SageMaker Developer Guide_. +For more information, see link:sagemaker/latest/dg/sagemaker-eks-operator.html[Using the HyperPod training operatorr,type="documentation"] in the _Amazon SageMaker Developer Guide_. === Required IAM permissions diff --git a/vale/styles/EksDocs/ExternalDomains.yml b/vale/styles/EksDocs/ExternalDomains.yml index 261ce5c5c..73dd0b766 100644 --- a/vale/styles/EksDocs/ExternalDomains.yml +++ b/vale/styles/EksDocs/ExternalDomains.yml @@ -13,13 +13,11 @@ exceptions: - anywhere.eks.amazonaws.com - apparmor.net - appdynamics.com - - argo-cd.readthedocs.io - aws-ia.github.io - aws-observability.github.io - aws-otel.github.io - aws.amazon.com - aws.github.io - - aws-controllers-k8s.github.io - awsdocs-neuron.readthedocs-hosted.com - awslabs.github.io - boto3.amazonaws.com @@ -66,7 +64,6 @@ exceptions: - github.com - grafana.com - guide.kubecost.com - - https://argo-cd.readthedocs.io - http://developers.eksworkshop.com - http://192.0.2.4:3128 - http://localhost:8080/utility/stress/1000000 @@ -76,7 +73,6 @@ exceptions: - https://amazon-eks.s3.us-west-2.amazonaws.com/eks-connector/ - https://antrea.io/docs/main/docs/eks-installation - https://anywhere.eks.amazonaws.com - - https://aws-controllers-k8s.github.io - https://aws-ia.github.io - https://aws-observability.github.io/ - https://aws.github.io/ @@ -139,7 +135,6 @@ exceptions: - https://karpenter.sh - https://kind.sigs.k8s.io - https://kong.github.io/aws-marketplace-addon-kong-gateway/ - - https://kro.run - https://kubernetes-sigs.github.io/ - https://kubernetes.io - https://marketplace.visualstudio.com/ @@ -186,7 +181,6 @@ exceptions: - huggingface.co - k8s.io - karpenter.sh - - kro.run - kubernetes-csi.github.io - kubernetes.io - learn.microsoft.com @@ -224,4 +218,4 @@ exceptions: - sdk.amazonaws.com - efa-installer.amazonaws.com - amazon-eks.s3.amazonaws.com - - amazon-eks-docs.s3.amazonaws.com + - amazon-eks-docs.s3.amazonaws.com \ No newline at end of file