From e246c3c8ba1f03d483218460ca59ad622cd6fabe Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Oct 2025 14:54:59 -0700 Subject: [PATCH 01/31] Create editing-configmaps.md Initial draft --- docs/versioned/admin/editing-configmaps.md | 155 +++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/versioned/admin/editing-configmaps.md diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md new file mode 100644 index 0000000000..0f37534ac0 --- /dev/null +++ b/docs/versioned/admin/editing-configmaps.md @@ -0,0 +1,155 @@ +--- +audience: administrator +components: + - serving + - eventing +function: explanation +--- +# Editing ConfigMaps + +This page provides information and best practices for editing ConfigMaps. While there is no technical difference in how Knative uses ConfigMaps in Kubernetes, you should be aware of the following points and tips while working with ConfigMaps: + +- The _example key. Don't modify. +- Value propagation. Know when changes to default settings take affect. +- Version control. Use ConfigMaps for version control. + +The most common way to use ConfigMaps is to configure settings for containers running in a Pod, or in multiple pods, that use a specified namespace. There are a number of other ways to use ConfigMaps as described in [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) documentation. + +## The _example key + +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. + +Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation: + +```yml +... +annotations: + knative.dev/example-checksum: "47c2487f" +``` + +To accurately create a ConfigMap using an existing file, use the Kubernetes[Define the key to use when creating a configmap from a file](https://kubernetes.io/dos/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) + +## 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. + +When a ConfigMap currently consumed in a volume is updated, projected keys are eventually updated as well. The `kubelet` checks whether the mounted ConfigMap is fresh on every periodic sync. + +Kubernetes does not automatically restart Pods when a ConfigMap changes, even if the ConfigMap is referenced. You may need to trigger a rolling update (e.g., via `kubectl rollout restart`) to ensure the changes are applied to running Pods. + +A ConfigMap can be either propagated by watch (default), ttl-based, or by redirecting all requests directly to the API server. Because the `kubelet` uses its local cache for getting the current value of the ConfigMap, there is a delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the Pod. The total delay can be as long as the `kubelet` sync period added to the cache propagation delay. The type of the cache is configurable using the `configMapAndSecretChangeDetectionStrategy` field in the [KubeletConfiguration struct](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/). + +When a field in a ConfigMap is changed, the effect of the change depends on how the ConfigMap is used by the application or resource uses it. Here's a breakdown: + +- Immediate Update in Kubernetes API - When you modify a ConfigMap (e.g., using `kubectl edit`, `kubectl apply`, or an API call), the change is immediately reflected in the Kubernetes API and stored in etcd clusters - a consistent and highly-available key value store used as Kubernetes' backing store for all cluster data. The updated ConfigMap is available for querying instantly. + +- Mounted as Volumes - If the ConfigMap is mounted as a volume in a Pod, Kubernetes automatically propagates changes to the ConfigMap to the Pod's filesystem. This process typically takes a few seconds to up to 60 seconds because of the kubelet sync interval. Applications should detect or reload these changes (e.g., by watching the file or restarting). +- Environment Variables - If the ConfigMap is used to set environment variables in a Pod, changes to the ConfigMap do not automatically propagate to the Pod. Pods must be restarted (e.g., by deleting and recreating them) for the updated ConfigMap values to take effect, as environment variables are set at container startup. +- Direct API Access - If an application directly queries the ConfigMap via the Kubernetes API, it will see the updated values immediately after the change is applied. +- Special Cases - Some applications or operators (e.g., those using tools like `reloader`) can watch for ConfigMap changes and automatically trigger Pod restarts or reloads. +- If the ConfigMap is used by a controller (e.g., a Deployment), changes might not affect running Pods unless the controller reconciles the change, which depends on its implementation. + +## Version control + +To maintain version control of Kubernetes ConfigMap settings and the version of the object they represent, you can follow these practices. + +### Store ConfigMaps as code + +Define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: + + ```yml + apiVersion: v1 + kind: ConfigMap + metadata: + name: my-app-config + namespace: default + data: + _example | ... + app.properties: | + version=1.2.3 + db.host=localhost + db.port=5432 + ``` + +- Commit these files to a Git repository to track changes over time. + +### Versioning ConfigMaps in Git + +- Use meaningful commit messages to describe changes to ConfigMap data (e.g., "Updated app.properties to version 1.2.4"). +- Tag commits in Git with version numbers (e.g., `git tag config-v1.2.3`) to mark specific ConfigMap versions. +- Use branches for different environments (e.g., `dev`, `staging`, `prod`) or feature-specific ConfigMap changes. + +### 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" + ``` + +### Use GitOps for Deployment + +- Implement a GitOps workflow with tools like ArgoCD or Flux to synchronize ConfigMaps from Git to your Kubernetes cluster. +- These tools detect changes in the Git repository and automatically apply them to the cluster, ensuring the deployed ConfigMap matches the versioned configuration in Git. + +### Immutable ConfigMaps with Versioned Names + +- Create immutable ConfigMaps by appending a version or hash to the ConfigMap name (e.g., `my-app-config-v1.2.3` or `my-app-config-abc123`). +- Update the application’s Deployment or Pod to reference the new ConfigMap version when rolling out changes. + + ```yaml + apiVersion: apps/v1 + kind: Deployment + spec: + template: + spec: + containers: + - name: my-app + envFrom: + - configMapRef: + name: my-app-config-v1.2.3 + ``` + +- This approach ensures ConfigMaps are not modified in-place, preserving historical versions. + +### Track Changes in Kubernetes + +- Use Kubernetes resource versioning (e.g., `resourceVersion` in metadata) to track changes to the ConfigMap object itself within the cluster. However, this is managed by Kubernetes and not suitable for application-level versioning. +- Enable audit logging in Kubernetes to track who modified ConfigMaps and when. + +### Use Helm for Versioned Configurations + +- If using Helm, store ConfigMaps in Helm chart templates or values files and version the chart itself (e.g., `Chart.yaml` with `version: 1.2.3`). +- Helm’s release history can track which ConfigMap versions were deployed. + +### Automate Version Updates + +- Use CI/CD pipelines (e.g., GitHub Actions, Jenkins) to automate updates to the version field in ConfigMaps when the application version changes. +- Example: A pipeline updates `app.properties` with `version=1.2.4` and commits the change to Git. + +### 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. + +### Best Practices + +- Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository (e.g., `k8s/configmaps/`). +- Use Descriptive Naming: Name ConfigMaps clearly (e.g., `app-name-environment-config`) to avoid confusion. +- Document Changes: Include a `CHANGELOG.md` in your repository to document ConfigMap updates alongside application changes. +- Backup ConfigMaps: Periodically export ConfigMaps from the cluster (`kubectl get configmap -o yaml`) and commit them to Git for recovery purposes. + From d05c343fbef32abde3456d6b82fc5ee1daae0247 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Oct 2025 15:03:43 -0700 Subject: [PATCH 02/31] Update .nav.yml Added page to the Nav --- docs/versioned/.nav.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 75968b917d..998c709863 100644 --- a/docs/versioned/.nav.yml +++ b/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 + - Editing 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: From a42327c4a380b1c7f1ee879977b42a9527e4233d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 23 Oct 2025 17:20:42 -0700 Subject: [PATCH 03/31] Update editing-configmaps.md Processed reviewer edits --- docs/versioned/admin/editing-configmaps.md | 23 +++------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 0f37534ac0..3c0b2823c0 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -7,17 +7,11 @@ function: explanation --- # Editing ConfigMaps -This page provides information and best practices for editing ConfigMaps. While there is no technical difference in how Knative uses ConfigMaps in Kubernetes, you should be aware of the following points and tips while working with ConfigMaps: - -- The _example key. Don't modify. -- Value propagation. Know when changes to default settings take affect. -- Version control. Use ConfigMaps for version control. - -The most common way to use ConfigMaps is to configure settings for containers running in a Pod, or in multiple pods, that use a specified namespace. There are a number of other ways to use ConfigMaps as described in [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) documentation. +This page provides information and best practices for editing ConfigMaps. Knative usually 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 should update behavior live shortly after the ConfigMap is updated. ## The _example key -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. +ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. This key does not affect Knative behavior, but contains a value which acts as a documentation 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. @@ -128,18 +122,7 @@ Define ConfigMaps in YAML or JSON files and store them in a version control syst ### Track Changes in Kubernetes -- Use Kubernetes resource versioning (e.g., `resourceVersion` in metadata) to track changes to the ConfigMap object itself within the cluster. However, this is managed by Kubernetes and not suitable for application-level versioning. -- Enable audit logging in Kubernetes to track who modified ConfigMaps and when. - -### Use Helm for Versioned Configurations - -- If using Helm, store ConfigMaps in Helm chart templates or values files and version the chart itself (e.g., `Chart.yaml` with `version: 1.2.3`). -- Helm’s release history can track which ConfigMap versions were deployed. - -### Automate Version Updates - -- Use CI/CD pipelines (e.g., GitHub Actions, Jenkins) to automate updates to the version field in ConfigMaps when the application version changes. -- Example: A pipeline updates `app.properties` with `version=1.2.4` and commits the change to Git. +Enable audit logging in Kubernetes to track who modified ConfigMaps and when. ### Validate and Test Changes From 275dd3c7012f75578f3e0eced5071441d15e65d8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 24 Oct 2025 10:41:57 -0700 Subject: [PATCH 04/31] Update editing-configmaps.md Removed unneeded content --- docs/versioned/admin/editing-configmaps.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 3c0b2823c0..0ad21471cd 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -25,20 +25,11 @@ annotations: To accurately create a ConfigMap using an existing file, use the Kubernetes[Define the key to use when creating a configmap from a file](https://kubernetes.io/dos/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) -## 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. - -When a ConfigMap currently consumed in a volume is updated, projected keys are eventually updated as well. The `kubelet` checks whether the mounted ConfigMap is fresh on every periodic sync. - -Kubernetes does not automatically restart Pods when a ConfigMap changes, even if the ConfigMap is referenced. You may need to trigger a rolling update (e.g., via `kubectl rollout restart`) to ensure the changes are applied to running Pods. - -A ConfigMap can be either propagated by watch (default), ttl-based, or by redirecting all requests directly to the API server. Because the `kubelet` uses its local cache for getting the current value of the ConfigMap, there is a delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the Pod. The total delay can be as long as the `kubelet` sync period added to the cache propagation delay. The type of the cache is configurable using the `configMapAndSecretChangeDetectionStrategy` field in the [KubeletConfiguration struct](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/). +## Monitoring values When a field in a ConfigMap is changed, the effect of the change depends on how the ConfigMap is used by the application or resource uses it. Here's a breakdown: - Immediate Update in Kubernetes API - When you modify a ConfigMap (e.g., using `kubectl edit`, `kubectl apply`, or an API call), the change is immediately reflected in the Kubernetes API and stored in etcd clusters - a consistent and highly-available key value store used as Kubernetes' backing store for all cluster data. The updated ConfigMap is available for querying instantly. - - Mounted as Volumes - If the ConfigMap is mounted as a volume in a Pod, Kubernetes automatically propagates changes to the ConfigMap to the Pod's filesystem. This process typically takes a few seconds to up to 60 seconds because of the kubelet sync interval. Applications should detect or reload these changes (e.g., by watching the file or restarting). - Environment Variables - If the ConfigMap is used to set environment variables in a Pod, changes to the ConfigMap do not automatically propagate to the Pod. Pods must be restarted (e.g., by deleting and recreating them) for the updated ConfigMap values to take effect, as environment variables are set at container startup. - Direct API Access - If an application directly queries the ConfigMap via the Kubernetes API, it will see the updated values immediately after the change is applied. From 04fe58e48d9299aa340344e806270be74838098e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 27 Oct 2025 12:03:04 -0700 Subject: [PATCH 05/31] Update editing-configmaps.md Worked on Brokers section --- docs/versioned/admin/editing-configmaps.md | 48 +++++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 0ad21471cd..ca24ab0fc1 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -7,7 +7,49 @@ function: explanation --- # Editing ConfigMaps -This page provides information and best practices for editing ConfigMaps. Knative usually 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 should update behavior live shortly after the ConfigMap is updated. +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. + +## Configurations overview + +### Knative Operator and YAML installations + +To be written. + +### Brokers + +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. On the more wider level of scope, you can specify which Broker class to use for a particular namespace. + +To create a customized Broker class, you can do either or both of the following: + +- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. These ConfigMaps are used when a `spec.config` is *not* the class. For example, use this method if you want to use a `KafkaBroker` Broker class for all other Brokers created on the cluster, but a particular Broker class for Brokers created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. + +- Specify a ConfigMap to use in the `spec.config` keys in the Broker class you're defining. That ConfigMap must have a `channel-template-spec` that defines the channel implementation for the Broker. + +Set other default configurations for Brokers with these ConfigMaps: + +- `config-features` - Defines defaults for features including integration, sender identity, and transport encryption. +- `default-ch-webhook` - Defines default channel implementation settings. +- `config-kafka-sink-data-plane` - Used for sending events to the Apache Kafka cluster. +- `config-ping-defaults` - Defines event resources, such as the the maximum amount of data PingSource can add to cloud events. +- `sugar-controller` - Manages eventing resources in a cluster or namespace. Disable Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. + +### Observability and logging + +To be written. + +### Deployments and resources + +To be written. + +### Networking and domains + +To be written. + +### Security + +To be written. ## The _example key @@ -123,7 +165,9 @@ Enable audit logging in Kubernetes to track who modified ConfigMaps and when. ### Best Practices - Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository (e.g., `k8s/configmaps/`). -- Use Descriptive Naming: Name ConfigMaps clearly (e.g., `app-name-environment-config`) to avoid confusion. +- Use Descriptive Naming: Name ConfigMaps cn + +- learly (e.g., `app-name-environment-config`) to avoid confusion. - Document Changes: Include a `CHANGELOG.md` in your repository to document ConfigMap updates alongside application changes. - Backup ConfigMaps: Periodically export ConfigMaps from the cluster (`kubectl get configmap -o yaml`) and commit them to Git for recovery purposes. From e2decb8e7c5112cc114cfef600f3d17fb630794c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 27 Oct 2025 21:52:50 -0700 Subject: [PATCH 06/31] Update editing-configmaps.md Added links to Brokers section --- docs/versioned/admin/editing-configmaps.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index ca24ab0fc1..184c0ee307 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -21,19 +21,22 @@ When creating a Broker class, you can define default values and settings on diff Knative uses `MTChannelBasedBroker` as the default class for creating Brokers. On the more wider level of scope, you can specify which Broker class to use for a particular namespace. +For details, see [Broker Configuration Options](../eventing/brokers/broker-developer-config-options.md), [Configure broker defaults](../eventing/configuration/broker-configuration.md) and [Channel based broker](../eventing/brokers/broker-types/channel-based-broker/README.md). + To create a customized Broker class, you can do either or both of the following: -- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. These ConfigMaps are used when a `spec.config` is *not* the class. For example, use this method if you want to use a `KafkaBroker` Broker class for all other Brokers created on the cluster, but a particular Broker class for Brokers created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. +- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. These ConfigMaps are used when a `spec.config` is *not* the class. For example, use this method if you want to use a [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) for all other Brokers created on the cluster, but a particular Broker class for Brokers created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. - Specify a ConfigMap to use in the `spec.config` keys in the Broker class you're defining. That ConfigMap must have a `channel-template-spec` that defines the channel implementation for the Broker. Set other default configurations for Brokers with these ConfigMaps: -- `config-features` - Defines defaults for features including integration, sender identity, and transport encryption. -- `default-ch-webhook` - Defines default channel implementation settings. -- `config-kafka-sink-data-plane` - Used for sending events to the Apache Kafka cluster. -- `config-ping-defaults` - Defines event resources, such as the the maximum amount of data PingSource can add to cloud events. -- `sugar-controller` - Manages eventing resources in a cluster or namespace. Disable Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. +- `config-features` - Defines defaults for features including integration, sender identity, and transport encryption. See [Eventing integration with Istio service mesh](../eventing/features/istio-integration.md). +- `default-ch-webhook` - Defines default channel implementation settings. See [Channel types and defaults](../eventing/channels/channel-types-defaults.md). +- `config-kafka-features` - Enable KEDA autoscaling. See [Configure KEDA Autoscaling of Knative Kafka Resources](../eventing/configuration/keda-configuration.md). +- `config-kafka-sink-data-plane` - Used for sending events to the Apache Kafka cluster. See [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) +- `config-ping-defaults` - Defines event resources, such as the the maximum amount of data PingSource can add to cloud events. See [Configure event source defaults](../eventing/configuration/sources-configuration.md). +- `sugar-controller` - The default controller that manages eventing resources in a cluster or namespace. Disable Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. See [Configure Sugar Controller](../eventing/configuration/sugar-configuration.md) ### Observability and logging From a9eaaff9dcf20a79c88d333bee4bee3f916025d2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 27 Oct 2025 23:01:00 -0700 Subject: [PATCH 07/31] Update editing-configmaps.md Grammer edits --- docs/versioned/admin/editing-configmaps.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 184c0ee307..5d5ef9efbb 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -19,24 +19,24 @@ To be written. 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. On the more wider level of scope, you can specify which Broker class to use for a particular namespace. +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. For details, see [Broker Configuration Options](../eventing/brokers/broker-developer-config-options.md), [Configure broker defaults](../eventing/configuration/broker-configuration.md) and [Channel based broker](../eventing/brokers/broker-types/channel-based-broker/README.md). To create a customized Broker class, you can do either or both of the following: -- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. These ConfigMaps are used when a `spec.config` is *not* the class. For example, use this method if you want to use a [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) for all other Brokers created on the cluster, but a particular Broker class for Brokers created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. - - Specify a ConfigMap to use in the `spec.config` keys in the Broker class you're defining. That ConfigMap must have a `channel-template-spec` that defines the channel implementation for the Broker. +- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. Knative refers to these ConfigMaps are used when a `spec.config` is *not* present. For example, use this method if you want to use a [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) for all Brokers created on the cluster, except for a particular Broker created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. + Set other default configurations for Brokers with these ConfigMaps: - `config-features` - Defines defaults for features including integration, sender identity, and transport encryption. See [Eventing integration with Istio service mesh](../eventing/features/istio-integration.md). - `default-ch-webhook` - Defines default channel implementation settings. See [Channel types and defaults](../eventing/channels/channel-types-defaults.md). -- `config-kafka-features` - Enable KEDA autoscaling. See [Configure KEDA Autoscaling of Knative Kafka Resources](../eventing/configuration/keda-configuration.md). -- `config-kafka-sink-data-plane` - Used for sending events to the Apache Kafka cluster. See [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) +- `config-kafka-features` - Enables KEDA autoscaling. See [Configure KEDA Autoscaling of Knative Kafka Resources](../eventing/configuration/keda-configuration.md). +- `config-kafka-sink-data-plane` - Sends events to the Apache Kafka cluster. See [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) - `config-ping-defaults` - Defines event resources, such as the the maximum amount of data PingSource can add to cloud events. See [Configure event source defaults](../eventing/configuration/sources-configuration.md). -- `sugar-controller` - The default controller that manages eventing resources in a cluster or namespace. Disable Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. See [Configure Sugar Controller](../eventing/configuration/sugar-configuration.md) +- `sugar-controller` - Defines the default controller that manages eventing resources in a cluster or namespace. Disable the Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. See [Configure Sugar Controller](../eventing/configuration/sugar-configuration.md) ### Observability and logging From 3df551f732f8b9966e7e2dff241caeeb44df181a Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Oct 2025 10:31:49 -0700 Subject: [PATCH 08/31] Update editing-configmaps.md Refocused content on just working with ConfigMaps. Removed generalized info not Knative specific. --- docs/versioned/admin/editing-configmaps.md | 118 ++++----------------- 1 file changed, 19 insertions(+), 99 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 5d5ef9efbb..3f4c5b7ee3 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -5,54 +5,10 @@ components: - eventing function: explanation --- -# 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. +# Working with ConfigMaps -## Configurations overview - -### Knative Operator and YAML installations - -To be written. - -### Brokers - -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. - -For details, see [Broker Configuration Options](../eventing/brokers/broker-developer-config-options.md), [Configure broker defaults](../eventing/configuration/broker-configuration.md) and [Channel based broker](../eventing/brokers/broker-types/channel-based-broker/README.md). - -To create a customized Broker class, you can do either or both of the following: - -- Specify a ConfigMap to use in the `spec.config` keys in the Broker class you're defining. That ConfigMap must have a `channel-template-spec` that defines the channel implementation for the Broker. - -- For a scope on a cluster wide or on a per namespace basis, use the `config-br-defaults` ConfigMap or the `kafka-channel` ConfigMap to define default values for the Broker. Knative refers to these ConfigMaps are used when a `spec.config` is *not* present. For example, use this method if you want to use a [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) for all Brokers created on the cluster, except for a particular Broker created in `namespace-1`. In the `config-br-defaults` ConfigMap, set the default Broker configuration for one or more dedicated namespaces by including them in the `namespaceDefaults` section. - -Set other default configurations for Brokers with these ConfigMaps: - -- `config-features` - Defines defaults for features including integration, sender identity, and transport encryption. See [Eventing integration with Istio service mesh](../eventing/features/istio-integration.md). -- `default-ch-webhook` - Defines default channel implementation settings. See [Channel types and defaults](../eventing/channels/channel-types-defaults.md). -- `config-kafka-features` - Enables KEDA autoscaling. See [Configure KEDA Autoscaling of Knative Kafka Resources](../eventing/configuration/keda-configuration.md). -- `config-kafka-sink-data-plane` - Sends events to the Apache Kafka cluster. See [Kafka Broker](../eventing/brokers/broker-types/kafka-broker/README.md) -- `config-ping-defaults` - Defines event resources, such as the the maximum amount of data PingSource can add to cloud events. See [Configure event source defaults](../eventing/configuration/sources-configuration.md). -- `sugar-controller` - Defines the default controller that manages eventing resources in a cluster or namespace. Disable the Sugar Controller by setting `namespace-selector` and `trigger-selector` to an empty string. See [Configure Sugar Controller](../eventing/configuration/sugar-configuration.md) - -### Observability and logging - -To be written. - -### Deployments and resources - -To be written. - -### Networking and domains - -To be written. - -### Security - -To be written. +This page provides important information and best practices for working with Kubernetes ConfigMaps. ## The _example key @@ -81,13 +37,20 @@ When a field in a ConfigMap is changed, the effect of the change depends on how - Special Cases - Some applications or operators (e.g., those using tools like `reloader`) can watch for ConfigMap changes and automatically trigger Pod restarts or reloads. - If the ConfigMap is used by a controller (e.g., a Deployment), changes might not affect running Pods unless the controller reconciles the change, which depends on its implementation. -## Version control +## Best practices -To maintain version control of Kubernetes ConfigMap settings and the version of the object they represent, you can follow these practices. +This section provides recommended procedures for storage, monitoring, and version control of ConfigMaps. -### Store ConfigMaps as code +### Validate and Test Changes -Define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: +- 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. + +### Storage and versioning + +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. + +You can also define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: ```yml apiVersion: v1 @@ -103,40 +66,18 @@ Define ConfigMaps in YAML or JSON files and store them in a version control syst db.port=5432 ``` -- Commit these files to a Git repository to track changes over time. +### Git recommendations -### Versioning ConfigMaps in Git +In addition to diligent usage of commit messages, here are some suggestions for ConfigMaps in GitHub: -- Use meaningful commit messages to describe changes to ConfigMap data (e.g., "Updated app.properties to version 1.2.4"). +- Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository (e.g., `k8s/configmaps/`). - Tag commits in Git with version numbers (e.g., `git tag config-v1.2.3`) to mark specific ConfigMap versions. -- Use branches for different environments (e.g., `dev`, `staging`, `prod`) or feature-specific ConfigMap changes. - -### 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" - ``` - -### Use GitOps for Deployment - - Implement a GitOps workflow with tools like ArgoCD or Flux to synchronize ConfigMaps from Git to your Kubernetes cluster. - These tools detect changes in the Git repository and automatically apply them to the cluster, ensuring the deployed ConfigMap matches the versioned configuration in Git. -### Immutable ConfigMaps with Versioned Names +### 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. - Create immutable ConfigMaps by appending a version or hash to the ConfigMap name (e.g., `my-app-config-v1.2.3` or `my-app-config-abc123`). - Update the application’s Deployment or Pod to reference the new ConfigMap version when rolling out changes. @@ -153,24 +94,3 @@ Define ConfigMaps in YAML or JSON files and store them in a version control syst - configMapRef: name: my-app-config-v1.2.3 ``` - -- This approach ensures ConfigMaps are not modified in-place, preserving historical versions. - -### Track Changes in Kubernetes - -Enable audit logging in Kubernetes to track who modified ConfigMaps and when. - -### 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. - -### Best Practices - -- Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository (e.g., `k8s/configmaps/`). -- Use Descriptive Naming: Name ConfigMaps cn - -- learly (e.g., `app-name-environment-config`) to avoid confusion. -- Document Changes: Include a `CHANGELOG.md` in your repository to document ConfigMap updates alongside application changes. -- Backup ConfigMaps: Periodically export ConfigMaps from the cluster (`kubectl get configmap -o yaml`) and commit them to Git for recovery purposes. - From 420803abb2c04a579413238ddf366b4a4537975c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Oct 2025 20:44:23 -0700 Subject: [PATCH 09/31] Update editing-configmaps.md Reviewer edits --- docs/versioned/admin/editing-configmaps.md | 23 ++-------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 3f4c5b7ee3..900edcb001 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,7 +8,7 @@ function: explanation # Working with ConfigMaps -This page provides important information and best practices for working with Kubernetes ConfigMaps. +This page provides important information and best practices for working with Kubernetes ConfigMaps. ## The _example key @@ -43,7 +43,7 @@ This section provides recommended procedures for storage, monitoring, and versio ### Validate and Test Changes -- Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or `kubectl apply --dry-run=client`. +- Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or `kubectl apply --dry-run=server`. - Test ConfigMap changes in a staging environment to ensure compatibility with the application version. ### Storage and versioning @@ -75,22 +75,3 @@ In addition to diligent usage of commit messages, here are some suggestions for - Implement a GitOps workflow with tools like ArgoCD or Flux to synchronize ConfigMaps from Git to your Kubernetes cluster. - These tools detect changes in the Git repository and automatically apply them to the cluster, ensuring the deployed ConfigMap matches the versioned configuration in Git. -### 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. - -- Create immutable ConfigMaps by appending a version or hash to the ConfigMap name (e.g., `my-app-config-v1.2.3` or `my-app-config-abc123`). -- Update the application’s Deployment or Pod to reference the new ConfigMap version when rolling out changes. - - ```yaml - apiVersion: apps/v1 - kind: Deployment - spec: - template: - spec: - containers: - - name: my-app - envFrom: - - configMapRef: - name: my-app-config-v1.2.3 - ``` From ee3de62efc5607bb948489fb133bb4098e1a36e5 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 3 Nov 2025 23:32:18 -0800 Subject: [PATCH 10/31] Update editing-configmaps.md Updated _example key content and reviewer edits --- docs/versioned/admin/editing-configmaps.md | 67 +++++++++++++++------- 1 file changed, 47 insertions(+), 20 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 900edcb001..d834a4006e 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -6,7 +6,7 @@ components: function: explanation --- -# Working with ConfigMaps +# Using ConfigMaps This page provides important information and best practices for working with Kubernetes ConfigMaps. @@ -14,33 +14,62 @@ This page provides important information and best practices for working with Kub ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. This key does not affect Knative behavior, but contains a value which acts as a documentation 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. +If a user edits the `_example` key by mistakenly thinking their edits will have an affect, the Knative webhook server catches the error with the following alert text (using the `config-defaults` ConfigMap as a example): -Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation: +```bash +error: configmaps "config-defaults" could not be patched: admission webhook "config.webhook.serving.knative.dev" denied the request: validation failed: the update modifies a key in "_example" which is probably not what you want. Instead, copy the respective setting to the top-level of the ConfigMap, directly below "data" +You can run `kubectl replace -f /var/folders/9t/yzwp6zrx765clbvl1c_dqc2r0000gn/T/kubectl-edit-2068368769.yaml` to try this update again. +``` + +More specifically, 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 or missing, the webhook server 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 annotation. The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` ```yml -... -annotations: - knative.dev/example-checksum: "47c2487f" +apiVersion: 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. + # + . . . + # In environments with large number of services it is suggested + # to set this value to `false`. + # See https://github.com/knative/serving/issues/8498. + enable-service-links: "false" ``` -To accurately create a ConfigMap using an existing file, use the Kubernetes[Define the key to use when creating a configmap from a file](https://kubernetes.io/dos/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) - -## Monitoring values +## Values propagation to Pods When a field in a ConfigMap is changed, the effect of the change depends on how the ConfigMap is used by the application or resource uses it. Here's a breakdown: -- Immediate Update in Kubernetes API - When you modify a ConfigMap (e.g., using `kubectl edit`, `kubectl apply`, or an API call), the change is immediately reflected in the Kubernetes API and stored in etcd clusters - a consistent and highly-available key value store used as Kubernetes' backing store for all cluster data. The updated ConfigMap is available for querying instantly. +- Immediate update in Kubernetes API - When you modify a ConfigMap (e.g., using `kubectl edit`, `kubectl apply`, or an API call), the change is immediately reflected in the Kubernetes API and stored in etcd clusters. The updated ConfigMap is available for querying instantly. - Mounted as Volumes - If the ConfigMap is mounted as a volume in a Pod, Kubernetes automatically propagates changes to the ConfigMap to the Pod's filesystem. This process typically takes a few seconds to up to 60 seconds because of the kubelet sync interval. Applications should detect or reload these changes (e.g., by watching the file or restarting). -- Environment Variables - If the ConfigMap is used to set environment variables in a Pod, changes to the ConfigMap do not automatically propagate to the Pod. Pods must be restarted (e.g., by deleting and recreating them) for the updated ConfigMap values to take effect, as environment variables are set at container startup. -- Direct API Access - If an application directly queries the ConfigMap via the Kubernetes API, it will see the updated values immediately after the change is applied. -- Special Cases - Some applications or operators (e.g., those using tools like `reloader`) can watch for ConfigMap changes and automatically trigger Pod restarts or reloads. -- If the ConfigMap is used by a controller (e.g., a Deployment), changes might not affect running Pods unless the controller reconciles the change, which depends on its implementation. +- Environment Variables - If the ConfigMap is used to set environment variables in a Pod, changes to the ConfigMap do not automatically propagate to the Pod. Because container values are set at container startup, pods must be deleted and recreated for the updated ConfigMap values to take effect. +- Direct API Access - If an application directly queries the ConfigMap through the Kubernetes API, it will get the updated values immediately after the change is applied. +- Special Cases - Some applications or operators, such as the `reloader` tool, can watch for ConfigMap changes and automatically trigger Pod restarts or reloads. +- If the ConfigMap is used by a controller, changes might not affect running Pods unless the change is recognized by the controller as defined by the implementation. ## Best practices -This section provides recommended procedures for storage, monitoring, and version control of ConfigMaps. - ### Validate and Test Changes - Before applying ConfigMaps, validate their syntax and content using tools like `kubeval` or `kubectl apply --dry-run=server`. @@ -48,9 +77,9 @@ This section provides recommended procedures for storage, monitoring, and versio ### Storage and versioning -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. +- 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. -You can also define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: +- You can also define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: ```yml apiVersion: v1 @@ -73,5 +102,3 @@ In addition to diligent usage of commit messages, here are some suggestions for - Centralize ConfigMaps: Store all ConfigMaps in a dedicated directory in your Git repository (e.g., `k8s/configmaps/`). - Tag commits in Git with version numbers (e.g., `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. -- These tools detect changes in the Git repository and automatically apply them to the cluster, ensuring the deployed ConfigMap matches the versioned configuration in Git. - From 6ed18462eccaeda5a6c4c16a9435538129ce26b0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 3 Nov 2025 23:49:04 -0800 Subject: [PATCH 11/31] Update editing-configmaps.md Misc edits --- docs/versioned/admin/editing-configmaps.md | 24 +++++++--------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index d834a4006e..5d6aa63e80 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,7 +8,7 @@ function: explanation # Using ConfigMaps -This page provides important information and best practices for working with Kubernetes ConfigMaps. +This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps and YAML resource files are the primary means for storing configuration values in Knative. ## The _example key @@ -23,7 +23,11 @@ You can run `kubectl replace -f /var/folders/9t/yzwp6zrx765clbvl1c_dqc2r0000gn/T More specifically, 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 or missing, the webhook server 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 annotation. The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` +Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation. + +### Example + +The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` ```yml apiVersion: v1 @@ -79,21 +83,7 @@ When a field in a ConfigMap is changed, the effect of the change depends on how - 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. -- You can also define ConfigMaps in YAML or JSON files and store them in a version control system (VCS) like Git. For example: - - ```yml - apiVersion: v1 - kind: ConfigMap - metadata: - name: my-app-config - namespace: default - data: - _example | ... - app.properties: | - version=1.2.3 - db.host=localhost - db.port=5432 - ``` +- You can also define ConfigMaps in YAML or JSON files and store them in a repository like GitHub. ### Git recommendations From 79b55027fb8404f9eea0773eeb59b86f78f711e7 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 3 Nov 2025 23:56:56 -0800 Subject: [PATCH 12/31] Update editing-configmaps.md Removed Value Propagation - not needed --- docs/versioned/admin/editing-configmaps.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 5d6aa63e80..cf2d46bef4 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -61,17 +61,6 @@ data: enable-service-links: "false" ``` -## Values propagation to Pods - -When a field in a ConfigMap is changed, the effect of the change depends on how the ConfigMap is used by the application or resource uses it. Here's a breakdown: - -- Immediate update in Kubernetes API - When you modify a ConfigMap (e.g., using `kubectl edit`, `kubectl apply`, or an API call), the change is immediately reflected in the Kubernetes API and stored in etcd clusters. The updated ConfigMap is available for querying instantly. -- Mounted as Volumes - If the ConfigMap is mounted as a volume in a Pod, Kubernetes automatically propagates changes to the ConfigMap to the Pod's filesystem. This process typically takes a few seconds to up to 60 seconds because of the kubelet sync interval. Applications should detect or reload these changes (e.g., by watching the file or restarting). -- Environment Variables - If the ConfigMap is used to set environment variables in a Pod, changes to the ConfigMap do not automatically propagate to the Pod. Because container values are set at container startup, pods must be deleted and recreated for the updated ConfigMap values to take effect. -- Direct API Access - If an application directly queries the ConfigMap through the Kubernetes API, it will get the updated values immediately after the change is applied. -- Special Cases - Some applications or operators, such as the `reloader` tool, can watch for ConfigMap changes and automatically trigger Pod restarts or reloads. -- If the ConfigMap is used by a controller, changes might not affect running Pods unless the change is recognized by the controller as defined by the implementation. - ## Best practices ### Validate and Test Changes From 5257455056f694feed2c5aaed198fd3b5a91674c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 7 Nov 2025 20:42:26 -0800 Subject: [PATCH 13/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index cf2d46bef4..f8632dbb62 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,7 +8,7 @@ function: explanation # Using ConfigMaps -This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps and YAML resource files are the primary means for storing configuration values in Knative. +This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps and YAML resource files are the primary means for managing configuration values for Knative controllers. ## The _example key From 9d97ee8388142688ddec004ad6d162cdd0944d5c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 7 Nov 2025 20:43:08 -0800 Subject: [PATCH 14/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index f8632dbb62..dc235fb70f 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -14,7 +14,7 @@ This page provides important information and best practices for working with Kub ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. 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 will have an affect, the Knative webhook server catches the error with the following alert text (using the `config-defaults` ConfigMap as a example): +If a user edits the `_example` key by mistakenly thinking their edits will have an affect, the Knative webhook catches the error with the following alert text (using the `config-defaults` ConfigMap as a example): ```bash error: configmaps "config-defaults" could not be patched: admission webhook "config.webhook.serving.knative.dev" denied the request: validation failed: the update modifies a key in "_example" which is probably not what you want. Instead, copy the respective setting to the top-level of the ConfigMap, directly below "data" From 9f6549881c358279afea72c805b827096c405bdf Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 7 Nov 2025 20:47:49 -0800 Subject: [PATCH 15/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index dc235fb70f..4adbcce110 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -16,10 +16,11 @@ ConfigMap files installed by Knative contain an `_example` key that shows the us If a user edits the `_example` key by mistakenly thinking their edits will have an affect, the Knative webhook catches the error with the following alert text (using the `config-defaults` ConfigMap as a example): -```bash + + error: configmaps "config-defaults" could not be patched: admission webhook "config.webhook.serving.knative.dev" denied the request: validation failed: the update modifies a key in "_example" which is probably not what you want. Instead, copy the respective setting to the top-level of the ConfigMap, directly below "data" You can run `kubectl replace -f /var/folders/9t/yzwp6zrx765clbvl1c_dqc2r0000gn/T/kubectl-edit-2068368769.yaml` to try this update again. -``` + More specifically, 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 or missing, the webhook server does not create the warning. From ef280e8aa75594df6b16f517abb49d6abc370fbb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 11 Nov 2025 21:26:24 -0800 Subject: [PATCH 16/31] Update editing-configmaps.md Line annotation test --- docs/versioned/admin/editing-configmaps.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 4adbcce110..c086a6c412 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -58,10 +58,13 @@ data: . . . # In environments with large number of services it is suggested # to set this value to `false`. - # See https://github.com/knative/serving/issues/8498. + # See https://github.com/knative/serving/issues/8498. # (1) enable-service-links: "false" ``` +1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted + text__, images, ... basically anything that can be written in Markdown. + ## Best practices ### Validate and Test Changes From c4ae66c25efa3dc8b79b7e17c35fe55ead047d08 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 11 Nov 2025 21:48:00 -0800 Subject: [PATCH 17/31] Update editing-configmaps.md Highlighting code lines test --- docs/versioned/admin/editing-configmaps.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index c086a6c412..5320253d8a 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -30,7 +30,7 @@ Accordingly, you cannot alter the contents of the `_example` key, but you can de The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` -```yml +```yml hl_lines="26 28" apiVersion: v1 kind: ConfigMap metadata: @@ -58,13 +58,10 @@ data: . . . # In environments with large number of services it is suggested # to set this value to `false`. - # See https://github.com/knative/serving/issues/8498. # (1) + # See https://github.com/knative/serving/issues/8498. enable-service-links: "false" ``` -1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted - text__, images, ... basically anything that can be written in Markdown. - ## Best practices ### Validate and Test Changes From 8af3db77ce683743fa07c10ffa7fd1560e25cd47 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 11 Nov 2025 22:01:35 -0800 Subject: [PATCH 18/31] Nav update and annotation testing Testing code blocks annotations --- docs/versioned/.nav.yml | 2 +- docs/versioned/admin/editing-configmaps.md | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 998c709863..d84ab43b3a 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -265,7 +265,7 @@ nav: # Vendor list - Using a Knative-based offering: install/knative-offerings.md - Configuring Knative: - - Editing ConfigMaps: admin/editing-configmaps.md + - 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: diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 5320253d8a..bf8710bfd6 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -6,7 +6,7 @@ components: function: explanation --- -# Using ConfigMaps +# Working with ConfigMaps This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps and YAML resource files are the primary means for managing configuration values for Knative controllers. @@ -30,7 +30,7 @@ Accordingly, you cannot alter the contents of the `_example` key, but you can de The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` -```yml hl_lines="26 28" +```yml hl_lines="11" apiVersion: v1 kind: ConfigMap metadata: @@ -44,12 +44,12 @@ metadata: knative.dev/example-checksum: "5b64ff5c" data: _example: | - ################################ - # # - # EXAMPLE CONFIGURATION # - # # - ################################ - + #######!#### + # + # EXAMPLE! + # + #########!#### +# (1)! # This block is not actually functional configuration, # but serves to illustrate the available configuration # options and document them in a way that is accessible @@ -62,6 +62,8 @@ data: enable-service-links: "false" ``` +(1) Testing + ## Best practices ### Validate and Test Changes From 0bec94e72c47148a839c4e4396917f808bdcfe5b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 11 Nov 2025 22:43:33 -0800 Subject: [PATCH 19/31] Update editing-configmaps.md Line numbers test --- docs/versioned/admin/editing-configmaps.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index bf8710bfd6..ea18a8ebe4 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -30,8 +30,8 @@ Accordingly, you cannot alter the contents of the `_example` key, but you can de The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` -```yml hl_lines="11" -apiVersion: v1 +```yml linenums="1" hl_lines="11" +piVersion: v1 kind: ConfigMap metadata: name: config-defaults @@ -44,12 +44,12 @@ metadata: knative.dev/example-checksum: "5b64ff5c" data: _example: | - #######!#### - # - # EXAMPLE! - # - #########!#### -# (1)! + ################################ + # # + # 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 From ff4dac3c66f966efd1cd607c9e08f632992fca4c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 12:25:56 -0800 Subject: [PATCH 20/31] Update editing-configmaps.md Fixes and reviewer edits --- docs/versioned/admin/editing-configmaps.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index ea18a8ebe4..a66df0ace9 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -28,7 +28,7 @@ Accordingly, you cannot alter the contents of the `_example` key, but you can de ### Example -The following example shows the abbreviated content of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` +The following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` ```yml linenums="1" hl_lines="11" piVersion: v1 @@ -55,15 +55,8 @@ data: # options and document them in a way that is accessible # to users that `kubectl edit` this config map. # - . . . - # In environments with large number of services it is suggested - # to set this value to `false`. - # See https://github.com/knative/serving/issues/8498. - enable-service-links: "false" ``` -(1) Testing - ## Best practices ### Validate and Test Changes @@ -73,8 +66,8 @@ data: ### Storage and versioning -- 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 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), remember to include applicable version numbers in `app.properties` as needed. - You can also define ConfigMaps in YAML or JSON files and store them in a repository like GitHub. ### Git recommendations From 410abd84c69e4936388601491a5a5466610531ef Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 13:23:34 -0800 Subject: [PATCH 21/31] Update editing-configmaps.md removed unneeded error example --- docs/versioned/admin/editing-configmaps.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index a66df0ace9..0ff28cc5eb 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -14,19 +14,11 @@ This page provides important information and best practices for working with Kub ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. 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 will have an affect, the Knative webhook catches the error with the following alert text (using the `config-defaults` ConfigMap as a example): - - - -error: configmaps "config-defaults" could not be patched: admission webhook "config.webhook.serving.knative.dev" denied the request: validation failed: the update modifies a key in "_example" which is probably not what you want. Instead, copy the respective setting to the top-level of the ConfigMap, directly below "data" -You can run `kubectl replace -f /var/folders/9t/yzwp6zrx765clbvl1c_dqc2r0000gn/T/kubectl-edit-2068368769.yaml` to try this update again. - +If a user edits the `_example` key by mistakenly thinking their edits will have an affect, 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 pod's template annotations. If the checksum is null or missing, the webhook server 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 annotation. - -### Example +Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation. The following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` From 630180005d370d89256de33dec970372fa9bc17d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 21:04:08 -0800 Subject: [PATCH 22/31] Update editing-configmaps.md One last annotation test --- docs/versioned/admin/editing-configmaps.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 0ff28cc5eb..30c8e29528 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -20,7 +20,7 @@ More specifically, the edit is caught when the value of the checksum for the `_e Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation. -The following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with most of the file removed except for the last four lines. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` +The following YAML code shows the first 24 lines of the `config-defaults` ConfigMap. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` ```yml linenums="1" hl_lines="11" piVersion: v1 @@ -35,7 +35,7 @@ metadata: annotations: knative.dev/example-checksum: "5b64ff5c" data: - _example: | + _example: | # (1) ################################ # # # EXAMPLE CONFIGURATION # @@ -49,6 +49,8 @@ data: # ``` +1. :man_raising_hand: Do not change. + ## Best practices ### Validate and Test Changes From 8d4cf07d089600e3ad28fa1f595d6112b07d2340 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 21:58:34 -0800 Subject: [PATCH 23/31] Update editing-configmaps.md Made reviewer edits --- docs/versioned/admin/editing-configmaps.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 30c8e29528..4a30b03af9 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,19 +8,17 @@ function: explanation # Working with ConfigMaps -This page provides important information and best practices for working with Kubernetes ConfigMaps. ConfigMaps and YAML resource files are the primary means for managing configuration values for Knative controllers. +This page provides important information and best practices for working with Kubernetes ConfigMaps. If you are using the operator to install and manage your Knative cluster, see [Configuring Knative by using the Operator](../install/operator/configuring-with-operator.md) for information on how to manage ConfigMaps using the operator. ConfigMaps are the primary means for managing configuration values for Knative controllers. ## The _example key -ConfigMap files installed by Knative contain an `_example` key that shows the usage and purpose of a configuration key. This key does not affect Knative behavior, but contains a value which acts as a documentation comment. +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 will have an affect, 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 pod's template annotations. If the checksum is null or missing, the webhook server does not create the warning. +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. Accordingly, you cannot alter the contents of the `_example` key, but you can delete the `_example` key altogether or delete the annotation. -The following YAML code shows the first 24 lines of the `config-defaults` ConfigMap. The checksum is in the annotations as `Knative.dev/example-checksum: "5b64ff5c"` +For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checkum highlighted. ```yml linenums="1" hl_lines="11" piVersion: v1 @@ -35,7 +33,7 @@ metadata: annotations: knative.dev/example-checksum: "5b64ff5c" data: - _example: | # (1) + _example: | ################################ # # # EXAMPLE CONFIGURATION # @@ -49,12 +47,12 @@ data: # ``` -1. :man_raising_hand: Do not change. - ## 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 `kubectl apply --dry-run=server`. - Test ConfigMap changes in a staging environment to ensure compatibility with the application version. From 20432ae905cf6f2830b5c638a86ec01d1746ae0f Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 22:57:22 -0800 Subject: [PATCH 24/31] Update editing-configmaps.md Worked on the canonical edit - git v cluster --- docs/versioned/admin/editing-configmaps.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 4a30b03af9..e3b2b42177 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -58,9 +58,11 @@ Knative controllers process new values, including roll-backs to previous values, ### Storage and versioning -- 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), remember to include applicable version numbers in `app.properties` as needed. -- You can also define ConfigMaps in YAML or JSON files and store them in a repository like GitHub. +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 (`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. ### Git recommendations From 604589e13dac47bd1770a731c713f684f0853198 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 12 Nov 2025 23:34:34 -0800 Subject: [PATCH 25/31] Update editing-configmaps.md Reviewer edits --- docs/versioned/admin/editing-configmaps.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index e3b2b42177..eff976bcf8 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,7 +8,9 @@ function: explanation # Working with ConfigMaps -This page provides important information and best practices for working with Kubernetes ConfigMaps. If you are using the operator to install and manage your Knative cluster, see [Configuring Knative by using the Operator](../install/operator/configuring-with-operator.md) for information on how to manage ConfigMaps using the operator. ConfigMaps are the primary means for managing configuration values for Knative controllers. +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. + +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 From b11781213faeeea89e3c829599751294a690701a Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 10:23:21 -0800 Subject: [PATCH 26/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index eff976bcf8..240032f4f9 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -8,7 +8,7 @@ function: explanation # 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. +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. From e8cc8526f4a61890265db0e43010d343e5363d41 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 10:24:02 -0800 Subject: [PATCH 27/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 240032f4f9..a6dae584ab 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -16,7 +16,7 @@ If you are using the Knative Operator to install and manage your Knative cluster 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. +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 annotation. From a096d978385a39a37c4dca5e8a13b5ccd9d4f73f Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 10:27:34 -0800 Subject: [PATCH 28/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index a6dae584ab..bb66880c2b 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -20,7 +20,7 @@ If a user edits the `_example` key rather than creating a new key in the ConfigM 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. +For example, the following YAML code shows the first 24 lines of the `config-defaults` ConfigMap with the checksum highlighted. ```yml linenums="1" hl_lines="11" piVersion: v1 From de63c7d6c8f256cf454315e8e61ed56dcb828784 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 10:28:25 -0800 Subject: [PATCH 29/31] Update docs/versioned/admin/editing-configmaps.md Co-authored-by: Evan Anderson --- docs/versioned/admin/editing-configmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index bb66880c2b..9eca424b57 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -64,7 +64,7 @@ How you manage storage relates the canonical locations of both the cluster and G 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. +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 From 6f1a4c479d4643feac70892cd32103a6c6d47078 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 10:55:51 -0800 Subject: [PATCH 30/31] Update editing-configmaps.md Copy edits --- docs/versioned/admin/editing-configmaps.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/versioned/admin/editing-configmaps.md b/docs/versioned/admin/editing-configmaps.md index 9eca424b57..644448ecf9 100644 --- a/docs/versioned/admin/editing-configmaps.md +++ b/docs/versioned/admin/editing-configmaps.md @@ -14,13 +14,13 @@ If you are using the Knative Operator to install and manage your Knative cluster ## 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 contains a value which acts as a documentation comment. +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 annotation. +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. +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 @@ -53,16 +53,16 @@ data: ### Validate and Test Changes -Knative controllers process new values, including roll-backs to previous values, within a few seconds after being applied. +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 `kubectl apply --dry-run=server`. +- 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 (`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 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. @@ -70,6 +70,6 @@ If you manage the ConfigMap by keeping the definition in Git and automatically a 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 (e.g., `k8s/configmaps/`). -- Tag commits in Git with version numbers (e.g., `git tag config-v1.2.3`) to mark specific ConfigMap versions. +- 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. From ae692274ad227530ab054ff6cdec37ba0e9331e5 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 11:04:48 -0800 Subject: [PATCH 31/31] Update admin-overview.md Added link to 'Working with ConfigMaps'. --- docs/versioned/admin/admin-overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/versioned/admin/admin-overview.md b/docs/versioned/admin/admin-overview.md index 16f9f94133..6045cf4838 100644 --- a/docs/versioned/admin/admin-overview.md +++ b/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.