Skip to main content

Provider Options

Inside the provider.yaml, you can specify options that DevPod can pass to the provider when calling it. Each option will be passed as an environment variable to the commands or can be used directly inside the agent section of a provider.

...
...
options:
  MY_OPTION_NAME:
    description: "this is my option"
    default: "default_value"
    required: false
    password: true
...
...

How options work​

Options are variables needed for the provider to function properly, for example:

  • User Accounts
  • VMs images
  • VMs sizes
  • Account region

These options are parsed and validated by DevPod when Adding the provider and passed to the provider as environment variables.

It's the provider's job to retrieve them from the environment and validate them. It's recommended to make use of the init command that will be called by DevPod when options change to validate environment variables on the provider side.

You can check our example in the Devpod's AWS Provider where we parse and validate the variables:

...
    diskSizeGB, err := fromEnvOrError("AWS_DISK_SIZE")
    if err != nil {
        return nil, err
    }

    retOptions.DiskSizeGB, err = strconv.Atoi(diskSizeGB)
    if err != nil {
        return nil, err
    }
...

Options will also be passed to the agent and can be used in the agent.exec section. This is very useful if you require certain information on the agent side to perform an auto-inactivity timeout.

Option configuration​

Each option has a set of attributes that can modify how DevPod interprets it when configuring or adding the provider:

  • description: Description shown in devpod provider options and in the Desktop App
  • default: Default value of the option provided as a string. Can also reference other variables, e.g. ${MY_OTHER_VAR}-suffix
  • required: Boolean if this option needs to be non-empty before using the provider. DevPod will ask in the CLI and make sure that this option is filled in the Desktop application.
  • password: Boolean to indicate this is a sensitive value. Prevents this value from showing up in the devpod provider options command and will be a password field in the Desktop application.
  • suggestions: An array of suggestions for this option. Will be shown as auto complete options in the DevPod desktop application
  • command: A command to retrieve the option value automatically. Can also reference other variables in the command, e.g. echo ${MY_OTHER_VAR}-suffix. For compatibility reasons, this command will be executed in an emulated shell on Windows.
  • local: If true, the option will be filled individually for each machine / workspace
  • global: If true, the option will be reused for each machine / workspace
  • cache: If non-empty, DevPod will re-execute the command after the given timeout. E.g. if this is 5m, DevPod will re-execute the command after 5 minutes to re-fill this value. This is useful if you want to store a token or something that expires locally in a variable.
  • hidden: If true, DevPod will not show this option in the Desktop application or through devpod provider options. Can be used to calculate variables internally or save tokens or other things internally.

Default values​

As the name implies, this is a default value for the option. It is always advisable to place a sensible default for any option.

You can also reference other options inside the default value, e.g. ${MY_OTHER_VAR}-suffix. DevPod will automatically figure out what options need to be resolved before this option.

If not specified, it defaults to an empty string.

Required options​

If an option is required, and no default is set, DevPod will prompt the user for a value when adding the provider.

In the DevPod Desktop App, the required options will be displayed and prompted right in the Provider's "Add" page.

If not specified, it defaults to false.

Password options​

If specified and true, the option's value will be treated as a secret, so it won't be shown when listing options.

Example:

~$ adevpod provider options civo

          NAME            | REQUIRED |          DESCRIPTION           |               DEFAULT                |                VALUE
----------------------------+----------+--------------------------------+--------------------------------------+---------------------------------------
AGENT_PATH                | false    | The path where to inject the   | /var/lib/toolbox/devpod              | /var/lib/toolbox/devpod
                          |          | DevPod agent to.               |                                      |
CIVO_API_KEY              | true     | The civo api key to use        |                                      | ********
CIVO_DISK_IMAGE           | false    | The disk image to use.         | d927ad2f-5073-4ed6-b2eb-b8e61aef29a8 | d927ad2f-5073-4ed6-b2eb-b8e61aef29a8

...

If not specified, it defaults to false.

Options suggestions​

Suggestions are a list of possible values for the option. Suggested use-cases could be for regions/locations, VM sizes, etc...

info

This option is specifically for the DevPod desktop application, suggestions won't be shown in the CLI app.

If not specified, it defaults to empty and ignored.

Command options​

The command option lets you define a possible value for an option based on a shell command launched on your machine. Can also reference other variables in the command, e.g. echo ${MY_OTHER_VAR}-suffix. For compatibility reasons, this command will be executed in an emulated shell on Windows.

One example would be to forward ENV variables from your machine to the provider, for example:

  AWS_ACCESS_KEY_ID:
    description: The aws access key id
    required: false
    command: printf "%s" "${AWS_ACCESS_KEY_ID:-}"
  AWS_SECRET_ACCESS_KEY:
    description: The aws secret access key
    required: false
    command: printf "%s" "${AWS_SECRET_ACCESS_KEY:-}"

Or running an helper command (defined in the binaries section), and forwarding the result as the option's value:

  AWS_TOKEN:
    local: true
    hidden: true
    cache: 5m
    description: "The AWS auth token to use"
    command: |-
      ${AWS_PROVIDER} token

If not specified, it defaults to empty and ignored.

Built-In Options​

There are a couple of predefined options from DevPod, that can be used within the default field of another option or in an option command. Some built-in options are only available for local options as the MACHINE_ID might not be available already. Predefined options:

  • DEVPOD: Absolute path to the current DevPod CLI binary. Can be used to call a helper function within DevPod or any other DevPod command. Also available on the agent side.
  • DEVPOD_OS: Current Operating system. Can be either: linux, darwin or windows
  • DEVPOD_ARCH: Current operating system architecture. Can be either: amd64 or arm64.
  • MACHINE_ID: The machine id that should be used. (Only available for local options, commands and machine providers)
  • MACHINE_FOLDER: The machine folder that can be used to cache information locally. (Only available for local options, commands and machine providers)
  • MACHINE_CONTEXT: The DevPod context this machine was created in. (Only available for local options, commands and machine providers)
  • MACHINE_PROVIDER: The provider name that was used to create this machine. (Only available for local options, commands and machine providers)
  • WORKSPACE_ID: The workspace id that should be used. (Only available for local options, commands and non-machine providers)
  • WORKSPACE_FOLDER: The workspace folder that can be used to cache information locally. (Only available for local options, commands and non-machine providers)
  • WORKSPACE_CONTEXT: The DevPod context this workspace was created in. (Only available for local options, commands and non-machine providers)
  • WORKSPACE_PROVIDER: The provider name that was used to create this workspace. (Only available for local options, commands and non-machine providers)
  • PROVIDER_ID: The provider name. (Only available for local options, commands and non-machine providers)
  • PROVIDER_CONTEXT: The provider context. (Only available for local options, commands and non-machine providers)
  • PROVIDER_FOLDER: The provider folder where the provider config is saved in, can be used to save global information about the provider such as global session tokens etc. (Only available for local options, commands and non-machine providers)

Option Groups​

info

This section is specifically for organizing options in the DevPod Desktop app. This has no effect on the CLI app.

You can organize your options in groups, for example:

optionGroups:
  - options:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_AMI
      - AWS_DISK_SIZE
      - AWS_INSTANCE_TYPE
      - AWS_VPC_ID
    name: "AWS options"
    defaultVisible: true
  - options:
      - AGENT_PATH
      - INACTIVITY_TIMEOUT
      - INJECT_DOCKER_CREDENTIALS
      - INJECT_GIT_CREDENTIALS
    name: "Agent options"
    defaultVisible: false

Options are easily grouped by listing them, each group has a name and a defaultVisible property, which is false by default. If defaultVisible is false, then an user will need to manually expand the option group in the Desktop App.