Creating a RESTful Service - Go

This “stock ticker” sample demonstrates how to create and run a simple RESTful service on Knative Serving. The exposed endpoint outputs the stock price for a given “stock symbol”, like AAPL,AMZN, GOOG, MSFT, etc.

Prerequisites

  1. A Kubernetes cluster with Knative Serving installed and DNS configured.

  2. Docker installed locally.

  3. 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 on OS X.

  4. Download a copy of the code:

    git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs
cd knative-docs

Setup

In order to run an application on Knative Serving a container image must be available to fetch from a container registry.

This sample uses Docker for both building and pushing.

To build and push to a container registry using Docker:

  1. From the knative-docs directory, run the following command to set your container registry endpoint as an environment variable.

    This sample uses Google Container Registry (GCR):

    export REPO="gcr.io/<YOUR_PROJECT_ID>"

  2. Set up your container registry to make sure you are ready to push.

    To push to GCR, you need to:

    If you are using a different container registry, you will want to follow the registry specific instructions for both setup and authorizing the image push.

  3. Use Docker to build your application container:

    docker build \
  --tag "${REPO}/rest-api-go" \
  --file docs/serving/samples/rest-api-go/Dockerfile .

  4. Push your container to a container registry:

    docker push "${REPO}/rest-api-go"

  5. 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 docs/serving/samples/rest-api-go/sample.yaml.

    envsubst < docs/serving/samples/rest-api-go/sample-template.yaml > \
docs/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:

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

The above command creates a Knative Service within your Kubernetes cluster in the default namespace.

Explore the Service

The Knative Service creates the following child resources:

  • Knative Route
  • Knative Configuration
  • Knative Revision
  • Kubernetes Deployment
  • Kubernetes Service

You can inspect the created resources with the following kubectl commands:

  • View the created Service resource:

    kubectl get ksvc stock-service-example --output yaml

  • View the created Route resource:

    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 \
"serving.knative.dev/service=stock-service-example" --output yaml

  • View the created Configuration resource:

    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 \
"serving.knative.dev/service=stock-service-example" --output yaml

  • View the Deployment created by our Revision

    kubectl get deployment -l \
"serving.knative.dev/service=stock-service-example" --output yaml

Access the Service

To access this service and run the stock ticker, you first obtain the service URL, and then you run curl commands to send request with your stock symbol.

  1. Get the URL of the service:

    kubectl get ksvc stock-service-example  --output=custom-columns=NAME:.metadata.name,URL:.status.url
NAME                    URL
stock-service-example   http://stock-service-example.default.1.2.3.4.xip.io

  2. Send requests to the service using curl:

    1. Send a request to the index endpoint:

      curl http://stock-service-example.default.1.2.3.4.xip.io

      Response body: Welcome to the stock app!

    2. Send a request to the /stock endpoint:

      curl http://stock-service-example.default.1.2.3.4.xip.io/stock

      Response body: stock ticker not found!, require /stock/{ticker}

    3. Send a request to the /stock endpoint with your “stock symbol":

      curl http://stock-service-example.default.1.2.3.4.xip.io/stock/<SYMBOL>

      where <SYMBOL> is your “stock symbol”.

      Response body: stock price for ticker <SYMBOL> is <PRICE>

      Example

      Request:

      curl http://stock-service-example.default.1.2.3.4.xip.io/stock/FAKE

      Response: stock price for ticker FAKE is 0.00

Next Steps

The traffic splitting example continues from here to walk you through how to create new Revisions and then use traffic splitting between those Revisions.

Clean Up

To clean up the sample Service:

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