API Reference

The following is the API reference for the ak package.

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

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

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

Raises:

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

Returns:

A dictionary containing the AWS profile information.

Return type:

dict

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()

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

ak_tool.cli.complete_aws_profile(ctx, param, incomplete)

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

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

Parameters:

• ctx – Click context.

• param – 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)

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

Executes the command 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.

• param – 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)

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.

• param – 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_wrapper(shell)

Generate a custom wrapper function for Bash or Zsh.

The wrapper executes the ‘ak’ binary and evaluates lines that begin with export or if to update the shell’s environment.

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)

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”, “fish”, or “powershell”).

Returns:

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

Return type:

str

ak_tool.cli.generate_fish_wrapper()

Generate a custom wrapper function for the Fish shell.

The wrapper executes the ‘ak’ command and evaluates lines that begin with export or if, ensuring environment variables are updated correctly.

Returns:

A string containing the Fish shell wrapper script.

Return type:

str

ak_tool.cli.generate_powershell_wrapper()

Generate a custom wrapper function for PowerShell.

The wrapper executes the ‘ak’ command and evaluates lines that begin with export (after stripping the export keyword) so that environment variables are updated.

Returns:

A string containing the PowerShell wrapper script.

Return type:

str

ak_tool.cli.get_official_completion(mode)

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)

Determine the Click completion mode for the given shell.

Parameters:

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

Returns:

The Click completion mode corresponding to the shell.

Return type:

str

Raises:

ValueError – If the shell is unsupported.

ak_tool.cli.main()

Entry point for the ‘ak’ CLI tool.

Invokes the Click command group.

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

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

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, and returns a shell export command to set AWS_PROFILE.

Parameters:

mfa_code (str) – The MFA code for authentication.

Returns:

The export AWS_PROFILE=authenticated_profile command.

Return type:

str

Raises:

RuntimeError – If the AWS login attempt fails.

Example

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

`shell export AWS_PROFILE=nuvo-root-mfa `

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

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

switch_config(kubeconfig_name: str) → str

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.

Parameters:

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

Returns:

The export KUBECONFIG=… command.

Return type:

str

Raises:

FileNotFoundError – If the kubeconfig does not exist.

switch_context(context_name: str) → str

Switches the active Kubernetes context and updates the shell prompt with context info.

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

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

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