Airctl Reference

Airctl Overview

Airctl is Platform9's On-Prem, air gapped Kubernetes orchestrator that comprises a useful command-line utility and related functions that manages the lifecycle of the Management Server in the Platform9 management plane. Additionally, it also contains auxiliary functions like:

• DNS management: A straightforward way to ensure all the other nodes can reach the temp management plane when it starts.
• Image management: Populating the image cache onto various nodes to avoid image fetching when the management plane is not running. This setup includes the docker images as well as RPM packages.
• State management: starts the management plane (creates and configures it first if necessary)
• Platform9 uses a mysql database. Airctl would help with the backup of that data. However, since we are only looking at a three-node cluster, the amount of backup data would be minimal.
• Config File: config files describe the state of the cluster that the user wants to create and contain the pointers (ip addresses) for Kubernetes nodes and their corresponding credentials.
• Other CLI utilities to help with backup and recovery of the ‘state'.

Airctl CLI Options

Bash

$ /opt/pf9/airctl/airctl

Usage Syntax:
  airctl [command]

Available Commands:
  advanced-du         advanced command for the Management Server configuration
  advanced-hosts      advanced command for the hosts configuration
  backup              backs up the the management plane's state to a tar.gz file
  configure-hosts     configure the hosts
  configure-localhost configures the local host's qemu hook and /etc/hosts file (requires sudo)
  configure-sso       configure sso
  gen-support-bundle  generate support bundle
  get-creds           displays the admin username (email) and initial generated password
  get-du-version      displays the Management Server's release version
  help                Help about any command
  host-status         reports the statuses of all hosts
  restore             restores the management plane from a backup
  rollback            attempts to rollback a failed management plane upgrade operation
  start               starts the management plane (creates and configures it first if necessary)
  status              reports the status of the management plane
  stop                stops the management plane if it is running
  unconfigure-du      delete the management plane's configuration state
  upgrade             upgrades a new management plane VM using specified disk
  upgrade-hosts       upgrade Platform9 agent on all hosts

Flags:
      --config string   config file (default is $HOME/airctl-config.yaml)
  -h, --help            help for airctl
      --verbose         print verbose logs to the console
  -v, --version         version for airctl

Use "airctl [command] --help" for more information about a command.

Host Configuration Options

Here is an outline of the different options which can be passed using the configure-hosts flag.

Bash

$ /opt/pf9/airctl/airctl configure-hosts --config

Error: flag needs an argument: --config

Usage Syntax:
  airctl configure-hosts [flags]

Flags:
  -h, --help                     help for configure-hosts
      --skip-docker-img-import   skip import the docker images on each hosts
      --skip-docker-install      skip docker install on each hosts
      --skip-image-renaming      skip image renaming to point to the privateRegistryBase, for e.g gcr.io/hyperkube will become <privateRegistryBase>/hyperkube
      --skip-yum-repo-install    skip yum repo installation, default to false

Global Flags:
      --config string   config file (default is $HOME/airctl-config.yaml)
      --verbose         print verbose logs to the console
Explanation of each Skip Flag:


--skip-docker-img-import: By default, the cache of docker images required to stand up the cluster are copied over to the hosts to pre-warm the local docker cache. 
                          This option skips that step; the host will now rely on the local registry to serve these images.

--skip-docker-install: By default, airctl installs docker as a part of the host configuration. 
                       With this option set, airctl skips that step and expects the host to come with its own docker installed. 
                       Note: Passing this option also skips installation of the docker images

--skip-image-renaming: If the airctl-config.yaml has private registry turned on, i.e, has the privateRegistryType field set to anything but none, the host configuration step will automatically rename images to point to the local registry instead of its upstream versions. 
                       Pass this option to continue copying over upstream versions of the images to the hosts. Note: This option is meaningless if the --skip-docker-img-import option is passed

--skip-yum-repo-install: Pass this option to prevent airctl from installing the local yum repos for pf9-hostagent and other associated packages. 
                         Instead, the host is expected to pick these packages up from an external yum repo.

Management Cluster Configuration

Use one of the sample configuration templates below, to describe your management cluster.

Sample configuration for a single master cluster:

Bash

