Rancher Catalog

Overview

This document covers the rancher Catalog feature design.

Purpose

Rancher Catalog feature will enable a user to view a catalog of pre-cooked templates and launch the template onto a specific Rancher environment.

Use cases

Use Case #1

• On UI, User lists and views a catalog of templates pulled from the public rancher github repo.
• The catalog should be arranged using categories of templates and provide name/description for the template

Use Case #2

• Enable User to launch a template to a specified rancher environment
• User will need to authenticate with rancher environment by providing relevant keys.
• User should be able to provide input to the rancher-compose or docker-compose file on the UI

Use Case #3

• Enable the catalog consumer to know if newer versions of a particular template are available
• This will help rancher stack to find out if 'upgrade' option is available for a service in the stack

Scope

Scope of this feature is limited to above two usecase. The service will not implement adding/updating the templates to the catalog on github. Service will just implement pulling the catalog from github.

Design

A new service will be hosted to read the template catalog from the github repo and expose a REST API to list the templates.

For phase 1, assume the public github rancher repo containing the catalog.

API design

For the use case#1

The service will expose following API with the schema as below. The API will list all metadata for all templates in the catalog. Each template will carry links to the subversions.

http://<server_ip>:8088/v1/schemas/template

{
  "id": "template", 
  "type": "schema",
  "resourceMethods": ["GET"],
  "resourceFields": {
     "name":   {"type": "string", "required": true},
     "description":   {"type": “string"},
     "category":   {"type": “string","required": true},
     "defaultVersion":   {"type": “string","required": true},
     "iconLink":   {"type": “string","required": true},
     "versionLinks":   {"type": "map[string]","required": true},
  },
  “resourceActions”:{}
  "collectionMethods": ["GET"],
  “collectionActions”:{},
  "collectionFields": {},
  "collectionFilters": {}
}

GET http://<server_ip>:8088/v1/templates/

{
  "type": "collection",
  "resourceType": "template",
  "links": {},
  "createTypes": {},
  "actions": {},
  "data": [
    {
     "type": "template",
     "links": {},
     "actions": {},
     "name": "Elastic",
     "category": "ELK",
     "description": “Its designed…”,
     "defaultVersion": “1.2”,
     "iconLink":"” ,
 "versionLinks": {
    	"1.1-2": "http://.../v1/templates/Elastic/1.1-2",
    	"1.2": "http://.../",
		}
    }
  ]
}

For the use case#2

A user can click on each template version link, that will load the details of the template.

The details will have the rancherCompose and dockerCompose file contents. Also it will have a 'questions' sections with expected answer datatype. These questions will be the user input parameters required to launch the template.

GET http://<server_ip>:8088/v1/templates/Elastic/1.1-2 

{
     "type": "template",
     "links": {},
     "actions": {},
     "name": "Elastic/1.1-2",
     "uuid": "a9630a81-6114-421b-b304-3c7469105335",
     "category": "ELK",
     "description": “Its designed…”,
     "defaultVersion": “1.1-2”,
     "iconLink": "",
     "rancherCompose": "",
     "dockerCompose": "",
     "questions": [
       {
        name: "BLAH",
        description: "What do want to call BLAH",
        type: "enum",
        options:
        name: "BLAH2"
        type: "string"
        }
      ]
   }

For the use case#3

The service will expose following API to find out if any new versions are available for a given template uuid. If the response provides links to newer versions, it will indicate that an upgrade is available. If there are no newer versions, an empty versionLinks will be present.

POST http://<server_ip>:8088/v1/templates/<template_uuid>?getNewVersions
Response:
{
  "type": "collection",
  "resourceType": "template",
  "links": {},
  "createTypes": {},
  "actions": {},
  "data": [
    {
     "type": "template",
     "links": {},
     "actions": {},
     "name": "Elastic",
     "category": "ELK",
     "description": “Its designed…”,
     "defaultVersion": “1.2”,
     "iconLink":"” ,
 "versionLinks": {
    	"1.3": "http://.../v1/templates/Elastic/1.3",
    	"1.4": "http://.../",
		}
    }
  ]
}

Github repo structure

Refer: rancher-catalog repo here

TODOs/Thoughts

1. How to read from the github repo - do we need to create a read-only account on that repo and let the service connect using ssh keys of the account?
2. Need to disallow writing to this repo.
3. How to set the rancher environment to launch the template
4. How to transfer the icon image?
5. The service will not save the repo state in DB, but maybe in-memory cache is needed to have faster catalog rendering. If cache used, need to re-sync the repo periodically