Skip to content

Configure Command-Line Interface Templates

What are Templates?

Templates are a way to reduce the number of flags required when using the Command-Line Interface to start workloads. The researcher can:

  • Use a template by running runai submit --template <template-name>
  • Review list of templates by running runai list template
  • Review the contents of a specific template by running runai describe template <template-name>

The purpose of this document is to provide the Administrator with guidelines on how to create & maintain templates.

Template and Kubernetes

CLI Templates are implemented as_ Kubernetes ConfigMaps. A Kubernetes ConfigMap is the standard way to save cluster-wide settings.

Creating a Template

To create a template, create a file (e.g. my-template.yaml) with:

apiVersion: v1
kind: ConfigMap
data:
  name: template-1
  description: "my first template"
  values: |
    gpu: 
      required: true
    image:
      value: tensorflow/tensorflow:1.14.0-gpu-py3
    environments:
      - LEARNING_RATE=0.2
      - MYUSER=$USER
      - MYPASSWORD=SECRET:my-secret,cred-pass
metadata:
  name: template-1
  namespace: runai
  labels:
    runai/template: "true"

To store this template run:

kubectl apply -f my-template.yaml 

Notes

  • The template above sets the following:
    • That --gpu (or -g) is a required field when using this template
    • The default image file will be tensorflow/tensorflow:1.14.0-gpu-py3. The user can override this value and use a different image by setting the --image (-i) flag.
    • There are two environment variables set LEARNING_RATE and MYUSER. Note that MYUSER will be set at runtime according to the value of $USER. The user can add environment variables, and override existing ones.
    • MYPASSWORD is set from a Kubernetes secret. For further information see Setting secrets in Jobs
  • The label runai/template marks the ConfigMap as a Run:AI template.
  • The name and description will show when using the runai template list command.
  • See additional information below on flag syntax.

To see this template in the template list run:

runai list template

To show the properties of the created template run:

runai describe template template-1

Use the template when submitting a workload

runai submit my-job1 ....  --template template-1

Syntax

  • When specifying a single-value flag, use the full name of the flag. For example, for setting --gpu use gpu. For a list of flags, see the runai-submit reference document.
  • When specifying a multi-value flag, use the plural of the flag name. For example: for setting the --environment flag use environments. For setting the --volume flag. Use volumes
  • When specifying a single value flag, use the syntax:
single-value-flag:
    required: true/false
    value: string
  • When specifying a multi-value flag, use the syntax:
multi-value-flag:
  - value1
  - value2
  - ...

The Default Template

The Administrator can also set a template that is always active:

apiVersion: v1
kind: ConfigMap
data:
  name: template-admin
  description: "my first template"
  values: |
    job-name-prefix:
      value: acme
    volumes:
      - /mnt/nfs-share/john:/workspace/john
metadata:
  name: template-admin
  namespace: runai
  labels:
    runai/template: "true"

Notes

  • The template is denoted as the admin template with the name template-admin

Override rules

  • The User, when running runai submit always overrides the default template and a template specified with --template
  • The default template overrides any specified template.

Deleting a Template

to delete a template, run:

kubectl delete cm -n runai <template-name>

See Also

For a list of runai submit flags, see the Run:AI command-line reference


Last update: November 29, 2020