Azure AKS Cluster

Azure AKS Cluster Provisioner

The Azure AKS Cluster Provisioner deploys a production-ready Kubernetes cluster on Microsoft Azure, using dynamic credentials — no hardcoded secrets or service account keys needed.

AKS Specification

The aks struct configures the AKS provisioner.

subscriptionId: Required Azure subscription ID (UUID format).
resourceGroup: Required Azure resource group name.
kubernetesVersion: Optional field for Kubernetes version (e.g., 1.30 or 1.30.5).
nodeOsUpgradeChannel: Optional field for node OS upgrade behavior (SecurityPatch, NodeImage, None, Unmanaged).
autoUpgradeChannel: Optional field for cluster auto-upgrade cadence (patch, stable, rapid, node-image, none).
enableWorkloadIdentity: Optional boolean to enable Microsoft Entra Workload Identity.
enableOidcIssuer: Optional boolean to enable the OIDC issuer on the cluster.
privateCluster: Optional boolean to enable private API server access.
networkPlugin: Optional field for AKS networking (azure, kubenet, none).
networkPluginMode: Optional field for Azure CNI overlay mode.
vnetSubnetId: Optional full Azure subnet resource ID for BYOVNet.
authorizedIPRanges: Optional list of CIDR ranges to restrict API server access.
tags: Optional Azure resource tags.
credentials: Required field for cloud provider credentials.

Bring your own VNet (BYOVNet)

vnetSubnetId and optionally authorizedIPRanges are used for BYOVNet deployments.

Prerequisites

To create an AKS cluster on Azure, ensure the following CLI tools are installed on your local machine:

Azure CLI for AKS cluster communication
kubectl (optional) for AKS cluster interaction
astroctl for cluster management

To set up the cloud credentials on the astro platform and your Azure subscription, run the following command. Omitting this step will result in an error during cluster creation.

astroctl cloud azure connect --subscription-id <subscription-id> --resource-group <resource-group> --cluster-name <cluster-name> --region <region>

Cloud Account Setup Example

Example command for setting up the cloud account for cluster my-cluster in eastus with subscription id 12345678-1234-1234-1234-123456789abc.

astroctl cloud azure connect --subscription-id 12345678-1234-1234-1234-123456789abc --resource-group my-resource-group --cluster-name my-cluster --region eastus

Follow the instructions shown in the terminal to complete the cloud account setup.

Region and Zone Identification

Identify the region using the Azure portal or the following command:

astroctl cloud azure regions list

Complete Field Reference

The aks struct configures the AKS provisioner. This is the authoritative reference for all available fields.

Core Fields

Field	Type	Required	Default	Description
`subscriptionId`	string	Yes	-	Azure subscription ID (UUID format)
`resourceGroup`	string	Yes	-	Azure resource group name where the cluster will be created
`credentials`	object	Yes	-	Cloud provider credentials. Use `type: dynamic` (set up via `astroctl cloud azure connect`). The `type: vault` is only supported for self-hosted provisioners.

Networking Fields (BYOVNet)

Field	Type	Required	Default	Description
`vnetSubnetId`	string	No	-	Full Azure subnet resource ID for BYOVNet (e.g., `/subscriptions/.../subnets/default`)
`authorizedIPRanges`	[]string	No	-	CIDR ranges that can access the API server (e.g., `["10.0.0.0/8", "203.0.113.0/24"]`)
`networkPlugin`	string	No	`azure`	Networking plugin: `azure` (Azure CNI), `kubenet`, or `none`
`networkPluginMode`	string	No	-	Azure CNI overlay mode configuration
`privateCluster`	bool	No	`false`	Enable private API server access (no public endpoint)

Cluster Configuration Fields

Field	Type	Required	Default	Description
`kubernetesVersion`	string	No	Latest	Kubernetes version. Accepts: `1.30` or `1.30.5` format
`nodeOsUpgradeChannel`	string	No	-	Node OS upgrade behavior: `SecurityPatch`, `NodeImage`, `None`, `Unmanaged`
`autoUpgradeChannel`	string	No	-	Cluster auto-upgrade cadence: `patch`, `stable`, `rapid`, `node-image`, `none`
`enableWorkloadIdentity`	bool	No	`false`	Enable Microsoft Entra Workload Identity for pod-level Azure access
`enableOidcIssuer`	bool	No	`false`	Enable OIDC issuer on the cluster (required for Workload Identity)
`tags`	map[string]string	No	-	Key-value pairs for Azure resource tagging

