Getting Involved¶
Development Location¶
The code for commissaire lives on GitHub. The main repo can be found at https://github.com/projectatomic/commissaire.
Vagrant¶
A Vagrantfile is provided which will give you a full local development setup.
To run the vagrant development environment make sure you have a supported virtualization system, vagrant and vagrant-sshfs installed, and have all commissaire projects checked out in the parent folder as the commissaire vagrant box will attempt to mount them over SSH.
$ ls ../ | grep 'commissaire'
commissaire
commissaire-http
commissaire-service
$
To run the vagrant development environment make sure you have a support
virtualization system as well as vagrant installed and execute ./tools/vagrantup.
Warning
If you want to use the vagrant command directly note that you will have to follow the same start up process used in ./tools/vagrantup
Note
If you decide to use the vagrant command directly, the fedora-atomic host will
require a manual work-around to mount the shared folder at /home/vagrant/sync.
After the box is up the first time, run vagrant ssh fedora-atomic to log into the
virtual machine, then run sudo rpm-ostree install fuse-sshfs. Exit back out to
the host machine and restart the virtual machine with vagrant reload fedora-atomic.
Note
You will need to add an ssh pub key to /root/.ssh/authorized_keys on nodes if you will not be using cloud-init for bootstrapping.
| Server | IP | OS | AutoStart |
|---|---|---|---|
| Servers (etcd/redis) | 192.168.152.101 | Fedora Cloud 25 | Yes |
| Fedora Node | 192.168.152.110 | Fedora Cloud 25 | Yes |
| Fedora Atomic Node | 192.168.152.111 | Fedora Atomic 25 | Yes |
| Commissaire | 192.168.152.100 | Fedora Cloud 25 | No |
| Kubernetes | 192.168.152.102 | Fedora Cloud 25 | No |
For more information see the Vagrant site.
Getting Up To Speed¶
As you can see commissaire uses a number of libraries.
setuptools #license=MIT
sphinx_rtd_theme #license=BSD
python-etcd #license=MIT
requests #license=ASLv2.0
kombu #license=BSD
Of these, the most important to be up to speed on are:
- ansible: https://www.ansible.com/
Standards¶
Conventions¶
Code¶
Like most projects commissaire expects specific coding standards to be followed. pep8 is followed strictly with the exception of E402: module level import not at top of file.
Commissaire Proposal Document¶
A Commissaire Proposal Document (CPD) must be submitted and approved before significantly changing the current implementation. This applies to changes which break backward compatibility, replace a subsystem, change the user experience, etc.. For information on the CPD process see CPD-1: CPD Process and the CPD Template.
Ansible Templates¶
Variables are used with jinja2 templates and should always prefix commissaire_. Here is a current list variables in use as examples:
| Name | Description |
|---|---|
| commissaire_targets | Host(s) to target |
| commissaire_install_libselinux_python | Command to install libselinux-python |
| commissaire_install_flannel | Command to install flannel |
| commissaire_flanneld_config_local | Local flannel config file to template to the target(s) |
| commissaire_flanneld_config | Remote path to the flannel config |
| commissaire_flannel_service | Name of the flannel service |
| commissaire_install_docker | Command to install docker |
| commissaire_docker_config_local | Local docker config file to template to the target(s) |
| commissaire_docker_config | Remote path to the docker config |
| commissaire_docker_service | Name of the docker service |
| commissaire_install_kube | Command to install kubernetes minion packages |
| commissaire_kubernetes_config_local | Local kubernetes config file to template to the target(s) |
| commissaire_kubernetes_config | Remote path to the kubernetes config |
| commissaire_kubeconfig_config_local | Local kubeconfig file to template to the target(s) |
| commissaire_kubeconfig_config | Remote path to the kubeconfig |
| commissaire_kubelet_service | Name of the kubelet service |
| commissaire_kubeproxy_service | Name of the kubernetes proxy service |
| commissaire_restart_command | Host restart command |
| commissaire_upgrade_command | Host upgrade command |
| commissaire_bootstrap_ip | The IP address of the host |
| commissaire_kubernetes_api_server_url | The kubernetes api server (scheme://host:port) |
| commissaire_kubernetes_client_cert_path | Path to the kubernetes client certificate |
| commissaire_kubernetes_client_key_path | Path to the kubernetes client key |
| commissaire_kubernetes_client_cert_path_local | Path to the local kubernetes client certificate |
| commissaire_kubernetes_client_key_path_local | Path to the local kubernetes client key |
| commissaire_kubernetes_bearer_token | The bearer token used to contact kubernetes |
| commissaire_docker_registry_host | The docker registry host |
| commissaire_docker_registry_port | The docker registry port |
| commissaire_etcd_server_url | The etcd server (scheme://host:port) |
| commissaire_etcd_ca_path | Path to the etcd certificate authority |
| commissaire_etcd_client_cert_path | Path to the etcd client certificate |
| commissaire_etcd_client_key_path | Path to the etcd client key |
| commissaire_etcd_ca_path_local | Path to the local etcd certificate authority |
| commissaire_etcd_client_cert_path_local | Path to the local etcd client certificate |
| commissaire_etcd_client_key_path_local | Path to the local etcd client key |
| commissaire_flannel_key | The flannel configuration key |
Testing¶
Unit Testing¶
commissaire uses TravisCI to verify that all unit tests are passing. All unit tests must pass and coverage must be above 80% before code will be accepted. No exceptions..
To run unit tests locally and see where your code stands:
$ tox
...
End-to-End/BDD Testing¶
commissaire uses Behave to execute end to end/BDD tests. You will need to have the following in your parent directory to properly be able to execute tests locally.
$ ls ../ | grep 'comm'
commctl
commissaire
commissaire-http
commissaire-service
$
To run e2e/bdd tests locally and see where your code stands:
(virtualenv)$ behave -D start-all-servers
...
Note
you can pass -D commissaire-server-args="" to append server arguments when starting the server from behave.
or via tox
(virtualenv)$ tox -e bdd
...
You can also run the tests against any commissaire/etcd instance directly.
Warning
Do not point to a real instance of commissaire. e2e/BDD tests will simulate real usage on a running server and will probably cause damage.
See manual_installation for how to set up commissaire.
# Set up ...
(virtualenv)$ behave \
-D commissaire-server=http://127.0.0.1:8000 \
-D etcd=http://127.0.0.1:2379 \
-D bus-uri=redis://127.0.0.1:6379
...
If you are using our vagrant set up you can use the use-vagrant argument.
(virtualenv)$ ./tools/vagrantup ... (virtualenv)$ behave -D use-vagrant ...
Here are all of the user arguments supported by using the -D options:
- commissaire-server: The URI of the server to use.
- etcd: The URI of a running etcd to use.
- bus-uri: The URI of a bus service to use.
- use-vagrant: If vagrant is in use. Ignores start-* items.
- start-all-servers: Starts everything (like setting all start-* items).
- start-etcd: If etcd should be started.
- start-redis: If redis should be started. Also sets BUS_URI.
- start-storage-service: If commissaire-storage-service should start.
- start-investigator-service: If commissaire-investigator-service should start.
- start-watcher-service: If commissaire-watcher-service should start.
- start-commissaire-server: If the commissaire-server should start.
- commissaire-server-args: Any extra arguments for starting commissaire-server.
There are a number of tags within the tests. Using these tags can target
specific parts of the codebase without running the full suite. Use -t to
specify tags. -k is also helpful as it will suppress showing the tests
that did not run. Using a ~ before the tag will disable all test with that tag.
See behave --tags-help for more details
| Tag | Description |
|---|---|
| anonymous | Tests without authentication |
| clientcert | Tests that use a client certificate |
| cluster | Tests that are specific to cluster functionality |
| clusterexec | Tests that use the clusterexec code |
| create | Tests that create a resource |
| delete | Tests that delete a resource |
| deploy | Tests which use the deploy functionality |
| hosts | Tests that are specific to the hosts functionality |
| list | Tests that list a resource |
| recreate | Tests that recreate a resource |
| restart | Tests which use the restart functionality |
| retrieve | Tests the get a resource |
| slow | Tests that are known to run slow |
| ssh | Tests which use the ssh related functionality |
| status | Tests that are specific to the status functionality |
| upgrade | Tests which use the upgrade functionality |
The following command shows how to run all the create tests that are not marked slow:
# Set up ...
(virtualenv)$ behave -k -t create,~slow \
-D commissaire-server=http://127.0.0.1:8000 \
-D etcd=http://127.0.0.1:2379 \
-D bus-uri=redis://127.0.0.1:6379
...
The same thing using the ./tools/behave script:
# Set up ...
(virtualenv)$ ./tools/behave -t create,~slow
...