Boosting up your Rancher and build infrastructure as code with cattlectl

I don’t.

Don’t expect others to do what you are not willing to do on your own.

After we decided to create an automation tool for Rancher we started to look for the what and how.

The “what” was simple: Let’s have the functionality provided by kubectl but for Rancher.

Start by having the functionality of apply.

Regarding the “how” we got some help by the fact that Rancher is providing a complete API client written in go.

So we started to develop cattlectl.

The current version is 1.


0 .

It comes with a DSL to describe Rancher resources, which is currently supporting project descriptors to converge all resources needed by aRancher project.

Let’s do a simple project to verify if we really have infrastructure as code.

We are going to set up a WordPress installation using thewordpress chart from the Rancher 2 Catalog.

The installation shall have a Rancher 2 project my-wordpress-blog with a namespace my-wordbress-blog-web and of course do the wordpress app itself.

To set up our cattlectl environment we have to download the latest release of cattlectl from https://github.


And create a configuration file ~/.


yaml with the access data for our Rancher.

See https://rancher.


x/en/user-settings/api-keys/ for how to crate the API keysNow we have configured cattlectl how to talk with the Rancher API.

If we want to change the used cluster we can set the environment variable RANCHER_CLUSTER_NAME or change the value of rancher.

cluster_name in the ~/.



We are following the concept of “convention over configuration” for cattlectl which means that the command apply expects a file project.

yaml and an optional file values.

yaml in the current directory.

We could point cattlectl to other files, but we will stick to the convention for this article.


yaml is providing default values to be used for template expressions in project.


All this values have corresponding environment variables to change the values.



: wordpress.

username has the corresponding environment variable WORDPRESS_USERNAME.

Now we can create the project descriptor project.


We want to build the attributes:project name: my-wordpress-blogone namespace: my-wordpress-blog-webone app: blog-wordpressWe can use golang template expressions to use the values from values.


We will care for the ingress configuration in a second step.

For now, we want to have the mariadb and wordpress services up and running.

This is now simply done by applying our project descriptor using cattlectl apply .

We now have a new project my-wordpress-blog in our cluster.

If we open the “Catalog Apps” tab of this project we see our created app.

This app does not have any public access URL and is not a very high value for a user.

But it has already two deployments.

One is the MariaDB serving as database backend and the wordpress deployment configured to use the MariaDB.

Next step is to enable the ingress to the wordpress service reachable on a xip.

io hostname.

By default Rancher is configured to generate xip.

io conforming ingress hostnames if the ingress.


name is xip.


For our project, the generated hostname will be xip.








io where XXX.



XXX will be the IP used by Rancher to access your cluster.

To activate ingress we need to uncomment these two lines in our project.



enabled: true 'ingress.


name': xip.

ioAnd run again cattlectl apply.

As visible from the log there is no new project or namespace created but an upgrade for the app blog-wordpress performed.

If we check the “Catalog Apps” page again we’ll see an access point 80/http for our app.

If we follow that link we’ll be presented with the default landing page of our new wordpress installation.

Where to go from here?You are welcome to read our documentation on GitHub.

We already deliver cattlectl as command line tools for Linux and Mac OS but we do not check if it is also working on Windows.

For CI scenarios we do provide a docker image bitgrip/cattlectl and do use it in our own pipelines.

We plan to create a set of different usage examples with commonly used CI servers.



:JenkinsTravis CIGitLap CIWe plan to support more descriptor types and want to work on the completion to the Rancher model.



: Manage Catalogs or Clusters using descriptors.

If you have any issues or feature request to the tool or its documentation feel free to drop us a line.

.. More details

Leave a Reply