Skip to content

cli-setup.md

Latest commit

 

History

History
174 lines (123 loc) · 7.96 KB

cli-setup.md

File metadata and controls

174 lines (123 loc) · 7.96 KB

AKS Flex CLI Setup

Overview

The AKS Flex CLI (aks-flex-cli) is a command-line tool for managing AKS Flex clusters that span across Azure and remote cloud providers (e.g. Nebius). It handles the end-to-end lifecycle of a multi-cloud Kubernetes environment, including:

  • Network provisioning -- deploy and manage the Azure-side network infrastructure
  • AKS cluster deployment -- create and configure AKS clusters with options such as Cilium CNI and WireGuard encryption
  • Remote cloud integration -- configure networking and agent pools on remote cloud providers
  • Configuration generation -- bootstrap environment configs, Kubernetes cluster settings, and node bootstrap scripts

The CLI is organized into four top-level commands:

Command Description
config Generate environment files, network configs, agent pool configs, and bootstrap manifests
network Deploy and manage Azure network resources
aks Deploy and manage the AKS cluster
plugin Apply, get, and delete remote cloud resources (networks, agent pools)

Getting Started

Prerequisites

The following tools must be installed and available on your PATH:

  • Go 1.26+ -- required to build the CLI from source
  • Azure CLI (az) -- used to resolve your Azure subscription and manage Azure resources. You must be logged in (az login) before using the CLI.
  • kubectl -- required for interacting with the deployed AKS cluster
  • Helm (helm) (optional) -- used for deploying Helm charts to the cluster
  • Cilium CLI (cilium) (optional) -- used for managing and validating Cilium networking. See Cilium install guide.
  • Nebius CLI (nebius) (optional) -- required only if you plan to integrate with Nebius as a remote cloud provider

Download pre-built binaries

Pre-built binaries are available for the following platforms:

Platform Architecture Download
macOS (Darwin) arm64 aks-flex-cli_0.0.1-snapshot-b1dba55_darwin_arm64.tar.gz
Linux amd64 aks-flex-cli_0.0.1-snapshot-b1dba55_linux_amd64.tar.gz
Linux arm64 aks-flex-cli_0.0.1-snapshot-b1dba55_linux_arm64.tar.gz

Download and install the binary for your platform:

# Example for macOS (arm64)
curl -LO https://aksflxcli.z20.web.core.windows.net/aks-flex-cli/aks-flex-cli_0.0.1-snapshot-b1dba55_darwin_arm64.tar.gz
tar -xzf aks-flex-cli_0.0.1-snapshot-b1dba55_darwin_arm64.tar.gz
chmod +x aks-flex-cli_darwin_arm64
mkdir -p ~/.local/bin
mv aks-flex-cli_darwin_arm64 ~/.local/bin/aks-flex-cli
# Example for WSL / Linux (amd64)
curl -LO https://aksflxcli.z20.web.core.windows.net/aks-flex-cli/aks-flex-cli_0.0.1-snapshot-b1dba55_linux_amd64.tar.gz
tar -xzf aks-flex-cli_0.0.1-snapshot-b1dba55_linux_amd64.tar.gz
chmod +x aks-flex-cli_linux_amd64
mkdir -p ~/.local/bin
mv aks-flex-cli_linux_amd64 ~/.local/bin/aks-flex-cli

Make sure ~/.local/bin is on your PATH. If it isn't, add the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.local/bin:$PATH"

Verify checksums

After downloading, verify the integrity of the archive using SHA-256:

65a5f391c8cd9e5d72199ea737c3c73d40a7bad6db1dea1659f50e1e4f6300fd  aks-flex-cli_0.0.1-snapshot-b1dba55_darwin_arm64.tar.gz
b7b40f2560b03d88daf6d68968a16f000f5067907985fc5aac044b37e5d441a3  aks-flex-cli_0.0.1-snapshot-b1dba55_linux_amd64.tar.gz
0c6ae69d258f1df27a72b8ff3774e3d1de4dfc4a283aac56ca414a3feb2e6cc5  aks-flex-cli_0.0.1-snapshot-b1dba55_linux_arm64.tar.gz

shasum -a 256 aks-flex-cli_*.tar.gz

TODO: These binaries will be published to GitHub Releases in the future. Once available, download URLs and installation instructions will be updated accordingly.

Install from source

Clone the repository and build the binary:

git clone https://github.com/Azure/aks-flex.git
cd aks-flex/cli
make build-local

The compiled binary is placed at ./bin/aks-flex-cli. You can move it to a directory on your PATH:

cp ./bin/aks-flex-cli /usr/local/bin/

Verify the installation:

$ aks-flex-cli version
aks-flex-cli <version> (commit: <commit>, built: <build-time>)

Configuration

Before running any provisioning commands, you need to generate an environment configuration file that supplies Azure (and optionally remote cloud) settings to the CLI.

Generate the environment file

Run the config env subcommand and redirect the output to a .env file in the cli/ directory:

$ aks-flex-cli config env > .env

The command auto-detects your current Azure subscription (via az account show) and generates a .env file similar to:

# !! This file includes sensitive information, please do not commit it to any public repository !!
# Please update the values in this file for your environment.

# -----------------------------------------------------------------------------
# Azure Config
# -----------------------------------------------------------------------------
# Azure side resource location
export LOCATION=southcentralus
# Azure side subscription ID
export AZURE_SUBSCRIPTION_ID=<your-subscription-id>
# Azure side resource group name
export RESOURCE_GROUP_NAME=rg-aks-flex-<username>

To include Nebius configuration, pass the --nebius flag:

$ aks-flex-cli config env --nebius > .env

This appends Nebius-specific variables (project ID, region, credentials file path) to the generated output. If the Nebius CLI is installed and configured, the project ID is resolved automatically; otherwise placeholder values are inserted that you must fill in manually.

Review and update the configuration

Open the generated .env file and verify or update the following values:

Variable Description Default
LOCATION Azure region for resources southcentralus
AZURE_SUBSCRIPTION_ID Azure subscription ID auto-detected from az CLI
RESOURCE_GROUP_NAME Resource group name rg-aks-flex-<username>
NEBIUS_PROJECT_ID Nebius project ID (if --nebius) auto-detected or placeholder
NEBIUS_REGION Nebius region (if --nebius) placeholder -- must be updated
NEBIUS_CREDENTIALS_FILE Path to Nebius credentials JSON (if --nebius) placeholder -- must be updated

Authentication

The CLI uses your existing Azure CLI session for authentication. Make sure you are logged in before running any commands:

az login
az account set --subscription <your-subscription-id>

For Nebius integration, follow the Nebius authorized keys documentation to create a credentials file and set its path in NEBIUS_CREDENTIALS_FILE.

Once the .env file is in place, the CLI loads it automatically on startup (via godotenv), so no additional sourcing step is required.