[docs] update readme

This commit is contained in:
gardlt 2017-07-03 11:21:22 -05:00 committed by Alexis Rivera DeLa Torre
parent 35249aac88
commit 818aba66b2
5 changed files with 115 additions and 106 deletions

View File

@ -3,84 +3,33 @@ Armada
|Docker Repository on Quay| |Build Status| |Doc Status|
A python orchestrator for a installing, upgrading, and managing a
collection of helm charts, dependencies, and values overrides.
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 hem releases.
Note that this project is pre-alpha and under active development. It may
undergo drastic changes to support the long-term vision but
contributions are welcome.
Roadmap
-------
Overview
--------
Detailed roadmap can be viewed `here <https://github.com/att-comdev/armada/milestones>`_
The armada python library and command line tool provides a way to
synchronize a helm (tiller) target with an operators intended state,
consisting of several charts, dependencies, and overrides using a single
file or directory with a collection of files. This allows operators to
define many charts, potentially with different namespaces for those
releases, and their overrides in a central place. With a single command,
deploy and/or upgrade them where applicable.
Armada also supports fetching helm chart source and then building charts
from source from various local and remote locations, such as git/github
endpoints. In the future, it may supprot other mechanisms as well.
It will also give the operator some indication of what is about to
change by assisting with diffs for both values, values overrides, and
actual template changes.
Its functionality may extend beyond helm, assisting in interacting with
kubernetes directly to perform basic pre and post steps, such as
removing completed or failed jobs, running backup jobs, blocking on
chart readiness, or deleting resources that do not support upgrades.
However, primarily, it will be an interface to support orchestrating
Helm.
Running Armada
--------------
To use this container, use these simple instructions:
::
docker run -d --name armada -v ~/.kube/config:/root/.kube/config -v $(pwd)/examples/:/examples quay.io/attcomdev/armada:latest
Manual Install
~~~~~~~~~~~~~~
If you want to build the docker image, follow these steps:
::
docker build . -t <namespace>/armada
docker run -d --name armada -v ~/.kube/config:/root/.kube/config -v $(pwd)/examples/:/examples <namespace>/armada
Issues can be reported `here <https://github.com/att-comdev/armada/issues>`_
Installation
------------
The installation is fairly straight forward:
.. code-block:: bash
Recomended Enviroment: Ubuntu 16.04
docker run -d --net host -p 8000:8000 --name armada -v ~/.kube/config:/root/.kube/config -v $(pwd)/examples/:/examples quay.io/attcomdev/armada:latest
Installing Dependecies
~~~~~~~~~~~~~~~~~~~~~~
Using armada `docs <docs/source/operations/guide-use-armada.rst>`_
you can run:
Getting Started
---------------
- ``tox testenv:ubuntu`` or ``sudo sh tools/libgit2.sh``
- ``sudo pip install -r requirements.txt``
Get started guide can be found in our `docs <docs/source/development/getting-started.rst>`_
NOTE: If you want to use virtualenv please refer to `pygit2`_
Installing armada
~~~~~~~~~~~~~~~~~
``sudo pip install -e .``
``armada [-h | --help]``
Using Armada
------------
Usage
-----
Before using armada we need to check a few things:
@ -98,7 +47,7 @@ number of charts:
::
$ armada apply examples/openstack-helm.yaml [--debug ]
$ armada apply examples/openstack-helm.yaml [--debug-loggging ]
Your output will look something like this:

View File

