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	22

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	DU

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

YAML

# 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