diff --git a/README.rst b/README.rst index 2d85d7da..9900eadf 100644 --- a/README.rst +++ b/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 `_ +Detailed roadmap can be viewed `here `_. -Issues can be reported `on GitHub `_ +Issues can be reported `on GitHub `_. 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 `_. + +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 `_ +Manual Installation +^^^^^^^^^^^^^^^^^^^ -Getting Started ---------------- - -Get started guide can be found in our -`Getting Started docs `_ +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) `_. .. _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 diff --git a/docs/source/development/getting-started.rst b/docs/source/development/getting-started.rst index 68062d47..1cde54ce 100644 --- a/docs/source/development/getting-started.rst +++ b/docs/source/development/getting-started.rst @@ -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 `_ -2. Clone the forked repo -3. Change to the directory of the cloned repo +#. Clone the `Armada repository `_. +#. ``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 _` 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 `_ + +* `Kubeadm-AIO `_ + +.. _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= - # 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/* / + $ mv /armada.conf.sample /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 `_ + $ TOKEN=$(openstack token issue --format value -c id) + $ curl -i -X GET localhost:8000/versions -H "X-Auth-Token: $TOKEN" -`Kubeadm-AIO `_ + 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 diff --git a/docs/source/operations/guide-use-armada.rst b/docs/source/operations/guide-use-armada.rst index e179153c..a467795b 100644 --- a/docs/source/operations/guide-use-armada.rst +++ b/docs/source/operations/guide-use-armada.rst @@ -1,5 +1,7 @@ -Armada - Using Armada -===================== +.. _guide-use-armada: + +Armada Install & Usage Guide +============================ Prerequisites -------------