Create Editing ConfigMaps page

docs/versioned/.nav.yml

@@ -265,7 +265,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

@@ -48,6 +48,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.

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.