From 2a94a293cbc26bf06a83ebdea27e2195a2f3b5f2 Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Fri, 20 Jul 2018 15:12:00 -0700 Subject: [PATCH 1/7] [WIP] Updates to Thumbnailer sample --- serving/samples/thumbnailer-go/README.md | 66 ++++++++++++++++-------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index de45379d3f4..8f72bdf93c1 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -1,23 +1,32 @@ # Thumbnailer Demo -Thumbnailer demo is a walk-through example on how to deploy a 'dockerized' application to the Knative Serving service. In this demo we will use a sample `golang` application that takes video URL as an input and generates its thumbnail image. +This is a walk-through example that demonstrates deploying a dockerized +application to the Knative Serving service. In this demo we will use a sample +`golang` application that takes a video URL as an input and generates its thumbnail image. -> In this demo we will assume access to existing Knative Serving service. If not, consult [README.md](https://github.com/knative/serving/blob/master/README.md) on how to deploy one. +## Before you begin -## Sample Code +* [Install Knative Serving](../../../install/README.md) +* [Install Go](https://golang.org/doc/install) (if you want to run and test the sample app locally) -In this demo we are going to use a simple `golang` REST app called [rester-tester](https://github.com/mchmarny/rester-tester). It's important to point out that this application doesn't use any 'special' Knative Serving components nor does it have any Knative Serving SDK dependencies. +## Sample code -### App code +In this demo we are going to use a simple `golang` REST app called +[rester-tester](https://github.com/mchmarny/rester-tester). It's important +to point out that this application doesn't use any special Knative Serving +components, nor does it have any Knative Serving SDK dependencies. -Let's start by cloning the public `rester-tester` repository +### Cloning the sample code + +Let's start by cloning the public `rester-tester` repository: ``` git clone git@github.com:mchmarny/rester-tester.git cd rester-tester ``` -The `rester-tester` application uses [godep](https://github.com/tools/godep) to manage its own dependencies. Go get it and restore the app dependencies +The `rester-tester` application uses [godep](https://github.com/tools/godep) +to manage its own dependencies. Download `godep` and restore the app dependencies: ``` go get github.com/tools/godep @@ -26,7 +35,7 @@ godep restore ### Test -To quickly make sure the application is ready, execute the integrated tests +To make sure the application is ready, run the integrated tests: ``` go test ./... @@ -34,11 +43,13 @@ go test ./... ### Run -You can now run the `rester-tester` application locally in `go` or using Docker +You can now run the `rester-tester` application locally in `go` or using Docker. **Local** -> Note: to run the application locally in `go` you will need [FFmpeg](https://www.ffmpeg.org/) in your path. +> Note: To run the application locally in `go` you will need [FFmpeg](https://www.ffmpeg.org/) in your path. + +To run the app: ``` go build @@ -47,7 +58,10 @@ go build **Docker** -When running the application locally in docker, you do not need to install `ffmpeg`, Docker will install it for you 'inside' of the Docker image +When running the application locally using Docker, you do not need to install `ffmpeg`; +Docker will install it for you 'inside' of the Docker image. + +To run the app: ``` docker build -t rester-tester:latest . @@ -56,26 +70,28 @@ docker run -p 8080:8080 rester-tester:latest ### Test -To test the thumbnailing service use `curl` to submit `src` video URL. +To test the thumbnailing service, use `curl` to submit the `src`, a video URL: ``` curl -X POST -H "Content-Type: application/json" http://localhost:8080/image \ -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' ``` -## Deploy (Prebuilt) +## Deploy a prebuilt version of the app -You can now deploy the `rester-tester` app to the Knative Serving service using `kubectl` using the included `sample-prebuilt.yaml`. +You can now deploy the `rester-tester` app to the Knative Serving service using +`kubectl` and the included `sample-prebuilt.yaml` file. ``` -# From inside this directory +# From inside the thumbnailer-go directory kubectl apply -f sample-prebuilt.yaml ``` -If you would like to publish your own copy of the container image, you can update the image reference in this file. +If you would like to publish your own copy of the container image, +you can update the image reference in `sample-prebuilt.yaml` file. -## Deploy (with Build) +## Build and deploy a version of the app You can also build the image as part of deployment. This sample uses the [Kaniko build @@ -122,13 +138,16 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) knative-ingressgateway LoadBalancer 10.23.247.74 35.203.155.229 80:32380/TCP,443:32390/TCP,32400:32400/TCP 2d ``` -Sometimes the newly deployed app may take few seconds to initialize. You can check its status like this +The newly deployed app may take few seconds to initialize. You can check its status +by entering the following command: ``` kubectl -n default get pods ``` -The Knative Serving ingress service will automatically be assigned an IP so let's capture that IP so we can use it in subsequent `curl` commands +The Knative Serving ingress service will automatically be assigned an IP, +so let's capture the IP and Host URL in variables so that we can use them +in `curl` commands: ``` # Put the Host name into an environment variable. @@ -149,7 +168,7 @@ export SERVICE_IP=$(kubectl get po -l knative=ingressgateway -n istio-system -o ### Ping -Let's start with a simple `ping` service +Let's start with a simple `ping`: ``` curl -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ @@ -165,7 +184,8 @@ curl -X POST -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ http://$SERVICE_IP/image -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' | jq '.' ``` -You can then download the newly created thumbnail. Make sure to replace the image name with the one returned by the previous service +You can then download the newly created thumbnail. Make sure to replace the image file name +with the one returned by the previous curl request: ``` curl -H "Host: $SERVICE_HOST" \ @@ -174,4 +194,6 @@ curl -H "Host: $SERVICE_HOST" \ ## Final Thoughts -While we used in this demo an external application, the Knative Serving deployment steps would be similar for any 'dockerized' app you may already have... just copy the `thumbnailer.yaml` and change a few variables. +Although this demo uses an external application, the Knative Serving deployment +steps would be similar for any 'dockerized' app you may already have. +Just copy the `thumbnailer.yaml` and change a few variables. From cb6ea56833320a0459c5e239972b59bbb6f6220d Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Fri, 20 Jul 2018 16:11:59 -0700 Subject: [PATCH 2/7] More edits --- serving/samples/thumbnailer-go/README.md | 53 +++++++++++++----------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index 8f72bdf93c1..9cf7c190fa0 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -33,7 +33,7 @@ go get github.com/tools/godep godep restore ``` -### Test +### Run tests To make sure the application is ready, run the integrated tests: @@ -41,13 +41,13 @@ To make sure the application is ready, run the integrated tests: go test ./... ``` -### Run +### Run the app You can now run the `rester-tester` application locally in `go` or using Docker. **Local** -> Note: To run the application locally in `go` you will need [FFmpeg](https://www.ffmpeg.org/) in your path. +> Note: To run the application locally in `go`, you will need [FFmpeg](https://www.ffmpeg.org/) in your path. To run the app: @@ -77,26 +77,27 @@ curl -X POST -H "Content-Type: application/json" http://localhost:8080/image \ -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' ``` -## Deploy a prebuilt version of the app +## Deploying the app to Knative + +From this point, you can either build the app yourself and then deploy it, +or you can deploy a prebuilt image of the app. + +### Deploying a prebuilt image -You can now deploy the `rester-tester` app to the Knative Serving service using -`kubectl` and the included `sample-prebuilt.yaml` file. +You can deploy a prebuilt image of the `rester-tester` app to the Knative Serving service using +`kubectl` and the included `sample-prebuilt.yaml` file: ``` # From inside the thumbnailer-go directory kubectl apply -f sample-prebuilt.yaml ``` -If you would like to publish your own copy of the container image, -you can update the image reference in `sample-prebuilt.yaml` file. - - -## Build and deploy a version of the app +### Building and deploying a version of the app -You can also build the image as part of deployment. This sample uses the +If you want to build the image yourself, follow these instructions. This sample uses the [Kaniko build template](https://github.com/knative/build-templates/blob/master/kaniko/kaniko.yaml) -in the [build-templates](https://github.com/knative/build-templates/) repo. +from the [build-templates](https://github.com/knative/build-templates/) repo. ```shell # Replace the token string with a suitable registry @@ -125,12 +126,13 @@ items: ... ``` -Once `BuildComplete` has a `status: "True"`, the revision will get deployed as in the "prebuilt" case above. +Once `BuildComplete` has a `status: "True"`, the revision will be deployed. -## Demo +## Using the app -To confirm that the app deployed, you can check for the Knative Serving service using `kubectl`. First, is there an ingress service: +To confirm that the app deployed, you can check for the Knative Serving service using `kubectl`. +First, is there an ingress service, and does it have an `EXTERNAL-IP`: ``` kubectl get svc knative-ingressgateway -n istio-system @@ -145,12 +147,12 @@ by entering the following command: kubectl -n default get pods ``` -The Knative Serving ingress service will automatically be assigned an IP, +The Knative Serving ingress service will automatically be assigned an external IP, so let's capture the IP and Host URL in variables so that we can use them in `curl` commands: ``` -# Put the Host name into an environment variable. +# Put the Host URL into an environment variable. export SERVICE_HOST=`kubectl get route thumb -o jsonpath="{.status.domain}"` # Put the ingress IP into an environment variable. @@ -158,17 +160,20 @@ export SERVICE_IP=`kubectl get svc knative-ingressgateway -n istio-system -o jso ``` 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: +your services will never get an external IP address. In that case, use the istio +`hostIP` and `nodePort` as the service IP: ```shell 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}') ``` -> To make the JSON service responses more readable consider installing [jq](https://stedolan.github.io/jq/), makes JSON pretty +> To make the JSON service responses more readable, this guide uses + [jq](https://stedolan.github.io/jq/). If you don't want to install + it, remove `| jq '.'` from the following commands. ### Ping -Let's start with a simple `ping`: +Let's start with a simple `ping` to make sure the app is deployed: ``` curl -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ @@ -177,15 +182,15 @@ curl -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ ### Video Thumbnail -Now the video thumbnail. +Now, supply the video URL and generate a video thumbnail: ``` curl -X POST -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ http://$SERVICE_IP/image -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' | jq '.' ``` -You can then download the newly created thumbnail. Make sure to replace the image file name -with the one returned by the previous curl request: +You can then download the newly created thumbnail. Make sure to replace the +image file name with the one returned by the previous curl request: ``` curl -H "Host: $SERVICE_HOST" \ From 31bea15595b5df6ea60e0bff095a19f66251fdcf Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Fri, 20 Jul 2018 16:14:58 -0700 Subject: [PATCH 3/7] More edits --- serving/samples/thumbnailer-go/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index 9cf7c190fa0..23a7ba75a79 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -79,8 +79,8 @@ curl -X POST -H "Content-Type: application/json" http://localhost:8080/image \ ## Deploying the app to Knative -From this point, you can either build the app yourself and then deploy it, -or you can deploy a prebuilt image of the app. +From this point, you can either deploy a prebuilt image of the app, or build +the app locally and then deploy it. ### Deploying a prebuilt image From ab19249e525a53983d7ed3259e2e3bdbd64fe981 Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Fri, 20 Jul 2018 16:17:20 -0700 Subject: [PATCH 4/7] Update README.md --- serving/samples/thumbnailer-go/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index 23a7ba75a79..497f1b8ebce 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -140,6 +140,8 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) knative-ingressgateway LoadBalancer 10.23.247.74 35.203.155.229 80:32380/TCP,443:32390/TCP,32400:32400/TCP 2d ``` +> Note: It can take a few seconds for the service to show an `EXTERNAL-IP`. + The newly deployed app may take few seconds to initialize. You can check its status by entering the following command: From 5e8d9335d30a5c62fa552bdfc36952e5a08db7c5 Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Mon, 23 Jul 2018 13:08:42 -0700 Subject: [PATCH 5/7] Removing jq and 'service' --- serving/samples/thumbnailer-go/README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index 497f1b8ebce..a9dbbd3d22c 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -84,7 +84,7 @@ the app locally and then deploy it. ### Deploying a prebuilt image -You can deploy a prebuilt image of the `rester-tester` app to the Knative Serving service using +You can deploy a prebuilt image of the `rester-tester` app to Knative Serving using `kubectl` and the included `sample-prebuilt.yaml` file: ``` @@ -169,17 +169,13 @@ your services will never get an external IP address. In that case, use the istio 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}') ``` -> To make the JSON service responses more readable, this guide uses - [jq](https://stedolan.github.io/jq/). If you don't want to install - it, remove `| jq '.'` from the following commands. - ### Ping Let's start with a simple `ping` to make sure the app is deployed: ``` curl -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ - http://$SERVICE_IP/ping | jq '.' + http://$SERVICE_IP/ping ``` ### Video Thumbnail @@ -188,7 +184,7 @@ Now, supply the video URL and generate a video thumbnail: ``` curl -X POST -H "Content-Type: application/json" -H "Host: $SERVICE_HOST" \ - http://$SERVICE_IP/image -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' | jq '.' + http://$SERVICE_IP/image -d '{"src":"https://www.youtube.com/watch?v=DjByja9ejTQ"}' ``` You can then download the newly created thumbnail. Make sure to replace the From d3694832a1b09e9cc6ca4e41b16dbf42a67748c9 Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Mon, 23 Jul 2018 13:31:22 -0700 Subject: [PATCH 6/7] Removing another 'service' --- serving/samples/thumbnailer-go/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index a9dbbd3d22c..9839d0da4f7 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -1,13 +1,15 @@ # Thumbnailer Demo This is a walk-through example that demonstrates deploying a dockerized -application to the Knative Serving service. In this demo we will use a sample -`golang` application that takes a video URL as an input and generates its thumbnail image. +application to Knative Serving. In this demo we will use a sample `golang` +application that takes a video URL as an input and generates its thumbnail image. ## Before you begin * [Install Knative Serving](../../../install/README.md) -* [Install Go](https://golang.org/doc/install) (if you want to run and test the sample app locally) +And if you want to run the app locally: +* [Install Go](https://golang.org/doc/install) +* [Install `ffmpeg`](https://www.ffmpeg.org/) ## Sample code @@ -47,8 +49,6 @@ You can now run the `rester-tester` application locally in `go` or using Docker. **Local** -> Note: To run the application locally in `go`, you will need [FFmpeg](https://www.ffmpeg.org/) in your path. - To run the app: ``` From 884fc5034353c0d2943630abbe395a1958c3bfc0 Mon Sep 17 00:00:00 2001 From: Sam O'Dell <31352624+samodell@users.noreply.github.com> Date: Mon, 23 Jul 2018 14:22:28 -0700 Subject: [PATCH 7/7] Add language about external dependencies --- serving/samples/thumbnailer-go/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/serving/samples/thumbnailer-go/README.md b/serving/samples/thumbnailer-go/README.md index 9839d0da4f7..6fce3399df3 100644 --- a/serving/samples/thumbnailer-go/README.md +++ b/serving/samples/thumbnailer-go/README.md @@ -1,15 +1,17 @@ -# Thumbnailer Demo +# Thumbnailer External Dependencies Demo This is a walk-through example that demonstrates deploying a dockerized -application to Knative Serving. In this demo we will use a sample `golang` -application that takes a video URL as an input and generates its thumbnail image. +application that accesses external dependencies to Knative Serving. In this demo +we will use a sample `golang` application that takes a video URL as an input and +generates its thumbnail image using the `ffmpeg` framework. ## Before you begin * [Install Knative Serving](../../../install/README.md) -And if you want to run the app locally: + +If you want to test and run the app locally: * [Install Go](https://golang.org/doc/install) -* [Install `ffmpeg`](https://www.ffmpeg.org/) +* [Download `ffmpeg`](https://www.ffmpeg.org/download.html) ## Sample code