API Reference

Below is the API reference for the ak Python modules. This includes classes and functions that power the CLI.

class ak_tool.config.AKConfig(config_path: str = '~/.config/ak/config.ini')[source]

Bases: object

Loads and manages configuration for AWS and Kubernetes usage, including multiple AWS profiles in sections like [aws.company], [aws.home], etc.

property aws_global_token_validity_seconds: int

Get the global default token validity in seconds.

This is the default duration for which an AWS token remains valid (e.g., 43200s = 12 hours).

Returns:

Token validity duration in seconds.

Return type:

int

property credentials_file: str

Get the path to the AWS credentials file.

Returns:

AWS credentials file path.

Return type:

str

property default_aws_profile: str

Get the default AWS profile name.

Returns:

Default AWS profile.

Return type:

str

property default_kube_config: str

Get the default Kubernetes configuration name.

Returns:

Default Kubernetes configuration.

Return type:

str

get_aws_profile(profile_name: str) → dict[source]

Retrieve AWS profile information for a given profile.

This method fetches details such as original_profile, authenticated_profile, and mfa_serial from the configuration section [aws.<profile_name>]. It also retrieves a token validity value, which may override the global default.

Parameters:

profile_name (str) – The name of the AWS profile (without the “aws.” prefix).

Returns:

A dictionary containing the AWS profile information.

Return type:

dict

Raises:

KeyError – If the profile section [aws.<profile_name>] does not exist.

property kube_configs_dir: str

Get the directory where Kubernetes configuration files are stored.

Returns:

Kubernetes configuration directory path.

Return type:

str

property kube_temp_dir: str

Get the temporary directory used for storing Kubernetes tokens.

Returns:

Temporary Kubernetes directory path.

Return type:

str

property kube_token_validity_seconds: int

Get the Kubernetes API token validity duration in seconds.

Returns:

Token validity duration in seconds.

Return type:

int

save()[source]

Save any changes made to the configuration back to the configuration file.

class ak_tool.core.AWSManager(config: AKConfig, logger: Logger, aws_profile_name: str)[source]

Bases: object

Manages AWS MFA login, storing credentials in the specified credentials file.

This class handles AWS MFA-based authentication and stores the resulting credentials in an AWS CLI-compatible credentials file. It also provides an export command for updating environment variables.

config

Configuration settings for AWS login.

Type:

AKConfig

logger

Logger instance for debugging and error reporting.

Type:

logging.Logger

aws_profile_name

The name of the AWS profile being used.

Type:

str

mfa_login(mfa_code: str) → str[source]

Perform AWS MFA login using the original profile and MFA code.

This method retrieves a temporary AWS session token using MFA, stores it in the AWS credentials file. Then it selects the default kubernetes configuration.

Parameters:

mfa_code (str) – The MFA code for authentication.

Returns:

The commands to execute to adjust env variables.

Return type:

str

Raises:

RuntimeError – If the AWS login attempt fails.

Example

`python aws = AWSManager(config, logger, "company") export_line = aws.mfa_login("123456") print(export_line) `

`shell export AWS_PROFILE=company-root-mfa `

class ak_tool.core.KubeManager(config: AKConfig, logger: Logger)[source]

Bases: object

Manages Kubernetes kubeconfig switching and token handling.

This class provides functionality to switch Kubernetes configurations, refresh AWS-based authentication tokens, and ensure valid kubeconfig contexts.

config

Configuration settings.

Type:

AKConfig

logger

Logger instance.

Type:

logging.Logger

force_refresh(kubeconfig: str = '') → None[source]

Forces a token refresh for the specified kubeconfig.

Parameters:

  • kubeconfig (str) – The name of the kubeconfig to refresh.

  • variable. (Defaults to the basename of the KUBECONFIG environment)

  • "all" (If set to)

  • configured (refreshes all kubeconfigs in the)

  • directory.

switch_config(kubeconfig_name: str) → str[source]

Switch to a specified kubeconfig, resolving AWS-based authentication tokens.

This method ensures that the kubeconfig is copied to a temporary location and all aws-iam-authenticator references are replaced with static tokens. It returns an export command that sets the KUBECONFIG as well as (if applicable) the AWS_PROFILE based on the user’s exec block.

Parameters:

kubeconfig_name (str) – Name of the kubeconfig to switch to.

Returns:

The export command to set KUBECONFIG and possibly AWS_PROFILE.

Return type:

str

Raises:

FileNotFoundError – If the kubeconfig does not exist.

switch_context(context_name: str, kubeconfig: str = '') → str[source]

Switches the active Kubernetes context and updates the shell prompt with context info, and now also exports AWS_PROFILE if the original kubeconfig defines it via an aws-iam-authenticator exec block.

The prompt includes Git branch, original kubeconfig name, and current context, formatted for Bash, Zsh, or Fish shells.

Parameters:

  • context_name (str) – The Kubernetes context name to switch to.

  • kubeconfig (str, optional) – Path to the kubeconfig file. Defaults to the KUBECONFIG environment variable if not provided.

