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
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.
|
|
||
| ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. The key itself is not a key, but a long comment. | ||
|
|
||
| In case a user edits the `_example` key by mistakenly thinking their edits would have an affect, the administrator needs to be alerted. The Knative webhook server determines if the `_example key` has been altered. The edit is caught when the value of the checksum for the `_example` key is different when compared with the pod's template annotations. If the checksum is null however, it does not create the warning. |
There was a problem hiding this comment.
This phrasing is slightly confusing. If you have a quickstart cluster, it might be informative to simply try editing one of the configmaps with something like kubectl edit --namespace knative-serving config-default, and see what message you get when you edit the _example. That message has been fairly stable, and including it in the documentation would help for people searching for that error string.
| ### Validate and Test Changes | ||
|
|
||
| - Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or `kubectl apply --dry-run=client`. | ||
| - Test ConfigMap changes in a staging environment to ensure compatibility with the application version. |
There was a problem hiding this comment.
These are general best-practices, but I think the more useful thing to know is that Knative will do some validation when the ConfigMap is updated. (Verify this in a quickstart cluster, and you might include the error messages provided.)
Note that ConfigMaps in general don't support this type of validation, but Knative has added validating admission webhooks to perform these checks before the configuration is submitted to the cluster.
There was a problem hiding this comment.
This topic covers editing the ConfigMaps, which is great, but it doesn't explain how the operator interacts with ConfigMaps. IIRC, the operator will write and update ConfigMaps, so if you're using the operator, you should update the KnativeServing and KnativeEventing custom resources instead of directly editing ConfigMap values.
|
/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 |
| ## 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.
|
|
||
| When creating a Broker class, you can define default values and settings on different levels of scope. You can specify a ConfigMap that defines the implementation of the Broker, and apply it in different ways. | ||
|
|
||
| Knative uses `MTChannelBasedBroker` as the default class for creating Brokers. For scopes at the namespace level, you can specify which Broker class to use for a particular namespace. |
There was a problem hiding this comment.
I'm not sure I understand the second sentence here -- where are you picking that content up from?
There was a problem hiding this comment.
It was from aggregated from eventing/brokers/broker-developer-config-options.md and eventing/brokers/broker-types/channel-based-broker/README.md - but won't be using
|
|
||
| ### Validate and Test Changes | ||
|
|
||
| - Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or `kubectl apply --dry-run=client`. |
There was a problem hiding this comment.
The --dry-run=server option should run the webhook validation, and is probably better than --dry-run=client.
| ### Immutable ConfigMaps | ||
|
|
||
| If you have services processing information that must not change, such as for finances and payment processing, consider using immutable ConfigMaps. This approach ensures ConfigMaps are not modified in-place, preserving historical versions. |
There was a problem hiding this comment.
Immutable ConfigMaps don't work for the Knative configuration, because the Knative controllers look up specific ConfigMap names, and immutable ConfigMaps need a new name each time.
Reviewer edits
2 participants
Need to alert users about not modifying the _example key, value propagation, versioning, and other tips about ConfigMaps.
Proposed Changes