diff --git a/local-app/python-tools/eks-tools/README.eks_addon_versions.md b/local-app/python-tools/eks-tools/README.eks_addon_versions.md new file mode 100755 index 00000000..49e6587e --- /dev/null +++ b/local-app/python-tools/eks-tools/README.eks_addon_versions.md @@ -0,0 +1,188 @@ +# eks_addon_versions.py + +Queries the AWS EKS API for all available managed add-ons and their latest +supported versions, filtered to EKS 1.30 and above. Outputs a structured YAML +report grouped by EKS version, suitable for use in upgrade planning and +Terraform variable management. + +--- + +## Requirements + +- Python 3.10+ +- AWS credentials configured (environment variables, `~/.aws/credentials`, or IAM instance/task role) +- IAM permission: `eks:DescribeAddonVersions` + +--- + +## Installation + +Install the required Python dependencies: + +```bash +pip install boto3 pyyaml +``` + +No other installation is needed — the script is a single self-contained file. + +--- + +## Usage + +``` +eks_addon_versions.py [-h] [--version EKS_VERSION] [--region AWS_REGION] + [--output FILE] [--profile AWS_PROFILE] +``` + +### Arguments + +| Argument | Short | Description | +|---|---|---| +| `--version EKS_VERSION` | `-v` | Query a specific EKS version (e.g. `1.33`). Omit to query all available 1.30+ versions. | +| `--region AWS_REGION` | `-r` | AWS region to query. Defaults to your environment/CLI configuration. | +| `--output FILE` | `-o` | Write YAML output to a file instead of stdout. | +| `--profile AWS_PROFILE` | `-p` | AWS CLI named profile to use. | + +--- + +## Examples + +### Query all EKS 1.30+ versions, print to stdout + +```bash +python3 eks_addon_versions.py +``` + +### Query all versions and save to a file + +```bash +python3 eks_addon_versions.py --output eks_addons.yaml +``` + +### Query a specific EKS version + +```bash +python3 eks_addon_versions.py --version 1.33 +``` + +### Query a specific version and save to a file + +```bash +python3 eks_addon_versions.py --version 1.33 --output eks_addons_1.33.yaml +``` + +### Use a non-default AWS region + +```bash +python3 eks_addon_versions.py --region us-east-2 --output eks_addons.yaml +``` + +### GovCloud with a named profile + +```bash +python3 eks_addon_versions.py \ + --region us-gov-west-1 \ + --profile my-govcloud-profile \ + --output eks_addons_govcloud.yaml +``` + +### Combine all options + +```bash +python3 eks_addon_versions.py \ + --version 1.33 \ + --region us-gov-west-1 \ + --profile my-govcloud-profile \ + --output eks_addons_1.33_govcloud.yaml +``` + +--- + +## Output Format + +The YAML output is structured by EKS version. Under each version, add-ons are +listed alphabetically with their latest available version string. + +```yaml +eks_addon_versions: + 1.30: + addons: + aws-ebs-csi-driver: v1.37.0-eksbuild.1 + coredns: v1.11.4-eksbuild.2 + eks-pod-identity-agent: v1.3.4-eksbuild.1 + kube-proxy: v1.30.9-eksbuild.3 + vpc-cni: v1.19.3-eksbuild.1 + 1.31: + addons: + aws-ebs-csi-driver: v1.40.0-eksbuild.1 + coredns: v1.11.4-eksbuild.2 + eks-pod-identity-agent: v1.3.4-eksbuild.1 + kube-proxy: v1.31.6-eksbuild.3 + vpc-cni: v1.19.3-eksbuild.1 + 1.32: + addons: + aws-ebs-csi-driver: v1.40.0-eksbuild.1 + coredns: v1.11.4-eksbuild.2 + eks-pod-identity-agent: v1.3.4-eksbuild.1 + kube-proxy: v1.32.3-eksbuild.3 + vpc-cni: v1.19.3-eksbuild.1 + 1.33: + addons: + aws-ebs-csi-driver: v1.51.0-eksbuild.1 + coredns: v1.12.1-eksbuild.2 + eks-pod-identity-agent: v1.3.9-eksbuild.3 + kube-proxy: v1.33.3-eksbuild.4 + vpc-cni: v1.20.4-eksbuild.1 +``` + +> **Note:** Actual versions returned will reflect what is currently available +> in AWS at the time the script is run. Results may differ between commercial +> and GovCloud regions. + +### Version selection logic + +For each add-on, the script prefers versions AWS has flagged as +`defaultVersion: true` for that specific EKS minor version, then selects the +highest semver among those. If no version is flagged as default (uncommon, but +possible for newly added add-ons), it falls back to the highest among all +compatible versions. + +--- + +## Credentials + +The script uses the standard boto3 credential chain in order: + +1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) +2. AWS CLI config (`~/.aws/credentials`, `~/.aws/config`) +3. Named profile via `--profile` +4. IAM instance profile or ECS task role + +For GovCloud, always specify `--region` explicitly, as the default region from +your environment may point to a commercial partition endpoint. + +--- + +## Changelog + +### v1.0.3 — Paginator fix +- Fixed boto3 paginator name to `describe_addon_versions` (snake_case). + The `get_paginator()` method requires the Python snake_case form of the + operation name, not the AWS CLI kebab-case or API PascalCase forms. + +### v1.0.2 — Version numbering added +- Added version number to script header and changelog block. +- Paginator fix from v1.0.1 was not correctly incorporated in this release. + +### v1.0.1 — Paginator fix attempt (incorrect) +- Attempted to fix paginator name using PascalCase (`DescribeAddonVersions`). + This was incorrect and still raised a `KeyError`. + +### v1.0.0 — Initial release +- Query all EKS 1.30+ managed add-on versions via the EKS API. +- Dynamic EKS version discovery (no hardcoded version list). +- Structured YAML output grouped by EKS version, add-ons sorted alphabetically. +- `--version` argument to target a single EKS version. +- `--region`, `--profile`, and `--output` arguments. +- Input validation for version format and minimum version enforcement. +- Prefers AWS-default-flagged add-on versions; falls back to highest semver.