diff --git a/docs/eventing/samples/kafka/channel/README.md b/docs/eventing/samples/kafka/channel/README.md index ba1c4321f69..d55bd218bde 100644 --- a/docs/eventing/samples/kafka/channel/README.md +++ b/docs/eventing/samples/kafka/channel/README.md @@ -19,7 +19,7 @@ You must also have the following tools installed: Install the `KafkaChannel` sub-component on your Knative Eventing cluster: ``` - curl -L "https://github.com/knative/eventing-contrib/releases/download/v0.10.1/kafka-channel.yaml" \ + curl -L "https://storage.googleapis.com/knative-releases/eventing-contrib/latest/kafka-channel.yaml" \ | sed 's/REPLACE_WITH_CLUSTER_URL/my-cluster-kafka-bootstrap.kafka:9092/' \ | kubectl apply --filename - ``` @@ -36,8 +36,8 @@ kind: KafkaChannel metadata: name: my-kafka-channel spec: - numPartitions: 1 - replicationFactor: 3 + numPartitions: 3 + replicationFactor: 1 EOF ``` diff --git a/docs/eventing/samples/kafka/source/README.md b/docs/eventing/samples/kafka/source/README.md index 4cebe56e3a5..d3b27960e3b 100644 --- a/docs/eventing/samples/kafka/source/README.md +++ b/docs/eventing/samples/kafka/source/README.md @@ -16,7 +16,7 @@ You must ensure that you meet the [prerequisites listed in the Apache Kafka over 1. Install the `KafkaSource` sub-component to your Knative cluster: ``` - kubectl apply -f https://github.com/knative/eventing-contrib/releases/download/v0.10.1/kafka-source.yaml + kubectl apply -f https://storage.googleapis.com/knative-releases/eventing-contrib/latest/kafka-source.yaml ``` 2. Check that the `kafka-controller-manager-0` pod is running. @@ -188,7 +188,7 @@ You must ensure that you meet the [prerequisites listed in the Apache Kafka over ``` 3. Remove the Apache Kafka Event Controller ``` - $ kubectl delete -f https://github.com/knative/eventing-contrib/releases/download/v0.10.1/kafka-importer.yaml + $ kubectl delete -f https://storage.googleapis.com/knative-releases/eventing-contrib/latest/kafka-source.yaml serviceaccount "kafka-controller-manager" deleted clusterrole.rbac.authorization.k8s.io "eventing-sources-kafka-controller" deleted clusterrolebinding.rbac.authorization.k8s.io "eventing-sources-kafka-controller" deleted diff --git a/docs/install/README.md b/docs/install/README.md index b3998ecfd2c..36d6414aaf4 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -62,6 +62,10 @@ There are several options when installing Knative: For new users, we recommend the comprehensive install to get you up and running quickly. +## Installing Knative with Kourier + +[Installing Knative with Kourier](./knative-with-kourier.md): In this guide, Knative will be installed with Kourier to replace the Istio Service Mesh, providing a more lightweight and simple Ingress controller. Note that Istio is required for the Knative Eventing component. + ### Install guides Follow these step-by-step guides for setting up Kubernetes and installing diff --git a/docs/install/knative-with-kourier.md b/docs/install/knative-with-kourier.md new file mode 100644 index 00000000000..3ccd724e0d4 --- /dev/null +++ b/docs/install/knative-with-kourier.md @@ -0,0 +1,162 @@ +--- +title: "Installing Knative with Kourier" +linkTitle: "Kourier Ingress and Knative" +weight: 15 +type: "docs" +--- + +[Kourier](https://github.com/3scale/kourier) is an open-source lightweight Knative Ingress based on Envoy. It's been designed for Knative, without requiring any additional custom resource definitions (CRDs). + +This guide walks you through the installation of the latest version of Knative +with Kourier as the ingress. + +## Before you Begin + +Knative requires a Kubernetes cluster v1.14 or newer, as well as a compatible `kubectl`. This guide assumes that you have already [created a Kubernetes cluster](https://kubernetes.io/docs/setup/) and are using +bash in a Mac or Linux environment. + +## Install Knative + +Let's do a core install of Knative Serving with the released yaml templates: + +1. To install Knative, first install the CRDs by running the following `kubectl apply` + command. This prevents race conditions during the install, which cause intermittent errors: + + kubectl apply --filename https://github.com/knative/serving/releases/download/{{< version >}}/serving-crds.yaml + +1. To complete the install of Knative and its dependencies, next run the + following `kubectl apply` command: + + kubectl apply --filename https://github.com/knative/serving/releases/download/{{< version >}}/serving-core.yaml + +1. Monitor the Knative Serving namespace and wait until all of the pods come up with a + `STATUS` of `Running`: + + ``` + kubectl get pods -w -n knative-serving + ``` + + +## Install Kourier + +Knative default installation uses Istio to handle internal and external traffic. If you are just interested in exposing Knative applications to the external network, a service mesh adds overhead and increases the system complexity. Kourier provides a way to expose your Knative application in a more simple and lightweight way. + +You can install Kourier with `kubectl`: + +``` +kubectl apply \ + --filename https://raw.githubusercontent.com/knative/serving/{{< version >}}/third_party/kourier-latest/kourier.yaml +``` + +## Configuring the Knative ingress class + +Kourier only exposes ingresses that have the "kourier" ingress class. By default Knative annotates all the ingresses for Istio but you can change that by patching the "config-network" configmap as follows: + +``` +kubectl patch configmap/config-network \ + -n knative-serving \ + --type merge \ + -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' +``` + +## Configuring DNS + +Installing Kourier will create a Kubernetes Service with type `LoadBalancer`. +This may take some time to get an IP address assigned, during this process, it +will appear as ``. You must wait for this IP address to be assigned +before DNS may be set up. + +To get the external IP address, use the following command: + +``` +kubectl get svc kourier -n kourier-system + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +kourier LoadBalancer 10.43.242.100 172.22.0.2 80:31828/TCP 19m + +``` + +This external IP can be used with your DNS provider with a wildcard `A` record; +however, for a basic functioning DNS setup (not suitable for production!) this +external IP address can be added to the `config-domain` ConfigMap in +`knative-serving`. You can edit this with the following command: + +``` +kubectl edit cm config-domain --namespace knative-serving +``` + +Given the external IP above, change the content to: + +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-domain + namespace: knative-serving +data: + # xip.io is a "magic" DNS provider, which resolves all DNS lookups for: + # *.{ip}.xip.io to {ip}. + 172.22.0.2.xip.io: "" +``` + +## Deploying an Application + +Now that Kourier is running and Knative is configured properly, you can go ahead and create your first Knative application: + +1. 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/v1 + 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 + ``` + +1. Send a request + + `Knative Service`s are exposed via a `Host` header assigned by Knative. By + default, Knative will assign the `Host`: + `{service-name}.{namespace}.{the domain we have setup above}`. You can see this + with: + + ``` + $ kubectl get ksvc helloworld-go + NAME URL LATESTCREATED LATESTREADY READY REASON + helloworld-go http://helloworld-go.default.172.22.0.2.xip.io helloworld-go-ps7lp helloworld-go-ps7lp True + ``` + + You can send a request to the `helloworld-go` service with curl + using the `URL` given above: + + ``` + $ curl http://helloworld-go.default.172.22.0.2.xip.io + + Hello Go Sample v1! + ``` + +Congratulations! You have successfully installed Knative with Kourier to manage and route your serverless applications! + +## What's next + +- Try the + [Getting Started with App Deployment guide](../serving/getting-started-knative-app.md) + for Knative serving. +- Get started with Knative Eventing by walking through one of the + [Eventing Samples](../eventing/samples/). diff --git a/docs/serving/samples/hello-world/helloworld-java-spring/README.md b/docs/serving/samples/hello-world/helloworld-java-spring/README.md index 535f44344e0..46b58283a7a 100644 --- a/docs/serving/samples/hello-world/helloworld-java-spring/README.md +++ b/docs/serving/samples/hello-world/helloworld-java-spring/README.md @@ -14,8 +14,8 @@ cluster. You can also download a working copy of the sample, by running the following commands: ```shell -git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs cd -knative-docs/docs/serving/samples/hello-world/helloworld-java-spring +git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs +cd knative-docs/docs/serving/samples/hello-world/helloworld-java-spring ``` ## Before you begin diff --git a/docs/serving/using-auto-tls.md b/docs/serving/using-auto-tls.md index 0fc84d823ec..9881300bf4d 100644 --- a/docs/serving/using-auto-tls.md +++ b/docs/serving/using-auto-tls.md @@ -6,56 +6,68 @@ type: "docs" --- If you install and configure cert-manager, you can configure Knative to -automatically obtain new TLS certificates and renew existing ones. To learn more -about using secure connections in Knative, see +automatically obtain new TLS certificates and renew existing ones for Knative +Services. +To learn more about using secure connections in Knative, see [Configuring HTTPS with TLS certificates](./using-a-tls-cert.md). +## Automatic TLS provision mode + +Knative supports the following Auto TLS modes: + +1. Using DNS-01 challenge + + In this mode, your cluster needs to be able to talk to your DNS server to verify the ownership of your domain. + - **Provision Certificate per namespace is supported when using DNS-01 challenge mode.** + - This is the recommended mode for faster certificate provision. + - In this mode, a single Certificate will be provisioned per namespace and is reused across the Knative Services within the same namespace. + + - **Provision Certificate per namespace is supported when using DNS-01 challenge mode.** + - This is the recommended mode for better certificate islation between Knative Services. + - In this mode, a Certificate will be provisioned for each Knative Service. + - The TLS effective time is longer as it needs Certificate provision for each Knative Service creation. + +1. Using HTTP-01 challenge + + - In this type, your cluster does not need to be able to talk to your DNS server. You just + need to map your domain to the IP of the cluser ingress. + - When using HTTP-01 challenge, **a certificate will be provisioned per Knative Service.** Certificate provision per namespace is not supported when using HTTP-01 challenge. + ## Before you begin -You must meet the following prerequisites to enable automatic certificate -provisioning: +You must meet the following prerequisites to enable auto TLS: - The following must be installed on your Knative cluter: - [Knative Serving](../install/). - - [Istio with SDS, version 1.1 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway), + - [Istio with SDS, version 1.3 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway), [Contour, version 1.1 or higher](../install/Knative-with-Contour.md), 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). + - [cert-manager version `0.12.0` or higher](./installing-cert-manager.md). - Your Knative cluster must be configured to use a [custom domain](./using-a-custom-domain.md). - Your DNS provider must be setup and configured to your domain. +- If you want to use HTTP-01 challenge, you need to configure your custom +domain to map to the IP of ingress. You can achieve this by adding a DNS A record to map the domain to the IP according to the instructions of your DNS provider. -## Enabling automatic certificate provisioning +## Enabling Auto TLS -To enable support for automatic TLS certificate provisioning in Knative: +To enable support for Auto TLS in Knative: -1. Determine if `networking-certmanager` is already installed by running the  - following command: +### Create cert-manager ClusterIssuer - ```shell - kubectl get deployment networking-certmanager -n knative-serving - ``` +1. Create and add the `ClusterIssuer` configuration file to your Knative cluster +to define who issues the TLS certificates, how requests are validated, +and which DNS provider validates those requests. -1. If `networking-certmanager` is not found, run the following command: + #### ClusterIssuer for DNS-01 challenge - ```shell - kubectl apply --filename https://github.com/knative/serving/releases/download/{{< version >}}/serving-cert-manager.yaml - ``` - -1. Create and add the `ClusterIssuer` configuration file to your Knative cluster - to define who issues the TLS certificates, how requests are validated - (`DNS-01`), and which DNS provider validates those requests. - - 1. Create the `ClusterIssuer` file: - - Use the cert-manager reference to determine how to configure your - `ClusterIssuer` file: - - - See the generic - [`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer) - - Also see the - [`DNS-01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html) + Use the cert-manager reference to determine how to configure your + `ClusterIssuer` file: + - See the generic + [`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer) + - Also see the + [`DNS01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html) **Example**: Cloud DNS `ClusterIssuer` configuration file: @@ -67,11 +79,10 @@ To enable support for automatic TLS certificate provisioning in Knative: [Configuring HTTPS with cert-manager and Google Cloud DNS](./using-cert-manager-on-gcp.md). ```shell - apiVersion: certmanager.k8s.io/v1alpha1 + apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: - name: letsencrypt-issuer - namespace: cert-manager + name: letsencrypt-dns-issuer spec: acme: server: https://acme-v02.api.letsencrypt.org/directory @@ -80,171 +91,231 @@ To enable support for automatic TLS certificate provisioning in Knative: email: myemail@gmail.com privateKeySecretRef: # Set privateKeySecretRef to any unused secret name. - name: letsencrypt-issuer - dns01: - providers: - - name: cloud-dns-provider - clouddns: - # Set this to your GCP project-id - project: $PROJECT_ID - # Set this to the secret that we publish our service account key - # in the previous step. - serviceAccountSecretRef: - name: cloud-dns-key - key: key.json + name: letsencrypt-dns-issuer + solvers: + - dns01: + clouddns: + # Set this to your GCP project-id + project: $PROJECT_ID + # Set this to the secret that we publish our service account key + # in the previous step. + serviceAccountSecretRef: + name: cloud-dns-key + key: key.json ``` - 1. Add your `ClusterIssuer` configuration to your Knative cluster by running - the following commands, where `` is the name of the file that - you created: + #### ClusterIssuer for HTTP-01 challenge - 1. Add the configuration file to Knative: + Run the following command to apply the ClusterIssuer for HTT01 challenge: - ```shell - kubectl apply -f .yaml - ``` + ```shell + kubectl apply -f - < --output yaml + ``` - Result: The `Status.Conditions` should include `Ready=True`. + Result: The `Status.Conditions` should include `Ready=True`. -1. Update your - [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml) - in the `knative-serving` namespace to define your new `ClusterIssuer` - configuration and your your DNS provider. - 1. Run the following command to edit your `config-certmanager` ConfigMap: +### Install networking-certmanager deployment - ```shell - kubectl edit configmap config-certmanager --namespace knative-serving - ``` +1. Determine if `networking-certmanager` is already installed by running the + following command: - 1. Add the `issuerRef` and `solverConfig` sections within the `data` section: + ```shell + kubectl get deployment networking-certmanager -n knative-serving + ``` - ```shell - ... - data: - ... - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer - - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` +1. If `networking-certmanager` is not found, run the following command: - Example: + ```shell + kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-cert-manager.yaml + ``` - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-certmanager - namespace: knative-serving - labels: - networking.knative.dev/certificate-provider: cert-manager - data: - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` +### Install networking-ns-cert component - 1. Ensure that the file was updated successfully: +If you choose to use the mode of provisioning certificate per namespace, you need to install `networking-ns-cert` components. - ```shell - kubectl get configmap config-certmanager --namespace knative-serving --output yaml - ``` +1. Determine if `networking-ns-cert` deployment is already installed by +running the following command: -1. Update the - [`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml) - in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP - requests are handled: + ```shell + kubectl get deployment networking-ns-cert -n knative-serving + ``` - 1. Run the following command to edit your `config-network` ConfigMap: +1. If `networking-ns-cert` deployment is not found, run the following command: - ```shell - kubectl edit configmap config-network --namespace knative-serving - ``` + ```shell + kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-nscert.yaml + ``` - 1. Add the `autoTLS: Enabled` attribute under the `data` section: +### Configure config-certmanager ConfigMap - ```shell - ... - data: - ... - autoTLS: Enabled - ... - ``` +Update your [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml) +in the `knative-serving` namespace to reference your new `ClusterIssuer`. - Example: +1. Run the following command to edit your `config-certmanager` ConfigMap: - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - autoTLS: Enabled - ... - ``` + ```shell + kubectl edit configmap config-certmanager --namespace knative-serving + ``` + +1. Add the `issuerRef` within the `data` section: + + ```shell + ... + data: + ... + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-issuer + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-certmanager + namespace: knative-serving + labels: + networking.knative.dev/certificate-provider: cert-manager + data: + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-http01-issuer + ``` + + `issueRef` defines which `ClusterIssuer` will be used by Knative to issue + certificates. + +1. Ensure that the file was updated successfully: + + ```shell + kubectl get configmap config-certmanager --namespace knative-serving --output yaml + ``` + +### Turn on Auto TLS + +Update the +[`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml) +in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP +requests are handled: + +1. Run the following command to edit your `config-network` ConfigMap: - 1. Configure how HTTP and HTTPS requests are handled in the - [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) - attribute. - - By default, Knative ingress is configured to serve HTTP traffic - (`httpProtocol: Enabled`). Now that your cluster is configured to use TLS - certificates and handle HTTPS traffic, you can specify whether or not any - HTTP traffic is allowed. - - Supported `httpProtocol` values: - - - `Enabled`: Serve HTTP traffic. - - `Disabled`: Rejects all HTTP traffic. - - `Redirected`: Responds to HTTP request with a `302` redirect to ask the - clients to use HTTPS. - - - ```shell - ... - data: - ... - autoTLS: Enabled - ... - ``` - - Example: - - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - autoTLS: Enabled - ... - httpProtocol: Redirected - ... - ``` - - 1. Ensure that the file was updated successfully: - - ```shell - kubectl get configmap config-network --namespace knative-serving --output yaml - ``` + ```shell + kubectl edit configmap config-network --namespace knative-serving + ``` + +1. Add the `autoTLS: Enabled` attribute under the `data` section: + + ```shell + ... + data: + ... + autoTLS: Enabled + ... + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + autoTLS: Enabled + ... + ``` + +1. Configure how HTTP and HTTPS requests are handled in the + [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) + attribute. + + By default, Knative ingress is configured to serve HTTP traffic + (`httpProtocol: Enabled`). Now that your cluster is configured to use TLS + certificates and handle HTTPS traffic, you can specify whether or not any + HTTP traffic is allowed. + + Supported `httpProtocol` values: + + - `Enabled`: Serve HTTP traffic. + - `Disabled`: Rejects all HTTP traffic. + - `Redirected`: Responds to HTTP request with a `302` redirect to ask the + clients to use HTTPS. + + ```shell + ... + data: + ... + autoTLS: Enabled + ... + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + autoTLS: Enabled + ... + httpProtocol: Redirected + ... + ``` + + **Note:** + When using HTTP-01 challenge, `httpProtocol` field has to be set to `Enabled` to make sure HTTP-01 challenge requests can be accepted by the cluster. + +1. Ensure that the file was updated successfully: + + ```shell + kubectl get configmap config-network --namespace knative-serving --output yaml + ``` Congratulations! Knative is now configured to obtain and renew TLS certificates. When your TLS certificate is active on your cluster, your Knative services will be able to handle HTTPS traffic. + +### Verify Auto TLS + +1. Run the following comand to create a Knative Service: + ```shell + kubectl apply -f https://raw.githubusercontent.com/knative/docs/master/docs/serving/samples/autoscale-go/service.yaml + ``` + +1. When the certificate is provisioned (which could take up to several minutes depending on + the challenge type), you should see something like: + ``` + NAME URL LATESTCREATED LATESTREADY READY REASON + autoscale-go https://autoscale-go.default.{custom-domain} autoscale-go-6jf85 autoscale-go-6jf85 True + ``` + + Note that the URL will be **https** in this case. \ No newline at end of file