mirror of https://github.com/knative/docs.git
137 lines
4.6 KiB
Markdown
137 lines
4.6 KiB
Markdown
# Creating a RESTful Service
|
|
|
|
This sample demonstrates creating a simple RESTful service. The exposed endpoint takes a stock ticker (i.e. stock symbol), then outputs the stock price. The endpoint resource name is defined by an environment variable set in the configuration file.
|
|
|
|
## Prerequisites
|
|
|
|
1. A Kubernetes cluster with [Knative Serving](https://github.com/knative/docs/blob/master/install/README.md) installed.
|
|
2. Install [Docker](https://docs.docker.com/get-started/#prepare-your-docker-environment).
|
|
3. You need to [configure outbound network access](https://github.com/knative/docs/blob/master/serving/outbound-network-access.md) because this application makes an external API request.
|
|
4. Check out the code:
|
|
```
|
|
go get -d github.com/knative/docs/serving/samples/rest-api-go
|
|
```
|
|
|
|
## Setup
|
|
|
|
Build the application container and publish it to a container registry:
|
|
|
|
1. Move into the sample directory:
|
|
```
|
|
cd $GOPATH/src/github.com/knative/docs
|
|
```
|
|
|
|
2. Set your preferred container registry:
|
|
```
|
|
export REPO="gcr.io/<YOUR_PROJECT_ID>"
|
|
```
|
|
To run the sample, you need to have a Google Cloud Platform project, and you also need to enable the [Google Container Registry
|
|
API](https://console.cloud.google.com/apis/library/containerregistry.googleapis.com).
|
|
|
|
3. Use Docker to build your application container:
|
|
```
|
|
docker build \
|
|
--tag "${REPO}/serving/samples/rest-api-go" \
|
|
--file serving/samples/rest-api-go/Dockerfile .
|
|
```
|
|
|
|
4. Push your container to a container registry:
|
|
```
|
|
docker push "${REPO}/serving/samples/rest-api-go"
|
|
```
|
|
|
|
5. 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:
|
|
```
|
|
perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/rest-api-go/sample.yaml
|
|
```
|
|
|
|
## Deploy the Configuration
|
|
|
|
Deploy the Knative Serving sample:
|
|
```
|
|
kubectl apply --filename serving/samples/rest-api-go/sample.yaml
|
|
```
|
|
|
|
## Explore the Configuration
|
|
|
|
Inspect the created resources with the `kubectl` commands:
|
|
|
|
* View the created Route resource:
|
|
```
|
|
kubectl get route --output yaml
|
|
```
|
|
|
|
* View the created Configuration resource:
|
|
```
|
|
kubectl get configurations --output yaml
|
|
```
|
|
|
|
* View the Revision that was created by our Configuration:
|
|
```
|
|
kubectl get revisions --output yaml
|
|
```
|
|
|
|
## Access the Service
|
|
|
|
To access this service via `curl`, you need to determine its ingress address.
|
|
|
|
1. To determine if your service is ready:
|
|
```
|
|
kubectl get svc knative-ingressgateway --namespace istio-system --watch
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
2. When the service is ready, export the ingress hostname and IP as environment variables:
|
|
```
|
|
export SERVICE_HOST=`kubectl get route stock-route-example --output jsonpath="{.status.domain}"`
|
|
export SERVICE_IP=`kubectl get svc knative-ingressgateway --namespace istio-system \
|
|
--output 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 --selector knative=ingressgateway --namespace istio-system \
|
|
--output 'jsonpath={.items[0].status.hostIP}'):$(kubectl get svc knative-ingressgateway --namespace istio-system \
|
|
--output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
|
|
```
|
|
|
|
3. Now use `curl` to make a request to the service:
|
|
* Make a request to the index endpoint:
|
|
```
|
|
curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}
|
|
```
|
|
Response body: `Welcome to the stock app!`
|
|
|
|
* Make a request to the `/stock` endpoint:
|
|
```
|
|
curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/stock
|
|
```
|
|
Response body: `stock ticker not found!, require /stock/{ticker}`
|
|
|
|
* Make a request to the `/stock` endpoint with a `ticker` parameter:
|
|
```
|
|
curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/stock/<ticker>
|
|
```
|
|
Response body: `stock price for ticker <ticker> is <price>`
|
|
|
|
|
|
## Clean Up
|
|
|
|
To clean up the sample service:
|
|
```
|
|
kubectl delete --filename serving/samples/rest-api-go/sample.yaml
|
|
```
|