Airctl Reference

Airctl is an on-premises Kubernetes orchestrator by Platform9. Comprising a useful command-line utility and related functions that manage the lifecycle of the Management Server on the Management Plane of Private Cloud Director.

This powerful tool serves as your control center for managing Private Cloud Director on-premises environment. Airctl provides comprehensive management capabilities that ensure your Kubernetes environment runs smoothly while automatically handling critical infrastructure components.

What Airctl Does?

Cluster Lifecycle Management: Create, configure, scale, and upgrade Kubernetes management clusters.
Backup & Recovery: Protect your cluster configuration and MySQL database.

Prerequisites

Before using Airctl, ensure your environment meets these requirements:

Operating System: Ubuntu 22.04 with sudo access.
Storage: NFS server (for shared storage scenarios).
Resources: Minimum hardware requirements for your target deployment type.

Airctl Core Functions

Airctl offers functions that simplify on-premises management.

State management

Initializes and configures the Management Plane, creating necessary components automatically when needed.

Database Backup

Facilitates MySQL database backup for the Platform9 data store. Optimized for typical three-node cluster configurations.

Configuration Management

Manages cluster state through configuration files containing node IP addresses and credentials. These files describe the desired state of your cluster and serve as the foundation for deployment and management operations.

CLI Utilities

Provides comprehensive command-line utilities for backup and recovery of cluster state. These utilities ensure you can protect, restore, and maintain your entire management cluster configuration, enabling disaster recovery and environment replication across different deployments.

Command Reference

Cluster Management Commands

Command

Description

Use Case

create-cluster

Create a nodelet-based management cluster

Initial cluster deployment

delete-cluster

Delete a headless management cluster

Cluster decommissioning

scale-cluster

Scale up or down a nodelet-based management cluster

Capacity adjustment

upgrade-cluster

Upgrade a nodelet-based management cluster

Version updates

start

Start the Management Plane and auto-configure

Normal operations

stop

Stop the Management Plane

Maintenance windows

status

Report Management Plane status

Health monitoring

upgrade

Upgrade the management plane

Normal operations

add-region

Add a new region to the PCD deployment

Advanced multi tenancy

Configuration Commands

Command

Description

Example

configure

Generate management plane configuration

update-admin-password

Set airctl admin password

get-creds

Display admin credentials

Backup and Recovery Commands

These CLI utilities provide comprehensive backup and recovery capabilities for both MySQL database and cluster state management.

Command

Description

Output

backup

Back up management plane state and configuration

Creates tar.gz file

restore

Restore from backup (includes cluster state)

Restores from tar.gz file

gen-support-bundle

Generate support bundle

Diagnostic package

Maintenance Commands

Command

Description

When to Use

check

Check deployment prerequisites

Before installation

upgrade

Upgrade management plane apps

Version updates

reset-taskstate

Reset deployment state after resolving errors

Management plane upgrade failure

Advanced Commands

Command

Description

Use Case

unconfigure-du

Delete the Management Plane configuration state

Clean slate deployment

Key Configuration Options

General Configuration

Flag

Decription

Deafult

-d, --cluster-deployment-type

Choose 'nodeletd' or 'k3s'

nodeletd

-f, --du-fqdn

Management plane (DU) FQDN

airctl-1.platform9.localnet

-r, --regions

Specify regions for the DU (at least 1)

Region1

-a, --enable-k8s

Enable Kubernetes

true

Node Configuration

Flag

Decription

Deafult

-i, --master-ips

Master node IP addresses (comma-separated)

-w, --worker-ips

Worker node IP addresses (comma-separated)

--ssh-port int

SSH port for nodes

Network Configuration

Flag

Decription

Deafult

-4, --ipv4-enabled

Enable IPv4 networking. To enable dual-stack networks, set this flag and "ipv6-enabled"

true

-6, --ipv6-enabled

Enable IPv6 networking. To enable dual-stack networks, set this flag and "ipv4-enabled"

false

-e, --external-ip4

Set the external IPv4 for the DU

-x, --external-ip6

Set the external IPv6 for the DU

VIP Configuration

Flag

Decription

Deafult

