Building Rancher Docker Container Catalog Templates from Scratch : Part 1

Rancher ships with a number of reusable, pre-built application stack templates. Extending these templates or creating and sharing completely new ones are great ways to participate in the Rancher user community and to help your organization effectively leverage container-based technologies. Although the Rancher documentation is fairly exhaustive, so far documentation on how to get started as a new Catalog template author has consisted of only a single high-level blog post. This article is the first in a series aimed at helping the new Catalog template author ramp-up quickly, with the best available tooling and techniques. For the first article in this series, we are going to construct a very simple (and not terribly useful) Cattle Catalog template. In an upcoming article, we will flesh out this template with more detail until we have a working multi-container NGINX-based static website utilizing all of the basics of Rancher Compose, Docker Compose, and Rancher Cattle.

[Overview and Terminology]

Before we dive into creating a new Rancher Catalog template, let’s first get some common terminology out of the way. If you are an experienced Rancher user, you may be able to scan through this section. If you are new to the world of Linux containers, cluster managers, and container orchestration, now is a good time to do some Googling. For our purposes, Rancher is Open Source software enabling deployment and lifecycle management of container-based application stacks, using most of the commonly available Open Source container orchestration frameworks. As of this writing, Rancher has excellent support for Docker containers and the following orchestration frameworks:

• Kubernetes (1, 2)
• Mesos (1, 2)
• Docker Swarm (1, 2)
• Rancher’s own Docker Compose-based Cattle

If your favorite framework isn’t listed rest assured, that support is probably on the way. Within the context of each of the previously mentioned orchestration frameworks, Rancher includes a catalog of pre-built and reusable application templates. These templates may be composed of a single container image, but many times they stitch together multiple images. Templates can be fed environment-specific configuration parameters and instantiated into running application stacks via the Rancher admin console. The screenshot below shows several applications stacks as viewed via the Rancher admin console. Note that the Wordpress and Prometheus stacks are expanded to show the multiple containers comprising each stack. In this article, we are going to focus on Rancher’s own Cattle orchestrator. See the image below for examples of some of the many pre-built Catalog templates which ship for Cattle.

###

Creating your first Rancher Cattle Catalog template

Many times these pre-built Rancher Catalog templates can be used as shipped, but sometimes you’ll need to modify a template (and please then submit your pull request to the upstream!), or even create a new template from scratch when your desired application stack does not already have one.

Doing it manually

For the purposes of this exercise, I’ll assume you have:

(1) a container host running the rancher/server container (2) at least one compute node running rancher/agent (for the purposes of the demo, (1) and (2) can be the same host) (3) a configured Rancher Cattle environment (available by default with a running rancher/server instance)

If that is not the case, please check out the one of the Rancher Overview videos on the Rancher Labs YouTube channel.

Adding a custom Cattle Catalog template

By default, the Catalog templates listed in the Rancher admin console are sourced from the Rancher Community Catalog repository. We’ll create our own git repo as a source for our new ‘demo app’ Cattle Catalog template. First, we’ll set up our working directory on our local workstation: Although there’s no deep magic, let’s step through the above:

1. Create a project working directory named ‘rancher-cattle-demo’ under ~/workspace. These names and paths are fairly arbitrary though you may find it useful to name the working directory and git repo according to the following convention: rancher-<orchestration framework>-<app name>.
2. Create the git repo locally with ‘git init’ and on GitHub via the ‘hub’ utility.
3. Populate the repo with a minimal set of files necessary for a Rancher Cattle Catalog template. We’ll cover this in detail in a second.

Now let’s do our initial commit and ‘git push’ of the demo template: For sanity’s sake, you might want to check that your push to GitHub was successful. Here’s my account after the above push: It’s worth noting that in the above screenshot I’m using the Octotree Chrome extension to get a full filesystem view of the repo. Now let’s configure Rancher to pull in our new Catalog template. This is done via the Rancher admin console under Admin/Settings: Click the \“+\” next to \“Add Catalog\” near the middle of the page. Text boxes will appear where you can enter a name and URI for the new Catalog repo. In this case, I’ve chosen the name ‘demo app’ for our new Catalog repo. Note the other custom Catalog settings from previous custom work. Now we can go to Catalog/demo app in the Rancher admin console and pull see the listing of container templates. In this case, just our ‘demo app’ template. But wait there’s something wrong... We’ve successfully created the scaffolding for a Rancher Cattle template, but we’ve not populated any of the metadata for our template, nor the definition or configuration of our container-based app. The definition of our application via docker-compose.yml and rancher-compose.yml is worthy or its own blog post (or two!), but for now we’ll focus on just basic metadata for the template. In other words, we’ll look at just the contents of config.yml

Minimal config.yml

The Rancher documentation contains detailed information about config.yml. We’re going to do just enough to get things working, but a thorough read of the docs is highly recommended.

config.yml

The config.yml file is the primary source of metadata associated with the template. Let’s look at a minimal example:

---
name: Demo App
description: >
  A Demo App which does almost nothing of any practical value.
version: 0.0.1-rancher1
category: Toy Apps
maintainer: Nathan Valentine <nathan@rancher.com|nrvale0@gmail.com>
license: Apache2
projectURL: https://github.com/nrvale0/rancher-cattle-demo

In case it wasn’t evident from the filename, the metadata is specified as YAML. Given the above YAML and the Icon file present in this git commit, let’s look at the new state of our template: That’s starting to look a lot better, but our Catalog template still doesn’t do anything useful. In our next post in this series, we’ll cover how to define our application stack (Hint: it involves populating the docker-compose.yml and rancher-compose.yml files.)

A better way to create templates

Before we move on to definition of our application, I need to tell you a secret... When creating new Catalog templates manually doesn’t require any deep magic, it’s easy to make a small and silly mistake which results in an error. It would be excellent to have tooling that allowed us to create new Catalog templates in a fast, repeatable, low-probability-of-error way...and in fact there is. The Rancher community has submitted a Rancher Catalog Template ‘generator’ to The Yeoman Project. Assuming you have a working Node.js environment, generating a new Cattle Catalog Template with default scaffolding is as simple as the process shown below: