Create Editing ConfigMaps page (#6466)

* Create editing-configmaps.md

Initial draft

* Update .nav.yml

Added page to the Nav

* Update editing-configmaps.md

Processed reviewer edits

* Update editing-configmaps.md

Removed unneeded content

* Update editing-configmaps.md

Worked on Brokers section

* Update editing-configmaps.md

Added links to Brokers section

* Update editing-configmaps.md

Grammer edits

* Update editing-configmaps.md

Refocused content on just working with ConfigMaps. Removed generalized info not Knative specific.

* Update editing-configmaps.md

Reviewer edits

* Update editing-configmaps.md

Updated _example key content and reviewer edits

* Update editing-configmaps.md

Misc edits

* Update editing-configmaps.md

Removed Value Propagation - not needed

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update editing-configmaps.md

Line annotation test

* Update editing-configmaps.md

Highlighting code lines test

* Nav update and annotation testing

Testing code blocks annotations

* Update editing-configmaps.md

Line numbers test

* Update editing-configmaps.md

Fixes and reviewer edits

* Update editing-configmaps.md

removed unneeded error example

* Update editing-configmaps.md

One last annotation test

* Update editing-configmaps.md

Made reviewer edits

* Update editing-configmaps.md

Worked on the canonical edit - git v cluster

* Update editing-configmaps.md

Reviewer edits

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update docs/versioned/admin/editing-configmaps.md

Co-authored-by: Evan Anderson <[email protected]>

* Update editing-configmaps.md

Copy edits

* Update admin-overview.md

Added link to 'Working with ConfigMaps'.

---------

Co-authored-by: Evan Anderson <[email protected]>

Author: iRaindrop

docs/versioned/.nav.yml

@@ -263,7 +263,7 @@ nav:
         # Vendor list
         - Using a Knative-based offering: install/knative-offerings.md
       - Configuring Knative:
-        # TODO: add a doc on editing ConfigMaps
+        - Working with ConfigMaps: admin/editing-configmaps.md
         - Configure high-availability components: serving/config-ha.md
         - Exclude namespaces from the Knative webhook: serving/webhook-customizations.md
         - Networking Options:

docs/versioned/admin/admin-overview.md

@@ -108,6 +108,8 @@ Knative configurations are performed by the following methods:
 
     Store and manage configuration data as key-value pairs. ConfigMaps are frequently used to tune platform-wide behavior. Most of the Knative ConfigMaps are in the `knative-serving` and `knative-eventing` namespaces. Their settings apply to all the relevant Knative components in all namespaces.
 
+    See [Working with ConfigMaps](editing-configmaps.md) for important usage information and best practices.
+
 - Using the Knative Operator
 
     Some platform-wide settings can be managed declaratively using the Knative Operator, installed with the `kn` Knative CLI plugin. You can manage the operator without using the `kn` CLI. The `kn` CLI manages only operator installations.

docs/versioned/admin/editing-configmaps.md

@@ -0,0 +1,75 @@
+---
+audience: administrator
+components:
+  - serving
+  - eventing
+function: explanation
+---
+
+# Working with ConfigMaps
+
+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.
+
+If you are using the Knative Operator to install and manage your Knative cluster, you should not edit the ConfigMaps directly as the Operator will overwrite the changes. See [Configuring Knative by using the Operator](../install/operator/configuring-with-operator.md) for information on how to manage ConfigMaps using the operator.
+
+## The _example key
+
+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 does contains a value which acts as a documentation comment.
+
+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.
+
+Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the `example-checksum` annotation.
+
+For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checksum highlighted on line 11.
+
+```yml linenums="1" hl_lines="11"
+piVersion: v1
+kind: ConfigMap
+metadata:
+  name: config-defaults
+  namespace: knative-serving
+  labels:
+    app.kubernetes.io/name: knative-serving
+    app.kubernetes.io/component: controller
+    app.kubernetes.io/version: devel
+  annotations:
+    knative.dev/example-checksum: "5b64ff5c"
+data:
+  _example: |
+    ################################
+    #                              #
+    #    EXAMPLE CONFIGURATION     #
+    #                              #
+    ################################
+
+    # This block is not actually functional configuration,
+    # but serves to illustrate the available configuration
+    # options and document them in a way that is accessible
+    # to users that `kubectl edit` this config map.
+    #
+```
+
+## Best practices
+
+### Validate and Test Changes
+
+Knative controllers process new values, including roll-backs to previous values, within a few seconds after being applied.
+
+- Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or use `kubectl apply --dry-run=server`.
+- Test ConfigMap changes in a staging environment to ensure compatibility with the application version.
+
+### Storage and versioning
+
+How you manage storage relates the canonical locations of both the cluster and Git. If your cluster is canonical, then you're exporting or backing up the configuration to Git. If Git is canonical, then you're practicing GitOps, and you should make changes in Git and then apply the files from Git to your cluster.
+
+If you manage the ConfigMap by using `kubectl edit`, periodically export ConfigMaps from the cluster with `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 or use automation (for example Flux or ArgoCD) to apply the changes after they are committed.
+
+### Git recommendations
+
+In addition to diligent usage of commit messages, here are some suggestions for ConfigMaps in GitHub:
+
+- Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository, such as `k8s/configmaps/`.
+- Tag commits in Git with version numbers, such as `git tag config-v1.2.3` to mark specific ConfigMap versions.
+- Implement a GitOps workflow with tools like ArgoCD or Flux to synchronize ConfigMaps from Git to your Kubernetes cluster.