Using Private Catalogs in Rancher

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

Catalog Repositories

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.

Private Repos

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:

• docker-compose.yml

  version: '2'
  services:
    test:
      image: rawmind/web-test
      tty: true
      labels:
        io.rancher.container.hostname_override: container_name
        io.rancher.scheduler.affinity:container_label_ne: io.rancher.stack_service.name=$${stack_name}/$${service_name}
    lb:
      image: rancher/lb-service-haproxy:v0.7.6
      ports:
      - 8080:8080/tcp
      labels:
        io.rancher.container.agent.role: environmentAdmin
        io.rancher.container.create_agent: 'true'

• rancher-compose.yml

  version: '2'
  services:
    test:
      scale: 2
      retain_ip: true
      start_on_create: true
      health_check:
        healthy_threshold: 2
        response_timeout: 2000
        port: 8080
        unhealthy_threshold: 3
        initializing_timeout: 60000
        interval: 2000
        strategy: recreate
        request_line: GET "/" "HTTP/1.0"
    lb:
      scale: 1
      start_on_create: true
      lb_config:
        certs: []
        port_rules:
        - hostname: ''
          priority: 1
          protocol: http
          service: test
          source_port: 8080
          target_port: 8080
      health_check:
        healthy_threshold: 2
        response_timeout: 2000
        port: 42
        unhealthy_threshold: 3
        initializing_timeout: 60000
        interval: 2000
        reinitializing_timeout: 60000

To Create a Private Catalog Repo

1. Initialize an empty Git repo.
2. 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

3. Create a package structure inside each folder type:

   1. Create a folder with the package name, such as myservice,
      where you’ll save files.

   2. Create a config.yml file to describe the package:

      name: # The name of the Catalog entry
      description: |
        # 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

   3. 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.

   4. 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.

        version: '2'
        services:
          test:
            image: rawmind/web-test
            tty: true
            labels:
              io.rancher.container.hostname_override: container_name
              io.rancher.scheduler.affinity:container_label_ne: io.rancher.stack_service.name=$${stack_name}/$${service_name}
          lb:
            image: rancher/lb-service-haproxy:v0.7.6
            ports:
            - ${PUBLISH_PORT}:${PUBLISH_PORT}/tcp
            labels:
              io.rancher.container.agent.role: environmentAdmin
              io.rancher.container.create_agent: ‘true'

      • rancher-compose.yml — Add a catalog section and
        questions to this file.

        version: '2'
        catalog:
          name: "myservice"
          version: “0.1"
          description: "Package example to show private repo"
          questions:
            - variable: "PUBLISH_PORT"
              label: "Publish port"
              description: |
                Select port to publish service
              required: true
              default: "8080"
              type: int
        services:
          test:
            scale: 2
            retain_ip: true
            start_on_create: true
            health_check:
              healthy_threshold: 2
              response_timeout: 2000
              port: 8080
              unhealthy_threshold: 3
              initializing_timeout: 60000
              interval: 2000
              strategy: recreate
              request_line: GET "/" "HTTP/1.0"
          lb:
            scale: 1
            start_on_create: true
            lb_config:
              certs: []
              port_rules:
              - hostname: ''
                priority: 1
                protocol: http
                service: test
                source_port: 8080
                target_port: 8080
            health_check:
              healthy_threshold: 2
              response_timeout: 2000
              port: 42
              unhealthy_threshold: 3
              initializing_timeout: 60000
              interval: 2000
              reinitializing_timeout: 60000

      • README.md — Optionally, we recommend adding this file
        to describe how the package works.

      Your Git repo folder structure should look like this:

      templates
      |_ myservice
         |_ config.yml
         |_ catalogIcon-myservice.svg
         |_ 0
            |_ docker-compose.yml
            |_ rancher-compose.yml
            |_ README.md

4. Add, commit, and push your files into your Git repo.

5. 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.

Conclusion

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.