--master-vip4

Virtual IP for Management Cluster (IPv4)

--master-vip6

Virtual IP for Management Cluster (IPv6)

-v, --master-vip-interface

Specify the masterVipVrouterId since more than 1 master node

-z, --master-vip-vrouterid

Specify the masterVipVrouterId since more than 1 master node

Storage Configuration

Flag

Decription

Deafult

-p, --storage-provider

StorageProvider (Either 'hostpath-provisioner' or 'custom') (For custom, save provider-specific YAMLs to /opt/pf9/airctl/conf/ddu/storage/custom/)

hostpath-provisioner

-k, --nfs-ip

Set the NFS server IP address for DU

-n, --nfs-share

Specify the NFS share path for DU

K3s Configuration

Flag

Decription

Default

-c, --k3s-pod-cidr

Specify the Pod CIDR for the k3s cluster

10.20.0.0/16

-s, --k3s-service-cidrService

Specify the service CIDR for the k3s cluster

10.21.0.0/16

Registry Configuration

Flag

Decription

Default

--registry-type privateRegistryType

Type of container image registry to use. Possible values: DU, custom, none

Global Flags

These flags can be used with any Airctl command:

Flag

Decription

Example

--config

config file

$HOME/airctl-config.yaml

--quiet

Disable spinners

--verbose

Print verbose logs to the console

airctl configure --verbose

-h, --help

Show command help

airctl configure --help

-v, --version

Version for airctl

Configure your management cluster options

Select from various installation types tailored to your specific needs and environmental requirements.

Single-master management cluster - Ideal for proof-of-concept (POC) installations and testing environments where high availability isn't critical.
Multi-master management cluster - Required for production installations where you need high availability and redundancy for your workloads.

Airctl Configuration Reference

# airctl-config.yaml Schema Documentation
# This file documents all possible configuration options for airctl-config.yaml
# Format: YAML with JSON Schema-like descriptions

