diff --git a/docs/install/Knative-with-Gloo.md b/docs/install/Knative-with-Gloo.md index e930a2839..ae69a58bd 100644 --- a/docs/install/Knative-with-Gloo.md +++ b/docs/install/Knative-with-Gloo.md @@ -1,12 +1,16 @@ --- title: "Knative Install using Gloo on a Kubernetes Cluster" -linkTitle: "Gloo on a Cluster" +linkTitle: "Gloo" weight: 10 type: "docs" --- -This guide walks you through the installation of the latest version of Knative -using pre-built images. +Learn how to deploy Gloo and Knative to your Kubernetes cluster using the Gloo command line tool `glooctl`. + + +[Gloo](https://gloo.solo.io) is a popular open-source Envoy control plane and API gateway built for Kubernetes (and other platforms). + +Gloo provides a complete gateway replacement for Istio and supports the full Knative Ingress spec. Choose Gloo if you don't require a service mesh in your cluster and want a lightweight alternative that requires less resource usage and operational overhead. ## Before you begin @@ -16,13 +20,11 @@ enabled. `kubectl` v1.10 is also required. This guide assumes that you've already created a Kubernetes cluster which you're comfortable installing _alpha_ software on. -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. +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 Glooctl -This installation method for Knative depends on Gloo. Run the following to -install `glooctl`, the Gloo command line. +Gloo's CLI tool `glooctl` makes it easy to install both Gloo and Knative without the need to use [Helm](https://helm.sh) or multiple manifests. Let's go ahead and download `glooctl`: ```shell curl -sL https://run.solo.io/gloo/install | sh @@ -43,7 +45,7 @@ Verify the CLI is installed and running correctly with: glooctl --version ``` -### Installing Gloo and Knative to your cluster +### Deploying Gloo and Knative to your cluster Finally, install Gloo and Knative in a single command with `glooctl`: @@ -51,9 +53,19 @@ Finally, install Gloo and Knative in a single command with `glooctl`: glooctl install knative ``` -> Note: To see the content of the kubernetes manifest glooctl installs, run -> `glooctl install knative --dry-run`. Monitor the Gloo components until all of -> the components show a `STATUS` of `Running` or `Completed`: +The `glooctl install knative` command can be customized with a variety of options: +- use `--install-knative-version` to set the installed version of Knative Serving (defaults to `0.8.0`) +- use `--install-build` to install Knative Build +- use `--install-eventing` to install Knative Eventing +- use `--dry-run` to produce the kubernetes YAML that would be applied to your cluster rather than applying. +- use `--install-knative=false` to only install Gloo without installing Knative components. This can be used if you wish to install Knative independently of Gloo. + +See https://github.com/solo-io/gloo/blob/master/docs/cli/glooctl_install_knative.md for the full list of available options for installing Knative with `glooctl` + +> Note: `glooctl` generates a manifest which can be piped to stdout or a file using the `--dry-run` flag. Alternatively, +Gloo can be installed via its [Helm Chart](https://gloo.solo.io/installation/gateway/kubernetes/#installing-on-kubernetes-with-helm), which will permit fine-grained configuration of installation parameters. + +Monitor the Gloo and Knative components until each one shows a `STATUS` of `Running` or `Completed`: ```shell kubectl get pods --namespace gloo-system @@ -69,22 +81,74 @@ rerun the command to see the current status. Now you can deploy an app using your freshly installed Knative environment. -## Deploying an app +## Running Knative apps -Now that your cluster has Knative installed, you can see what Knative has to -offer. +Now that your cluster has Gloo & Knative installed, you can run serverless applications with Knative. -To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](../serving/getting-started-knative-app.md) -guide. +Let's deploy an app to test that everything is set up correctly: -Note that when you've finished deploying the app, you'll need to connect to the -Gloo Gateway rather than the Istio Gateway. + +1. Next, create a `Knative Service` + + For this demo, a simple helloworld application written in go will be used. + Copy the YAML below to a file called `helloworld-go.yaml` and apply it with + `kubectl` + + ```yaml + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + env: + - name: TARGET + value: Go Sample v1 + ``` + + ``` + kubectl apply -f helloworld-go.yaml + ``` + +2. Send a request + + **Knative Services** are exposed via the *Host* header assigned by Knative. By + default, Knative will use the header `Host`: + `{service-name}.{namespace}.example.com`. You can discover the appropriate *Host* header by checking the URL Knative has assigned to the `helloworld-go` service created above. + + ``` + $ kubectl get ksvc helloworld-go -n default --output=custom-columns=NAME:.metadata.name,URL:.status.url + ``` + + ``` + NAME URL + helloworld-go http://helloworld-go.default.example.com + ``` + + Gloo uses the `Host` header to route requests to the correct + service. You can send a request to the `helloworld-go` service with curl + using the `Host` and `$GATEWAY_URL` from above: + + ``` + curl -H "Host: helloworld-go.default.example.com" $(glooctl proxy url --name knative-external-proxy) + ``` + + ``` + Hello Go Sample v1! + ``` + +Congratulations! You have successfully installed Knative with Gloo to manage and route to serverless applications! + +> Note that when following other Knative tutorials, you'll need to connect to the Gloo Gateway rather than the Istio Gateway when the tutorials prompts doing so. To get the URL of the Gloo Gateway, run ```bash -export GATEWAY_URL=$(glooctl proxy url --name clusteringress-proxy) +export GATEWAY_URL=$(glooctl proxy url --name knative-external-proxy) echo $GATEWAY_URL http://192.168.99.230:31864 @@ -93,172 +157,19 @@ http://192.168.99.230:31864 To send requests to your service: ```bash -export GATEWAY_URL=$(glooctl proxy url --name clusteringress-proxy) +export GATEWAY_URL=$(glooctl proxy url --name knative-external-proxy) curl -H "Host: helloworld-go.myproject.example.com" $GATEWAY_URL ``` -The full instructions for the -[Go Hello-World Sample](../serving/samples/hello-world/helloworld-go) with this -substitution are published bellow: +## What's next -### Deploy the Hello-World Go App: +Now that your cluster has Knative installed, you can see what Knative has to +offer. -Create a new file named `helloworld.go` and paste the following code. This code -creates a basic web server which listens on port 8080: +Learn more about deploying apps to Knative with the +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) +guide. -```go -package main - -import ( - "fmt" - "log" - "net/http" - "os" -) - -func handler(w http.ResponseWriter, r *http.Request) { - log.Print("Hello world received a request.") - target := os.Getenv("TARGET") - if target == "" { - target = "World" - } - fmt.Fprintf(w, "Hello %s!\n", target) -} - -func main() { - log.Print("Hello world sample started.") - - http.HandleFunc("/", handler) - - port := os.Getenv("PORT") - if port == "" { - port = "8080" - } - - log.Fatal(http.ListenAndServe(fmt.Sprintf(":%s", port), nil)) -} -``` - -In your project directory, create a file named `Dockerfile` and copy the code -block below into it. For detailed instructions on dockerizing a Go app, see -[Deploying Go servers with Docker](https://blog.golang.org/docker). - -```dockerfile -# Use the official Golang image to create a build artifact. -# This is based on Debian and sets the GOPATH to /go. -# https://hub.docker.com/_/golang -FROM golang as builder - -# Copy local code to the container image. -WORKDIR /go/src/github.com/knative/docs/helloworld -COPY . . - -# Build the helloworld command inside the container. -# (You may fetch or manage dependencies here, -# either manually or with a tool like "godep".) -RUN CGO_ENABLED=0 GOOS=linux go build -v -o helloworld - -# Use a Docker multi-stage build to create a lean production image. -# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds -FROM alpine -RUN apk add --no-cache ca-certificates - -# Copy the binary to the production image from the builder stage. -COPY --from=builder /go/src/github.com/knative/docs/helloworld/helloworld /helloworld - -# Run the web service on container startup. -CMD ["/helloworld"] -``` - -Create a new file, `service.yaml` and copy the following service definition into -the file. Make sure to replace `{username}` with your Docker Hub username. - -```yaml -apiVersion: serving.knative.dev/v1alpha1 -kind: Service -metadata: - name: helloworld-go - namespace: default -spec: - template: - spec: - containers: - - image: docker.io/{username}/helloworld-go - env: - - name: TARGET - value: "Go Sample v1" -``` - -Once the sample code has been created, we'll build and deploy it - -Use Docker to build the sample code into a container. To build and push with -Docker Hub, run these commands replacing `{username}` with your Docker Hub -username: - -```bash -# Build the container on your local machine -docker build -t {username}/helloworld-go . - -# Push the container to docker registry -docker push {username}/helloworld-go -``` - -After the build has completed and the container is pushed to docker hub, you can -deploy the app into your cluster. Ensure that the container image value in -`service.yaml` matches the container you built in the previous step. Apply the -configuration using `kubectl`: - -```bash -kubectl apply --filename 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. -- Network programming to create a route, ingress, service, and load balance for - your app. -- Automatically scale your pods up and down (including to zero active pods). - -- Run the following command to find the external IP address for the Gloo cluster - ingress. - -```bash -CLUSTERINGRESS_URL=$(glooctl proxy url --name clusteringress-proxy) -echo $CLUSTERINGRESS_URL -http://192.168.99.230:31864 -``` - -Run the following command to find the domain URL for your service: - -```bash -kubectl get ksvc helloworld-go -n default --output=custom-columns=NAME:.metadata.name,URL:.status.url -``` - -Example: - -```bash -NAME URL -helloworld-go http://helloworld-go.default.example.com -``` - -Test your app by sending it a request. Use the following `curl` command with the -domain URL `helloworld-go.default.example.com` and `EXTERNAL-IP` address that -you retrieved in the previous steps: - -```bash -curl -H "Host: helloworld-go.default.example.com" ${CLUSTERINGRESS_URL} -Hello Go Sample v1! -``` - -> Note: Add `-v` option to get more detail if the `curl` command failed. - -Removing the sample app deployment To remove the sample app from your cluster, -delete the service record: - -```bash -kubectl delete --filename service.yaml -``` - -Great! our Knative ingress is up and running. See -[Knative documentation](../README.md) for more information on using Knative. +To get started with Knative Eventing, pick one of the +[Eventing Samples](../eventing/samples/) to walk through. diff --git a/docs/install/README.md b/docs/install/README.md index 9b1bee37a..97d424cbe 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -36,10 +36,7 @@ component. ## Installing Knative with Gloo -[Install with Gloo](./Knative-with-Gloo.md): Gloo functions as a lightweight -gateway for Knative. Choose this option if you don't require service mesh in -your cluster and want a lighter-weight alternative to Istio. Note that _the -Knative Eventing component_ is not supported by Gloo at this time. +[Install with Gloo](./Knative-with-Gloo.md): Gloo functions as a lightweight gateway for Knative. Choose this option if you don't require a service mesh in your cluster and want a lightweight alternative to Istio. Gloo supports all documented Knative features, as well as extensions to Serving such as Eventing and Monitoring. ## Installing Knative with Istio diff --git a/docs/serving/using-auto-tls.md b/docs/serving/using-auto-tls.md index 5f7c89d95..ff0aee8cf 100644 --- a/docs/serving/using-auto-tls.md +++ b/docs/serving/using-auto-tls.md @@ -17,8 +17,8 @@ provisioning: - The following must be installed on your Knative cluter: - [Knative Serving version 0.6.0 or higher](../install/). - - [Istio with SDS, version 1.1 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway). - Note: Currently, [Gloo](https://github.com/solo-io/gloo) is unsupported. + - [Istio with SDS, version 1.1 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway) or [Gloo, version 0.18.16 or higher](../install/Knative-with-Gloo.md). + Note: Currently, [Ambassador](https://github.com/datawire/ambassador) is unsupported. - [cert-manager version `0.6.1` or higher](./installing-cert-manager.md). - Your Knative cluster must be configured to use a [custom domain](./using-a-custom-domain.md).