Merge pull request #100963 from trevorbye/master

environment schema for cli

Author: PRMerger6

articles/machine-learning/concept-environments.md

@@ -39,6 +39,7 @@ Environments can be created by:
 * Defining new `Environment` objects, either using a curated environment or by defining your own dependencies
 * Using existing `Environment` objects from your workspace. This allows for consistency and reproducibility with your dependencies
 * Importing from an existing Anaconda environment definition.
+* Using the Azure Machine Learning CLI
 
 See the [how-to](how-to-use-environments.md#create-an-environment) for specific code examples. Environments are also easily managed through your workspace and include the following functionality:
 

articles/machine-learning/how-to-use-environments.md

@@ -344,6 +344,34 @@ service = Model.deploy(
 
 This [example notebook](https://github.com/Azure/MachineLearningNotebooks/tree/master/how-to-use-azureml/training/using-environments) expands upon concepts and methods demonstrated in this article.
 
+## Create and manage environments with the CLI
+
+The [Azure Machine Learning CLI](reference-azure-machine-learning-cli.md) mirrors the majority of the functionality of the Python SDK, and can be used for environment creation and management. The following commands demonstrate basic functionality.
+
+The following command scaffolds the files for a default environment definition in the specified directory. These files are JSON files that are similar in function to the corresponding class in the SDK, and can be used to create new environments with custom settings. 
+
+```azurecli-interactive
+az ml environment scaffold -n myenv -d myenvdir
+```
+
+Run the following command to register an environment from a specified directory.
+
+```azurecli-interactive
+az ml environment register -d myenvdir
+```
+
+Running the following command will list all registered environments.
+
+```azurecli-interactive
+az ml environment list
+```
+
+Download a registered environment with the following command.
+
+```azurecli-interactive
+az ml environment download -n myenv -d downloaddir
+```
+
 ## Next steps
 
 * [Tutorial: Train a model](tutorial-train-models-with-aml.md) uses a managed compute target to  train a model.

articles/machine-learning/reference-azure-machine-learning-cli.md

@@ -259,6 +259,65 @@ The following commands demonstrate how to create, register, and list Azure Machi
 
     For more information, see [az ml environment download](https://docs.microsoft.com/cli/azure/ext/azure-cli-ml/ml/environment?view=azure-cli-latest#ext-azure-cli-ml-az-ml-environment-download).
 
+### Environment configuration schema
+
+If you used the `az ml environment scaffold` command, it generates a template `azureml_environment.json` file that can be modified and used to create custom environment configurations with the CLI. The top level object loosely maps to the [`Environment`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.environment(class)?view=azure-ml-py) class in the Python SDK. 
+
+```json
+{
+    "name": "testenv",
+    "version": null,
+    "environmentVariables": {
+        "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
+    },
+    "python": {
+        "userManagedDependencies": false,
+        "interpreterPath": "python",
+        "condaDependenciesFile": null,
+        "baseCondaEnvironment": null
+    },
+    "docker": {
+        "enabled": false,
+        "baseImage": "mcr.microsoft.com/azureml/base:intelmpi2018.3-ubuntu16.04",
+        "baseDockerfile": null,
+        "sharedVolumes": true,
+        "shmSize": "2g",
+        "arguments": [],
+        "baseImageRegistry": {
+            "address": null,
+            "username": null,
+            "password": null
+        }
+    },
+    "spark": {
+        "repositories": [],
+        "packages": [],
+        "precachePackages": true
+    },
+    "databricks": {
+        "mavenLibraries": [],
+        "pypiLibraries": [],
+        "rcranLibraries": [],
+        "jarLibraries": [],
+        "eggLibraries": []
+    },
+    "inferencingStackVersion": null
+}
+```
+
+The following table details each top-level field in the JSON file, it's type, and a description. If an object type is linked to a class from the Python SDK, there is a loose 1:1 match between each JSON field and the public variable name in the Python class. In some cases the field may map to a constructor argument rather than a class variable. For example, the `environmentVariables` field maps to the `environment_variables` variable in the [`Environment`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.environment(class)?view=azure-ml-py) class.
+
+| JSON field | Type | Description |
+|---|---|---|
+| `name` | `string` | Name of the environment. Do not start name with **Microsoft** or **AzureML**. |
+| `version` | `string` | Version of the environment. |
+| `environmentVariables` | `{string: string}` | A hash-map of environment variable names and values. |
+| `python` | [`PythonSection`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.environment.pythonsection?view=azure-ml-py) | Object that defines the Python environment and interpreter to use on target compute resource. |
+| `docker` | [`DockerSection`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.environment.dockersection?view=azure-ml-py) | Defines settings to customize the Docker image built to the environment's specifications. |
+| `spark` | [`SparkSection`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.environment.sparksection?view=azure-ml-py) | The section configures Spark settings. It is only used when framework is set to PySpark. |
+| `databricks` | [`DatabricksSection`](https://docs.microsoft.com/python/api/azureml-core/azureml.core.databricks.databrickssection?view=azure-ml-py) | Configures Databricks library dependencies. |
+| `inferencingStackVersion` | `string` | Specifies the inferencing stack version added to the image. To avoid adding an inferencing stack, leave this field `null`. Valid value: "latest". |
+
 ## ML pipeline management
 
 The following commands demonstrate how to work with machine learning pipelines: