From 2087d8f73a4637d9ca78227e8424215062e4a6d9 Mon Sep 17 00:00:00 2001
From: Dan Gerdesmeier <dangerd@google.com>
Date: Fri, 15 Feb 2019 21:25:03 +0000
Subject: [PATCH 1/5] 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.
---
 serving/samples/rest-api-go/README.md         |  74 ++++---
 serving/samples/traffic-splitting/README.md   | 190 ++++++++++--------
 ...configuration.yaml => release_sample.yaml} |  38 ++--
 .../traffic-splitting/split_sample.yaml       |  36 ++++
 .../traffic-splitting/updated_sample.yaml     |  35 ++++
 5 files changed, 239 insertions(+), 134 deletions(-)
 rename serving/samples/traffic-splitting/{updated_configuration.yaml => release_sample.yaml} (52%)
 create mode 100644 serving/samples/traffic-splitting/split_sample.yaml
 create mode 100644 serving/samples/traffic-splitting/updated_sample.yaml

diff --git a/serving/samples/rest-api-go/README.md b/serving/samples/rest-api-go/README.md
index edca5d7086f..5f6c3bb4d48 100644
--- a/serving/samples/rest-api-go/README.md
+++ b/serving/samples/rest-api-go/README.md
@@ -15,7 +15,7 @@ then outputs the stock price.
    enabled for this Service to make external API requests.
 1. The code checked out locally.
 
-```
+```shell
 go get -d github.com/knative/docs/serving/samples/rest-api-go
 ```
 
@@ -35,7 +35,7 @@ To build and push to a container registry using Docker:
 
 1. Move into the sample directory:
 
-```
+```shell
 cd $GOPATH/src/github.com/knative/docs
 ```
 
@@ -43,7 +43,7 @@ cd $GOPATH/src/github.com/knative/docs
    This sample uses
    [Google Container Registry (GCR)](https://cloud.google.com/container-registry/):
 
-```
+```shell
 export REPO="gcr.io/<YOUR_PROJECT_ID>"
 ```
 
@@ -64,7 +64,7 @@ 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" \
   --file serving/samples/rest-api-go/Dockerfile .
@@ -72,7 +72,7 @@ docker build \
 
 5. Push your container to a container registry:
 
-```
+```shell
 docker push "${REPO}/serving/samples/rest-api-go"
 ```
 
@@ -87,7 +87,7 @@ docker push "${REPO}/serving/samples/rest-api-go"
 
    - Use run this command:
 
-   ```
+   ```shell
    perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/rest-api-go/sample.yaml
    ```
 
@@ -96,7 +96,7 @@ docker push "${REPO}/serving/samples/rest-api-go"
 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,43 +117,43 @@ You can inspect the created resources with the following `kubectl` commands:
 
 - View the created Service resource:
 
-```
-kubectl get ksvc stock-service-example --output yaml
+```shell
+kubectl get ksvc stock-service-example -o yaml
 ```
 
 - View the created Route resource:
 
-```
-kubectl get route -l
-"serving.knative.dev/service=stock-service-example" --output yaml
+```shell
+kubectl get route -l \
+"serving.knative.dev/service=stock-service-example" -o yaml
 ```
 
 - View the Kubernetes Service created by the Route
 
-```
-kubectl get service -l
-"serving.knative.dev/service=stock-service-example" --output yaml
+```shell
+kubectl get service -l \
+"serving.knative.dev/service=stock-service-example" -o yaml
 ```
 
 - View the created Configuration resource:
 
-```
-kubectl get configuration -l
-"serving.knative.dev/service=stock-service-example" --output yaml
+```shell
+kubectl get configuration -l \
+"serving.knative.dev/service=stock-service-example" -o yaml
 ```
 
 - View the Revision that was created by our Configuration:
 
-```
-kubectl get revision -l
-"serving.knative.dev/service=stock-service-example" --output yaml
+```shell
+kubectl get revision -l \
+"serving.knative.dev/service=stock-service-example" -o yaml
 ```
 
 - View the Deployment created by our Revision
 
-```
-kubectl get deployment -l
-"serving.knative.dev/service=stock-service-example" --output yaml
+```shell
+kubectl get deployment -l \
+"serving.knative.dev/service=stock-service-example" -o yaml
 ```
 
 ## Access the Service
@@ -163,9 +163,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 +178,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,7 +212,7 @@ 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}
 ```
 
@@ -210,7 +220,7 @@ Response body: `Welcome to the stock app!`
 
 - Make a request to the `/stock` endpoint:
 
-```
+```shell
 curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock
 ```
 
@@ -218,7 +228,7 @@ 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 +245,6 @@ between multiple Revisions.
 
 To clean up the sample Service:
 
-```
+```shell
 kubectl delete --filename serving/samples/rest-api-go/sample.yaml
 ```
diff --git a/serving/samples/traffic-splitting/README.md b/serving/samples/traffic-splitting/README.md
index d0c8c35effc..e70e90c9cb4 100644
--- a/serving/samples/traffic-splitting/README.md
+++ b/serving/samples/traffic-splitting/README.md
@@ -1,138 +1,164 @@
 # Simple Traffic Splitting Between Revisions
 
-This samples builds off the [Creating a RESTful Service](../rest-api-go) sample
-to illustrate applying a revision, then using that revision for manual traffic
-splitting.
+This samples builds off of the [Creating a RESTful Service](../rest-api-go) sample
+to illustrate updating a Service to create a new Revision as well as splitting traffic
+between the two created Revisions.
 
 ## Prerequisites
 
-1. [Creating a RESTful Service](../rest-api-go).
+1. Complete the Service creation steps in [Creating a RESTful Service](../rest-api-go).
+1. Move into the docs directory:
 
-## Updating the Service
+```shell
+cd $GOPATH/src/github.com/knative/docs
+```
 
-This section describes how to create an revision by deploying a new
-configuration.
+## Updating to Release Mode
 
-1. Replace the image reference path with our published image path in the
-   configuration files
-   (`serving/samples/traffic-splitting/updated_configuration.yaml`:
+The service was originally created with a mode of `runLatest`. In `runLatest`
+mode, the service serves the latest Revision that is ready to handle incoming
+traffic. To split traffic between multiple Revisions, the Service mode will need
+to be changed to `release` mode. The `release` mode differs from `runLatest` in that
+it requires a `revisions` list. The `revisions` list accepts 1 or 2 Revisions
+that will be served by the base domain of the service. When 2 Revisions are
+present in the list a `rolloutPercent` parameter specifies the percentage of
+traffic to send to each Revision.
 
-   - Manually replace:
-     `image: github.com/knative/docs/serving/samples/rest-api-go` with
-     `image: <YOUR_CONTAINER_REGISTRY>/serving/samples/rest-api-go`
+This first step will update the Service to release mode with a single Revision.
 
-   Or
+1. To populate the `revisions` list the name of the created Revision is required.
+The command below captures the names of all created Revisions as an array so it
+can be substituted it into the YAML.
 
-   - Use run this command:
+```shell
+REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" -o \
+jsonpath="{.items[*].metadata.name}"))
+echo ${REVISIONS[*]}
+```
 
-   ```
-   perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/rest-api-go/updated_configuration.yaml
-   ```
+2. The `release_sample.yaml` is setup in this directory to allow enable substituting the
+Revision name into the file with the `envsubst` utility. Executing the
+command below will update the Service to release mode with the queried Revision name.
 
-2. Deploy the new configuration to update the `RESOURCE` environment variable
-   from `stock` to `share`:
+- Note: The command below expects `$REPO` to still be exported. See
+  [RESTful Service Setup](https://github.com/knative/docs/tree/master/serving/samples/rest-api-go#setup) to set it.
 
-```
-kubectl apply --filename serving/samples/traffic-splitting/updated_configuration.yaml
+```shell
+CURRENT=${REVISIONS[0]} \
+envsubst < serving/samples/traffic-splitting/release_sample.yaml \
+| kubectl apply -f -
 ```
 
-3. Once deployed, traffic will shift to the new revision automatically. Verify
-   the deployment by checking the route status:
+3. The `spec` of the Service should now show `release` with the Revision name
+retrieved above.
 
-```
-kubectl get route --output yaml
+```shell
+kubectl get ksvc stock-service-example -oyaml
 ```
 
-4. When the new route is ready, you can access the new endpoints: The hostname
-   and IP address can be found in the same manner as the
-   [Creating a RESTful Service](../rest-api-go) sample:
+## Updating the Service
 
-```
-export SERVICE_HOST=`kubectl get route stock-route-example --output jsonpath="{.status.domain}"`
+This section describes how to create a new Revision by updating your Service.
 
-# In Knative 0.2.x and prior versions, the `knative-ingressgateway` service was used instead of `istio-ingressgateway`.
-INGRESSGATEWAY=knative-ingressgateway
+A new Revision is created every time a value in the `revisionTemplate` section of
+the Service `spec` is updated. The `updated_sample.yaml` in this folder changes
+the environment variable `RESOURCE` from `stock` to `share`. Applying this
+change will result in a new Revision.
 
-# The use of `knative-ingressgateway` is deprecated in Knative v0.3.x.
-# Use `istio-ingressgateway` instead, since `knative-ingressgateway`
-# will be removed in Knative v0.4.
-if kubectl get configmap config-istio -n knative-serving &> /dev/null; then
-    INGRESSGATEWAY=istio-ingressgateway
-fi
+For comparison, you can diff the `release_sample.yaml` with the `updated_sample.yaml`.
 
-export SERVICE_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \
-    --output jsonpath="{.status.loadBalancer.ingress[*].ip}"`
+```shell
+diff release_sample.yaml updated_sample.yaml
 ```
 
-- Make a request to the index endpoint:
+1.  Execute the command below to update the environment variable in the Service
+    resulting in a new Revision.
 
+```shell
+CURRENT=${REVISIONS[0]} \
+envsubst < serving/samples/traffic-splitting/updated_sample.yaml \
+| kubectl apply -f -
 ```
-curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}
-```
-
-Response body: `Welcome to the share app!`
 
-- Make a request to the `/share` endpoint:
+2. Since we are using a `release` service, traffic will _not_ shift to the new
+   Revision automatically. However, it will be available from the subdomain
+   `latest`. This can be verified through the Service status:
 
+```shell
+kubectl get ksvc stock-service-example --output yaml
 ```
-curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share
-```
-
-Response body: `share ticker not found!, require /share/{ticker}`
 
-- Make a request to the `/share` endpoint with a `ticker` parameter:
+3. The readiness of the Service can be verified through the Service Conditions.
+   When the Service conditions report it is ready again, you can access the new
+   Revision using the same method as found in the [previous sample](../rest-api-go/README.md#access-the-service)
+   by prefixing the Service hostname with `latest.`.
 
-```
-curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share/<ticker>
+```shell
+curl --header "Host:latest.${SERVICE_HOSTNAME}" http://${INGRESS_IP}
 ```
 
-Response body: `share price for ticker <ticker> is <price>`
+- Hitting the top domain (or `current.`) will hit the Revision at the first
+  index of the `revisions` list:
 
-## Manual Traffic Splitting
+```shell
+curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP}
+curl --header "Host:current.${SERVICE_HOSTNAME}" http://${INGRESS_IP}
+```
 
-This section describes how to manually split traffic to specific revisions.
+## Traffic Splitting
 
-1. Get your revisions names via:
+Updating the service to split traffic between the two revisions is done by
+placing a second revision in of the `revisions` list and specifying a `rolloutPercent`.
+The `rolloutPercent` is the percentage of traffic to send to the second element in
+the list. When the Service is Ready the traffic will be split as desired for the
+base domain, and a subdomain of `candidate` will be available pointing to the
+second Revision.
 
-```
-kubectl get revisions
-```
+1. Get the latest list of revisions by executing the command below:
 
+```shell
+REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" -o \
+jsonpath="{.items[*].metadata.name}"))
+echo ${REVISIONS[*]}
 ```
-NAME                                AGE
-stock-configuration-example-00001   11m
-stock-configuration-example-00002   4m
-```
 
-2. Update the `traffic` list in `serving/samples/rest-api-go/sample.yaml` as:
+2. Update the `revisions` list in
+   `serving/samples/traffic-splitting/split_sample.yaml`. A `rolloutPercent` of
+   50 has already been specified, but can be changed if desired by editing the
+   `split_sample.yaml` file.
+
 
-```yaml
-traffic:
-  - revisionName: <YOUR_FIRST_REVISION_NAME>
-    percent: 50
-  - revisionName: <YOUR_SECOND_REVISION_NAME>
-    percent: 50
+```shell
+CURRENT=${REVISIONS[0]} CANDIDATE=${REVISIONS[1]} \
+envsubst < serving/samples/traffic-splitting/split_sample.yaml \
+| kubectl apply -f -
 ```
 
-3. Deploy your traffic revision:
+3. Verify the deployment by checking the service status:
 
-```
-kubectl apply --filename serving/samples/rest-api-go/sample.yaml
+```shell
+kubectl get ksvc --output yaml
 ```
 
-4. Verify the deployment by checking the route status:
+4. Once updated, `curl` requests to the base domain should result in responses split evenly between `Welcome to the share app!` and
+`Welcome to the stock app!`.
 
-```
-kubectl get route --output yaml
+```shell
+curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP}
 ```
 
-Once updated, you can make `curl` requests to the API using either `stock` or
-`share` endpoints.
+5. Much like the `current` and `latest` subdomains there should now be a
+`candidate` subdomain that should return `Welcome to the share app!` as it hits
+the second index of the `revisions` list.
+
+```shell
+curl --header "Host:candidate.${SERVICE_HOSTNAME}" http://${INGRESS_IP}
+```
 
 ## Clean Up
 
 To clean up the sample service:
 
-```
-kubectl delete --filename serving/samples/traffic-splitting/updated_configuration.yaml
+```shell
+kubectl delete --filename serving/samples/traffic-splitting/split_sample.yaml
 ```
diff --git a/serving/samples/traffic-splitting/updated_configuration.yaml b/serving/samples/traffic-splitting/release_sample.yaml
similarity index 52%
rename from serving/samples/traffic-splitting/updated_configuration.yaml
rename to serving/samples/traffic-splitting/release_sample.yaml
index a57bf5b1cf8..18b64000860 100644
--- a/serving/samples/traffic-splitting/updated_configuration.yaml
+++ b/serving/samples/traffic-splitting/release_sample.yaml
@@ -1,4 +1,4 @@
-# Copyright 2018 The Knative Authors
+# Copyright 2019 The Knative Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,25 +13,23 @@
 # limitations under the License.
 
 apiVersion: serving.knative.dev/v1alpha1
-kind: Configuration
+kind: Service
 metadata:
-  name: stock-configuration-example
+  name: stock-service-example
   namespace: default
 spec:
-  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
-        env:
-          - name: RESOURCE
-            value: share
-        readinessProbe:
-          httpGet:
-            path: /
-          initialDelaySeconds: 3
-          periodSeconds: 3
+ release:
+  revisions: ["${CURRENT}"]
+  configuration:
+    revisionTemplate:
+      spec:
+        container:
+          image: ${REPO}/serving/samples/rest-api-go
+          env:
+            - name: RESOURCE
+              value: stock
+          readinessProbe:
+            httpGet:
+              path: /
+            initialDelaySeconds: 0
+            periodSeconds: 3
diff --git a/serving/samples/traffic-splitting/split_sample.yaml b/serving/samples/traffic-splitting/split_sample.yaml
new file mode 100644
index 00000000000..8cd27016e67
--- /dev/null
+++ b/serving/samples/traffic-splitting/split_sample.yaml
@@ -0,0 +1,36 @@
+# Copyright 2019 The Knative Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: serving.knative.dev/v1alpha1
+kind: Service
+metadata:
+  name: stock-service-example
+  namespace: default
+spec:
+ release:
+  revisions: [ "${CURRENT}", "${CANDIDATE}"]
+  rolloutPercent: 50
+  configuration:
+    revisionTemplate:
+      spec:
+        container:
+          image: ${REPO}/serving/samples/rest-api-go
+          env:
+            - name: RESOURCE
+              value: share
+          readinessProbe:
+            httpGet:
+              path: /
+            initialDelaySeconds: 0
+            periodSeconds: 3
diff --git a/serving/samples/traffic-splitting/updated_sample.yaml b/serving/samples/traffic-splitting/updated_sample.yaml
new file mode 100644
index 00000000000..b0587e2355f
--- /dev/null
+++ b/serving/samples/traffic-splitting/updated_sample.yaml
@@ -0,0 +1,35 @@
+# Copyright 2019 The Knative Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: serving.knative.dev/v1alpha1
+kind: Service
+metadata:
+  name: stock-service-example
+  namespace: default
+spec:
+ release:
+  revisions: ["${CURRENT}"]
+  configuration:
+    revisionTemplate:
+      spec:
+        container:
+          image: ${REPO}/serving/samples/rest-api-go
+          env:
+            - name: RESOURCE
+              value: share
+          readinessProbe:
+            httpGet:
+              path: /
+            initialDelaySeconds: 0
+            periodSeconds: 3

From a99ece3a954c5123653781d8fccd73bc9374142c Mon Sep 17 00:00:00 2001
From: Dan Gerdesmeier <dangerd@google.com>
Date: Thu, 7 Mar 2019 17:43:11 +0000
Subject: [PATCH 2/5] Use envsubst instead of perl. Simplify image path

---
 serving/samples/rest-api-go/README.md         | 20 ++++------
 serving/samples/rest-api-go/sample.yaml       | 38 -------------------
 .../traffic-splitting/release_sample.yaml     |  2 +-
 .../traffic-splitting/split_sample.yaml       |  2 +-
 .../traffic-splitting/updated_sample.yaml     |  2 +-
 5 files changed, 10 insertions(+), 54 deletions(-)
 delete mode 100644 serving/samples/rest-api-go/sample.yaml

diff --git a/serving/samples/rest-api-go/README.md b/serving/samples/rest-api-go/README.md
index 5f6c3bb4d48..4b4ce2cc241 100644
--- a/serving/samples/rest-api-go/README.md
+++ b/serving/samples/rest-api-go/README.md
@@ -66,29 +66,23 @@ registry specific instructions for both setup and authorizing the image push.
 
 ```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}/serving/samples/rest-api-go"
+docker push "${REPO}/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
-
-   - Use run this command:
+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`.
 
    ```shell
-   perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/rest-api-go/sample.yaml
+   envsubst < serving/samples/rest-api-go/sample-template.yaml > \
+   serving/samples/rest-api-go/sample.yaml
    ```
 
 ## Deploy the Service
diff --git a/serving/samples/rest-api-go/sample.yaml b/serving/samples/rest-api-go/sample.yaml
deleted file mode 100644
index 0076b74b93e..00000000000
--- a/serving/samples/rest-api-go/sample.yaml
+++ /dev/null
@@ -1,38 +0,0 @@
-# Copyright 2018 The Knative Authors
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-apiVersion: serving.knative.dev/v1alpha1
-kind: Service
-metadata:
-  name: stock-service-example
-  namespace: default
-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
-            env:
-              - name: RESOURCE
-                value: stock
-            readinessProbe:
-              httpGet:
-                path: /
-              initialDelaySeconds: 0
-              periodSeconds: 3
diff --git a/serving/samples/traffic-splitting/release_sample.yaml b/serving/samples/traffic-splitting/release_sample.yaml
index 18b64000860..3ee2064098e 100644
--- a/serving/samples/traffic-splitting/release_sample.yaml
+++ b/serving/samples/traffic-splitting/release_sample.yaml
@@ -24,7 +24,7 @@ spec:
     revisionTemplate:
       spec:
         container:
-          image: ${REPO}/serving/samples/rest-api-go
+          image: ${REPO}/rest-api-go
           env:
             - name: RESOURCE
               value: stock
diff --git a/serving/samples/traffic-splitting/split_sample.yaml b/serving/samples/traffic-splitting/split_sample.yaml
index 8cd27016e67..191f91803ec 100644
--- a/serving/samples/traffic-splitting/split_sample.yaml
+++ b/serving/samples/traffic-splitting/split_sample.yaml
@@ -25,7 +25,7 @@ spec:
     revisionTemplate:
       spec:
         container:
-          image: ${REPO}/serving/samples/rest-api-go
+          image: ${REPO}/rest-api-go
           env:
             - name: RESOURCE
               value: share
diff --git a/serving/samples/traffic-splitting/updated_sample.yaml b/serving/samples/traffic-splitting/updated_sample.yaml
index b0587e2355f..cd7c866ca96 100644
--- a/serving/samples/traffic-splitting/updated_sample.yaml
+++ b/serving/samples/traffic-splitting/updated_sample.yaml
@@ -24,7 +24,7 @@ spec:
     revisionTemplate:
       spec:
         container:
-          image: ${REPO}/serving/samples/rest-api-go
+          image: ${REPO}/rest-api-go
           env:
             - name: RESOURCE
               value: share

From 91ecf2ec0a9392c49272fd5e91ecd6c281309f57 Mon Sep 17 00:00:00 2001
From: Dan Gerdesmeier <dangerd@google.com>
Date: Thu, 7 Mar 2019 17:48:34 +0000
Subject: [PATCH 3/5] Use long names for arguments

---
 serving/samples/rest-api-go/README.md       | 12 ++++++------
 serving/samples/traffic-splitting/README.md | 10 +++++-----
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/serving/samples/rest-api-go/README.md b/serving/samples/rest-api-go/README.md
index 4b4ce2cc241..b55f23d16b3 100644
--- a/serving/samples/rest-api-go/README.md
+++ b/serving/samples/rest-api-go/README.md
@@ -112,42 +112,42 @@ You can inspect the created resources with the following `kubectl` commands:
 - View the created Service resource:
 
 ```shell
-kubectl get ksvc stock-service-example -o yaml
+kubectl get ksvc stock-service-example --output yaml
 ```
 
 - View the created Route resource:
 
 ```shell
 kubectl get route -l \
-"serving.knative.dev/service=stock-service-example" -o yaml
+"serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Kubernetes Service created by the Route
 
 ```shell
 kubectl get service -l \
-"serving.knative.dev/service=stock-service-example" -o yaml
+"serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the created Configuration resource:
 
 ```shell
 kubectl get configuration -l \
-"serving.knative.dev/service=stock-service-example" -o yaml
+"serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Revision that was created by our Configuration:
 
 ```shell
 kubectl get revision -l \
-"serving.knative.dev/service=stock-service-example" -o yaml
+"serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 - View the Deployment created by our Revision
 
 ```shell
 kubectl get deployment -l \
-"serving.knative.dev/service=stock-service-example" -o yaml
+"serving.knative.dev/service=stock-service-example" --output yaml
 ```
 
 ## Access the Service
diff --git a/serving/samples/traffic-splitting/README.md b/serving/samples/traffic-splitting/README.md
index e70e90c9cb4..89740ab98c2 100644
--- a/serving/samples/traffic-splitting/README.md
+++ b/serving/samples/traffic-splitting/README.md
@@ -46,14 +46,14 @@ command below will update the Service to release mode with the queried Revision
 ```shell
 CURRENT=${REVISIONS[0]} \
 envsubst < serving/samples/traffic-splitting/release_sample.yaml \
-| kubectl apply -f -
+| kubectl apply --filename -
 ```
 
 3. The `spec` of the Service should now show `release` with the Revision name
 retrieved above.
 
 ```shell
-kubectl get ksvc stock-service-example -oyaml
+kubectl get ksvc stock-service-example --output yaml
 ```
 
 ## Updating the Service
@@ -77,7 +77,7 @@ diff release_sample.yaml updated_sample.yaml
 ```shell
 CURRENT=${REVISIONS[0]} \
 envsubst < serving/samples/traffic-splitting/updated_sample.yaml \
-| kubectl apply -f -
+| kubectl apply --filename -
 ```
 
 2. Since we are using a `release` service, traffic will _not_ shift to the new
@@ -117,7 +117,7 @@ second Revision.
 1. Get the latest list of revisions by executing the command below:
 
 ```shell
-REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" -o \
+REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" --output \
 jsonpath="{.items[*].metadata.name}"))
 echo ${REVISIONS[*]}
 ```
@@ -131,7 +131,7 @@ echo ${REVISIONS[*]}
 ```shell
 CURRENT=${REVISIONS[0]} CANDIDATE=${REVISIONS[1]} \
 envsubst < serving/samples/traffic-splitting/split_sample.yaml \
-| kubectl apply -f -
+| kubectl apply --filename -
 ```
 
 3. Verify the deployment by checking the service status:

From 5ded4c5f8de3f5c3688df53ff76a666297da68b0 Mon Sep 17 00:00:00 2001
From: Dan Gerdesmeier <dangerd@google.com>
Date: Thu, 7 Mar 2019 17:56:08 +0000
Subject: [PATCH 4/5] Update diff statement

---
 serving/samples/traffic-splitting/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/serving/samples/traffic-splitting/README.md b/serving/samples/traffic-splitting/README.md
index 89740ab98c2..93170b1309b 100644
--- a/serving/samples/traffic-splitting/README.md
+++ b/serving/samples/traffic-splitting/README.md
@@ -68,7 +68,8 @@ change will result in a new Revision.
 For comparison, you can diff the `release_sample.yaml` with the `updated_sample.yaml`.
 
 ```shell
-diff release_sample.yaml updated_sample.yaml
+diff serving/samples/traffic-splitting/release_sample.yaml \
+serving/samples/traffic-splitting/updated_sample.yaml
 ```
 
 1.  Execute the command below to update the environment variable in the Service

From aaf8f31636776bd7600212ceaee1fbcecd1c1464 Mon Sep 17 00:00:00 2001
From: Dan Gerdesmeier <dangerd@google.com>
Date: Thu, 7 Mar 2019 18:42:38 +0000
Subject: [PATCH 5/5] Add envsubst install instructions

---
 serving/samples/rest-api-go/README.md         |  3 ++
 .../samples/rest-api-go/sample-template.yaml  | 33 +++++++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 serving/samples/rest-api-go/sample-template.yaml

diff --git a/serving/samples/rest-api-go/README.md b/serving/samples/rest-api-go/README.md
index b55f23d16b3..70c5a7cf65d 100644
--- a/serving/samples/rest-api-go/README.md
+++ b/serving/samples/rest-api-go/README.md
@@ -14,6 +14,9 @@ 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
diff --git a/serving/samples/rest-api-go/sample-template.yaml b/serving/samples/rest-api-go/sample-template.yaml
new file mode 100644
index 00000000000..865f662f036
--- /dev/null
+++ b/serving/samples/rest-api-go/sample-template.yaml
@@ -0,0 +1,33 @@
+# Copyright 2018 The Knative Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+apiVersion: serving.knative.dev/v1alpha1
+kind: Service
+metadata:
+  name: stock-service-example
+  namespace: default
+spec:
+  runLatest:
+    configuration:
+      revisionTemplate:
+        spec:
+          container:
+            image: ${REPO}/rest-api-go
+            env:
+              - name: RESOURCE
+                value: stock
+            readinessProbe:
+              httpGet:
+                path: /
+              initialDelaySeconds: 0
+              periodSeconds: 3