Airskiff: Lightweight Airship for Dev¶

Skiff (n): a shallow, flat-bottomed, open boat
Airskiff (n): a learning development, and gating environment for Airship

What is Airskiff¶

Airskiff is an easy way to get started with the software delivery components of Airship:

Airskiff is packaged with a set of deployment scripts modeled after the OpenStack-Helm project for seamless developer setup.

These scripts:

Download, build, and containerize the Airship components above from source.
Deploy a Kubernetes cluster using Minikube.
Deploy Armada, Deckhand, and Shipyard using the latest Armada image.
Deploy OpenStack using the Airskiff site and charts from the OpenStack-Helm project.

Warning

Airskiff is not safe for production use. These scripts are only intended to deploy a minimal development environment.

Common Deployment Requirements¶

This section covers actions that may be required for some deployment scenarios.

Passwordless sudo¶

Airskiff relies on scripts that utilize the sudo command. Throughout this guide the assumption is that the user is: ubuntu. It is advised to add the following lines to /etc/sudoers:

root    ALL=(ALL) NOPASSWD: ALL
ubuntu  ALL=(ALL) NOPASSWD: ALL

Proxy Configuration¶

Note

This section assumes you have properly defined the standard http_proxy, https_proxy, and no_proxy environment variables and have followed the Docker proxy guide to create a systemd drop-in unit.

In order to deploy Airskiff behind proxy servers, define the following environment variables:

export USE_PROXY=true
export PROXY=${http_proxy}
export no_proxy=${no_proxy},10.0.2.15,.svc.cluster.local
export NO_PROXY=${NO_PROXY},10.0.2.15,.svc.cluster.local

Note

The .svc.cluster.local address is required to allow the OpenStack client to communicate without being routed through proxy servers. The IP address 10.0.2.15 is the advertised IP address of the minikube Kubernetes cluster. Replace the addresses if your configuration does not match the one defined above.

Deploy Airskiff¶

Deploy Airskiff using the deployment scripts contained in the tools/deployment/airskiff directory of the airship-treasuremap repository.

Note

Scripts should be run from the root of treasuremap repository.

Clone Dependencies¶

#!/bin/bash
set -xe

CURRENT_DIR="$(pwd)"
: "${INSTALL_PATH:="../"}"
: "${OSH_INFRA_COMMIT:="e6dfa15c269caa9fffb7d2205e614bb2deae43d6"}"
: "${CLONE_ARMADA:=true}"
: "${CLONE_DECKHAND:=true}"
: "${CLONE_SHIPYARD:=true}"

cd ${INSTALL_PATH}

# Clone Airship projects
if [[ ${CLONE_ARMADA} = true ]] ; then
    git clone https://opendev.org/airship/armada.git
fi
if [[ ${CLONE_DECKHAND} = true ]] ; then
    git clone https://opendev.org/airship/deckhand.git
fi
if [[ ${CLONE_SHIPYARD} = true ]] ; then
    git clone https://opendev.org/airship/shipyard.git
fi

# Clone dependencies
git clone https://opendev.org/openstack/openstack-helm-infra.git

cd openstack-helm-infra
git checkout "${OSH_INFRA_COMMIT}"

cd "${CURRENT_DIR}"

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/000-clone-dependencies.sh

Setup AppArmor¶

#!/bin/bash

CURRENT_DIR="$(pwd)"
: "${OSH_INFRA_PATH:="../openstack-helm-infra"}"

cd "${OSH_INFRA_PATH}"
bash -c "./tools/deployment/common/001-setup-apparmor-profiles.sh"

cd "${CURRENT_DIR}"

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/009-setup-apparmor.sh

Deploy Kubernetes with Minikube¶

#!/bin/bash

CURRENT_DIR="$(pwd)"
: "${OSH_INFRA_PATH:="../openstack-helm-infra"}"

# Configure proxy settings if $PROXY is set
if [ -n "${PROXY}" ]; then
  . tools/deployment/airskiff/common/setup-proxy.sh
fi

# Deploy K8s with Minikube
cd "${OSH_INFRA_PATH}"
bash -c "./tools/deployment/common/005-deploy-k8s.sh"

kubectl label nodes --all --overwrite ucp-control-plane=enabled

# Add user to Docker group
# NOTE: This requires re-authentication. Restart your shell.
sudo adduser "$(whoami)" docker
sudo su - "$USER" -c bash <<'END_SCRIPT'
if echo $(groups) | grep -qv 'docker'; then
    echo "You need to logout to apply group permissions"
    echo "Please logout and login"
fi
END_SCRIPT

# clean up /etc/resolv.conf, if it includes a localhost dns address
sudo sed -i.bkp '/^nameserver.*127.0.0.1/d
                 w /dev/stdout' /etc/resolv.conf

cd "${CURRENT_DIR}"

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/010-deploy-k8s.sh

Restart your shell session¶

At this point, restart your shell session to complete adding $USER to the docker group.

Setup OpenStack Client¶

#!/bin/bash
set -xe

# Install OpenStack client and create OpenStack client configuration file.
sudo -H -E pip3 install "cmd2<=0.8.7"
sudo -H -E pip3 install --upgrade setuptools==50.0.0
sudo -H -E pip3 install python-openstackclient python-heatclient

