docs/doc/source/airship2/airship-in-a-pod.rst

Airship in a Pod (AIAP)

Airship-in-a-Pod (AIAP) is a Kubernetes pod definition that describes all of the components required to deploy a fully functioning Airship 2 in a working Kubernetes cluster. The pod consists of the following "Task" containers:

• airshipctl-builder: This container builds the airshipctl binary and makes it available to the other containers. Airshipctl manages the lifecycle of a site utilizing declarations about the infrastructure (stored in source code).
• infra-builder: This container creates the various virtual networks and machines required for an Airship deployment.
• runner: The runner container is the "meat" of the pod, and executes the deployment.

The pod also contains the following "Support" containers:

• libvirt: This provides virtualization.
• sushy-tools: This is used for its Bare Metal Container (BMC) emulator.
• docker-in-docker: This is used for nesting containers.
• nginx: This is used for image hosting.

Prerequisites

Airship in a Pod (AIAP) is a pod definition. Deploying and using AIAP is as simple as deploying it on any Kubernetes pod on a Linux machine matching the following requirements.

• Linux bare metal server* with KVM (server recommended specs: CPUs 4, RAM 16G, free disk space 60GB)
• Kubernetes**
• kubectl**
• Kubernetes cluster

* This is our initial AIAP deployment platform. Additional deployment platforms are under consideration for future AIAP installments. ** Please note that for compatibility the Kubernetes and kubectl releases should be within 1 release of each other.

Deploying a Kubernetes Cluster

First, we need a working Kubernetes cluster and these can be provided by tools such as kubeadm, minikube and Docker Desktop. The instructions to "Deploy AIAP" using kubectl are agnostic to how the kubernetes cluster is deployed.

In this example we shall utilize minikube to provide us with a Kubernetes cluster; minikube requires that we also deploy the docker-ce engine.

Pre-deploy needed utilites

sudo apt-get install  apt-transport-https  \
    ca-certificates curl  gnupg  lsb-release

Deploy minikube

Exceute the following in a terminal (cmd or shell) window:

wget https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo chmod 755 minikube-linux-amd64
sudo mv minikube-linux-amd64 /usr/local/bin/minikube

Deploy Docker

sudo apt-get update

Add Docker GPG key

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Add stable directory

sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable"

Update package

sudo apt update
apt-cache policy docker-ce

Install

sudo apt-get install docker-ce docker-ce-cli containerd.io

Add Docker User

sudo usermod -aG docker $USER && newgrp docker

To check Docker status

sudo systemctl status docker

Start minikube

This will install kubernetes and create a kubernetes "default" cluster.

minikube start --cpus=4 --memory=16384 --driver=none

Please note that you can specify a smaller configuration or let minikube utilize the default configuraion by not specifying cpus or memory but, if resources permit, the above specifiction is highly recommended.

Deploy AIAP

The airship-in-a-pod.yaml file contains declarations about the seven (7) containers (listed previously). To deploy AIAP once a kubernetes cluster is available:

$ kubectl apply -f https://raw.githubusercontent.com/airshipit/airshipctl/master/tools/airship-in-a-pod/airship-in-a-pod.yaml

You should see the message "airship-in-a-pod" created. The deployment of the containers will take some time.

View Pod Logs

kubectl logs airship-in-a-pod -c $CONTAINER

Usage

Interact with the Pod

kubectl exec -it airship-in-a-pod -c $CONTAINER -- bash

where $CONTAINER is one of the containers listed above.

Output

Airship-in-a-pod produces the following outputs:

• The airshipctl repo and associated binary used with the deployment
• A tarball containing the generated ephemeral ISO, as well as the configuration used during generation.

These artifacts are placed at ARTIFACTS_DIR (defaults to /opt/aiap-artifacts).

Caching

As it can be cumbersome and time-consuming to build and rebuild binaries and images, some options are made available for caching. A developer may re-use artifacts from previous runs (or provide their own) by placing them in CACHE_DIR (defaults to /opt/aiap-cache). Special care is needed for the caching:

• If using a cached airshipctl, the airshipctl binary must be stored in the $CACHE_DIR/airshipctl/bin/ directory, and the developer must have set USE_CACHED_AIRSHIPCTL to true.
• If using a cached ephemeral iso, the iso must first be contained in a tarball named iso.tar.gz, must be stored in the $CACHE_DIR/ directory, and the developer must have set USE_CACHED_ISO to true.