ak tool (access kubernetes) is a unified CLI tool that simplifies AWS MFA logins, Kubernetes context switching, and Kubernetes API token refreshing. Designed for engineers managing multiple Kubernetes clusters across different AWS accounts, ak streamlines daily authentication and environment management—especially when using OpenID Connect SSO, MFA, or other secure authentication methods.

• ak tool
  • Table of Contents
  • Quick Start
    • 1. Install
    • 2. Source the Completion Script
    • 3. Run ak Commands
    • 4. Prompt & Environment Variables
  • Introduction
  • Features
    • Streamlined AWS MFA Authentication
      • How It Works
      • Configuration Breakdown
      • AWS CLI Configuration
      • How ak Updates Credentials
    • Streamlined Kubernetes API Authentication
      • How It Works
      • Configuration Breakdown
      • AWS CLI Configuration
      • The kubeconfig File
    • Multiple Kubeconfigs & Namespaces
    • Automatic or On-Demand Token Refresh
    • Kubernetes & AWS Profile Synchronization
    • Completion
  • Command Line Parameters
  • Configuration
  • Testing
    • Run Tests with Pytest Directly
    • Using Make
    • Coverage Reports
  • Final Notes

pip3 install ak-tool

Using a virtual environment:

Assuming you have git, python3 and make installed on your system:

git clone https://github.com/aharonh/ak-tool.git
cd ak
python3 -m venv .venv
source .venv/bin/activate
make install

eval "$(ak completion bash)"

• AWS Login with MFA Code:

  ak l 123456

• Switch to a Particular Kubeconfig:

  ak c dev

• Switch to a Named Context:

  ak x kube-system

• After running ak c <kubeconfig> or ak x <context>, your shell prompt (PS1) updates to reflect the active context.
• The AWS_PROFILE environment variable is automatically set to match the AWS account linked to the new context.
• The KUBECONFIG environment variable is updated to point to the correct kubeconfig file.

Managing multiple AWS accounts and Kubernetes clusters can be complex. ak minimizes that complexity by:

• Handling AWS MFA tokens and short-lived Kubernetes API tokens.
• Automating token refreshes.
• Providing a single interface for switching contexts across environments.

ak simplifies the process of AWS MFA authentication and token management. In secure environments where MFA and SSO are required, ak reduces the daily authentication steps to a single command.

• Dual-Profile Model:
  • Original Profile: Used for initial MFA authentication with AWS.
  • Authenticated Profile: Stores temporary credentials after MFA validation.

Running:

ak l 123456

performs the following steps:

1. Authenticates using the original profile.
2. Retrieves a temporary AWS STS session token.
3. Writes new credentials under the authenticated profile in your AWS credentials file.
4. Switches AWS authentication to the authenticated profile.

Key configuration options:

• credentials_file: Path to your AWS credentials file.
• token_validity_seconds: Duration (in seconds) for temporary credentials (e.g., 43200 seconds).
• default_profile: Default AWS profile when --aws-profile is not specified.
• Per-account settings ([aws.<profile_name>]):
  • original_profile: AWS profile for initial MFA.
  • authenticated_profile: AWS profile to store temporary credentials.
  • mfa_serial: ARN of the MFA device.

Example configuration:

[aws]
credentials_file = /home/user/.aws/credentials
token_validity_seconds = 43200
default_profile = company

[aws.company]
original_profile = company-root
authenticated_profile = company-root-mfa
mfa_serial = arn:aws:iam::3453453454345:mfa/yubikey4

[aws.home]
original_profile = home-systems
authenticated_profile = home-systems-mfa
mfa_serial = arn:aws:iam::262626262626:mfa/yubikey4

Ensure your AWS CLI is correctly configured. Example for the AWS config file:

[profile company-root]
region = us-east-1
output = json

[profile company-root-mfa]
region = us-east-1
output = json

And the corresponding AWS credentials file:

[company-root]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[company-root-mfa]
aws_access_key_id = ASIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = FQoGZXIvYXdzEJr//////////wEaDIN

When you run:

ak l 123456

ak:

1. Uses the original profile for MFA validation.
2. Retrieves and stores a temporary STS session token under the authenticated profile.
3. Updates the credentials in your ~/.aws/credentials file, ensuring you always have valid credentials.

Managing Kubernetes API tokens—especially for kOps-based clusters—can be cumbersome. ak caches and refreshes these tokens to speed up your workflow.

• Token Caching:
  ak caches the Kubernetes API token in a temporary file.
• Automatic Refresh:
  The token is refreshed automatically upon expiration.
• Improved Performance:
  This avoids the overhead of generating a new token with each kubectl command.

Configuration options for Kubernetes:

• configs_dir: Directory containing your kubeconfig files.
• temp_dir: Directory for storing temporary Kubernetes tokens.
• token_validity_seconds: Duration (in seconds) for which the Kubernetes token is valid.
• default_config: Default kubeconfig used with the ak l command.

Example configuration:

[kube]
configs_dir = /home/user/.kubeconfigs
temp_dir = /home/user/.kubeconfigs_temp
token_validity_seconds = 900
default_config = dev

When working with multiple clusters across AWS accounts, you may need additional AWS profiles. For example:

[profile company-dev-access]
region = us-east-1
output = json
role_arn = arn:aws:iam::11111111111111:role/admin
source_profile = company-root-mfa
role_session_name = your.username

[profile company-prod-access]
region = eu-central-1
output = json
role_arn = arn:aws:iam::22222222222222:role/admin
source_profile = company-root-mfa
role_session_name = your.username

ak automatically sets the correct AWS_PROFILE based on the kubeconfig context.

ak scans your kubeconfig file for users with an exec section using aws-iam-authenticator. It generates a temporary kubeconfig file that replaces the aws-iam-authenticator command entries with a cached token.

Example kubeconfig entry (before):

users:
- name: aws-user-dev
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - token
      - -i
      - dev.company.com
      command: /home/user/bin/aws-iam-authenticator
      env:
      - name: AWS_PROFILE
        value: company-dev-access
      interactiveMode: IfAvailable
      provideClusterInfo: false

The entry is replaced with:

- name: aws-user-dev
  user:
    token: k8s-aws-v1.aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8_QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS
    # additional fields...

• Switch Kubeconfigs:
  Easily switch between different clusters (e.g., dev, test, prod):

  ak c prod

• Switch Namespaces:
  Change between namespace contexts within a single cluster:

  ak x kube-system

• Visual Feedback:
  The active context is displayed in your shell prompt (e.g., (dev-kube-system) $).

• Automatic Refresh:
  When the Kubernetes API token expires but the AWS session token remains valid, ak automatically refreshes the token.

• Manual Refresh:
  Force a token refresh with:

  ak r

Each kubeconfig context is associated with an AWS profile. When you switch contexts using:

ak x <context>

ak exports the appropriate AWS_PROFILE so that all your AWS CLI commands use the correct account credentials.

ak supports tab-completion for Bash, Zsh, and Fish. To enable completion for Bash, run:

eval "$(ak completion bash)"

For persistent Bash completion, install the completion script:

ak completion bash | sudo tee /etc/bash_completion.d/ak
. /etc/bash_completion.d/ak

Display the help text with:

ak --help

Example output:

Usage: ak [OPTIONS] COMMAND [ARGS]...

Options:
  --debug             Enable debug logging.
  --aws-profile TEXT  Name of AWS sub-profile section, e.g. 'company', 'home'.
  --help              Show this message and exit.

Commands:
  c           Switch to a specific kubeconfig by name.
  completion  Generate a shell completion script and custom function...
  l           AWS MFA login.
  r           Force token refresh for the current KUBECONFIG.
  x           Switch context within the current KUBECONFIG.

ak uses a configuration file located at ~/.config/ak/config.ini.

Example configuration:

[aws]
credentials_file = /home/user/.aws/credentials
token_validity_seconds = 43200
default_profile = company

[aws.company]
original_profile = company-root
authenticated_profile = company-root-mfa
mfa_serial = arn:aws:iam::3453453454345:mfa/yubikey4

[aws.company-dev-root]
original_profile = company-dev-root
authenticated_profile = company-dev-root-mfa
mfa_serial = arn:aws:iam::345345345343:mfa/yubikey4

[aws.company-prod-root]
original_profile = company-prod-root
authenticated_profile = company-prod-root-mfa
mfa_serial = arn:aws:iam::800175841235:mfa/yubikey4

[aws.home]
original_profile = home-systems
authenticated_profile = home-systems-mfa
mfa_serial = arn:aws:iam::262626262626:mfa/yubikey4

[aws.home-root]
original_profile = home-systems-root
authenticated_profile = home-systems-root-mfa
mfa_serial = arn:aws:iam::239087474744:mfa/yubikey4

[kube]
configs_dir = /home/user/.kubeconfigs
temp_dir = /home/user/.kubeconfigs_temp
token_validity_seconds = 900

pytest tests/ --verbose

make test

Generate coverage reports using:

make coverage

This command runs pytest --cov to generate a detailed coverage report.

ak is designed to reduce operational overhead by consolidating AWS and Kubernetes authentication tasks. Whether you’re switching contexts, refreshing tokens, or managing multiple environments, ak provides a streamlined and efficient workflow.

Happy coding!