type: object
properties:
  # Installation and Deployment Configuration
  installDriver:
    type: string
    enum: ["DDU", "openstack"]
    default: "openstack"
    description: "Type of installation driver to use for deployment"

  clusterDeploymentType:
    type: string
    enum: ["nodeletd", "k3s"]
    description: "Type of cluster deployment (nodeletd or k3s) - k3s only supported in Community Edition"

  # DU Configuration
  duFqdn:
    type: string
    required: true
    example: "airctl-1.pf9.localnet"
    description: "Fully qualified domain name for the DU"

  duTenant:
    type: string
    default: "service"
    description: "DU tenant identifier"

  duRegion:
    type: string
    default: "Infra"
    example: "Infra RegionOne"
    description: "DU region(s) - space-separated for multiple regions"

  duUser:
    type: string
    example: "[email protected]"
    description: "DU admin user email/username"

  duPassword:
    type: string
    description: "DU admin user password"

  # SSH Configuration
  sshUser:
    type: string
    required: true
    example: "ubuntu"
    description: "SSH username for node access"

  sshPort:
    type: integer
    default: 22
    description: "SSH port for node access"

  sshPublicKeyFile:
    type: string
    default: "~/.ssh/id_rsa.pub"
    description: "Path to SSH public key file"

  sshPrivateKeyFile:
    type: string
    default: "~/.ssh/id_rsa"
    description: "Path to SSH private key file"

  # Network Configuration
  externalIP:
    type: string
    example: "10.128.135.5"
    description: "External IP (VIP) to access the control plane on the UI. Needs to be in same subnet as cluster nodes"

  externalIpV6:
    type: string
    description: "External IP (VIP) to access the control plane on the UI. Needs to be in same subnet as cluster nodes"

  IpV4:
    type: boolean
    default: true
    description: "Enable IPv4 support"

  IpV6:
    type: boolean
    default: false
    description: "Enable IPv6 support"

  # Storage Configuration
  storageProvider:
    type: string
    enum: ["hostpath-provisioner", "custom"]
    default: "hostpath-provisioner"
    description: "Storage provider type"

  nfsServerIP:
    type: string
    example: "10.10.10.10"
    description: "NFS server IP address"

  nfsShare:
    type: string
    example: "/mnt/pcd-data-share"
    description: "NFS share path"

  # Installation Paths and Directories
  installDir:
    type: string
    default: "/opt/pf9/airctl"
    description: "Airctl installation directory"

  logDir:
    type: string
    default: "~"
    description: "Log directory path (defaults to user home)"

  # Configuration File Paths
  kubeCfgPath:
    type: string
    default: "/etc/nodelet/airctl-mgmt/certs/admin.kubeconfig"
    description: "Path to Kubernetes configuration file"

  bootstrapCfgPath:
    type: string
    default: "/opt/pf9/airctl/conf/nodelet-bootstrap-config.yaml"
    example: "/etc/nodelet/airctl-mgmt/airctl-mgmt.yaml"
    description: "Path to bootstrap configuration file to deploy the kubernetes cluster"

  # Certificate Configuration
  clusterFQDN:
    type: string
    description: "Cluster fully qualified domain name"

  caCertPath:
    type: string
    description: "Path to CA certificate file"

  caKeyPath:
    type: string
    description: "Path to CA key file"

  certPath:
    type: string
    description: "Path to certificate file"

  certKeyPath:
    type: string
    description: "Path to certificate key file"

  # Component Version Configuration
  consulVersion:
    type: string
    default: "1.2.0"
    description: "Consul version"

  vaultVersion:
    type: string
    default: "0.21.1"
    description: "Vault version"

  kplaneVersion:
    type: string
    default: "0.3.5"
    description: "Kplane version"

  pxcOperatorVersion:
    type: string
    default: "1.16.1"
    description: "Percona XtraDB Cluster Operator version"

  pxcDbVersion:
    type: string
    default: "1.16.1"
    description: "Percona XtraDB Cluster Database version"

  # Features and Options
  enableK8s:
    type: boolean
    default: true
    description: "Enable Kubernetes (K8s/Kaapi) support - default true for On-Prem, false for CE"

  analytics:
    type: boolean
    default: false
    description: "Enable Platform9 telemetry and analytics"

  pcdChartBundleEnabled:
    type: boolean
    default: false
    description: "Enable PCD chart bundle for airgap mode"

  # Timeouts
  svcDeploymentTimeout:
    type: integer
    default: 600
    description: "Service deployment timeout in seconds"

  nodeShutdownTaintTimeout:
    type: integer
    default: 3600
    description: "Node shutdown taint timeout in seconds"

  # Administrative Configuration
  adminUserEmail:
    type: string
    default: "[email protected]"
    description: "Admin user email address"

  # NTP Configuration
  ntpServers:
    type: string
    example: "time.google.com time1.google.com"
    description: "Space-separated list of NTP servers for DU time synchronization"

  # Options Path
  optionsPath:
    type: string
    default: "/opt/pf9/airctl/conf/options.json"
    description: "Path to additional options JSON file"

  # Error Collection Configuration (Root Level)
  error_collection_enabled:
    type: boolean
    default: false
    description: "Enable error collection and debugging information upload"

  error_collection_upload_endpoint:
    type: string
    example: "https://ce-support-bundle-dev.s3.us-west-1.amazonaws.com"
    description: "Endpoint URL for uploading error collection data"
# Additional Notes:
# 1. Required fields vary based on installDriver value (DDU vs openstack)
# 2. For custom storage provider, nfsServerIP and nfsShare are required
# 3. Multiple regions can be specified in duRegion as space-separated values
# 4. Version fields may be automatically determined based on airctl version

PreviousBackup and Restore Management Plane NextAdding a New Region to an Existing Deployment

Last updated 15 days ago

Was this helpful?

Good evening

What Airctl Does?

Prerequisites

Airctl Core Functions

State management

Database Backup

Configuration Management

CLI Utilities

Command Reference

Cluster Management Commands

Configuration Commands

Backup and Recovery Commands

Maintenance Commands

Advanced Commands

Key Configuration Options

General Configuration

Node Configuration

Network Configuration

VIP Configuration

Storage Configuration

K3s Configuration

Registry Configuration

Global Flags

Airctl Configuration Reference