Audience

This article is to support customers of Runner, a product that enables teams, developers, and engineers to quickly provision, interact, and modify their environments anywhere - CenturyLink Cloud, third-party cloud providers, and on-premises.

Catalog & Product Overview

A Runner product allows for a user to build a form around their Ansible playbooks to allow for dynamic user inputs at runtime. A Runner catalog is a git repository that contains a collection of products.

• Create a Runner Catalog
• Update a Runner Catalog
• Refresh a Runner Catalog
• Create a Runner Product
• Create Product Config
  • Readme File
  • Config File
  • Required Elements
  • Config Field Types

Create a Runner Catalog

A Runner Catalog is a github repository that contains one or more Runner proudcts. To create a Catalog, click the Help & Settings drop-down and select Settings.

On the left side, select Catalogs and this will bring up a view showing you all of your existing catalogs. Click on the add button and a form will appear where you can enter the required information.

• (1): Enter the name that you want to use to label this catalog.
• (2): Enter a description for this catalog
• (3): Enter the HTTPS git URL for the repo you are wanting to add as a catalog
• (4): Enter the branch you want this catalog to read from. (This needs to be compliant with github's API, so for branch "master" it is "heads/master")
• (5): Enter your github username. (This is only required if it is a private repository)
• (6): Enter your github password. (This is only required if it is a private repository)

Click the submit button and your catalog will be added. If you already have products configured in your repo they will start to show up in the private products section after several minutes.

Update a Runner Catalog

To update a Runner Catalog, go back to the Catlogs screen and hover over the catalog you want to update. Click the gear icon and it will open the edit form where you can edit any necessary details.

Refresh a Runner Catalog

Runner catalogs will refresh themselves every 5 minutes and scan your repository for new product directories. In the event that you need an immediate refresh or are not seeing your updates there is a manual refresh button that can be used. If you go to your catalogs, hover over the relevant catalog and hit the refresh button. This will trigger a forced reload of your catalog.

Create a Runner Product

In order to have a product be recognized by Runner, it must first be present in its own folder in an existing catalog. Inside the folder, there must be a minimum of three files; your main playbook.yaml file, a README.md file, and a product.yml file.

In the below image, you can see the public Runner Library repository. Through the Runner interface, this repository is configured as a catalog and each folder that you see is a separate product within Runner.

Create Product Config

Readme File

As part of configuring a new product, your product folder must have a README.md file. This file should provide details about how your product works and the various options that are provided. The contents of this file are then rendered into the Runner UI when your product is loaded.

Config File

The config.yml file tells Runner all the necessary details about your product and is also where you configure your product form. Below are the required fields that you must put in your config.yml in order to have your Runner product page render properly.

Required Elements:

Config Field Types

The config.yml file is used to not only provide information about your product, but can also be used to build dynamic forms to provide information to your playbook. Below are the various field types you can use to acquire information from the user and pass it to your playbook.

Datacenters

The datacenters field will query the CenturyLink Cloud APIs and bring back all valid datacenters for an account alias.

Options

Example

  fields:
    - type: datacenters
      name: my_datacenter
      displayName: Select a Datacenter
      required: true

Groups

The groups field will query the CenturyLink Cloud APIs and display all groups for an account alias. The output can be restricted to a specific datacenter if you include a parent option.

Options

Example

fields:
  - type: groups
    name: my_groups
    displayName: Select Your Groups
    multiple: true
    required: true

Parent Example

fields:
  - type: datacenters
    name: my_datacenter
    displayName: Select a Datacenter
    required: true

  - type: groups
    name: my_groups
    displayName: Select Group
    parent: my_datacenter
    multiple: false
    required: true

Servers

The servers field will query the CenturyLink Cloud APIs and display all servers for an account alias.

Options

Example

fields:
  - type: servers
    name: my_servers
    displayName: Select your servers
    multiple: true
    required: true
    inventory: false

Networks

The networks field will query the CenturyLink Cloud APIs and display all networks for an account alias.

Options

Example

fields:
  - type: networks
    name: my_network
    displayName: Select your Network
    required: true
    detail: true

Textblock

The textblock field can be used to display various types of information or warning type text on the product form.

Options

Example

fields:
  - type: textblock
    name: text_block_warning
    title: "Warning"
    text: "This is showing you the warning text"
    level: warning

Toggle

The toggle field generates a toggle button that can be used to send a true or false variable to Ansible

Options

Example

fields:
  - type: toggle
    name: toggle_field
    displayName: "Enable this feature?"
    default: true

Slider

The slider field allows you to generate a numeric slider

Options

Example

fields:
  - type: slider
    name: slider_value
    displayName: "How many things do you want?"
    min: 1
    max: 10
    default: 4
    required: true

Text

The text field allows you to specify text as a value

Options

Example

fields:
  - type: text
    name: text_value
    displayName: "What would you like to name this item?"
    helpText: "The name of your server for example?"
    default: "Test12"
    maxLength: 6
    required: false

Textarea

The textarea field allows you to specify large blocks of text

Options

Example

fields:
  - type: textarea
    name: license
    displayName: "Copy in your license text"
    required: true

Number

The number field allows you to specify a number

Options

Example

fields:
  - type: number
    name: some_number
    displayName: "Enter a number"
    default: 3
    min: 1
    max: 10
    required: false

Select

The select field allows you to select values from a pre-defined list

Options

Example

fields:
  - type: select
    name: item_select
    displayName: Select an item
    options:
      - displayName: "Item 1"
        value: item1
      - displayName: "Item 2"
        value: item2
        selected: true
      - displayName: "Item 3"
        value: item3
    multiple: false
    required: true

Password

The password field allows you to specify passwords while keeping the text hidden on the screen

Options

Example

fields:
  - type: password
    name: srv_password
    displayName: "Please enter a server password"
    required: true

PasswordStrength

The passwordStrength field allows you to specify passwords that conform to certain complexity standards

Options

Example

fields:
  - type: passwordStrength
    name: srv_password
    displayName: "Enter a strong password"
    validationMsg: A password must be at least 9 characters and contain at least 3 of the following (uppercase letters, lowercase letters, numbers, symbols)
    requiredStrength: 3
    dissallowedCharacters: "/"
    required: true