Tutorial: Writing your First Commodore Component

The Lieutenant Operator and its API are the major elements of a Project Syn installation. They provide a complete catalog of information about all of your clusters, and allow developers to operate on those clusters through a unique API.

In this tutorial we are going to install Lieutenant in the same Minikube cluster that we will use later on; this is usually not the case, and Lieutenant and its API are usually installed separately. Doing so will, however, simplify our setup greatly.

First you need to set a few environment variables:

To install Lieutenant Operator and API on Minikube, we are going to execute the ./1_lieutenant_on_minikube.sh script. This script mimicks the steps explained in the "Getting Started" tutorial, so we will not go through them here. The script is quite self-explanatory, though:

This script will launch a new Minikube instance, will apply all the required kubectl commands, and wait for the cluster to be in the expected state before continuing.

It will also expose the Lieutenant API using the ngrok reverse proxy tool. You do not need a commercial (paying) ngrok account to use it; just download the version corresponding to your system and install it somewhere in your PATH.

Once the script has run, you will find two new private repositories in your GitLab account: one named tutorial-cluster-minikube and another named tutorial-tenant. Project Syn tools use these repositories to perform "GitOps" operations on all the clusters.

The second step in this tutorial is to bootstrap Commodore in our Minikube cluster. For that we can just run the ./2_commodore_on_minikube.sh script. This script requires an environment variable to run: COMMODORE_SSH_PRIVATE_KEY which should contain the path to your personal SSH public key. For example:

Do not press the Enter key when prompted with the If you don’t see a command prompt, try pressing enter message! Instead, type the passphrase of your SSH key.

Now that Lieutenant is installed we can install Steward on our cluster. This tool is in charge of bootstrapping Argo CD which watches the GitLab and GitHub repositories, and triggers the GitOps operations required to keep each cluster up-to-date.

We can easily install Steward on Minikube using the ./3_steward_on_minikube.sh script.

Now it is time to spin our second cluster, this time using K3s, itself managed using K3d. Again, a couple of scripts will make our life easier.

First we need to get some variables from our environment:

Now we can run a script that will not only spin a new k3s cluster, but will also install Steward and register it as a cluster belonging to our tenant. That is, we will "synthesize" our cluster.

And now we are ready: we have two working Kubernetes clusters, one Minikube and one k3s, and both are assigned to the same tenant. To verify this, we ask now the Lieutenant Custom Resources, available in our Minikube cluster:

Of course, in your case the NAME column will show different, random values. But we can see both clusters and the tenant object, all happily residing inside the realm of our Project Syn installation.

For more information, check out the diagram in the Project Syn website.

This is an optional step! If you feel adventurous enough, and still have enough available RAM in your system, install kind or Microk8s and run the ./4_synthesize_on_kind.sh or ./4_synthesize_on_microk8s.sh scripts, to spin up yet another cluster (or two!) to be added to your current tenant.

We are going to use now the commodore tool to generate and compile our new component. This tool is written in Python and requires quite a few dependencies; to make our lives easier, we are instead going to use the corresponding container image available in Docker Hub. This is why it is strongly recommended that you define the following function in your environment, which will make using commodore a much simpler task. See Running Commodore.

In order to create a new component, we need to clone the official Commodore project from GitHub first. Inside of that clone of the Commodore source code we will create a few folders:

We also need to define the contents of the .env file, used by Docker to set environment variables required by the commodore command. We can do this in a snap with this command, which should display an output similar to this one:

The first step to create a Commodore Component is what is usually referred to as "compiling the catalog." This catalog provides a unique reference point of information about all the configuration and workloads affecting a single cluster.

Now we are ready to compile our catalog. Every time you call the commodore tool you will have to enter the password of your SSH key.

We must repeat this operation for each cluster, and of course, you should use the cluster IDs you got from the last kubectl command above.

With our catalog ready to use, we can create a new component. In this case, we want to create a component that automatically deploys a very simple application called the "Fortune Cookie Service" to our clusters. This application, written in Python, returns a funny "fortune cookie" message in the console.

Let us create the component first:

The new component is located now in the dependencies/fortune folder. We can edit it using Visual Studio Code:

Commodore Components are usually written using Jsonnet (pronounced "jay-sonnet"), a data templating language for app and tool developers. If you have never written Jsonnet before, do not worry; just know that all valid JSON files are valid Jsonnet files, and that Jsonnet provides useful extensions, such as variables and functions, and various export formats, which make it easy to write very complex JSON applications with it.

In Visual Studio Code, open the component/main.jsonnet file, and replace its text with the following:

This Jsonnet file provides the definition of a complete Kubernetes deployment. However, instead of being specified in YAML, this file specifies it in Jsonnet format. After the import statements we define a few variables. The entries that follow define various Kubernetes objects: a deployment, a service, and a namespace to hold everything together.

The vscode-jsonnet extension for Visual Studio Code has a nifty "live preview" feature; the picture below shows how Jsonnet outputs the classic "YAML" format that any Kubernetes cluster might expect.

Now that we have written our component, let’s compile it to see if it’s generating what we need:

Our component compiles! Let us create a new project in GitHub to push our code into:

Now that we have a component that compiles, and that we have pushed it to GitHub, we want to deploy it to our clusters.

We need to edit two files for that:

The global folder is a clone of the fork of the commodore-defaults project.

Edit commodore.yml and add this at the end:

Commit and push your changes, and cd to another folder:

This repository is a clone of the tutorial-tenant project in your GitLab account.

Edit /common.yml and add this text:

And once again, commit and push your changes.

Since we edited the common.yml file, the changes will propagate to all clusters. If you want your changes to apply to just one cluster, edit the corresponding file in the same folder.

We’re ready! Now we just have to recompile both catalogs and push the changes. For that we need to recompile the catalogs, but this time using the --push parameter, so that our changes are sent to their respective GitLab repositories.

We have to do this for all clusters!

Since Argo CD, itself managed by Steward, is watching these repositories, it will pick up the new state and seamlessly deploy it across our two clusters in a few minutes.

With K9s we can watch our clusters as they pick up the changes and apply them in all transparency. The namespace syn-fortune will contain the required deployment, pods, and service.

Argo CD is a declarative GitOps continuous deployment tool for Kubernetes. It is managed by Steward, and takes care of synchronizing and automatically updating the state of our clusters following changes in the configuration. You can access the Argo CD console in both clusters through these steps:

First, retrieve the Argo CD admin password with this command:

Second, redirect traffic to Argo CD:

And third, open localhost:8080 with the username admin and the password you copied in the previous step.

You can repeat this steps to access the console in the K3s cluster, by changing the value of the kubectl --context parameter.

Of course you can test the fortune-service running in your clusters using the following commands:

For k3d:

For Minikube:

We are done! You can now remove the clusters in your computer, and also remove the projects you’ve created in GitHub and GitLab:

The GitLab projects tutorial-tenant, tutorial-cluster-minikube, and tutorial-cluster-k3s have been automatically deleted by the Lieutenant Operator.