Environments

Creating an environment

Go to your team's directory in the repo and create a new directory for your environment with these contents:

my_env/               # Name should match environment name
├── asset.yaml        # Asset config file
├── environment.yaml  # Environment config file
├── spec.yaml         # Spec file for use with Azure CLI
└── context/          # Docker build context (may contain additional files)
    └── Dockerfile    # Dockerfile

asset.yaml

The asset config file provides configuration that is common to all types of assets.

name: my_env                    # Asset name. If omitted, will be read from spec's name property.
version: auto                   # Asset version. If omitted, will be read from spec's version property. "auto" means automatic 1-up versioning.
type: environment               # Asset type. Must be code, component, environment, or model.
spec: spec.yaml                 # Spec file, relative to asset config file
extra_config: environment.yaml  # Environment config file, relative to asset config file
release_paths:                  # Optional, used to include additional dirs/files during release
- ../src                        # Paths are relative to asset config file
- "!../src/test"                # Exclude dirs/files by using a ! prefix
test:                           # Optional, used to enable pytest testing
  pytest:                                     # Config items for pytest 
    enabled: true                             # Flag to enable/disable testing
    pip_requirements: tests/requirements.txt  # Requirements installed before testing
    tests_dir: tests                          # Directory containing tests

environment.yaml

An environment config file provides configuration specific to environments.

image:                          # Image configuration
  name: azureml/curated/my_env  # Name of the environment's Docker image
  os: linux                     # OS type, either linux or windows
  context:                      # Docker build context information
    dir: context                # Directory containing the build context, relative to the environment config file
    dockerfile: Dockerfile      # Dockerfile location, relative to the build context directory. Defaults to Dockerfile if unspecified.
    template_files:             # Optional list of files that contain template tags that should be resolved before building the image
    - Dockerfile                # Template tags in this file will be replaced
  publish:                      # Publishing settings for the image
    location: mcr               # Location to which the image will be published. Must be set to mcr.
    visibility: public          # Visibility of published image. Options are public, internal, staging, or unlisted.

Template tags

The following template tags are supported:

Tag	Normally used in	Resolves to	Example
{{latest-image-tag}}	Dockerfile	Either an image tag that with the same digest as latest, or the digest itself if a tag is not found	FROM mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:{{latest-image-tag}}
{{latest-image-tag:<some_regex>}}	Dockerfile	The most recent (descending lexicographical sort) tag that matches the provided regular expression	FROM mcr.microsoft.com/azureml/aifx/stable-ubuntu2004-cu113-py38-torch1110:{{latest-image-tag:monthly\.\d{6}}}
{{latest-pypi-version}}	requirements.txt or conda_dependencies.yaml	The latest version of a package in PyPI	azureml-core=={{latest-pypi-version}}

Any of the above tags are resolved if they appear in any of the files listed in an environment config's template_files property.

spec.yaml

An Azure CLI v2 spec file. An environment example would look like this:

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json

description: >-
  A sample environment.

name: "{{asset.name}}"
version: "{{asset.version}}"

build:
  path: "{{asset.repo.url}}#{{asset.repo.commit_hash}}:{{asset.repo.build_context.path}}"
  dockerfile_path: "{{image.dockerfile.path}}"

os_type: linux

tags:
  PyTorch: "1.11"
  GPU: Cuda11
  OS: Ubuntu20.04
  Training: ""
  Preview: ""

Spec files associated with assets in this repository may contain the following template tags:

Tag	Resolves to
{{asset.name}}	Name of the asset, from the asset config
{{asset.version}}	Version of the asset, from the asset config
{{asset.repo.build_context.path}}	Path to the environment's Docker build context in the release branch
{{asset.repo.commit_hash}}	Git commit hash of the commit being released
{{asset.repo.url}}	Git URL for this respository
{{image.name}}	Name of the environment's Docker image
{{image.dockerfile.path}}	Path to the Dockerfile, relative to the Docker build context root
{{image.publish.hostname}}	Hostname of the container registry to which the image will be published

Note that some of the tags above are common to all assets and some are environment-specific.

Releasing an environment