Returns:

The shell commands to switch context and (if applicable) export AWS_PROFILE.

Return type:

str

Raises:

  • EnvironmentError – If no valid kubeconfig is set.

  • RuntimeError – If an unsupported shell is detected.

ak_tool.logger.setup_logger(name: str = 'ak', debug: bool = False) → Logger[source]

Create and return a logger with either DEBUG or INFO level.

CLI entry point for the ‘ak’ tool.

This module provides the command-line interface for the ‘ak’ tool, which consolidates AWS MFA login, Kubernetes context switching, and Kubernetes API token refreshing into one simple CLI tool. It also includes functionality to print out the current version when called with –version.

ak_tool.cli.complete_aws_profile(ctx, param, incomplete)[source]

Return a list of AWS profile names matching the incomplete text.

Retrieves AWS profile names from configuration sections that start with aws. and returns those that begin with the provided incomplete string.

Parameters:

  • ctx (click.Context) – Click context.

  • param (click.Parameter) – Click parameter.

  • incomplete (str) – Incomplete text typed by the user.

Returns:

A list of CompletionItem objects with matching AWS profile names.

Return type:

list[CompletionItem]

ak_tool.cli.complete_context_name(ctx, param, incomplete)[source]

Return a list of Kubernetes context names matching the incomplete text.

Executes kubectl config get-contexts -o name to retrieve context names, then filters and returns those that start with the provided incomplete string.

Parameters:

  • ctx (click.Context) – Click context.

  • param (click.Parameter) – Click parameter.

  • incomplete (str) – Incomplete text typed by the user.

Returns:

A list of CompletionItem objects with matching Kubernetes context names.

Return type:

list[CompletionItem]

ak_tool.cli.complete_kube_name(ctx, param, incomplete)[source]

Return a list of kubeconfig filenames matching the incomplete text.

Scans the directory specified by the configuration for kubeconfigs and returns filenames that start with the provided incomplete string.

Parameters:

  • ctx (click.Context) – Click context.

  • param (click.Parameter) – Click parameter.

  • incomplete (str) – Incomplete text typed by the user.

Returns:

A list of CompletionItem objects with matching kubeconfig filenames.

Return type:

list[CompletionItem]

ak_tool.cli.generate_bash_zsh_prompt_script() → str[source]

Generate a one-off script for Bash/Zsh that defines and sets a colorful prompt showing user@host, directory, Git branch, and Kube context.

Returns:

The script for setting a colorful prompt in Bash/Zsh.

Return type:

str

ak_tool.cli.generate_bash_zsh_wrapper(shell)[source]

Generate a custom wrapper function for Bash or Zsh.

The wrapper executes the ‘ak’ binary and evaluates lines that begin with the >>> prefix to update the shell’s environment and prompt.

Parameters:

shell (str) – The shell type (“bash” or “zsh”).

Returns:

A string containing the custom wrapper script.

Return type:

str

ak_tool.cli.generate_custom_wrapper(shell)[source]

Generate a shell-specific custom function wrapper.

Dispatches the wrapper generation to the appropriate function based on the shell.

Parameters:

shell (str) – The shell name (“bash”, “zsh”, or “fish”).

Returns:

A string containing the custom wrapper script for the specified shell.

Return type:

str

Raises:

SystemExit – Prints an error and exits if the shell is unsupported.

ak_tool.cli.generate_fish_prompt_script() → str[source]

Generate a one-off script for Fish that defines a new fish_prompt function showing user@host, directory, Git branch, and Kube context in color.

Returns:

The Fish prompt script.

Return type:

str

ak_tool.cli.generate_fish_wrapper()[source]

Generate a custom wrapper function for the Fish shell.

The wrapper executes the ‘ak’ command and accumulates lines that begin with the >>> prefix into a single string, then evaluates them all at once.

Returns:

The custom wrapper function script for the Fish shell.

Return type:

str

ak_tool.cli.generate_prompt_script(shell: str) → str[source]

Return a one-off script that sets a colorized prompt displaying user@host, current directory, Git branch, and Kube context for the specified shell.

Parameters:

shell (str) – The shell name (“bash”, “zsh”, or “fish”).

Returns:

The prompt script for the specified shell.

Return type:

str

ak_tool.cli.get_official_completion(mode)[source]

Retrieve the official Click-generated shell completion script.

Executes a subprocess call with the environment variable _AK_COMPLETE set to the specified mode and returns the resulting completion script.

Parameters:

mode (str) – The shell completion mode.

Returns:

The shell completion script.

Return type:

str

Raises:

subprocess.CalledProcessError – If the subprocess call fails.

ak_tool.cli.get_shell_mode(shell)[source]

Determine the Click completion mode for the given shell.

Parameters:

shell (str) – The shell name (e.g., “bash”, “zsh”, or “fish”).

Returns:

The Click completion mode corresponding to the shell.

Return type:

str

Raises:

ValueError – If the shell is unsupported.

ak_tool.cli.main()[source]

Entry point for the ‘ak’ CLI tool.

Invokes the Click command group.