From 844b6f0f7d098a225a94258c2d6a83106c3eb62c Mon Sep 17 00:00:00 2001 From: Samia Nneji Date: Thu, 21 Apr 2022 12:57:30 +0100 Subject: [PATCH] Clean up broken formatting in Operator install docs (#4932) * Clean up operator docs formatting * A few more fixes --- .../operator/configuring-eventing-cr.md | 73 ++++++------ .../operator/configuring-serving-cr.md | 109 +++++++++--------- .../operator/knative-with-operators.md | 72 ++++++------ 3 files changed, 130 insertions(+), 124 deletions(-) diff --git a/docs/install/operator/configuring-eventing-cr.md b/docs/install/operator/configuring-eventing-cr.md index 8f868aaff..5e910b1f5 100644 --- a/docs/install/operator/configuring-eventing-cr.md +++ b/docs/install/operator/configuring-eventing-cr.md @@ -1,7 +1,7 @@ # Configuring the Eventing Operator custom resource You can configure the Knative Eventing operator by modifying settings in the KnativeEventing custom resource (CR). -Knative Eventing can be configured with the following options: +You can configure Knative Eventing with the following options: - [Installing a specific version of Eventing](#installing-a-specific-version-of-eventing) - [Installing customized Knative Eventing](#installing-customized-knative-eventing) @@ -45,11 +45,12 @@ The Operator provides you with the flexibility to install Knative Eventing custo As long as the manifests of customized Knative Eventing are accessible to the Operator, you can install 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. +With overwrite mode, under `.spec.manifests`, you must define all manifests needed for Knative Eventing +to install because the Operator will no longer install any default manifests. +With append mode, under `.spec.additionalManifests`, you only need to define your customized manifests. The customized manifests are installed after default manifests are applied. -**Overwrite mode:** +### Overwrite mode Use overwrite mode when you want to customize all Knative Eventing manifests to be installed. @@ -83,7 +84,7 @@ This example installs the customized Knative Eventing at version `$spec_version` 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. -**Append mode:** +### Append mode You can use append mode to add your customized manifests into the default manifests. @@ -113,7 +114,7 @@ This example installs the default Knative Eventing, and installs your customized Knative Operator installs the default manifests of Knative Eventing at the version `$spec_version`, and then installs your customized manifests based on them. -### Setting a default channel +## Setting a default channel If you are using different channel implementations, like the KafkaChannel, or you want a specific configuration of the InMemoryChannel to be the default configuration, you can change the default behavior by updating the `default-ch-webhook` ConfigMap. @@ -149,7 +150,7 @@ spec: !!! note The `clusterDefault` setting determines the global, cluster-wide default channel type. You can configure channel defaults for individual namespaces by using the `namespaceDefaults` setting. -### Setting the default channel for the broker +## Setting the default channel for the broker If you are using a channel-based broker, you can change the default channel type for the broker from InMemoryChannel to KafkaChannel, by updating the `config-br-default-channel` ConfigMap. @@ -203,36 +204,38 @@ Some images are defined by using the environment variable in Knative Eventing. T This example shows how you can define custom image links that can be defined in the KnativeEventing CR using the simplified format `docker.io/knative-images/${NAME}:{CUSTOM-TAG}`. -In the following example: +In this example: - The custom tag `latest` is used for all images. - All image links are accessible without using secrets. - Images are defined in the accepted format `docker.io/knative-images/${NAME}:{CUSTOM-TAG}`. +To define your image links: + 1. Push images to the following image tags: - | Deployment | Container | Docker image | - |----|----|----| - | `eventing-controller` | `eventing-controller` | `docker.io/knative-images/eventing-controller:latest` | - | | `eventing-webhook` | `docker.io/knative-images/eventing-webhook:latest` | - | `broker-controller` | `eventing-controller` | `docker.io/knative-images/broker-eventing-controller:latest` | - | | `controller` | `docker.io/knative-images/controller:latest` | - | | `dispatcher` | `docker.io/knative-images/dispatcher:latest` | + | Deployment | Container | Docker image | + |----|----|----| + | `eventing-controller` | `eventing-controller` | `docker.io/knative-images/eventing-controller:latest` | + | | `eventing-webhook` | `docker.io/knative-images/eventing-webhook:latest` | + | `broker-controller` | `eventing-controller` | `docker.io/knative-images/broker-eventing-controller:latest` | + | | `controller` | `docker.io/knative-images/controller:latest` | + | | `dispatcher` | `docker.io/knative-images/dispatcher:latest` | -2. Define your the KnativeEventing CR with following content: +2. Define your KnativeEventing CR with following content: - ```yaml - apiVersion: operator.knative.dev/v1beta1 - kind: KnativeEventing - metadata: - name: knative-eventing - namespace: knative-eventing - spec: - registry: - default: docker.io/knative-images/${NAME}:latest - override: - broker-controller/eventing-controller: docker.io/knative-images-repo1/broker-eventing-controller:latest - ``` + ```yaml + apiVersion: operator.knative.dev/v1beta1 + kind: KnativeEventing + metadata: + name: knative-eventing + namespace: knative-eventing + spec: + registry: + default: docker.io/knative-images/${NAME}:latest + override: + broker-controller/eventing-controller: docker.io/knative-images-repo1/broker-eventing-controller:latest + ``` - `${NAME}` maps to the container name in each `Deployment` resource. - `default` is used to define the image format for all containers, except the container `eventing-controller` in the deployment `broker-controller`. To replace the image for this container, use the `override` @@ -243,17 +246,17 @@ In the following example: If your custom image links are not defined in a uniform format, you will need to individually include each link in the KnativeEventing CR. -For example, to define the following list of images: +For example, given the following list of images: | Deployment | Container | Docker Image | |----|----|----| -| `eventing-controller` | `eventing-controller` | `docker.io/knative-images/eventing-controller:latest` | -| | `eventing-webhook` | `docker.io/knative-images/eventing-webhook:latest` | -| | `controller` | `docker.io/knative-images/controller:latest` | -| | `dispatcher` | `docker.io/knative-images/dispatcher:latest` | -| `broker-controller` | `eventing-controller` | `docker.io/knative-images/broker-eventing-controller:latest` | +| `eventing-controller` | `eventing-controller` | `docker.io/knative-images-repo1/eventing-controller:latest` | +| | `eventing-webhook` | `docker.io/knative-images-repo2/eventing-webhook:latest` | +| | `controller` | `docker.io/knative-images-repo3/imc-controller:latest` | +| | `dispatcher` | `docker.io/knative-images-repo4/imc-dispatcher:latest` | +| `broker-controller` | `eventing-controller` | `docker.io/knative-images-repo5/broker-eventing-controller:latest` | -The KnativeEventing CR must be modified to include the full list. For example: +You must modify the KnativeEventing CR to include the full list. For example: ```yaml apiVersion: operator.knative.dev/v1beta1 diff --git a/docs/install/operator/configuring-serving-cr.md b/docs/install/operator/configuring-serving-cr.md index dbf4a747e..72b9aa294 100644 --- a/docs/install/operator/configuring-serving-cr.md +++ b/docs/install/operator/configuring-serving-cr.md @@ -1,6 +1,6 @@ # Configuring the Knative Serving Operator custom resource -Knative Serving can be configured with the following options: +You can configure Knative Serving with the following options: - [Version configuration](#version-configuration) - [Install customized Knative Serving](#install-customized-knative-serving) @@ -42,16 +42,17 @@ enables upgrading or downgrading the Knative Serving version, without needing to 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. -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. +There are two modes available for you to install customized manifests: _overwrite mode_ and _append mode_. +With overwrite mode, under `.spec.manifests`, you must define all manifests needed for +Knative Serving to install because the Operator will no longer install any default manifests. +With append mode, under `.spec.additionalManifests`, you only need to define your customized manifests. +The customized manifests are installed after default manifests are applied. -**Overwrite mode:** +### 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 +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 @@ -83,7 +84,7 @@ This example installs the customized Knative Serving at version `$spec_version` 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:** +### Append mode You can use append mode to add your customized manifests into the default manifests. @@ -130,61 +131,63 @@ must be created in the same namespace as the Knative Serving Deployments. See [deploying images from a private container registry](../../serving/deploying-from-private-registry.md) for configuration details. -### Download images in a predefined format without secrets: +### Download images in a predefined format without secrets This example shows how you can define custom image links that can be defined in the CR using the simplified format `docker.io/knative-images/${NAME}:{CUSTOM-TAG}`. In the following example: -- the custom tag `v0.13.0` is used for all images -- all image links are accessible without using secrets -- images are pushed as `docker.io/knative-images/${NAME}:{CUSTOM-TAG}` +- The custom tag `latest` is used for all images. +- All image links are accessible without using secrets. +- Images are pushed as `docker.io/knative-images/${NAME}:{CUSTOM-TAG}`. -First, you need to make sure your images pushed to the following image tags: +To define your image links: -| Container | Docker Image | -|----|----| -|`activator` | `docker.io/knative-images/activator:v0.13.0` | -| `autoscaler` | `docker.io/knative-images/autoscaler:v0.13.0` | -| `controller` | `docker.io/knative-images/controller:v0.13.0` | -| `webhook` | `docker.io/knative-images/webhook:v0.13.0` | -| `autoscaler-hpa` | `docker.io/knative-images/autoscaler-hpa:v0.13.0` | -| `net-istio-controller` | `docker.io/knative-images/net-istio-controller:v0.13.0` | -| `queue-proxy` | `docker.io/knative-images/queue-proxy:v0.13.0` | +1. Push images to the following image tags: -Then, you need to define your operator CR with following content: + | Container | Docker Image | + |----|----| + |`activator` | `docker.io/knative-images/activator:latest` | + | `autoscaler` | `docker.io/knative-images/autoscaler:latest` | + | `controller` | `docker.io/knative-images/controller:latest` | + | `webhook` | `docker.io/knative-images/webhook:latest` | + | `autoscaler-hpa` | `docker.io/knative-images/autoscaler-hpa:latest` | + | `net-istio-controller` | `docker.io/knative-images/net-istio-controller:latest` | + | `queue-proxy` | `docker.io/knative-images/queue-proxy:latest` | -```yaml -apiVersion: operator.knative.dev/v1beta1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving -spec: - registry: - default: docker.io/knative-images/${NAME}:v0.13.0 -``` +2. Define your operator CR with following content: + + ```yaml + apiVersion: operator.knative.dev/v1beta1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + registry: + default: docker.io/knative-images/${NAME}:latest + ``` ### Download images individually without secrets If your custom image links are not defined in a uniform format by default, you will need to individually include each link in the CR. -For example, to given the following images: +For example, given the following images: | Container | Docker Image | |----|----| -| `activator` | `docker.io/knative-images-repo1/activator:v0.13.0` | -| `autoscaler` | `docker.io/knative-images-repo2/autoscaler:v0.13.0` | -| `controller` | `docker.io/knative-images-repo3/controller:v0.13.0` | -| `webhook` | `docker.io/knative-images-repo4/webhook:v0.13.0` | -| `autoscaler-hpa` | `docker.io/knative-images-repo5/autoscaler-hpa:v0.13.0` | -| `net-istio-controller` | `docker.io/knative-images-repo6/prefix-net-istio-controller:v0.13.0` | -| `net-istio-webhook` | `docker.io/knative-images-repo6/net-istio-webhooko:v0.13.0` | -| `queue-proxy` | `docker.io/knative-images-repo7/queue-proxy-suffix:v0.13.0` | +| `activator` | `docker.io/knative-images-repo1/activator:latest` | +| `autoscaler` | `docker.io/knative-images-repo2/autoscaler:latest` | +| `controller` | `docker.io/knative-images-repo3/controller:latest` | +| `webhook` | `docker.io/knative-images-repo4/webhook:latest` | +| `autoscaler-hpa` | `docker.io/knative-images-repo5/autoscaler-hpa:latest` | +| `net-istio-controller` | `docker.io/knative-images-repo6/prefix-net-istio-controller:latest` | +| `net-istio-webhook` | `docker.io/knative-images-repo6/net-istio-webhooko:latest` | +| `queue-proxy` | `docker.io/knative-images-repo7/queue-proxy-suffix:latest` | -The Operator CR should be modified to include the full list: +You must modify the Operator CR to include the full list. For example: ```yaml apiVersion: operator.knative.dev/v1beta1 @@ -195,14 +198,14 @@ metadata: spec: registry: override: - activator: docker.io/knative-images-repo1/activator:v0.13.0 - autoscaler: docker.io/knative-images-repo2/autoscaler:v0.13.0 - controller: docker.io/knative-images-repo3/controller:v0.13.0 - webhook: docker.io/knative-images-repo4/webhook:v0.13.0 - autoscaler-hpa: docker.io/knative-images-repo5/autoscaler-hpa:v0.13.0 - net-istio-controller/controller: docker.io/knative-images-repo6/prefix-net-istio-controller:v0.13.0 - net-istio-webhook/webhook: docker.io/knative-images-repo6/net-istio-webhook:v0.13.0 - queue-proxy: docker.io/knative-images-repo7/queue-proxy-suffix:v0.13.0 + activator: docker.io/knative-images-repo1/activator:latest + autoscaler: docker.io/knative-images-repo2/autoscaler:latest + controller: docker.io/knative-images-repo3/controller:latest + webhook: docker.io/knative-images-repo4/webhook:latest + autoscaler-hpa: docker.io/knative-images-repo5/autoscaler-hpa:latest + net-istio-controller/controller: docker.io/knative-images-repo6/prefix-net-istio-controller:latest + net-istio-webhook/webhook: docker.io/knative-images-repo6/net-istio-webhook:latest + queue-proxy: docker.io/knative-images-repo7/queue-proxy-suffix:latest ``` !!! note @@ -348,12 +351,12 @@ The key in `spec.config.istio` is in the format of `gateway.. Update `spec.ingress.istio.knative-local-gateway` to select the labels of the new cluster-local ingress gateway: -### Default local gateway name: +### Default local gateway name Go through the [installing Istio](../installing-istio.md#installing-istio-without-sidecar-injection) guide to use local cluster gateway, if you use the default gateway called `knative-local-gateway`. -### Non-default local gateway name: +### Non-default local gateway name If you create custom local gateway with a name other than `knative-local-gateway`, update `config.istio` and the `knative-local-gateway` selector: diff --git a/docs/install/operator/knative-with-operators.md b/docs/install/operator/knative-with-operators.md index 16b7d9d99..95be885e1 100644 --- a/docs/install/operator/knative-with-operators.md +++ b/docs/install/operator/knative-with-operators.md @@ -50,7 +50,7 @@ kubectl logs -f deploy/knative-operator ### Upgrade the existing custom resources -If you are upgrading an existing Operator install from v1.2 (or earlier) to v1.3 (or later), run the following command +If you are upgrading an existing Operator install from v1.2 or earlier to v1.3 or later, run the following command to upgrade the existing custom resources to `v1beta1`: ```bash @@ -68,28 +68,28 @@ To create the custom resource for the latest available Knative Serving in the Op 1. Copy the following YAML into a file: -```yaml -apiVersion: v1 -kind: Namespace -metadata: - name: knative-serving ---- -apiVersion: operator.knative.dev/v1beta1 -kind: KnativeServing -metadata: - 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. + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-serving + --- + apiVersion: operator.knative.dev/v1beta1 + kind: KnativeServing + metadata: + 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. 1. Apply the YAML file by running the command: -```bash -kubectl apply -f .yaml -``` + ```bash + kubectl apply -f .yaml + ``` -Where `` is the name of the file you created in the previous step. + Where `` is the name of the file you created in the previous step. ### Install the networking layer @@ -279,27 +279,27 @@ To create the custom resource for the latest available Knative Eventing in the O 1. Copy the following YAML into a file: -```yaml -apiVersion: v1 -kind: Namespace -metadata: - name: knative-eventing ---- -apiVersion: operator.knative.dev/v1beta1 -kind: KnativeEventing -metadata: - name: knative-eventing - namespace: knative-eventing -``` + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: knative-eventing + --- + apiVersion: operator.knative.dev/v1beta1 + kind: KnativeEventing + metadata: + 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. + !!! note + When you do not specify a version by using `spec.version` field, the Operator defaults to the latest available version. 1. Apply the YAML file by running the command: -```bash -kubectl apply -f .yaml -``` + ```bash + kubectl apply -f .yaml + ``` Where `` is the name of the file you created in the previous step.