Update how-to-troubleshoot-environments.md

Author: edebar01

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

@@ -165,7 +165,7 @@ To create a new environment, you must use one of the following approaches:
     - [Sample here](https://aka.ms/azureml/environment/create-env-conda-spec-v2)
 
 ### Missing Docker definition
-*Applies to: Azure CLI & Python SDK v1 (Deprecated)*
+*Applies to: Python SDK v1 (Deprecated)*
 <!--issueDescription-->
 This issue can happen when your environment definition is missing a `DockerSection.` This section configures settings related to the final Docker image built from your environment specification.
 
@@ -195,16 +195,12 @@ myenv.docker.base_dockerfile = dockerfile
 **Resources**
 * [DockerSection](https://aka.ms/azureml/environment/environment-docker-section)
 
-### Missing Docker build context location
-- If you're specifying a Docker build context as part of your environment build, you must provide the path of the build context directory
-- See [BuildContext](https://aka.ms/azureml/environment/build-context-class)
-
 ### Too many Docker options
 <!--issueDescription-->
 
 **Potential causes:**
 
-*Applies to: Azure CLI & Python SDK v1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 You have more than one of these Docker options specified in your environment definition
 - `base_image`
@@ -227,7 +223,7 @@ You have more than one of these Docker options specified in your environment def
 
 Choose which Docker option you'd like to use to build your environment. Then set all other specified options to None.
 
-*Applies to: Azure CLI & Python SDK v1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 ```
 from azureml.core import Environment
@@ -248,7 +244,7 @@ myenv.docker.base_image = None
 
 **Potential causes:**
 
-*Applies to: Azure CLI & Python SDK v1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 You didn't specify one of the following options in your environment definition
 - `base_image`
@@ -271,15 +267,15 @@ You didn't specify one of the following options in your environment definition
 
 Choose which Docker option you'd like to use to build your environment, then populate that option in your environment definition.
 
-*Applies to: Azure CLI & Python SDK v1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 ```
 from azureml.core import Environment
 myenv = Environment(name="myEnv")
 myenv.docker.base_image = "pytorch/pytorch:latest"
 ```
 
-*Applies to: Azure CLI & Python SDK v2*
+*Applies to: Python SDK v2*
 
 ```
 env_docker_image = Environment(
@@ -307,7 +303,7 @@ ml_client.environments.create_or_update(env_docker_image)
 
 **Troubleshooting steps**
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 Add the missing username or password to your environment definition to fix the issue
 
@@ -323,7 +319,7 @@ ws = Workspace.from_config()
 ws.set_connection("connection1", "ACR", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")
 ```
 
-*Applies to: Azure CLI extensions V1 & V2*
+*Applies to: Azure CLI extensions v1 & v2*
 
 Create a workspace connection from a YAML specification file
 
@@ -335,8 +331,8 @@ az ml connection create --file connection.yml --resource-group my-resource-group
 > * Providing credentials in your environment definition is deprecated. Use workspace connections instead.
  
 **Resources**
-* [Python SDK AzureML v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
-* [Python SDK AzureML v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
+* [Python SDK v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
+* [Python SDK v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
 * [Azure CLI workspace connections](/cli/azure/ml/connection)
 
 ### Multiple credentials for base image registry
@@ -352,7 +348,7 @@ az ml connection create --file connection.yml --resource-group my-resource-group
 
 **Troubleshooting steps**
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 If you're using workspace connections, view the connections you have set, and delete whichever one(s) you don't want to use
 
@@ -374,8 +370,8 @@ myEnv.docker.base_image_registry.registry_identity = None
  
 **Resources**
 * [Delete a workspace connection v1](https://aka.ms/azureml/environment/delete-connection-v1)
-* [Python SDK AzureML v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
-* [Python SDK AzureML v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
+* [Python SDK v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
+* [Python SDK v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
 * [Azure CLI workspace connections](/cli/azure/ml/connection)
 
 ### Secrets in base image registry
@@ -393,7 +389,7 @@ myEnv.docker.base_image_registry.registry_identity = None
 
 Specifying credentials in your environment definition is deprecated. Delete credentials from your environment definition and use workspace connections instead.
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 Set a workspace connection on your workspace
 
@@ -403,7 +399,7 @@ ws = Workspace.from_config()
 ws.set_connection("connection1", "ACR", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")
 ```
 
-*Applies to: Azure CLI extensions V1 & V2*
+*Applies to: Azure CLI extensions v1 & v2*
 
 Create a workspace connection from a YAML specification file
 
@@ -412,8 +408,8 @@ az ml connection create --file connection.yml --resource-group my-resource-group
 ```
 
 **Resources**
-* [Python SDK AzureML v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
-* [Python SDK AzureML v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
+* [Python SDK v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
+* [Python SDK v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
 * [Azure CLI workspace connections](/cli/azure/ml/connection)
 
 ### Deprecated Docker attribute
@@ -436,30 +432,107 @@ az ml connection create --file connection.yml --resource-group my-resource-group
 
 **Troubleshooting steps**
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1 (Deprecated)*
 
 Instead of specifying these attributes in the `DockerSection` of your environment definition, use [DockerConfiguration](https://aka.ms/azureml/environment/docker-configuration-class)
 
 **Resources**
 * See `DockerSection` [deprecated variables](https://aka.ms/azureml/environment/docker-section-class)
 
 ### Dockerfile length over limit
-- The specified Dockerfile can't exceed the maximum Dockerfile size of 100 KB
-- Consider shortening your Dockerfile to get it under this limit
+<!--issueDescription-->
+**Potential causes:**
+* Your specified Dockerfile exceeded the maximum size of 100 KB
+
+**Affected areas (symptoms):**
+* Failure in registering your environment
+<!--/issueDescription-->
+
+**Troubleshooting steps**
+
+Shorten your Dockerfile to get it under this limit
+ 
+**Resources**
+* See [best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
 
 ### *Docker build context issues*
+### Missing Docker build context location
+<!--issueDescription-->
+**Potential causes:**
+* You didn't provide the path of your build context directory in your environment definition
+
+**Affected areas (symptoms):**
+* Failure in registering your environment
+<!--/issueDescription-->
+
+**Troubleshooting steps**
+
+*Applies to: Python SDK v1 (Deprecated)*
+
+Include a path in the `build_context` of your [DockerSection](https://aka.ms/azureml/environment/docker-section-class)
+* See [DockerBuildContext Class](/python/api/azureml-core/azureml.core.environment.dockerbuildcontext)
+
+*Applies to: Azure CLI & Python SDK v2*
+
+Ensure that you include a path for your build context
+* See [BuildContext class](https://aka.ms/azureml/environment/build-context-class)
+* See this [sample](https://aka.ms/azureml/environment/create-env-build-context-v2)
+
+**Resources**
+* [Understand build context](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#understand-build-context)
+
 ### Missing Dockerfile path
-- In the Docker build context, a Dockerfile path must be specified
-- The path should be relative to the root of the Docker build context directory
-- See [Build Context class](https://aka.ms/azureml/environment/build-context-class)
+<!--issueDescription-->
+This issue can happen when AzureML fails to find your Dockerfile. As a default, AzureML will look for a Dockerfile named 'Dockerfile' at the root of your build context directory unless a Dockerfile path is specified.
+
+**Potential causes:**
+* Your Dockerfile isn't at the root of your build context directory and/or is named something other than 'Dockerfile,' and you didn't provide its path
+
+**Affected areas (symptoms):**
+* Failure in registering your environment
+<!--/issueDescription-->
+
+**Troubleshooting steps**
+
+*Applies to: Python SDK v1 (Deprecated)*
+
+In the `build_context` of your [DockerSection](https://aka.ms/azureml/environment/docker-section-class), include a `dockerfile_path`
+* See [DockerBuildContext Class](/python/api/azureml-core/azureml.core.environment.dockerbuildcontext)
+
+*Applies to: Azure CLI & Python SDK v2*
+
+Specify a Dockerfile path
+* [See BuildContext class](https://aka.ms/azureml/environment/build-context-class)
+* See this [sample](https://aka.ms/azureml/environment/create-env-build-context-v2)
+
+**Resources**
+* [Understand build context](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#understand-build-context)
 
 ### Not allowed to specify attribute with Docker build context
-- If a Docker build context is specified, then the following items can't also be specified in the
-environment definition:
-    - Environment variables
-    - Conda dependencies
-    - R
-    - Spark 
+<!--issueDescription-->
+This issue can happen when you've specified properties in your environment definition that can't be included with a Docker build context.
+
+**Potential causes:**
+* You specified a Docker build context, along with at least one of the following in your environment definition:
+	* Environment variables
+	* Conda dependencies
+	* R
+	* Spark
+
+**Affected areas (symptoms):**
+* Failure in registering your environment
+<!--/issueDescription-->
+
+**Troubleshooting steps**
+
+*Applies to: Python SDK v1 (Deprecated)*
+
+If any of the above-listed properties are specified in your environment definition, remove them
+* If you're using a Docker build context and want to specify conda dependencies, your conda specification should reside in your build context directory
+
+**Resources**
+* [Understand build context](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#understand-build-context)
+* Python SDK v1 [Environment Class](https://aka.ms/azureml/environment/environment-class-v1)
 
 ### Location type not supported/Unknown location type
 - The following are accepted location types:
@@ -644,7 +717,7 @@ This issue can happen by failing to access a workspace's associated Azure Contai
 
 **Troubleshooting steps**
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1*
 
 Update the workspace image build compute property using SDK:
 
@@ -654,7 +727,7 @@ ws = Workspace.from_config()
 ws.update(image_build_compute = 'mycomputecluster')
 ```
 
-*Applies to: Azure CLI extensions V1 & V2*
+*Applies to: Azure CLI extensions v1 & v2*
 
 Update the workspace image build compute property using Azure CLI:
 
@@ -1004,15 +1077,15 @@ because you can't provide interactive authentication during a build
 
 Provide authentication via workspace connections
 
-*Applies to: Python SDK azureml V1*
+*Applies to: Python SDK v1*
 
 ```
 from azureml.core import Workspace
 ws = Workspace.from_config()
 ws.set_connection("connection1", "PythonFeed", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")
 ```
 
-*Applies to: Azure CLI extensions V1 & V2*
+*Applies to: Azure CLI extensions v1 & v2*
 
 Create a workspace connection from a YAML specification file
 
@@ -1021,8 +1094,8 @@ az ml connection create --file connection.yml --resource-group my-resource-group
 ```
 
 **Resources**
-* [Python SDK AzureML v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
-* [Python SDK AzureML v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
+* [Python SDK v1 workspace connections](https://aka.ms/azureml/environment/set-connection-v1)
+* [Python SDK v2 workspace connections](/python/api/azure-ai-ml/azure.ai.ml.entities.workspaceconnection)
 * [Azure CLI workspace connections](/cli/azure/ml/connection)
 
 ### Forbidden blob