308 lines
8.2 KiB
ReStructuredText
308 lines
8.2 KiB
ReStructuredText
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:
|
|
|
|
* `Armada`_
|
|
* `Deckhand`_
|
|
* `Pegleg`_
|
|
* `Shipyard`_
|
|
|
|
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``:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
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 ``airship-treasuremap``
|
|
repository.
|
|
|
|
Install required packages
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/000-install-packages.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./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.
|
|
|
|
Clone Dependencies
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/005-clone-dependencies.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./tools/deployment/airskiff/developer/005-clone-dependencies.sh
|
|
|
|
Deploy Kubernetes with Minikube
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/010-deploy-k8s.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./tools/deployment/airskiff/developer/010-deploy-k8s.sh
|
|
|
|
Setup OpenStack Client
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/020-setup-client.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./tools/deployment/airskiff/developer/020-setup-client.sh
|
|
|
|
Deploy Airship components using Armada
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/030-armada-bootstrap.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./tools/deployment/airskiff/developer/030-armada-bootstrap.sh
|
|
|
|
Deploy OpenStack using Airship
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. literalinclude:: ../../tools/deployment/airskiff/developer/100-deploy-osh.sh
|
|
:language: shell
|
|
:lines: 1,18-
|
|
|
|
Alternatively, this step can be performed by running the script directly:
|
|
|
|
.. code-block:: shell
|
|
|
|
./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``.
|
|
|
|
.. code-block:: shell
|
|
|
|
export OS_CLOUD=airship
|
|
|
|
List the Airship service endpoints:
|
|
|
|
.. code-block:: shell
|
|
|
|
openstack endpoint list
|
|
|
|
.. note:: ``${SHIPYARD}`` is the path to a cloned `Shipyard`_ repository.
|
|
|
|
Run Helm tests for all deployed releases:
|
|
|
|
.. code-block:: shell
|
|
|
|
${SHIPYARD}/tools/shipyard.sh create action test_site
|
|
|
|
List all `Shipyard`_ actions:
|
|
|
|
.. code-block:: shell
|
|
|
|
${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``:
|
|
|
|
.. code-block:: shell
|
|
|
|
export OS_CLOUD=openstack
|
|
|
|
List the OpenStack service endpoints:
|
|
|
|
.. code-block:: shell
|
|
|
|
openstack endpoint list
|
|
|
|
List ``Glance`` images:
|
|
|
|
.. code-block:: shell
|
|
|
|
openstack image list
|
|
|
|
Issue a new ``Keystone`` token:
|
|
|
|
.. code-block:: shell
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
cd ${ARMADA}
|
|
make images
|
|
|
|
Update Airship components:
|
|
|
|
.. code-block:: shell
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
# For Airship services
|
|
export OS_CLOUD=airship
|
|
|
|
# For OpenStack services
|
|
export OS_CLOUD=openstack
|
|
|
|
.. _Docker proxy guide: https://docs.docker.com/config/daemon/systemd/
|
|
#httphttps-proxy
|
|
|
|
.. _OpenStack-Helm project: https://docs.openstack.org/openstack-helm/latest/
|
|
install/developer/requirements-and-host-config.html
|
|
|
|
.. _Armada: https://opendev.org/airship/armada
|
|
.. _Deckhand: https://opendev.org/airship/deckhand
|
|
.. _Pegleg: https://opendev.org/airship/pegleg
|
|
.. _Shipyard: https://opendev.org/airship/shipyard
|
|
|
|
.. _Armada image: https://quay.io/repository/airshipit/armada?tab=tags
|
|
|
|
.. _airship-treasuremap: https://opendev.org/airship/treasuremap
|
|
|
|
.. _Shipyard actions: https://airship-shipyard.readthedocs.io/en/latest/
|
|
action-commands.html
|
|
|
|
.. _IRC: irc://chat.freenode.net:6697/airshipit
|
|
|
|
.. _site authoring and deployment guide: https://
|
|
airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html
|