docs(readme): Update Armada README/installation documentation
This PS revamps the Armada README and installation documentation to increase clarity about how to install and use Armada, and provide additional resource links to aid installation. This PS also fixes a few typos with the current readme. Change-Id: I6fafe8be8a2caf67c5bdecf5d5e682b580332e63
This commit is contained in:
Felipe Monteiro
parent
15957e5bd3
commit
03e9fc290c
96
README.rst
96
README.rst
@ -3,63 +3,93 @@ Armada
|
|||||||
|
|
||||||
|Docker Repository on Quay| |Build Status| |Doc Status|
|
|Docker Repository on Quay| |Build Status| |Doc Status|
|
||||||
|
|
||||||
Armada is a tool for managing multiple helm charts with dependencies by centralizing
|
Armada is a tool for managing multiple Helm charts with dependencies by centralizing
|
||||||
all configurations in a single Armada yaml and providing lifecycle
|
all configurations in a single Armada YAML and providing lifecycle
|
||||||
hooks for all helm releases.
|
hooks for all Helm releases.
|
||||||
|
|
||||||
|
Armada consists of two separate but complementary components:
|
||||||
|
|
||||||
|
#. CLI component (**mandatory**) which interfaces directly with `Tiller`_.
|
||||||
|
#. API component (**optional**) which services user requests through a wsgi
|
||||||
|
server (which in turn communicates with the `Tiller`_ server) and provides
|
||||||
|
the following additional functionality:
|
||||||
|
|
||||||
|
* Role-Based Access Control.
|
||||||
|
* Limiting projects to specific `Tiller`_ functionality by leveraging
|
||||||
|
project-scoping provided by `Keystone`_.
|
||||||
|
|
||||||
Roadmap
|
Roadmap
|
||||||
-------
|
-------
|
||||||
|
|
||||||
Detailed roadmap can be viewed `here <https://github.com/att-comdev/armada/milestones>`_
|
Detailed roadmap can be viewed `here <https://github.com/att-comdev/armada/milestones>`_.
|
||||||
|
|
||||||
Issues can be reported `on GitHub <https://github.com/att-comdev/armada/issues>`_
|
Issues can be reported `on GitHub <https://github.com/att-comdev/armada/issues>`_.
|
||||||
|
|
||||||
Installation
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
Quick Start (via Container)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Armada can be most easily installed as a container, which requires Docker to be
|
||||||
|
executed. To install Docker, please reference the following
|
||||||
|
`install guide <https://docs.docker.com/engine/installation/>`_.
|
||||||
|
|
||||||
|
Afterward, you can launch the Armada container by executing:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
docker run -d --net host -p 8000:8000 --name armada -v ~/.kube/config:/armada/.kube/config -v $(pwd)/examples/:/examples quay.io/attcomdev/armada:latest
|
$ sudo docker run -d --net host -p 8000:8000 --name armada \
|
||||||
|
-v ~/.kube/config:/armada/.kube/config \
|
||||||
|
-v $(pwd)/examples/:/examples quay.io/attcomdev/armada:latest
|
||||||
|
|
||||||
Using armada `docs <http://armada-helm.readthedocs.io/en/latest/operations/
|
Manual Installation
|
||||||
guide-use-armada.html>`_
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Getting Started
|
For a comprehensive manual installation guide, please
|
||||||
---------------
|
see :ref:`dev-getting-started`.
|
||||||
|
|
||||||
Get started guide can be found in our
|
|
||||||
`Getting Started docs <http://armada-helm.readthedocs.io/en/latest/
|
|
||||||
readme.html#getting-started>`_
|
|
||||||
|
|
||||||
Usage
|
Usage
|
||||||
-----
|
^^^^^
|
||||||
|
|
||||||
Before using armada we need to check a few things:
|
To run Armada, simply supply it with your YAML-based intention for any
|
||||||
|
number of charts::
|
||||||
1. you have a properly configure ``~/.kube/config``
|
|
||||||
|
|
||||||
- ``kubectl config view``
|
|
||||||
- If it does not exist, you can create it using `kubectl`_
|
|
||||||
|
|
||||||
2. Check that you have a running Tiller
|
|
||||||
|
|
||||||
- ``kubectl get pods -n kube-system``
|
|
||||||
|
|
||||||
To run armada, simply supply it with your YAML based intention for any
|
|
||||||
number of charts:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ armada apply examples/openstack-helm.yaml [--debug-loggging ]
|
$ armada apply examples/openstack-helm.yaml [--debug-loggging ]
|
||||||
|
|
||||||
Your output will look something like this:
|
Which should output something like this::
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ armada apply examples/openstack-helm.yaml 2017-02-10 09:42:36,753
|
$ armada apply examples/openstack-helm.yaml 2017-02-10 09:42:36,753
|
||||||
|
|
||||||
armada INFO Cloning git:
|
armada INFO Cloning git:
|
||||||
|
...
|
||||||
|
|
||||||
|
For more information on how to install and use Armada, please reference:
|
||||||
|
:ref:`guide-use-armada`.
|
||||||
|
|
||||||
|
|
||||||
|
Integration Points
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Armada CLI component has the following integration points:
|
||||||
|
|
||||||
|
* `Tiller`_ manages Armada chart installations.
|
||||||
|
* `Deckhand`_ supplies storage and management of site designs and secrets.
|
||||||
|
|
||||||
|
In addition, Armada's API component has the following integration points:
|
||||||
|
|
||||||
|
* `Keystone`_ (OpenStack's identity service) provides authentication and
|
||||||
|
support for role-based authorization.
|
||||||
|
|
||||||
|
Further Reading
|
||||||
|
---------------
|
||||||
|
|
||||||
|
`Undercloud Platform (UCP) <https://github.com/att-comdev/ucp-integration>`_.
|
||||||
|
|
||||||
.. _kubectl: https://kubernetes.io/docs/user-guide/kubectl/kubectl_config/
|
.. _kubectl: https://kubernetes.io/docs/user-guide/kubectl/kubectl_config/
|
||||||
|
.. _Tiller: https://docs.helm.sh/using_helm/#easy-in-cluster-installation
|
||||||
|
.. _Deckhand: https://github.com/openstack/deckhand
|
||||||
|
.. _Keystone: https://github.com/openstack/keystone
|
||||||
|
|
||||||
.. |Docker Repository on Quay| image:: https://quay.io/repository/attcomdev/armada/status
|
.. |Docker Repository on Quay| image:: https://quay.io/repository/attcomdev/armada/status
|
||||||
:target: https://quay.io/repository/attcomdev/armada
|
:target: https://quay.io/repository/attcomdev/armada
|
||||||
|
|||||||
@ -1,117 +1,278 @@
|
|||||||
***********
|
.. _dev-getting-started:
|
||||||
Development
|
|
||||||
***********
|
|
||||||
|
|
||||||
Docker
|
Developer Install Guide
|
||||||
######
|
=======================
|
||||||
|
|
||||||
|
Quick Start (via Container)
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
If actively developing new Armada functionality, it is recommended to proceed
|
||||||
|
with :ref:`manual-installation` instead.
|
||||||
|
|
||||||
To use the docker container to develop:
|
To use the docker container to develop:
|
||||||
|
|
||||||
1. Fork the `Repository <http://github.com/att-comdev/armada>`_
|
#. Clone the `Armada repository <http://github.com/att-comdev/armada>`_.
|
||||||
2. Clone the forked repo
|
#. ``cd`` into the cloned directory.
|
||||||
3. Change to the directory of the cloned repo
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
git clone http://github.com/att-comdev/armada.git && cd armada
|
$ git clone http://github.com/att-comdev/armada.git && cd armada
|
||||||
|
|
||||||
pip install tox
|
#. 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::
|
||||||
|
|
||||||
tox -e genconfig
|
$ pip install tox
|
||||||
tox -e genpolicy
|
|
||||||
|
|
||||||
docker build . -t armada/latest
|
$ tox -e genconfig
|
||||||
|
$ tox -e genpolicy
|
||||||
|
|
||||||
make images
|
$ docker build . -t armada/latest
|
||||||
|
|
||||||
|
$ make images
|
||||||
|
|
||||||
.. code-block:: bash
|
#. Run the container via Docker::
|
||||||
|
|
||||||
# Run Docker Image
|
$ docker run -d --name armada -v ~/.kube/:/armada/.kube/ -v $(pwd)/etc:/etc armada:local
|
||||||
docker run -d --name armada -v ~/.kube/:/armada/.kube/ -v $(pwd)/etc:/etc armada:local
|
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
.. note::
|
The first build will take several minutes. Afterward, it will build much
|
||||||
|
|
||||||
The first build will take a little while. Afterwords, it will build much
|
|
||||||
faster.
|
faster.
|
||||||
|
|
||||||
Virtualenv
|
.. _manual-installation:
|
||||||
##########
|
|
||||||
|
|
||||||
How to set up armada in your local using virtualenv:
|
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).
|
||||||
|
|
||||||
|
#. Install Kubernetes (k8s) and deploy a k8s cluster.
|
||||||
|
|
||||||
|
This can be accomplished by cloning the
|
||||||
|
`k8s repo <https://github.com/kubernetes/kubernetes>_` and running
|
||||||
|
``kube-up.sh`` in ``kubernetes/cluster``.
|
||||||
|
|
||||||
|
Alternatively, reference the :ref:`k8s-cluster-management` section below.
|
||||||
|
|
||||||
|
#. Install and configure `kubectl`_
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
|
||||||
|
#. Install and configure the `Helm`_ client.
|
||||||
|
|
||||||
|
#. Install and configure `Tiller`_ (Helm server).
|
||||||
|
|
||||||
|
#. Verify that Tiller is installed and running correctly by running:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ kubectl get pods -n kube-system
|
||||||
|
|
||||||
|
.. _k8s-cluster-management:
|
||||||
|
|
||||||
|
Kubernetes Cluster Management
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
To test Armada fixes/features a Kubernetes cluster must be installed.
|
||||||
|
|
||||||
|
Either software is recommended:
|
||||||
|
|
||||||
|
* `Kubeadm <https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/>`_
|
||||||
|
|
||||||
|
* `Kubeadm-AIO <https://docs.openstack.org/openstack-helm/latest/install/
|
||||||
|
developer/all-in-one.html>`_
|
||||||
|
|
||||||
|
.. _armada-cli-installation:
|
||||||
|
|
||||||
|
Armada CLI Installation
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Follow the steps below to install the Armada CLI.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Suggest that you use a Ubuntu 16.04 VM
|
Some commands below use ``apt-get`` as the package management software.
|
||||||
|
Use whichever command corresponds to the Linux distro being used.
|
||||||
|
|
||||||
From the directory of the forked repository:
|
.. warning::
|
||||||
|
|
||||||
.. code-block:: bash
|
Armada is only tested against a Ubuntu 16.04 environment.
|
||||||
|
|
||||||
|
Clone the Armada repository, ``cd`` into it::
|
||||||
|
|
||||||
git clone http://github.com/att-comdev/armada.git && cd armada
|
git clone http://github.com/att-comdev/armada.git && cd armada
|
||||||
|
|
||||||
virtualenv -p python3 venv
|
It is recommended that Armada be run inside a virtual environment. To do so::
|
||||||
|
|
||||||
.. code-block:: bash
|
$ virtualenv -p python3 venv
|
||||||
|
...
|
||||||
|
>> New python executable in <...>/venv/bin/python3
|
||||||
|
|
||||||
pip install -r requirements.txt -r test-requirements.txt
|
Afterward, ``source`` the executable::
|
||||||
|
|
||||||
make bootstrap # install only requirements lib
|
source <...>/venv/bin/activate
|
||||||
make bootstrap-all # install all requirements and tests lib
|
|
||||||
|
|
||||||
|
Next, ensure that ``pip`` is installed.
|
||||||
|
|
||||||
.. code-block:: bash
|
$ apt-get install -y python3-pip
|
||||||
|
$ pip3 install --upgrade pip
|
||||||
|
|
||||||
pip install .
|
Finally, run (from inside the Armada root directory)::
|
||||||
make build
|
|
||||||
|
|
||||||
|
$ (venv) make build
|
||||||
|
|
||||||
.. code-block:: bash
|
The above command will install ``pip`` requirements and execute
|
||||||
|
``python setup.py build`` within the virtual environment.
|
||||||
|
|
||||||
# Testing your armada code
|
Verify that the Armada CLI is installed::
|
||||||
# The tox command will execute lint, bandit, cover
|
|
||||||
|
|
||||||
pip install tox
|
$ armada --help
|
||||||
|
|
||||||
tox
|
Which should emit::
|
||||||
make test-all
|
|
||||||
|
|
||||||
# Linting
|
>> Usage: armada [OPTIONS] COMMAND [ARGS]...
|
||||||
tox -e pep8
|
>>
|
||||||
make test-pep8
|
>> Multi Helm Chart Deployment Manager
|
||||||
make lint
|
...
|
||||||
|
|
||||||
# Bandit
|
Armada API Server Installation
|
||||||
tox -e bandit
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
make test-bandit
|
|
||||||
|
|
||||||
# Coverage
|
The Armada API server is not required in order to use the Armada CLI,
|
||||||
tox -e coverage
|
which in this sense is standalone. The Armada CLI communicates with the Tiller
|
||||||
make test-coverage
|
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:
|
||||||
|
|
||||||
# build charts
|
* Role-Based Access Control, allowing Armada to provide authorization around
|
||||||
make charts
|
specific Armada (and by extension) Tiller functionality.
|
||||||
|
* `Keystone`_ authentication and project scoping, providing an additional
|
||||||
|
layer of security.
|
||||||
|
|
||||||
# policy and config are used in order to use and configure Armada API
|
Before proceeding, ensure that the steps in :ref:`armada-cli-installation`
|
||||||
tox -e genconfig
|
have been followed.
|
||||||
tox -e genpolicy
|
|
||||||
|
|
||||||
|
#. Determine where the Armada configuration/deployment files should be stored.
|
||||||
|
The default location is ``/etc/armada``. To override the default, run::
|
||||||
|
|
||||||
.. note::
|
$ export OS_ARMADA_CONFIG_DIR=<desired_path>
|
||||||
|
|
||||||
If building from source, Armada requires that git be installed on
|
#. If the directory specified by ``OS_ARMADA_CONFIG_DIR`` is empty, run
|
||||||
the system.
|
(from the Armada root directory)::
|
||||||
|
|
||||||
Kubernetes
|
$ cp etc/armada/* <OS_ARMADA_CONFIG_DIR>/
|
||||||
##########
|
$ mv <OS_ARMADA_CONFIG_DIR>/armada.conf.sample <OS_ARMADA_CONFIG_DIR>/armada.conf
|
||||||
|
|
||||||
To test your armada fixes/features you will need to set-up a Kubernetes cluster.
|
# Install ``uwsgi``::
|
||||||
|
|
||||||
We recommend:
|
$ apt-get install uwsgi -y
|
||||||
|
|
||||||
`Kubeadm <https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/>`_
|
#. Ensure that port 8000 is available or else change the ``PORT`` value in
|
||||||
|
``entrypoint.sh``.
|
||||||
|
|
||||||
`Kubeadm-AIO <https://docs.openstack.org/openstack-helm/latest/install/
|
#. From the root Armada directory, execute::
|
||||||
developer/all-in-one.html>`_
|
|
||||||
|
$ ./entrypoint.sh server
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
|
||||||
|
To lint Helm charts, execute::
|
||||||
|
|
||||||
|
$ make lint
|
||||||
|
|
||||||
|
To run unit tests, execute::
|
||||||
|
|
||||||
|
$ tox -e py35
|
||||||
|
|
||||||
|
To run the test coverage job::
|
||||||
|
|
||||||
|
$ tox -e coverage
|
||||||
|
|
||||||
|
To run security checks via `Bandit`_ execute::
|
||||||
|
|
||||||
|
$ tox -e bandit
|
||||||
|
|
||||||
|
To build all Armada charts, execute::
|
||||||
|
|
||||||
|
$ make charts
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
.. _Bandit: https://github.com/openstack/bandit
|
||||||
|
.. _kubectl: https://kubernetes.io/docs/user-guide/kubectl/kubectl_config/
|
||||||
|
.. _Helm: https://docs.helm.sh/using_helm/#installing-helm
|
||||||
|
.. _Keystone: https://github.com/openstack/keystone
|
||||||
|
.. _Tiller: https://docs.helm.sh/using_helm/#easy-in-cluster-installation
|
||||||
|
|||||||
@ -1,5 +1,7 @@
|
|||||||
Armada - Using Armada
|
.. _guide-use-armada:
|
||||||
=====================
|
|
||||||
|
Armada Install & Usage Guide
|
||||||
|
============================
|
||||||
|
|
||||||
Prerequisites
|
Prerequisites
|
||||||
-------------
|
-------------
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user