Boosting up your Rancher and build infrastructure as code with cattlectl

Rancher is great in managing all your Kubernetes clusters. With cattlectl you now have the power to manage your Rancher projects as code.

When I first came along Rancher I asked a friend if he had any experience using it. His answer was surprising at first:

“Rancher is great for creating and managing Kubernetes clusters but I have no clue how to automate it.”

Actually, we were looking for a platform to manage all the Kubernetes clusters for the different environments of our customer. So Rancher was a natural fit and we started to find a way to automate it.

A journey to automation

Reading the documentation we came across the rancher cli which is shipped with Rancher. That sounds like a good way to automate our projects.

Using rancher at the command line enables you to do direct CRUD on projects, namespaces, apps, … It also enables you to query for running workload on your projects.

But …

Far from enabling us to manage all the required Rancher resources. There are no storage classes, no docker credentials, no … Also the commands on the rancher command line are not idempotent which forces you to do that in your automation scripts.

Please don’t get me wrong. The rancher command line is very helpful for simple adjustments and task which are not repeated. It’s just not targeting any automation.

Other possibilities …

Rancher comes with a powerful REST API which enables you to do everything you can do in the UI by setting up curl scripts or creating Postman collections. 
Do you know any developer happy with such an automation? 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.0 .
It comes with a DSL to describe Rancher resources, which is currently supporting project descriptors to converge all resources needed by a
Rancher 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.com/bitgrip/cattlectl/releases. And create a configuration file ~/.cattlectl.yaml with the access data for our Rancher.

See https://rancher.com/docs/rancher/v2.x/en/user-settings/api-keys/ for how to crate the API keys

Now 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 ~/.cattlectl.yaml.

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.

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

All this values have corresponding environment variables to change the values. E.g.: wordpress.username has the corresponding environment variable WORDPRESS_USERNAME.

Now we can create the project descriptor project.yaml. We want to build the attributes:

  • project name: my-wordpress-blog
  • one namespace: my-wordpress-blog-web
  • one app: blog-wordpress

We can use golang template expressions to use the values from values.yaml.

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.host[*].name is xip.io. For our project, the generated hostname will be xip.io-blog-wordpress.my-wordpress-blog-web.XXX.XXX.XXX.XXX.xip.io where XXX.XXX.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.yaml.

    ingress.enabled: true
'ingress.hosts[0].name': xip.io

And 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. E.g.:

  • Jenkins
  • Travis CI
  • GitLap CI

We plan to support more descriptor types and want to work on the completion to the Rancher model. E.g.: 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.