Add the instructions on how to configure the operator CRs by houshengbo · Pull Request #2273 · knative/docs

houshengbo · 2020-03-04T19:23:42Z

Fixes #2277
The page of configuring serving CR: https://github.com/houshengbo/docs/blob/operator-cr-configuration/docs/install/operator/configuring-serving-cr.md
The page of configuring eventing CR: https://github.com/houshengbo/docs/blob/operator-cr-configuration/docs/install/operator/configuring-eventing-cr.md

Proposed Changes

This PR adds the the documentation on how to configure Knative by configuring the operator CRs.

aliok · 2020-03-05T06:49:41Z

cc @abrennan89

abrennan89

Some initial comments - I won't have time to review all of this today because it is a very large PR.

Please visit the developer style guide docs for tips on tone and style of writing - there is a lot of frivolous / unnecessary language in this PR which is taking a very long time for me to review. https://developers.google.com/style/tone

abrennan89 · 2020-03-09T17:26:47Z

+You are only able to configure Knative Eventing with the following option:
+
+* Private repository and private secret


Change to something like
"Knative Eventing can only be configured using a private repository and private secret."

abrennan89 · 2020-03-09T17:28:17Z

+
+* Private repository and private secret
+
+We configure Eventing operator CR the same way as Serving operator CR, with the same fields. Refer to the section of


Change to
"The Knative Eventing operator CR is configured similarly to the Knative Serving operator CR. For more information, see the documentation on Private repository and private secret."

abrennan89 · 2020-03-09T17:28:59Z

+
+We configure Eventing operator CR the same way as Serving operator CR, with the same fields. Refer to the section of
+“[Private repository and private secret](configuring-serving-cr.md#private-repository-and-private-secrets)” in Serving operator for detailed instruction. The difference is that Knative
+Eventing Operator only allows us to customize the images for all deployments: `eventing-controller`, `eventing-webhook`,


If it's 'all deployments' do we need to list them like this? What do we mean by 'deployments' here?

It means all deployment resources.

abrennan89 · 2020-03-09T17:29:38Z

+`imc-controller`, `imc-dispatcher`, and `broker-controller`. You need to either use these names as your names of the images
+in the repository, or to map your image links on a one-on-one basis.
+
+## Example 1 — download images in a predefined format without secrets:


Remove example part:
"Downloading images in a predefined format without secrets"

abrennan89 · 2020-03-09T17:52:38Z

+Suppose you use the custom tag v0.13.0 for all your images, and all the image links you have are able to accessible
+without secrets, and defined in the expected format: `docker.io/knative-images/${NAME}:v0.13.0`, you need to define your
+operator CR with following content:


Remove language like "Suppose...", again please refer to the https://developers.google.com/style/tone style guide.

Maybe something like:
"In the example below:

the custom tag v0.13.0 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}"

abrennan89 · 2020-03-09T18:05:42Z

+No matter you use the key `default` or `override` to define where to download your images, when you need to access your
+images with private secrets, you need to append a section called `imagePullSecrets` under `spec.registry`.
+
+The secret we are about to use is called `regcred`. It is your responsibility to create the private secrets, used to


Instead:

"This example uses a secret named regcred. You must create your own private secrets if these are required."

abrennan89 · 2020-03-09T18:06:05Z

+      - name: regcred
+```
+
+If you need to add another secret called `regcred-2`, add it as below:


Remove this, it doesn't add anything IMHO

I tend to keep this part, because it tells the users this field imagePullSecrets can accept a list of secrets.

abrennan89 · 2020-03-09T18:07:06Z

+- /docs/operator/configuring-serving-cr/
+---
+
+# Configuring Serving Operator Custom Resource


Configuring the Serving operator....

Also, use capitalization consistently. Either use Operator or operator - I think generally docs use lowercase.

abrennan89 · 2020-03-09T18:07:49Z

+
+# Configuring Serving Operator Custom Resource
+
+You are able to configure Knative Serving with the following options:


Instead:

"The Knative Serving operator can be configured with these options:"

abrennan89 · 2020-03-09T18:09:51Z

+* [Knative ingress gateway](#configuration-of-knative-ingress-gateway)
+* [Cluster local gateway](#configuration-of-cluster-local-gateway)
+
+Currently, Knative operators are __NOT__ able to configure the following options for Knative:


Make this a note instead of adding NOT formatting.
e.g.

NOTE: High availability and Kubernetes level policies cannot be configured using the Knative operators."

evankanderson · 2020-03-17T17:08:59Z

Right now, you're creating a new top-level section "operator" on the website with no front matter; I'd suggest putting your two new docs under docs/install/operator.

aliok

The content of the new 2 pages are technically all good.

evankanderson

Thanks for writing this up!

Since I think the goal is to get some documentation in quickly, I took the liberty of rewriting some portions of the text to flow more quickly and actively. Unfortunately, I don't have any great references to recommend for learning to write technical documentation in English more effectively; this is the combination of a number of years of grammar school (Middle School) along with an attempted minor in English).

evankanderson · 2020-04-17T17:26:21Z

+`deployment/container` as the unique key.
+
+Some images are defined via environment variable in Knative Eventing. They can be replaced by taking advantage of the
+`override` field.


Not for this PR, but it seems like there should be an issue to track a consistent resolution to this (the queue-proxy seems to be a somewhat similar problem in serving).

For this PR: can you link an issue that describes the problem (no solution needed)?

Added this link to the issue.

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-eventing-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com> Update docs/install/operator/configuring-serving-cr.md Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

googlebot · 2020-04-17T20:49:37Z

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.

evankanderson

A few small points, but looking much better. Thanks!

evankanderson · 2020-04-17T21:22:51Z

+
+The Knative Serving operator can be configured with these options:
+
+- [All the ConfigMaps](#all-the-configmaps)


I just read this, and it reads strangely:

"The Knative Serving operator can be configured with the option 'all the ConfigMaps'."

Maybe "Service Configuration by ConfigMap"?

You probably also want to change the last one to 'System Resource Settings', rather than saying "The Knative Serving operator can be configured with the option 'managing resources for containers'".

evankanderson · 2020-04-17T21:28:59Z

+
+For example, the following KnativeServing resource configures the `activator` to request 0.3 CPU and 100MB of RAM, and sets hard limits of 1 CPU, 250MB RAM, and 4GB of local storage:
+
+\```


You need to remove the "" here and on line 359. I can't use suggestion blocks for that, because they use the ``` shortcode.