sudo -H mkdir -p /etc/openstack
sudo -H chown -R "$(id -un)": /etc/openstack
tee /etc/openstack/clouds.yaml << EOF
clouds:
  airship:
    region_name: RegionOne
    identity_api_version: 3
    auth:
      username: 'admin'
      password: 'password123'
      project_name: 'admin'
      project_domain_name: 'default'
      user_domain_name: 'default'
      auth_url: 'http://keystone-api.ucp.svc.cluster.local:5000/v3'
  openstack:
    region_name: RegionOne
    identity_api_version: 3
    auth:
      username: 'admin'
      password: 'password123'
      project_name: 'admin'
      project_domain_name: 'default'
      user_domain_name: 'default'
      auth_url: 'http://keystone-api.openstack.svc.cluster.local:5000/v3'
EOF

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/020-setup-client.sh

Deploy Airship components using Armada¶

#!/bin/bash
set -xe

: "${INSTALL_PATH:="$(pwd)/../"}"
: "${PEGLEG:="./tools/airship pegleg"}"
: "${PL_SITE:="airskiff"}"
: "${TARGET_MANIFEST:="cluster-bootstrap"}"

# Render documents
${PEGLEG} site -r . render "${PL_SITE}" -o airskiff.yaml

# Set permissions o+r, beacause these files need to be readable
# for Armada in the container
AIRSKIFF_PERMISSIONS=$(stat --format '%a' airskiff.yaml)
KUBE_CONFIG_PERMISSIONS=$(stat --format '%a' ~/.kube/config)

sudo chmod 0644 airskiff.yaml
# sudo chmod 0644 ~/.kube/config


# Download latest Armada image and deploy Airship components
docker run --rm --net host -p 8000:8000 --name armada \
    -v ~/.kube/config:/armada/.kube/config \
    -v "$(pwd)"/airskiff.yaml:/airskiff.yaml \
    -v "${INSTALL_PATH}":/airship-components \
    quay.io/airshipit/armada:latest-ubuntu_focal\
    apply /airskiff.yaml --debug --target-manifest $TARGET_MANIFEST

# # Set back permissions of the files
sudo chmod "${AIRSKIFF_PERMISSIONS}" airskiff.yaml
# sudo chmod "${KUBE_CONFIG_PERMISSIONS}" ~/.kube/config

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/030-armada-bootstrap.sh

Deploy OpenStack using Airship¶

#!/bin/bash
set -xe

# Lint deployment documents
: "${AIRSHIP_PATH:="./tools/airship"}"
: "${PEGLEG:="${AIRSHIP_PATH} pegleg"}"
: "${SHIPYARD:="${AIRSHIP_PATH} shipyard"}"
: "${PL_SITE:="airskiff"}"

# Source OpenStack credentials for Airship utility scripts
. tools/deployment/airskiff/common/os-env.sh

# NOTE(drewwalters96): Disable Pegleg linting errors P001 and P009; a
#  a cleartext storage policy is acceptable for non-production use cases
#  and maintain consistency with other treasuremap sites.
${PEGLEG} site -r . lint "${PL_SITE}" -x P001 -x P009

# Collect deployment documents
: "${PL_OUTPUT:="peggles"}"
mkdir -p ${PL_OUTPUT}

TERM_OPTS="-l info" ${PEGLEG} site -r . collect ${PL_SITE} -s ${PL_OUTPUT}

# Start the deployment
${SHIPYARD} create configdocs airskiff-design \
             --replace \
             --directory=${PL_OUTPUT}
${SHIPYARD} commit configdocs
${SHIPYARD} create action update_software --allow-intermediate-commits

Alternatively, this step can be performed by running the script directly:

./tools/deployment/airskiff/developer/100-deploy-osh.sh

Use Airskiff¶

The Airskiff deployment scripts install and configure the OpenStack client for usage on your host machine.

Airship Examples¶

To use Airship services, set the OS_CLOUD environment variable to airship.

export OS_CLOUD=airship

List the Airship service endpoints:

openstack endpoint list

Note

${SHIPYARD} is the path to a cloned Shipyard repository.

Run Helm tests for all deployed releases:

${SHIPYARD}/tools/shipyard.sh create action test_site

List all Shipyard actions:

${SHIPYARD}/tools/shipyard.sh get actions

For more information about Airship operations, see the Shipyard actions documentation.

OpenStack Examples¶

To use OpenStack services, set the OS_CLOUD environment variable to openstack:

export OS_CLOUD=openstack

List the OpenStack service endpoints:

openstack endpoint list

List Glance images:

openstack image list

Issue a new Keystone token:

openstack token issue

Note

Airskiff deploys identity, network, cloudformation, placement, compute, orchestration, and image services. You can deploy more services by adding chart groups to site/airskiff/software/manifests/full-site.yaml. For more information, refer to the site authoring and deployment guide.

Develop with Airskiff¶

Once you have successfully deployed a running cluster, changes to Airship and OpenStack components can be deployed using Shipyard actions or the Airskiff deployment scripts.

This example demonstrates deploying Armada changes using the Airskiff deployment scripts.

Note

${ARMADA} is the path to your cloned Armada repository that contains the changes you wish to deploy. ${TREASUREMAP} is the path to your cloned Treasuremap repository.

Build Armada:

cd ${ARMADA}
make images

Update Airship components:

cd ${TREASUREMAP}
./tools/deployment/airskiff/developer/030-armada-bootstrap.sh

Troubleshooting¶

This section is intended to help you through the initial troubleshooting process. If issues persist after following this guide, please join us on IRC: #airshipit (freenode)

Missing value auth-url required for auth plugin password

If this error message appears when using the OpenStack client, verify your client is configured for authentication:

# For Airship services
export OS_CLOUD=airship

# For OpenStack services
export OS_CLOUD=openstack