
Operations
**********


Preface
=======

All operations via commissaire are done via REST. While any HTTP
client can be used this document will show examples using *commctl* as
well as *curl*.

Note: **commctl** can be found in the commctl python package


commctl
-------

commctl requires a configuration file. The default path is
"~/.commissaire.json" though it can be changed with the "--
config"/"-c" option.

   {
       "username": "a",
       "endpoint": "http://127.0.0.1:8000"
   }

The password may be stored in the configuration file as well.

Warning: The configuration file is plain text. If you choose to keep
  a password in the file make sure to keep the file permissions locked
  down.

   {
       "username": "a",
       "password": "a",
       "endpoint": "http://127.0.0.1:8000"
   }

Multiple endpoints may be specified. If the first endpoint is
unreachable the next endpoint in the list is used.

   {
       "username": "a",
       "endpoint": [
           "http://127.0.0.1:8000",
           "http://192.168.122.100:8000",
           "http://10.1.1.1:8000"]
   }


curl
----

Every call requires a username and password to be passed via HTTP
Basic Auth. With curl this looks like:

   curl ... -u "USERNAME:PASSWORD" ...

The proper headers must also be passed. Since all of the REST
communication is done via JSON the content-type must be set to
application/json.

   curl ... -H "Content-Type: application/json" ...

Lastly, the type of operation must be specified. For example, *PUT*
must be used when creating while *GET* must be used for retrieving.

   curl ... -XPUT ...


Bootstrapping
=============

Bootstrapping happens when a new host is added to commissaire via the
Host endpoint.

   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="}'
   ...

It's important to remember *ssh_priv_key* must be base64 encoded
without newlines. On many systems this can be done via that **base64**
command and using the **-w0** switch.

   $ cat path/to/key | base64 -w0 > encoded_key

For specifics on the endpoint see Host

Note: commissaire can help automate the bootstrapping of new hosts
  using cloud-init for early initialization.  See Cloud-Init
  Integration.


Cluster Operations with commctl
===============================

These operations are done across all hosts associated with a cluster.


List
----

To list all clusters:

   commctl list clusters
   ...

To list all hosts:

   commctl list hosts
   ...

To list all hosts in a specific cluster:

   commctl list hosts -n datacenter1
   ...


Restart
-------

To restart a cluster:

   commctl create restart datacenter1
   ...

To check up on a restart:

   commctl get restart datacenter1
   ...


Upgrade
-------

To upgrade a cluster:

   commctl create upgrade datacenter1 -u 7.2.2
   ...

To check up on an upgrade:

   commctl get upgrade datacenter1
   ...


Cluster Operations with curl
============================

These operations are done across all hosts associated with a cluster.


Restart
-------

Restarting a cluster is done by creating a new restart record for a
specific cluster.

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

To check up on a restart a REST *GET* call on the same endpoint will
show the current status.

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

For specifics on the endpoint see Cluster Operations: Restart


Upgrade
-------

Upgrading a cluster is done by creating a new upgrade record for a
specific cluster.

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

To check up on an upgrade a REST *GET* call on the same endpoint will
show the current status.

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

For specifics on the endpoint see Cluster Operations: Upgrade
