From 1bcd6e44fffdbefc0ae22110d84f9434ed14f4e8 Mon Sep 17 00:00:00 2001
From: Vincent Hou <shou@us.ibm.com>
Date: Fri, 18 Dec 2020 16:49:31 -0500
Subject: [PATCH] Add the description on how to to append customized the
 manifests

---
 docs/install/knative-with-operators.md | 70 ++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/docs/install/knative-with-operators.md b/docs/install/knative-with-operators.md
index 4ad8319f200..d8f63d4703d 100644
--- a/docs/install/knative-with-operators.md
+++ b/docs/install/knative-with-operators.md
@@ -143,9 +143,15 @@ Put the manifest you want to apply first on the top.
 Knative Serving based your own requirements. As long as the manifests of customized Knative Serving are accessible to
 the operator, they can be installed.
 
-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 below:
+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 below to install your Knative Serving and the istio ingress:
 
 ```
 apiVersion: v1
@@ -170,6 +176,30 @@ of links. The ordering of the URLs is critical. Put the manifest you want to app
 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.
 
+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 below:
+
+```
+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
+```
+
+Knative operator will install the default manifests of Knative Serving at the version `{{spec.version}}`, and then install
+your customized manifests based on them.
+
 {{< /tab >}}
 
 {{< /tabs >}}
@@ -621,8 +651,14 @@ to apply first on the top.
 Knative Eventing based your own requirements. As long as the manifests of customized Knative Eventing are accessible to
 the operator, they can be installed.
 
-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 as below:
+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 as below to install your Knative Eventing:
 
 ```
 apiVersion: v1
@@ -646,6 +682,30 @@ of links. The ordering of the URLs is critical. Put the manifest you want to app
 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.
 
+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 below:
+
+```
+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
+```
+
+Knative operator will install the default manifests of Knative Eventing at the version `{{spec.version}}`, and then install
+your customized manifests based on them.
+
 {{< /tab >}}
 
 {{< /tabs >}}