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-..`. The targets for `bar` and `baz` can only be accessed using the main route, `..`. + +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-` 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.