updates for endpoint versions

Author: Larry Franks

articles/machine-learning/how-to-deploy-azure-kubernetes-service.md

@@ -228,10 +228,28 @@ For information on using VS Code, see [deploy to AKS via the VS Code extension](
 > Deploying through VS Code requires the AKS cluster to be created or attached to your workspace in advance.
 
 ## Deploy models to AKS using controlled rollout (preview)
-Analyze and promote model versions in a controlled fashion using endpoints. Deploy up to 6 versions behind a single endpoint and configure the % of scoring traffic to each deployed version. You can enable app insights to view operational metrics of endpoints and deployed versions.
+
+Analyze and promote model versions in a controlled fashion using endpoints. You can deploy up to six versions behind a single endpoint. Endpoints provide the following capabilities:
+
+* Configure the __percentage of scoring traffic sent to each endpoint__. For example, route 20% of the traffic to endpoint 'test' and 80% to 'production'.
+
+    > [!NOTE]
+    > If you do not account for 100% of the traffic, any remaining percentage is routed to the __default__ endpoint. For example, if you configure endpoint 'test' to get 10% of the traffic, the remaining 90% is sent to the default endpoint.
+    >
+    > The first endpoint created is automatically configured as the default. You can change this by setting `is_default=True` when creating or updating an endpoint version.
+     
+* Tag an endpoint as either __control__ or __treatment__. For example, the current production endpoint might be the control, while potential new models are deployed as treatments. After evaluating performance of the treatment endpoints, if one outperforms the current control, it might be promoted to the new production/control.
+
+    > [!NOTE]
+    > You can only have __one__ control endpoint. You can have multiple treatments.
+
+You can enable app insights to view operational metrics of endpoints and deployed versions.
 
 ### Create an endpoint
-Once you are ready to deploy your models, create a scoring endpoint and deploy your first version. The step below shows you how to deploy and create the endpoint using the SDK. The first deployment will be defined as the default version which means that unspecified traffic percentile across all versions will go to the default version.  
+Once you are ready to deploy your models, create a scoring endpoint and deploy your first version. The following example shows how to deploy and create the endpoint using the SDK. The first deployment will be defined as the default version, which means that unspecified traffic percentile across all versions will go to the default version.  
+
+> [!TIP]
+> In the following example, the configuration sets this endpoint to handle 20% of the traffic. Since this is the first endpoint, it's also the default endpoint. And since we don't have any other endpoints for the other 80% of traffic, it is routed to the default endpoint. Until other endpoints that take a percentage of traffic are deployed, this one effectively receives 100% of the traffic.
 
 ```python
 import azureml.core,
@@ -242,8 +260,8 @@ from azureml.core.compute import ComputeTarget
 compute = ComputeTarget(ws, 'myaks')
 namespace_name= endpointnamespace
 # define the endpoint and version name
-endpoint_name = "mynewendpoint",
-version_name= "versiona",
+endpoint_name = "mynewendpoint"
+version_name= "versiona"
 # create the deployment config and define the scoring traffic percentile for the first deployment
 endpoint_deployment_config = AksEndpoint.deploy_configuration(cpu_cores = 0.1, memory_gb = 0.2,
                                                               enable_app_insights = True,
@@ -253,11 +271,16 @@ endpoint_deployment_config = AksEndpoint.deploy_configuration(cpu_cores = 0.1, m
                                                               traffic_percentile = 20)
  # deploy the model and endpoint
  endpoint = Model.deploy(ws, endpoint_name, [model], inference_config, endpoint_deployment_config, compute)
+ # Wait for he process to complete
+ endpoint.wait_for_deployment(True)
  ```
 
 ### Update and add versions to an endpoint
 
-Add another version to your endpoint and configure the scoring traffic percentile going to the version. There are two types of versions, a control and a treatment version. There can be multiple treatment version to help compare against a single control version.
+Add another version to your endpoint and configure the scoring traffic percentile going to the version. There are two types of versions, a control and a treatment version. There can be multiple treatment versions to help compare against a single control version.
+
+> [!TIP]
+> The previous endpoint is set to receive 20% of the traffic. It's also the default, so it gets any leftover traffic not handled by other endpoints. The second endpoint version created by the next code snippet accepts 10% of traffic. After it is created, the first endpoint version is configured for 20% of the traffic and the new version for 10%. The remaining 70% is sent to the first endpoint version, because it is also the default version.
 
  ```python
 from azureml.core.webservice import AksEndpoint
@@ -270,9 +293,13 @@ endpoint.create_version(version_name = version_name_add,
                         tags = {'modelVersion':'b'},
                         description = "my second version",
                         traffic_percentile = 10)
+endpoint.wait_for_deployment(True)
 ```
 
-Update existing versions or delete them in an endpoint. You can change the version's default type, control type, and the traffic percentile.
+Update existing versions or delete them in an endpoint. You can change the version's default type, control type, and the traffic percentile. In the following example, the second version increases its traffic to 40% and is now the default.
+
+> [!TIP]
+> Since the second version is now default, and is configured for 40%, while the original version is configured for 20%. This means that 40% of traffic is not accounted for by version configurations, and will also be routed to the second version. It effectively receives 80% of the traffic.
 
  ```python
 from azureml.core.webservice import AksEndpoint
@@ -283,7 +310,8 @@ endpoint.update_version(version_name=endpoint.versions["versionb"].name,
                         traffic_percentile=40,
                         is_default=True,
                         is_control_version_type=True)
-
+# Wait for the process to complete before deleting
+endpoint.wait_for_deployment(true)
 # delete a version in an endpoint
 endpoint.delete_version(version_name="versionb")