add docs

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.