docs/serving/samples/rest-api-go

Stock

A simple Restful service for testing purpose. It expose an endpoint, which takes a stock ticker (stock symbol) and output the stock price. It uses the the REST resource name from environment defined in configuration.

Prerequisites

1. Install Knative Serving
2. Install docker

Setup

Build the app container and publish it to your registry of choice:

REPO="gcr.io/<your-project-here>"

# Build and publish the container, run from the root directory.
docker build \
  --tag "${REPO}/serving/samples/rest-api-go" \
  --file=serving/samples/rest-api-go/Dockerfile .
docker push "${REPO}/serving/samples/rest-api-go"

# Replace the image reference with our published image.
perl -pi -e "s@github.com/knative/docs/serving/samples/rest-api-go@${REPO}/serving/samples/rest-api-go@g" serving/samples/rest-api-go/*.yaml

# Deploy the Knative Serving sample
kubectl apply -f serving/samples/rest-api-go/sample.yaml

Exploring

Once deployed, you can inspect the created resources with kubectl commands:

# This will show the route that we created:
kubectl get route -o yaml

# This will show the configuration that we created:
kubectl get configurations -o yaml

# This will show the Revision that was created by our configuration:
kubectl get revisions -o yaml

To access this service via curl, we first need to determine its ingress address:

watch get svc knative-ingressgateway -n istio-system

When the service is ready, you'll see an IP address in the EXTERNAL-IP field:

NAME                     TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                                      AGE
knative-ingressgateway   LoadBalancer   10.23.247.74   35.203.155.229   80:32380/TCP,443:32390/TCP,32400:32400/TCP   2d

Once the ADDRESS gets assigned to the cluster, you can run:

# Put the host name into an environment variable.
export SERVICE_HOST=`kubectl get route stock-route-example -o jsonpath="{.status.domain}"`

# Put the ingress IP into an environment variable.
export SERVICE_IP=`kubectl get svc knative-ingressgateway -n istio-system -o jsonpath="{.status.loadBalancer.ingress[*].ip}"`

If your cluster is running outside a cloud provider (for example on Minikube), your services will never get an external IP address. In that case, use the istio hostIP and nodePort as the service IP:

export SERVICE_IP=$(kubectl get po -l knative=ingressgateway -n istio-system -o 'jsonpath={.items[0].status.hostIP}'):$(kubectl get svc knative-ingressgateway -n istio-system -o 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')

Now curl the service IP as if DNS were properly configured:

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}
# Welcome to the stock app!

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/stock
# stock ticker not found!, require /stock/{ticker}

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/stock/<ticker>
# stock price for ticker <ticker>  is  <price>

Updating

You can update this to a new version. For example, update it with a new configuration.yaml via:

kubectl apply -f serving/samples/rest-api-go/updated_configuration.yaml

Once deployed, traffic will shift to the new revision automatically. You can verify the new version by checking route status:

# This will show the route that we created:
kubectl get route -o yaml

Or curling the service:

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}
# Welcome to the share app!

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share
# share ticker not found!, require /share/{ticker}

curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share/<ticker>
# share price for ticker <ticker>  is  <price>

Manual traffic splitting

You can manually split traffic to specific revisions. Get your revisions names via:

kubectl get revisions

NAME                                AGE
stock-configuration-example-00001   11m
stock-configuration-example-00002   4m

Update traffic part in serving/samples/rest-api-go/sample.yaml as:

traffic:
  - revisionName: <YOUR_FIRST_REVISION_NAME>
    percent: 50
  - revisionName: <YOUR_SECOND_REVISION_NAME>
    percent: 50

Then update your change via:

kubectl apply -f serving/samples/rest-api-go/sample.yaml

Once updated, you can verify the traffic splitting by looking at route status and/or curling the service.

Cleaning up

To clean up the sample service:

kubectl delete -f serving/samples/rest-api-go/sample.yaml