Merge "docs(readme): Update Armada README/installation documentation"
This commit is contained in:
commit
cc322b6f73
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