You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
treasuremap/doc/source/airskiff.rst

308 lines
8.1 KiB

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:
* `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