Field Validation Rules

Field	Validation
`subscriptionId`	Must be a valid UUID format
`resourceGroup`	Must be a valid Azure resource group name
`kubernetesVersion`	Must be valid K8s version format: `1.30` or `1.30.5`
`nodeOsUpgradeChannel`	Must be one of: `SecurityPatch`, `NodeImage`, `None`, `Unmanaged`
`autoUpgradeChannel`	Must be one of: `patch`, `stable`, `rapid`, `node-image`, `none`
`networkPlugin`	Must be one of: `azure`, `kubenet`, `none`
`authorizedIPRanges`	Each entry must be valid CIDR notation
`tags`	Each key and value must be at least 1 character

Bring Your Own Account (BYOA)

The astro platform allows you to bring your own Azure subscription for AKS cluster creation. The following example illustrates the AKS specification, with the platform managing VNet, subnet, and other networking configurations. You only need to provide the subscription ID, resource group, and ensure proper quota for these configurations.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-aks-cluster
  provider: azure
  region: eastus
  provisioner:
    type: aks
    aks:
      subscriptionId: "12345678-1234-1234-1234-123456789abc"
      resourceGroup: "my-resource-group"
      tags:
        environment: "dev"
        owner: "foo@bar.com"
      credentials:
        type: dynamic  # dynamic credentials
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-pool
          minNode: 1
          maxNode: 3
          instanceType: ondemand  # or "spot" for cost savings
          machineTypes:
            - Standard_D2s_v3
          labels:
            environment: dev

Bring Your Own VNet (BYOVNet)

For BYOVNet deployments, provide the full Azure subnet resource ID. The platform will deploy the AKS cluster into your existing network infrastructure.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-aks-vnet-cluster
  provider: azure
  region: eastus
  provisioner:
    type: aks
    aks:
      subscriptionId: "12345678-1234-1234-1234-123456789abc"
      resourceGroup: "my-resource-group"
      vnetSubnetId: "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/my-rg/providers/Microsoft.Network/virtualNetworks/my-vnet/subnets/default"
      authorizedIPRanges:
        - "10.0.0.0/8"
        - "203.0.113.0/24"
      networkPlugin: "azure"
      tags:
        environment: "dev"
        owner: "foo@bar.com"
      credentials:
        type: dynamic  # dynamic credentials
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-pool
          minNode: 1
          maxNode: 3
          machineTypes:
            - Standard_D2s_v3
          labels:
            environment: dev

For BYOVNet, the astroctl validates quota, permissions, and configurations before cluster creation. Ensure the subnet has sufficient IP address space for your node and pod requirements.

Cluster Updates

AKS clusters support updates to Kubernetes version, agent pool configurations, and cluster settings. You can use either the Console UI or the CLI.

Option 1: Console (Upgrade Wizard)

The Console provides a guided 5-step upgrade wizard:

Preflight Check - Validates upgrade paths and checks for issues
Readiness Report - Generates comprehensive upgrade analysis with risk score
Pre-Upgrade Checklist - Interactive checklist with verification commands
Configuration - Select target version and rolling update settings
Confirmation - Review summary and confirm by typing cluster name

To access: Go to Clusters → Select cluster → Click Upgrade button

The wizard shows:

Visual version timeline (current → next → locked future versions)
Agent pool scaling controls (min/max nodes)
Rolling update settings (maxSurge, maxUnavailable)
Impact summary before execution

Option 2: CLI Commands

Version Discovery

# List available versions for this cluster
astroctl infra k8s upgrade <cluster-name> --list-versions

# Check versions for a region
astroctl cloud azure k8s-versions
astroctl cloud azure k8s-versions -r eastus
astroctl cloud azure k8s-versions --show-upgrade-paths

Kubernetes Version Upgrade

# Dry-run validation first
astroctl infra k8s upgrade <cluster-name> 1.30 --dry-run

# Generate readiness report
astroctl infra k8s upgrade <cluster-name> 1.30 --generate-report

# Execute upgrade
astroctl infra k8s upgrade <cluster-name> 1.30

# Skip confirmation (for automation)
astroctl infra k8s upgrade <cluster-name> 1.30 --yes

Scaling Agent Pools

# List agent pools
astroctl infra k8s scale <cluster-name> --list

