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/Config b/Config index 97e3e3525..c9664a2d8 100755 --- a/Config +++ b/Config @@ -24,7 +24,7 @@ package.AmazonEKSDocs = { AWSEC2ContainerChecklist = 1.0; AWSDevDocsQuotasShare = 1.0; AWSDocsSdkExamplesPublic = 1.0; - ZonBook = 5.1; + ZonBook = 5.0; AWSDevDocsChecklistBJS = 2.0; }; }; 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-change.adoc b/latest/ug/automode/auto-change.adoc index dcc074a4b..f0393ff5c 100644 --- a/latest/ug/automode/auto-change.adoc +++ b/latest/ug/automode/auto-change.adoc @@ -95,7 +95,3 @@ DRA is not currently supported by EKS Auto Mode. == March 14, 2025 **Feature**: `IPv4` egress enabled in `IPv6` clusters. `IPv4` traffic egressing from `IPv6` Auto Mode clusters will now be automatically translated to the `v4` address of the node primary ENI. - -== November 19, 2025 - -**Feature**: Supports static-capacity node pools that maintain a fixed number of nodes. \ No newline at end of file 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-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/automode/auto-static-capacity.adoc b/latest/ug/automode/auto-static-capacity.adoc deleted file mode 100644 index a55a1f243..000000000 --- a/latest/ug/automode/auto-static-capacity.adoc +++ /dev/null @@ -1,256 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#auto-static-capacity] -= Static-Capacity Node Pools in EKS Auto Mode -:info_titleabbrev: Static-capacity node pools - -Amazon EKS Auto Mode supports static-capacity node pools that maintain a fixed number of nodes regardless of pod demand. Static-capacity node pools are useful for workloads that require predictable capacity, reserved instances, or specific compliance requirements where you need to maintain a consistent infrastructure footprint. - -Unlike dynamic node pools that scale based on pod scheduling demands, static-capacity node pools maintain the number of nodes that you have configured. - -== Basic example - -Here's a simple static-capacity node pool that maintains 5 nodes: - -[source,yaml] ----- -apiVersion: karpenter.sh/v1 -kind: NodePool -metadata: - name: my-static-nodepool -spec: - replicas: 5 # Maintain exactly 5 nodes - - template: - spec: - nodeClassRef: - group: eks.amazonaws.com - kind: NodeClass - name: default - - requirements: - - key: "eks.amazonaws.com/instance-category" - operator: In - values: ["m", "c"] - - key: "topology.kubernetes.io/zone" - operator: In - values: ["us-west-2a", "us-west-2b"] - - limits: - nodes: 8 ----- - -== Configure a static-capacity node pool - -To create a static-capacity node pool, set the `replicas` field in your NodePool specification. The `replicas` field defines the exact number of nodes that the node pool will maintain. - -== Static-capacity node pool constraints - -Static-capacity node pools have several important constraints and behaviors: - -**Configuration constraints:** - -* **Cannot switch modes**: Once you set `replicas` on a node pool, you cannot remove it. The node pool cannot switch between static and dynamic modes. -* **Limited resource limits**: Only the `limits.nodes` field is supported in the limits section. CPU and memory limits are not applicable. -* **No weight field**: The `weight` field cannot be set on static-capacity node pools since node selection is not based on priority. - -**Operational behavior:** - -* **No consolidation**: Nodes in static-capacity pools are not considered for consolidation based on utilization. -* **Scaling operations**: Scale operations bypass node disruption budgets but still respect PodDisruptionBudgets. -* **Node replacement**: Nodes are still replaced for drift (such as AMI updates) and expiration based on your configuration. - -== Scale a static-capacity node pool - -You can change the number of replicas in a static-capacity node pool using the `kubectl scale` command: - -[source,bash] ----- -# Scale down to 5 nodes -kubectl scale nodepool static-nodepool --replicas=5 ----- - -When scaling down, EKS Auto Mode will terminate nodes gracefully, respecting PodDisruptionBudgets and allowing running pods to be rescheduled to remaining nodes. - -== Monitor static-capacity node pools - -Use the following commands to monitor your static-capacity node pools: - -[source,bash] ----- -# View node pool status -kubectl get nodepool static-nodepool - -# Get detailed information including current node count -kubectl describe nodepool static-nodepool - -# Check the current number of nodes -kubectl get nodepool static-nodepool -o jsonpath='{.status.nodes}' ----- - -The `status.nodes` field shows the current number of nodes managed by the node pool, which should match your desired `replicas` count under normal conditions. - -== Example configurations - -=== Basic static-capacity node pool - -[source,yaml] ----- -apiVersion: karpenter.sh/v1 -kind: NodePool -metadata: - name: basic-static -spec: - replicas: 5 - - template: - spec: - nodeClassRef: - group: eks.amazonaws.com - kind: NodeClass - name: default - - requirements: - - key: "eks.amazonaws.com/instance-category" - operator: In - values: ["m"] - - key: "topology.kubernetes.io/zone" - operator: In - values: ["us-west-2a"] - - limits: - nodes: 8 # Allow scaling up to 8 during operations ----- - -=== Static-capacity with specific instance types - -[source,yaml] ----- -apiVersion: karpenter.sh/v1 -kind: NodePool -metadata: - name: reserved-instances -spec: - replicas: 20 - - template: - metadata: - labels: - instance-type: reserved - cost-center: production - spec: - nodeClassRef: - group: eks.amazonaws.com - kind: NodeClass - name: default - - requirements: - - key: "node.kubernetes.io/instance-type" - operator: In - values: ["m5.2xlarge"] # Specific instance type - - key: "karpenter.sh/capacity-type" - operator: In - values: ["on-demand"] - - key: "topology.kubernetes.io/zone" - operator: In - values: ["us-west-2a", "us-west-2b", "us-west-2c"] - - limits: - nodes: 25 - - disruption: - # Conservative disruption for production workloads - budgets: - - nodes: 10% ----- - -=== Multi-zone static-capacity node pool - -[source,yaml] ----- -apiVersion: karpenter.sh/v1 -kind: NodePool -metadata: - name: multi-zone-static -spec: - replicas: 12 # Will be distributed across specified zones - - template: - metadata: - labels: - availability: high - spec: - nodeClassRef: - group: eks.amazonaws.com - kind: NodeClass - name: default - - requirements: - - key: "eks.amazonaws.com/instance-category" - operator: In - values: ["c", "m"] - - key: "eks.amazonaws.com/instance-cpu" - operator: In - values: ["8", "16"] - - key: "topology.kubernetes.io/zone" - operator: In - values: ["us-west-2a", "us-west-2b", "us-west-2c"] - - key: "karpenter.sh/capacity-type" - operator: In - values: ["on-demand"] - - limits: - nodes: 15 - - disruption: - budgets: - - nodes: 25% ----- - -== Best practices - -**Capacity planning:** - -* Set `limits.nodes` higher than `replicas` to allow for temporary scaling during node replacement operations. -* Consider the maximum capacity needed during node drift or AMI updates when setting limits. - -**Instance selection:** - -* Use specific instance types when you have Reserved Instances or specific hardware requirements. -* Avoid overly restrictive requirements that might limit instance availability during scaling. - -**Disruption management:** - -* Configure appropriate disruption budgets to balance availability with maintenance operations. -* Consider your application's tolerance for node replacement when setting budget percentages. - -**Monitoring:** - -* Regularly monitor the `status.nodes` field to ensure your desired capacity is maintained. -* Set up alerts for when the actual node count deviates from the desired replicas. - -**Zone distribution:** - -* For high availability, spread static capacity across multiple Availability Zones. -* When you create a static-capacity node pool that spans multiple availability zones, EKS Auto Mode distributes the nodes across the specified zones, but the distribution is not guaranteed to be even. -* For predictable and even distribution across availability zones, create separate static-capacity node pools, each pinned to a specific availability zone using the `topology.kubernetes.io/zone` requirement. -* If you need 12 nodes evenly distributed across three zones, create three node pools with 4 replicas each, rather than one node pool with 12 replicas across three zones. - -== Troubleshooting - -**Nodes not reaching desired replicas:** - -* Check if the `limits.nodes` value is sufficient -* Verify that your requirements don't overly constrain instance selection -* Review {aws} service quotas for the instance types and regions you're using - -**Node replacement taking too long:** - -* Adjust disruption budgets to allow more concurrent replacements -* Check if PodDisruptionBudgets are preventing node termination - -**Unexpected node termination:** - -* Review the `expireAfter` and `terminationGracePeriod` settings -* Check for manual node terminations or {aws} maintenance events diff --git a/latest/ug/automode/settings-auto.adoc b/latest/ug/automode/settings-auto.adoc index 832a8e621..ff13eb864 100644 --- a/latest/ug/automode/settings-auto.adoc +++ b/latest/ug/automode/settings-auto.adoc @@ -44,16 +44,6 @@ a| - Set resource limits for CPU and memory usage |<> -a| -*Static-capacity node pools* - -- Maintain a fixed number of nodes regardless of pod demand -- Configure predictable capacity for reserved instances -- Set specific replica counts for consistent infrastructure footprint -- Scale static node pools manually -- Monitor static-capacity node pool status -|<> - a| *Application Load Balancer settings* @@ -109,8 +99,6 @@ include::create-node-class.adoc[leveloffset=+1] include::create-node-pool.adoc[leveloffset=+1] -include::auto-static-capacity.adoc[leveloffset=+1] - include::auto-configure-alb.adoc[leveloffset=+1] include::auto-configure-nlb.adoc[leveloffset=+1] diff --git a/latest/ug/book.adoc b/latest/ug/book.adoc index 260a4825a..19abdd4c7 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] @@ -74,8 +72,6 @@ include::outposts/eks-outposts.adoc[leveloffset=+1] include::ml/machine-learning-on-eks.adoc[leveloffset=+1] -include::tools/eks-tools.adoc[leveloffset=+1] - include::versioning/versioning.adoc[leveloffset=+1] include::troubleshooting/troubleshooting.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..fe7455d7e 100644 --- a/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc +++ b/latest/ug/cluster-management/cost-monitoring-kubecost-view-dashboard.adoc @@ -19,19 +19,10 @@ kubectl get pods --namespace kubecost . On your device, enable port-forwarding to expose the Kubecost dashboard. + -* If kubecost is installed using helm: -+ [source,bash,subs="verbatim,attributes"] ---- kubectl port-forward deployment/kubecost-cost-analyzer 9090 --namespace kubecost ---- - -* If kubecost is installed using Amazon EKS add-on: -+ -[source,bash,subs="verbatim,attributes"] ----- -kubectl port-forward deployment/cost-analyzer 9090 --namespace kubecost ----- + Alternatively, you can use the <> to expose Kubecost and use Amazon Cognito for authentication, authorization, and user management. For more information, see link:containers/how-to-use-application-load-balancer-and-amazon-cognito-to-authenticate-users-for-your-kubernetes-web-apps[How to use Application Load Balancer and Amazon Cognito to authenticate users for your Kubernetes web apps,type="blog"]. . On the same device that you completed the previous step on, open a web browser and enter the following address. diff --git a/latest/ug/clusters/clusters.adoc b/latest/ug/clusters/clusters.adoc index 21ec055ce..4f2d06ae3 100644 --- a/latest/ug/clusters/clusters.adoc +++ b/latest/ug/clusters/clusters.adoc @@ -14,8 +14,6 @@ include::create-cluster-auto.adoc[leveloffset=+1] include::create-cluster.adoc[leveloffset=+1] -include::eks-provisioned-control-plane-introduction.adoc[leveloffset=+1] - include::cluster-insights.adoc[leveloffset=+1] include::update-cluster.adoc[leveloffset=+1] diff --git a/latest/ug/clusters/create-cluster-auto.adoc b/latest/ug/clusters/create-cluster-auto.adoc index 3c22ada26..385a91411 100644 --- a/latest/ug/clusters/create-cluster-auto.adoc +++ b/latest/ug/clusters/create-cluster-auto.adoc @@ -106,7 +106,7 @@ When you're done with this page, choose *Next*. ** When you're done with this page, choose *Next*. . On the *Configure selected add-ons settings* page, select the version that you want to install. You can always update to a later version after cluster creation. + -For add-ons that support EKS Pod Identities, you can use the console to automatically generate the role with the name, {aws} managed policy, and trust policy prepopulated specifically for the add-on. You can re-use existing roles or create new roles for supported add-ons. For the steps to use the console to create roles for add-ons that support EKS Pod Identities, see <>. If an add-on does not support EKS Pod Identity, a message displays with instructions to use the wizard to create the IAM roles for service accounts (IRSA) after the cluster is created. +For add-ons that support EKS Pod Identities, you can use the console to automatically generate the role with the name, {aws} managed policy, and trust policy prepopulated specifically for the add-on. You can re-use existing roles or create new roles for supported add-ons. For the steps to use the console to create roles for add-ons that support EKS Pod Identities, see <<_create_add_on_console>>. If an add-on does not support EKS Pod Identity, a message displays with instructions to use the wizard to create the IAM roles for service accounts (IRSA) after the cluster is created. + You can update the configuration of each add-on after cluster creation. For more information about configuring add-ons, see <>. When you're done with this page, choose *Next*. . On the *Review and create* page, review the information that you entered or selected on the previous pages. If you need to make changes, choose *Edit*. When you're satisfied, choose *Create*. The *Status* field shows *CREATING* while the cluster is provisioned. @@ -311,4 +311,4 @@ aws eks describe-cluster --region region-code --name my-cluster --query "cluster * <> * <>. * <>. -* <>. +* <>. \ No newline at end of file diff --git a/latest/ug/clusters/create-cluster.adoc b/latest/ug/clusters/create-cluster.adoc index 339c52f8a..8527e0b9e 100644 --- a/latest/ug/clusters/create-cluster.adoc +++ b/latest/ug/clusters/create-cluster.adoc @@ -12,7 +12,7 @@ Learn how to create an Amazon EKS cluster to run Kubernetes applications, includ [NOTE] ==== -This topic covers creating Amazon EKS clusters without EKS Auto Mode. +This topic covers creating EKS clusters without EKS Auto Mode. For detailed instructions on creating an EKS Auto Mode cluster, see <>. @@ -189,7 +189,7 @@ When you're done with this page, choose *Next*. Some add-ons, such as Amazon VPC CNI, CoreDNS, and kube-proxy, are installed by default. If you disable any of the default add-ons, this may affect your ability to run Kubernetes applications. . On the *Configure selected add-ons settings* page, select the version that you want to install. You can always update to a later version after cluster creation. + -For add-ons that support EKS Pod Identities, you can use the console to automatically generate the role with the name, {aws} managed policy, and trust policy prepopulated specifically for the add-on. You can re-use existing roles or create new roles for supported add-ons. For the steps to use the console to create roles for add-ons that support EKS Pod Identities, see <>. If an add-on does not support EKS Pod Identity, a message displays with instructions to use the wizard to create the IAM roles for service accounts (IRSA) after the cluster is created. +For add-ons that support EKS Pod Identities, you can use the console to automatically generate the role with the name, {aws} managed policy, and trust policy prepopulated specifically for the add-on. You can re-use existing roles or create new roles for supported add-ons. For the steps to use the console to create roles for add-ons that support EKS Pod Identities, see <<_create_add_on_console>>. If an add-on does not support EKS Pod Identity, a message displays with instructions to use the wizard to create the IAM roles for service accounts (IRSA) after the cluster is created. + You can update the configuration of each add-on after cluster creation. For more information about configuring add-ons, see <>. When you're done with this page, choose *Next*. . On the *Review and create* page, review the information that you entered or selected on the previous pages. If you need to make changes, choose *Edit*. When you're satisfied, choose *Create*. The *Status* field shows *CREATING* while the cluster is provisioned. diff --git a/latest/ug/clusters/eks-provisioned-control-plane-getting-started.adoc b/latest/ug/clusters/eks-provisioned-control-plane-getting-started.adoc deleted file mode 100644 index c673061dd..000000000 --- a/latest/ug/clusters/eks-provisioned-control-plane-getting-started.adoc +++ /dev/null @@ -1,311 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-provisioned-control-plane-getting-started] -= Getting started with the Amazon EKS Provisioned Control Plane -:info_titleabbrev: Getting started with Provisioned Control Plane - -[abstract] --- -Learn how to create and manage Amazon EKS clusters with Provisioned Control Plane using the {aws} CLI and {aws-management-console}. --- - -This guide walks you through the steps to set up and use EKS Provisioned Control Plane using {aws} CLI and {aws-management-console}. - -== Prerequisites - -Before you begin, ensure you have: - -* *{aws} CLI* – A command line tool for working with {aws} services, including Amazon EKS. For more information, see link:cli/latest/userguide/cli-chap-install.html[Installing,type="documentation"] in the _{aws} Command Line Interface User Guide_. After installing the {aws} CLI, we recommend that you also configure it. For more information, see link:cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config[Quick configuration with aws configure,type="documentation"] in the _{aws} Command Line Interface User Guide_. Note that {aws} CLI v2 is required to use the *update-kubeconfig* option shown in this page. -* *Required IAM permissions* – The IAM security principal that you're using must have permissions to work with Amazon EKS IAM roles, service linked roles, {aws} CloudFormation, a VPC, and related resources. For more information, see link:service-authorization/latest/reference/list_amazonelastickubernetesservice.html[Actions,type="documentation"] and link:IAM/latest/UserGuide/using-service-linked-roles.html[Using service-linked roles,type="documentation"] in the _IAM User Guide_. You must complete all steps in this guide as the same user. To check the current user, run the following command: -+ -[source,bash] ----- -aws sts get-caller-identity ----- - -NOTE: We recommend that you complete the steps in this topic in a Bash shell. If you aren't using a Bash shell, some script commands such as line continuation characters and the way variables are set and used require adjustment for your shell. Additionally, the quoting and escaping rules for your shell might be different. For more information, see link:cli/latest/userguide/cli-usage-parameters-quoting-strings.html[Using quotation marks with strings in the {aws} CLI,type="documentation"] in the _{aws} Command Line Interface User Guide_. - -== EKS Provisioned Control Plane - {aws} CLI - -=== Create cluster with EKS Provisioned Control Plane Scaling Tier - -[source,bash] ----- -aws eks create-cluster --name prod-cluster \ ---role-arn arn:aws:iam::012345678910:role/eks-service-role-AWSServiceRoleForAmazonEKS-J7ONKE3BQ4PI \ ---resources-vpc-config subnetIds=subnet-6782e71e,subnet-e7e761ac,securityGroupIds=sg-6979fe18 \ ---control-plane-scaling-config tier=tier-xl ----- - -Response: - -[source,json] ----- -{ - "cluster": { - "name": "my-eks-cluster", - "arn": "arn:aws:eks:us-east-2:111122223333:cluster/my-eks-cluster", - "createdAt": "2024-03-14T11:31:44.348000-04:00", - "version": "1.26", - "endpoint": "https://JSA79429HJDASKJDJ8223829MNDNASW.yl4.us-east-2.eks.amazonaws.com", - "roleArn": "arn:aws:iam::111122223333:role/eksctl-my-eks-cluster-cluster-ServiceRole-zMF6CBakwwbW", - "resourcesVpcConfig": { - "subnetIds": [ - "subnet-0fb75d2d8401716e7", - "subnet-02184492f67a3d0f9", - "subnet-04098063527aab776", - "subnet-0e2907431c9988b72", - "subnet-04ad87f71c6e5ab4d", - "subnet-09d912bb63ef21b9a" - ], - "securityGroupIds": [ - "sg-0c1327f6270afbb36" - ], - "clusterSecurityGroupId": "sg-01c84d09d70f39a7f", - "vpcId": "vpc-0012b8e1cc0abb17d", - "endpointPublicAccess": true, - "endpointPrivateAccess": true, - "publicAccessCidrs": [ - "22.19.18.2/32" - ] - }, - "controlPlaneScalingConfig": { - "tier": "tier-xl" - }, - "kubernetesNetworkConfig": { - "serviceIpv4Cidr": "10.100.0.0/16", - "ipFamily": "ipv4" - }, - "logging": { - "clusterLogging": [ - { - "types": [ - "api", - "audit", - "authenticator", - "controllerManager", - "scheduler" - ], - "enabled": true - } - ] - }, - "identity": { - "oidc": { - "issuer": "https://oidc.eks.us-east-2.amazonaws.com/id/JSA79429HJDASKJDJ8223829MNDNASW" - } - }, - "status": "CREATING", - "certificateAuthority": { - "data": "CA_DATA_STRING..." - }, - "platformVersion": "eks.14", - "tags": { - "aws:cloudformation:stack-name": "eksctl-my-eks-cluster-cluster", - "alpha.eksctl.io/cluster-name": "my-eks-cluster", - "karpenter.sh/discovery": "my-eks-cluster", - "aws:cloudformation:stack-id": "arn:aws:cloudformation:us-east-2:111122223333:stack/eksctl-my-eks-cluster-cluster/e752ea00-e217-11ee-beae-0a9599c8c7ed", - "auto-delete": "no", - "eksctl.cluster.k8s.io/v1alpha1/cluster-name": "my-eks-cluster", - "EKS-Cluster-Name": "my-eks-cluster", - "alpha.eksctl.io/cluster-oidc-enabled": "true", - "aws:cloudformation:logical-id": "ControlPlane", - "alpha.eksctl.io/eksctl-version": "0.173.0-dev+a7ee89342.2024-03-01T03:40:57Z", - "Name": "eksctl-my-eks-cluster-cluster/ControlPlane" - }, - "health": { - "issues": [] - }, - "accessConfig": { - "authenticationMode": "API_AND_CONFIG_MAP" - } - } -} ----- - -=== View cluster's Control Plane Scaling Tier - -[source,bash] ----- -aws eks describe-cluster --name prod-cluster ----- - -Response: - -[source,json] ----- -{ - "cluster": { - "name": "my-eks-cluster", - "arn": "arn:aws:eks:us-east-2:111122223333:cluster/my-eks-cluster", - "createdAt": "2024-03-14T11:31:44.348000-04:00", - "version": "1.26", - "endpoint": "https://JSA79429HJDASKJDJ8223829MNDNASW.yl4.us-east-2.eks.amazonaws.com", - "roleArn": "arn:aws:iam::111122223333:role/eksctl-my-eks-cluster-cluster-ServiceRole-zMF6CBakwwbW", - "resourcesVpcConfig": { - "subnetIds": [ - "subnet-0fb75d2d8401716e7", - "subnet-02184492f67a3d0f9", - "subnet-04098063527aab776", - "subnet-0e2907431c9988b72", - "subnet-04ad87f71c6e5ab4d", - "subnet-09d912bb63ef21b9a" - ], - "securityGroupIds": [ - "sg-0c1327f6270afbb36" - ], - "clusterSecurityGroupId": "sg-01c84d09d70f39a7f", - "vpcId": "vpc-0012b8e1cc0abb17d", - "endpointPublicAccess": true, - "endpointPrivateAccess": true, - "publicAccessCidrs": [ - "22.19.18.2/32" - ] - }, - "controlPlaneScalingConfig": { - "tier": "tier-xl" - }, - "kubernetesNetworkConfig": { - "serviceIpv4Cidr": "10.100.0.0/16", - "ipFamily": "ipv4" - }, - "logging": { - "clusterLogging": [ - { - "types": [ - "api", - "audit", - "authenticator", - "controllerManager", - "scheduler" - ], - "enabled": true - } - ] - }, - "identity": { - "oidc": { - "issuer": "https://oidc.eks.us-east-2.amazonaws.com/id/JSA79429HJDASKJDJ8223829MNDNASW" - } - }, - "status": "ACTIVE", - "certificateAuthority": { - "data": "CA_DATA_STRING..." - }, - "platformVersion": "eks.14", - "tags": { - "aws:cloudformation:stack-name": "eksctl-my-eks-cluster-cluster", - "alpha.eksctl.io/cluster-name": "my-eks-cluster", - "karpenter.sh/discovery": "my-eks-cluster", - "aws:cloudformation:stack-id": "arn:aws:cloudformation:us-east-2:111122223333:stack/eksctl-my-eks-cluster-cluster/e752ea00-e217-11ee-beae-0a9599c8c7ed", - "auto-delete": "no", - "eksctl.cluster.k8s.io/v1alpha1/cluster-name": "my-eks-cluster", - "EKS-Cluster-Name": "my-eks-cluster", - "alpha.eksctl.io/cluster-oidc-enabled": "true", - "aws:cloudformation:logical-id": "ControlPlane", - "alpha.eksctl.io/eksctl-version": "0.173.0-dev+a7ee89342.2024-03-01T03:40:57Z", - "Name": "eksctl-my-eks-cluster-cluster/ControlPlane" - }, - "health": { - "issues": [] - }, - "accessConfig": { - "authenticationMode": "API_AND_CONFIG_MAP" - } - } -} ----- - -=== Update cluster to use EKS Provisioned Control Plane - -[source,bash] ----- -aws eks update-cluster-config --name prod-cluster \ ---control-plane-scaling-config tier=tier-2xl ----- - -Response: - -[source,json] ----- -{ - "update": { - "id": "7551c64b-1d27-4b1e-9f8e-c45f056eb6fd", - "status": "InProgress", - "type": "ScalingTierConfigUpdate", - "params": [ - { - "type": "UpdatedTier", - "value": "tier-2xl" - }, - { - "type": "PreviousTier", - "value": "tier-xl" - } - ], - "createdAt": 1565807210.37, - "errors": [] - } -} ----- - -=== View Control Plane Scaling update - -[source,bash] ----- -aws eks list-updates --name example ----- - -Response: - -[source,json] ----- -{ - "updateIds": [ - "7551c64b-1d27-4b1e-9f8e-c45f056eb6fd1" - ] -} ----- - -=== Exit Provisioned Control Plane to Standard Control Plane - -[source,bash] ----- -aws eks update-cluster-config --name prod-cluster \ ---control-plane-scaling-config tier=standard ----- - -Response: - -[source,json] ----- -{ - "update": { - "id": "7551c64b-1d27-4b1e-9f8e-c45f056eb6fd", - "status": "InProgress", - "type": "ScalingTierConfigUpdate", - "params": [ - { - "type": "UpdatedTier", - "value": "standard" - }, - { - "type": "PreviousTier", - "value": "tier-2xl" - } - ], - "createdAt": 1565807210.37, - "errors": [] - } -} ----- - -== EKS Provisioned Control Plane - {aws-management-console} - -. Open the link:eks/home#/clusters[Amazon EKS console,type="console"]. -. Choose *Create cluster*. -. Under _Configuration options_, select *Custom configuration*. -. Scroll down to *Control plane scaling tier*. Select *Use a scaling tier* to enable Provisioned Control Plane. -. Select the control plane scaling tier that you would like to provision for the cluster from various scaling tier options such as XL, 2XL, and 4XL. -. Select other cluster configurations options as needed. On the final step select *Create cluster*. Note it may take several minutes for cluster creation to complete. diff --git a/latest/ug/clusters/eks-provisioned-control-plane-introduction.adoc b/latest/ug/clusters/eks-provisioned-control-plane-introduction.adoc deleted file mode 100644 index d29f16ac7..000000000 --- a/latest/ug/clusters/eks-provisioned-control-plane-introduction.adoc +++ /dev/null @@ -1,232 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-provisioned-control-plane] -= Amazon EKS Provisioned Control Plane -:info_titleabbrev: Create Provisioned Control Plane - -[abstract] --- -Learn how to use Amazon EKS Provisioned Control Plane for predictable and high performance from the cluster's control plane. --- - -== Overview - -Amazon EKS Provisioned Control Plane is a feature that enables cluster -administrators to select from a set of scaling tiers and -designate their chosen tier for very high, predictable performance from the cluster's control plane. This enables cluster administrators to ensure that the control plane is always provisioned with the specified -capacity. - -Amazon EKS offers two modes of operations for your cluster's control plane. By default, Amazon EKS clusters use *Standard mode*, where the control plane automatically scales up and down based on your workload demands. Standard mode dynamically allocates sufficient control plane capacity to meet your workload needs and is the recommended solution for most use cases. However, for specialized workloads that cannot tolerate any performance variability due to control plane scaling or those requiring very high amounts of control plane capacity, you can optionally use *Provisioned mode*. Provisioned mode allows you to pre-allocate control plane capacity that is always ready to handle demanding workload requirements. - -[NOTE] -==== -Provisioned mode is an additional control plane operations mode alongside the default Standard mode. The introduction of Provisioned mode does not change Standard mode behavior. -==== - -With EKS Provisioned Control Plane, cluster administrators can -pre-provision the desired control plane capacity ahead of time, providing -predictable and high performance from the cluster's control plane that is always available. EKS Provisioned Control Plane also enables cluster administrators to provision the same control plane capacity across environments, from staging to production and disaster recovery sites. This is important for ensuring that the control plane performance obtained across environments is consistent and predictable. Finally, EKS Provisioned Control Plane gives you access to very high levels of control plane performance, enabling the running of massively scalable AI workloads, high-performance computing, and large-scale data processing workloads on Kubernetes. - -All existing and new Amazon EKS clusters operate in Standard mode by -default. For clusters requiring high, predictable -performance from the control plane, you can opt in to use the EKS -Provisioned Control Plane feature. You will be billed at the hourly rate -for the particular control plane scaling tier in addition to the -standard or extended support EKS hourly charges. For more information -about pricing, see https://aws.amazon.com/eks/pricing/[Amazon EKS -pricing]. - -image::images/control-plane-modes.png[Amazon EKS Control Plane Modes,scaledwidth=100%] - -== Use cases - -EKS Provisioned Control Plane is designed to address specific scenarios -where high and predictable control plane performance is critical to your operations. Understanding these use cases can help you -determine whether EKS Provisioned Control Plane is the right solution -for your workloads. - -*Performance-critical workloads* – For workloads that demand minimal -latency and maximum performance from the Kubernetes control plane, EKS -Provisioned Control Plane provides capacity that eliminates -performance variability with control plane scaling. - -*Massively scalable workloads* – If you run highly scalable workloads -such as AI training and inference, high-performance computing, or -large-scale data processing that require a large number of nodes running -in the cluster, Provisioned Control Plane provides the necessary -control plane capacity to support these demanding workloads. - -*Anticipated high-demand events* – When you expect a sudden surge in -control plane requests due to an upcoming event such as e-commerce sales -or promotions, product launches, holiday shopping seasons, or major -sporting or entertainment events, Provisioned Control Plane allows -you to scale your control plane capacity in advance. This proactive -approach ensures your control plane is ready to handle the increased -load without waiting for automatic scaling to respond to demand. - -*Environment consistency* – Provisioned Control Plane enables you to -match control plane capacity and performance across staging and -production environments, helping you identify potential issues early -before deployment to production. By maintaining the same control plane -tier across environments, you can ensure that testing results accurately -reflect production behavior, reducing the risk of performance-related -surprises during rollout. - -*Disaster recovery and business continuity* – For disaster recovery -scenarios, Provisioned Control Plane allows you to provision -failover environments with the same level of capacity as your primary -environment. This ensures minimal disruption and quick recovery during -failover events, as your disaster recovery cluster will have identical -control plane performance characteristics to your production cluster -from the moment it's activated. - -== Control Plane Scaling Tiers - -EKS Provisioned Control Plane offers scaling tiers named using t-shirt -sizes (XL, 2XL, 4XL). Each tier defines its capacity through three key -Kubernetes attributes that determine the performance characteristics of your -cluster's control plane. Understanding these attributes helps you select -the appropriate tier for your workload requirements. - -*API request concurrency* measures the number of requests that the -Kubernetes control plane's API server can process concurrently, which is critical for high throughput workloads. - -*Pod scheduling rate* indicates how quickly the default Kubernetes -scheduler can schedule pods on nodes, measured in pods per second. - -*Cluster database size* indicates the storage space allocated to etcd, the database that holds the cluster state/metadata. - -When you provision your cluster's control plane on a certain scaling tier using Provisioned Control Plane, EKS ensures your cluster's control -plane maintains the limits corresponding to that tier. The -limits of control plane scaling tiers vary by Kubernetes version, -as shown in the following tables. - -=== EKS v1.28 and v1.29 - -[cols="1,1,1,1",options="header",] -|=== -|Provisioned Control Plane Scaling Tier -|API request concurrency (seats) -|Pod scheduling rate (pods/sec) -|Cluster database size (GB) - -|XL -|1700 -|100 -|16 - -|2XL -|3400 -|100 -|16 - -|4XL -|6800 -|100 -|16 -|=== - -=== EKS v1.30 and later - -[cols="1,1,1,1",options="header",] -|=== -|Provisioned Control Plane Scaling Tier -|API request concurrency (seats) -|Pod scheduling rate (pods/sec) -|Cluster database size (GB) - -|XL -|1700 -|167 -|16 - -|2XL -|3400 -|283 -|16 - -|4XL -|6800 -|400 -|16 -|=== - -=== Monitoring control plane scaling tier utilization - -Amazon EKS provides several metrics to help you monitor your control -plane's tier utilization. These metrics are published as <> and are -accessible through the CloudWatch and EKS console. Additionally, these metrics -are scrapable from your EKS cluster's Prometheus endpoint (see <>). - - -[cols="1,1,1",options="header",] -|=== -| -|*Prometheus Metric* -|*CloudWatch Metric* - -|*API request concurrency* -|apiserver_flowcontrol_current_executing_seats -|apiserver_flowcontrol_current_executing_seats - - -|*Pod scheduling rate* -|scheduler_schedule_attempts_total -|scheduler_schedule_attempts_total, scheduler_schedule_attempts_SCHEDULED, scheduler_schedule_attempts_UNSCHEDULABLE - - -|*Cluster database size* -|apiserver_storage_size_bytes -|apiserver_storage_size_bytes -|=== - -=== Understanding Tier capacity versus actual performance - -When you select a Provisioned Control Plane scaling tier, the tier attributes represent the underlying configurations that Amazon EKS applies to your control plane. However, the actual performance you achieve depends on your specific workload patterns, configurations, and adherence to Kubernetes best practices. For example, while a 4XL tier configures API Priority and Fairness (APF) with 6,800 concurrent request seats, the actual request throughput you obtain from the control plane depends on the types of operations being performed. For example, Kubernetes penalizes list requests more than get, and hence the effective number of list requests processed concurrently by control plane is lower than get requests (see https://docs.aws.amazon.com/eks/latest/best-practices/scale-control-plane.html#_api_priority_and_fairness[here]). Similarly, although the default scheduler QPS is set to 400 for a 4XL tier, your actual pod scheduling rate depends on factors like nodes being ready and health for scheduling. To achieve optimal performance, ensure your applications follow Kubernetes best practices (see https://docs.aws.amazon.com/eks/latest/best-practices/scalability.html[here]) and are properly configured for your workload characteristics. - -== Considerations - -* *Standard control plane capacity* – EKS Standard control plane mode -offers the best -price to performance ratio, and is the recommended option for the vast majority of use cases. However, for specialized workloads that cannot tolerate any performance variability due to control plane scaling or those requiring very high amounts of control plane capacity, you can optionally consider using Provisioned mode. -* *Opt-in required* – Existing clusters will not automatically scale up -from the Standard control plane to a higher https://aws.amazon.com/eks/pricing/[priced] EKS Provisioned -Control Plane tier. You must explicitly opt in to one of the new EKS -Provisioned Control Plane scaling tiers. -* *Exit restriction* – Standard control plane mode supports up to 8 GB of cluster database (etcd) size. If your cluster's database size exceeds 8 GB while using Provisioned mode, you cannot switch back to Standard mode until you reduce the database size to below 8 GB. For example, if you are using 14 GB of database storage in Provisioned mode, you must first reduce your database utilization to less than 8GB before returning to Standard mode. -* *No automatic tier scaling* – EKS Provisioned Control Plane does not -automatically scale between tiers. Once you select a scaling tier, your -cluster's control plane remains pinned to that tier, ensuring consistent -and predictable performance. However, you have the flexibility to -implement your own autoscaling solution by monitoring tier utilization -metrics and using the EKS Provisioned Control Plane APIs to scale up or -down when these metrics cross thresholds you define, giving you full -control over your scaling strategy and cost optimization. -* *Viewing current tier* – You can use the Amazon EKS console, Amazon Web Services CLI, -or API to view the current control plane scaling tier. In the CLI, -you can run the `describe-cluster` command: -`aws eks describe-cluster --name cluster-name` -* *Tier transition time* – You can use the Amazon EKS console, Amazon -EKS APIs, or CLI to exit or move between scaling tiers. Amazon EKS -has introduced a new cluster update type called -`ScalingTierConfigUpdate`, which you can inspect to monitor the progress -of the transition. After you execute a tier change command, you can list -the updates on the cluster to see a new update of type -`ScalingTierConfigUpdate` with status `Updating`. The status changes to -`Successful` upon completion of the update, or to `Failed` if an error -occurs. The error field in the update indicates the reason for failure. -There are no restrictions on how frequently you can switch between -tiers. Changing the control plane tier takes several minutes to -complete. -* *Selecting optimal tier* – To determine the optimal Provisioned Control Plane scaling tier for your cluster, you can perform load testing by provisioning your cluster on the highest tier (4XL). Then perform a load -test to simulate peak demand on your cluster's control plane. Observe -the control plane tier utilization metrics at peak load, and use these -observations as the guiding factor to select the appropriate tier for -Provisioned mode. -* *Provisioned Control Plane pricing* – You will be billed at the hourly rate for the Provisioned Control Plane scaling tier your cluster is on. This is in addition to the standard or extended support hourly charges. See Amazon EKS Pricing https://aws.amazon.com/eks/pricing/[page] for details. -* *Larger scaling tier* – If you intend to run your cluster on scaling tier larger than 4XL, contact your Amazon Web Services account team for additional pricing information. -* *Kubernetes version and region support* – EKS Provisioned Control Plane is supported in all Amazon Web Services commercial, GovCloud, and China regions. Provisioned Control Plane works on EKS v1.28 and higher. - - -include::eks-provisioned-control-plane-getting-started.adoc[leveloffset=+1] diff --git a/latest/ug/clusters/update-cluster.adoc b/latest/ug/clusters/update-cluster.adoc index 13f6f3018..b648d3747 100644 --- a/latest/ug/clusters/update-cluster.adoc +++ b/latest/ug/clusters/update-cluster.adoc @@ -86,7 +86,6 @@ Use Amazon EKS upgrade insights to identify issues. For more information, see << ** If the `kubelet` on your managed and Fargate nodes is on Kubernetes version `1.25` or newer, you can update your cluster up to three versions ahead without updating the `kubelet` version. For example, if the `kubelet` is on version `1.25`, you can update your Amazon EKS cluster version from `1.25` to `1.26`, to `1.27`, and to `1.28` while the `kubelet` remains on version `1.25`. * As a best practice before starting an update, make sure that the `kubelet` on your nodes is at the same Kubernetes version as your control plane. * If your cluster is configured with a version of the Amazon VPC CNI plugin for Kubernetes that is earlier than `1.8.0`, then we recommend that you update the plugin to the latest version before updating your cluster. To update the plugin, see <>. -* You can take a backup of your Amazon EKS cluster, to allow you to restore your Amazon EKS cluster state and persistent storage in the case of failures during the upgrade process. See <> [#update-cluster-control-plane] == Step 3: Update cluster control plane diff --git a/latest/ug/doc-history.adoc b/latest/ug/doc-history.adoc index 945be0bd4..19b6a04b2 100644 --- a/latest/ug/doc-history.adoc +++ b/latest/ug/doc-history.adoc @@ -19,35 +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] -link:eks/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-updates[type="documentation"] - -Amazon EKS has released a new managed policy `AmazonEKSMCPReadOnlyAccess` to enable read-only tools in the Amazon EKS MCP Server for observability and troubleshooting. For information, see link:eks/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-updates[Amazon EKS updates to {aws} managed policies,type="documentation"]. - -[.update,date="2025-11-19"] -=== Network observability -[.update-ulink] -link:eks/latest/userguide/network-observability.html[type="documentation"] - -Amazon EKS now provides enhanced container network observability with performance monitoring and workload traffic visibility. - -[.update,date="2025-11-17"] -=== {aws} managed policy updates -[.update-ulink] -link:eks/latest/userguide/security-iam-awsmanpol.html[type="documentation"] - -Added `ec2:CopyVolumes` permission to `AmazonEBSCSIDriverPolicy` to allow the EBS CSI Driver to copy EBS volumes directly. - [.update,date="2025-10-22"] === {aws} managed policy updates diff --git a/latest/ug/getting-started/install-kubectl.adoc b/latest/ug/getting-started/install-kubectl.adoc index 2fc675b67..a35ab4983 100644 --- a/latest/ug/getting-started/install-kubectl.adoc +++ b/latest/ug/getting-started/install-kubectl.adoc @@ -84,43 +84,43 @@ Procedure: + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/darwin/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/darwin/amd64/kubectl ---- **** Kubernetes `1.27` + @@ -142,43 +142,43 @@ curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-12-12/bin/dar + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/darwin/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/darwin/amd64/kubectl.sha256 ---- ***** Kubernetes `1.27` + @@ -236,43 +236,43 @@ Procedure: + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/linux/amd64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/linux/amd64/kubectl ---- **** Kubernetes `1.27` + @@ -294,43 +294,43 @@ curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-12-12/bin/lin + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/linux/amd64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/linux/amd64/kubectl.sha256 ---- ***** Kubernetes `1.27` + @@ -396,43 +396,43 @@ Procedure: + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/linux/arm64/kubectl +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/linux/arm64/kubectl ---- **** Kubernetes `1.27` + @@ -454,43 +454,43 @@ curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-12-12/bin/lin + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/linux/arm64/kubectl.sha256 +curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/linux/arm64/kubectl.sha256 ---- ***** Kubernetes `1.27` + @@ -556,43 +556,43 @@ Procedure: + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/windows/amd64/kubectl.exe +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/windows/amd64/kubectl.exe ---- **** Kubernetes `1.27` + @@ -614,43 +614,43 @@ curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-12-12/bin + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.2/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.34.1/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.33` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.33.5/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.32` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.32.9/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.31` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.13/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.30` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.14/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.29` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.15/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.28` + [source,bash,subs="verbatim,attributes"] ---- -curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-11-13/bin/windows/amd64/kubectl.exe.sha256 +curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.15/2025-09-19/bin/windows/amd64/kubectl.exe.sha256 ---- ***** Kubernetes `1.27` + 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/aws-service-view.png b/latest/ug/images/aws-service-view.png deleted file mode 100644 index a9ca787d6..000000000 Binary files a/latest/ug/images/aws-service-view.png and /dev/null differ diff --git a/latest/ug/images/cluster-view.png b/latest/ug/images/cluster-view.png deleted file mode 100644 index cd74276ef..000000000 Binary files a/latest/ug/images/cluster-view.png and /dev/null differ diff --git a/latest/ug/images/control-plane-modes.png b/latest/ug/images/control-plane-modes.png deleted file mode 100644 index 70ad28675..000000000 Binary files a/latest/ug/images/control-plane-modes.png and /dev/null differ diff --git a/latest/ug/images/ecommerce-deployment.png b/latest/ug/images/ecommerce-deployment.png deleted file mode 100644 index 031a5217c..000000000 Binary files a/latest/ug/images/ecommerce-deployment.png and /dev/null differ diff --git a/latest/ug/images/ecommerce-pod.png b/latest/ug/images/ecommerce-pod.png deleted file mode 100644 index 32ba804b4..000000000 Binary files a/latest/ug/images/ecommerce-pod.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/images/llm-inference-vllm-architecture.png b/latest/ug/images/llm-inference-vllm-architecture.png deleted file mode 100644 index c53c75b66..000000000 Binary files a/latest/ug/images/llm-inference-vllm-architecture.png and /dev/null differ diff --git a/latest/ug/images/llm-inference-vllm-chatui.png b/latest/ug/images/llm-inference-vllm-chatui.png deleted file mode 100644 index e176a6897..000000000 Binary files a/latest/ug/images/llm-inference-vllm-chatui.png and /dev/null differ diff --git a/latest/ug/images/llm-inference-vllm-guidellm-baseline.png b/latest/ug/images/llm-inference-vllm-guidellm-baseline.png deleted file mode 100644 index 26bef7813..000000000 Binary files a/latest/ug/images/llm-inference-vllm-guidellm-baseline.png and /dev/null differ diff --git a/latest/ug/images/llm-inference-vllm-guidellm-optimized.png b/latest/ug/images/llm-inference-vllm-guidellm-optimized.png deleted file mode 100644 index d1cd09b20..000000000 Binary files a/latest/ug/images/llm-inference-vllm-guidellm-optimized.png and /dev/null differ diff --git a/latest/ug/images/nfm-eks-metrics-types-workflow.png b/latest/ug/images/nfm-eks-metrics-types-workflow.png deleted file mode 100644 index e74a26f30..000000000 Binary files a/latest/ug/images/nfm-eks-metrics-types-workflow.png and /dev/null differ diff --git a/latest/ug/images/nfm-eks-metrics-workflow.png b/latest/ug/images/nfm-eks-metrics-workflow.png deleted file mode 100644 index aa34fc699..000000000 Binary files a/latest/ug/images/nfm-eks-metrics-workflow.png and /dev/null differ diff --git a/latest/ug/images/nfm-eks-workflow.png b/latest/ug/images/nfm-eks-workflow.png deleted file mode 100644 index ae6f5b3c5..000000000 Binary files a/latest/ug/images/nfm-eks-workflow.png and /dev/null differ diff --git a/latest/ug/images/photo-gallery-deployment.png b/latest/ug/images/photo-gallery-deployment.png deleted file mode 100644 index 76a0cf147..000000000 Binary files a/latest/ug/images/photo-gallery-deployment.png and /dev/null differ diff --git a/latest/ug/images/photo-gallery-pod.png b/latest/ug/images/photo-gallery-pod.png deleted file mode 100644 index 4f64407e8..000000000 Binary files a/latest/ug/images/photo-gallery-pod.png and /dev/null differ diff --git a/latest/ug/integrations/eks-integrations.adoc b/latest/ug/integrations/eks-integrations.adoc index 706a0507f..a4778f605 100644 --- a/latest/ug/integrations/eks-integrations.adoc +++ b/latest/ug/integrations/eks-integrations.adoc @@ -9,22 +9,16 @@ 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] \ No newline at end of file diff --git a/latest/ug/integrations/integration-backup.adoc b/latest/ug/integrations/integration-backup.adoc deleted file mode 100644 index 2be9fe038..000000000 --- a/latest/ug/integrations/integration-backup.adoc +++ /dev/null @@ -1,25 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#integration-backup] -= Backup your EKS Clusters with {aws} Backup -:info_titleabbrev: {aws} Backup - -{aws} Backup supports backups of Amazon EKS clusters, including Kubernetes cluster state and persistent storage attached to the EKS cluster via a persistent volume claim (EBS volumes, EFS file systems, and S3 buckets). -An Amazon EKS backup will create a composite recovery point, where a child recovery point will be for each resource backed up. - -* How to back up resources: link:aws-backup/latest/devguide/getting-started.html[Getting started with {aws} Backup,type="documentation"] -* Backup creation by Resource Type: link:aws-backup/latest/devguide/creating-a-backup.html[Amazon EKS Backups,type="documentation"] -* How to restore Amazon EKS clusters: link:aws-backup/latest/devguide/restoring-a-backup.html[Amazon EKS Backups restore,type="documentation"] - -To get started via the EKS console, {aws} Backup console or CLI ensure that your IAM role has the following permissions: - -* These can be found in {aws} Backup’s Managed policy link:aws-backup/latest/devguide/security-iam-awsmanpol.html#AWSBackupServiceRolePolicyForBackup[AWSBackupServiceRolePolicyForBackup,type="documentation"]. This contains the required permissions to backup your Amazon EKS cluster and EBS and EFS persistent storage -* If your EKS Cluster contains an S3 bucket you will need to ensure the following policies and prequisites for your S3 bucket are added and enabled as documented: - * link:aws-backup/latest/devguide/security-iam-awsmanpol.html#AWSBackupServiceRolePolicyForS3Backup[AWSBackupServiceRolePolicyForS3Backup,type="documentation"] - * Prerequisites for link:aws-backup/latest/devguide/s3-backups.html#s3-backup-prerequisites#AWSBackupServiceRolePolicyForS3Backup[S3 Backups,type="documentation"] - -Ensure your EKS Clusters have the following settings: - - * EKS Cluster link:eks/latest/userguide/setting-up-access-entries.html[authorization mode,type="documentation"] set to API or API_AND_CONFIG_MAP for {aws} Backup to create link:eks/latest/userguide/access-entries.html[Access Entries,type="documentation"] to access the EKS cluster. - 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..5231c0a2c 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 @@ -657,267 +657,6 @@ DaemonSet Access: This policy is automatically managed by the EKS service for Cluster Insights. For more information, see <>. -== AWSBackupFullAccessPolicyForBackup - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AWSBackupFullAccessPolicyForBackup` - -AWSBackupFullAccessPolicyForBackup - -This policy grants the permissions necessary for {aws} Backup to manage and create backups of the EKS Cluster. This policy includes the following permissions: - -[%header,cols="3"] -|=== -| Kubernetes API groups -| Kubernetes resources -| Kubernetes verbs (permissions) - - -|`{asterisk}` -|`*` -|`list`, `get` -|=== - -== AWSBackupFullAccessPolicyForRestore - -*ARN* – `{arn-aws}eks::aws:cluster-access-policy/AWSBackupFullAccessPolicyForRestore` - -AWSBackupFullAccessPolicyForRestore - -This policy grants the permissions necessary for {aws} Backup to manage and restore backups of the EKS Cluster. This policy includes the following permissions: - -[%header,cols="3"] -|=== -| Kubernetes API groups -| Kubernetes resources -| Kubernetes verbs (permissions) - - -|`{asterisk}` -|`*` -|`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 +668,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-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 deleted file mode 100644 index a58846940..000000000 --- a/latest/ug/ml/ml-realtime-inference-llm-inference-vllm.adoc +++ /dev/null @@ -1,654 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#ml-realtime-inference-llm-inference-vllm] -= Quickstart: High-throughput LLM inference with vLLM on Amazon EKS -:info_titleabbrev: LLM inference with vLLM - -[abstract] --- -Deploy Large Language Models (LLMs) on Amazon EKS using vLLM and GPUs for text-based real-time inference applications. --- - -== Introduction - -This quickstart guide provides a walkthrough for deploying Large Language Models (LLMs) on Amazon EKS using vLLM and GPUs for text-based real-time inference applications. - -The solution leverages Amazon EKS for container orchestration and vLLM for efficient model serving, enabling you to build scalable AI applications with GPU acceleration and high-throughput inference serving. The Llama 3.1 8B Instruct model is used for demonstration, but you can deploy any other LLM supported by vLLM (check https://docs.vllm.ai/en/latest/models/supported_models.html#list-of-text-only-language-models[vLLM documentation] for a list of supported models). To test LLM inference, we use a sample chatbot application based on the project https://github.com/yoziru/nextjs-vllm-ui[nextjs-vllm-ui]. Finally, we use GuideLLM to benchmark and tune vLLM configuration parameters to optimize inference performance. - -.vLLM Architecture on EKS -image::images/llm-inference-vllm-architecture.png[vLLM Architecture diagram] - -When you complete this procedure, you will have a vLLM inference endpoint optimized for throughput and low latency, and you will be able to interact with a Llama model through a chat frontend application, demonstrating a typical use case for chatbot assistants and other LLM-based applications. - -For additional guidance and advanced deployment resources, check our https://docs.aws.amazon.com/eks/latest/best-practices/aiml.html[EKS Best Practices Guide for AI/ML workloads] and production-ready https://github.com/awslabs/ai-on-eks/tree/main/blueprints/inference/inference-charts[AI on EKS inference charts]. - -== Before you begin - -Before getting started, ensure you have: - -* An Amazon EKS cluster with the following main components: Karpenter nodepools with G5 or G6 EC2 instance family, the NVIDIA Device Plugin installed on your GPU-enabled worker nodes, and the S3 Mountpoint CSI Driver installed. To create this baseline setup, follow steps in <>, up to completing step #4. -* A Hugging Face account. To sign up, see https://huggingface.co/login. - -== Set Up Model Storage with Amazon S3 - -Store large LLM files efficiently in Amazon S3 to separate storage from compute resources. This approach streamlines model updates, reduces costs, and simplifies management in production setups. S3 handles massive files reliably, while integration with Kubernetes via the Mountpoint CSI driver lets pods access models like local storage—no need for time-consuming downloads during startup. Follow these steps to create an S3 bucket, upload an LLM, and mount it as a volume in your inference serving container. - -Other storage solutions are also available on EKS for model caching, such as EFS and FSx for Lustre. For more information, check https://docs.aws.amazon.com/eks/latest/best-practices/aiml-storage.html[EKS Best Practices]. - -=== Set environment variables - -Create a unique name for a new Amazon S3 bucket that we will create later in this guide. Once created, use this same bucket name for all steps. For example: - -[source,bash] ----- -MY_BUCKET_NAME=model-store-$(date +%s) ----- - -Define environment variables and store them in a file: - -[source,bash] ----- -cat << EOF > .env-quickstart-vllm -export BUCKET_NAME=${MY_BUCKET_NAME} -export AWS_REGION=us-east-1 -export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) -EOF ----- - -Load environment variables in your shell environment. If you close the current shell environment and open a new one, make sure to re-source environment variables using this same command: - -[source,bash] ----- -source .env-quickstart-vllm ----- - -=== Create an S3 bucket to store model files - -Create an S3 bucket to store model files: - -[source,bash] ----- -aws s3 mb s3://${BUCKET_NAME} --region ${AWS_REGION} ----- - -=== Download model from Hugging Face - -Hugging Face is one of the main model hubs for accessing LLM models. To download the Llama model, you'll need to accept the model license and set up token authentication: - -1. Accept the Llama 3.1 8B Instruct model license at https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct. -2. Generate an access token (go to your Profile > Settings > Access Tokens, then create a new token using Read token type). - -Set an environment variable with your Hugging Face token: - -[source,bash] ----- -export HF_TOKEN=your_token_here ----- - -Install pip3 package if not already installed in your environment. Example command in Amazon Linux 2023: - -[source,bash] ----- -sudo dnf install -y python3-pip ----- - -Install the https://huggingface.co/docs/huggingface_hub/main/en/guides/cli[Hugging Face CLI]: - -[source,bash] ----- -pip install huggingface-hub ----- - -Download Llama-3.1-8B-Instruct model from Hugging Face (~15 GB) using the `--exclude` flag to skip the legacy PyTorch format and only download the optimized safetensors format files, which reduces download size while maintaining full compatibility with popular inference engines: - -[source,bash] ----- -huggingface-cli download meta-llama/Meta-Llama-3.1-8B-Instruct \ - --exclude "original/*" \ - --local-dir ./llama-3.1-8b-instruct \ - --token $HF_TOKEN ----- - -Verify the downloaded files: - -[source,bash] ----- -$ ls llama-3.1-8b-instruct ----- - -The expected output should look like this: - -[source,console] ----- -LICENSE config.json model-00002-of-00004.safetensors model.safetensors.index.json tokenizer_config.json -README.md generation_config.json model-00003-of-00004.safetensors special_tokens_map.json -USE_POLICY.md model-00001-of-00004.safetensors model-00004-of-00004.safetensors tokenizer.json ----- - -=== Upload model files - -Enable {aws} Common Runtime (CRT) for improved S3 transfer performance. The CRT-based transfer client provides enhanced throughput and reliability for large file operations: - -[source,bash] ----- -aws configure set s3.preferred_transfer_client crt ----- - -Upload the model: - -[source,bash] ----- -aws s3 cp ./llama-3.1-8b-instruct s3://$BUCKET_NAME/llama-3.1-8b-instruct \ - --recursive ----- - -The expected output should look like this: - -[source,console] ----- -... -upload: llama-3.1-8b-instruct/tokenizer.json to s3://model-store-1753EXAMPLE/llama-3.1-8b-instruct/tokenizer.json -upload: llama-3.1-8b-instruct/model-00004-of-00004.safetensors to s3://model-store-1753890326/llama-3.1-8b-instruct/model-00004-of-00004.safetensors -upload: llama-3.1-8b-instruct/model-00002-of-00004.safetensors to s3://model-store-1753890326/llama-3.1-8b-instruct/model-00002-of-00004.safetensors -upload: llama-3.1-8b-instruct/model-00003-of-00004.safetensors to s3://model-store-1753890326/llama-3.1-8b-instruct/model-00003-of-00004.safetensors -upload: llama-3.1-8b-instruct/model-00001-of-00004.safetensors to s3://model-store-1753890326/llama-3.1-8b-instruct/model-00001-of-00004.safetensors ----- - -=== Set Up S3 Mountpoint CSI permissions - -The S3 Mountpoint CSI driver enables native integration between Kubernetes and S3, allowing pods to directly access model files as if they were local storage, eliminating the need for local copies during container startup. - -Create an IAM policy to allow the S3 mount point to read from your S3 bucket: - -[source,bash] ----- -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}/*\"]}]}" ----- - -Find the IAM role name used by the S3 Mountpoint CSI Driver by checking S3 CSI Driver service account annotations: - -[source,bash] ----- -ROLE_NAME=$(kubectl get serviceaccount s3-csi-driver-sa -n kube-system -o jsonpath='{.metadata.annotations.eks\.amazonaws\.com/role-arn}' | cut -d'/' -f2) ----- - -Attach your IAM policy with the S3 Mountpoint CSI role: - -[source,bash] ----- -aws iam attach-role-policy \ - --role-name ${ROLE_NAME} \ - --policy-arn arn:aws:iam::${AWS_ACCOUNT_ID}:policy/S3BucketAccess-${BUCKET_NAME} ----- - -If S3 Mountpoint CSI is not installed in the cluster, follow the deployment steps in <>. - -=== Mount S3 bucket as a Kubernetes volume - -Create a Persistent Volume (PV) and Persistent Volume Claim (PVC) to provide read-only access to the S3 bucket across multiple inference pods. The ReadOnlyMany access mode ensures concurrent access to model files, while the CSI driver handles the S3 bucket mounting: - -[source,yaml] ----- -cat <>. This cluster includes Karpenter nodepools that can provision GPU enabled nodes with sufficient node storage to download vLLM container image. If using your custom EKS cluster, ensure that it can launch GPU enabled nodes. - -*Instance Selection* - -Proper instance selection for LLM inference requires ensuring that available GPU memory is sufficient to load model weights. Model weights for Llama 3.1 8B Instruct are approximately 16GB (size of model files .safetensor), therefore we need to provide at least this amount of memory to the vllm process to load the model. - -https://aws.amazon.com/ec2/instance-types/g5/[Amazon G5 EC2 Instances] with A10G GPUs and https://aws.amazon.com/ec2/instance-types/g6/[G6 EC2 instances] with L4 GPUs both provide 24GB VRAM per GPU, sufficient for loading Llama 3.1 8B Instruct weights. If you are deploying a model with larger weights, consider using a multi-GPU instance type or a multi-node setup. - -*NVIDIA device drivers* - -NVIDIA drivers provide the necessary runtime environment for containers to access GPU resources efficiently. It enables GPU resource allocation and management within Kubernetes, making GPUs available as schedulable resources. - -Our cluster uses EKS Bottlerocket AMIs, which include all necessary NVIDIA device drivers and plugins on all GPU-enabled nodes, ensuring immediate GPU accessibility for containerized workloads without additional setup. If you are using other types of EKS nodes, you need to ensure all necessary drivers and plugins are installed. - -=== Test GPU Infrastructure - -Test your cluster's GPU capabilities by executing the steps below to ensure pods can access NVIDIA GPU resources and schedule correctly on GPU-enabled nodes. - -Deploy an Nvidia SMI test pod: - -[source,yaml] ----- -cat <>. If you are using different node pools, ensure the pod matches nodeSelector and Tolerations accordingly. - -== Deploy Inference Container - -The serving stack determines both performance and scalability capabilities of your inference infrastructure. vLLM has emerged as a leading solution for production deployments. vLLM's architecture provides continuous batching for dynamic request processing, kernel optimizations for faster inference, and efficient GPU memory management through PagedAttention. These features, combined with a production-ready REST API and support for popular model formats, make it an optimal choice for high-performance inference deployments. - -=== Select {aws} Deep Learning Container image - -https://github.com/aws/deep-learning-containers/tree/master[{aws} Deep Learning Containers] (DLCs) provide pre-optimized environments with security updates, {aws} infrastructure compatibility, and optimized driver configurations. This reduces deployment complexity and maintenance overhead while ensuring production readiness. - -For this deployment, we'll use the {aws} DLC for vLLM 0.9, which includes Nvidia libraries and optimized GPU performance configurations specifically tuned for transformer model inference on {aws} GPU instances. - -[source,text] ----- -image: 763104351884.dkr.ecr.us-east-1.amazonaws.com/vllm:0.9-gpu-py312-ec2 ----- - -=== Apply vLLM Kubernetes manifests - -There are multiple ways to deploy vLLM in EKS. This guide demonstrates vLLM deployment using a Kubernetes deployment, which is a Kubernetes-native and easy way to get started. For advanced deployment options see https://docs.vllm.ai/en/latest/deployment/k8s.html[vLLM docs] and https://awslabs.github.io/ai-on-eks/docs/blueprints[AI on EKS blueprints]. - -Define deployment parameters through Kubernetes manifests to control resource allocation, node placement, health probes, exposing the service, etc. Configure your deployment to run a GPU-enabled pod using {aws} Deep Learning Container image for vLLM. Set optimized parameters for LLM inference and expose the vLLM OpenAPI-compatible endpoint via {aws} Load Balancer service: - -[source,yaml] ----- -cat <>. - - -== Run inference - -=== Validate inference pod - -Validate the inference container functionality locally through the forwarded port. Send a connection request and ensure that the response includes HTTP code 200: - -[source,bash] ----- -$ curl -IX GET "http://localhost:8000/v1/models" ----- - -[source,console] ----- -HTTP/1.1 200 OK -date: Mon, 13 Oct 2025 23:24:57 GMT -server: uvicorn -content-length: 516 -content-type: application/json ----- - -Test inference capabilities and validate external connectivity by sending a completion request to the LLM via the NLB endpoint: - -[source,bash] ----- -curl -X POST "http://$NLB:80/v1/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "/mnt/models/llama-3.1-8b-instruct", - "prompt": "Explain artificial intelligence:", - "max_tokens": 512, - "temperature": 0.7 - }' ----- - -This endpoint follows the OpenAI API format, making it compatible with existing applications while providing configurable generation parameters like response length and temperature for controlling output diversity. - -=== Run chatbot app - -For demonstration, this guide runs a sample chatbot application using project https://github.com/yoziru/nextjs-vllm-ui[nextjs-vllm-ui] to showcase user interactions with the model. - -Run a chatbot UI as a Docker container that maps port 3000 to localhost and connects to the vLLM NLB endpoint: - -[source,bash] ----- -docker run --rm \ - -p 3000:3000 \ - -e VLLM_URL="http://${NLB}:80" \ - --name nextjs-vllm-ui-demo \ - ghcr.io/yoziru/nextjs-vllm-ui:latest ----- - -Open your web browser and navigate to: http://localhost:3000/ - -You should see the chat interface where you can interact with the Llama model. - -.Chat UI Interface -image::images/llm-inference-vllm-chatui.png[Chat UI Interface] - - - -== Optimize inference performance - -Specialized inference engines like vLLM provide advanced features that significantly boost inference performance, including continuous batching, efficient KV caching, and optimized memory attention mechanisms. You can tune vLLM configuration parameters to improve inference performance while meeting your specific use case requirements and workload patterns. Proper configuration is essential for achieving GPU saturation, ensuring you extract maximum value from expensive GPU resources while delivering high throughput, low latency, and cost-effective operations. The following optimizations will help you maximize your vLLM deployment's performance on EKS. - -=== Benchmark vLLM configurations - -To tune vLLM configuration parameters for your use case, benchmark different settings using a comprehensive inference benchmarking tool like https://github.com/vllm-project/guidellm[GuideLLM]. This will collect key metrics like request per second throughput (RPS), end-to-end latency (E2E), time to first token (TTFT), and tail latency (TPOT) to compare different configurations. - -=== Baseline vLLM configuration - -This is the baseline configuration that was used to run vLLM: - -[cols="1,2"] -|=== -|vLLM Parameter |Description - -|tensor_parallel_size: 1 -|Distribute model across 1 GPU - -|gpu_memory_utilization: 0.90 -|Reserve 10% GPU memory for system overhead - -|max_sequence_length: 8192 -|Maximum total sequence length (input + output) - -|max_num_seqs: 1 -|Maximum concurrent requests per GPU (Batching) -|=== - -Run GuideLLM with this baseline setup to establish a performance baseline. For this test, GuideLLM is configured to generate 1 request per second, with 256-token requests and 128-token responses. - -[source,bash] ----- -guidellm benchmark \ ---target "http://${NLB}:80" \ ---processor meta-llama/Llama-3.1-8B-Instruct \ ---rate-type constant \ ---rate 1 \ ---max-seconds 30 \ ---data "prompt_tokens=256,output_tokens=128" ----- - -Expected output: - -.Baseline Benchmark Results -image::images/llm-inference-vllm-guidellm-baseline.png[Baseline Benchmark Results] - -=== Tuned vLLM configuration - -Adjust vLLM parameters to better utilize GPU resources and parallelization: - -[cols="1,2"] -|=== -|vLLM Parameter |Description - -|tensor_parallel_size: 1 -|Keep at 1 GPU. Tensor parallelization must match the number of GPUs to be used by vLLM - -|gpu_memory_utilization: 0.92 -|Reduce overhead GPU memory if possible, while ensuring that vLLM continues to run without errors - -|max_sequence_length: 4096 -|Adjust max sequence per your use case requirements; lower max sequence frees up resources that can be used for increased parallelization - -|max_num_seqs: 8 -|Increasing max seq increases throughput but also increases latency. Increase this value to maximize throughput while ensuring that latency stays within your use case requirements -|=== - -Apply these changes to the running deployment using kubectl patch command: - -[source,bash] ----- -kubectl patch deployment vllm-inference-app --type='json' -p='[ - {"op": "replace", "path": "/spec/template/spec/containers/0/args/4", "value": "--gpu-memory-utilization=0.92"}, - {"op": "replace", "path": "/spec/template/spec/containers/0/args/5", "value": "--max-model-len=4096"}, - {"op": "replace", "path": "/spec/template/spec/containers/0/args/6", "value": "--max-num-seqs=8"} -]' ----- - -Check that vLLM pod is in `Ready 1/1` state: - -[source,bash] ----- -kubectl get pod -l app=vllm-inference-app -w ----- - -Expected output: - -[source,console] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -vllm-inference-app-65df5fddc8-5kmjm 1/1 1 1 5m ----- - -Then run GuideLLM again using the same benchmarking values as before: - -[source,bash] ----- -guidellm benchmark \ ---target "http://${NLB}:80" \ ---processor meta-llama/Llama-3.1-8B-Instruct \ ---rate-type constant \ ---rate 1 \ ---max-seconds 30 \ ---data "prompt_tokens=256,output_tokens=128" ----- - -Expected output: - -.Optimized Benchmark Results -image::images/llm-inference-vllm-guidellm-optimized.png[Optimized Benchmark Results] - -=== Benchmarking results - -Compute benchmarking results in a table for both baseline and optimized vLLM configuration: - -[cols="1,1,1"] -|=== -|Avg Values |Baseline config |Optimized config - -|RPS -|0.23 req/sec -|0.86 req/sec - -|E2E -|12.99 s -|5.19 s - -|TTFT -|8637.2 ms -|147.9 ms - -|TPOT -|34.0 ms -|39.5 ms -|=== - -The optimized vLLM configurations significantly improved inference throughput (RPS) and reduced latency (E2E, TTFT) with only a minor millisecond increase in tail latency (TPOT). These results demonstrate how vLLM significantly improves inference performance, allowing each container to process more requests in less time for cost-effective operation. - - diff --git a/latest/ug/ml/ml-realtime-inference.adoc b/latest/ug/ml/ml-realtime-inference.adoc index e87d869dc..d1f6d7ded 100644 --- a/latest/ug/ml/ml-realtime-inference.adoc +++ b/latest/ug/ml/ml-realtime-inference.adoc @@ -16,5 +16,3 @@ This section is designed to help you deploy and operate real-time online inferen [[Topic List]] include::ml-realtime-inference-cluster.adoc[leveloffset=+1] - -include::ml-realtime-inference-llm-inference-vllm.adoc[leveloffset=+1] 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/networking/lbc-manifest.adoc b/latest/ug/networking/lbc-manifest.adoc index 2b53ce848..eea269e12 100644 --- a/latest/ug/networking/lbc-manifest.adoc +++ b/latest/ug/networking/lbc-manifest.adoc @@ -229,7 +229,7 @@ curl -Lo v2_14_1_full.yaml https://github.com/kubernetes-sigs/aws-load-balancer- + [source,shell,subs="verbatim,attributes"] ---- -sed -i.bak -e '764,772d' ./v2_14_1_full.yaml +sed -i.bak -e '764,773d' ./v2_14_1_full.yaml ---- + If you downloaded a different file version, then open the file in an editor and remove the following lines. diff --git a/latest/ug/networking/managing-kube-proxy.adoc b/latest/ug/networking/managing-kube-proxy.adoc index 314a72030..6bd5eea20 100644 --- a/latest/ug/networking/managing-kube-proxy.adoc +++ b/latest/ug/networking/managing-kube-proxy.adoc @@ -35,13 +35,13 @@ The following table lists the latest version of the Amazon EKS add-on type for e |=== | Kubernetes version | `kube-proxy` version -| 1.34 | v1.34.1-eksbuild.2 -| 1.33 | v1.33.5-eksbuild.2 -| 1.32 | v1.32.9-eksbuild.2 -| 1.31 | v1.31.13-eksbuild.2 -| 1.30 | v1.30.14-eksbuild.8 -| 1.29 | v1.29.15-eksbuild.16 -| 1.28 | v1.28.15-eksbuild.31 +| 1.34 | v1.34.0-eksbuild.4 +| 1.33 | v1.33.3-eksbuild.10 +| 1.32 | v1.32.6-eksbuild.12 +| 1.31 | v1.31.10-eksbuild.12 +| 1.30 | v1.30.14-eksbuild.18 +| 1.29 | v1.29.15-eksbuild.26 +| 1.28 | v1.28.15-eksbuild.41 |=== @@ -65,10 +65,10 @@ The following table lists the latest available self-managed `kube-proxy` contain |=== | Version | kube-proxy -| 1.34 | v1.34.1-eksbuild.2 -| 1.33 | v1.33.5-minimal-eksbuild.2 -| 1.32 | v1.32.9-minimal-eksbuild.2 -| 1.31 | v1.31.13-minimal-eksbuild.2 +| 1.34 | v1.34.0-eksbuild.5 +| 1.33 | v1.33.3-minimal-eksbuild.11 +| 1.32 | v1.32.6-minimal-eksbuild.13 +| 1.31 | v1.31.10-minimal-eksbuild.13 | 1.30 | v1.30.14-minimal-eksbuild.8 | 1.29 | v1.29.15-minimal-eksbuild.16 | 1.28 | v1.28.15-minimal-eksbuild.31 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..3f0e0fa8f 100644 --- a/latest/ug/nodes/eks-ami-build-scripts.adoc +++ b/latest/ug/nodes/eks-ami-build-scripts.adoc @@ -2,8 +2,7 @@ include::../attributes.txt[] [.topic] [#eks-ami-build-scripts] -= Build a custom EKS-optimized Amazon Linux AMI - += Build a custom Amazon Linux AMI :info_titleabbrev: Custom builds [abstract] @@ -11,12 +10,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..63d224845 100644 --- a/latest/ug/nodes/eks-ami-deprecation-faqs.adoc +++ b/latest/ug/nodes/eks-ami-deprecation-faqs.adoc @@ -10,17 +10,12 @@ 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 <>. -* Bottlerocket enables enhanced security, faster boot times, and a smaller attack surface for improved efficiency with its purpose-built, container-optimized design, well-suited for container-native approaches with minimal node customizations. To learn more, see https://aws.amazon.com/bottlerocket/faqs/[Bottlerocket FAQs] or view our detailed migration guidance at <>. +* 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. +* Bottlerocket enables enhanced security, faster boot times, and a smaller attack surface for improved efficiency with its purpose-built, container-optimized design, well-suited for container-native approaches with minimal node customizations. -Alternatively, you can <> until the EOS date (November 26, 2025). Additionally, you can build a custom AMI with an Amazon Linux 2 base instance until the Amazon Linux 2 EOS date (June 30, 2026). +Alternatively, you can <> until the EOS date (November 26, 2025), or build a custom AMI with an Amazon Linux 2 base instance until the Amazon Linux 2 EOS date (June 30, 2026). For more information, please visit https://aws.amazon.com/linux/amazon-linux-2023/faqs/[AL2023 FAQs], https://aws.amazon.com/bottlerocket/faqs/[Bottlerocket FAQs] or refer to <> or <> documentation for detailed migration guidance. == Migration and support FAQs @@ -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..5f1b2e706 100644 --- a/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc +++ b/latest/ug/nodes/hybrid-nodes-bottlerocket.adoc @@ -10,9 +10,9 @@ include::../attributes.txt[] Connect hybrid nodes running Bottlerocket to an Amazon EKS cluster. -- -This topic describes how to connect hybrid nodes running Bottlerocket to an Amazon EKS cluster. link:bottlerocket/[Bottlerocket,type="marketing"] is an open source Linux distribution that is sponsored and supported by {aws}. Bottlerocket is purpose-built for hosting container workloads. With Bottlerocket, you can improve the availability of containerized deployments and reduce operational costs by automating updates to your container infrastructure. Bottlerocket includes only the essential software to run containers, which improves resource usage, reduces security threats, and lowers management overhead. +This topic describes how to connect hybrid nodes running Bottlerocket to an Amazon EKS cluster. link:bottlerocket/[Bottlerocket,type="marketing"] is an open source Linux distribution that is sponsored and supported by {aws}. Bottlerocket is purpose-built for hosting container workloads. With Bottlerocket, you can improve the availability of containerized deployments and reduce operational costs by automating updates to your container infrastructure. Bottlerocket includes only the essential software to run containers, which improves resource usage, reduces security threats, and lowers management overhead. -Only VMware variants of Bottlerocket version v1.37.0 and above are supported with EKS Hybrid Nodes. VMware variants of Bottlerocket are available for Kubernetes versions v1.28 and above. The OS images for these variants include the kubelet, containerd, aws-iam-authenticator and other software prerequisites for EKS Hybrid Nodes. You can configure these components using a Bottlerocket https://github.com/bottlerocket-os/bottlerocket#settings[settings] file that includes base64 encoded user-data for the Bottlerocket bootstrap and admin containers. Configuring these settings enables Bottlerocket to use your hybrid nodes credentials provider to authenticate hybrid nodes to your cluster. After your hybrid nodes join the cluster, they will appear with status `Not Ready` in the Amazon EKS console and in Kubernetes-compatible tooling such as `kubectl`. After completing the steps on this page, proceed to <> to make your hybrid nodes ready to run applications. +Only VMware variants of Bottlerocket version v1.37.0 and above are supported with EKS Hybrid Nodes. VMware variants of Bottlerocket are available for Kubernetes versions v1.28 and above. The OS images for these variants include the kubelet, containerd, aws-iam-authenticator and other software prerequisites for EKS Hybrid Nodes. You can configure these components using a Bottlerocket https://github.com/bottlerocket-os/bottlerocket?tab=readme-ov-file#settings[settings] file that includes base64 encoded user-data for the Bottlerocket bootstrap and admin containers. Configuring these settings enables Bottlerocket to use your hybrid nodes credentials provider to authenticate hybrid nodes to your cluster. After your hybrid nodes join the cluster, they will appear with status `Not Ready` in the Amazon EKS console and in Kubernetes-compatible tooling such as `kubectl`. After completing the steps on this page, proceed to <> to make your hybrid nodes ready to run applications. == Prerequisites @@ -25,12 +25,7 @@ Before connecting hybrid nodes to your Amazon EKS cluster, make sure you have co == Step 1: Create the Bottlerocket settings TOML file -To configure Bottlerocket for hybrid nodes, you need to create a `settings.toml` file with the necessary configuration. The contents of the TOML file will differ based on the credential provider you are using (SSM or IAM Roles Anywhere). This file will be passed as user data when provisioning the Bottlerocket instance. - -[NOTE] -==== -The TOML files provided below only represent the minimum required settings for initializing a Bottlerocket VMWare machine as a node on an EKS cluster. Bottlerocket provides a wide range of settings to address several different use cases, so for further configuration options beyond hybrid node initialization, please refer to the https://bottlerocket.dev/en[Bottlerocket documentation] for the comprehensive list of all documented settings for the Bottlerocket version you are using (for example, https://bottlerocket.dev/en/os/1.51.x/api/settings-index[here] are all the settings available for Bottlerocket 1.51.x). -==== +To configure Bottlerocket for hybrid nodes, you need to create a `settings.toml` file with the necessary configuration. The contents of the TOML file will differ based on the credential provider you are using (SSM or IAM Roles Anywhere). This file will be passed as user data when provisioning the Bottlerocket instance. === SSM @@ -46,7 +41,6 @@ hostname-override = "" provider-id = "eks-hybrid://///" authentication-mode = "aws" cloud-provider = "" -server-tls-bootstrap = true [settings.network] hostname = "" @@ -54,18 +48,6 @@ hostname = "" [settings.aws] region = "" -[settings.kubernetes.credential-providers.ecr-credential-provider] -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", - "public.ecr.aws" -] - [settings.kubernetes.node-labels] "eks.amazonaws.com/compute-type" = "hybrid" "eks.amazonaws.com/hybrid-credential-provider" = "ssm" @@ -124,7 +106,6 @@ hostname-override = "" provider-id = "eks-hybrid://///" authentication-mode = "aws" cloud-provider = "" -server-tls-bootstrap = true [settings.network] hostname = "" @@ -133,18 +114,6 @@ hostname = "" region = "" config = "" -[settings.kubernetes.credential-providers.ecr-credential-provider] -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", - "public.ecr.aws" -] - [settings.kubernetes.node-labels] "eks.amazonaws.com/compute-type" = "hybrid" "eks.amazonaws.com/hybrid-credential-provider" = "iam-ra" @@ -225,7 +194,7 @@ govc vm.create \ -template= \ -govc vm.change +govc vm.change -vm \ -e guestinfo.userdata="$(base64 -w0 settings.toml)" \ -e guestinfo.userdata.encoding="base64" 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/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/cloudwatch.adoc b/latest/ug/observability/cloudwatch.adoc index da94025f5..990d2cdef 100644 --- a/latest/ug/observability/cloudwatch.adoc +++ b/latest/ug/observability/cloudwatch.adoc @@ -27,14 +27,6 @@ For clusters that are Kubernetes version `1.28` and above, you get CloudWatch ve |Metric name |Description -|`apiserver_flowcontrol_current_executing_seats` -| The number of seats currently in use for executing API requests. Seat allocation is determined by the priority_level and flow_schema configuration in the Kubernetes API Priority and Fairness -https://kubernetes.io/docs/concepts/cluster-administration/flow-control/[feature]. - -*Units:* Count - -*Valid statistics:* Max - |`scheduler_schedule_attempts_total` |The number of total attempts by the scheduler to schedule Pods in the cluster for a given period. This metric helps monitor the scheduler's workload and can indicate scheduling pressure or potential issues with Pod placement. diff --git a/latest/ug/observability/container-network-observability.adoc b/latest/ug/observability/container-network-observability.adoc deleted file mode 100644 index a6e980779..000000000 --- a/latest/ug/observability/container-network-observability.adoc +++ /dev/null @@ -1,412 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#network-observability] -= Monitor Kubernetes workload traffic with Container Network Observability -:info_titleabbrev: Container network observability - -Amazon EKS provides enhanced network observability features that provide deeper insights into your container networking environment. These capabilities help you better understand, monitor, and troubleshoot your Kubernetes network landscape in {aws}. With enhanced container network observability, you can leverage granular, network-related metrics for better proactive anomaly detection across cluster traffic, cross-AZ flows, and {aws} services. Using these metrics, you can measure system performance and visualize the underlying metrics using your preferred observability stack. - -In addition, Amazon EKS now provides network monitoring visualizations in the {aws} console that accelerate and enhance precise troubleshooting for faster root cause analysis. You can also leverage these visual capabilities to pinpoint top-talkers and network flows causing retransmissions and retransmission timeouts, eliminating blind spots during incidents. - -These capabilities are enabled by https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor.html[Amazon CloudWatch Network Flow Monitor]. - -== Use cases - -=== Measure network performance to detect anomalies -Several teams standardize on an observability stack that allows them to measure their system’s performance, visualize system metrics and be alarmed in the event that a specific threshold is breached. Container network observability in EKS aligns with this by exposing key system metrics that you can scrape to broaden observability of your system’s network performance at the pod and worker node level. - -=== Leverage console visualizations for more precise troubleshooting -In the event of an alarm from your monitoring system, you may want to hone in on the cluster and workload where an issue originated from. To support this, you can leverage visualizations in the EKS console that narrow the scope of investigation at a cluster level, and accelerate the disclosure of the network flows responsible for the most retransmissions, retransmission timeouts, and the volume of data transferred. - -=== Track top-talkers in your Amazon EKS environment -A lot of teams run EKS as the foundation for their platforms, making it the focal point for an application environment’s network activity. Using the network monitoring capabilities in this feature, you can track which workloads are responsible for the most traffic (measured by data volume) within the cluster, across AZs, as well as traffic to external destinations within {aws} (DynamoDB and S3) and beyond the {aws} cloud (the internet or on-prem). Additionally, you can monitor the performance of each of these flows based on retransmissions, retransmission timeouts, and data transferred. - -== Features - -. Performance metrics - This feature allows you to scrape network-related system metrics for pods and worker nodes directly from the Network Flow Monitor (NFM) Agent running in your EKS cluster. -. Service map - This feature dynamically visualizes intercommunication between workloads in the cluster, allowing you to quickly disclose key metrics (retransmissions - RT, retransmission timeouts - RTO, and data transferred - DT) associated with network flows between communicating pods. -. Flow table - With this table, you can monitor the top talkers across the Kubernetes workloads in your cluster from three different angles: {aws} service view, cluster view, and external view. For each view, you can see the retransmissions, retransmission timeouts, and data transferred between the source pod and its destination. - * {aws} service view: Shows top talkers to {aws} services (DynamoDB and S3) - * Cluster view: Shows top talkers within the cluster (east ← to → west) - * External view: Shows top talkers to cluster-external destinations outside {aws} - -== Get started -To get started, enable Container Network Observability in the EKS console for a new or existing cluster. This will automate the creation of Network Flow Monitor (NFM) dependencies (https://docs.aws.amazon.com/networkflowmonitor/2.0/APIReference/API_CreateScope.html[Scope] and https://docs.aws.amazon.com/networkflowmonitor/2.0/APIReference/API_CreateMonitor.html[Monitor] resources). In addition, you will have to install the https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-agents-kubernetes-eks.html[Network Flow Monitor Agent add-on]. Alternatively, you can install these dependencies using the `{aws} CLI`, https://docs.aws.amazon.com/eks/latest/APIReference/API_Operations_Amazon_Elastic_Kubernetes_Service.html[EKS APIs] (for the add-on), https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-API-operations.html[NFM APIs] or Infrastructure as Code (like https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkflowmonitor_monitor[Terraform]). Once these dependencies are in place, you can configure your preferred monitoring tool to scrape network performance metrics for pods and worker nodes from the NFM agent. To visualize the network activity and performance of your workloads, you can navigate to the EKS console under the “Network” tab of the cluster’s observability dashboard. - -When using Network Flow Monitor in EKS, you can maintain your existing observability workflow and technology stack while leveraging a set of additional features which further enable you to understand and optimize the network layer of your EKS environment. You can learn more about the https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor.pricing.html[Network Flow Monitor pricing here]. - -== Prerequisites and important notes - -. 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 - -==== EKS add-on for NFM agent -You can use the `CloudWatchNetworkFlowMonitorAgentPublishPolicy` https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchNetworkFlowMonitorAgentPublishPolicy.html[{aws} managed policy] with Pod Identity. This policy contains permissions for the NFM agent to send telemetry reports (metrics) to a Network Flow Monitor endpoint. -[source,json,subs="verbatim,attributes"] ----- -{ - "Version" : "2012-10-17", - "Statement" : [ - { - "Effect" : "Allow", - "Action" : [ - "networkflowmonitor:Publish" - ], - "Resource" : "*" - } - ] -} ----- - -==== Container Network Observability in the EKS console -The following permissions are required to enable the feature and visualize the service map and flow table in the console. -[source,json,subs="verbatim,attributes"] ----- -{ - "Version" : "2012-10-17", - "Statement" : [ - { - "Effect": "Allow", - "Action": [ - "networkflowmonitor:ListScopes", - "networkflowmonitor:ListMonitors", - "networkflowmonitor:GetScope", - "networkflowmonitor:GetMonitor", - "networkflowmonitor:CreateScope", - "networkflowmonitor:CreateMonitor", - "networkflowmonitor:TagResource", - "networkflowmonitor:StartQueryMonitorTopContributors", - "networkflowmonitor:StopQueryMonitorTopContributors", - "networkflowmonitor:GetQueryStatusMonitorTopContributors", - "networkflowmonitor:GetQueryResultsMonitorTopContributors" - ], - "Resource": "*" - } - ] -} ----- - -== Using {aws} CLI, EKS API and NFM API - -[source,bash] ----- -#!/bin/bash - -# Script to create required Network Flow Monitor resources -set -e - -CLUSTER_NAME="my-eks-cluster" -CLUSTER_ARN="arn:aws:eks:{Region}:{Account}:cluster/{ClusterName}" -REGION="us-west-2" -AGENT_NAMESPACE="amazon-network-flow-monitor" - -echo "Creating Network Flow Monitor resources..." - -# Check if Network Flow Monitor agent is running in the cluster -echo "Checking for Network Flow Monitor agent in cluster..." -if kubectl get pods -n "$AGENT_NAMESPACE" --no-headers 2>/dev/null | grep -q "Running"; then - echo "Network Flow Monitor agent exists and is running in the cluster" -else - echo "Network Flow Monitor agent not found. Installing as EKS addon..." - aws eks create-addon \ - --cluster-name "$CLUSTER_NAME" \ - --addon-name "$AGENT_NAMESPACE" \ - --region "$REGION" - echo "Network Flow Monitor addon installation initiated" -fi - -# Get Account ID -ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) - -echo "Cluster ARN: $CLUSTER_ARN" -echo "Account ID: $ACCOUNT_ID" - -# Check for existing scope -echo "Checking for existing Network Flow Monitor Scope..." -EXISTING_SCOPE=$(aws networkflowmonitor list-scopes --region $REGION --query 'scopes[0].scopeArn' --output text 2>/dev/null || echo "None") - -if [ "$EXISTING_SCOPE" != "None" ] && [ "$EXISTING_SCOPE" != "null" ]; then - echo "Using existing scope: $EXISTING_SCOPE" - SCOPE_ARN=$EXISTING_SCOPE -else - echo "Creating new Network Flow Monitor Scope..." - SCOPE_RESPONSE=$(aws networkflowmonitor create-scope \ - --targets "[{\"targetIdentifier\":{\"targetId\":{\"accountId\":\"${ACCOUNT_ID}\"},\"targetType\":\"ACCOUNT\"},\"region\":\"${REGION}\"}]" \ - --region $REGION \ - --output json) - - SCOPE_ARN=$(echo $SCOPE_RESPONSE | jq -r '.scopeArn') - echo "Scope created: $SCOPE_ARN" -fi - -# Create Network Flow Monitor with EKS Cluster as local resource -echo "Creating Network Flow Monitor..." -MONITOR_RESPONSE=$(aws networkflowmonitor create-monitor \ - --monitor-name "${CLUSTER_NAME}-monitor" \ - --local-resources "type=AWS::EKS::Cluster,identifier=${CLUSTER_ARN}" \ - --scope-arn "$SCOPE_ARN" \ - --region $REGION \ - --output json) - -MONITOR_ARN=$(echo $MONITOR_RESPONSE | jq -r '.monitorArn') - -echo "Monitor created: $MONITOR_ARN" - -echo "Network Flow Monitor setup complete!" -echo "Monitor ARN: $MONITOR_ARN" -echo "Scope ARN: $SCOPE_ARN" -echo "Local Resource: AWS::EKS::Cluster (${CLUSTER_ARN})" ----- - -== Using Infrastructure as Code (IaC) - -=== Terraform - -If you are using Terraform to manage your {aws} cloud infrastructure, you can include the following resource configurations to enable Container Network Observability for your cluster. - -===== NFM Scope - -[source,terraform] ----- -data "aws_caller_identity" "current" {} - -resource "aws_networkflowmonitor_scope" "example" { - target { - region = "us-east-1" - target_identifier { - target_type = "ACCOUNT" - target_id { - account_id = data.aws_caller_identity.current.account_id - } - } - } - - tags = { - Name = "example" - } -} ----- - -===== NFM Monitor - -[source,terraform] ----- -resource "aws_networkflowmonitor_monitor" "example" { - monitor_name = "eks-cluster-name-monitor" - scope_arn = aws_networkflowmonitor_scope.example.scope_arn - - local_resource { - type = "AWS::EKS::Cluster" - identifier = aws_eks_cluster.example.arn - } - - remote_resource { - type = "AWS::Region" - identifier = "us-east-1" # this must be the same region that the cluster is in - } - - tags = { - Name = "example" - } -} ----- - -===== EKS add-on for NFM - -[source,terraform] ----- -resource "aws_eks_addon" "example" { - cluster_name = aws_eks_cluster.example.name - addon_name = "aws-network-flow-monitoring-agent" -} ----- - -== How does it work? - -=== Performance metrics - -==== System metrics -If you are running third party (3P) tooling to monitor your EKS environment (such as Prometheus and Grafana), you can scrape the supported system metrics directly from the Network Flow Monitor agent. These metrics can be sent to your monitoring stack to expand measurement of your system’s network performance at the pod and worker node level. The available metrics are listed in the table, under Supported system metrics. - -image::images/nfm-eks-metrics-workflow.png[Illustration of scraping system metrics] - -To enable these metrics, override the following environment variables using the configuration variables during the installation process (see: https://aws.amazon.com/blogs/containers/amazon-eks-add-ons-advanced-configuration/): - -[source,yaml] ----- -OPEN_METRICS: - Enable or disable open metrics. Disabled if not supplied - Type: String - Values: [“on”, “off”] -OPEN_METRICS_ADDRESS: - Listening IP address for open metrics endpoint. Defaults to 127.0.0.1 if not supplied - Type: String -OPEN_METRICS_PORT: - Listening port for open metrics endpoint. Defaults to 80 if not supplied - Type: Integer - Range: [0..65535] ----- - -==== Flow level metrics -In addition, Network Flow Monitor captures network flow data along with flow level metrics: retransmissions, retransmission timeouts, and data transferred. This data is processed by Network Flow Monitor and visualized in the EKS console to surface traffic in your cluster’s environment, and how it’s performing based on these flow level metrics. - -The diagram below depicts a workflow in which both types of metrics (system and flow level) can be leveraged to gain more operational intelligence. - -image::images/nfm-eks-metrics-types-workflow.png[Illustration of workflow with different performance metrics] - -. The platform team can collect and visualize system metrics in their monitoring stack. With alerting in place, they can detect network anomalies or issues impacting pods or worker nodes using the system metrics from the NFM agent. -. As a next step, platform teams can leverage the native visualizations in the EKS console to further narrow the scope of investigation and accelerate troubleshooting based on flow representations and their associated metrics. - -Important note: The scraping of system metrics from the NFM agent and the process of the NFM agent pushing flow-level metrics to the NFM backend are independent processes. - -===== Supported system metrics - -Important note: system metrics are exported in https://openmetrics.io/[OpenMetrics] format. - -[%header,cols="4"] -|==== - -|Metric name -|Type -|Dimensions -|Description - -|ingress_flow -|Gauge -|instance_id, iface, pod, namespace, node -|Ingress TCP flow count (TcpPassiveOpens) - -|egress_flow -|Gauge -|instance_id, iface, pod, namespace, node -|Egress TCP flow count (TcpActiveOpens) - -|ingress_packets -|Gauge -|instance_id, iface, pod, namespace, node -|Ingress packet count (delta) - -|egress_packets -|Gauge -|instance_id, iface, pod, namespace, node -|Egress packet count (delta) - -|ingress_bytes -|Gauge -|instance_id, iface, pod, namespace, node -|Ingress bytes count (delta) - -|egress_bytes -|Gauge -|instance_id, iface, pod, namespace, node -|Egress bytes count (delta) - -|bw_in_allowance_exceeded -|Gauge -|instance_id, eni, node -|Packets queued/dropped due to inbound bandwidth limit - -|bw_out_allowance_exceeded -|Gauge -|instance_id, eni, node -|Packets queued/dropped due to outbound bandwidth limit - -|pps_allowance_exceeded -|Gauge -|instance_id, eni, node -|Packets queued/dropped due to bidirectional PPS limit - -|conntrack_allowance_exceeded -|Gauge -|instance_id, eni, node -|Packets dropped due to connection tracking limit - -|linklocal_allowance_exceeded -|Gauge -|instance_id, eni, node -|Packets dropped due to local proxy service PPS limit - -|==== - -===== Supported flow level metrics - -[%header,cols="3"] -|=== - -|Metric name -|Type -|Description - -|TCP retransmissions -|Counter -|Number of times a sender resends a packet that was lost or corrupted during transmission. - -|TCP retransmission timeouts -|Counter -|Number of times a sender initiated a waiting period to determine if a packet was lost in transit. - -|Data (bytes) transferred -|Counter -|Volume of data transferred between a source and destination for a given flow. - -|=== - -=== Service map and flow table - -image::images/nfm-eks-workflow.png[Illustration of how NFM works with EKS] - -. When installed, the Network Flow Monitor agent runs as a DaemonSet on every worker node and collects the top 500 network flows (based on volume of data transferred) every 30 seconds. -. These network flows are sorted into the following categories: Intra AZ, Inter AZ, EC2 → S3, EC2 → DynamoDB (DDB), and Unclassified. Each flow has 3 metrics associated with it: retransmissions, retransmission timeouts, and data transferred (in bytes). - * Intra AZ - network flows between pods in the same AZ - * Inter AZ - network flows between pods in different AZs - * EC2 → S3 - network flows from pods to S3 - * EC2 → DDB - network flows from pods to DDB - * Unclassified - network flows from pods to the Internet or on-prem -. Network flows from the Network Flow Monitor Top Contributors API are used to power the following experiences in the EKS console: - * Service map: Visualization of network flows within the cluster (Intra AZ and Inter AZ). - * Flow table: Table presentation of network flows within the cluster (Intra AZ and Inter AZ), from pods to {aws} services (EC2 → S3 and EC2 → DDB), and from pods to external destinations (Unclassified). - -The network flows pulled from the Top Contributors API are scoped to a 1 hour time range, and can include up to 500 flows from each category. For the service map, this means up to 1000 flows can be sourced and presented from the Intra AZ and Inter AZ flow categories over a 1 hour time range. For the flow table, this means that up to 3000 network flows can be sourced and presented from all 6 network flow categories over a 2 hour time range. - -===== Example: Service map - -_Deployment view_ - -image::images/ecommerce-deployment.png[Illustration of service map with ecommerce app in deployment view] - -_Pod view_ - -image::images/ecommerce-pod.png[Illustration of service map with ecommerce app in pod view] - -_Deployment view_ - -image::images/photo-gallery-deployment.png[Illustration of service map with photo-gallery app in deployment view] - -_Pod view_ - -image::images/photo-gallery-pod.png[Illustration of service map with photo-gallery app in pod view] - -===== Example: Flow table - -_{aws} service view_ - -image::images/aws-service-view.png[Illustration of flow table view] - -_Cluster view_ - -image::images/cluster-view.png[Illustration of flow table in cluster view] - -== Considerations and limitations -* Container Network Observability in EKS is only available in regions where https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-Regions.html[Network Flow Monitor is supported]. -* 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. - diff --git a/latest/ug/observability/eks-observe.adoc b/latest/ug/observability/eks-observe.adoc index 31dd34372..5a19c5e3c 100644 --- a/latest/ug/observability/eks-observe.adoc +++ b/latest/ug/observability/eks-observe.adoc @@ -144,8 +144,6 @@ The following table describes various logging tool options. include::observability-dashboard.adoc[leveloffset=+1] -include::container-network-observability.adoc[leveloffset=+1] - include::prometheus.adoc[leveloffset=+1] include::cloudwatch.adoc[leveloffset=+1] 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..b85035c60 100644 --- a/latest/ug/quickstart.adoc +++ b/latest/ug/quickstart.adoc @@ -10,36 +10,47 @@ 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]. +// GDC: this page will need to check if builds -<> 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. +Deploy a game application and persist its data on Amazon EKS + +This quickstart tutorial shows 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]. Amazon EKS Auto Mode automates routine tasks for cluster block storage, networking, load balancing, and compute autoscaling. + +As we progress, we'll walk you through the cluster setup process. Amazon EKS Auto Mode will automate tasks for creating a node using an EC2 managed instance, creating an application load balancer, and creating an EBS volume. -In summary, you'll deploy a sample workload with the custom annotations needed for seamless integration with {aws} services. +Overall, you'll deploy a sample workload with the custom annotations required to fully integrate with {aws} services. == In this tutorial 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. -- *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. -- *External App Access*: Use the load balancing capability of EKS Auto Mode to dynamically provision an Application Load Balancer (ALB). +*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. + +*External App Access* +Use the load balancing capability of EKS Auto Mode to dynamically provision an Application Load Balancer (ALB). == Prerequisites -Before you start, make sure you have performed the following tasks: +Before you begin, ensure you have the following prerequisites set up to use Amazon EKS: + +* Set up {aws} CLI and configure credentials +* Install eksctl +* Install kubectl -* link:eks/latest/userguide/setting-up.html[Setup your environment for Amazon EKS,type="documentation"] -* https://eksctl.io/installation/[Install the latest version of eksctl] +For more information, see <>. == Configure the cluster 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, such as `us-east-1`: ```yaml apiVersion: eksctl.io/v1alpha5 @@ -54,7 +65,7 @@ autoModeConfig: ``` Now, we're ready to create the cluster. -Create the EKS cluster using the `cluster-config.yaml``: +Create the Amazon EKS cluster: ```bash eksctl create cluster -f cluster-config.yaml @@ -68,10 +79,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 +102,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 +129,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,17 +269,17 @@ 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. +== Delete your cluster and nodes -Delete the CloudFormation stack: +After you've finished with the cluster that you created for this tutorial, you should clean up by deleting the cluster with the following command. If you want to do more with this cluster before you clean up, see Next steps. ```bash eksctl delete cluster -f ./cluster-config.yaml -``` \ No newline at end of file +``` + +EKS will automatically clean up any nodes it provisioned when the cluster is deleted. 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-awsmanpol.adoc b/latest/ug/security/iam-reference/security-iam-awsmanpol.adoc index 045f2610c..f23f1e29e 100644 --- a/latest/ug/security/iam-reference/security-iam-awsmanpol.adoc +++ b/latest/ug/security/iam-reference/security-iam-awsmanpol.adoc @@ -84,7 +84,6 @@ This policy includes the following permissions that allow Amazon EKS to complete To view the latest version of the JSON policy document, see link:aws-managed-policy/latest/reference/AmazonEKSFargatePodExecutionRolePolicy.html#AmazonEKSFargatePodExecutionRolePolicy-json[AmazonEKSFargatePodExecutionRolePolicy,type="documentation"] in the {aws} Managed Policy Reference Guide. - [#security-iam-awsmanpol-AmazonEKSConnectorServiceRolePolicy] == {aws} managed policy: AmazonEKSConnectorServiceRolePolicy :info_titleabbrev: AmazonEKSConnectorServiceRolePolicy @@ -231,26 +230,6 @@ The policy also includes several condition checks to ensure that the permissions To view the latest version of the JSON policy document, see link:aws-managed-policy/latest/reference/AmazonEKSLoadBalancingPolicy.html#AmazonEKSLoadBalancingPolicy-json[AmazonEKSLoadBalancingPolicy,type="documentation"] in the {aws} Managed Policy Reference Guide. -[#security-iam-awsmanpol-amazoneksmcpreadonlyaccess] -== {aws} managed policy: AmazonEKSMCPReadOnlyAccess -:info_titleabbrev: AmazonEKSMCPReadOnlyAccess - -You can attach `AmazonEKSMCPReadOnlyAccess` to your IAM entities. This policy provides read-only access to Amazon EKS resources and related {aws} services, enabling the Amazon EKS Model Context Protocol (MCP) Server to perform observability and troubleshooting operations without making any modifications to your infrastructure. - -*Permissions details* - -This policy includes the following permissions that allow principals to complete the following tasks: - -* *`eks`* &endash; Allows principals to describe and list EKS clusters, node groups, add-ons, access entries, insights, and access the Kubernetes API for read-only operations. -* *`iam`* &endash; Allows principals to retrieve information about IAM roles, policies, and their attachments to understand the permissions associated with EKS resources. -* *`ec2`* &endash; Allows principals to describe VPCs, subnets, and route tables to understand the network configuration of EKS clusters. -* *`sts`* &endash; Allows principals to retrieve caller identity information for authentication and authorization purposes. -* *`logs`* &endash; Allows principals to start queries and retrieve query results from CloudWatch Logs for troubleshooting and monitoring. -* *`cloudwatch`* &endash; Allows principals to retrieve metric data for monitoring cluster and workload performance. -* *`eks-mcp`* &endash; Allows principals to invoke MCP operations and call read-only tools within the Amazon EKS MCP Server. - -To view the latest version of the JSON policy document, see link:aws-managed-policy/latest/reference/AmazonEKSMCPReadOnlyAccess.html[AmazonEKSMCPReadOnlyAccess,type="documentation"] in the {aws} Managed Policy Reference Guide. - [#security-iam-awsmanpol-amazoneksservicepolicy] == {aws} managed policy: AmazonEKSServicePolicy :info_titleabbrev: AmazonEKSServicePolicy @@ -387,7 +366,7 @@ To view the latest version of the JSON policy document, see link:aws-managed-pol == {aws} managed policy: AmazonEBSCSIDriverPolicy :info_titleabbrev: AmazonEBSCSIDriverPolicy -The `AmazonEBSCSIDriverPolicy` policy allows the Amazon EBS Container Storage Interface (CSI) driver to create, modify, copy, attach, detach, and delete volumes on your behalf. This includes modifying tags on existing volumes and enabling Fast Snapshot Restore (FSR) on EBS volumes. It also grants the EBS CSI driver permissions to create, restore, and delete snapshots, and to list your instances, volumes, and snapshots. +The `AmazonEBSCSIDriverPolicy` policy allows the Amazon EBS Container Storage Interface (CSI) driver to create, modify, attach, detach, and delete volumes on your behalf. This includes modifying tags on existing volumes and enabling Fast Snapshot Restore (FSR) on EBS volumes. It also grants the EBS CSI driver permissions to create, restore, and delete snapshots, and to list your instances, volumes, and snapshots. To view the latest version of the JSON policy document, see link:aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html#AmazonEBSCSIDriverPolicy-json[AmazonEBSCSIDriverServiceRolePolicy,type="documentation"] in the {aws} Managed Policy Reference Guide. @@ -451,14 +430,6 @@ https://github.com/awsdocs/amazon-eks-user-guide/commits/mainline/latest/ug/secu |Description |Date -|Introduced <>. -|Amazon EKS introduced new managed policy `AmazonEKSMCPReadOnlyAccess` to enable read-only tools in the Amazon EKS MCP Server for observability and troubleshooting. -|November 21, 2025 - -|Added permissions to <>. -|Added `ec2:CopyVolumes` permission to allow the EBS CSI Driver to copy EBS volumes directly. -|November 17, 2025 - |Added permission to <>. |Added `ec2:DescribeRouteTables` and `ec2:DescribeNetworkAcls` permissions to `AmazonEKSServiceRolePolicy`. This allows Amazon EKS to detect configuration issues with VPC route tables and network ACLs for hybrid nodes as part of cluster insights. |Oct 22, 2025 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/storage/storage.adoc b/latest/ug/storage/storage.adoc index 8d66f04f0..301929e62 100644 --- a/latest/ug/storage/storage.adoc +++ b/latest/ug/storage/storage.adoc @@ -9,7 +9,7 @@ include::../attributes.txt[] This chapter covers storage options for Amazon EKS clusters. -- -You can use a range of {aws} storage services with Amazon EKS for the storage needs of your applications. Through an {aws}-supported breadth of Container Storage Interface (CSI) drivers, you can easily use Amazon EBS, Amazon S3, Amazon EFS, Amazon FSX, and Amazon File Cache for the storage needs of your applications running on Amazon EKS. To manage backups of your Amazon EKS cluster, see link:aws-backup/latest/devguide/working-with-supported-services.html#working-with-eks[{aws} Backup support for Amazon EKS,type="documentation"]. +You can use a range of {aws} storage services with Amazon EKS for the storage needs of your applications. Through an {aws}-supported breadth of Container Storage Interface (CSI) drivers, you can easily use Amazon EBS, Amazon S3, Amazon EFS, Amazon FSX, and Amazon File Cache for the storage needs of your applications running on Amazon EKS. This chapter covers storage options for Amazon EKS clusters. diff --git a/latest/ug/tools/amazon-q-integration.adoc b/latest/ug/tools/amazon-q-integration.adoc deleted file mode 100644 index 137310666..000000000 --- a/latest/ug/tools/amazon-q-integration.adoc +++ /dev/null @@ -1,49 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#amazon-q-integration] -= Use Amazon Q Developer on the Amazon EKS console -:info_titleabbrev: Amazon Q - -Amazon Elastic Kubernetes Service (EKS) integrates with Amazon Q to provide AI-powered troubleshooting directly in the {aws} Management Console. This integration helps you quickly investigate and resolve cluster, control plane, node, and workload issues with AI assistance from Amazon Q. - -== How it works - -The Amazon EKS console displays **Inspect with Amazon Q** buttons contextually alongside errors or issues throughout the console. When you click this button, Amazon Q automatically analyzes the issue and opens a chat panel on the right side of the console with investigation results, root cause analysis, and suggested mitigation steps. - -The integration appears in the following locations within the Amazon EKS console: - -* **Cluster health** - Investigate cluster health issues and status messages in the Cluster health tab in observability dashboard -* **Control plane** - Troubleshoot control plane component errors and warnings in Control plane monitoring in observability dashboard -* **Upgrade insights** - Analyze potential upgrade blockers and compatibility issues in Upgrade insights in observability dashboard -* **Node health** - Investigate node-level issues affecting cluster capacity in Node health issues in observability dashboard -* **Workloads** - Analyze Kubernetes events on pods indicating failures or issues - - -== Using Amazon Q for troubleshooting - -**To investigate an issue with Amazon Q** - -1. Open the link:eks/home#/clusters[Amazon EKS console,type="console"]. -2. Choose the name of the cluster to investigate. -3. When you encounter an error message or issue indicator, look for the **Inspect with Amazon Q** button. The button appears contextually next to the issue or in the error status details view. -4. Choose **Inspect with Amazon Q**. -5. Amazon Q automatically investigates the issue and displays the analysis in a chat panel on the right side of the console. -6. Review the investigation results, including root cause analysis and suggested mitigation steps. -7. You can continue the conversation by asking Amazon Q follow-up questions about the issue. - -**Note** -The Amazon Q integration only appears when there is an error, warning, or issue requiring investigation. It does not appear when resources are healthy. - -== Considerations - -Consider the following when using Amazon Q with Amazon EKS: - - -* **Read-only operations** - The Amazon Q integration performs only read operations on your cluster resources. It does not make any mutating or write actions to your cluster configuration or workloads. -* **Cross-region processing** - Amazon Q may process data across {aws} regions to provide AI-powered analysis. For more information about cross-region processing, see link:https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/cross-region-processing.html[Cross-region processing] in the _Amazon Q Developer User Guide_. -* **{aws} Management Console only** - This integration is available only through the {aws} Management Console. It is not available through the {aws} CLI, {aws} APIs, or infrastructure as code tools. - -== Learn more - -For more information about using Amazon Q, see link:https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/chat-with-q.html[Chat with Amazon Q] in the _Amazon Q Developer User Guide_. diff --git a/latest/ug/tools/eks-mcp-getting-started.adoc b/latest/ug/tools/eks-mcp-getting-started.adoc deleted file mode 100644 index b17fa07bd..000000000 --- a/latest/ug/tools/eks-mcp-getting-started.adoc +++ /dev/null @@ -1,675 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-mcp-getting-started] -= Getting Started with the Amazon EKS MCP Server -:info_titleabbrev: Get started - -This guide walks you through the steps to setup and use the EKS MCP Server with your AI code assistants. You'll learn how to configure your environment, connect to the server, and start managing your EKS clusters through natural language interactions. - -[NOTE] -==== -The Amazon EKS MCP Server is in preview release for Amazon EKS and is subject to change. -==== - -== Prerequisites - -Before you start, make sure you have performed the following tasks: - -* link:https://aws.amazon.com/resources/create-account/[Create an {aws} account with access to Amazon EKS] -* link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html[Install and configure the {aws} CLI with credentials] -* link:https://www.python.org/downloads/release/python-3100/[Install Python 3.10+] -* link:https://docs.astral.sh/uv/getting-started/installation/[Install `uv`] - -== Setup - -=== 1. Verify prerequisites - -[source,bash] ----- -# Check that your Python version is 3.10 or higher -python3 --version - -# Check uv installation -uv --version - -# Verify CLI configuration -aws configure list ----- - -=== 2. Setup IAM permissions - -To connect to the EKS MCP server, your link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html[IAM role] must have the following policies attached: *`eks-mcp:InvokeMcp`* (required permissions for initialization and retrieving information about available tools), *`eks-mcp:CallReadOnlyTool`* (required permissions for usage of read only tools), and *`eks-mcp:CallPrivilegedTool`* (required permissions for usage of full access (write) tools). These `eks-mcp` permissions are included in the read-only and full-access {aws} managed policies provided, below. - -* Open the link:https://console.aws.amazon.com/iam/[IAM console]. -* In the left navigation pane, choose *Users*, *User groups*, or *Roles* depending on the identity you want to attach the policy to, then the name of the specific user, group, or role. -* Choose the *Permissions* tab. -* Choose *Attach policies* (or *Add permissions* if it's the first time). -* In the policy list, search for and select the managed policy you want to attach: - * *Read-only operations*: AmazonEKSMCPReadOnlyAccess -* Choose *Attach policies* (or *Next* and then *Add permissions* to confirm). - -This attaches the policy, and the permissions take effect immediately. You can attach multiple policies to the same identity, and each can contain various permissions. To learn more about these policies, see link:https://docs.aws.amazon.com/eks/latest/userguide/security-iam-awsmanpol.html[{aws} managed policies for Amazon Elastic Kubernetes Service]. - -=== 3. Choose an AI assistant - -Choose one of the following MCP-compatible AI assistants or any MCP-compatible tool: - -* link:https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html[Install Amazon Q Developer CLI] -* link:https://kiro.dev/docs/getting-started/installation/[Install Kiro] -* link:https://cursor.com/download[Install Cursor] -* link:https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev[Install Cline VS Code Extension] - -== Step 1: Configure your AI assistant - -Choose from any one of the following options to setup your AI code assistant. Completing this step sets up your AI code assistant to use the MCP Proxy for {aws}, which is required for secure, authenticated access to the Amazon EKS MCP Server. This involves adding or editing the MCP configuration file (e.g., `~/.aws/amazonq/mcp.json` for Amazon Q Developer CLI). The proxy acts as a client-side bridge, handling {aws} SigV4 authentication using your local {aws} credentials and enabling dynamic tool discovery for interacting with backend {aws} MCP servers like the EKS MCP Server. To learn more, see the link:https://github.com/aws/mcp-proxy-for-aws[_MCP Proxy for {aws} repository_]. - -=== Option A: Amazon Q Developer CLI - -The Q Developer CLI provides the most integrated experience with the EKS MCP Server. - -==== 1. Locate MCP Configuration File - -* *macOS/Linux*: `~/.aws/q/mcp.json` -* *Windows*: `%USERPROFILE%\.aws\q\mcp.json` - -==== 2. Add MCP Server Configuration - -Create the configuration file if it doesn't exist. Be sure to replace the region (`{region}`) placeholder with your desired region. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*Security note*: `--read-only` can be used to only allow read-only tool operations. - -==== 3. Verify Configuration - -Restart Q Developer CLI, then check available tools: - -[source] ----- -q /tools ----- - -=== Option B: Kiro IDE - -Kiro is an AI-first coding workspace with built-in link:https://kiro.dev/docs/mcp/[MCP support]. - -==== 1. Open Kiro Settings - -* Open Kiro -* Go to *Kiro* → *Settings* and search for "MCP Config" -* Or press `Cmd+Shift+P,` (Mac) or `Ctrl+Shift+P,` (Windows/Linux) and search for "MCP Config" - -==== 2. Add MCP Server Configuration - -* Click "Open Workspace MCP Config" or "Open User MCP Config" to edit the MCP configuration file directly. - -Be sure to replace the region (`{region}`) placeholder with your desired region. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*Security note*: `--read-only` can be used to only allow read-only tool operations. - -=== Option C: Cursor IDE - -Cursor provides built-in MCP support with a graphical configuration interface. - -==== 1. Open Cursor Settings - -* Open Cursor -* Go to *Settings* → *Cursor Settings* → *Tools & MCP* -* Or press `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows) and search for "MCP" - -==== 2. Add MCP Server Configuration - -* Click "New MCP Server" - -Create the configuration file if it doesn't exist. Be sure to replace the region (`{region}`) placeholder with your desired region. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*Security note*: `--read-only` can be used to only allow read-only tool operations. - -==== 3. Restart Cursor - -Close and reopen Cursor for the changes to take effect. - -==== 4. Verify in Cursor chat - -Open the chat panel and try: - -[source] ----- -What EKS MCP tools are available? ----- - -You should see a list of available EKS management tools. - -=== Option D: Cline (VS Code Extension) - -Cline is a popular VS Code extension that brings AI assistance directly into your editor. - -==== 1. Open Cline Settings - -* Open Cline -* Press `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows) and search for "MCP" - -==== 2. Add MCP Server Configuration - -* Click "Add Server" -* Click "Open User Configuration" - -Create the configuration file if it doesn't exist. Be sure to replace the region (`{region}`) placeholder with your desired region. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "{region}" - ] - } - } -} ----- - -*Security note*: `--read-only` can be used to only allow read-only tool operations. - -==== 2. Reload VS Code - -Press `Cmd+Shift+P` / `Ctrl+Shift+P` and select "Developer: Reload Window" - -==== 3. Verify configuration - -Open Cline and ask: - -[source] ----- -List the available MCP tools for EKS ----- - -== Step 2: (Optional) Create a "write" policy - -Optionally, you can create a link:https://docs.aws.amazon.com/privateca/latest/userguide/auth-CustManagedPolicies.html[customer-managed IAM policy] that provides full access to the Amazon EKS MCP server. This policy grants permissions to use all tools in the EKS MCP server, including both privileged tools that may involve write operations and read-only tools. Note that high-risk permissions (anything with Delete*, or unrestricted IAM resource) are included in this policy, as they're required for setup/teardown of the cluster resources in the *manage_eks_stacks* tool. - -[source,bash] ----- -aws iam create-policy \ - --policy-name EKSMcpWriteManagementPolicy \ - --policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"eks:DescribeCluster\", \"eks:ListClusters\", \"eks:DescribeNodegroup\", \"eks:ListNodegroups\", \"eks:DescribeAddon\", \"eks:ListAddons\", \"eks:DescribeAccessEntry\", \"eks:ListAccessEntries\", \"eks:DescribeInsight\", \"eks:ListInsights\", \"eks:AccessKubernetesApi\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"eks:CreateCluster\", \"eks:DeleteCluster\", \"eks:CreateAccessEntry\", \"eks:TagResource\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:GetRole\", \"iam:ListRolePolicies\", \"iam:ListAttachedRolePolicies\", \"iam:GetRolePolicy\", \"iam:GetPolicy\", \"iam:GetPolicyVersion\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:TagRole\", \"iam:CreateRole\", \"iam:AttachRolePolicy\", \"iam:PutRolePolicy\", \"iam:DetachRolePolicy\", \"iam:DeleteRole\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"iam:PassRole\"], \"Resource\": \"*\", \"Condition\": {\"StringEquals\": {\"iam:PassedToService\": [\"eks.amazonaws.com\", \"ec2.amazonaws.com\"]}}}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:CreateVpc\", \"ec2:CreateSubnet\", \"ec2:CreateRouteTable\", \"ec2:CreateRoute\", \"ec2:CreateInternetGateway\", \"ec2:CreateNatGateway\", \"ec2:CreateSecurityGroup\", \"ec2:AttachInternetGateway\", \"ec2:AssociateRouteTable\", \"ec2:ModifyVpcAttribute\", \"ec2:ModifySubnetAttribute\", \"ec2:AllocateAddress\", \"ec2:CreateTags\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:DeleteVpc\", \"ec2:DeleteSubnet\", \"ec2:DisassociateRouteTable\", \"ec2:DeleteRouteTable\", \"ec2:DeleteRoute\", \"ec2:DetachInternetGateway\", \"ec2:DeleteInternetGateway\", \"ec2:DeleteNatGateway\", \"ec2:ReleaseAddress\", \"ec2:DeleteSecurityGroup\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"ec2:DescribeVpcs\", \"ec2:DescribeSubnets\", \"ec2:DescribeRouteTables\", \"ec2:DescribeInternetGateways\", \"ec2:DescribeNatGateways\", \"ec2:DescribeAddresses\", \"ec2:DescribeSecurityGroups\", \"ec2:DescribeAvailabilityZones\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"cloudformation:CreateStack\", \"cloudformation:UpdateStack\", \"cloudformation:DeleteStack\", \"cloudformation:DescribeStacks\", \"cloudformation:TagResource\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"sts:GetCallerIdentity\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"logs:StartQuery\", \"logs:GetQueryResults\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"cloudwatch:GetMetricData\"], \"Resource\": \"*\"}, {\"Effect\": \"Allow\", \"Action\": [\"eks-mcp:*\"], \"Resource\": \"*\"}]}" ----- - -== Step 3: Verify your setup - -=== Test connection - -Ask your AI assistant a simple question to verify the connection: - -[source] ----- -List all EKS clusters in my {aws} account ----- - -You should see a list of your EKS clusters. - -== Step 4: Run your first tasks - -=== Example 1: Explore your clusters - -[source] ----- -Show me all EKS clusters and their status -What insights does EKS have about my production-cluster? -Show me the VPC configuration for my staging cluster ----- - -=== Example 2: Check Kubernetes resources - -[source] ----- -Get the details of all the kubernetes resources deployed in my EKS cluster -Show me pods that are not in Running state or pods with any restarts -Get the logs from the aws-node daemonset in the last 30 minutes ----- - -=== Example 3: Troubleshoot issues - -[source] ----- -Why is my nginx-ingress-controller pod failing to start? -Search the EKS troubleshooting guide for pod networking issues -Show me events related to the failed deployment in the staging namespace ----- - -=== Example 4: Create resources (if "write" mode is enabled) - -[source] ----- -Create a new EKS cluster named demo-cluster with VPC and Auto Mode -Deploy my containerized app from ECR to the production namespace with 3 replicas -Generate a Kubernetes deployment YAML for my Node.js app running on port 3000 ----- - -== Common configurations - -=== Scenario 1: Multiple {aws} profiles - -If you work with multiple {aws} accounts, create separate MCP server configurations. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-prod": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "production", - "--region", - "us-west-2" - ] - }, - "eks-mcp-dev": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "development", - "--region", - "us-east-1" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-prod": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "production", - "--region", - "us-west-2" - ] - }, - "eks-mcp-dev": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "development", - "--region", - "us-east-1" - ] - } - } -} ----- - -=== Scenario 2: Read-only for production - -Create a read-only configuration for production environments. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-prod-readonly": { - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "production", - "--region", - "us-west-2", - "--read-only" - ], - "autoApprove": [ - "list_k8s_resources", - "get_pod_logs", - "get_k8s_events" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-prod-readonly": { - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "production", - "--region", - "us-west-2", - "--read-only" - ], - "autoApprove": [ - "list_k8s_resources", - "get_pod_logs", - "get_k8s_events" - ] - } - } -} ----- - -=== Scenario 3: Development with full access - -For development environments with full write access. - -*For Mac/Linux:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-dev-full": { - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "development", - "--region", - "us-east-1" - ] - } - } -} ----- - -*For Windows:* - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp-dev-full": { - "command": "uvx", - "args": [ - "--from", - "mcp-proxy-for-aws@latest", - "mcp-proxy-for-aws.exe", - "https://eks-mcp.{region}.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "development", - "--region", - "us-east-1" - ] - } - } -} ----- - -== Considerations - -=== Security - -Do not pass secrets or sensitive information via allowed input mechanisms: - -* Do not include secrets or credentials in YAML files applied with apply_yaml. -* Do not pass sensitive information directly in the prompt to the model. -* Do not include secrets in CloudFormation templates or application manifests. -* Avoid using MCP tools for creating Kubernetes Secrets, as this would require providing the secret data to the model. -* Avoid logging sensitive information in application logs within Kubernetes pods. - -YAML content security: - -* Only use YAML files from trustworthy sources. -* The server relies on Kubernetes API validation for YAML content and does not perform its own validation. -* Audit YAML files before applying them to your cluster. - -Instead of passing secrets through MCP: - -* Use link:https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html[{aws} Secrets Manager] or link:https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html[Parameter Store] to store sensitive information. -* Configure proper Kubernetes RBAC for service accounts. -* Use IAM roles for service accounts (IRSA) for {aws} service access from pods. - -== Next up - -For a complete list of tools and configurations, see <>. diff --git a/latest/ug/tools/eks-mcp-introduction.adoc b/latest/ug/tools/eks-mcp-introduction.adoc deleted file mode 100644 index 12f681b92..000000000 --- a/latest/ug/tools/eks-mcp-introduction.adoc +++ /dev/null @@ -1,87 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-mcp-introduction] -= Amazon EKS Model Context Protocol (MCP) Server -:info_titleabbrev: Model Context Protocol (MCP) - -[abstract] --- -Learn how to manage your Amazon EKS cluster, Kubernetes resources, diagnose issues, and query Amazon EKS documentation with the EKS MCP Server. --- - -The Amazon EKS MCP server is a fully managed service enabling AI powered experiences for development and operations. link:https://modelcontextprotocol.io/docs/getting-started/intro[Model Context Protocol (MCP)] provides a standardized interface that enriches AI agents and applications with real-time, contextual knowledge of your EKS clusters and Kubernetes resources, enabling more accurate, context-aware responses and AI-powered workflows throughout the application lifecycle, from initial setup through production optimization, and troubleshooting. - -[NOTE] -==== -The Amazon EKS MCP Server is in preview release for Amazon EKS and is subject to change. -==== - -== Overview - -The EKS MCP server can be easily integrated with any MCP compatible AI coding assistant to enhance your development workflow like link:https://kiro.dev/?trk=4e1f440a-99e0-4ad0-9a9c-6b04723ec916&sc_channel=ps&ef_id=CjwKCAiAwqHIBhAEEiwAx9cTecSJYyUgoD93aVmUNglC8epCwc2HOHHTH-dtL6FbZJaD0xmrNjN1uxoCnaUQAvD_BwE:G:s&s_kwcid=AL!4422!3!773515754057!e!!g!!aws%20kiro!23000458260!188935657567&gad_source=1&gad_campaignid=23000458260&gclid=CjwKCAiAwqHIBhAEEiwAx9cTecSJYyUgoD93aVmUNglC8epCwc2HOHHTH-dtL6FbZJaD0xmrNjN1uxoCnaUQAvD_BwE[Kiro], link:https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html[Amazon Q Developer] CLI, or third party tools like link:https://cursor.com/[Cursor] or link:https://cline.bot/[Cline]. When getting started, the EKS MCP server guides you through cluster creation, automatically provisioning prerequisites and applying {aws} best practices. During development, it simplifies EKS and Kubernetes operations by providing high-level workflows for application deployment and cluster management. For debugging and troubleshooting, the server accelerates issue-resolution through integrated troubleshooting aids and knowledge base access available on the EKS console and your favorite AI assistants. These capabilities are accessible through natural language interactions, enabling you to perform complex Kubernetes operations more intuitively and efficiently. - -The fully managed EKS MCP server is hosted in the {aws} cloud, eliminating the need for local installation and maintenance. It provides enterprise-grade capabilities like automatic updates and patching, centralized security through {aws} IAM integration, comprehensive audit logging via {aws} CloudTrail, and the proven scalability, reliability, and support of {aws}. The fully managed EKS MCP server hosted in the {aws} cloud offers the following key benefits: - -* *Eliminate installation and maintenance.* With the EKS MCP server being hosted in the {aws} cloud, you no longer need manage version updates, or troubleshoot local server issues. Simply configure your AI assistant to connect to the hosted EKS MCP server endpoint, and you're ready to start working with your EKS clusters. -* *Centralized access management.* The EKS MCP server integrates with link:https://aws.amazon.com/iam/[IAM], providing a centralized, secure way to control access to the server. All requests are signed using link:https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html[{aws} SigV4] through a lightweight proxy, enabling seamless integration with your existing {aws} credentials and IAM policies. -* *Enhanced monitoring and visibility.* {aws} CloudTrail integration captures initialization and full access tool calls made through the hosted service, enabling detailed audit trails and compliance reporting. -* *Always up-to-date.* Receive new tools, features, and bug fixes automatically without needing to update local installations. The hosted service is continuously improved based on your feedback and {aws} best practices. - -== Integration examples - -The EKS MCP Server provides several tools that you can use to: - -* *Manage your cluster* + -Create, configure, and manage EKS clusters with automated best practices. -* *Manage Kubernetes resources* + -Deploy applications, manage Kuberentes resources, and inspect cluster state. -* *Troubleshoot your cluster* + -Diagnose issues using integrated troubleshooting tools and knowledge base of runbooks -* *Query documentation* + -Search and retrieve relevant EKS documentation contextually. - -=== Explore your clusters - -[source] ----- -Show me all EKS clusters and their status -What insights does EKS have about my production-cluster? -Show me the VPC configuration for my staging cluster ----- - -=== Check Kubernetes resources - -[source] ----- -List all deployments in the production namespace -Show me pods that are not in Running state -Get the logs from the api-server pod in the last 30 minutes ----- - -=== Troubleshoot issues - -[source] ----- -Why is my nginx-ingress-controller pod failing to start? -Search the EKS troubleshooting guide for pod networking issues -Show me events related to the failed deployment in the staging namespace ----- - -=== Create resources (if "write" mode is enabled) - -[source] ----- -Create a new EKS cluster named demo-cluster with VPC and Auto Mode -Deploy my containerized app from ECR to the production namespace with 3 replicas -Generate a Kubernetes deployment YAML for my Node.js app running on port 3000 ----- - -== Get started - -To get started, see <>. - -include::eks-mcp-getting-started.adoc[leveloffset=+1] - -include::eks-mcp-tool-configurations.adoc[leveloffset=+1] - diff --git a/latest/ug/tools/eks-mcp-tool-configurations.adoc b/latest/ug/tools/eks-mcp-tool-configurations.adoc deleted file mode 100644 index 65e345444..000000000 --- a/latest/ug/tools/eks-mcp-tool-configurations.adoc +++ /dev/null @@ -1,343 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-mcp-tool-configurations] -= Amazon EKS MCP Server Tool Configuration Reference -:info_titleabbrev: Tools - -This guide shows all the configurations available for the link:https://github.com/aws/mcp-proxy-for-aws[_mcp-proxy-for-aws_] client-side tool that allows you to connect to the fully managed Amazon EKS MCP Server from your IDE. - -[NOTE] -==== -The Amazon EKS MCP Server is in preview release for Amazon EKS and is subject to change. -==== - -== Example - -[source,json] ----- -{ - "mcpServers": { - "eks-mcp": { - "disabled": false, - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-proxy-for-aws@latest", - "https://eks-mcp.us-west-2.api.aws/mcp", - "--service", - "eks-mcp", - "--profile", - "default", - "--region", - "us-east-1", - "--read-only" - ] - } - } -} ----- - -== IAM permissions - -The role used for connecting to the MCP server requires *`eks-mcp:InvokeMcp`* permissions for initialization and retrieving information about available tools. *`eks-mcp:CallReadOnlyTool`* is required for usage of read only tools and *`eks-mcp:CallPrivilegedTool`* is required for usage of full access (write) tools. - -== Environment variables - -*`AWS_PROFILE`* (optional) + -{aws} credentials profile name to use; can be overridden by the `--profile` command-line argument. - -* Example: `export AWS_PROFILE=production` - -*`AWS_REGION`* (optional) + -{aws} region for SigV4 signing; defaults to `us-west-2` if not set. - -* Example: `export AWS_REGION=us-east-1` - -== Arguments - -*SigV4 MCP endpoint URL* (required) + -The MCP endpoint URL to connect to. - -* Example: `https://eks-mcp.us-west-2.api.aws/mcp` - -*`--service`* (optional) + -{aws} service name for SigV4 signing; auto-detected from the endpoint hostname if not provided. - -* Example: `--service eks-mcp` - -*`--profile`* (optional) + -{aws} credentials profile to use. Defaults to the `AWS_PROFILE` environment variable if not specified. - -* Example: `--profile production` - -*`--region`* + -{aws} region to use. Uses `AWS_REGION` environment variable if not set, defaults to `us-east-1`. - -* Example: `--region us-west-2` - -*`--read-only`* (optional) + -Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with readOnlyHint=true). By default, all tools are enabled. - -* Example: `--read-only` - -For more configuration options, see link:https://github.com/aws/mcp-proxy-for-aws?tab=readme-ov-file#configuration-parameters[Configuration parameters]. - -== Tools - -The server exposes the following link:https://modelcontextprotocol.io/docs/concepts/tools[MCP tools]. - -=== Read only tools - -This section describes the read-only tools available for the EKS MCP Server. Note that all read-only Kubernetes API operations can access both: - -* *Private clusters* (see link:https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html#cluster-endpoint-private[Cluster private endpoint]) -* *Public clusters* - -*search_eks_documentation* + -Search EKS documentation for up-to-date information and guidance. This tool provides access to the latest EKS documentation, including new features and recent enhancements that agents may not be aware of. - -Parameters: - -* *query* (required): Your specific question or search query related to EKS documentation, features, or best practices. -* *limit* (optional): Maximum number of documentation results to return (1-10). Default: 5. - -*search_eks_troubleshooting_guide* + -Searches the EKS Troubleshoot Guide for troubleshooting information based on a query. It helps identify common problems and provides step-by-step solutions. - -Parameters: - -* *query* (required): Your specific question or issue description related to EKS troubleshooting. - -*describe_eks_resource* + -Retrieves detailed information about a specific EKS cluster resource including configuration, status, and metadata. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster (required for cluster-scoped resources). -* *resource_type* (required): The EKS resource type to describe. Valid values: - * accessentry (requires cluster_name and resource_name as principalArn) - * addon (requires cluster_name and resource_name as addon name) - * cluster (requires cluster_name), nodegroup (requires cluster_name and resource_name as nodegroup name). -* *resource_name* (optional): Name of the specific resource to describe (required for most resource types). - -*list_eks_resources* + -Lists EKS resources of a specific type, returning a summary of all resources of the specified type that are accessible. - -Parameters: - -* *resource_type* (required): The EKS resource type to list. Valid values: + - * accessentry (requires cluster_name) - * addon (requires cluster_name) - * cluster (no additional parameters required) - * nodegroup (requires cluster_name). -* *cluster_name* (optional): Name of the EKS cluster (required for cluster-scoped resources). - -*get_eks_insights* + -Retrieves EKS cluster insights and recommendations for optimization. Provides actionable insights for security, performance, and cost optimization based on {aws} best practices and cluster analysis. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster. -* *category* (optional): Optional category to filter insights by (e.g., "MISCONFIGURATION" or "UPGRADE_READINESS"). -* *insight_id* (optional): Optional ID of a specific insight to get detailed information for. -* *next_token* (optional): Optional token for pagination to get the next set of results. - -*get_eks_vpc_config* + -Retrieves VPC configuration for an EKS cluster, including subnets, route tables, and network connectivity. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster to get VPC configuration for. -* *vpc_id* (optional): ID of the specific VPC to query (optional, will use cluster VPC if not specified). - -*get_k8s_events* + -Retrieves Kubernetes events related to specific resources for troubleshooting and monitoring. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster where the resource is located. -* *kind* (required): Kind of the involved object (e.g., "Pod", "Deployment", "Service"). Must match the resource kind exactly. -* *name* (required): Name of the involved object to get events for. -* *namespace* (optional): Namespace of the involved object. Required for namespaced resources (like Pods, Deployments). Not required for cluster-scoped resources (like Nodes, PersistentVolumes). - -*get_pod_logs* + -Retrieves logs from pods in an EKS cluster with filtering options. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster where the pod is running. -* *namespace* (required): Kubernetes namespace where the pod is located. -* *pod_name* (required): Name of the pod to retrieve logs from. -* *container_name* (optional): Name of the specific container to get logs from. Required only if the pod contains multiple containers. -* *limit_bytes* (optional): Maximum number of bytes to return. Default: 10KB (10240 bytes). -* *previous* (optional): Return previous terminated container logs (defaults to false). Useful to get logs for pods that are restarting. -* *since_seconds* (optional): Only return logs newer than this many seconds. Useful for getting recent logs without retrieving the entire history. -* *tail_lines* (optional): Number of lines to return from the end of the logs. Default: 100. - -*list_api_versions* + -Lists all available API versions in the specified Kubernetes cluster. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster. - -*list_k8s_resources* + -Lists Kubernetes resources of a specific kind in an EKS cluster. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster where the resources are located. -* *kind* (required): Kind of the Kubernetes resources to list (e.g., 'Pod', 'Service', 'Deployment'). Use the `list_api_versions` tool to find available resource kinds. -* *api_version* (required): API version of the Kubernetes resources (e.g., 'v1', 'apps/v1', 'networking.k8s.io/v1'). Use the `list_api_versions` tool to find available API versions. -* *field_selector* (optional): Field selector to filter resources (e.g., 'metadata.name=my-pod,status.phase=Running'). Uses the same syntax as kubectl's --field-selector flag. -* *label_selector* (optional): Label selector to filter resources (e.g., 'app=nginx,tier=frontend'). Uses the same syntax as kubectl's `--selector` flag. -* *namespace* (optional): Namespace of the Kubernetes resources to list. If not provided, resources will be listed across all namespaces (for namespaced resources). - -*read_k8s_resource* + -Retrieves detailed information about a specific Kubernetes resource in an EKS cluster. - -Parameters: - -* *api_version* (required): API version of the Kubernetes resource (e.g., "v1", "apps/v1", "networking.k8s.io/v1"). -* *cluster_name* (required): Name of the EKS cluster where the resource is located. -* *kind* (required): Kind of the Kubernetes resource (e.g., "Pod", "Service", "Deployment"). -* *name* (required): Name of the Kubernetes resource to read. -* *namespace* (optional): Namespace of the Kubernetes resource. Required for namespaced resources. Not required for cluster-scoped resources (like Nodes, PersistentVolumes). - -*generate_app_manifest* + -Generates standardized Kubernetes deployment and service manifests for containerized applications. - -Parameters: - -* *app_name* (required): Name of the application. Used for deployment and service names, and for labels. -* *image_uri* (required): Full ECR image URI with tag (e.g., 123456789012.dkr.ecr.region.amazonaws.com/repo:tag). Must include the full repository path and tag. -* *load_balancer_scheme* (optional): {aws} load balancer scheme. Valid values: + - * "internal" (private VPC only) - * "internet-facing" (public access). - * Default: "internal". -* *cpu* (optional): CPU request for each container (e.g., "100m" for 0.1 CPU cores, "500m" for half a core). Default: "100m". -* *memory* (optional): Memory request for each container (e.g., "128Mi" for 128 MiB, "1Gi" for 1 GiB). Default: "128Mi" -* *namespace* (optional): Kubernetes namespace to deploy the application to. Default: "default". -* *port* (optional): Container port that the application listens on. Default: 80 -* *replicas* (optional): Number of replicas to deploy. Default: 2 - -*get_cloudwatch_logs* + -Queries CloudWatch logs with filtering based on the input parameters and support for standard log groups used for EKS cluster observability. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster where the resource is located. Used to construct the CloudWatch log group name. -* *resource_type* (required): Resource type to search logs for. Valid values: +"pod", "node", "container", "cluster". This determines how logs are filtered. -* *log_type* (required): Log type to query. Valid values: -+ - * "application": Container/application logs - * "host": Node-level system logs - * "performance": Performance metrics logs - * "control-plane": EKS control plane logs - * "your-log-group-name": Provide a custom CloudWatch log group name directly. -* *resource_name* (optional): Resource name to search for in log messages (e.g., pod name, node name, container name). Used to filter logs for the specific resource. -* *minutes* (optional): Number of minutes to look back for logs. Default: 15. Ignored if start_time is provided. Use smaller values for recent issues, larger values for historical analysis. -* *start_time* (optional): Start time in ISO format (e.g., "2023-01-01T00:00:00Z"). If provided, overrides the minutes parameter. -* *end_time* (optional): End time in ISO format (e.g., "2023-01-01T01:00:00Z"). If not provided, defaults to current time. -* *fields* (optional): Custom fields to include in the query results (defaults to "@timestamp, @message"). Use CloudWatch Logs Insights field syntax. -* *filter_pattern* (optional): Additional CloudWatch Logs filter pattern to apply. Uses CloudWatch Logs Insights syntax (e.g., "ERROR", "field=value"). -* *limit* (optional): Maximum number of log entries to return. Use lower values (10-50) for faster queries, higher values (100-1000) for more comprehensive results. Higher values may impact performance. - -*get_cloudwatch_metrics* + -Retrieves CloudWatch metrics and data points for EKS cluster monitoring and performance analysis. Handles Container Insights metrics, custom metrics, and configurable time periods and dimensions. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster to get metrics for. -* *dimensions* (required): Dimensions to use for the CloudWatch metric query as a JSON string. Must include appropriate dimensions for the resource type and metric (e.g., '{"ClusterName": "my-cluster", "PodName": "my-pod", "Namespace": "default"}'). -* *metric_name* (required): Metric name to retrieve. Common examples: - * `cpu_usage_total`: Total CPU usage - * `memory_rss`: Resident Set Size memory usage - * `network_rx_bytes`: Network bytes received - * `network_tx_bytes`: Network bytes transmitted -* *namespace* (required): CloudWatch namespace where the metric is stored. Common values: - * `"ContainerInsights"`: For container metrics - * `"AWS/EC2"`: For EC2 instance metrics - * `"AWS/EKS"`: For EKS control plane metrics -* *minutes* (optional): Number of minutes to look back for metrics. Default: 15. Ignored if start_time is provided. -* *start_time* (optional): Start time in ISO format (e.g., "2023-01-01T00:00:00Z"). If provided, overrides the minutes parameter. -* *end_time* (optional): End time in ISO format (e.g., "2023-01-01T01:00:00Z"). If not provided, defaults to current time. -* *limit* (optional): Maximum number of data points to return. Higher values (100-1000) provide more granular data but may impact performance. Default: 50. -* *period* (optional): Period in seconds for the metric data points. Default: 60 (1 minute). Lower values (1-60) provide higher resolution but may be less available. -* *stat* (optional): Statistic to use for the metric aggregation. Default: "Average". Valid values: + - * `Average`: Mean value during the period - * `Sum:` Total value during the period - * `Maximum`: Highest value during the period - * `Minimum`: Lowest value during the period - * `SampleCount`: Number of samples during the period. - -*get_eks_metrics_guidance* + -Get CloudWatch metrics guidance for specific resource types in EKS clusters. Useful for the agent when determining the correct dimensions to use with the get_cloudwatch_metrics tool. - -Parameters: - -* *resource_type* (required): Type of resource to get metrics for (cluster, node, pod, namespace, service). - -*get_policies_for_role* + -Retrieves all policies attached to a specified IAM role, including assume role policy, managed policies, and inline policies. - -Parameters: - -* *role_name* (required): Name of the IAM role to get policies for. The role must exist in your {aws} account. - -=== Full access (write) tools - -This section describes the read-only tools available for the EKS MCP Server. Note that (as of "today") all write Kubernetes API operations can access only: - -* *Public clusters* (endpointPublicAccess=true) - -*manage_k8s_resource* + -Manages a single Kubernetes resource with write operations (create, update, patch, or delete). - -Parameters: - -* *operation* (required): Operation to perform on the resource. Valid values: + - * `create:` Create a new resource - * `replace`: Replace an existing resource - * `patch`: Update specific fields of an existing resource - * `delete`: Delete an existing resource - * *Note*: Use read_k8s_resource for reading resources and list_k8s_resources for listing multiple resources. -* *cluster_name* (required): Name of the EKS cluster where the resource is located or will be created. -* *kind* (required): Kind of the Kubernetes resource (e.g., "Pod", "Service", "Deployment"). -* *api_version* (required): API version of the Kubernetes resource (e.g., "v1", "apps/v1", "networking.k8s.io/v1"). -* *body* (optional): Resource definition as a JSON string. Required for create, replace, and patch operations. For create and replace, this should be a complete resource definition. For patch, this should contain only the fields to update. -* *name* (optional): Name of the Kubernetes resource. Required for all operations except create (where it can be specified in the body). -* *namespace* (optional): Namespace of the Kubernetes resource. Required for namespaced resources. Not required for cluster-scoped resources (like Nodes, PersistentVolumes). - -*apply_yaml* + -Applies Kubernetes YAML manifests to an EKS cluster. - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster where the resources will be created or updated. -* *namespace* (required): Kubernetes namespace to apply resources to. Will be used for name-spaced resources that do not specify a namespace. -* *yaml_content* (required): YAML content to apply to the cluster. Can contain multiple documents separated by '---'. -* *force* (optional): Whether to update resources if they already exist (similar to kubectl apply). Set to false to only create new resources. - -*manage_eks_stacks* + -Manages EKS CloudFormation stacks with operations for generating templates, deploying, describing, and deleting EKS clusters and their underlying infrastructure. Cluster creation typically takes 15-20 minutes to complete. For deploy and delete operations, the stack must have been created by this tool (i.e., tagged with CreatedBy=EksMcpServer). - -Parameters: - -* *cluster_name* (required): Name of the EKS cluster (for generate, deploy, describe and delete operations). This name will be used to derive the CloudFormation stack name and will be embedded in the cluster resources. -* *operation* (required): Operation to perform. Valid values: + - * `generate`: Generate a CloudFormation template - * `deploy`: Deploy a CloudFormation stack (requires `template_content`) - * `describe`: Describe/read a CloudFormation stack (read-only) - * `delete`: Delete a CloudFormation stack -* *template_content* (optional): CloudFormation template content (for deploy operations). This should be the complete YAML or JSON template content. Supports both single resources and multi-document YAML content separated by '---'. - -*add_inline_policy* + -Adds a new inline policy to an IAM role. - -Parameters: - -* *permissions* (required): Permissions to include in the policy as JSON strings representing IAM policy statements. Can be either a single JSON string or an array of JSON strings. -* *policy_name* (required): Name of the inline policy to create. Must be unique within the role. -* *role_name* (required): Name of the IAM role to add the policy to. The role must exist. diff --git a/latest/ug/tools/eks-tools.adoc b/latest/ug/tools/eks-tools.adoc deleted file mode 100644 index b3aa36dc0..000000000 --- a/latest/ug/tools/eks-tools.adoc +++ /dev/null @@ -1,29 +0,0 @@ -include::../attributes.txt[] - -[.topic] -[#eks-tools] -= Amazon EKS tools -:info_titleabbrev: Tools - -[abstract] --- -Set up and configure {aws} tools to manage your Amazon EKS cluster. --- - -Amazon EKS provides a suite of {aws} tools that help you manage, troubleshoot, and interact with your EKS clusters more efficiently. These tools leverage AI-powered capabilities and standardized interfaces to simplify cluster operations, accelerate troubleshooting, and enable natural language interactions with your Kubernetes resources. Available tools include: - -* *Amazon EKS Model Context Protocol (MCP) Server* - A fully managed service that enables AI-powered experiences for EKS cluster management. The EKS MCP Server integrates with MCP-compatible AI coding assistants to provide real-time, contextual knowledge of your clusters and Kubernetes resources. Use it to manage clusters, deploy applications, troubleshoot issues, and query EKS documentation through natural language interactions. - -* *Amazon Q on the Amazon EKS console* - An AI-powered troubleshooting integration available directly in the {aws} Management Console. Amazon Q automatically analyzes cluster issues and provides investigation results, root cause analysis, and suggested mitigation steps when you encounter errors or warnings in the EKS console. - -These tools work together to provide comprehensive support throughout your EKS cluster lifecycle, from initial setup and configuration through ongoing operations and troubleshooting. Whether you're developing applications, managing infrastructure, or resolving production issues, these {aws} tools help you work more efficiently with your EKS clusters. - - -[.topiclist] -[[Topic List]] - -include::eks-mcp-introduction.adoc[leveloffset=+1] - -include::amazon-q-integration.adoc[leveloffset=+1] - - 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/creating-an-add-on.adoc b/latest/ug/workloads/creating-an-add-on.adoc index db38e5e5c..4863d9d92 100644 --- a/latest/ug/workloads/creating-an-add-on.adoc +++ b/latest/ug/workloads/creating-an-add-on.adoc @@ -121,7 +121,7 @@ eksctl create addon --help + For more information about available options see https://eksctl.io/usage/addons/[Addons] in the `eksctl` documentation. -[#create_add_on_console] +[#_create_add_on_console] == Create add-on ({aws} Console) . Open the link:eks/home#/clusters[Amazon EKS console,type="console"]. @@ -327,4 +327,4 @@ For a full list of available options, see `link:cli/latest/reference/eks/create- ---- + -If you receive an error similar to the error in the previous output, visit the URL in the output of a previous step to subscribe to the add-on. Once subscribed, run the `create-addon` command again. +If you receive an error similar to the error in the previous output, visit the URL in the output of a previous step to subscribe to the add-on. Once subscribed, run the `create-addon` command again. \ 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..0b270fbb2 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. @@ -98,13 +98,6 @@ You can use any of the following Amazon EKS add-ons. |<> |EC2 -|Retrieve secrets from {aws} Secrets Manager and parameters from {aws} Systems Manager Parameter Store and mount them as files in Kubernetes pods. -|<> -|EC2, EKS Auto Mode, EKS Hybrid Nodes - -|With Spaces, you can create and manage JupyterLab and Code Editor applications to run interactive ML workloads. -|<> -|Hyperpod |=== @@ -457,7 +450,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 @@ -693,40 +686,3 @@ NOTE: This add-on requires nodes with SR-IOV-capable network interfaces. |None |=== - -[#add-ons-aws-secrets-store-csi-driver-provider] -=== {aws} Secrets Store CSI Driver provider - -The {aws} provider for the Secrets Store CSI Driver is an add-on that enables retrieving secrets from {aws} Secrets Manager and parameters from {aws} Systems Manager Parameter Store and mounting them as files in Kubernetes pods. - -[#add-ons-ascp-iam-permissions] -=== Required IAM permissions - -The add-on does not require IAM permissions. However, application pods will require IAM permissions to fetch secrets from {aws} Secrets Manager and parameters from {aws} Systems Manager Parameter Store. After installing the add-on, access must be configured via IAM Roles for Service Accounts (IRSA) or EKS Pod Identity. To use IRSA, please refer to the Secrets Manager https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_ascp_irsa.html[IRSA setup documentation]. To use EKS Pod Identity, please refer to the Secrets Manager https://docs.aws.amazon.com/secretsmanager/latest/userguide/ascp-pod-identity-integration.html[Pod Identity setup documentation]. - -{aws} suggests the `AWSSecretsManagerClientReadOnlyAccess` https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-policies.html#security-iam-awsmanpol-AWSSecretsManagerClientReadOnlyAccess[managed policy]. - -For more information about the required permissions, see `AWSSecretsManagerClientReadOnlyAccess` in the {aws} Managed Policy Reference. - -=== Additional information - -For more information, please see the secrets-store-csi-driver-provider-aws https://github.com/aws/secrets-store-csi-driver-provider-aws[GitHub repository]. - -To learn more about the add-on, please refer to the https://docs.aws.amazon.com/secretsmanager/latest/userguide/ascp-eks-installation.html[{aws} Secrets Manager documentation for the add-on]. - -[#add-ons-amazon-sagemaker-spaces] -== Amazon SageMaker Spaces - -The Amazon SageMaker Spaces Add-on provides ability to run IDEs and Notebooks on EKS or HyperPod-EKS clusters. Administrators can use EKS Console to install the add-on on their cluster, and define default space configurations such as images, compute resources, local storage for notebook settings (additional storage to be attached to their spaces), file systems, and initialization scripts. Admins can use the kubectl to install the operator, create default settings, and manage all spaces in a centralized location. - -AI developers can use kubectl to create, update, and delete spaces. They have the flexibility to use default configurations provided by admins or customize settings. AI developers can access their spaces on EKS or HyperPod-EKS using their local VS Code IDEs, and/or their web browser that hosts their JupyterLab or CodeEditor IDE on custom DNS domain configured by their admins. They can also use kubernetes’ port forwarding feature to access spaces in their web browsers. - -The Amazon EKS add-on name is `amazon-sagemaker-spaces`. - -=== Required IAM permissions - -This add-on requires IAM permissions. For more information about the required IAM setup, see https://docs.aws.amazon.com/sagemaker/latest/dg/permission-setup.html[IAM Permissions Setup] in the _Amazon SageMaker Developer Guide_. - -=== Additional information - -To learn more about the add-on and its capabilities, see https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-eks-cluster-ide.html[SageMaker AI Notebooks on HyperPod] in the _Amazon SageMaker Developer Guide_. 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