Rancher: Part 3 - Private Catalogs

Welcome to part 3 of a multi-part series where I will walk through the setup and configuration of Rancher.

In the previous posts, I walked through the installation of Rancher, deploying the server and 3 hosts that can run dockerized workloads. I then deployed a Jenkins Stack and a Load Balancer from the default catalogs.

In this post I will show you how to create a private catalog and modify the Load Balancer Stack to account for a new service.

Private Catalogs

Rancher has the ability add user defined catalogs to the system. These are implemented as git repositories and contain all of the metadata necessary to define and instantiate any number of services.

As an example, I decided to create a catalog which offered a Tiny Tiny RSS service. I currently run ttrss on one of my servers so this would be a good test.

Creating the Catalog

The documentation from Rancher Labs is very good and details the steps very well but I always find a real world example to be much better so here's a link to my catalog. The structure is pretty simple: Under the 'templates' directory, there is a directory per service (for example, I created a 'templates/ttrss' directory). Within that service directory, you place all of the metadata that is needed by Rancher.

  • In the root of the templates/ttrss directory I placed two files: the config.yml which is a bit of metadata that appears in the main Rancher catalog UI, and a svg image that I want Rancher to display.
  • I also created a directory named '0' as I was just creating the first version of my service. As I upgrade the service, I can create additional directories (called '1', '2', etc). Rancher will then deploy the latest version by default warn the users if there is a new version that they should upgrade to. Within that '0' directory, I placed three files:
    • rancher-compose.yml: This file is what drives the Rancher UI/CLI to display some information about my service and prompt the user for any configuration settings. In my case, I wanted to prompt the user for some database credentials.
    • docker-compose.yml: This is a file that can be processed by docker-compose, but has been extended so that the values retrieved fromt he user via the rancher-compose mechanism can be substituted in.
    • README.md: A markdown file that Rancher will display in the UI. This is very handy to display release notes, default credential information, and anything else.

Take a look at my catalog and it should be self explanatory

Adding the Catalog to Rancher

In order to add a Catalog to Rancher, you'll need three bits of information:

  • A name. This can be anything you want.
  • The git URL. This is the URL that you would use with git clone. I used a public repository to make it really simple.
  • The branch name. Most times I would imagine people use 'master'

Go to the "Admin"->"Settings" page and add your catalog.

Add a Catalog

The entries should show up almost immediately after you go to the "Catalog" section of the UI

View a Catalog

Deploying from a Private Catalog

Deploying a service from a Private Catalog is EXACTLY like using one of the default catalogs. Simply click on the service you want to deploy, fill out the form and press "Launch". In the screenshot below, you can see how the different files in the catalog provide information for the user. Deploy ttrss

After deploying, it should show up in the list of User Stacks Deployed ttrss

Next Up...

Monitoring Rancher