From eae58fbd30882787bc2e11da9cff904b0fd7df7c Mon Sep 17 00:00:00 2001
From: Andrew Su <2027679+andrew-su@users.noreply.github.com>
Date: Fri, 14 Feb 2020 17:12:41 -0500
Subject: [PATCH] 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              |  1 +
 docs/serving/cluster-local-route.md | 14 +++++++++--
 docs/serving/using-subroutes.md     | 38 +++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 docs/serving/using-subroutes.md

diff --git a/docs/serving/README.md b/docs/serving/README.md
index cfed6e1f7..11f722726 100644
--- a/docs/serving/README.md
+++ b/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
 
diff --git a/docs/serving/cluster-local-route.md b/docs/serving/cluster-local-route.md
index bf0d2e7ab..02c5baa25 100644
--- a/docs/serving/cluster-local-route.md
+++ b/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
-object.
+`serving.knative.dev/visibility=cluster-local` label to the KService, Route or 
+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:
 
diff --git a/docs/serving/using-subroutes.md b/docs/serving/using-subroutes.md
new file mode 100644
index 000000000..8ea38fa86
--- /dev/null
+++ b/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.