@ -22,9 +22,8 @@ To use the docker containter to develop:
.. note::
The first build will take a little while. Afterwards the it will much faster
3. EZPZ :)
The first build will take a little while. Afterwords, it will build much
faster.
Virtualenv
##########
@ -47,10 +46,12 @@ From the directory of the forked repository:
pip install -r requirements.txt
pip install -r test-requirements.txt
pip install -e .
Your env is now ready to go! :)
.. note::
.. note:: this will install latest libgit2 library so you have to make sure you install the same version library with pip ( current version: 0.25.0 )
this will install the latest libgit2 library so you have to make sure you
install the same version library with pip ( current version: 0.25.0 )
Kubernetes
##########
@ -61,6 +62,4 @@ We recommend:
`Kubeadm <https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/>`_
`Kubeadm-aio <https://github.com/openstack/openstack-helm/tree/master/tools/kubeadm-aio>`_
.. note:: When using Halcyon it will not generate a config file. Run the following commands to create one: `get_k8s_creds.sh <https://github.com/att-comdev/halcyon-vagrant-kubernetes#accessing-the-cluster>`_
`Kubeadm-AIO <https://github.com/openstack/openstack-helm/tree/master/tools/kubeadm-aio>`_

View File

@ -0,0 +1,72 @@
Armada - Using Armada
=====================
Prerequisites
-------------
Kubernetes Cluster
Tiller Service `here <http://github.com/kubernetes/helm>`_
Armada.yaml `here <guide-build-armada-yaml.rst>`_
.. note::
Need to have provided a storage system prior(ceph, nfs)
Usage
-----
1. Pull or Build the Armada Docker Images:
.. code:: bash
Pull:
docker pull quay.io/attcomdev/armada:latest
Build:
git clone https://github.com/att-comdev/armada
cd armada/
docker build . -t quay.io/attcomdev/armada:latest
2. Run Armada docker container
.. note::
Make sure to mount your kubeconfig into ``/root/.kube/config`` in
the container
.. note::
To run you custom Armada.yamls you need to mount them into the container as
shown below.
This example is using ``examples/`` directory in armada `repo <https://github.com/att-comdev/armada/tree/master/examples>`_
.. code:: bash
docker run -d --net host -p 8000:8000 --name armada -v ~/.kube/config:/root/.kube/config -v $(pwd)/examples/:/examples quay.io/attcomdev/armada:latest
3. Check that tiller is Available
.. code:: bash
docker exec -it armada armada tiller --status
4. If tiller is up then we can start deploying our armada yamls
.. code:: bash
docker exec -it armada armada apply /examples/openstack-helm.yaml [ --debug-logging ]
5. To upgrade charts just modify the armada yaml or chart code and re-run ``armada
apply`` above
6. To check deployed releases:
.. code:: bash
docker exec -it armada armada tiller --releases

View File

@ -12,3 +12,4 @@ Operations Guide
guide-troubleshooting.rst
guide-build-armada-yaml.rst
guide-use-armada.rst

View File

@ -1,10 +1,10 @@
armada:
release_prefix: armada
charts:
- description: Generate Bootstrap keys
- description: Deploys Helm Toolkit and Mariadb
sequenced: True
chart_group:
- chart: &helm-toolkit
- chart: &helm-toolkit
name: helm-toolkit
release_name: null
namespace: null
@ -15,34 +15,23 @@ armada:
subpath: helm-toolkit
reference: master
dependencies: []
- chart: &bootstrap-openstack
name: bootstrap-openstack
release_name: openstack
namespace: openstack
values: {}
source:
type: local
location: /home/ubuntu/openstack-helm
subpath: bootstrap
reference: master
dependencies: []
- chart: &mariadb
name: mariadb
release_name: mariadb
namespace: openstack
timeout: 50
install:
no_hooks: false
upgrade:
no_hooks: false
values: {}
source:
type: git
location: git://github.com/openstack/openstack-helm
subpath: mariadb
reference: master
dependencies:
- *helm-toolkit
- chart: &mariadb
name: mariadb
release_name: mariadb
namespace: openstack
timeout: 3360
install:
no_hooks: false
upgrade:
no_hooks: false
values: {}
source:
type: git
location: git://github.com/openstack/openstack-helm
subpath: mariadb
reference: master
dependencies:
- *helm-toolkit
- description: Undercloud Services add-ons
sequenced: False
chart_group:
@ -98,7 +87,6 @@ armada:
reference: master
dependencies:
- *helm-toolkit
- description: Openstack Services
sequenced: false
chart_group: