Welcome to Kompaas ¶

Kompaas is a python3 CLI that lets you customize and deploy helm charts. Below you will find a short How-To on getting started with kompaas, as well as documentation for the kompaas source.!

Summary

Installing ¶

The easiest way to install kompaas is through pip:

python3 -m pip install kompaas

Make sure you have the kubectl and helm2 binaries installed and configured on your system for full compatibility!

Kompaas is also provided as a docker image to easily deploy in your CI environment of choice:

docker run -it ziosting/kompaas

This image has the helm2 and kubectl binaries pre-installed for full compatibility with Kompaas’s features.

Lastly you can clone the git repo and use the Makefile in the src directory to create a local virtualenv:

make virtualenv

Quickstart Example ¶

Creating a project ¶

The following is an example of how to deploy an nginx deployment using Kompaas.

First, you need to create a Kompaas project. Let’s call it nginx:

kompaas project create nginx

Downloading a template ¶

Now, we need a chart template to be able to add a template to our nginx project. You can get one by using:

kompaas museum download http://registry.ziosting.net/chartrepo/public nginx

This will download the nginx chart from a public chart museum and place it in Kompaas’s default template directory.

To learn more about the museum command, see here

Creating a chart ¶

Then, we will need to copy that template into our nginx project, and give it a name, let’s say nginx-deployment:

kompaas chart create nginx nginx-deployment

Note

Here, the nginx parameter refers to the template called nginx in Kompaas’s default template directory. To learn more about Kompaas’s templates, see here

Checking the current context ¶

To check that everything has gone smoothly, you can use:

kompaas context

This will print out the current context of Kompaas. The context shows you which project and chart is currently active. It will display the project name in green, and the chart name in blue. You will notice that this color code is respected throughout the CLI, making it easier to recognizeobjects at a glance.

If eveything went ok, you should see your nginx project in green and nginx-deployment chart in blue.

Customizing Values ¶

Now to customize your deployment. By using:

kompaas values get

You will get a list of all values customizable in your chart. These are the same values found in the values.yaml file of your chart.

Let’s say you want a different replicaCount than the default one. We have seen that the replicaCount value is set to 1 by default. If you want to set it to 2 instead, simply use:

kompaas value update replicaCount 2

If you use kompaas value get once again, you will see that the value has successfully been updated. This is how you change the values of scalars.

For updating collections, such as sequences and mappings, there is a little nuance:

kompaas value update will add to a sequence or mapping,
meaning it will append the new value to the already existing ones.
kompaas value replace will replace the content
of a sequence or mapping by the new value.

Let’s look at an example: run kompaas value get again. You will notice a labels value. Its default content is {}, which represents an empty yaml mapping. A mapping is simply a key/value pair.

Now, run:

kompaas value update labels app:nginx

Note

The key of your new mapping will be whatever you placed before the :, here it is app. The value of your new mapping will be whatever is after the :, here it is nginx.

If you run kompaas value get you will see a new entry labels.app. This is your new mapping! You can change its value like any other scalar.

Let’s add another label. Run:

kompaas value update labels resource:server

Run kompaas value get again and you will see the new label has appered in addition to the old one.

But what if you wanted to override the old label? This is where replace comes in:

kompaas value replace labels newlabel:following

Run kompaas value get once more and you will see our other custom labels have been overriden by the new one.

Finally, if you need to completely delete a mapping, use:

kompaas value delete labels

Deploying ¶

With our chart customized, we are now ready to deploy to a kubernetes cluster. To see how to configure access to your cluster, see Configs.

If you simply need to print out kubernetes-compliant yaml files representing your project, use:

kompaas project render

If you want to deploy your project instead, use:

kompaas project deploy -n [NAMESPACE_TO_DEPLOY_IN]

That’s it! We’ve successfully deployed our customized chart using Kompaas! The next time you need Kompaas, you can try adding multiple charts to a single project!

If you need an exhaustive list of all available commands in Kompaas, check right here!

Available Commands ¶

A note on Kubernetes Configurations ¶

Kompaas allows you to deploy your charts directly from the cli. However, it is not an obligation; you can simply output your charts as kubernetes-compatible YAML files.

If you want to deploy from the command line, you will need to provide a KubeConfig file. Kompaas offers different ways of doing so:

Have a kubeconfig file in the default location ($HOME/.kube/config).
This means that if you are already using kubectl, locally, you are all set to use Kompaas.
By setting the KUBECONFIG environment variable to
a path to a kubeconfig file.
By using the KUBE_CONFIG_DATA environment variable.
Setting this variable to hold the contents of your kubeconfig file will allow the application to automatically write it to the default location. (Useful for CI environments)
By using Kompaas’s config objects. See here

Projects ¶

Projects are Kompaas’s way of organizing charts. You will be able to neatly store one or more charts in a project, and modify them without any impact to charts outside the project. You can think of them as namespaces of sorts.

To create a new project, use:

kompaas project create [PROJECT_NAME]

This will create a new project with the desired name and put you in its context.

To get a list of all your projects, use:

kompaas project get

If you need to switch between projects, use:

kompaas project use [PROJECT_NAME]

Finally, if you need to delete a project, use:

kompaas project delete

Templates ¶

Templates are nothing more than standard helm charts. For a template to be usable by Kompaas, it has to go through linting without errors.

Kompaas uses templates to differentiate between a default chart, and a customized one. A template is a default chart that will never be modified, Kompaas will only make copies of these templates.

To get a list of all the templates in the default path ($HOME/.kompaas/templates), use:

kompaas template get

To delete a template, use:

kompaas template delete [TEMPLATE_NAME]

You can use the -l argument to get templates from a different location, ex:

kompaas template get -l /home/helm/templates

Charts ¶

To create a chart, use:

kompaas chart create [TEMPLATE_NAME] [CHART_NAME]

You can also use the -l argument to choose a template outside of the default directory, ex:

kompaas chart create -l [TEMPLATE_DIRECTORY] [TEMPLATE_NAME] [CHART_NAME]

This will create a chart in your current project’s directory that is a copy of the chosen template, and put you in its context.

You can get all the charts in your current project by using:

kompaas chart get

Values ¶

To retrieve and update the values of your current chart, you can use the value sub-command. The values displayed will be the ones contained in the ‘values.yaml’ file of the current chart.

To get all values in the current chart, use:

kompaas value get

To update a value in the current chart, use:

kompaas value update [VALUE_NAME] [NEW_VALUE]

Note

If the target value is a sequence or a mapping, update will add the new value to the old value.

To update a mapping, [NEW_VALUE] must be of the form [KEY]:[VALUE]

To replace a value in the current chart, use:

kompaas value replace [VALUE_NAME] [NEW_VALUE]

Note

If the target value is a sequence or a mapping, replace will remove the old value and replace it with the new value.

To replace a mapping, [NEW_VALUE] must be of the form [KEY]:[VALUE]

To delete a value in a chart, use:

kompaas value delete [VALUE_NAME]

Docker Secrets ¶

Secrets is a synchronous tool to specify, read and delete docker registry secret access.

To get all secret in the current namespace, use:

kompaas secret get

To create a secret in the current namespace, use:

kompaas secret create [secret-name]
    --docker-username [DOCKER_USERNAME]
    --docker-password [DOCKER_PASSWORD]
    --docker-server [DOCKER_SERVER]

To delete a secret in the current namespace, use:

kompaas secret delete [secret-name]

Configs ¶

Configs are Kompaas’s way of storing multiple kubeconfig files. They will allow you to swap between different configs if you manage multiple clusters for example.

To create a new config, use:

kompaas config create [CONFIG_NAME] [PATH_TO_KUBECONFIG_FILE]

This will create a new config object and put you in its context, meaning it will be the one used to deploy your charts.

To display all current configs, use:

kompaas config get

This will produce a list of all currently available configs.

To select a different config, use:

kompaas config use [CONFIG_NAME]

You can see the user and context of a kubeconfig file by using:

kompaas config describe [CONFIG_NAME]

If you need to reset the config to its default local value, use

kompaas config default

Context ¶

If you need to display Kompaas’s current context, you can use:

kompaas context

That way you will see what Config, Project and Chart you are currently using.

Museum ¶

Kompaas allows you to download templates from chart museums directly from the cli. To do so, you can use the museum sub-command.

To list all charts in a remote chart museum, use:

kompaas museum get [MUSEUM_URL]

This will produce a list of all charts contained in that museum. If the target museum requires authentification, you can use:

kompaas museum get [MUSEUM_URL] --id [YOUR_ID] --password [YOUR_PASSWORD]

To download a template from a museum, use:

kompaas museum download [MUSEUM_URL] [CHART_NAME]

This will attempt to download the target chart and place it in the default templates directory.

Note

If you pass all as the [CHART_NAME] Kompaas will attempt to download all charts from the museum

Rendering and Deploying a Project ¶

Once you are happy with the customizations you have made to your charts, and are ready to deploy your project, use:

kompaas project deploy

This will render the current project’s helm charts using the customized values, and deploy the resulting YAML files to the kubernetes cluster defined in your current Kompaas config.

Possible arguments are:

-n, --namespace : Will let you chose the destination namespace.
--dryrunWill render the YAML files and go through the kubernetes
validation without deploying, useful for testing before deploying.

If you only wish to render the project, you can use:

kompaas project render

This will render the current project’s charts and output the result to stdout.

Source Code Documentation ¶