Parameters

Overview

Parameters allow a user to provide inputs to the Application Template used to customize an environment or runnable job at creation time.

Defining Parameters

Parameters are defined in your app template using the top-level parameters stanza.

For example:

parameters:
  - name: name
    type: string
    description: Enter your name

Parameters require a name, type, and description.

For a complete list of available parameter types, see the schema definition.

Default Values

To provide a default value for a parameter:

parameters:
  - name: gpu_count
    type: integer
    description: Number of GPUs
    default: 2

Optional Parameters

To declare a parameter as optional, set optional: true:

parameters:
  - name: not-required
    type: string
    description: I am not required
    optional: true

An optional parameter's value will be null or an empty string dependending on where it's referenced.

Advanced Parameters

If a parameter is infrequently used or is only used in very specific cases, you can mark the parmeter as advanced: true. Advanced parameters are rendered in the "Advanced" section of our UI and are hidden by default.

parameters:
  - name: my-special-param
    type: string
    description: Don't touch unless you know what you're doing!
    advanced: true

An optional parameter's value will be null or an empty string dependending on where it's referenced.

Using Parameters

Parameters can be referenced from most places in your Application Template using this syntax: ${parameters.my_parameter_name}. Here are some common example use cases.

Environment Variables

Injecting a parameter values into environment variables:

parameters:
  - name: worker_threads
    type: integer
    description: Number background worker threads
  - name: db_host
    type: string
    description: Database server hostname

services:
  - name: worker
    envs:
      - key: WORKER_THREADS
        value: ${parameters.worker_threads}
      - key: DB_URL
        value: postgres://${parameters.db_host}:5432/my_db

Resource Requests & Limits

Injecting a parameter values into resource limits:

parameters:
  - name: gpu_count
    type: integer
    description: Number of GPUs

services:
  - name: fine-tuning
    resources:
    nvidia_com_gpu:
      limits: ${parameters.gpu_count}

Workspaces

Parameters are designed to work well with Workspaces. For example the git-ref, git-repo, and file parameter types all produce result in values that can be referenced directly from a workspace mount.

This allows dynamically picking a file or Git repository that can be accessible from a known location from within your containers.

Example:

parameters:
  - name: source_repo
    type: git-repo
  - name: training_data
    type: file

workspaces:
  - name: default
    auto_attach: true
    path: /workspace
    mounts:
      - path: repo
        source_url: ${parameters.source_repo}
      - path: training-data
        source_url: ${parameters.training_data}

jobs:
  - name: run-training
    envs:
      - key: TRAINING_DATA_PATH
        value: /workspace/training-data
      - key: REPO_PATH
        value: /workspace/repo

This will show a Git repository picker and a file upload picker in the UI when creating a job or environment for this application allowing the user to customize which code or data is made available to the job.

Parameter Types

string

To define a single line string input:

parameters:
  - name: name
    type: string
    description: Enter your name

text

To define a multiline text parameter:

parameters:
  - name: long-text
    type: text
    description:

boolean

To define a boolean checkbox parameter:

parameters:
  - name: debug
    type: boolean
    description: Enable debug mode

The values when interpolated as a string (i.e. in an environment variable) will be either true or false.

git-repo

To define a Git repository picker parameter:

parameters:
  - name: repo
    type: git-repo
    description: Choose a Git repository

This will only allow selecting a repository that has been registered with Release. See source control integrations for more details.

Git repo parameters are also usable from workspace mounts.

git-ref

To define a Git ref picker parameter:

parameters:
  - name: ref
    type: git-ref
    description: Choose a Git repository and branch

This is similar to git-repo but instead of using the repository's default branch, it allows the user to select a specific branch, tag, or commit.

Git ref parameters are also usable from workspace mounts.

file

To define a file picker parameter:

parameters:
  - name: my-file
    type: file
    description: Upload or select a file

This will allow the user to either upload a new file or choose an previously uploaded file.

File parameters are also usable from workspace mounts.