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

Adds Getting Started Deployment Guide, updates to GKE and Minikube installs (#89) 

* Adding new Getting Started walkthrough, updates to GKE and minikube install guides

* Edit of new getting started guide and minor updates to existing install guides.

* Changes based on @labadavs review
This commit is contained in:
Sam O'Dell 2018-07-10 14:33:33 -07:00 committed by Google Prow Robot
parent dafe895e23
commit 868785656b
4 changed files with 209 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
install/Knative-with-GKE.md
View File

@ -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 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.
demonstrates creating and deploying an image of a sample "hello world" app onto
the newly created Knative cluster.
You can find [guides for other platforms here](README.md). 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, 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 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 instructions. This guide uses Google Kubernetes Engine to create a Kubernetes
cluster. cluster.
This guide assumes you are using bash in a Linux environment; some commands will This guide assumes you are using bash in a Mac or Linux environment; some
need to be adjusted for use in a Windows environment. commands will need to be adjusted for use in a Windows environment.
### Installing the Google Cloud SDK ### Installing the Google Cloud SDK
> If you already have `gcloud` installed, you can skip these steps. > If you already have `gcloud` installed, you can skip these steps.
1. Download and install the `gcloud` command line tool: 1. Download and install the `gcloud` command line tool:
https://cloud.google.com/sdk/ https://cloud.google.com/sdk/
1. Authorize `gcloud`: 1. Authorize `gcloud`:
``` ```
gcloud auth login gcloud auth login
``` ```
@ -38,45 +34,45 @@ To simplify the command lines for this walkthrough, we need to define a few
environment variables. environment variables.
1. Set a `PROJECT_ID` variable. 1. Set a `PROJECT_ID` variable.
* If you already have a default project set in `gcloud`, enter: * If you already have a default project set in `gcloud`, enter:
```bash ```bash
export PROJECT_ID=$(gcloud config get-value project) export PROJECT_ID=$(gcloud config get-value project)
``` ```
* Or, if you don't have an existing GCP project you'd like to use, replace * 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 `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 used later to create your new GCP project. The project ID must be globally
unique across all GCP projects. unique across all GCP projects.
```bash ```bash
export PROJECT_ID=my-knative-project export PROJECT_ID=my-knative-project
``` ```
1. Set `CLUSTER_NAME` and `CLUSTER_ZONE` variables as desired: 1. Set `CLUSTER_NAME` and `CLUSTER_ZONE` variables as desired:
```bash ```bash
export CLUSTER_NAME=knative export CLUSTER_NAME=knative
export CLUSTER_ZONE=us-west1-c export CLUSTER_ZONE=us-west1-c
``` ```
### Setting up a Google Cloud Platform project ### 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 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 * If you already have a GCP project, make sure your project is set as your
`gcloud` default: `gcloud` default:
```bash ```bash
gcloud config set project $PROJECT_ID gcloud config set project $PROJECT_ID
``` ```
* If you don't already have a GCP project configured, create a new project: * If you don't already have a GCP project configured, create a new project:
```bash ```bash
gcloud projects create $PROJECT_ID --set-as-default gcloud projects create $PROJECT_ID --set-as-default
``` ```
1. Enable the necessary APIs: 1. Enable the necessary APIs:
``` ```
gcloud services enable \ gcloud services enable \
cloudapis.googleapis.com \ cloudapis.googleapis.com \
container.googleapis.com \ container.googleapis.com \
containerregistry.googleapis.com containerregistry.googleapis.com
``` ```
## Creating a Kubernetes cluster ## Creating a Kubernetes cluster
@ -132,8 +128,8 @@ CTRL+C when it's done.
## Installing Knative Serving ## Installing Knative Serving
1. Next, we will install [Knative Serving](https://github.com/knative/serving) and 1. Next, we will install [Knative Serving](https://github.com/knative/serving)
its dependencies: and its dependencies:
```bash ```bash
kubectl apply -f https://storage.googleapis.com/knative-releases/latest/release.yaml 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 ## Deploying an app
Now that your cluster is running the Knative components, follow the instructions Now that your cluster has Knative installed, you're ready to deploy an app.
for one of the [sample apps](../serving/samples/README.md) to deploy your first
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 ## Cleaning up

45
install/Knative-with-Minikube.md
View File

@ -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 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 demonstrates creating and deploying an image of a sample "hello world" app onto
the newly created Knative cluster. 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 ## Deploying an app
The following instructions will deploy the `Primer` sample app onto your new Now that your cluster has Knative installed, you're ready to deploy an app.
Knative cluster.
> Note, you will be deploying using a pre-built image, so there is no need to clone the If you'd like to follow a step-by-step guide for deploying your first app on
Primer repo or install anything locally. If you want to run the `Primer` app Knative, check out the
locally see the [Primer Readme](https://github.com/mchmarny/primer) for [Getting Started with Knative App Deployment](getting-started-knative-app.md)
instructions. guide.
```shell If you'd like to view the available sample apps and deploy one of your choosing,
kubectl apply -f https://storage.googleapis.com/knative-samples/primer.yaml head to the [sample apps](../serving/samples/README.md) repo.
```
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
```
## Cleaning up ## Cleaning up

33
install/README.md
View File

@ -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 To get started with Knative Serving, you need a Kubernetes cluster. If you aren't
sure how to get started with Kubernetes, see sure what Kubernetes platform is right for you, see
[Picking the Right Solution](https://kubernetes.io/docs/setup/pick-right-solution/). [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 ## Install guides
Knative components, and running a sample app on the following platforms:
- [Google Kubernetes Engine](Knative-with-GKE.md) There are step-by-step guides for setting up Kubernetes and installing
- [Minikube](Knative-with-Minikube.md) 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.

127
install/getting-started-knative-app.md Normal file
View File

@ -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
```