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
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.
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
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
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 the
wordpress 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.
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
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
All this values have corresponding environment variables to change the values. E.g.:
wordpress.username has the corresponding environment variable
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
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
And run again
As visible from the log there is no new project or namespace created but an upgrade for the app
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.:
- 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.