ak-tool 0.1.5

Consolidates AWS MFA login, Kubernetes context switching, and Kubernetes API token refreshing into one simple CLI tool.

ak tool

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.

---

Table of Contents

• 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

---

Quick Start

1. Install

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

2. Source the Completion Script

eval "$(ak completion bash)"

3. Run ak Commands

• 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
  

4. Prompt & Environment Variables

• 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.

---

Introduction

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.

---

Features

Streamlined AWS MFA Authentication

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.

How It Works

• 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.

Configuration Breakdown

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

AWS CLI Configuration

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

How ak Updates Credentials

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.

---

Streamlined Kubernetes API Authentication

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

How It Works

• 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 Breakdown

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

AWS CLI Configuration

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.

The kubeconfig File

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...

---

Multiple Kubeconfigs & Namespaces

• 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 or On-Demand Token Refresh

• 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
  

---

Kubernetes & AWS Profile Synchronization

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.

---

Completion

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

---

Command Line Parameters

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.

---

Configuration

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

---

Testing

Run Tests with Pytest Directly

pytest tests/ --verbose

Using Make

make test

Coverage Reports

Generate coverage reports using:

make coverage

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

---

Final Notes

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!