armada/doc/source/development/getting-started.rst

Developer Install Guide

Quick Start (via Container)

Note

If actively developing new Armada functionality, it is recommended to proceed with manual-installation instead.

To use the docker container to develop:

1. Clone the Armada repository.

2. cd into the cloned directory.

   $ git clone https://opendev.org/airship/armada.git && cd armada

3. Next, run the following commands to install tox, generate sample policy and configuration files, and build Armada charts as well as the Armada container image. Armada Dockerfile.DISTRO files are located in images/armada. Supported DISTROs are ubuntu_bionic and opensuse_leap15. By default, DISTRO is ubuntu_bionic.

   $ pip install tox
   
   $ tox -e genconfig
   $ tox -e genpolicy
   
   $ export DISTRO=distro_name
   $ docker build -f Dockerfile.${DISTRO} -t armada/latest
   
   $ make images

4. Run the container via Docker:

   $ docker run -d --name armada -v ~/.kube/:/armada/.kube/ -v $(pwd)/etc:/etc armada:local

   Note

   The first build will take several minutes. Afterward, it will build much faster.

Manual Installation

Pre-requisites

Armada has many pre-requisites because it relies on Helm, which itself has pre-requisites. The guide below consolidates the installation of all pre-requisites. For help troubleshooting individual resources, reference their installation guides.

Armada requires a Kubernetes cluster to be deployed, along with kubectl, Helm client, and Tiller (the Helm server).

1. Install Kubernetes (k8s) and deploy a k8s cluster.

   Reference the k8s-cluster-management section below for help.

2. Install and configure kubectl

3. Ensure that ~/.kube/config exists and is properly configured by executing:

   $ kubectl config view

   If the file does not exist, please create it by running:

   $ kubectl

4. Install and configure the Helm client.

5. Install and configure Tiller (Helm server).

6. Verify that Tiller is installed and running correctly by running:

$ kubectl get pods -n kube-system

Kubernetes Cluster Management

To test Armada fixes/features a Kubernetes cluster must be installed.

Either software is recommended:

• Kubeadm
• Kubeadm-AIO <https://docs.openstack.org/openstack-helm/latest/install/ developer/all-in-one.html>

Armada CLI Installation

Follow the steps below to install the Armada CLI.

Note

Some commands below use apt-get as the package management software. Use whichever command corresponds to the Linux distro being used.

Warning

Armada is tested against a Ubuntu 16.04 and Opensuse(leap15.1)environment.

Clone the Armada repository, cd into it:

git clone https://opendev.org/airship/armada.git && cd armada

It is recommended that Armada be run inside a virtual environment. To do so:

$ virtualenv -p python3 venv
...
>> New python executable in <...>/venv/bin/python3

Afterward, source the executable:

source <...>/venv/bin/activate

Next, ensure that pip is installed.

$ apt-get install -y python3-pip $ pip3 install --upgrade pip

Finally, run (from inside the Armada root directory):

$ (venv) make build

The above command will install pip requirements and execute python setup.py build within the virtual environment.

Verify that the Armada CLI is installed:

$ armada --help

Which should emit:

>> Usage: armada [OPTIONS] COMMAND [ARGS]...
>>
>>  Multi Helm Chart Deployment Manager
...

Armada API Server Installation

The Armada API server is not required in order to use the Armada CLI, which in this sense is standalone. The Armada CLI communicates with the Tiller server and, as such, no API server needs to be instantiated in order for Armada to communicate with Tiller. The Armada API server and CLI interface have the exact same functionality. However, the Armada API server offers the following additional functionality:

• Role-Based Access Control, allowing Armada to provide authorization around specific Armada (and by extension) Tiller functionality.
• Keystone authentication and project scoping, providing an additional layer of security.

Before proceeding, ensure that the steps in armada-cli-installation have been followed.

1. Determine where the Armada configuration/deployment files should be stored. The default location is /etc/armada. To override the default, run:

   $ export OS_ARMADA_CONFIG_DIR=<desired_path>

2. If the directory specified by OS_ARMADA_CONFIG_DIR is empty, run (from the Armada root directory):

   $ cp etc/armada/* <OS_ARMADA_CONFIG_DIR>/
   $ mv <OS_ARMADA_CONFIG_DIR>/armada.conf.sample <OS_ARMADA_CONFIG_DIR>/armada.conf

# Install uwsgi:

$ apt-get install uwsgi -y

1. Ensure that port 8000 is available or else change the PORT value in entrypoint.sh.

2. From the root Armada directory, execute:

   $ ./entrypoint.sh server

3. Verify that the Armada server is running by executing:

   $ TOKEN=$(openstack token issue --format value -c id)
   $ curl -i -X GET localhost:8000/versions -H "X-Auth-Token: $TOKEN"

   Note that the port above uses the default value in entrypoint.sh.

Development Utilities

Armada comes equipped with many utilities useful for developers, such as unit test or linting jobs.

Many of these commands require that tox be installed. To do so, run:

$ pip3 install tox

To run the Python linter, execute:

$ tox -e pep8

or

$ make test-pep8

To lint Helm charts, execute:

$ make lint

To run unit tests, execute:

$ tox -e py35

or

$ make test-unit

To run the test coverage job:

$ tox -e coverage

or

$ make test-coverage

To run security checks via Bandit execute:

$ tox -e bandit

or

$ make test-bandit

To build the docker images:

$ make images

To build all Armada charts, execute:

$ make charts

To build a helm template for the charts:

$ make dry-run

To run lint, charts, and image targets all at once:

$ make all

To render any documentation that has build steps:

$ tox -e docs

or

$ make docs

To build armada's image:

$ make run_armada

To build all images:

$ make run_images

To generate sample configuration and policy files needed for Armada deployment, execute (respectively):

$ tox -e genconfig
$ tox -e genpolicy

Troubleshooting

The error messages are included in bullets below and tips to resolution are included beneath each bullet.

• "FileNotFoundError: [Errno 2] No such file or directory: '/etc/armada/api-paste.ini'"

  Reason: this means that Armada is trying to instantiate the server but failing to do so because it can't find an essential configuration file.

  Solution:

  $ cp etc/armada/armada.conf.sample /etc/armada/armada.conf

  This copies the sample Armada configuration file to the appropriate directory.

• For any errors related to tox:

  Ensure that tox is installed:

  $ sudo apt-get install tox -y

• For any errors related to running tox -e py35:

  Ensure that python3-dev is installed:

  $ sudo apt-get install python3-dev -y