# 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 <code class="expression">space.vars.product\_name</code>.

This powerful tool serves as your control center for managing <code class="expression">space.vars.product\_name</code> 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` | <p>Enable IPv4 networking.<br>To enable dual-stack networks, set this flag and "ipv6-enabled"</p> | true        |
| `-6, --ipv6-enabled` | <p>Enable IPv6 networking.<br>To enable dual-stack networks, set this flag and "ipv4-enabled"</p> | 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-cidr`Service | Specify the service CIDR for the k3s cluster | 10.21.0.0/16 |

#### Registry Configuration

| **Flag**                                                   | **Decription**                                                             | **Default** |
| ---------------------------------------------------------- | -------------------------------------------------------------------------- | ----------- |
| <p><code>--registry-type</code><br>privateRegistryType</p> | 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

{% tabs %}
{% tab title="YAML" %}

```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: "admin@airctl.localnet"
    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: "admin@airctl.localnet"
    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
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/airctl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.