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
andMYUSER
. Note thatMYUSER
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
usegpu
. 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 useenvironments
. For setting the--volume
flag. Usevolumes
- 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 - ...
-
When specifying a command and arguments, use the syntax:
command: value: true extra-args: - sleep - infinity
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