From 01d226f9ce43ceada56f0dc402b5abd1456e6401 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Fri, 4 Jun 2021 15:18:09 -0500 Subject: [PATCH] Update installation docs and links --- docs/admin/install/README.md | 36 +-- .../eventing/eventing-installation-files.md | 20 ++ .../install-eventing-with-yaml.md | 174 +++++++++--- docs/admin/install/install-extensions.md | 263 ------------------ docs/admin/install/installation-files.md | 49 ---- docs/admin/install/knative-offerings.md | 11 +- docs/admin/install/knative-with-operators.md | 21 +- .../install-serving-with-yaml.md | 131 ++++++--- .../serving/serving-installation-files.md | 22 ++ .../install => snippets}/prerequisites.md | 6 +- mkdocs.yml | 27 +- 11 files changed, 312 insertions(+), 448 deletions(-) create mode 100644 docs/admin/install/eventing/eventing-installation-files.md rename docs/admin/install/{ => eventing}/install-eventing-with-yaml.md (53%) delete mode 100644 docs/admin/install/install-extensions.md delete mode 100644 docs/admin/install/installation-files.md rename docs/admin/install/{ => serving}/install-serving-with-yaml.md (73%) create mode 100644 docs/admin/install/serving/serving-installation-files.md rename docs/{admin/install => snippets}/prerequisites.md (87%) diff --git a/docs/admin/install/README.md b/docs/admin/install/README.md index 31e71634fa..20f0fab77a 100644 --- a/docs/admin/install/README.md +++ b/docs/admin/install/README.md @@ -1,38 +1,18 @@ ---- -title: "Installing Knative" -weight: 05 -type: "docs" -aliases: - - /docs/install/knative-with-any-k8s - - /docs/install/knative-with-aks - - /docs/install/knative-with-ambassador - - /docs/install/knative-with-contour - - /docs/install/knative-with-docker-for-mac - - /docs/install/knative-with-gke - - /docs/install/knative-with-gardener - - /docs/install/knative-with-gloo - - /docs/install/knative-with-icp - - /docs/install/knative-with-iks - - /docs/install/knative-with-microk8s - - /docs/install/knative-with-minikube - - /docs/install/knative-with-minishift - - /docs/install/knative-with-pks - - /docs/install/any-kubernetes-cluster -showlandingtoc: "false" ---- - # Installing Knative !!! tip - You can install a local distribution of Knative for development use by following the [Getting started guide](../getting-started/){_blank}. + You can install a local distribution of Knative for development use by following the [Getting started guide](../../getting-started/){_blank}. You can install the Serving component, Eventing component, or both on your cluster by using one of the following deployment options: -- Using a [YAML-based installation](./prerequisites) +- Using a YAML-based installation: + - [Install Knative Serving by using YAML](../install/serving/install-serving-with-yaml) + - [Install Knative Eventing by using YAML](../install/eventing/install-eventing-with-yaml) - Using the [Knative Operator](./knative-with-operators). -- Following the documentation for vendor managed [Knative offerings](../knative-offerings). +- Following the documentation for vendor managed [Knative offerings](../install/knative-offerings). -You can also [upgrade an existing Knative installation](./upgrade-installation). +You can also [upgrade an existing Knative installation](../upgrade/). -**NOTE:** Knative installation instructions assume you are running Mac or Linux with a bash shell. +!!! note + Knative installation instructions assume you are running Mac or Linux with a bash shell. diff --git a/docs/admin/install/eventing/eventing-installation-files.md b/docs/admin/install/eventing/eventing-installation-files.md new file mode 100644 index 0000000000..26e0c1a974 --- /dev/null +++ b/docs/admin/install/eventing/eventing-installation-files.md @@ -0,0 +1,20 @@ +# Knative Eventing installation files + +This guide provides reference information about the core Knative Eventing YAML files, including: + +- The custom resource definitions (CRDs) and core components required to install Knative Eventing. +- Optional components that you can apply to customize your installation. + +For information about installing these files, see [Installing Knative Eventing using YAML files](../install-eventing-with-yaml). + +The table below describes the installation files included in Knative Eventing: + +| File name | Description | Dependencies| +| --- | --- | --- | +| eventing-core.yaml | Required: Knative Eventing core components. | eventing-crds.yaml | +| eventing-crds.yaml | Required: Knative Eventing core CRDs. | none | +| eventing-post-install.yaml | Jobs required for upgrading to a new minor version. | eventing-core.yaml, eventing-crds.yaml | +| eventing-sugar-controller.yaml | Reconciler that watches for labels and annotations on certain resources to inject eventing components. | eventing-core.yaml | +| eventing.yaml | Combines `eventing-core.yaml`, `mt-channel-broker.yaml`, and `in-memory-channel.yaml`. | none | +| in-memory-channel.yaml | Components to configure In-Memory Channels. | eventing-core.yaml | +| mt-channel-broker.yaml | Components to configure Multi-Tenant (MT) Channel Broker. | eventing-core.yaml | diff --git a/docs/admin/install/install-eventing-with-yaml.md b/docs/admin/install/eventing/install-eventing-with-yaml.md similarity index 53% rename from docs/admin/install/install-eventing-with-yaml.md rename to docs/admin/install/eventing/install-eventing-with-yaml.md index ca1f21de2f..421cce4767 100644 --- a/docs/admin/install/install-eventing-with-yaml.md +++ b/docs/admin/install/eventing/install-eventing-with-yaml.md @@ -1,19 +1,8 @@ ---- -title: "Installing Knative Eventing using YAML files" -linkTitle: "Install Eventing using YAML" -weight: 03 -type: "docs" -showlandingtoc: "false" ---- - # Installing Knative Eventing using YAML files This topic describes how to install Knative Eventing by applying YAML files using the `kubectl` CLI. -## Prerequisites - -Before installation, you must meet the prerequisites. -See [Knative Prerequisites](./prerequisites.md). +--8<-- "prerequisites.md" ## Install the Eventing component @@ -32,13 +21,10 @@ To install the Eventing component: ``` !!! info - For information about the YAML files in the Knative Serving and Eventing releases, see - [Installation files](./installation-files.md). - + For information about the YAML files in Knative Eventing, see [Description Tables for YAML Files](./eventing-installation-files.md). ## Verify the installation - !!! success "Monitor the Knative components until all of the components show a `STATUS` of `Running` or `Completed`:" ```{ .bash .no-copy } @@ -56,9 +42,9 @@ Follow the procedure for the channel of your choice: === "Apache Kafka Channel" 1. First, - [Install Apache Kafka for Kubernetes](../eventing/samples/kafka/README.md) + [Install Apache Kafka for Kubernetes](../../../../eventing/samples/kafka) - 1. Then install the Apache Kafka channel: + 1. Then install the Apache Kafka Channel: ```bash curl -L "{{ artifact(org="knative-sandbox",repo="eventing-kafka",file="channel-consolidated.yaml")}}" \ @@ -68,8 +54,7 @@ Follow the procedure for the channel of your choice: !!! tip To learn more about the Apache Kafka channel, try - [our sample](../eventing/samples/kafka/channel/README.md) - + [our sample](../../../../eventing/samples/kafka/channel/) === "Google Cloud Pub/Sub Channel" @@ -107,8 +92,6 @@ Follow the procedure for the channel of your choice: - - ## Optional: Install a broker layer: The tabs below expand to show instructions for installing the broker layer. @@ -132,20 +115,18 @@ Follow the procedure for the broker of your choice: kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-broker.yaml")}} ``` - For more information, see the [Kafka broker](./../eventing/broker/kafka-broker/) documentation. + For more information, see the [Kafka broker](../../../../eventing/broker/kafka-broker/) documentation. === "MT-Channel-based" The following command installs an implementation of broker that utilizes - channels and runs event routing components in a System Namespace, providing a - smaller and simpler installation. + channels and runs event routing components in a System Namespace, providing a smaller and simpler installation. ```bash kubectl apply -f {{ artifact(repo="eventing",file="mt-channel-broker.yaml")}} ``` - To customize which broker channel implementation is used, update the following - ConfigMap to specify which configurations are used for which namespaces: + To customize which broker channel implementation is used, update the following ConfigMap to specify which configurations are used for which namespaces: ```yaml apiVersion: v1 @@ -175,8 +156,7 @@ Follow the procedure for the broker of your choice: namespace: knative-eventing ``` - The referenced `imc-channel` and `kafka-channel` example ConfigMaps would look - like: + The referenced `imc-channel` and `kafka-channel` example ConfigMaps would look like: ```yaml apiVersion: v1 @@ -213,12 +193,138 @@ Follow the procedure for the broker of your choice: For more information, see the [RabbitMQ broker](https://github.com/knative-sandbox/eventing-rabbitmq) in GitHub. -## Next steps +## Install optional Eventing extensions + +The tabs below expand to show instructions for installing each Eventing extension. + + +=== "Apache Kafka Sink" + + 1. Install the Kafka controller: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-controller.yaml")}} + ``` + + 1. Install the Kafka Sink data plane: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-sink.yaml")}} + ``` + + For more information, see the [Kafka Sink](../../../eventing/sink/kafka-sink.md) documentation. + +=== "Sugar Controller" + + + + The following command installs the Eventing Sugar Controller: + + ```bash + kubectl apply -f {{ artifact(repo="eventing",file="eventing-sugar-controller.yaml")}} + ``` + + The Knative Eventing Sugar Controller will react to special labels and + annotations and produce Eventing resources. For example: -After installing Knative Eventing: + - When a Namespace is labeled with `eventing.knative.dev/injection=enabled`, the + controller will create a default broker in that namespace. + - When a Trigger is annotated with `eventing.knative.dev/injection=enabled`, the + controller will create a Broker named by that Trigger in the Trigger's + Namespace. -- To easily interact with Knative Eventing components, [install the `kn` CLI](/docs/client/install-kn.md) + The following command enables the default Broker on a namespace (here + `default`): -- To add optional enhancements to your installation, see [Installing optional extensions](./install-extensions.md) + ```bash + kubectl label namespace default eventing.knative.dev/injection=enabled + ``` + +=== "Github Source" + + The following command installs the single-tenant Github source: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-github",file="github.yaml")}} + ``` + + The single-tenant GitHub source creates one Knative service per GitHub source. + + The following command installs the multi-tenant GitHub source: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-github",file="mt-github.yaml")}} + ``` + + The multi-tenant GitHub source creates only one Knative service handling all + GitHub sources in the cluster. This source does not support logging or tracing + configuration yet. + + To learn more about the Github source, try + [our sample](../../../../eventing/sources/github-source/) + +=== "Apache Camel-K Source" + + The following command installs the Apache Camel-K Source: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-camel",file="camel.yaml")}} + ``` + + To learn more about the Apache Camel-K source, try + [our sample](../../../../eventing/sources/apache-camel-source/) + +=== "Apache Kafka Source" + + The following command installs the Apache Kafka Source: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka",file="source.yaml")}} + ``` + + To learn more about the Apache Kafka source, try + [our sample](../../../../eventing/sources/kafka-source) + + +=== "GCP Sources" + + The following command installs the GCP Sources: + + ```bash + # This installs both the Sources and the Channel. + kubectl apply -f {{ artifact(org="google",repo="knative-gcp",file="cloud-run-events.yaml")}} + ``` + + To learn more about the Cloud Pub/Sub source, try + [our sample](../../../../eventing/sources/cloud-pubsub-source). + + To learn more about the Cloud Storage source, try + [our sample](../../../../eventing/sources/cloud-storage-source). + + To learn more about the Cloud Scheduler source, try + [our sample](../../../../eventing/sources/cloud-scheduler-source). + + To learn more about the Cloud Audit Logs source, try + [our sample](../../../../eventing/sources/cloud-audit-logs-source). + + +=== "Apache CouchDB Source" + + The following command installs the Apache CouchDB Source: + + ```bash + kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-couchdb",file="couchdb.yaml")}} + ``` + + To learn more about the Apache CouchDB source, read the [documentation](https://github.com/knative-sandbox/eventing-couchdb/blob/main/source/README.md). + +=== "VMware Sources and Bindings" + + The following command installs the VMware Sources and Bindings: + + ```bash + kubectl apply -f {{ artifact(org="vmware-tanzu",repo="sources-for-knative",file="release.yaml")}} + ``` -- [Installing Knative Serving using YAML files](./install-serving-with-yaml.md) + To learn more about the VMware sources and bindings, try + [our samples](https://github.com/vmware-tanzu/sources-for-knative/tree/master/samples/README.md). diff --git a/docs/admin/install/install-extensions.md b/docs/admin/install/install-extensions.md deleted file mode 100644 index bb4754ae69..0000000000 --- a/docs/admin/install/install-extensions.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: "Installing optional extensions" -linkTitle: "Install optional extensions" -weight: 04 -type: "docs" -showlandingtoc: "false" ---- - -# Installing optional extensions - -To add extra features to your Knative Serving or Eventing installation, you can install extensions -by applying YAML files using the `kubectl` CLI. - -For information about the YAML files in the Knative Serving and Eventing releases, see -[Installation files](./installation-files.md). - - -## Prerequisites - -Before you install any optional extensions, you must install Knative Serving or Eventing. -See [Installing Serving using YAML files](./install-serving-with-yaml.md) -and [Installing Eventing using YAML files](./install-eventing-with-yaml.md). - - -## Install optional Serving extensions - -The tabs below expand to show instructions for installing each Serving extension. - -=== "HPA autoscaling" - - Knative also supports the use of the Kubernetes Horizontal Pod Autoscaler (HPA) - for driving autoscaling decisions. The following command will install the - components needed to support HPA-class autoscaling: - - ```bash - kubectl apply -f {{ artifact(repo="serving",file="serving-hpa.yaml")}} - ``` - - - - -=== "TLS with cert-manager" - - Knative supports automatically provisioning TLS certificates via - [cert-manager](https://cert-manager.io/docs/). The following commands will - install the components needed to support the provisioning of TLS certificates - via cert-manager. - - 1. First, install - [cert-manager version `v1.0.0` or higher](../serving/installing-cert-manager.md) - - 2. Next, install the component that integrates Knative with cert-manager: - - ```bash - kubectl apply -f {{ artifact(repo="net-certmanager",file="release.yaml")}} - ``` - - 3. Now configure Knative to - [automatically configure TLS certificates](../serving/using-auto-tls.md). - -=== "TLS via HTTP01" - - Knative supports automatically provisioning TLS certificates using Let's Encrypt - HTTP01 challenges. The following commands will install the components needed to - support that. - - 1. First, install the `net-http01` controller: - - ```bash - kubectl apply -f {{ artifact(repo="net-http01",file="release.yaml")}} - ``` - - 2. Next, configure the `certificate.class` to use this certificate type. - - ```bash - kubectl patch configmap/config-network \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"certificate.class":"net-http01.certificate.networking.knative.dev"}}' - ``` - - 3. Lastly, enable auto-TLS. - - ```bash - kubectl patch configmap/config-network \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"autoTLS":"Enabled"}}' - ``` - - -=== "TLS wildcard support" - - If you are using a Certificate implementation that supports provisioning - wildcard certificates (e.g. cert-manager with a DNS01 issuer), then the most - efficient way to provision certificates is with the namespace wildcard - certificate controller. The following command will install the components needed - to provision wildcard certificates in each namespace: - - ```bash - kubectl apply -f {{ artifact(repo="serving",file="serving-nscert.yaml")}} - ``` - - !!! warning - Note this will not work with HTTP01 either via cert-manager or the net-http01 - options. - - -=== "DomainMapping CRD" - - The `DomainMapping` CRD allows a user to map a Domain Name that they own to a - specific Knative Service. - - ```bash - kubectl apply -f {{ artifact(repo="serving",file="serving-domainmapping-crds.yaml")}} - kubectl apply -f {{ artifact(repo="serving",file="serving-domainmapping.yaml")}} - ``` - - -## Install optional Eventing extensions - -The tabs below expand to show instructions for installing each Eventing extension. - - -=== "Apache Kafka Sink" - - 1. Install the Kafka controller: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-controller.yaml")}} - ``` - - 1. Install the Kafka Sink data plane: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-sink.yaml")}} - ``` - - For more information, see the [Kafka Sink](./../eventing/sink/kafka-sink.md) documentation. - -=== "Sugar Controller" - - - - The following command installs the Eventing Sugar Controller: - - ```bash - kubectl apply -f {{ artifact(repo="eventing",file="eventing-sugar-controller.yaml")}} - ``` - - The Knative Eventing Sugar Controller will react to special labels and - annotations and produce Eventing resources. For example: - - - When a Namespace is labeled with `eventing.knative.dev/injection=enabled`, the - controller will create a default broker in that namespace. - - When a Trigger is annotated with `eventing.knative.dev/injection=enabled`, the - controller will create a Broker named by that Trigger in the Trigger's - Namespace. - - The following command enables the default Broker on a namespace (here - `default`): - - ```bash - kubectl label namespace default eventing.knative.dev/injection=enabled - ``` - - -=== "Github Source" - - The following command installs the single-tenant Github source: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-github",file="github.yaml")}} - ``` - - The single-tenant GitHub source creates one Knative service per GitHub source. - - The following command installs the multi-tenant GitHub source: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-github",file="mt-github.yaml")}} - ``` - - The multi-tenant GitHub source creates only one Knative service handling all - GitHub sources in the cluster. This source does not support logging or tracing - configuration yet. - - To learn more about the Github source, try - [our sample](../eventing/sources/github-source/README.md) - - -=== "Apache Camel-K Source" - - The following command installs the Apache Camel-K Source: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-camel",file="camel.yaml")}} - ``` - - To learn more about the Apache Camel-K source, try - [our sample](../eventing/sources/apache-camel-source/README.md) - - -=== "Apache Kafka Source" - - The following command installs the Apache Kafka Source: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka",file="source.yaml")}} - ``` - - To learn more about the Apache Kafka source, try - [our sample](../eventing/sources/kafka-source/README.md) - - -=== "GCP Sources" - - The following command installs the GCP Sources: - - ```bash - # This installs both the Sources and the Channel. - kubectl apply -f {{ artifact(org="google",repo="knative-gcp",file="cloud-run-events.yaml")}} - ``` - - To learn more about the Cloud Pub/Sub source, try - [our sample](../eventing/sources/cloud-pubsub-source/README.md). - - To learn more about the Cloud Storage source, try - [our sample](../eventing/sources/cloud-storage-source/README.md). - - To learn more about the Cloud Scheduler source, try - [our sample](../eventing/sources/cloud-scheduler-source/README.md). - - To learn more about the Cloud Audit Logs source, try - [our sample](../eventing/sources/cloud-audit-logs-source/README.md). - - -=== "Apache CouchDB Source" - - The following command installs the Apache CouchDB Source: - - ```bash - kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-couchdb",file="couchdb.yaml")}} - ``` - - To learn more about the Apache CouchDB source, read the [documentation](https://github.com/knative-sandbox/eventing-couchdb/blob/main/source/README.md). - - -=== "VMware Sources and Bindings" - - The following command installs the VMware Sources and Bindings: - - ```bash - kubectl apply -f {{ artifact(org="vmware-tanzu",repo="sources-for-knative",file="release.yaml")}} - ``` - - To learn more about the VMware sources and bindings, try - [our samples](https://github.com/vmware-tanzu/sources-for-knative/tree/master/samples/README.md). - - -## Next steps - -- To easily interact with Knative Services and Eventing components, [install the `kn` CLI](/docs/client/install-kn.md) diff --git a/docs/admin/install/installation-files.md b/docs/admin/install/installation-files.md deleted file mode 100644 index f8a87c80c6..0000000000 --- a/docs/admin/install/installation-files.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Installation files" -weight: 20 -type: "docs" ---- - -# Installation files - -This guide provides reference information about the YAML files in the Knative -Serving and Eventing releases. - -The YAML files in the releases include: - -- The custom resource definitions (CRDs) and core components required to install Knative. -- Optional components that you can apply to customize your installation. - -For information about installing these files, see [Installing Serving using YAML files](./install-serving-with-yaml) -and [Installing Eventing using YAML files](./install-eventing-with-yaml). - -## Knative Serving installation files - -The table below describes the installation files in the Knative Serving release: - -| File name | Description | Dependencies| -| --- | --- | --- | -| serving-core.yaml | Required: Knative Serving core components. | serving-crds.yaml | -| serving-crds.yaml | Required: Knative Serving core CRDs. | none | -| serving-default-domain.yaml | Configures Knative Serving to use [http://sslip.io](http://sslip.io) as the default DNS suffix. | serving-core.yaml | -| serving-domainmapping-crds.yaml | CRDs used by the Domain Mapping feature. | none | -| serving-domainmapping.yaml | Components used by the Domain Mapping feature. | serving-domainmapping-crds.yaml | -| serving-hpa.yaml | Components to autoscale Knative revisions through the Kubernetes Horizontal Pod Autoscaler. | serving-core.yaml | - serving-nscert.yaml | Components to provision TLS wildcard certificates. | serving-core.yaml | -| serving-post-install-jobs.yaml | Additional jobs after installing `serving-core.yaml`. Currently it is the same as `serving-storage-version-migration.yaml`. | serving-core.yaml | -| serving-storage-version-migration.yaml | Migrates the storage version of Knative resources, including Service, Route, Revision, and Configuration, from `v1alpha1` and `v1beta1` to `v1`. Required by upgrade from version 0.18 to 0.19. | serving-core.yaml | - - -## Knative Eventing installation files - -The table below describes the installation files in the Knative Eventing release: - -| File name | Description | Dependencies| -| --- | --- | --- | -| eventing-core.yaml | Required: Knative Eventing core components. | eventing-crds.yaml | -| eventing-crds.yaml | Required: Knative Eventing core CRDs. | none | -| eventing-post-install.yaml | Jobs required for upgrading to a new minor version. | eventing-core.yaml, eventing-crds.yaml | -| eventing-sugar-controller.yaml | Reconciler that watches for labels and annotations on certain resources to inject eventing components. | eventing-core.yaml | -| eventing.yaml | Combines `eventing-core.yaml`, `mt-channel-broker.yaml`, and `in-memory-channel.yaml`. | none | -| in-memory-channel.yaml | Components to configure In-Memory Channels. | eventing-core.yaml | -| mt-channel-broker.yaml | Components to configure Multi-Tenant (MT) Channel Broker. | eventing-core.yaml | diff --git a/docs/admin/install/knative-offerings.md b/docs/admin/install/knative-offerings.md index 603e1fa47d..21e1748c2e 100644 --- a/docs/admin/install/knative-offerings.md +++ b/docs/admin/install/knative-offerings.md @@ -1,10 +1,3 @@ ---- -title: "Knative Offerings" -linkTitle: "Knative Offerings" -weight: 15 -type: "docs" ---- - # Knative Offerings Knative has a rich community with many vendors participating, and many of those @@ -15,11 +8,11 @@ vendors for what is or is not supported. Here is a list of commercial Knative products (alphabetically): -- [Gardener](https://gardener.cloud/documentation/050-tutorials/content/howto/knative-install/): Install Knative in Gardener's vanilla Kubernetes clusters to add an extra layer of serverless runtime. +- [Gardener](https://gardener.cloud/documentation/tutorials/knative-install/): Install Knative in Gardener's vanilla Kubernetes clusters to add an extra layer of serverless runtime. - [Google Cloud Run for Anthos](https://cloud.google.com/run/docs/gke/setup): Extend Google Kubernetes Engine with a flexible serverless development platform. With Cloud Run for Anthos, you get the operational flexibility of Kubernetes with the developer experience of serverless, allowing you to deploy and manage Knative-based services on your own cluster, and trigger them with events from Google, 3rd-party sources, and your own applications. - [Google Cloud Run](https://cloud.google.com/run/docs/setup): A fully-managed Knative-based serverless platform. With no Kubernetes cluster to manage, Cloud Run lets you go from container to production in seconds. - [IBM Cloud Code Engine](https://cloud.ibm.com/codeengine): A fully-managed serverless platform that runs all your containerized workloads, including http-driven application, batch jobs or event-driven functions. -- [Red Hat Openshift Serverless](https://docs.openshift.com/container-platform/4.6/serverless/serverless-getting-started.html): enables stateful, stateless, and serverless workloads to all run on a single multi-cloud container platform with automated operations. Developers can use a single platform for hosting their microservices, legacy, and serverless applications. +- [Red Hat Openshift Serverless](https://docs.openshift.com/container-platform/4.7/serverless/serverless-getting-started.html): enables stateful, stateless, and serverless workloads to all run on a single multi-cloud container platform with automated operations. Developers can use a single platform for hosting their microservices, legacy, and serverless applications. - [TriggerMesh Cloud](https://cloud.triggermesh.io): A fully-managed Knative and Tekton cloud-native integration platform. With support for AWS, Azure and Google event sources and brokers. diff --git a/docs/admin/install/knative-with-operators.md b/docs/admin/install/knative-with-operators.md index 0d043ac5af..062cd48413 100644 --- a/docs/admin/install/knative-with-operators.md +++ b/docs/admin/install/knative-with-operators.md @@ -1,27 +1,12 @@ ---- -title: "Knative Operator installation" -weight: 05 -type: "docs" -showlandingtoc: "false" ---- - # Knative Operator installation Knative provides a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) to install, configure and manage Knative. You can install the Serving component, Eventing component, or both on your cluster. -**NOTE:** The Knative Operator is still in Alpha phase. It has not been tested in a production environment, and should be used -for development or test purposes only. - -## Prerequisites +!!! warning + The Knative Operator is still in Alpha phase. It has not been tested in a production environment, and should be used for development or test purposes only. -- You have a cluster that uses Kubernetes v1.18 or newer. -- You have installed the `kubectl` CLI. -- If you have only one node in your cluster, you will need at least 6 CPUs, 6 GB of memory, and 30 GB of disk storage. -- If you have multiple nodes in your cluster, for each node you will need at least 2 CPUs, 4 GB of memory, and 20 GB of disk storage. -- Your Kubernetes cluster must have access to the internet, since Kubernetes needs to be able to fetch images, such as `gcr.io/knative-releases/knative.dev/operator/cmd/operator:`. - -- You have installed [Istio](./installing-istio.md). +--8<-- "prerequisites.md" ## Installing the latest release diff --git a/docs/admin/install/install-serving-with-yaml.md b/docs/admin/install/serving/install-serving-with-yaml.md similarity index 73% rename from docs/admin/install/install-serving-with-yaml.md rename to docs/admin/install/serving/install-serving-with-yaml.md index 34f6c8c5b3..d667220da5 100644 --- a/docs/admin/install/install-serving-with-yaml.md +++ b/docs/admin/install/serving/install-serving-with-yaml.md @@ -1,19 +1,8 @@ ---- -title: "Installing Knative Serving using YAML files" -linkTitle: "Install Serving using YAML" -weight: 02 -type: "docs" -showlandingtoc: "false" ---- - # Installing Knative Serving using YAML files This topic describes how to install Knative Serving by applying YAML files using the `kubectl` CLI. -## Prerequisites - -Before installation, you must meet the prerequisites. -See [Knative Prerequisites](./prerequisites.md). +--8<-- "prerequisites.md" ## Install the Serving component @@ -32,9 +21,7 @@ To install the serving component: ``` !!! info - For information about the YAML files in the Knative Serving and Eventing releases, see - [Description Tables for YAML Files](./installation-files.md). - + For information about the YAML files in Knative Serving, see [Description Tables for YAML Files](./serving-installation-files.md). ## Install a networking layer @@ -197,7 +184,7 @@ Follow the procedure for the networking layer of your choice: The following commands install Istio and enable its Knative integration. - 1. Install a properly configured Istio ([Advanced installation](./installing-istio.md)) + 1. Install a properly configured Istio ([Advanced installation](../installing-istio.md)) ```bash kubectl apply -f {{ artifact(repo="net-istio",file="istio.yaml")}} @@ -218,7 +205,6 @@ Follow the procedure for the networking layer of your choice: !!! tip Save this to use in the `Configure DNS` section. - === "Kong" The following commands install Kong and enable its Knative integration. @@ -247,8 +233,6 @@ Follow the procedure for the networking layer of your choice: !!! tip Save this to use in the `Configure DNS` section. - - ## Verify the installation !!! success "Monitor the Knative components until all of the components show a `STATUS` of `Running` or `Completed`:" @@ -257,7 +241,6 @@ Follow the procedure for the networking layer of your choice: kubectl get pods --namespace knative-serving ``` - ## Configure DNS You can configure DNS to prevent the need to run curl commands with a host header. @@ -290,19 +273,21 @@ Follow the procedure for the DNS of your choice: 1. If the networking layer produced an External IP address, then configure a wildcard `A` record for the domain: - ```bash - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == A 35.233.41.212 - ``` - 1. If the networking layer produced a CNAME, then configure a CNAME record for - the domain: + ```bash + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == A 35.233.41.212 + ``` + + 1. If the networking layer produced a CNAME, then configure a CNAME record for the domain: + ```bash # Here knative.example.com is the domain suffix for your cluster *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com ``` 1. Once your DNS provider has been configured, direct Knative to use that domain: + ```bash # Replace knative.example.com with your domain suffix kubectl patch configmap/config-domain \ @@ -324,6 +309,7 @@ Follow the procedure for the DNS of your choice: To access your application using `curl` using this method: 1. After starting your application, get the URL of your application: + ```bash kubectl get ksvc ``` @@ -338,9 +324,8 @@ Follow the procedure for the DNS of your choice: 1. Instruct `curl` to connect to the External IP or CNAME defined by the networking layer in section 3 above, and use the `-H "Host:"` command-line option to specify the Knative application's host name. For example, if the - networking layer defines your External IP and port to be - `http://192.168.39.228:32198` and you wish to access the above - `helloworld-go` application, use: + networking layer defines your External IP and port to be `http://192.168.39.228:32198` and you wish to access the above `helloworld-go` application, use: + ```bash curl -H "Host: helloworld-go.default.example.com" http://192.168.39.228:32198 ``` @@ -355,12 +340,90 @@ Follow the procedure for the DNS of your choice: Refer to the "Real DNS" method for a permanent solution. -## Next steps +## Install optional Serving extensions + +The tabs below expand to show instructions for installing each Serving extension. + +=== "HPA autoscaling" + + Knative also supports the use of the Kubernetes Horizontal Pod Autoscaler (HPA) + for driving autoscaling decisions. The following command will install the + components needed to support HPA-class autoscaling: + + ```bash + kubectl apply -f {{ artifact(repo="serving",file="serving-hpa.yaml")}} + ``` + + + +=== "TLS with cert-manager" + + Knative supports automatically provisioning TLS certificates via + [cert-manager](https://cert-manager.io/docs/). The following commands will + install the components needed to support the provisioning of TLS certificates + via cert-manager. + + 1. First, install [cert-manager version `v1.0.0` or higher](../../../../serving/installing-cert-manager) + + 1. Next, install the component that integrates Knative with `cert-manager`: + + ```bash + kubectl apply -f {{ artifact(repo="net-certmanager",file="release.yaml")}} + ``` + + 1. Now configure Knative to + [automatically configure TLS certificates](../../../../serving/using-auto-tls). + +=== "TLS via HTTP01" + + Knative supports automatically provisioning TLS certificates using Encrypt HTTP01 challenges. The following commands will install the components needed to support TLS. + + 1. Install the `net-http01` controller: + + ```bash + kubectl apply -f {{ artifact(repo="net-http01",file="release.yaml")}} + ``` + + 2. Configure the `certificate.class` to use this certificate type: + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"certificate.class":"net-http01.certificate.networking.knative.dev"}}' + ``` + + 3. Enable auto-TLS. + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"autoTLS":"Enabled"}}' + ``` -After installing Knative Serving: -- [Installing Knative Eventing using YAML files](./install-eventing-with-yaml.md) +=== "TLS wildcard support" -- To add optional enhancements to your installation, see [Installing optional extensions](./install-extensions.md). + If you are using a Certificate implementation that supports provisioning + wildcard certificates (e.g. cert-manager with a DNS01 issuer), then the most + efficient way to provision certificates is with the namespace wildcard + certificate controller. The following command will install the components needed + to provision wildcard certificates in each namespace: -- To easily interact with Knative Services, [install the `kn` CLI](/docs/client/install-kn.md) + ```bash + kubectl apply -f {{ artifact(repo="serving",file="serving-nscert.yaml")}} + ``` + + !!! warning + Note this will not work with HTTP01 either via cert-manager or the net-http01 + options. + +=== "DomainMapping CRD" + + The `DomainMapping` CRD allows a user to map a Domain Name that they own to a specific Knative Service. + + ```bash + kubectl apply -f {{ artifact(repo="serving",file="serving-domainmapping-crds.yaml")}} + kubectl apply -f {{ artifact(repo="serving",file="serving-domainmapping.yaml")}} + ``` diff --git a/docs/admin/install/serving/serving-installation-files.md b/docs/admin/install/serving/serving-installation-files.md new file mode 100644 index 0000000000..e03bc1e518 --- /dev/null +++ b/docs/admin/install/serving/serving-installation-files.md @@ -0,0 +1,22 @@ +# Knative Serving installation files + +This guide provides reference information about the core Knative Serving YAML files, including: + +- The custom resource definitions (CRDs) and core components required to install Knative Serving. +- Optional components that you can apply to customize your installation. + +For information about installing these files, see [Installing Knative Serving using YAML files](../install-serving-with-yaml). + +The table below describes the installation files included in Knative Serving: + +| File name | Description | Dependencies| +| --- | --- | --- | +| serving-core.yaml | Required: Knative Serving core components. | serving-crds.yaml | +| serving-crds.yaml | Required: Knative Serving core CRDs. | none | +| serving-default-domain.yaml | Configures Knative Serving to use [http://sslip.io](http://sslip.io) as the default DNS suffix. | serving-core.yaml | +| serving-domainmapping-crds.yaml | CRDs used by the Domain Mapping feature. | none | +| serving-domainmapping.yaml | Components used by the Domain Mapping feature. | serving-domainmapping-crds.yaml | +| serving-hpa.yaml | Components to autoscale Knative revisions through the Kubernetes Horizontal Pod Autoscaler. | serving-core.yaml | + serving-nscert.yaml | Components to provision TLS wildcard certificates. | serving-core.yaml | +| serving-post-install-jobs.yaml | Additional jobs after installing `serving-core.yaml`. Currently it is the same as `serving-storage-version-migration.yaml`. | serving-core.yaml | +| serving-storage-version-migration.yaml | Migrates the storage version of Knative resources, including Service, Route, Revision, and Configuration, from `v1alpha1` and `v1beta1` to `v1`. Required by upgrade from version 0.18 to 0.19. | serving-core.yaml | diff --git a/docs/admin/install/prerequisites.md b/docs/snippets/prerequisites.md similarity index 87% rename from docs/admin/install/prerequisites.md rename to docs/snippets/prerequisites.md index e1af45199b..956e08a458 100644 --- a/docs/admin/install/prerequisites.md +++ b/docs/snippets/prerequisites.md @@ -1,18 +1,18 @@ -# Prerequisites +## Prerequisites Before installing Knative, you must meet the following prerequisites: - **For prototyping purposes**, Knative will work on most local deployments of Kubernetes. For example, you can use a local, one-node cluster that has 2 CPU and 4GB of memory. !!! tip - You can install a local distribution of Knative for development use by following the [Getting started guide](../../../getting-started/){_blank}. + You can install a local distribution of Knative for development use by following the [Getting started guide](../../../../getting-started/){_blank}. - **For production purposes**, it is recommended that: - If you have only one node in your cluster, you will need at least 6 CPUs, 6 GB of memory, and 30 GB of disk storage. - If you have multiple nodes in your cluster, for each node you will need at least 2 CPUs, 4 GB of memory, and 20 GB of disk storage. - You have a cluster that uses Kubernetes v1.18 or newer. - You have installed the [`kubectl` CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -- Your Kubernetes cluster must have access to the internet, since Kubernetes needs to be able to fetch images. To pull from a private registry, see [Deploying images from a private container registry](../../../serving/deploying-from-private-registry). +- Your Kubernetes cluster must have access to the internet, since Kubernetes needs to be able to fetch images. To pull from a private registry, see [Deploying images from a private container registry](../../../../serving/deploying-from-private-registry). !!! caution The system requirements provided are recommendations only. The requirements for your installation may vary, depending on whether you use optional components, such as a networking layer. diff --git a/mkdocs.yml b/mkdocs.yml index 6b6a1285c9..cbe64ed1cf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,17 +27,22 @@ nav: - Overview: admin/README.md - Installing Knative: - Overview: admin/install/README.md - - Prerequisites: admin/install/prerequisites.md - - Installing using YAML: - - Install Serving with YAML: admin/install/install-serving-with-yaml.md - - Install Eventing with YAML: admin/install/install-eventing-with-yaml.md - - Install optional extensions: admin/install/install-extensions.md - - Description Tables for YAML Files: admin/install/installation-files.md + # Serving Installation + - Install Knative Serving: + - Install Serving with YAML: admin/install/serving/install-serving-with-yaml.md + - Knative Serving installation files: admin/install/serving/serving-installation-files.md + # Eventing Installation + - Install Knative Eventing: + - Install Eventing with YAML: admin/install/eventing/install-eventing-with-yaml.md + - Knative Eventing installation files: admin/install/eventing/eventing-installation-files.md + # Operator Installation - Knative Operator: - Installing with the Operator: admin/install/knative-with-operators.md - Configuring Knative Eventing CRDs: admin/install/operator/configuring-eventing-cr.md - Configuring Knative Serving CRDs: admin/install/operator/configuring-serving-cr.md + # Istio Installation - Installing Istio for Knative: admin/install/installing-istio.md + # Vendor docs - Using a Knative-based Offering: admin/install/knative-offerings.md - ... | install/* - Checking your Knative version: check-install-version.md @@ -292,6 +297,8 @@ plugins: # Redirects - redirects: redirect_maps: + 'admin/install/install-serving-with-yaml.md': 'admin/install/serving/install-serving-with-yaml.md' + 'admin/install/install-eventing-with-yaml.md': 'admin/install/eventing/install-eventing-with-yaml.md' 'serving/services/deployment.md': 'admin/serving/deployment.md' 'serving/debugging-application-issues.md': 'developer/serving/troubleshooting/debugging-application-issues.md' 'serving/creating-domain-mappings.md': 'developer/serving/services/custom-domains.md' @@ -299,16 +306,16 @@ plugins: 'install/collecting-logs/index.md': 'admin/collecting-logs/README.md' 'install/README.md': 'admin/install/README.md' 'install/collecting-metrics/index.md': 'admin/collecting-metrics/README.md' - 'install/install-eventing-with-yaml.md': 'admin/install/install-eventing-with-yaml.md' + 'install/install-eventing-with-yaml.md': 'admin/install/eventing/install-eventing-with-yaml.md' 'install/install-extensions.md': 'admin/install/install-extensions.md' - 'install/install-serving-with-yaml.md': 'admin/install/install-serving-with-yaml.md' - 'install/installation-files.md': 'admin/install/installation-files.md' + 'install/install-serving-with-yaml.md': 'admin/install/serving/install-serving-with-yaml.md' + 'install/installation-files.md': 'admin/install/README.md' 'install/installing-istio.md': 'admin/install/installing-istio.md' 'install/knative-offerings.md': 'admin/install/knative-offerings.md' 'install/knative-with-operators.md': 'admin/install/knative-with-operators.md' 'install/operator/configuring-eventing-cr.md': 'admin/install/operator/configuring-eventing-cr.md' 'install/operator/configuring-serving-cr.md': 'admin/install/operator/configuring-serving-cr.md' - 'install/prerequisites.md': 'admin/install/prerequisites.md' + 'install/prerequisites.md': 'admin/install/README.md' 'uninstall.md': 'admin/install/uninstall.md' 'upgrade/index.md': 'admin/upgrade/README.md' 'upgrade/upgrade-installation-with-operator.md': 'admin/upgrade/upgrade-installation-with-operator.md'