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

Format markdown (#1379) 

Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)`
This commit is contained in:
mattmoor-sockpuppet 2019-05-29 07:28:34 -07:00 committed by Knative Prow Robot
parent dee2bd0751
commit ff9cac1293
1 changed files with 115 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,8 +1,7 @@
This "stock ticker" sample demonstrates how to create and run a simple RESTful service This "stock ticker" sample demonstrates how to create and run a simple RESTful
on Knative Serving. The exposed endpoint outputs the stock price for a given service on Knative Serving. The exposed endpoint outputs the stock price for a
"[stock symbol](https://www.marketwatch.com/tools/quotes/lookup.asp)", like given "[stock symbol](https://www.marketwatch.com/tools/quotes/lookup.asp)",
`AAPL`,`AMZN`, `GOOG`, `MSFT`, etc. like `AAPL`,`AMZN`, `GOOG`, `MSFT`, etc.
## Prerequisites ## Prerequisites
@ -17,10 +16,10 @@ on Knative Serving. The exposed endpoint outputs the stock price for a given
[Homebrew](https://brew.sh/) on OS X. [Homebrew](https://brew.sh/) on OS X.
1. Download a copy of the code: 1. Download a copy of the code:
```shell ```shell
git clone -b "release-0.6" https://github.com/knative/docs knative-docs git clone -b "release-0.6" https://github.com/knative/docs knative-docs
cd knative-docs/serving/samples/rest-api-go cd knative-docs/serving/samples/rest-api-go
``` ```
## Setup ## Setup
@ -37,9 +36,9 @@ To build and push to a container registry using Docker:
1. Move into the sample directory: 1. Move into the sample directory:
```shell ```shell
cd $GOPATH/src/github.com/knative/docs cd $GOPATH/src/github.com/knative/docs
``` ```
2. Set your preferred container registry endpoint as an environment variable. 2. Set your preferred container registry endpoint as an environment variable.
This sample uses This sample uses
@ -52,41 +51,41 @@ To build and push to a container registry using Docker:
3. Set up your container registry to make sure you are ready to push. 3. Set up your container registry to make sure you are ready to push.
To push to GCR, you need to: To push to GCR, you need to:
- Create a - Create a
[Google Cloud Platform project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project). [Google Cloud Platform project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).
- Enable the - Enable the
[Google Container Registry API](https://console.cloud.google.com/apis/library/containerregistry.googleapis.com). [Google Container Registry API](https://console.cloud.google.com/apis/library/containerregistry.googleapis.com).
- Setup an - Setup an
[auth helper](https://cloud.google.com/container-registry/docs/advanced-authentication#gcloud_as_a_docker_credential_helper) [auth helper](https://cloud.google.com/container-registry/docs/advanced-authentication#gcloud_as_a_docker_credential_helper)
to give the Docker client the permissions it needs to push. to give the Docker client the permissions it needs to push.
If you are using a different container registry, you will want to follow the 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. registry specific instructions for both setup and authorizing the image push.
4. Use Docker to build your application container: 4. Use Docker to build your application container:
```shell ```shell
docker build \ docker build \
--tag "${REPO}/rest-api-go" \ --tag "${REPO}/rest-api-go" \
--file docs/serving/samples/rest-api-go/Dockerfile . --file docs/serving/samples/rest-api-go/Dockerfile .
``` ```
5. Push your container to a container registry: 5. Push your container to a container registry:
```shell ```shell
docker push "${REPO}/rest-api-go" docker push "${REPO}/rest-api-go"
``` ```
6. Substitute the image reference path in the template with our published image 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 path. The command below substitutes using the \${REPO} variable into a new
file called `docs/serving/samples/rest-api-go/sample.yaml`. file called `docs/serving/samples/rest-api-go/sample.yaml`.
```shell ```shell
envsubst < docs/serving/samples/rest-api-go/sample-template.yaml > \ envsubst < docs/serving/samples/rest-api-go/sample-template.yaml > \
docs/serving/samples/rest-api-go/sample.yaml docs/serving/samples/rest-api-go/sample.yaml
``` ```
## Deploy the Service ## Deploy the Service
@ -114,132 +113,131 @@ You can inspect the created resources with the following `kubectl` commands:
- View the created Service resource: - View the created Service resource:
```shell ```shell
kubectl get ksvc stock-service-example --output yaml kubectl get ksvc stock-service-example --output yaml
``` ```
- View the created Route resource: - View the created Route resource:
```shell ```shell
kubectl get route -l \ kubectl get route -l \
"serving.knative.dev/service=stock-service-example" --output yaml "serving.knative.dev/service=stock-service-example" --output yaml
``` ```
- View the Kubernetes Service created by the Route - View the Kubernetes Service created by the Route
```shell ```shell
kubectl get service -l \ kubectl get service -l \
"serving.knative.dev/service=stock-service-example" --output yaml "serving.knative.dev/service=stock-service-example" --output yaml
``` ```
- View the created Configuration resource: - View the created Configuration resource:
```shell ```shell
kubectl get configuration -l \ kubectl get configuration -l \
"serving.knative.dev/service=stock-service-example" --output yaml "serving.knative.dev/service=stock-service-example" --output yaml
``` ```
- View the Revision that was created by our Configuration: - View the Revision that was created by our Configuration:
```shell ```shell
kubectl get revision -l \ kubectl get revision -l \
"serving.knative.dev/service=stock-service-example" --output yaml "serving.knative.dev/service=stock-service-example" --output yaml
``` ```
- View the Deployment created by our Revision - View the Deployment created by our Revision
```shell ```shell
kubectl get deployment -l \ kubectl get deployment -l \
"serving.knative.dev/service=stock-service-example" --output yaml "serving.knative.dev/service=stock-service-example" --output yaml
``` ```
## Access the Service ## Access the Service
To access this service and run the stock ticker, you first obtain the ingress address To access this service and run the stock ticker, you first obtain the ingress
and service hostname, and then you run `curl` commands to send request with your stock address and service hostname, and then you run `curl` commands to send request
symbol. with your stock symbol.
**Note**: This sample assumes that you are using Knative's default Ingress Gateway. **Note**: This sample assumes that you are using Knative's default Ingress
If you customized your gateway, you need to adjust the enviornment Gateway. If you customized your gateway, you need to adjust the enviornment
variables in the following steps. variables in the following steps.
1. Find the IP address of the ingress gateway: 1. Find the IP address of the ingress gateway:
- **Cloud Provider**: To get the IP address of your ingress gateway: - **Cloud Provider**: To get the IP address of your ingress gateway:
```shell ```shell
INGRESSGATEWAY=istio-ingressgateway INGRESSGATEWAY=istio-ingressgateway
INGRESSGATEWAY_LABEL=istio INGRESSGATEWAY_LABEL=istio
export INGRESS_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \ export INGRESS_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \
--output jsonpath="{.status.loadBalancer.ingress[*].ip}"` --output jsonpath="{.status.loadBalancer.ingress[*].ip}"`
echo $INGRESS_IP echo $INGRESS_IP
``` ```
- **Minikube**: If your cluster is running outside a cloud provider (for example on - **Minikube**: If your cluster is running outside a cloud provider (for
Minikube), your services will never get an external IP address, and example on Minikube), your services will never get an external IP address,
`INGRESS_IP` won't contain a value. In that case, use the Istio `hostIP` and and `INGRESS_IP` won't contain a value. In that case, use the Istio
`nodePort` as the ingress IP: `hostIP` and `nodePort` as the ingress IP:
```shell ```shell
export INGRESS_IP=$(kubectl get po --selector $INGRESSGATEWAY_LABEL=ingressgateway --namespace istio-system \ 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={.items[0].status.hostIP}'):$(kubectl get svc $INGRESSGATEWAY --namespace istio-system \
--output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}') --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
echo $INGRESS_IP echo $INGRESS_IP
``` ```
2. Get the hostname of the service: 2. Get the hostname of the service:
```shell ```shell
export SERVICE_HOSTNAME=`kubectl get ksvc stock-service-example --output jsonpath="{.status.domain}"` export SERVICE_HOSTNAME=`kubectl get ksvc stock-service-example --output jsonpath="{.status.domain}"`
echo $SERVICE_HOSTNAME echo $SERVICE_HOSTNAME
``` ```
3. Send requests to the service using `curl`: 3. Send requests to the service using `curl`:
1. Send a request to the index endpoint: 1. Send a request to the index endpoint:
The `curl` command below makes a request to the Ingress Gateway IP. The The `curl` command below makes a request to the Ingress Gateway IP. The
Ingress Gateway uses the host header to route the request to the Service. Ingress Gateway uses the host header to route the request to the Service.
This example passes the host header to skip DNS configuration. If your 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 cluster has DNS configured, you can simply curl the DNS name instead of
ingress gateway IP. the ingress gateway IP.
```shell ```shell
curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP} curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}
``` ```
Response body: `Welcome to the stock app!` Response body: `Welcome to the stock app!`
2. Send a request to the `/stock` endpoint: 2. Send a request to the `/stock` endpoint:
```shell ```shell
curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock
``` ```
Response body: `stock ticker not found!, require /stock/{ticker}` Response body: `stock ticker not found!, require /stock/{ticker}`
3. Send a request to the `/stock` endpoint with your 3. Send a request to the `/stock` endpoint with your
"[stock symbol](https://www.marketwatch.com/tools/quotes/lookup.asp)": "[stock symbol](https://www.marketwatch.com/tools/quotes/lookup.asp)":
```shell ```shell
curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock/<SYMBOL> curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock/<SYMBOL>
``` ```
where `<SYMBOL>` is your "stock symbol".
Response body: `stock price for ticker <SYMBOL> is <PRICE>`
**Example**
Request:
```shell
curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock/FAKE
```
Response: `stock price for ticker FAKE is 0.00` where `<SYMBOL>` is your "stock symbol".
Response body: `stock price for ticker <SYMBOL> is <PRICE>`
**Example**
Request:
```shell
curl --header "Host:$SERVICE_HOSTNAME" http://${INGRESS_IP}/stock/FAKE
```
Response: `stock price for ticker FAKE is 0.00`
## Next Steps ## Next Steps