Add documentation for subroutes and k8s service visibility tagging (#1827)

* Add documentation for subroutes and k8s service visibility tagging

* Add PR suggestions

docs/serving/README.md

@@ -77,6 +77,7 @@ in the Knative Serving repository.
 - [Configuring cluster local routes](./cluster-local-route.md)
 - [Using a custom domain](./using-a-custom-domain.md)
 - [Assigning a static IP address for Knative on Google Kubernetes Engine](./gke-assigning-static-ip-address.md)
+- [Using subroutes](./using-subroutes.md)
 
 ## Known Issues
 

docs/serving/cluster-local-route.md

@@ -29,8 +29,8 @@ inside the cluster:
 
 To configure a KService to only be available on the cluster-local network (and
 not on the public Internet), you can apply the
-`serving.knative.dev/visibility=cluster-local` label to the KService or Route
+`serving.knative.dev/visibility=cluster-local` label to the KService, Route or 
-object.
+Kubernetes Service object.
 
 To label the KService:
 
@@ -44,6 +44,16 @@ To label a route:
 kubectl label route ${ROUTE_NAME} serving.knative.dev/visibility=cluster-local
 ```
 
+To label a Kubernetes service:
+
+```shell
+kubectl label route ${SERVICE_NAME} serving.knative.dev/visibility=cluster-local
+```
+
+By labeling the Kubernetes service it allows you to restrict visibility in a more
+fine-grained way. See [subroutes](./using-subroutes.md) for information about
+tagged routes.
+
 For example, you can deploy the [Hello World sample](./samples/hello-world/helloworld-go/README.md)
 and then convert it to be an cluster-local service by labeling the service:
 

docs/serving/using-subroutes.md

@@ -0,0 +1,38 @@
+---
+title: "Creating and using Subroutes"
+weight: 20
+type: "docs"
+---
+
+Subroutes are most effective when used with multiple revisions. When defining a Knative service/route, the traffic section of the spec can split between the different revisions. For example:
+
+```yaml
+traffic:
+- percent: 0
+  revisionName: foo
+- percent: 40
+  revisionName: bar
+- percent: 60
+  revisionName: baz
+```
+
+This allows anyone targeting the main route to have a 0% chance of hitting revision `foo`, 40% chance of hitting revision `bar` and 60% chance of hitting revision `baz`.
+
+## Using tags to create target URLs
+
+The spec defines an attribute called `tag`. When a `tag` is applied to a route, an address for the specific traffic target is created.
+
+```yaml
+traffic:
+- percent: 0
+  revisionName: foo
+  tag: staging
+- percent: 40
+  revisionName: bar
+- percent: 60
+  revisionName: baz
+```
+
+In the above example, you can access the staging target by accessing `staging-<route name>.<namespace>.<domain>`. The targets for `bar` and `baz` can only be accessed using the main route, `<route name>.<namespace>.<domain>`.
+
+When a traffic target gets tagged, a new Kubernetes service is created for it so that other services can also access it within the cluster. From the above example, a new Kubernetes service called `staging-<route name>` will be created in the same namespace. This service has the ability to override the visibility of this specific route by applying the label `serving.knative.dev/visibility` with value `cluster-local`. See [cluster local routes](./cluster-local-route.md#label-a-service-to-be-cluster-local) for more information about how to restrict visibility on the specific route.