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 \
apparmor \
ca-certificates \
git \
make \
jq \
nmap \
curl \
uuid-runtime \
apt-transport-https \
ca-certificates \
software-properties-common
# Purge Docker and install Docker CE
sudo 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
# Enable apparmor
sudo systemctl enable apparmor
sudo systemctl start apparmor
# 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 && make images
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 ef3adc4d0e5d26e74590d2f78400f7e1d800dbcb
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
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:latest \
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