evankanderson · 2020-04-17T21:35:00Z

+- [Private repository and private secret](#private-repository-and-private-secrets)
+- [Configuring default broker class](#configuring-default-broker-class)
+
+__NOTE:__ Kubernetes spec level policies cannot be configured using the Knative operators.


I'm not sure what this comment is supposed to mean. Are you trying to say that parts of the Eventing system components which aren't exposed by the operator can't be updated by end-users?

I think I should remove it for confusion. It did not mean anything informative.

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

evankanderson

/lgtm
/approve

knative-prow-robot · 2020-04-17T23:17:29Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: evankanderson, houshengbo

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [evankanderson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

evankanderson · 2020-04-17T23:21:39Z

@googlebot I consent

googlebot · 2020-04-17T23:21:54Z

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

googlebot added the cla: yes Indicates the PR's author has signed the CLA. label Mar 4, 2020

knative-prow-robot requested review from RichieEscarez and abrennan89 March 4, 2020 19:23

knative-prow-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Mar 4, 2020

mattmoor reviewed Mar 4, 2020

View reviewed changes

abrennan89 suggested changes Mar 9, 2020

View reviewed changes

knative-prow-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 17, 2020

abrennan89 added this to the 0.14.x milestone Mar 27, 2020

aliok reviewed Apr 3, 2020

View reviewed changes

Vincent Hou added 12 commits April 16, 2020 13:14

Explain how to configure the ConfigMaps with operator CRs

52e0e29

Describe how to configure private repository and private secrets

a698cba

Describe how to configure SSL certificate for controller

a9a2a91

Describe how to configure ingress gateway

c2d765b

Describe how to configure the local gateway

f03bb59

Describe how to configure HA

1c2914c

Add instruction on eventing operator CR

469d957

Change the description on default and override fields

1bcb771

Change the instruction on image overriding for Knative Eventing operator

fce20f7

Describe how to manage the container resources

c55107e

Add the description on defaultBrokerClass

cacb5f9

Add HA configuration to HorizontalPodAutoscaler

78b4772

houshengbo mentioned this pull request Apr 16, 2020

Add docs on the configuration of operator CRs knative/operator#18

Closed

evankanderson reviewed Apr 17, 2020

View reviewed changes

mattmoor reviewed Apr 17, 2020

View reviewed changes

Vincent and others added 2 commits April 17, 2020 15:58

Change the content based on the non-suggestion comments

1314955

googlebot added cla: no Indicates the PR's author has not signed the CLA. and removed cla: yes Indicates the PR's author has signed the CLA. labels Apr 17, 2020

evankanderson reviewed Apr 17, 2020

View reviewed changes

Vincent and others added 5 commits April 17, 2020 17:52

Update docs/install/operator/configuring-serving-cr.md

729828f

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

Update docs/install/operator/configuring-serving-cr.md

7f3b11f

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

Update docs/install/operator/configuring-serving-cr.md

bde3359

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

Update docs/install/operator/configuring-serving-cr.md

1928a27

Co-Authored-By: Evan Anderson <evan.k.anderson@gmail.com>

Fix based on the comments

d82ae8b

evankanderson reviewed Apr 17, 2020

View reviewed changes

knative-prow-robot assigned evankanderson Apr 17, 2020

knative-prow-robot added the lgtm Indicates that a PR is ready to be merged. label Apr 17, 2020

knative-prow-robot added the approved label Apr 17, 2020

googlebot added cla: yes Indicates the PR's author has signed the CLA. and removed cla: no Indicates the PR's author has not signed the CLA. labels Apr 17, 2020

knative-prow-robot merged commit c79c75a into knative:master Apr 17, 2020

abrennan89 mentioned this pull request Jun 11, 2020

Add abrennan89 to doc-approvers #2579

Merged

3 tasks

		You are only able to configure Knative Eventing with the following option:

		* Private repository and private secret


		* Private repository and private secret

		We configure Eventing operator CR the same way as Serving operator CR, with the same fields. Refer to the section of


		# Configuring Serving Operator Custom Resource

		You are able to configure Knative Serving with the following options:


		The Knative Serving operator can be configured with these options:

		- [All the ConfigMaps](#all-the-configmaps)


		For example, the following KnativeServing resource configures the `activator` to request 0.3 CPU and 100MB of RAM, and sets hard limits of 1 CPU, 250MB RAM, and 4GB of local storage:

		\```

Conversation

houshengbo commented Mar 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed Changes

Uh oh!

aliok commented Mar 5, 2020

Uh oh!

abrennan89 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evankanderson commented Mar 17, 2020

Uh oh!

aliok left a comment

Choose a reason for hiding this comment

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

googlebot commented Apr 17, 2020

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

knative-prow-robot commented Apr 17, 2020

houshengbo commented Mar 4, 2020 •

edited

Loading