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
88
README.rst
88
README.rst
@ -3,63 +3,93 @@ Armada
|
||||
|
||||
|Docker Repository on Quay| |Build Status| |Doc Status|
|
||||
|
||||
Armada is a tool for managing multiple helm charts with dependencies by centralizing
|
||||
all configurations in a single Armada yaml and providing lifecycle
|
||||
hooks for all helm releases.
|
||||
Armada is a tool for managing multiple Helm charts with dependencies by centralizing
|
||||
all configurations in a single Armada YAML and providing lifecycle
|
||||
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
|
||||
-------
|
||||
|
||||
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
|
||||
------------
|
||||
|
||||
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
|
||||
|
||||
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/
|
||||
guide-use-armada.html>`_
|
||||
Manual Installation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
Get started guide can be found in our
|
||||
`Getting Started docs <http://armada-helm.readthedocs.io/en/latest/
|
||||
readme.html#getting-started>`_
|
||||
For a comprehensive manual installation guide, please
|
||||
see :ref:`dev-getting-started`.
|
||||
|
||||
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``
|
||||
$ armada apply examples/openstack-helm.yaml [--debug-loggging ]
|
||||
|
||||
- ``kubectl config view``
|
||||
- If it does not exist, you can create it using `kubectl`_
|
||||
Which should output something like this::
|
||||
|
||||
2. Check that you have a running Tiller
|
||||
$ armada apply examples/openstack-helm.yaml 2017-02-10 09:42:36,753
|
||||
|
||||
- ``kubectl get pods -n kube-system``
|
||||
armada INFO Cloning git:
|
||||
...
|
||||
|
||||
To run armada, simply supply it with your YAML based intention for any
|
||||
number of charts:
|
||||
For more information on how to install and use Armada, please reference:
|
||||
:ref:`guide-use-armada`.
|
||||
|
||||
::
|
||||
|
||||
$ armada apply examples/openstack-helm.yaml [--debug-loggging ]
|
||||
Integration Points
|
||||
------------------
|
||||
|
||||
Your output will look something like this:
|
||||
Armada CLI component has the following integration points:
|
||||
|
||||
::
|
||||
* `Tiller`_ manages Armada chart installations.
|
||||
* `Deckhand`_ supplies storage and management of site designs and secrets.
|
||||
|
||||
$ armada apply examples/openstack-helm.yaml 2017-02-10 09:42:36,753
|
||||
armada INFO Cloning git:
|
||||
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/
|
||||
.. _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
|
||||
:target: https://quay.io/repository/attcomdev/armada
|
||||
|
||||
@ -1,117 +1,278 @@
|
||||
***********
|
||||
Development
|
||||
***********
|
||||
.. _dev-getting-started:
|
||||
|
||||
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:
|
||||
|
||||
1. Fork the `Repository <http://github.com/att-comdev/armada>`_
|
||||
2. Clone the forked repo
|
||||
3. Change to the directory of the cloned repo
|
||||
#. Clone the `Armada repository <http://github.com/att-comdev/armada>`_.
|
||||
#. ``cd`` into the cloned directory.
|
||||
|
||||
.. 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
|
||||
tox -e genpolicy
|
||||
$ pip install tox
|
||||
|
||||
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::
|
||||
|
||||
The first build will take several minutes. Afterward, it will build much
|
||||
faster.
|
||||
|
||||
.. _manual-installation:
|
||||
|
||||
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::
|
||||
|
||||
The first build will take a little while. Afterwords, it will build much
|
||||
faster.
|
||||
Some commands below use ``apt-get`` as the package management software.
|
||||
Use whichever command corresponds to the Linux distro being used.
|
||||
|
||||
Virtualenv
|
||||
##########
|
||||
.. warning::
|
||||
|
||||
How to set up armada in your local using virtualenv:
|
||||
Armada is only tested against a Ubuntu 16.04 environment.
|
||||
|
||||
.. note::
|
||||
Clone the Armada repository, ``cd`` into it::
|
||||
|
||||
Suggest that you use a Ubuntu 16.04 VM
|
||||
git clone http://github.com/att-comdev/armada.git && cd armada
|
||||
|
||||
From the directory of the forked repository:
|
||||
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
|
||||
|
||||
Afterward, ``source`` the executable::
|
||||
|
||||
git clone http://github.com/att-comdev/armada.git && cd armada
|
||||
source <...>/venv/bin/activate
|
||||
|
||||
virtualenv -p python3 venv
|
||||
Next, ensure that ``pip`` is installed.
|
||||
|
||||
.. code-block:: bash
|
||||
$ apt-get install -y python3-pip
|
||||
$ pip3 install --upgrade pip
|
||||
|
||||
pip install -r requirements.txt -r test-requirements.txt
|
||||
Finally, run (from inside the Armada root directory)::
|
||||
|
||||
make bootstrap # install only requirements lib
|
||||
make bootstrap-all # install all requirements and tests lib
|
||||
$ (venv) make build
|
||||
|
||||
The above command will install ``pip`` requirements and execute
|
||||
``python setup.py build`` within the virtual environment.
|
||||
|
||||
.. code-block:: bash
|
||||
Verify that the Armada CLI is installed::
|
||||
|
||||
pip install .
|
||||
make build
|
||||
$ armada --help
|
||||
|
||||
Which should emit::
|
||||
|
||||
.. code-block:: bash
|
||||
>> Usage: armada [OPTIONS] COMMAND [ARGS]...
|
||||
>>
|
||||
>> Multi Helm Chart Deployment Manager
|
||||
...
|
||||
|
||||
# Testing your armada code
|
||||
# The tox command will execute lint, bandit, cover
|
||||
Armada API Server Installation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
pip install tox
|
||||
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:
|
||||
|
||||
tox
|
||||
make test-all
|
||||
* 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.
|
||||
|
||||
# Linting
|
||||
tox -e pep8
|
||||
make test-pep8
|
||||
make lint
|
||||
Before proceeding, ensure that the steps in :ref:`armada-cli-installation`
|
||||
have been followed.
|
||||
|
||||
# Bandit
|
||||
tox -e bandit
|
||||
make test-bandit
|
||||
#. Determine where the Armada configuration/deployment files should be stored.
|
||||
The default location is ``/etc/armada``. To override the default, run::
|
||||
|
||||
# Coverage
|
||||
tox -e coverage
|
||||
make test-coverage
|
||||
$ export OS_ARMADA_CONFIG_DIR=<desired_path>
|
||||
|
||||
# build charts
|
||||
make charts
|
||||
#. If the directory specified by ``OS_ARMADA_CONFIG_DIR`` is empty, run
|
||||
(from the Armada root directory)::
|
||||
|
||||
# policy and config are used in order to use and configure Armada API
|
||||
tox -e genconfig
|
||||
tox -e genpolicy
|
||||
$ cp etc/armada/* <OS_ARMADA_CONFIG_DIR>/
|
||||
$ mv <OS_ARMADA_CONFIG_DIR>/armada.conf.sample <OS_ARMADA_CONFIG_DIR>/armada.conf
|
||||
|
||||
# Install ``uwsgi``::
|
||||
|
||||
.. note::
|
||||
$ apt-get install uwsgi -y
|
||||
|
||||
If building from source, Armada requires that git be installed on
|
||||
the system.
|
||||
#. Ensure that port 8000 is available or else change the ``PORT`` value in
|
||||
``entrypoint.sh``.
|
||||
|
||||
Kubernetes
|
||||
##########
|
||||
#. From the root Armada directory, execute::
|
||||
|
||||
To test your armada fixes/features you will need to set-up a Kubernetes cluster.
|
||||
$ ./entrypoint.sh server
|
||||
|
||||
We recommend:
|
||||
#. Verify that the Armada server is running by executing::
|
||||
|
||||
`Kubeadm <https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/>`_
|
||||
$ TOKEN=$(openstack token issue --format value -c id)
|
||||
$ curl -i -X GET localhost:8000/versions -H "X-Auth-Token: $TOKEN"
|
||||
|
||||
`Kubeadm-AIO <https://docs.openstack.org/openstack-helm/latest/install/
|
||||
developer/all-in-one.html>`_
|
||||
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
|
||||
-------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user