diff --git a/install/Knative-with-GKE.md b/install/Knative-with-GKE.md index 9d5515d0d..a42195949 100644 --- a/install/Knative-with-GKE.md +++ b/install/Knative-with-GKE.md @@ -1,9 +1,7 @@ -# Getting Started with Knative on Google Kubernetes Engine +# Easy Install on Google Kubernetes Engine This guide walks you through the installation of the latest version of -[Knative](https://github.com/knative/serving) using pre-built images and -demonstrates creating and deploying an image of a sample "hello world" app onto -the newly created Knative cluster. +[Knative Serving](https://github.com/knative/serving) using pre-built images. You can find [guides for other platforms here](README.md). @@ -11,23 +9,21 @@ You can find [guides for other platforms here](README.md). Knative requires a Kubernetes cluster v1.10 or newer. If you don't have one, you can create one on Google Cloud Platform. You can also use Minikube; see the -[Knative the easy way with Minikube](Knative-with-Minikube.md) guide for +[Easy Install on Minikube](Knative-with-Minikube.md) guide for instructions. This guide uses Google Kubernetes Engine to create a Kubernetes cluster. -This guide assumes you are using bash in a Linux environment; some commands will -need to be adjusted for use in a Windows environment. +This guide assumes you are using bash in a Mac or Linux environment; some +commands will need to be adjusted for use in a Windows environment. ### Installing the Google Cloud SDK > If you already have `gcloud` installed, you can skip these steps. 1. Download and install the `gcloud` command line tool: - https://cloud.google.com/sdk/ - + 1. Authorize `gcloud`: - ``` gcloud auth login ``` @@ -38,45 +34,45 @@ To simplify the command lines for this walkthrough, we need to define a few environment variables. 1. Set a `PROJECT_ID` variable. - * If you already have a default project set in `gcloud`, enter: - ```bash - export PROJECT_ID=$(gcloud config get-value project) - ``` - * Or, if you don't have an existing GCP project you'd like to use, replace - `my-knative-project` with your desired project ID. This variable will be - used later to create your new GCP project. The project ID must be globally - unique across all GCP projects. - ```bash - export PROJECT_ID=my-knative-project - ``` + * If you already have a default project set in `gcloud`, enter: + ```bash + export PROJECT_ID=$(gcloud config get-value project) + ``` + * Or, if you don't have an existing GCP project that you'd like to use, replace + `my-knative-project` with your desired project ID. This variable will be + used later to create your new GCP project. The project ID must be globally + unique across all GCP projects. + ```bash + export PROJECT_ID=my-knative-project + ``` 1. Set `CLUSTER_NAME` and `CLUSTER_ZONE` variables as desired: - ```bash - export CLUSTER_NAME=knative - export CLUSTER_ZONE=us-west1-c - ``` + ```bash + export CLUSTER_NAME=knative + export CLUSTER_ZONE=us-west1-c + ``` ### Setting up a Google Cloud Platform project -You need a Google Cloud Platform project to create a Kubernetes Engine cluster. +You need a GCP project to create a Kubernetes Engine cluster. 1. Create a new GCP project and set it as your `gcloud` default, or set an - existing GCP as your `gcloud` default. + existing GCP as your `gcloud` default. * If you already have a GCP project, make sure your project is set as your `gcloud` default: - ```bash - gcloud config set project $PROJECT_ID - ``` + ```bash + gcloud config set project $PROJECT_ID + ``` * If you don't already have a GCP project configured, create a new project: - ```bash - gcloud projects create $PROJECT_ID --set-as-default - ``` + ```bash + gcloud projects create $PROJECT_ID --set-as-default + ``` 1. Enable the necessary APIs: - ``` - gcloud services enable \ - cloudapis.googleapis.com \ - container.googleapis.com \ - containerregistry.googleapis.com - ``` + ``` + gcloud services enable \ + cloudapis.googleapis.com \ + container.googleapis.com \ + containerregistry.googleapis.com + ``` ## Creating a Kubernetes cluster @@ -132,8 +128,8 @@ CTRL+C when it's done. ## Installing Knative Serving -1. Next, we will install [Knative Serving](https://github.com/knative/serving) and -its dependencies: +1. Next, we will install [Knative Serving](https://github.com/knative/serving) +and its dependencies: ```bash kubectl apply -f https://storage.googleapis.com/knative-releases/latest/release.yaml ``` @@ -149,9 +145,16 @@ You are now ready to deploy an app to your new Knative cluster. ## Deploying an app -Now that your cluster is running the Knative components, follow the instructions -for one of the [sample apps](../serving/samples/README.md) to deploy your first -app. +Now that your cluster has Knative installed, you're ready to deploy an app. + +You have two options for deploying your first app: + +* You can follow the step-by-step + [Getting Started with Knative App Deployment](getting-started-knative-app.md) + guide. + +* You can view the available [sample apps](../serving/samples/README.md) and + deploy one of your choosing. ## Cleaning up diff --git a/install/Knative-with-Minikube.md b/install/Knative-with-Minikube.md index a8d279511..296efb3b2 100644 --- a/install/Knative-with-Minikube.md +++ b/install/Knative-with-Minikube.md @@ -1,7 +1,7 @@ -# Getting Started with Knative on Minikube +# Easy Install on Minikube This guide walks you through the installation of the latest version of -[Knative](https://github.com/knative/serving) using pre-built images and +[Knative Serving](https://github.com/knative/serving) using pre-built images and demonstrates creating and deploying an image of a sample "hello world" app onto the newly created Knative cluster. @@ -97,42 +97,15 @@ Now you can deploy your app/function to your newly created Knative cluster. ## Deploying an app -The following instructions will deploy the `Primer` sample app onto your new -Knative cluster. +Now that your cluster has Knative installed, you're ready to deploy an app. -> Note, you will be deploying using a pre-built image, so there is no need to clone the -Primer repo or install anything locally. If you want to run the `Primer` app -locally see the [Primer Readme](https://github.com/mchmarny/primer) for -instructions. +If you'd like to follow a step-by-step guide for deploying your first app on +Knative, check out the +[Getting Started with Knative App Deployment](getting-started-knative-app.md) +guide. -```shell -kubectl apply -f https://storage.googleapis.com/knative-samples/primer.yaml -``` - -Wait until your route gets assigned a domain, - -```shell -kubectl get route primer -o=custom-columns=NAME:.metadata.name,DOMAIN:.status.domain --watch -``` -CTRL+C when it's done. - -Capture the IP and host name by running these commands: - -```shell -export SERVICE_IP=$(minikube ip):$(kubectl get svc knative-ingressgateway -n istio-system \ - -o 'jsonpath={.spec.ports[?(@.port==80)].nodePort}') - -export SERVICE_HOST=`kubectl get route primer -o jsonpath="{.status.domain}"` -``` - -> Alternatively, you can create an entry in your DNS server to point your - subdomain to the IP. - -Run the Primer app. The higher the number, the longer it will run. - -```shell -curl -H "Host: ${SERVICE_HOST}" http://$SERVICE_IP/5000000 -``` +If you'd like to view the available sample apps and deploy one of your choosing, +head to the [sample apps](../serving/samples/README.md) repo. ## Cleaning up diff --git a/install/README.md b/install/README.md index 772ba9ab8..962408128 100644 --- a/install/README.md +++ b/install/README.md @@ -1,11 +1,30 @@ -# Knative the easy way +# Knative Serving Install -To get started with Knative, you need a Kubernetes cluster. If you aren't -sure how to get started with Kubernetes, see +To get started with Knative Serving, you need a Kubernetes cluster. If you aren't +sure what Kubernetes platform is right for you, see [Picking the Right Solution](https://kubernetes.io/docs/setup/pick-right-solution/). +We provide information for installing Knative on +[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/) and +[Minikube](https://kubernetes.io/docs/setup/minikube/) clusters. -This repo includes step-by-step guides for setting up Kubernetes, installing -Knative components, and running a sample app on the following platforms: +## Install guides -- [Google Kubernetes Engine](Knative-with-GKE.md) -- [Minikube](Knative-with-Minikube.md) \ No newline at end of file +There are step-by-step guides for setting up Kubernetes and installing +Knative components on the following platforms: + +* [Easy Install on Google Kubernetes Engine](Knative-with-GKE.md) +* [Easy Install on Minikube](Knative-with-Minikube.md) + +## Deploying an app + +Once you have Knative installed on your Kubernetes cluster, you're ready to +deploy an app. + +You have two options: + +* You can follow the step-by-step + [Getting Started with Knative App Deployment](getting-started-knative-app.md) + guide. + +* You can view the available [sample apps](../serving/samples/README.md) and + deploy one of your choosing. \ No newline at end of file diff --git a/install/getting-started-knative-app.md b/install/getting-started-knative-app.md new file mode 100644 index 000000000..1ac669b80 --- /dev/null +++ b/install/getting-started-knative-app.md @@ -0,0 +1,127 @@ +# Getting Started with Knative App Deployment + +This guide shows you how to deploy an app using Knative Serving. + +## Before you begin + +You need a Kubernetes cluster with Knative Serving installed. + +For installation instructions, see one of the following install guides: +* [Easy Install on Google Kubernetes Engine](Knative-with-GKE.md) +* [Easy Install on Minikube](Knative-with-Minikube.md) + +You also need an image of the app that you'd like to deploy available on an +image hosting platform like Google Container Registry or Docker Hub. An image of +the sample application used in this guide is available on GCR. + +## Sample application + +This guides uses the +[Hello World sample app in Go](../serving/samples/helloworld-go) to demonstrate +the basic workflow for deploying an app, but these steps can be adapted for your +own application if you have an image of it available on Google Container +Registry, Docker Hub, or another image hosting platform. + +The Hello World sample app reads in an `env` variable, `TARGET`, from the +configuration `.yaml` file, then prints "Hello World: ${TARGET}!". If `TARGET` +isn't defined, it will print "NOT SPECIFIED". + +## Configuring your deployment + +To deploy an app using Knative Serving, you need a configuration .yaml file +that defines a Service. For more information about the Service object, see the +[Resource Types documentation](https://github.com/knative/serving/blob/master/docs/spec/overview.md#service). + +This configuration file specifies metadata about the application, points to the +hosted image of the app for deployment, and allows the deployment to be +configured. For more information about what configuration options are available, +see the +[Serving spec documentation](https://github.com/knative/serving/blob/master/docs/spec/spec.md). + +Create a new file named `service.yaml`, then copy and paste the following content into it: + +```yaml +apiVersion: serving.knative.dev/v1alpha1 # Current version of Knative +kind: Service +metadata: + name: helloworld-go # The name of the app + namespace: default # The namespace the app will use +spec: + runLatest: + configuration: + revisionTemplate: + spec: + container: + image: gcr.io/knative-samples/helloworld-go # The URL to the hosted image of the app + env: + - name: TARGET # The environment variable printed out by the sample app + value: "Go Sample v1" +``` + +If you want to deploy the sample app, leave the config file as-is. If you're +deploying an image of your own app, update the name of the app and the URL of +the image accordingly. + +## Deploying your app + +From the directory where the new `service.yaml` file was created, apply the configuration: +```bash +kubectl apply -f service.yaml +``` + +Now that your service is created, Knative will perform the following steps: + * Create a new immutable revision for this version of the app. + * Perform network programming to create a route, ingress, service, and load + balance for your app. + * Automatically scale your pods up and down based on traffic, including to + zero active pods. + +To see if the new app has been deployed succesfully, you need the HOST and +IP_ADDRESS created by Knative. + +1. To find the IP address for your service, enter + `kubectl get svc knative-ingressgateway -n istio-system`. If your cluster is + new, it can take sometime for the service to get asssigned an external IP address. + + ```shell + kubectl get svc knative-ingressgateway -n istio-system + + 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 + + ``` + Take note of the `EXTERNAL-IP` address. + +1. To find the HOST URL for your service, enter: + + ```shell + kubectl get services.serving.knative.dev helloworld-go -o=custom-columns=NAME:.metadata.name,DOMAIN:.status.domain + NAME DOMAIN + helloworld-go helloworld-go.default.example.com + ``` + If you changed the name from `helloworld-go` to something else when creating + the the `.yaml` file, replace `helloworld-go` in the above command with the + name you entered. + +1. Now you can make a request to your app to see the results. Replace + `IP_ADDRESS` with the `EXTERNAL-IP` you wrote down, and replace + `helloworld-go.default.example.com` with the domain returned in the previous + step. If you deployed your own app, you may want to customize this curl + request to interact with your application. + + ```shell + curl -H "Host: helloworld-go.default.example.com" http://IP_ADDRESS + Hello World: Go Sample v1! + ``` + It can take a few seconds for Knative to scale up your application and return + a response. + +You've deployed your first application using Knative! + +## Cleaning up + +To remove the sample app from your cluster, delete the service record: + +```shell +kubectl delete -f service.yaml +``` \ No newline at end of file