Create Editing ConfigMaps page #6466
Conversation
Initial draft
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
knative-prow
bot
added
the
size/L
knative-prow
bot
added
the
do-not-merge/work-in-progress
Added page to the Nav
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
Thanks for this draft! Unfortunately, I think pulling in a lot of the general-purposes reference material about using ConfigMaps with generic applications obscured (rather than clarified) how Knative administrators need to interact with the ConfigMaps used to configure Knative.
|
/assign |
Processed reviewer edits
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: iRaindrop The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
It looks like the recent commit only addressed some comments, so I didn't repeat all the outstanding comments.
| ## Value propagation | ||
| The ConfigMap change is immediate in the Kubernetes API, but its effect on Pods or applications depends on how the ConfigMap is consumed (volume, environment variables, or API) and whether the application or Pod is designed to pick up the change dynamically or requires a restart. For volumes, updates propagate within seconds, but for environment variables, a Pod restart is needed. |
There was a problem hiding this comment.
I'm not sure if any of this "value propagation" information is necessary given how Knative watches ConfigMaps directly.
| ### Track Object Version in ConfigMap | ||
|
|
||
| - Include a version field in the ConfigMap’s data to explicitly track the version of the application or configuration it represents. | ||
|
|
||
| ```yaml | ||
| data: | ||
| app.properties: | | ||
| version=1.2.3 | ||
| # other settings | ||
| ``` | ||
|
|
||
| - Alternatively, use annotations in the ConfigMap’s metadata: | ||
|
|
||
| ```yaml | ||
| metadata: | ||
| name: my-app-config | ||
| annotations: | ||
| app-version: "1.2.3" | ||
| ``` |
There was a problem hiding this comment.
(this still seems to be an issue)
Removed unneeded content
Worked on Brokers section
Added links to Brokers section
Grammer edits
Refocused content on just working with ConfigMaps. Removed generalized info not Knative specific.
knative-prow
bot
added
size/M
| --- | ||
| # Editing ConfigMaps | ||
|
|
||
| This page provides information and best practices for editing ConfigMaps. Knative uses ConfigMaps to manage most system-level configuration, including default values, minimum and maximum values, and names and addresses of connecting services. Because Knative is implemented as a set of controllers, Knative watches the ConfigMaps and updates behavior live shortly after the ConfigMap is updated. |
There was a problem hiding this comment.
IMO, we should add a line here explaining that if you use the Knative Operator, the fields in the Operator resources (KnativeServing and KnativeEventing) are used to fill out the ConfigMap, and you shouldn't edit the ConfigMaps directly -- the operator will overwrite your changes.
Reviewer edits
Updated _example key content and reviewer edits
knative-prow
bot
added
size/L
Misc edits
knative-prow
bot
added
size/M
Removed Value Propagation - not needed
Co-authored-by: Evan Anderson <[email protected]>
Co-authored-by: Evan Anderson <[email protected]>
Co-authored-by: Evan Anderson <[email protected]>
Line annotation test
Highlighting code lines test
Testing code blocks annotations
Line numbers test
Fixes and reviewer edits
removed unneeded error example
One last annotation test
Made reviewer edits
Worked on the canonical edit - git v cluster
Reviewer edits
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
This is getting close! I added a couple suggested wording changes, and a bit of a rewrite on the what-happens-when-you-edit-_example section.
As a side note, Markdown will treat a single newline as simple whitespace. Using newlines like this can be helpful to break up larger paragraphs into 80-character or 1-sentence lines. Since GitHub reviews are line-based, shorter lines can enable more precise commenting on sections of a paragraph; the diffs from the suggestion feature can also be easier to read if each individual line is not too wide
|
|
||
| # Working with ConfigMaps | ||
|
|
||
| This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps are the primary means for managing configuration values for Knative controllers. |
There was a problem hiding this comment.
| This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps are the primary means for managing configuration values for Knative controllers. | |
| This page provides important Knative-specific information and best practices for managing cluster configuration using ConfigMaps. ConfigMaps are the primary means for managing configuration values for Knative controllers. |
|
|
||
| ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of all the known configuration keys in that ConfigMap. This key does not affect Knative behavior, but contains a value which acts as a documentation comment. | ||
|
|
||
| If a user edits the `_example` key by mistakenly thinking their edits don't effect on the cluster operation, the Knative webhook catches the error and alerts the user that their update could not be patched. More specifically, the edit is caught when the value of the checksum for the `_example` key is different when compared with the `knative.dev/example-checksum` annotation on the ConfigMap. If the checksum is null or missing, the webhook server does not create the warning. |
There was a problem hiding this comment.
| If a user edits the `_example` key by mistakenly thinking their edits don't effect on the cluster operation, the Knative webhook catches the error and alerts the user that their update could not be patched. More specifically, the edit is caught when the value of the checksum for the `_example` key is different when compared with the `knative.dev/example-checksum` annotation on the ConfigMap. If the checksum is null or missing, the webhook server does not create the warning. | |
| If a user edits the `_example` key rather than creating a new key in the ConfigMap, the changes won't affect the cluster cluster configuration, which can be confusing. The Knative webhook flags this error and alerts the user that their update could not be patched. More specifically, the edit is caught when the checksum for the `_example` key differs from the `knative.dev/example-checksum` annotation on the ConfigMap. If the checksum is null or missing, the webhook does not create the warning. |
The sentence here had some awkward wording "by mistakenly thinking ... don't effect on ...". I think this reads more smoothly?
|
|
||
| Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation. | ||
|
|
||
| For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checkum highlighted. |
There was a problem hiding this comment.
| For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checkum highlighted. | |
| For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checksum highlighted. |
|
|
||
| If you manage the ConfigMap by using `kubectl edit`, periodically export ConfigMaps from the cluster (`kubectl get configmap -o yaml`) and commit them to Git for recovery purposes. Include applicable version numbers in `app.properties` as needed. | ||
|
|
||
| If you manage the ConfigMap by keeping the definition in Git and automatically applying it to the cluster (GitOps), you can apply the changes manually sor use automation (for example Flux or ArgoCD) to apply the changes once they are committed. |
There was a problem hiding this comment.
| If you manage the ConfigMap by keeping the definition in Git and automatically applying it to the cluster (GitOps), you can apply the changes manually sor use automation (for example Flux or ArgoCD) to apply the changes once they are committed. | |
| If you manage the ConfigMap by keeping the definition in Git and automatically applying it to the cluster (GitOps), you can apply the changes manually or use automation (for example Flux or ArgoCD) to apply the changes after they are committed. |
2 participants
Need to alert users about not modifying the _example key, value propagation, versioning, and other tips about ConfigMaps.
Proposed Changes