Walkthrough¶

This document walkthroughs a simple scenario with Commissaire.

Before We Start¶

Some commands sections talk about an ssh key. The clarify, the ssh key always meets these requirements:

The key is a private ssh key
A copy of the private key would be on the operators system
The key would belong to a user on the remote host (IE: it would be listed in the authorized_keys file on the remote host)
The user on the remote system would be privileged (easiest example: root)
The key is used within Commissaire to access hosts

Configuring a ContainerManager (Optional)¶

If you will be using OpenShift, OCP, or Kubernetes then configuring a ContainerManager is the first thing to do. This essentially will tell commissaire how to communicate with your ContainerManager. When a cluster is associated to this ContainerManager new hosts will be automatically added into the the ContainerManager as nodes.

Let’s say you wanted to add a ContainerManager called ocp, which has a url of https://openshift.example.com, and uses a token of aaa for authentication:

commctl container_manager create --type openshift --options='{"server_url": "https://openshift.example.com", "token": "aaa"}' ocp
...

Note

Adding Hosts To The Cluster, later in this document, will show how the ContainerManager interacts binds with Clusters and Hosts.

Creating a Cluster¶

Clusters are groupings of hosts. These hosts are expected to be similar to each other in functionality. In other words, the configurations of hosts in a cluster should not differ. While the functionality provided by the hosts may differ the system itself should not. Take OpenShift nodes as an example. Some nodes may be hosting pods running different workloads, such as database services, web applications, or a mixture. However, the underlying hosts themselves are configured to be OpenShift nodes and are configured identical to each other.

To create a brand new cluster:

Note

If you did not create a ContainerManager you can omit --container-manager.

commctl cluster create --container-manager ocp mycluster
...

Adding Hosts To The Cluster¶

Adding new hosts to Commissaire comes in two forms. Automatic registration and manual additions.

Automatic Registration¶

First, you must create the user-data file. commctl provides a command, named user-data, which helps generate this file for you. Here is an example:

$ commctl user-data \
  --password \
  --username USER \
  --cluster CLUSTER \
  --endpoint https://example.com/ \
  CLUSTER.userdata
Password: <PASS>
$ # Let's check that the userdata file is indeed a multipart/mixed file
$ file CLUSTER.userdata
CLUSTER.userdata: multipart/mixed; boundary="===============8094544984785845936==, ASCII text

Now provide the new user-data file when provisioning new hosts in your cloud provider. When the new host starts it will automatically register into Commissaire.

Manual Registration¶

You can also add hosts into Commissaire in a manual fashion. To do this you will need:

The host to have sshd running
The host to have sshd port open.
The private key to an administrative user on the host (EG: root)

Note

Jump to Creating Keys if you want to create a new key

Let’s say you have a host called 192.168.152.110 which you’d like to add to the cluster my_cluster. You also have a private key of the remote root user for 192.168.152.110 at /path/to/remote/hosts/priv/ssh_key. The following command would add the host to the cluster:

Note

Remember, the ssh key references the operators copy of the key used when accessing the new host

$ commctl host create --cluster my_cluster 192.168.152.110 /path/to/remote/hosts/priv/ssh_key
...

Operations¶

Now that you have at least one host registered in a cluster you can now do operations. Let’s do a restart. The following command will start the restart process.

commctl cluster restart start my_cluster
...

Now let’s see what the status of the process is:

For more operations via commctl see commctl

Optional Steps¶

The following are optional items which may prove useful for some users.

Creating Keys¶

If you want to create a new key pair for the remote host you can do the following:

This creates a new ssh public and private key as ``new_key.pub`` and ``new_key``.

.. code-block:: shell

   $ ssh-keygen -f new_key -C root
   Generating public/private rsa key pair.
   Enter passphrase (empty for no passphrase): 
   Enter same passphrase again: 
   Your identification has been saved in new_key.
   Your public key has been saved in new_key.pub.
   The key fingerprint is:
   SHA256:YoFOXojY0tIkAQBRiPe00HWQdJ8zgOylJwDuQXXJfXc steve@bitfall
   The key's randomart image is:
   +---[RSA 2048]----+
   |O%oo=.=*Bo.      |
   |*.*+ Bo+*= . E   |
   |oo .o Eo=.. .    |
   |+.  + o .        |
   |...   o+S        |
   |oo oo  .    ..   |
   |+ . +            |
   | ..              |
   |                 |
   +----[SHA256]-----+

You could then use your cloud provider to inject the key into the host.