Using Private Catalogs in Rancher | SUSE Communities

Using Private Catalogs in Rancher

Share

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.