# Scale an agent pool
astroctl infra k8s scale <cluster-name> <pool-name> --min 3 --max 10

# Preview changes
astroctl infra k8s scale <cluster-name> <pool-name> --min 5 --max 20 --dry-run

Advanced Updates (YAML)

# Show YAML examples for your cluster
astroctl infra k8s update <cluster-name> --example

# Apply update
astroctl infra k8s update <cluster-name> -f update.yaml

# Dry-run validation
astroctl infra k8s update <cluster-name> -f update.yaml --dry-run

# Skip confirmation
astroctl infra k8s update <cluster-name> -f update.yaml --auto-approve

Monitor Progress

# Stream real-time progress
astroctl infra k8s progress stream <cluster-name>

# Get current status
astroctl infra k8s progress get <cluster-name>

# View operation history
astroctl infra k8s progress history <cluster-name>

Update File Reference

apiVersion: platform.astropulse.io/v1
kind: K8sClusterUpdate
spec:
  # Kubernetes version
  kubernetesVersion: "1.30"

  # Rolling update configuration
  updateConfig:
    maxSurge: "1"           # Nodes added during update (number or %)
    maxUnavailable: "1"     # Nodes down during update (number or %)
    dryRun: false           # Validate without applying
    generateReport: false   # Generate readiness report

  # Agent pools
  nodeGroups:
    - name: "default-pool"
      minNode: 2
      maxNode: 8
      machineTypes: ["Standard_D2s_v3"]
      instanceType: "ondemand"  # or "spot"
      labels:
        workload: "general"

  # AKS-specific settings
  aks:
    nodeOsUpgradeChannel: "SecurityPatch"
    autoUpgradeChannel: "stable"

  # Resource tags
  tags:
    environment: "production"

Rolling Update Strategy

Control the speed and safety of agent pool upgrades with --max-unavailable and --max-surge flags:

# Configure rolling update speed
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 2 --max-surge 1

# Use percentage-based configuration
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 25%

Smart Defaults: If you don't specify these flags, AstroPulse automatically determines optimal values:

Agent Pool Type	Default Strategy	Why
Small (1-3 nodes)	surge=1, unavailable=0	Maintain full capacity
Medium (4-10 nodes)	surge=2, unavailable=1	Balance speed and safety
Large (10+ nodes)	surge=10%, unavailable=10%	Percentage-based scaling
GPU nodes	surge=1, unavailable=0	Protect expensive resources
System/Critical	surge=1, unavailable=0	Ensure cluster stability

Upgrade Process

Control plane is upgraded first (Azure managed)
Agent pools are upgraded sequentially with rolling updates
System add-ons are updated to compatible versions
Progress is tracked and reported in real-time

Upgrade Considerations

AKS only supports upgrades to sequential minor versions (cannot skip versions)
Control plane cannot be downgraded after upgrade
Agent pools use rolling update strategy for zero-downtime upgrades
Always test upgrades in a non-production environment first

KubeConfig

With a simple command, you can set the context to the cluster and access it. Make sure to have kubectl installed.

astroctl infra k8s set-context <cluster-name>

The cluster managed by the astro platform uses Microsoft Entra tokens for kubectl authentication. Ensure the Azure CLI is installed for token refresh.

Added Capabilities

The AKS provisioner supports the following capabilities for AKS clusters:

Azure CNI: Advanced container networking with native Azure VNet integration. Choose between standard Azure CNI or overlay mode for flexible IP address management.
Workload Identity: Enable Microsoft Entra Workload Identity for pod-level access to Azure resources without managing credentials. Requires enableWorkloadIdentity and enableOidcIssuer.
OIDC Issuer: Enable the OIDC issuer endpoint on the cluster for federated identity scenarios.
Node OS Auto-Upgrade: Configure automatic OS-level patching for cluster nodes via nodeOsUpgradeChannel.

Auto-Upgrade Channels

AKS supports cluster auto-upgrade channels to keep your cluster up to date automatically:

Channel	Behavior	Use Case
`patch`	Auto-upgrade to latest patch version	Production (recommended)
`stable`	Upgrade to latest stable patch of N-1 minor	Conservative production
`rapid`	Upgrade to latest supported patch of latest minor	Testing, development
`node-image`	Upgrade node images weekly	Node OS freshness
`none`	No auto-upgrades	Full manual control

Set the channel in your cluster spec or update it later via astroctl infra k8s update.