clusterName: airctl-mgmt
sshUser: root
sshPrivateKeyFile: /root/.ssh/id_rsa
nodeletPkg: /opt/pf9/airctl/nodelet/nodelet.tar.gz
allowWorkloadsOnMaster: true
masterIp: 10.128.144.161
masterVipEnabled: false
calicoV4Interface: "interface=eth0"
privileged: true
masterNodes:
  - nodeName: 10.128.144.151
workerNodes:
  - nodeName: 10.128.144.151
  - nodeName: 10.128.145.202
  - nodeName: 10.128.145.63
  - nodeName: 10.128.145.219

Info : Tweak the following sections based on the operating system

As shown in the following example, the nodelet package on Ubuntu is named nodelet-deb.tar.gz . The masterVipInterface can be ens3 on some systems instead eth0 . This needs to be tweaked according to the networking configuration on the OS.

Bash

nodeletPkg: /opt/pf9/airctl/nodelet/nodelet-deb.tar.gz
masterVipInterface: ens3
calico:
  ... 
  v4Interface: interface=ens3

_ _

Sample configuration of a multi-master Centos cluster: _ _

Bash

clusterName: airctl-mgmt
sshUser: root
sshPrivateKeyFile: /root/.ssh/id_rsa
kubeconfig: /etc/nodelet/airctl-mgmt/certs/admin.kubeconfig
nodeletPkg: /opt/pf9/airctl/nodelet/nodelet.tar.gz
allowWorkloadsOnMaster: true
masterIp: 10.128.144.161
masterVipEnabled: true
masterVipInterface: eth0
masterVipVrouterId: 209
calicoV4Interface: "interface=eth0"
privileged: true
masterNodes:
  - nodeName: 10.128.144.151
  - nodeName: 10.128.145.63
  - nodeName: 10.128.145.219
  - nodeName: 10.128.145.137
  - nodeName: 10.128.145.76
workerNodes:
  - nodeName: 10.128.145.202
  - nodeName: 10.128.145.197

Sample configuration of a dual-stack Centos cluster:

Bash

allowWorkloadsOnMaster: true
calico:
  v4BlockSize: 26
  v4ContainersCidr: 10.20.0.0/22
  v4Interface: interface=eth1
  v4IpIpMode: Always
  v4NATOutgoing: true
  v6BlockSize: 122
  v6ContainersCidr: fd00:101::/116
  v6Interface: interface=eth0
  v6NATOutgoing: true
clusterName: airctl-mgmt
containerRuntime:
  cgroupDriver: systemd
  name: containerd
dns:
  corednsHosts:
  - 10.128.145.197 airctl-1-2479689-127.pf9.localnet
  - fc00:1:a:2::297 airctl-1-2479689-127.pf9.localnet
ipv4: true
ipv6: true
k8sApiPort: "443"
masterIp: 10.128.145.189
masterIpV6: fc00:1:a:2::14e
masterNodes:
- nodeName: 10.128.145.189
masterVipInterface: eth1
mtu: "1440"
nodeletPkg: /opt/pf9/airctl/nodelet/nodelet.tar.gz
privileged: "true"
sshPrivateKeyFile: /home/centos/.ssh/id_rsa
sshUser: centos
userImages:
- /home/centos/downloads/nodelet-imgs-v-5.6.0-2481858.tar.gz
- /home/centos/downloads/kubedu-imgs-v-5.6.0-2481858.tar.gz
workerNodes: []

Airctl automatically adds a couple of required tar.gz image bundles, to upload and import into the container runtime of every node in the cluster.

This will be required if public image repositories are not available. These will be added to the systemImages section when the management cluster is created. The file names are generated based on the airctl version.

The config will look as follows in the cluster spec file. The user does not need to add this, it is added automatically.

Bash

systemImages:
  - /root/kubedu-imgs-v-5.10.0-3248001.tar.gz
  - /root/nodelet-imgs-v-5.10.0-3248001.tar.gz

However, if there are custom image bundles that the user does want loaded, they may use the following section to specify their bundles:

Bash

userImages:
  - /root/<img-bundle-1>.tar.gz
  - /root/<img-bundle-2>.tar.gz

For more information, please see: https://github.com/platform9/nodelet/blob/main/nodeletctl/README.md#airgapped-user-image-bundles