Environments

Creating an environment

Some examples are located under training/general/src/environments.

Environment name

Please see the environment naming convention.

Environment files

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.

Note that the image name will need to be registered with MCR before the environment is added to azureml-assets. Otherwise, the environment will fail to create in any registry. The image name should largely match the environment name and be prefixed with azureml/curated/.

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}}
{{latest-pypi-version:pre}}	requirements.txt or conda_dependencies.yaml	The latest version of a package in PyPI, including prerelease ones	azureml-core=={{latest-pypi-version:pre}}

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.context.path}}	Path to the Docker build context, relative to the spec file
{{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

The assets-release workflow runs each time a PR merges to the main branch. The workflow performs the following actions:

1. Searches the main branch for asset.yaml files
2. Compares each asset against the contents of release branch to identify whether it's new, updated, or unchanged
3. Adds new assets to the release branch
4. Updates changed assets, if one of the following is true:
   • The asset is auto versioned
   • It's manually versioned and hasn't been released yet
5. Commits changes to the release branch

Environments are released as needed from the contents of the release branch. As part of the release process an environment/<name>/<version> tag is added to the repo for reference. These steps occur outside of GitHub and involve building and publishing the Docker image, and then creating the environment in the azureml registry.

Deprecating an environment

When an environment is no longer needed, follow the steps below to deprecate it:

1. Create a PR to modify the environment in the main branch:
   • Add the following to the beginning of the environment's description: DEPRECATED: Please use <recommended replacement environment> instead.
   • Add a Deprecated tag with an empty value
   • Add a DeleteOn tag with the value of the date (YYYY-MM-DD) that it should removed from the UI, ideally 3-6 months from the current date
2. After the PR is merged, release the updated environment
3. Create a PR to remove the environment from the main branch, and do the same for the release branch as well
4. When the DeleteOn date, archive the environment, which removes it from display by the UI/SDK/CLI, but doesn't break anyone still using it