commctl¶

Preface¶

commctl is the official command line utility for Commissaire. commctl acts as a clean user interface between the operator and the commissaire-server allowing for a more traditional experience for operators.

Installation¶

Via Source¶

$ pip install git+https://github.com/projectatomic/commctl.git
...

Via Docker¶

From a checkout of the commctl repository:

$ sudo docker build -t commctl .  # Done once to build the image
...
$ sudo docker run -t -i --volume=`pwd`/.commissaire.json:/root/.commissaire.json:Z commctl --help

Via RPM¶

If you want to roll your own RPM, the spec file can be found in the Fedora package repo.

On RHEL/CentOS/Fedora based systems you will also need to make sure to have an RPM build environment set up. This includes packages such as:

rpm-build
redhat-rpm-config

For further dependencies please see BuildRequires in the spec file.

Configuration¶

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"
}

Note

At least one endpoint must be defined!

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"
}

If you are using the Kubernetes authentication plugin you can opt to reuse the credentials from your kubeconfig like so:

Note

If you include username/password and kubeconfig items the username/password will be ignored in favor of the kubeconfig.

Multiple fallback endpoints may be specified as a list. The endpoints are tried in order until a successful connection is made.

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

Commands¶

cluster¶

Note

For API versions of these commands see the Cluster API

create¶

create will create a new cluster. It takes in two flags:

-t/--type: Type of the cluster (Default: kubernetes)
-n/--network: Name of the network (Default: default)

create requires one positional argument:

name: The name to give the cluster

$ commctl cluster create --type kubernetes --network default my_cluster

delete¶

delete will delete a cluster from the server.

delete requires one positional argument:

name: The name of the cluster to delete

$ commctl cluster delete my_cluster

get¶

get will retrieve a cluster from the server.

get requires one positional argument:

name: The name of the cluster to retrieve

$ commctl cluster get my_cluster

list¶

list will provide a list of all configured clusters.

To list all clusters:

commctl cluster list
...

deploy start¶

deploy start will create a new deployment on an Atomic Host. This is an asynchronous action. See deploy status on checking the results.

deploy start requires two positional arguments:

name: The name of the cluster to deploy upon
version: The version with which to upgrade

$ commctl cluster deploy start mycluster 7.4.1

deploy status¶

deploy status will retrieve the status of an deploy

deploy status requires one positional argument:

name: The name of the cluster to check

$ commctl cluster deploy status mycluster

restart start¶

restart start will create a new restart roll on a cluster of hosts. This is an asynchronous action. See restart status on checking the results.

restart start requires one positional argument:

name: The name of the cluster to restart

commctl cluster restart start my_cluster
...

restart status¶

restart status will retrieve the status of an restart

restart status requires one positional argument:

name: The name of the cluster to check

commctl cluster restart status my_cluster
...

upgrade start¶

upgrade start will create a new upgrade on a cluster of hosts. This is an asynchronous action. See upgrade status on checking the results.

upgrade start requires one positional argument:

name: The name of the cluster to upgrade

commctl cluster upgrade start datacenter1 7.2.2
...

upgrade status¶

upgrade status will retrieve the status of an upgrade

upgrade status requires one positional argument:

name: The name of the cluster to check

commctl cluster upgrade status datacenter1
...

host¶

Note

For API versions of these commands see the Host API

create¶

create will create a new host record. It takes in one flag:

-c/--cluster: Adds the host to the specified cluster

create requires two positional arguments:

address: The domain or address of the host to access and add
ssh_priv_key: The full path to the remote hosts ssh private key for initial access

.. code-block:: shell

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

Note

When creating a new host record the remote host will need to have an ssh key already generated and available for commissaire. The host also will need to have ssh running and the python command must be available. If you want to bootstrap new hosts please see our Cloud-Init Integration documentation.

delete¶

delete will delete a host from the server.

delete requires one positional argument:

name: The name of the host to delete

$ commctl host delete 192.168.152.110

get¶

get retrieves a host record from the server.

get requires one positional argument:

address: The address or domain of the host to retrieve

$ commctl host get 192.168.152.110

list¶

list will provide a list of all configured hosts.

To list all hosts:

commctl host list
...

status¶

status retrieves status information for a specific host.

status requires one positional argument:

address: The address or domain of the host to retrieve status

$ commctl host status 192.168.152.110

ssh¶

Note

For the api used for this commands see the Host Creds API

commctl provides a simple way to connect to your host node by pulling down the ssh_priv_key and remote_user from the server. The ssh_priv_key is stored temporarily and is removed upon the completion of the connection.

ssh requires one positional argument:

hostname: The address or domain of th

ssh allows for N optional positional argument:

extra_args: Extra arguments to pass to the ssh command

To connect to a host node:

commctl host ssh 192.168.1.100
...

To connect to a host node with extra ssh parameters:

commctl host ssh 192.168.1.100 -v -p 9876
...

network¶

Note

For API versions of these commands see the Network API

create¶

create will create a new network record. It takes in two flags:

-t/--type: The type of the network: (Default: flannel_etcd)
-o/--options: Additional options for the network (Default: “{}”)

create requires one positional argument:

name: The name to give the network

$ commctl network create --type flannel_server --options '{"address": "192.168.152.100:8080"}' my_network

delete¶

delete will delete a network from the server.

delete requires one positional argument:

name: The name of the network to delete

$ commctl network delete my_network

get¶

get will retrieve a network from the server.

get requires one positional argument:

name: The name of the network to retrieve

$ commctl network get my_network

list¶

list will provide a list of all configured networks.

To list all hosts in a specific cluster:

commctl host list datacenter1
...

passhash¶

The passhash command provides an easy way to create bcrypt2 hashes.

The quickest way to use the command is to provide no flags. This will prompt you for the password and output the hash.

$ commctl passhash
Password:
$2a$12$tMz3FVwwwkXoXcTvCHdNnul1wC.sBX1KyRYEB.FZ42VCPZVc5.SyW

If you have a password in a file you can use the --file/-f switch to use it as the password.

$ commctl passhash --file my_password.txt
$2a$12$K5KtQ6woCJW5Y9gSC9W25eRu1rMWIT5WyLsLtauoZyB2bZQ8yjc1C

If you would like to change the strength of the hash via it’s rounds you can use --rounds/-r.

$ commctl passhash --rounds 15
Password:
$2a$15$mTKz3Hl08AcJsK79YGk9G.RHe1P9ksr/whLyxZGsh92bvJt83mb8q

If you want to pass the password directly in the command you can use --password

Warning

Generally this is a bad idea as the password may be kept in shell history and will be viewable by anyone else with access to the terminal.

$ commctl passhash --password bad_idea
$2a$12$BJZYMKFEvG1osE5YXBxwIOMEHCpvHu8IlSnVpE6L0JbuhNCa.Lj.C