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


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

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

* Python2.7 or Python3.1+

* virtualenv

* etcd2 (running)

* OpenShift or Kubernetes Cluster (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...

   $ tox
   ...


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) Set The OpenShift or Kubernetes Access Method
--------------------------------------------------------

There are two methods for accessing the container manager: Client Side
Certificate and Bearer Token. Only one is needed when working with a
secured Kubernetes installation.


(Recommended) Client Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To configure a client certificate:

Note: There is no default for the client certificate!

   $ cat /etc/commissaire/commissaire.conf
   {
     ...
     "register-store-handler": [
       {
         "name": "commissaire.store.kubestorehandler",
         ...
         "certificate_path": "/path/to/kube_clientside.crt",
         "certificate_key_path": "/path/to/kube_clientside.key"
       }
     ]
   }


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

To configure a Bearer token:

Note: There is no default for the bearer token!

   $ cat /etc/commissaire/commissaire.conf
   {
     ...
     "register-store-handler": [
       "name": "commissaire.store.kubestorehandler",
       ...
       "token": "$KUBERNETES_ACCESS_TOKEN"
     ]
   }


(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
-------------------

Most of Commissaire's command-line options can be specified in a JSON
configuration file, by default "/etc/commissaire/commissaire.conf" or
as specified by the "--config-file" option.

Note: Command-line options take precedence over the configuration
  file.

Note: The URI you give for etcd and Kubernetes via the CLI will be
  fed into the configuration files on remote host nodes. Make sure to
  use the public IP of the etcd and Kubernetes hosts.


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

To launch the server from the repo root, with a configuration file
such as those given below:

   (virtualenv)$ pip install -e /path/to/commissaire/checkout
   ...
   (virtualenv)$ commissaire --config-file=/etc/commissaire/commissaire.conf &
   ...

**Not So Secure Configuration**

   $ cat /etc/commissaire/commissaire.conf
   {
     "listen-interface": "127.0.0.1",
     "listen-port": 8000,
     "register-store-handler": [
       {
         "name": "commissaire.store.kubestorehandler",
         "server_url": "http://192.168.152.102:8080",
         "models": ["*"]
       },
       {
         "name": "commissaire.store.etcdstorehandler",
         "server_url": "http://192.168.152.101:2379",
         "models": []
       }
     ],
     "authentication-plugin": {
       "name": "commissaire.authentication.httpbasicauth",
       "users": {
         "a": {
           "hash": "$2a$12$GlBCEIwz85QZUCkWYj11he6HaRHufzIvwQjlKeu7Rwmqi/mWOpRXK"
         }
       }
     }
   }

**More Secure Configuration**

Note: Using client side certificates to access etcd/kubernetes will
  require proper configuration within etcd/kubernetes.Also, this
  example shows placing hashed user passwords in a separate
  *users.json* file, presumably with more restrictive access
  permissions.

   $ cat /etc/commissaire/commissaire.conf
   {
     "listen-interface": "127.0.0.1",
     "listen-port": 8000,
     "tls-certfile": "/path/to/server.crt",
     "tls-keyfile": "/path/to/server.key",
     "register-store-handler": [
       {
         "name": "commissaire.store.kubestorehandler",
         "server_url": "https://192.168.152.101:8080",
         "certificate_path": "/path/to/kube_clientside.crt",
         "certificate_key_path": "/path/to/kube_clientside.key",
         "models": ["*"]
       },
       {
         "name": "commissaire.store.etcdstorehandler",
         "server_url": "https://192.168.152.100:2379",
         "certificate_path": "/path/to/etcd_clientside.crt",
         "certificate_key_path": "/path/to/etcd_clientside.key",
         "models": []
       }
     ],
     "authentication-plugin": {
       "name": "commissaire.authentication.httpbasicauth",
       "filepath": "conf/users.json"
     }
   }


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

To run the image, place a "commissaire.conf" file (see the examples
above) in an empty directory and then bind-mount the directory to
"/etc/commissaire" in the container.

Similarly, if you are using client-side certificates, place the
certificate files in an empty directory and then bind-mount the
directory inside the container (shown below as "/certs"), making sure
all the certificate path settings in "commissaire.conf" use the bind-
mounted directory path.

   $ sudo docker run --detach \
       --publish 8000:8000 \
       --volume /path/to/config:/etc/commissaire \
       --volume /path/to/certificates:/certs \
       commissaire
   ...

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


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", "remote_user": "root", "ssh_priv_key": "dGVzdAo="}'
   ...
