From 818aba66b24e0094f234f38b4f78b28a8ec46247 Mon Sep 17 00:00:00 2001 From: gardlt Date: Mon, 3 Jul 2017 11:21:22 -0500 Subject: [PATCH] [docs] update readme --- README.rst | 83 ++++----------------- docs/source/development/getting-started.rst | 15 ++-- docs/source/operations/guide-use-armada.rst | 72 ++++++++++++++++++ docs/source/operations/index.rst | 1 + examples/openstack-helm.yaml | 50 +++++-------- 5 files changed, 115 insertions(+), 106 deletions(-) create mode 100644 docs/source/operations/guide-use-armada.rst diff --git a/README.rst b/README.rst index 71e000c0..7404c315 100644 --- a/README.rst +++ b/README.rst @@ -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 `_ -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 /armada - docker run -d --name armada -v ~/.kube/config:/root/.kube/config -v $(pwd)/examples/:/examples /armada +Issues can be reported `here `_ 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 `_ -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 `_ -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: diff --git a/docs/source/development/getting-started.rst b/docs/source/development/getting-started.rst index 23c5b6aa..54273aa6 100644 --- a/docs/source/development/getting-started.rst +++ b/docs/source/development/getting-started.rst @@ -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 `_ -`Kubeadm-aio `_ - -.. note:: When using Halcyon it will not generate a config file. Run the following commands to create one: `get_k8s_creds.sh `_ +`Kubeadm-AIO `_ diff --git a/docs/source/operations/guide-use-armada.rst b/docs/source/operations/guide-use-armada.rst new file mode 100644 index 00000000..73fc16ee --- /dev/null +++ b/docs/source/operations/guide-use-armada.rst @@ -0,0 +1,72 @@ +Armada - Using Armada +===================== + +Prerequisites +------------- + +Kubernetes Cluster + +Tiller Service `here `_ + +Armada.yaml `here `_ + +.. 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 `_ + +.. 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 diff --git a/docs/source/operations/index.rst b/docs/source/operations/index.rst index 33c2b6a5..66f4910a 100644 --- a/docs/source/operations/index.rst +++ b/docs/source/operations/index.rst @@ -12,3 +12,4 @@ Operations Guide guide-troubleshooting.rst guide-build-armada-yaml.rst + guide-use-armada.rst diff --git a/examples/openstack-helm.yaml b/examples/openstack-helm.yaml index 9ca4318a..0f170c14 100644 --- a/examples/openstack-helm.yaml +++ b/examples/openstack-helm.yaml @@ -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: