Update traffic splitting example to use Release mode (#964)

* Update traffic splitting example to use Release mode

This change updates the traffic splitting example to use release mode
introducing the concepts of the mode in three steps. This change also
simplifies running the commands and removes the need to mutate files on
disk to run through the example.

* Use envsubst instead of perl. Simplify image path

* Use long names for arguments

* Update diff statement

* Add envsubst install instructions

Author: Dan Gerdesmeier

serving/samples/rest-api-go/README.md

@@ -14,8 +14,11 @@ then outputs the stock price.
 1. [Outbound network access](https://github.com/knative/docs/blob/master/serving/outbound-network-access.md)
    enabled for this Service to make external API requests.
 1. The code checked out locally.
+1. `envsubst` installed locally. This is installed by the `gettext` package. If
+   not installed it can be installed by a Linux package manager, or by
+   [Homebrew](https://brew.sh/) on OS X.
 
-```
+```shell
 go get -d github.com/knative/docs/serving/samples/rest-api-go
 ```
 
@@ -35,15 +38,15 @@ To build and push to a container registry using Docker:
 
 1. Move into the sample directory:
 
-```
+```shell
 cd $GOPATH/src/github.com/knative/docs
 ```
 
 2. Set your preferred container registry endpoint as an environment variable.
    This sample uses
    [Google Container Registry (GCR)](https://cloud.google.com/container-registry/):
 
-```
+```shell
 export REPO="gcr.io/<YOUR_PROJECT_ID>"
 ```
 
@@ -64,39 +67,33 @@ registry specific instructions for both setup and authorizing the image push.
 
 4. Use Docker to build your application container:
 
-```
+```shell
 docker build \
-  --tag "${REPO}/serving/samples/rest-api-go" \
+  --tag "${REPO}/rest-api-go" \
   --file serving/samples/rest-api-go/Dockerfile .
 ```
 
 5. Push your container to a container registry:
 
+```shell
+docker push "${REPO}/rest-api-go"
 ```
-docker push "${REPO}/serving/samples/rest-api-go"
-```
-
-6. Replace the image reference path with our published image path in the
-   configuration files (`serving/samples/rest-api-go/sample.yaml`:
-
-   - Manually replace:
-     `image: github.com/knative/docs/serving/samples/rest-api-go` with
-     `image: <YOUR_CONTAINER_REGISTRY>/serving/samples/rest-api-go`
 
-   Or
+6. Substitute the image reference path in the template with our published image
+   path. The command below substitutes using the ${REPO} variable into a new
+   file called `serving/samples/rest-api-go/sample.yaml`.
 
-   - Use run this command:
-
-   ```
-   perl -pi -e "[email protected]/knative/docs@${REPO}@g" serving/samples/rest-api-go/sample.yaml
+   ```shell
+   envsubst < serving/samples/rest-api-go/sample-template.yaml > \
+   serving/samples/rest-api-go/sample.yaml
    ```
 
 ## Deploy the Service
 
 Now that our image is available from the container registry, we can deploy the
 Knative Serving sample:
 
-```
+```shell
 kubectl apply --filename serving/samples/rest-api-go/sample.yaml
 ```
 
@@ -117,42 +114,42 @@ You can inspect the created resources with the following `kubectl` commands:
 
 - View the created Service resource:
 
-```
+```shell
 kubectl get ksvc stock-service-example --output yaml
 ```
 
 - View the created Route resource:
 
-```
-kubectl get route -l
+```shell
+kubectl get route -l \
 "serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Kubernetes Service created by the Route
 
-```
-kubectl get service -l
+```shell
+kubectl get service -l \
 "serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the created Configuration resource:
 
-```
-kubectl get configuration -l
+```shell
+kubectl get configuration -l \
 "serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Revision that was created by our Configuration:
 
-```
-kubectl get revision -l
+```shell
+kubectl get revision -l \
 "serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Deployment created by our Revision
 
-```
-kubectl get deployment -l
+```shell
+kubectl get deployment -l \
 "serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
@@ -163,9 +160,13 @@ This example assumes you are using the default Ingress Gateway setup for
 Knative. If you customized your gateway, you will want to adjust the enviornment
 variables below.
 
+### Find Ingress Gateway IP
+
+#### Cloud Provider
+
 1. To get the IP address of your Ingress Gateway:
 
-```
+```shell
 INGRESSGATEWAY=istio-ingressgateway
 INGRESSGATEWAY_LABEL=istio
 
@@ -174,25 +175,31 @@ export INGRESS_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \
 echo $INGRESS_IP
 ```
 
-- If your cluster is running outside a cloud provider (for example on Minikube),
+#### Minikube
+
+1. If your cluster is running outside a cloud provider (for example on Minikube),
   your services will never get an external IP address, and your INGRESS_IP will
   be empty. In that case, use the istio `hostIP` and `nodePort` as the ingress
   IP:
 
-```
+```shell
 export INGRESS_IP=$(kubectl get po --selector $INGRESSGATEWAY_LABEL=ingressgateway --namespace istio-system \
   --output 'jsonpath={.items[0].status.hostIP}'):$(kubectl get svc $INGRESSGATEWAY --namespace istio-system \
   --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
 echo $INGRESS_IP
 ```
 
+### Get Service Hostname
+
 2. To get the hostname of the Service:
 
-```
+```shell
 export SERVICE_HOSTNAME=`kubectl get ksvc stock-service-example --output jsonpath="{.status.domain}"`
 echo $SERVICE_HOSTNAME
 ```
 
+### Sending Requests
+
 3. Now use `curl` to make a request to the Service:
 
 - Make a request to the index endpoint:
@@ -202,23 +209,23 @@ Gateway uses the host header to route the request to the Service. This example
 passes the host header to skip DNS configuration. If your cluster has DNS
 configured, you can simply curl the DNS name instead of the ingress gateway IP.
 
-```
+```shell
 curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}
 ```
 
 Response body: `Welcome to the stock app!`
 
 - Make a request to the `/stock` endpoint:
 
-```
+```shell
 curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock
 ```
 
 Response body: `stock ticker not found!, require /stock/{ticker}`
 
 - Make a request to the `/stock` endpoint with a `ticker` parameter:
 
-```
+```shell
 curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock/<ticker>
 ```
 
@@ -235,6 +242,6 @@ between multiple Revisions.
 
 To clean up the sample Service:
 
-```
+```shell
 kubectl delete --filename serving/samples/rest-api-go/sample.yaml
 ```

serving/samples/rest-api-go/sample.yaml renamed to serving/samples/rest-api-go/sample-template.yaml

@@ -20,14 +20,9 @@ spec:
   runLatest:
     configuration:
       revisionTemplate:
-        metadata:
-          labels:
-            knative.dev/type: container
         spec:
           container:
-            # This is the Go import path for the binary to containerize
-            # and substitute here.
-            image: github.com/knative/docs/serving/samples/rest-api-go
+            image: ${REPO}/rest-api-go
             env:
               - name: RESOURCE
                 value: stock