Airskiff

  • 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 KubeADM.
  • 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},172.17.0.1,.svc.cluster.local
export NO_PROXY=${NO_PROXY},172.17.0.1,.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 172.17.0.1 is the advertised IP address for the Kubernetes API server. 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 airship-treasuremap repository.

Install required packages

#!/bin/bash
set -xe

sudo apt-get update
sudo apt-get install --no-install-recommends -y \
        ca-certificates \
        git \
        make \
        jq \
        nmap \
        curl \
        uuid-runtime \
        apt-transport-https \
        ca-certificates \
        software-properties-common

# Purge Docker and install Docker CE
systemctl unmask docker.service
sudo apt-get remove --no-install-recommends -y docker docker-engine docker.io
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-add-repository \
        "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
        $(lsb_release -cs) \
        stable"

sudo apt-get update
sudo apt-get install --no-install-recommends -y docker-ce

# Add $USER to docker group
# NOTE: This requires re-authentication. Restart your shell.
sudo adduser "$(whoami)" docker

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

./tools/deployment/airskiff/developer/000-install-packages.sh

Restart your shell session

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

Build Airship components

#!/bin/bash
set -xe

# NOTE(drewwalters96): Build Airship components locally, for use as a
#   as a development environment.

CURRENT_DIR="$(pwd)"
: "${INSTALL_PATH:="../"}"

cd ${INSTALL_PATH}
git clone https://git.openstack.org/openstack/airship-armada.git
cd airship-armada
# NOTE(drewwalters96): Temporarily pin Armada to K8s v2.11.0.
git checkout dd75474d78e69f3634eb94c8ea6730b898e83277
make images IMAGE_TAG=dd75474d78e69f3634eb94c8ea6730b898e83277

cd ${INSTALL_PATH}
git clone https://git.openstack.org/openstack/airship-deckhand.git
cd airship-deckhand && make

cd ${INSTALL_PATH}
git clone https://git.openstack.org/openstack/airship-shipyard.git
cd airship-shipyard && make

cd ${INSTALL_PATH}
git clone https://git.openstack.org/openstack/airship-pegleg.git

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

cd openstack-helm-infra
git checkout 8662018a4dceb82a5d699d9e118caff9e5edb156

cd "${CURRENT_DIR}"

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

./tools/deployment/airskiff/developer/005-make-airship.sh

Deploy Kubernetes with KubeADM

#!/bin/bash
set -xe

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 a kubeadm-administered cluster.
cd ${OSH_INFRA_PATH}
make dev-deploy setup-host
make dev-deploy k8s
cd "${CURRENT_DIR}"

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

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

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

Setup OpenStack Client

#!/bin/bash
set -xe

# Install OpenStack client and create OpenStack client configuration file.
sudo -H -E pip install "cmd2<=0.8.7"
sudo -H -E pip 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: 'password'
      project_name: 'admin'
      project_domain_name: 'default'
      user_domain_name: 'default'
      auth_url: 'http://keystone.ucp.svc.cluster.local/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.openstack.svc.cluster.local/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)/../"}"

# Download latest Armada image and deploy Airship components
# NOTE(drewwalters96): Temporarily pin Armada to K8s v2.11.0.
docker run --rm --net host -p 8000:8000 --name armada \
    -v ~/.kube/config:/armada/.kube/config \
    -v "$(pwd)"/tools/deployment/airskiff/manifests/:/manifests \
    -v "${INSTALL_PATH}":/airship-components \
    quay.io/airshipit/armada:dd75474d78e69f3634eb94c8ea6730b898e83277 \
    apply /manifests/airship.yaml

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

# Deploy OpenStack using Airship
CURRENT_DIR="$(pwd)"
: "${PL_PATH:="../airship-pegleg"}"
: "${SY_PATH:="../airship-shipyard"}"

# NOTE: Image to use for all Pegleg operations
: "${PL_IMAGE:=quay.io/airshipit/pegleg:latest}"

# Lint deployment documents
: "${PEGLEG:="${PL_PATH}/tools/pegleg.sh"}"
: "${PL_SITE:="airskiff"}"

# 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.
IMAGE=${PL_IMAGE} TERM_OPTS=" " ${PEGLEG} site -r . lint "${PL_SITE}" -x P001 -x P009

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

IMAGE=${PL_IMAGE} TERM_OPTS="-l info" ${PEGLEG} site -r . collect ${PL_SITE} -s ${PL_OUTPUT}
cp -rp "${CURRENT_DIR}"/${PL_OUTPUT} ${SY_PATH}

# Deploy Airskiff site
cd ${SY_PATH}
: "${SHIPYARD:="./tools/shipyard.sh"}"

${SHIPYARD} create configdocs airskiff-design \
             --replace \
             --directory=/target/${PL_OUTPUT}

${SHIPYARD} commit configdocs
${SHIPYARD} create action update_software --allow-intermediate-commits
cd "${CURRENT_DIR}"

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/developer/airskiff/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