knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Dan Gerdesmeier 2019-03-15 13:06:46 -07:00 committed by Knative Prow Robot
parent 5c55756268
commit 1a8a63dbff
6 changed files with 255 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
serving/samples/rest-api-go/README.md
View File

@ -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,7 +38,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 +46,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,31 +67,25 @@ 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:
```
docker push "${REPO}/serving/samples/rest-api-go"
```shell
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`:
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`.
- 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:
```
perl -pi -e "s@github.com/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
@ -96,7 +93,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,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,7 +209,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 +217,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 +225,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 +242,6 @@ between multiple Revisions.
To clean up the sample Service:
```
```shell
kubectl delete --filename serving/samples/rest-api-go/sample.yaml
```

7
serving/samples/rest-api-go/sample.yaml → serving/samples/rest-api-go/sample-template.yaml
View File

@ -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

211
serving/samples/traffic-splitting/README.md
View File

@ -1,138 +1,165 @@
# 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:
```shell
cd $GOPATH/src/github.com/knative/docs
```
## Updating to Release Mode
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.
This first step will update the Service to release mode with a single Revision.
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.
```shell
REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" -o \
jsonpath="{.items[*].metadata.name}"))
echo ${REVISIONS[*]}
```
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.
- 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.
```shell
CURRENT=${REVISIONS[0]} \
envsubst < serving/samples/traffic-splitting/release_sample.yaml \
| 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 --output yaml
```
## Updating the Service
This section describes how to create an revision by deploying a new
configuration.
This section describes how to create a new Revision by updating your Service.
1. Replace the image reference path with our published image path in the
configuration files
(`serving/samples/traffic-splitting/updated_configuration.yaml`:
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.
- Manually replace:
`image: github.com/knative/docs/serving/samples/rest-api-go` with
`image: <YOUR_CONTAINER_REGISTRY>/serving/samples/rest-api-go`
For comparison, you can diff the `release_sample.yaml` with the `updated_sample.yaml`.
Or
- Use run this command:
```
perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/rest-api-go/updated_configuration.yaml
```
2. Deploy the new configuration to update the `RESOURCE` environment variable
from `stock` to `share`:
```
kubectl apply --filename serving/samples/traffic-splitting/updated_configuration.yaml
```shell
diff serving/samples/traffic-splitting/release_sample.yaml \
serving/samples/traffic-splitting/updated_sample.yaml
```
3. Once deployed, traffic will shift to the new revision automatically. Verify
the deployment by checking the route status:
1. Execute the command below to update the environment variable in the Service
resulting in a new Revision.
```
kubectl get route --output yaml
```shell
CURRENT=${REVISIONS[0]} \
envsubst < serving/samples/traffic-splitting/updated_sample.yaml \
| kubectl apply --filename -
```
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:
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:
```
export SERVICE_HOST=`kubectl get route stock-route-example --output jsonpath="{.status.domain}"`
# In Knative 0.2.x and prior versions, the `knative-ingressgateway` service was used instead of `istio-ingressgateway`.
INGRESSGATEWAY=knative-ingressgateway
# 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
export SERVICE_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \
--output jsonpath="{.status.loadBalancer.ingress[*].ip}"`
```shell
kubectl get ksvc stock-service-example --output yaml
```
- Make a request to the index endpoint:
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}
```shell
curl --header "Host:latest.${SERVICE_HOSTNAME}" http://${INGRESS_IP}
```
Response body: `Welcome to the share app!`
- Hitting the top domain (or `current.`) will hit the Revision at the first
index of the `revisions` list:
- Make a request to the `/share` endpoint:
```
curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share
```shell
curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP}
curl --header "Host:current.${SERVICE_HOSTNAME}" http://${INGRESS_IP}
```
Response body: `share ticker not found!, require /share/{ticker}`
## Traffic Splitting
- Make a request to the `/share` endpoint with a `ticker` parameter:
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.
```
curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share/<ticker>
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" --output \
jsonpath="{.items[*].metadata.name}"))
echo ${REVISIONS[*]}
```
Response body: `share price for ticker <ticker> is <price>`
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.
## Manual Traffic Splitting
This section describes how to manually split traffic to specific revisions.
1. Get your revisions names via:
```
kubectl get revisions
```shell
CURRENT=${REVISIONS[0]} CANDIDATE=${REVISIONS[1]} \
envsubst < serving/samples/traffic-splitting/split_sample.yaml \
| kubectl apply --filename -
```
```
NAME AGE
stock-configuration-example-00001 11m
stock-configuration-example-00002 4m
3. Verify the deployment by checking the service status:
```shell
kubectl get ksvc --output yaml
```
2. Update the `traffic` list in `serving/samples/rest-api-go/sample.yaml` as:
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!`.
```yaml
traffic:
- revisionName: <YOUR_FIRST_REVISION_NAME>
percent: 50
- revisionName: <YOUR_SECOND_REVISION_NAME>
percent: 50
```shell
curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP}
```
3. Deploy your traffic revision:
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}
```
kubectl apply --filename serving/samples/rest-api-go/sample.yaml
```
4. Verify the deployment by checking the route status:
```
kubectl get route --output yaml
```
Once updated, you can make `curl` requests to the API using either `stock` or
`share` endpoints.
## 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
```

38
serving/samples/traffic-splitting/updated_configuration.yaml → serving/samples/traffic-splitting/release_sample.yaml
View File

@ -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}/rest-api-go
env:
- name: RESOURCE
value: stock
readinessProbe:
httpGet:
path: /
initialDelaySeconds: 0
periodSeconds: 3

36
serving/samples/traffic-splitting/split_sample.yaml Normal file
View File

@ -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}/rest-api-go
env:
- name: RESOURCE
value: share
readinessProbe:
httpGet:
path: /
initialDelaySeconds: 0
periodSeconds: 3

35
serving/samples/traffic-splitting/updated_sample.yaml Normal file
View File

@ -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}/rest-api-go
env:
- name: RESOURCE
value: share
readinessProbe:
httpGet:
path: /
initialDelaySeconds: 0
periodSeconds: 3