Templating Syntax

Basic Template Policy #


Templates control how DevZero developer environments ("DevBoxes") are created, e.g. by cloning source code, installing packages, and running custom commands.


The DevZero template is composed of yaml with a few main blocks: softwarepolicy, repopolicy and scriptpolicy. Here's an example of a minimal template:

softwarepolicy:
- packagename: build-essential # includes make

repopolicy:
- path: /home/devzero/projects
  repourl: https://github.com/hashicorp/vault # will clone vault
  
scriptpolicy:
- script: |
    # some mulitline script
    echo "run this"
    wget "httpbin.org/get" > file.txt
  runas: devzero # user to run script as

Software Policy #

List of Debian packages that will get installed on a DevBox. These are installed by the root user. with apt-get.

softwarepolicy:
- packagename: build-essential
- packagename: nano
- packagenames: # or write as a list of packages
  - zsh
  - jq

Repo Policy #

These are the repositories that are cloned and kept updated by the agent. At checkout time, ownership is transferred to the user is assigned to the DevBox. Note that, for private repositories, organization configuration is required in order to access code.

repopolicy:
- path: /home/devzero/projects
  repourl: https://github.com/hashicorp/vault
- path: /home/devzero/projects
  repourl: https://github.com/organization/repo

Script Policy #

Scripts can be run at various stages using the key: runphase:

  • regular: after the machine has been initialized w/ the basic templates, this is the default, it does not need to be specified
  • checkout: when a user is assigned to a DevBox
scriptpolicy:
- script: |
    # docker install instructions from: https://docs.docker.com/engine/install/ubuntu
    apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
    echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
    apt-get update -y
    apt-get install docker-ce docker-ce-cli containerd.io -y
    
- script: whoami > /home/devzero/whoami.txt
  runphase: checkout # user will be filled in based on assigned user
  runas: devzero # this is the primary user for the machine
  timeoutsecs: 300 # set a timeout of 300 seconds, by default all scripts will execute until completion or exit
- script: echo 'hello!' > hello.txt
  cwd: /home/devzero # cwd will "change working directory" to path when running script, so file will be at /home/devzero/hello.txt

Secrets in script #

If you want to use a secret, put ${{ SECRET_NAME }} in the template. We make secrets available as environment variables.

If your key is `KEY`, and you want to use it in a script, you can do:

scriptpolicy:
- script: |
    huggingface-cli --token ${{ KEY }}

User Policy #

This section of code is run only on DevBoxes allocated to an individual user. For example, not every developer in an organization may want oh-my-zsh on their DevBoxes, but a user that does can have it installed every time by defining the policy here. Everything that the template policy has can also be accessed here, using the same terminologies.

# set up oh-my-zsh for this user
scriptpolicy:
- script: sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
  runas: devzero

Network Policy #

Defines available ports and protocols to be exposed. protocol: (http|https) where http indicates you are exposing a plain HTTP service, while https indicates you have your own TLS mechanism (e.g. self-signed certs).


networkpolicy:
  ports:
  - port: 8000
    protocol: http
    name: fileserver
  - port: 8001
    protocol: https
    name: secureserver





PreviousCLI Reference