If you use Rancher 1.6, you probably already know about Rancher Catalog, which lets your Rancher system users create and share application templates without the need for any technical knowledge about the applications.
In this tutorial, you’ll learn how to:
Create productive and reproducible private catalog templates
Provide templates in a self-service portal
Share services between distinct development teams
Manage versions and updates of your services
Offer your private templates to all Rancher users and customers
You can configure Rancher Catalog with different catalog repositories (repos) to get distinct templates. A catalog repo is just a Git repo with a specific structure.
By default, Rancher Catalog includes templates for two public catalog repos:
Rancher Certified Library — This repo provides templates for core and infrastructure services. It’s maintained and certified by Rancher Labs.
Community Catalog — This repo provides templates for any application. Templates are created and maintained by the Rancher Community, not certified by Rancher Labs.
Rancher enables these catalogs by default, but the admin can disable them on the Admin > Settings page.
One of the coolest features inside Rancher Catalog is the ability to generate and add your own catalog repos to your Rancher system.
Why use private repos?
This feature is especially useful when you want to:
Make your own developed services deployment productive and repeatable
Publish your own developed services for your users to consume
Manage the life cycle and control the updates of your deployed services
Share released services between distinct development teams
Kinds of Catalog Repos
There are two different kinds of Rancher Catalog repos:
Global — This kind of catalog repo is available to all Rancher environments. To manage global catalogs, go to the Admin > Settings page.
Environment — This kind is available only to the current Rancher environment. To manage environment catalogs, click Catalog > Manage.
Creating a Private Catalog Repo
As a basic example, let’s suppose you already have your docker-compose and rancher-compose files. For example:
Create a basic directory structure that consists of different folders for each package type:
templates — A folder for adding Cattle template packages
swarm-templates — A folder for adding Swarm template packages
mesos-templates — A folder for adding Mesos template packages
machine-templates — A folder for adding machine-driver template packages
infra-templates — A folder for adding infrastructure services template packages
README.md — A file for describing your catalog repo
Create a package structure inside each folder type:
Create a folder with the package name, such as myservice, where you’ll save files.
Create a config.yml file to describe the package:
name: # The name of the Catalog entry
# A description of the Catalog entry
version: #The default version of the package to use (must match any folder in the rancher-compose version)
category: # The category to use when searching for Catalog entries
maintainer: # The maintainer of the Catalog entry
license: # The license
projectURL: # The URL related to the Catalog entry
To display an icon for the Catalog entry, create an image file prefixed with “catalogIcon-,” such as catalogIcon-myservice.svg. The preferred image format is SVG, but PNG and JPG are allowed.
Create a folder for every package version. The package name has to be a number. Use “0” for the first version, “1” for the second version, and so on. Inside every version folder, you need to add these files:
docker-compose.yml — Set your questions variable values, if needed.
Add, commit, and push your files into your Git repo.
To update to a new package version, create a folder with the next version number inside your catalog folder, and then add new docker-compose and rancher-compose files.
Congrats! You created your first private catalog.
Using Your Private Catalog Repo
Once you’ve created your first catalog repo, you can use or share it.
To use it, just add your < GIT_REPO > URL and < GIT_BRANCH > to your Rancher system as a catalog kind:
Global — For global catalogs, enter the URL and branch on the Admin > Settings page.
Environment — For environment catalogs, enter the URL and branch by clicking Catalog > Manage.
Rancher Server clones the Git repo automatically, and you can access your catalog repo packages from the Catalog > < NAME > menu.
This blog entry taught you how to create a private catalog repo to provide templates for your users or customers. For more information, see our Catalog docs. You can also read our best practices for Catalog packages on GitHub.
About the Author
Raul Sanchez Liebana is a DevOps Lead at Rancher Labs.
Join us for free online training courses, hosted monthly by a Rancher technical expert. We provide a great hands-on overview for new users setting up a Rancher deployment, and answer any and all questions you have about Rancher and how to integrate it into your DevOps processes!