
Getting Started
***************


Manual Installation
===================

To test out the current code you will need the following installed:

* Python2.6+

* virtualenv

* etcd2 (running)

* Kubernetes Cluster with a bearer token for access (running)

* (Optional) docker (running)


Set up virtualenv
-----------------

   $ virtualenv /where/you/want/it/to/live
   ...
   (virtualenv)$ . /where/you/want/it/to/live/bin/activate
   (virtualenv)$ pip install -r requirements.txt
   ...


(Optional): Run Unittests
-------------------------

If you are running from the matest master it's a good idea to verify
that all the unittests run. From the repo root...

   (virtualenv)$ pip install -r test-requirements.txt
   ...
   (virtualenv)$ python setup.py nosetests


Setup Overlay Network Configuration
-----------------------------------

Flannel requires a configuration inside of etcd.

Note: For more information as to why this is necessary see the
  flannel documentation or the Project Atomic Getting Started Guide

   (virtualenv)$  etcdctl set '/atomic01/network/config' '{"Network": "172.16.0.0/12", "SubnetLen": 24, "Backend": {"Type": "vxlan"}}'
   ...


(Optional): Put Configs in Etcd
-------------------------------

commissaire will default back to the local files but using Etcd is
where configuration should be stored.

   (virtualenv)$ cat conf/users.json | etcdctl set '/commissaire/config/httpbasicauthbyuserlist'
   ...

   (virtualenv)$ cat conf/logger.json | etcdctl set '/commissaire/config/logger'
   ...


(Recommended) Set The Kubernetes Access Method
----------------------------------------------


Bearer Token
~~~~~~~~~~~~

To use a Bearer token:

Note: There is no default for the bearer token!

   (virtualenv)$ etcdctl set '/commissaire/config/kubetoken' $KUBERNETES_ACCESS_TOKEN


Client Certificate
~~~~~~~~~~~~~~~~~~

To use a client certificate:

Note: There is no default for the client certificate!

   (virtualenv)$ etcdctl set '/commissaire/config/kube_certificate_path' $PATH_TO_CRT_FILE
   ...
   (virtualenv)$ etcdctl set '/commissaire/config/kube_certificate_key_path' $PATH_TO_KEY_FILE
   ...


(Optional): Build Docker Container
----------------------------------

If you want to run from Docker and would like to build the image for
yourself run...

   docker build --tag commissaire .
   ...


Running the service
-------------------


From Source
~~~~~~~~~~~

From the repo root...

**Not So Secure Mode**

   (virtualenv)$ PYTHONPATH=`pwd`/src python src/commissaire/script.py \
       --etcd-uri http://192.168.152.100:2379 \
       --kube-uri http://192.168.152.101:8080 \
       --authentication-plugin commissaire.authentication.httpauthbyfile \
       --authentication-plugin-kwargs "filepath=conf/users.json" &
   ...

**More Secure Mode**

Note: Using client side certificates to access etcd/kubernetes will
  require proper configuration within etcd/kubernetes.

   (virtualenv)$ PYTHONPATH=`pwd`/src python src/commissaire/script.py  \
       --tls-keyfile /path/to/server.key \
       --tls-certificate /path/to/server.crt \
       --etcd-uri https://192.168.152.100:2379
       --etcd-cert-path /path/to/etcd_clientside.crt \
       --etcd-cert-key-path /path/to/etcd_clientside.key \
       --authentication-plugin commissaire.authentication.httpauthbyfile \
       --kube-uri https://192.168.152.101:8080 \
       --authentication-plugin-kwargs "filepath=conf/users.json" &
   ...


Via Docker
~~~~~~~~~~

To run the image specify the ETCD and KUBE variables pointing towards
the specific services.

Note: These commands assume you have put user configuration in etcd
  and are using the "commissaire.authentication.httpauthbyetcd"
  authentication plugin.

Note: Make sure that your firewall allows access to the etcd and
  kubernetes hosts and ports!

**Not So Secure Mode**

   docker run -d -p 8000:8000 -e ETCD=http://192.168.152.100:2379 -e KUBE=http://192.168.152.101:8080 commissaire
   ...

**More Secure Mode**

   docker run -d \
       -p 8000:8000
       -v /path/to/etcd/certificates:/certs \
       -e ETCD=https://192.168.152.100:2379 \
       -e KUBE=https://192.168.152.101:8080 \
       -e EXTRA_ARGS="--tls-certfile /certs/server.crt --tls-keyfile /certs/server.key --etcd-cert-path /certs/etcd.crt --etcd-cert-key-path /certs/etcd.key" \
       commissaire
   ...


Adding a Cluster
----------------

Verify that Commissaire is running as a container or in the virtual
environment then execute...

   curl -u "a:a" -XPUT -H "Content-Type: application/json" http://localhost:8000/api/v0/cluster/datacenter1
   ...


Adding a Host
-------------

Verify that Commissaire is running as a container or in the virtual
environment then execute...

   curl -u "a:a" -XPUT -H "Content-Type: application/json" http://localhost:8000/api/v0/host/192.168.1.100 -d '{"host": "192.168.1.100", "cluster": "datacenter1", "ssh_priv_key": "dGVzdAo="}'
   ...
