kubeconfig-update.sh

Previous Next

Purpose

Update kubeconfig context for an EKS cluster and optionally validate kubectl connectivity.

Location

cloud/aws/eks/kubeconfig-update.sh

Preconditions

  • Required tools: bash, aws (and kubectl for --validate)
  • Required permissions: eks:DescribeCluster, token/auth role permissions used by kubeconfig
  • Required environment variables: none

Arguments

Flag Required Default Description
--cluster-name NAME Yes N/A Cluster name
--alias NAME No generated by AWS CLI Context alias
--kubeconfig PATH No default kubeconfig Target kubeconfig path
--role-arn ARN No empty Role to assume for EKS auth
--region REGION, --profile PROFILE No AWS defaults AWS context override
--validate No false Run kubectl cluster-info validation
--dry-run No false Print planned commands

Scenarios

  • Happy path: kubeconfig is updated and kubectl can reach cluster.
  • Common operational path: CI/CD or developer workstation context refresh after cluster creation.
  • Failure path: cluster missing/inaccessible, invalid auth role, or kubectl context issues.
  • Recovery/rollback path: regenerate kubeconfig with correct profile/role and retry validation.

Usage

cloud/aws/eks/kubeconfig-update.sh --cluster-name prod-eks --region us-east-1
cloud/aws/eks/kubeconfig-update.sh --cluster-name prod-eks --alias prod --kubeconfig ~/.kube/prod-config --validate
cloud/aws/eks/kubeconfig-update.sh --cluster-name staging-eks --role-arn arn:aws:iam::123456789012:role/eks-admin --dry-run

Behavior

  • Main execution flow:
  • validates cluster reachability
  • runs aws eks update-kubeconfig with optional alias/file/role
  • optionally validates via kubectl
  • Idempotency notes: repeat-safe; updates/merges kubeconfig entries.
  • Side effects: local kubeconfig file changes.

Output

  • Standard output format: AWS CLI kubeconfig update output + logs.
  • Exit codes:
  • 0 success
  • 2 invalid arguments/preconditions
  • non-zero on AWS/kubectl failures

Failure Modes

  • Common errors and likely causes:
  • invalid role ARN or profile permissions
  • kubeconfig path permission issues
  • kubectl cannot reach cluster endpoint
  • Recovery and rollback steps:
  • verify IAM auth path and profile context
  • fix kubeconfig permissions/path
  • retry with --validate after correcting connectivity

Security Notes

  • Secret handling: does not emit secrets; kubeconfig should be protected as sensitive config.
  • Least-privilege requirements: limit auth roles used for kubeconfig generation.
  • Audit/logging expectations: cluster access role usage should be audited.

Testing

  • Unit tests:
  • argument validation and command composition
  • Integration tests:
  • kubeconfig update in sandbox cluster with validation path
  • Manual verification:
  • kubectl config get-contexts and kubectl cluster-info
delete-nodegroup.sh cluster-healthcheck.sh