diff --git a/config/nav.yml b/config/nav.yml index f7cc51fde..3c4228861 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -40,10 +40,10 @@ nav: - Knative Eventing installation files: install/eventing/eventing-installation-files.md # Operator Installation - Install with Knative Operator: - - Installing with the Operator: install/operator/knative-with-operators.md - - Configuring Knative by using the Operator: install/operator/configuring-with-operator.md - - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md + - Installing using the Operator: install/operator/knative-with-operators.md + - Configuring Knative using the Operator: install/operator/configuring-with-operator.md - Configuring Knative Serving CRDs: install/operator/configuring-serving-cr.md + - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md # kn Installation - Install the Knative CLI: - CLI tools overview: install/client/README.md diff --git a/docs/install/operator/knative-with-operators.md b/docs/install/operator/knative-with-operators.md index 9bec4c1c0..dfb1f9d55 100644 --- a/docs/install/operator/knative-with-operators.md +++ b/docs/install/operator/knative-with-operators.md @@ -1,62 +1,67 @@ -# Knative Operator installation +# Installing Knative using the Operator 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. --8<-- "prerequisites.md" -## Installing the latest release +## Install the Knative Operator -You can find information about the different released versions of the Knative Operator on the [Releases page](https://github.com/knative/operator/releases). +Before you install the Knative Serving and Eventing components, first install the Knative Operator. -Install the latest stable Operator release: +### Install the latest Knative Operator release -``` +To install the latest stable Operator release, run the command: + +```bash kubectl apply -f {{artifact(org="knative",repo="operator",file="operator.yaml" )}} ``` -## Verify your installation +You can find information about the released versions of the Knative Operator on the [releases page](https://github.com/knative/operator/releases). +### Verify your Knative Operator installation -1. Because the operator is installed to the `default` namespace, ensure you set the current namespace to `default` by running the command: +1. Because the Operator is installed to the `default` namespace, ensure you set the current namespace to `default` by running the command: - ``` + ```bash kubectl config set-context --current --namespace=default ``` -1. Check the operator deployment status by running the command: +1. Check the Operator deployment status by running the command: - ``` + ```bash kubectl get deployment knative-operator ``` -If the operator is installed correctly, the deployment shows a `Ready` status: + If the Operator is installed correctly, the deployment shows a `Ready` status: -``` -NAME READY UP-TO-DATE AVAILABLE AGE -knative-operator 1/1 1 1 19h -``` + ```{.bash .no-copy} + NAME READY UP-TO-DATE AVAILABLE AGE + knative-operator 1/1 1 1 19h + ``` -## Track the log +### Track the log -Track the log of the operator: +To track the log of the Operator, run the command: -``` +```bash kubectl logs -f deploy/knative-operator ``` ## Installing the Knative Serving component -### Create and apply the Knative Serving CR: +To install Knative Serving you must create a custom resource (CR), add a networking +layer to the CR, and configure DNS. -!!! note "Install Current Serving" +### Create the Knative Serving custom resource - === "Install Current Serving (default)" +=== "Install the current version (default)" - You can install the latest available Knative Serving in the - operator by applying a YAML file containing the following: + To create the custom resource for the latest available Knative Serving in the Operator: - ``` + 1. Copy the following YAML into a file: + + ```yaml apiVersion: v1 kind: Namespace metadata: @@ -68,16 +73,25 @@ kubectl logs -f deploy/knative-operator name: knative-serving namespace: knative-serving ``` + !!! note + When you don't specify a version by using `spec.version` field, the Operator defaults to the latest available version. - If you do not specify a version by using spec_version, the operator defaults to the latest available version. - - === "Install Future Knative Serving" - - You do not need to upgrade the operator to a newer version to install - new releases of Knative Serving. If Knative Serving launches a new version, e.g. `$spec_version`, you can install it by - applying a YAML file containing the following: + 1. Apply the YAML file by running the command: + ```bash + kubectl apply -f .yaml ``` + + Where `` is the name of the file you created in the previous step. + +=== "Install another version of Knative Serving" + + You can install a new release of Knative Serving without upgrading the Operator. + To install a new version of Knative Serving: + + 1. Create a YAML file containing the following: + + ```yaml apiVersion: v1 kind: Namespace metadata: @@ -89,94 +103,173 @@ kubectl logs -f deploy/knative-operator name: knative-serving namespace: knative-serving spec: - version: $spec_version + version: "" manifests: - URL: https://github.com/knative/serving/releases/download/v${VERSION}/serving-core.yaml - URL: https://github.com/knative/serving/releases/download/v${VERSION}/serving-hpa.yaml - URL: https://github.com/knative/serving/releases/download/v${VERSION}/serving-post-install-jobs.yaml - URL: https://github.com/knative/net-istio/releases/download/v${VERSION}/net-istio.yaml ``` + - The field `$spec_version` is used to set the version of Knative Serving. Replace `$spec_version` with the correct version number. - The tag `${VERSION}` is automatically replaced with the version number from `spec_version` by the operator. + Where `` is the Knative version you want to use, for example `1.0`. This field is used to set the version of Knative Serving and to automatically replace the tag `${VERSION}`. - The field `spec.manifests` is used to specify one or multiple URL links of Knative Serving component. Do not forget to - add the valid URL of the Knative network ingress plugin. Knative Serving component is still tightly-coupled with a network - ingress plugin in the operator. As in the example mentioned earlier, you can use `net-istio`. The ordering of the URLs is critical. - Put the manifest you want to apply first on the top. + !!! attention + The field `spec.manifests` is used to specify one or multiple URL links + of the Knative Serving component. + The ordering of the URLs is critical. Put the manifest you want to apply first on the top. - === "Install Customized Knative Serving" + You must add a valid URL of the Knative network ingress plugin. You can use `net-istio`. + Knative Serving component is tightly-coupled with a network ingress plugin in the Operator. - The operator provides you the flexibility to install customized - Knative Serving based your own requirements. As long as the manifests of customized Knative Serving are accessible to - the operator, they can be installed. + 1. Apply the YAML file by running the command: - There are two modes available for you to install the customized manifests: overwrite mode and append mode. With the - overwrite mode, you need to define all the manifests for Knative Serving to install, because the operator will no long - install any available default manifests. With the append mode, you only need to define your customized manifests, and - the customized manifests are installed, after default manifests are applied. - - 1. You can use the overwrite mode to customize all the Knative Serving manifests. For example, the version of the customized - Knative Serving is `$spec_version`, and it is available at `https://my-serving/serving.yaml`. You choose `net-istio` - as the ingress plugin, which is available at `https://my-net-istio/net-istio.yaml`. You can create the content of Serving - CR as in the following example to install your Knative Serving and the istio ingress: - ``` - apiVersion: v1 - kind: Namespace - metadata: - name: knative-serving - --- - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeServing - metadata: - name: knative-serving - namespace: knative-serving - spec: - version: $spec_version - manifests: - - URL: https://my-serving/serving.yaml - - URL: https://my-net-istio/net-istio.yaml + ```bash + kubectl apply -f .yaml ``` - You can make the customized Knative Serving available in one or multiple links, as the `spec.manifests` supports a list - of links. The ordering of the URLs is critical. Put the manifest you want to apply first on the top. We strongly recommend - you to specify the version and the valid links to the customized Knative Serving, by leveraging both `spec_version` - and `spec.manifests`. Do not skip either field. + Where `` is the name of the file you created in the previous step. - 1. You can use the append mode to add your customized manifests into the default manifests. For example, you only customize - a few resources, and make them available at `https://my-serving/serving-custom.yaml`. You still need to install the default - Knative Serving. In this case, you can create the content of Serving CR as follows: - ``` - apiVersion: v1 - kind: Namespace - metadata: - name: knative-serving - --- - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeServing - metadata: - name: knative-serving - namespace: knative-serving - spec: - version: $spec_version - additionalManifests: - - URL: https://my-serving/serving-custom.yaml - ``` +=== "Install customized Knative Serving" - Knative operator will install the default manifests of Knative Serving at the version `$spec_version`, and then install - your customized manifests based on them. + The Operator provides you with the flexibility to install Knative Serving + customized to your own requirements. + As long as the manifests of customized Knative Serving are accessible to + the Operator, you can install them. -### Installing Knative Serving with different networking layers + There are two modes available for you to install customized manifests: + _overwrite mode_ and _append mode_. + With overwrite mode, you must define all manifests needed for Knative Serving + to install because the Operator will no longer install any default manifests. + With append mode, you only need to define your customized manifests. + The customized manifests are installed after default manifests are applied. -Knative Operator can configure Knative Serving component with different network layer options. Istio is the default network -layer, if the ingress is not specified in the Knative Serving CR. Click on each of the following tabs to see how you can configure + **Overwrite mode:** + + You can use overwrite mode when you want to customize all Knative Serving manifests. + + For example, if you want to install Knative Serving and istio ingress and you + want customize both components, you can create the following YAML file: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-serving + --- + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + version: $spec_version + manifests: + - URL: https://my-serving/serving.yaml + - URL: https://my-net-istio/net-istio.yaml + ``` + + This example installs the customized Knative Serving at version `$spec_version` + which is available at `https://my-serving/serving.yaml`, and the customized ingress plugin `net-istio` + which is available at `https://my-net-istio/net-istio.yaml`. + + !!! attention + You can make the customized Knative Serving available in one or multiple links, as the `spec.manifests` supports a list of links. + The ordering of the URLs is critical. Put the manifest you want to apply first on the top. + + We strongly recommend you to specify the version and the valid links to the + customized Knative Serving, by leveraging both `spec_version` and `spec.manifests`. + Do not skip either field. + + **Append mode:** + + You can use append mode to add your customized manifests into the default manifests. + + For example, if you only want to customize a few resources but you still want + to install the default Knative Serving, you can create the following YAML file: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-serving + --- + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + version: $spec_version + additionalManifests: + - URL: https://my-serving/serving-custom.yaml + ``` + + This example installs the default Knative Serving, and installs + your customized resources available at `https://my-serving/serving-custom.yaml`. + + Knative Operator installs the default manifests of Knative Serving at the + version `$spec_version`, and then installs your customized manifests based on them. + +### Install the networking layer + +Knative Operator can configure Knative Serving component with different network layer options. +Istio is the default network layer if the ingress is not specified in the +Knative Serving CR. + +Click on each of the following tabs to see how you can configure Knative Serving with different ingresses: -=== "Kourier (Choose this if you are not sure)" +=== "Istio (default)" - The following commands install Kourier and enable its Knative integration. + The following steps install Istio to enable its Knative integration: + + 1. [Install Istio](../serving/installing-istio.md). + + 1. If you installed Istio under a namespace other than the default `istio-system`: + 1. Add `spec.config.istio` to your Serving CR YAML file as follows: + + ```yaml + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + # ... + config: + istio: + local-gateway..knative-local-gateway: "knative-local-gateway..svc.cluster.local" + ``` + + Where: + + - `` is the local gateway namespace, which is the same as Knative Serving namespace `knative-serving`. + - `` is the namespace where Istio is installed. + + 1. Apply the YAML file for your Serving CR by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of your Serving CR file. + + 1. Fetch the External IP or CNAME by running the command: + + ```bash + kubectl get svc istio-ingressgateway -n + ``` + + Save this for configuring DNS later. + +=== "Kourier" + + The following steps install Kourier and enable its Knative integration: + + 1. To configure Knative Serving to use Kourier, add `spec.ingress.kourier` and + `spec.config.network` to your Serving CR YAML file as follows: - 1. To configure Knative Serving to use Kourier, copy the following YAML into a file: ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeServing @@ -184,6 +277,7 @@ Knative Serving with different ingresses: name: knative-serving namespace: knative-serving spec: + # ... ingress: kourier: enabled: true @@ -192,78 +286,34 @@ Knative Serving with different ingresses: ingress-class: "kourier.ingress.networking.knative.dev" ``` - 1. Apply the YAML file by running the command: + 1. Apply the YAML file for your Serving CR by running the command: + ```bash kubectl apply -f .yaml ``` - Where `` is the name of the file you created in the previous step. + Where `` is the name of your Serving CR file. 1. Fetch the External IP or CNAME by running the command: + ```bash kubectl --namespace knative-serving get service kourier ``` Save this for configuring DNS later. -=== "Istio" - - The following commands install Istio and enable its Knative integration. - - 1. [Install Istio](../serving/installing-istio.md). - - 1. To configure Knative Serving to use Istio, copy the following YAML into a file: - ```yaml - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeServing - metadata: - name: knative-serving - namespace: knative-serving - ``` - - 1. If Istio is installed under a namespace other than the default `istio-system`, add the `spec.config.istio` field - to the YAML file as follows: - ```yaml - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeServing - metadata: - name: knative-serving - namespace: knative-serving - spec: - config: - istio: - local-gateway..knative-local-gateway: "knative-local-gateway..svc.cluster.local" - ``` - - Where: - - - `` is the local gateway namespace, which is the same as Knative Serving namespace `knative-serving`. - - `` is the namespace where Istio is installed. - - 1. Apply the YAML file by running the command: - ```bash - kubectl apply -f .yaml - ``` - - Where `` is the name of the file you created in the previous step. - - 1. Fetch the External IP or CNAME by running the command: - ```bash - kubectl get svc istio-ingressgateway -n - ``` - - Save this for configuring DNS later. - === "Ambassador" - The following commands install Ambassador and enable its Knative integration. + The following steps install Ambassador and enable its Knative integration: 1. Create a namespace to install Ambassador in: + ```bash kubectl create namespace ambassador ``` 1. Install Ambassador: + ```bash kubectl apply --namespace ambassador \ --filename https://getambassador.io/yaml/ambassador/ambassador-crds.yaml \ @@ -272,16 +322,20 @@ Knative Serving with different ingresses: ``` 1. Give Ambassador the required permissions: + ```bash kubectl patch clusterrolebinding ambassador -p '{"subjects":[{"kind": "ServiceAccount", "name": "ambassador", "namespace": "ambassador"}]}' ``` 1. Enable Knative support in Ambassador: + ```bash kubectl set env --namespace ambassador deployments/ambassador AMBASSADOR_KNATIVE_SUPPORT=true ``` - 1. To configure Knative Serving to use Ambassador, copy the following YAML into a file: + 1. To configure Knative Serving to use Ambassador, add `spec.config.network` + to your Serving CR YAML file as follows: + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeServing @@ -289,19 +343,22 @@ Knative Serving with different ingresses: name: knative-serving namespace: knative-serving spec: + # ... config: network: ingress-class: "ambassador.ingress.networking.knative.dev" ``` - 1. Apply the YAML file by running the command: + 1. Apply the YAML file for your Serving CR by running the command: + ```bash kubectl apply -f .yaml ``` - Where `` is the name of the file you created in the previous step. + Where `` is the name of your Serving CR file. 1. Fetch the External IP or CNAME by running the command: + ```bash kubectl --namespace ambassador get service ambassador ``` @@ -310,14 +367,17 @@ Knative Serving with different ingresses: === "Contour" - The following commands install Contour and enable its Knative integration. + The following steps install Contour and enable its Knative integration: 1. Install a properly configured Contour: + ```bash kubectl apply --filename {{artifact(repo="net-contour",file="contour.yaml")}} ``` - 1. To configure Knative Serving to use Contour, copy the following YAML into a file: + 1. To configure Knative Serving to use Contour, add `spec.ingress.contour` + `spec.config.network` to your Serving CR YAML file as follows: + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeServing @@ -325,6 +385,7 @@ Knative Serving with different ingresses: name: knative-serving namespace: knative-serving spec: + # ... ingress: contour: enabled: true @@ -333,47 +394,56 @@ Knative Serving with different ingresses: ingress-class: "contour.ingress.networking.knative.dev" ``` - 1. Apply the YAML file by running the command: + 1. Apply the YAML file for your Serving CR by running the command: + ```bash kubectl apply -f .yaml ``` - Where `` is the name of the file you created in the previous step. + Where `` is the name of your Serving CR file. 1. Fetch the External IP or CNAME by running the command: + ```bash kubectl --namespace contour-external get service envoy ``` Save this for configuring DNS later. +### Verify the Knative Serving deployment 1. Monitor the Knative deployments: -``` -kubectl get deployment -n knative-serving -``` -If Knative Serving has been successfully deployed, all deployments of the Knative Serving will show `READY` status. Here -is a sample output: -``` -NAME READY UP-TO-DATE AVAILABLE AGE -activator 1/1 1 1 18s -autoscaler 1/1 1 1 18s -autoscaler-hpa 1/1 1 1 14s -controller 1/1 1 1 18s -domain-mapping 1/1 1 1 12s -domainmapping-webhook 1/1 1 1 12s -webhook 1/1 1 1 17s -``` + + ```bash + kubectl get deployment -n knative-serving + ``` + + If Knative Serving has been successfully deployed, all deployments of the + Knative Serving will show `READY` status. Here is a sample output: + + ```{ .bash .no-copy } + NAME READY UP-TO-DATE AVAILABLE AGE + activator 1/1 1 1 18s + autoscaler 1/1 1 1 18s + autoscaler-hpa 1/1 1 1 14s + controller 1/1 1 1 18s + domain-mapping 1/1 1 1 12s + domainmapping-webhook 1/1 1 1 12s + webhook 1/1 1 1 17s + ``` 1. Check the status of Knative Serving Custom Resource: -``` -kubectl get KnativeServing knative-serving -n knative-serving -``` -If Knative Serving is successfully installed, you should see: -``` -NAME VERSION READY REASON -knative-serving True -``` + + ```bash + kubectl get KnativeServing knative-serving -n knative-serving + ``` + + If Knative Serving is successfully installed, you should see: + + ```{ .bash .no-copy } + NAME VERSION READY REASON + knative-serving True + ``` {% include "dns.md" %} @@ -382,14 +452,18 @@ knative-serving True ## Installing the Knative Eventing component -1. Create and apply the Knative Eventing CR: +To install Knative Eventing you must apply the custom resource (CR). +Optionally, you can install the Knative Eventing component with different event sources. - You can install the latest available Knative Eventing in the - operator by applying a YAML file containing the following: +### Create the Knative Eventing custom resource - === "Install Current Evenintg (default)" +=== "Install the current version (default)" - ``` + To create the custom resource for the latest available Knative Eventing in the Operator: + + 1. Copy the following YAML into a file: + + ```yaml apiVersion: v1 kind: Namespace metadata: @@ -401,16 +475,25 @@ knative-serving True name: knative-eventing namespace: knative-eventing ``` + !!! note + When you do not specify a version by using `spec.version` field, the Operator defaults to the latest available version. - If you do not specify a version by using spec.version, the operator defaults to the latest available version. - - === "Install Future Knative Eventing" - - You do not need to upgrade the operator to a newer version to install - new releases of Knative Eventing. If Knative Eventing launches a new version, e.g. `$spec_version`, you can install it by - applying a YAML file containing the following: + 1. Apply the YAML file by running the command: + ```bash + kubectl apply -f .yaml ``` + + Where `` is the name of the file you created in the previous step. + +=== "Install another version of Knative Eventing" + + You can install a new release of Knative Eventing without upgrading the Operator. + To install a new version of Knative Eventing: + + 1. Create a YAML file containing the following: + + ```yaml apiVersion: v1 kind: Namespace metadata: @@ -422,307 +505,425 @@ knative-serving True name: knative-eventing namespace: knative-eventing spec: - version: $spec_version + version: "" manifests: - URL: https://github.com/knative/eventing/releases/download/v${VERSION}/eventing.yaml - URL: https://github.com/knative/eventing/releases/download/v${VERSION}/eventing-post-install-jobs.yaml ``` + Where `` is the Knative version you want to use, for example `1.0`. This field is used to set the version of Knative Eventing and to automatically replace the tag `${VERSION}`. + !!! attention + The field `spec.manifests` is used to specify one or multiple URL links + of the Knative Serving component. + The ordering of the URLs is critical. Put the manifest you want to apply first on the top. - The field `spec.version` is used to set the version of Knative Eventing. Replace `$spec_version` with the correct version number. - The tag `${VERSION}` is automatically replaced with the version number from `spec.version` by the operator. + 1. Apply the YAML file by running the command: - The field `spec.manifests` is used to specify one or multiple URL links of Knative Eventing component. Do not forget to - add the valid URL of the Knative network ingress plugin. The ordering of the URLs is critical. Put the manifest you want - to apply first on the top. - - === "Install Customized Knative Evening" - - The operator provides you the flexibility to install customized - Knative Eventing based your own requirements. As long as the manifests of customized Knative Eventing are accessible to - the operator, they can be installed. - - There are two modes available for you to install the customized manifests: overwrite mode and append mode. With the - overwrite mode, you need to define all the manifests for Knative Eventing to install, because the operator will no long - install any available default manifests. With the append mode, you only need to define your customized manifests, and - the customized manifests are installed, after default manifests are applied. - - 1. You can use the overwrite mode to customize all the Knative Eventing manifests. For example, the version of the customized - Knative Eventing is `$spec_version`, and it is available at `https://my-eventing/eventing.yaml`. You can create the - content of Eventing CR to install your Knative Eventing as follows: - - ``` - apiVersion: v1 - kind: Namespace - metadata: - name: knative-eventing - --- - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeEventing - metadata: - name: knative-eventing - namespace: knative-eventing - spec: - version: $spec_version - manifests: - - URL: https://my-eventing/eventing.yaml + ```bash + kubectl apply -f .yaml ``` - You can make the customized Knative Eventing available in one or multiple links, as the `spec.manifests` supports a list - of links. The ordering of the URLs is critical. Put the manifest you want to apply first on the top. We strongly recommend - you to specify the version and the valid links to the customized Knative Eventing, by leveraging both `spec.version` - and `spec.manifests`. Do not skip either field. + Where `` is the name of the file you created in the previous step. - 1. You can use the append mode to add your customized manifests into the default manifests. For example, you only customize - a few resources, and make them available at `https://my-eventing/eventing-custom.yaml`. You still need to install the default - Knative eventing. In this case, you can create the content of Eventing CR as follows: +=== "Install customized Knative Eventing" - ``` - apiVersion: v1 - kind: Namespace - metadata: - name: knative-eventing - --- - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeEventing - metadata: - name: knative-eventing - namespace: knative-eventing - spec: - version: $spec_version - additionalManifests: - - URL: https://my-eventing/eventing-custom.yaml - ``` + The Operator provides you with the flexibility to install Knative Eventing + customized to your own requirements. + As long as the manifests of customized Knative Eventing are accessible to + the Operator, you can install them. - Knative operator will install the default manifests of Knative Eventing at the version `$spec_version`, and then install - your customized manifests based on them. + There are two modes available for you to install customized manifests: + _overwrite mode_ and _append mode_. + With overwrite mode, you must define all manifests needed for Knative Eventing + to install because the Operator will no longer install any default manifests. + With append mode, you only need to define your customized manifests. + The customized manifests are installed after default manifests are applied. -### Verify the Knative Eventing deployment: + **Overwrite mode:** -``` -kubectl get deployment -n knative-eventing -``` + Use overwrite mode when you want to customize all Knative Eventing manifests to be installed. -If Knative Eventing has been successfully deployed, all deployments of the Knative Eventing will show `READY` status. Here -is a sample output: + For example, if you want to install a customized Knative Eventing only, + you can create and apply the following Eventing CR: -``` -NAME READY UP-TO-DATE AVAILABLE AGE -eventing-controller 1/1 1 1 43s -eventing-webhook 1/1 1 1 42s -imc-controller 1/1 1 1 39s -imc-dispatcher 1/1 1 1 38s -mt-broker-controller 1/1 1 1 36s -mt-broker-filter 1/1 1 1 37s -mt-broker-ingress 1/1 1 1 37s -pingsource-mt-adapter 0/0 0 0 43s -sugar-controller 1/1 1 1 36s -``` + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-eventing + --- + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeEventing + metadata: + name: knative-eventing + namespace: knative-eventing + spec: + version: $spec_version + manifests: + - URL: https://my-eventing/eventing.yaml + ``` -### Check the status of Knative Eventing Custom Resource: + This example installs the customized Knative Eventing at version `$spec_version` + which is available at `https://my-eventing/eventing.yaml`. -``` -kubectl get KnativeEventing knative-eventing -n knative-eventing -``` + !!! attention + You can make the customized Knative Eventing available in one or multiple links, as the `spec.manifests` supports a list of links. + The ordering of the URLs is critical. Put the manifest you want to apply first on the top. -If Knative Eventing is successfully installed, you should see: + We strongly recommend you to specify the version and the valid links to the + customized Knative Eventing, by leveraging both `spec.version` and `spec.manifests`. + Do not skip either field. -``` -NAME VERSION READY REASON -knative-eventing True -``` + **Append mode:** -### Installing the Knative Eventing component with different eventing sources + You can use append mode to add your customized manifests into the default manifests. -Knative Operator can configure Knative Eventing component with different eventing sources. Click on each of the following tabs to -see how you can configure Knative Eventing with different eventing sources: + For example, if you only want to customize a few resources but you still want + to install the default Knative Eventing, + you can create and apply the following Eventing CR: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-eventing + --- + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeEventing + metadata: + name: knative-eventing + namespace: knative-eventing + spec: + version: $spec_version + additionalManifests: + - URL: https://my-eventing/eventing-custom.yaml + ``` + + This example installs the default Knative Eventing, and installs your customized + resources available at `https://my-eventing/eventing-custom.yaml`. + + Knative Operator installs the default manifests of Knative Eventing at the + version `$spec_version`, and then installs your customized manifests based on them. + +### Installing Knative Eventing with event sources + +Knative Operator can configure the Knative Eventing component with different event sources. +Click on each of the following tabs to +see how you can configure Knative Eventing with different event sources: === "Ceph" - To configure Knative Eventing to install Ceph as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install Ceph as the event source: + + 1. Add `spec.source.ceph` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: ceph: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "Apache CouchDB" - To configure Knative Eventing to install Apache CouchDB as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install Apache CouchDB as the event source: + + 1. Add `spec.source.couchdb` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: couchdb: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "GitHub" - To configure Knative Eventing to install GitHub as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install GitHub as the event source: + + 1. Add `spec.source.github` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: github: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "GitLab" - To configure Knative Eventing to install GitLab as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install GitLab as the event source: + + 1. Add `spec.source.gitlab` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: gitlab: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "Apache Kafka" - To configure Knative Eventing to install Kafka as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install Kafka as the event source: + + 1. Add `spec.source.kafka` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: kafka: - enabled: true - EOF + enabled: true ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "NATS Streaming" - To configure Knative Eventing to install NATS Streaming as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install NATS Streaming as the event source: + + 1. Add `spec.source.natss` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: natss: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "Prometheus" - To configure Knative Eventing to install Prometheus as the eventing source, apply the content of the Eventing CR as follows: + To configure Knative Eventing to install Prometheus as the event source: + + 1. Add `spec.source.prometheus` to your Eventing CR YAML file as follows: + + ```yaml + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeEventing + metadata: + name: knative-eventing + namespace: knative-eventing + spec: + # ... + source: + prometheus: + enabled: true + ``` + + 1. Apply the YAML file by running the command: + ```bash - cat <<-EOF | kubectl apply -f - - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeEventing - metadata: - name: knative-eventing - namespace: knative-eventing - spec: - source: - prometheus: - enabled: true - EOF - ``` + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. === "RabbitMQ" - To configure Knative Eventing to install RabbitMQ as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install RabbitMQ as the event source, + + 1. Add `spec.source.rabbitmq` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: rabbitmq: enabled: true - EOF ``` + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + === "Redis" - To configure Knative Eventing to install Redis as the eventing source, apply the content of the Eventing CR as follows: - ```bash - cat <<-EOF | kubectl apply -f - + To configure Knative Eventing to install Redis as the event source: + + 1. Add `spec.source.redis` to your Eventing CR YAML file as follows: + + ```yaml apiVersion: operator.knative.dev/v1alpha1 kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing spec: + # ... source: redis: enabled: true - EOF ``` -## Uninstall Knative + 1. Apply the YAML file by running the command: + + ```bash + kubectl apply -f .yaml + ``` + + Where `` is the name of the file you created in the previous step. + +### Verify the Knative Eventing deployment + +1. Monitor the Knative deployments: + + ```bash + kubectl get deployment -n knative-eventing + ``` + + If Knative Eventing has been successfully deployed, all deployments of the + Knative Eventing will show `READY` status. Here is a sample output: + + ```{.bash .no-copy} + NAME READY UP-TO-DATE AVAILABLE AGE + eventing-controller 1/1 1 1 43s + eventing-webhook 1/1 1 1 42s + imc-controller 1/1 1 1 39s + imc-dispatcher 1/1 1 1 38s + mt-broker-controller 1/1 1 1 36s + mt-broker-filter 1/1 1 1 37s + mt-broker-ingress 1/1 1 1 37s + pingsource-mt-adapter 0/0 0 0 43s + sugar-controller 1/1 1 1 36s + ``` + +1. Check the status of Knative Eventing Custom Resource: + + ```bash + kubectl get KnativeEventing knative-eventing -n knative-eventing + ``` + + If Knative Eventing is successfully installed, you should see: + + ```{.bash .no-copy} + NAME VERSION READY REASON + knative-eventing True + ``` + +## Uninstalling Knative + +Knative Operator prevents unsafe removal of Knative resources. Even if the Knative Serving and Knative Eventing CRs are +successfully removed, all the CRDs in Knative are still kept in the cluster. All your resources relying on Knative CRDs +can still work. ### Removing the Knative Serving component -Remove the Knative Serving CR: +To remove the Knative Serving CR run the command: -``` +```bash kubectl delete KnativeServing knative-serving -n knative-serving ``` ### Removing Knative Eventing component -Remove the Knative Eventing CR: +To remove the Knative Eventing CR run the command: -``` +```bash kubectl delete KnativeEventing knative-eventing -n knative-eventing ``` -Knative operator prevents unsafe removal of Knative resources. Even if the Knative Serving and Knative Eventing CRs are -successfully removed, all the CRDs in Knative are still kept in the cluster. All your resources relying on Knative CRDs -can still work. - ### Removing the Knative Operator: -If you have installed Knative using the Release page, remove the operator using the following command: +If you have installed Knative using the release page, remove the operator by running the command: -``` +```bash kubectl delete -f {{artifact(org="knative",repo="operator",file="operator.yaml")}} ``` If you have installed Knative from source, uninstall it using the following command while in the root directory for the source: -``` +```bash ko delete -f config/ ``` diff --git a/docs/install/upgrade/upgrade-installation-with-operator.md b/docs/install/upgrade/upgrade-installation-with-operator.md index 94e466ef4..df612f42e 100644 --- a/docs/install/upgrade/upgrade-installation-with-operator.md +++ b/docs/install/upgrade/upgrade-installation-with-operator.md @@ -15,7 +15,7 @@ The Knative Operator supports up to the last three major releases. For example, To upgrade, apply the Operator custom resources, adding the `spec.version` for the Knative version that you want to upgrade to: -1. Copy the following YAML into a file: +1. Create a YAML file containing the following: ```yaml apiVersion: operator.knative.dev/v1alpha1 @@ -24,8 +24,9 @@ To upgrade, apply the Operator custom resources, adding the `spec.version` for t name: knative-serving namespace: knative-serving spec: - version: "0.23" + version: "" ``` + Where `` is the Knative version that you want to upgrade to. 1. Apply the YAML file by running the command: @@ -122,7 +123,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v === "Knative Serving" -1. Copy the following YAML into a file: +To rollback to a previous version of Knative Serving: + +1. Create a YAML file containing the following: ```yaml apiVersion: operator.knative.dev/v1alpha1 @@ -131,8 +134,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v name: knative-serving namespace: knative-serving spec: - version: "0.22" + version: "" ``` + Where `` is the Knative version that you want to downgrade to. 1. Apply the YAML file by running the command: @@ -143,7 +147,9 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v === "Knative Eventing" -1. Copy the following YAML into a file: +To rollback to a previous version of Knative Eventing: + +1. Create a YAML file containing the following: ```yaml apiVersion: operator.knative.dev/v1alpha1 @@ -152,8 +158,10 @@ If the upgrade fails, you can rollback to restore your Knative to the previous v name: knative-eventing namespace: knative-eventing spec: - version: "0.22" + version: "" ``` + Where `` is the Knative version that you want to downgrade to. + 1. Apply the YAML file by running the command: ```bash diff --git a/docs/snippets/dns.md b/docs/snippets/dns.md index b7b3945fb..4bb46074a 100644 --- a/docs/snippets/dns.md +++ b/docs/snippets/dns.md @@ -1,4 +1,4 @@ -## Configure DNS +### Configure DNS You can configure DNS to prevent the need to run curl commands with a host header. diff --git a/docs/snippets/real-dns-operator.md b/docs/snippets/real-dns-operator.md index b51a3df26..6100e0ce6 100644 --- a/docs/snippets/real-dns-operator.md +++ b/docs/snippets/real-dns-operator.md @@ -7,30 +7,32 @@ - If the networking layer produced an External IP address, then configure a wildcard `A` record for the domain: - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == A 35.233.41.212 - ``` + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == A 35.233.41.212 + ``` - If the networking layer produced a CNAME, then configure a CNAME record for the domain: - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com - ``` + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com + ``` - - Once your DNS provider has been configured, add the following section into your existing Serving CR, and apply it: + - Once your DNS provider has been configured, add `spec.config.domain` into + your existing Serving CR, and apply it: - ```yaml - # Replace knative.example.com with your domain suffix - apiVersion: operator.knative.dev/v1alpha1 - kind: KnativeServing - metadata: - name: knative-serving - namespace: knative-serving - spec: - config: - domain: - "knative.example.com": "" - ... - ``` + ```yaml + # Replace knative.example.com with your domain suffix + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + ... + config: + domain: + "knative.example.com": "" + ... + ``` diff --git a/docs/snippets/real-dns-yaml.md b/docs/snippets/real-dns-yaml.md index 2a70c7fbd..d0ec6cf0e 100644 --- a/docs/snippets/real-dns-yaml.md +++ b/docs/snippets/real-dns-yaml.md @@ -7,24 +7,24 @@ - If the networking layer produced an External IP address, then configure a wildcard `A` record for the domain: - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == A 35.233.41.212 - ``` + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == A 35.233.41.212 + ``` - If the networking layer produced a CNAME, then configure a CNAME record for the domain: - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com - ``` + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com + ``` - Once your DNS provider has been configured, direct Knative to use that domain: - ```yaml - # Replace knative.example.com with your domain suffix - kubectl patch configmap/config-domain \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"knative.example.com":""}}' - ``` + ```yaml + # Replace knative.example.com with your domain suffix + kubectl patch configmap/config-domain \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"knative.example.com":""}}' + ```