docs(feature gates): updates content due to maturity

documentation/assemblies/deploying/assembly-deploy-intro-operators.adoc

@@ -32,4 +32,6 @@ These environment variables do not need to be set if you are deploying the opera
 //operator namespace 
 include::../../modules/operators/con-operators-namespaces.adoc[leveloffset=+1]
 //cluster operator's management of rbac resources
-include::../../modules/operators/ref-operator-cluster-rbac-resources.adoc[leveloffset=+1]
+include::../../modules/operators/ref-operator-cluster-rbac-resources.adoc[leveloffset=+1]
+//cluster operator's management of pod resources
+include::../../modules/configuring/con-pod-management.adoc[leveloffset=+1]

documentation/modules/configuring/con-pod-management.adoc

@@ -0,0 +1,16 @@
+// This assembly is included in the following assemblies:
+//
+// assembly-deploy-intro-operators.adoc
+
+[id='con-pod-management-{context}']
+= Managing pod resources
+
+[role="_abstract"]
+The `StrimziPodSet` custom resource is used by Strimzi to create and manage Kafka, Kafka Connect, and MirrorMaker 2 pods.
+If you are using ZooKeeper, ZooKeeper pods are also created and managed using `StrimziPodSet` resources.
+
+You must not create, update, or delete `StrimziPodSet` resources.
+The `StrimziPodSet` custom resource is used internally and resources are managed solely by the Cluster Operator.
+As a consequence, the Cluster Operator must be running properly to avoid the possibility of pods not starting and Kafka clusters not being available.
+
+NOTE: Kubernetes `Deployment` resources are used for creating and managing the pods of other components: Kafka Bridge, Kafka Exporter, Cruise Control, (deprecated) MirrorMaker 1, User Operator and Topic Operator.

documentation/modules/configuring/proc-changing-topic-replicas.adoc

@@ -55,7 +55,7 @@ Save a copy of this file locally in case you need to revert the changes later on
 
 . Edit the `reassignment.json` to remove a replica from each partition.
 +
-For example use `jq` to remove the last replica in the list for each partition of the topic:
+For example use the `jq` {JQTool} to remove the last replica in the list for each partition of the topic:
 +
 .Removing the last topic replica for each partition
 [source,shell,subs=+quotes]

documentation/modules/cruise-control/con-optimization-proposals.adoc

@@ -72,7 +72,7 @@ You can use the name of the `KafkaRebalance` resource to return a summary from t
 kubectl describe kafkarebalance _<kafka_rebalance_resource_name>_ -n _<namespace>_
 ----
 
-You can also use the `jq` command line JSON parser tool.
+You can also use the `jq` {JQTool}.
 
 .Returning an optimization proposal summary using jq
 [source,shell,subs=+quotes]
@@ -251,7 +251,7 @@ You can use the name of the ConfigMap to view its data from the command line.
 kubectl describe configmaps _<my_rebalance_configmap_name>_ -n _<namespace>_
 ----
 
-You can also use the `jq` command line JSON parser tool to extract the JSON string from the ConfigMap.
+You can also use the `jq` {JQTool} to extract the JSON string from the ConfigMap.
 
 .Extracting the JSON string from the ConfigMap using jq
 [source,shell,subs=+quotes]

documentation/modules/managing/con-custom-resources-status.adoc

@@ -22,7 +22,11 @@ m¦Strimzi resource
 
 m¦Kafka
 ¦`KafkaStatus` schema reference
-¦The Kafka cluster
+¦The Kafka cluster, its listeners, and node pools
+
+m¦KafkaNodePool
+¦`KafkaNodePoolStatus` schema reference
+¦The nodes in the node pool, their roles, and the associated Kafka cluster
 
 m¦KafkaTopic
 ¦`KafkaTopicStatus` schema reference
@@ -34,15 +38,15 @@ m¦KafkaUser
 
 m¦KafkaConnect
 ¦`KafkaConnectStatus` schema reference
-¦The Kafka Connect cluster
+¦The Kafka Connect cluster and connector plugins
 
 m¦KafkaConnector
 ¦`KafkaConnectorStatus` schema reference
 ¦`KafkaConnector` resources
 
 m¦KafkaMirrorMaker2
 ¦`KafkaMirrorMaker2Status` schema reference
-¦The Kafka MirrorMaker 2 cluster
+¦The Kafka MirrorMaker 2 cluster and internal connectors
 
 m¦KafkaMirrorMaker
 ¦`KafkaMirrorMakerStatus` schema reference
@@ -56,6 +60,10 @@ m¦KafkaRebalance
 ¦`KafkaRebalance` schema reference
 ¦The status and results of a rebalance
 
+m¦StrimziPodSet
+¦`StrimziPodSetStatus` schema reference
+¦The number of pods: being managed, using the current version, and in a ready state 
+
 |===
 
 The `status` property of a resource provides information on the state of the resource.
@@ -141,6 +149,3 @@ status:
 <7> The version of the operator that successfully completed the last reconciliation. 
 
 NOTE: The Kafka bootstrap addresses listed in the status do not signify that those endpoints or the Kafka cluster is in a `Ready` state.
-
-.Accessing status information
-You can access status information for a resource from the command line. For more information, see xref:proc-accessing-resource-status-{context}[].

documentation/modules/managing/proc-accessing-resource-status.adoc

@@ -18,10 +18,12 @@ This procedure describes how to find the status of a custom resource.
 +
 [source,shell,subs="+quotes,attributes"]
 ----
-kubectl get kafka _<kafka_resource_name>_ -o jsonpath='{.status}'
+kubectl get kafka <kafka_resource_name> -o jsonpath='{.status}' | jq
 ----
 +
 This expression returns all the status information for the specified custom resource. You can use dot notation, such as `status.listeners` or `status.observedGeneration`, to fine-tune the status information you wish to see.
++
+Using the `jq` {JQTool} makes it easier to read the output.
 
 [role="_additional-resources"]
 .Additional resources

documentation/modules/operators/con-removing-topic-finalizers.adoc

@@ -17,7 +17,7 @@ To remove finalizers on all topics, use the following command:
 kubectl get kt -o=json | jq '.items[].metadata.finalizers = null' | kubectl apply -f -
 ----
 
-The command uses the `jq` tool to modify the `KafkaTopic` (`kt`) resources by setting the finalizers to `null`.
+The command uses the `jq` {JQTool} to modify the `KafkaTopic` (`kt`) resources by setting the finalizers to `null`.
 You can also use the command for a specific topic:
 
 .Removing a finalizer on a specific topic

documentation/modules/operators/ref-operator-cluster-feature-gate-releases.adoc

@@ -22,7 +22,7 @@ Alpha and beta stage features are removed if they do not prove to be useful.
 * The `UseStrimziPodSets` feature gate moved to GA stage in Strimzi 0.35 and the support for StatefulSets is completely removed. It is now permanently enabled and cannot be disabled.
 * The `StableConnectIdentities` feature gate moved to GA stage in Strimzi 0.39.
   It is now permanently enabled and cannot be disabled.
-* The `UseKRaft` feature gate is available for development only and does not currently have a planned release for moving to the beta phase.
+* The `UseKRaft` feature gate is in beta stage and is enabled by default.
 * The `KafkaNodePools` feature gate is in beta stage and is enabled by default.
   It is expected to move to GA phase and be always enabled from Strimzi 0.41.
 * The `UnidirectionalTopicOperator` feature gate is in beta stage and is enabled by default.

documentation/modules/operators/ref-operator-cluster-feature-gates.adoc

@@ -3,68 +3,65 @@
 // deploying/deploying.adoc
 
 [id='ref-operator-cluster-feature-gates-{context}']
-= Enabling Strimzi feature gates
+= Feature gates
 
 [role="_abstract"]
-Strimzi operators use feature gates to enable or disable specific features and functions. 
-By enabling a feature gate, you alter the behavior of the corresponding operator, thereby introducing the feature to your Strimzi deployment.
+Strimzi operators use feature gates to enable or disable specific features and functions.
+Enabling a feature gate alters the behavior of the associated operator, introducing the corresponding feature to your Strimzi deployment.
 
-A feature gate might be enabled or disabled by default, depending on its level of maturity.
+The purpose of feature gates is to facilitate the trial and testing of a feature before it is fully adopted. 
+The state (enabled or disabled) of a feature gate may vary by default, depending on its maturity level.
 
-To modify a feature gate's default state, use the `STRIMZI_FEATURE_GATES` environment variable in the operator's configuration.
-You can modify multiple feature gates using this single environment variable.
-Specify a comma-separated list of feature gate names and prefixes.
-A `+` prefix enables the feature gate and a `-` prefix  disables it.
+As a feature gate graduates and reaches General Availability (GA), it transitions to an enabled state by default and becomes a permanent part of the Strimzi deployment.
+A feature gate at the GA stage cannot be disabled. 
 
-.Example feature gate configuration that enables `FeatureGate1` and disables `FeatureGate2`
-[source,yaml,options="nowrap"]
-----
-env:
-  - name: STRIMZI_FEATURE_GATES
-    value: +FeatureGate1,-FeatureGate2
-----
+== Graduated feature gates (GA)
+
+Graduated feature gates have reached General Availability (GA) and are permanently enabled features.
+
+=== ControlPlaneListener feature gate
 
-== ControlPlaneListener feature gate
+The `ControlPlaneListener` feature gate separates listeners for data replication and coordination:
 
-The `ControlPlaneListener` feature gate has moved to GA, which means it is now permanently enabled and cannot be disabled.
-With `ControlPlaneListener` enabled, the connections between the Kafka controller and brokers use an internal _control plane listener_ on port 9090.
-Replication of data between brokers, as well as internal connections from Strimzi operators, Cruise Control, or the Kafka Exporter use the _replication listener_ on port 9091.
+* Connections between the Kafka controller and brokers use an internal _control plane listener_ on port 9090.
+* Replication of data between brokers, as well as internal connections from Strimzi operators, Cruise Control, or the Kafka Exporter use a _replication listener_ on port 9091.
 
-IMPORTANT: With the `ControlPlaneListener` feature gate permanently enabled, it is no longer possible to upgrade or downgrade directly between Strimzi 0.22 and earlier and Strimzi 0.32 and newer.
-You have to first upgrade or downgrade through one of the Strimzi versions in-between, disable the `ControlPlaneListener` feature gate, and then downgrade or upgrade (with the feature gate enabled) to the target version.
+IMPORTANT: With the `ControlPlaneListener` feature gate permanently enabled, direct upgrades or downgrades between Strimzi 0.22 and earlier and Strimzi 0.32 and newer are not possible.
+You must first upgrade or downgrade through one of the Strimzi versions in-between, disable the `ControlPlaneListener` feature gate, and then downgrade or upgrade (with the feature gate enabled) to the target version.
 
-== ServiceAccountPatching feature gate
+=== ServiceAccountPatching feature gate
 
-The `ServiceAccountPatching` feature gate has moved to GA, which means it is now permanently enabled and cannot be disabled.
-With `ServiceAccountPatching` enabled, the Cluster Operator always reconciles service accounts and updates them when needed.
+The `ServiceAccountPatching` feature gate ensures that the Cluster Operator always reconciles service accounts and updates them when needed.
 For example, when you change service account labels or annotations using the `template` property of a custom resource, the operator automatically updates them on the existing service account resources.
 
 [id='ref-operator-use-strimzi-pod-sets-feature-gate-{context}']
-== UseStrimziPodSets feature gate
+=== UseStrimziPodSets feature gate
 
-The `UseStrimziPodSets` feature gate has moved to GA, which means it is now permanently enabled and cannot be disabled.
-Support for `StatefulSets` has been removed and Strimzi is now always using `StrimziPodSets` to manage Kafka and ZooKeeper pods.
+The `UseStrimziPodSets` feature gate introduced the `StrimziPodSet` custom resource for managing Kafka and ZooKeeper pods, replacing the use of Kubernetes `StatefulSet` resources.
 
-IMPORTANT: With the `UseStrimziPodSets` feature gate permanently enabled, it is no longer possible to downgrade directly from Strimzi 0.35 and newer to Strimzi 0.27 or earlier.
-You have to first downgrade through one of the Strimzi versions in-between, disable the `UseStrimziPodSets` feature gate, and then downgrade to Strimzi 0.27 or earlier.
+IMPORTANT: With the `UseStrimziPodSets` feature gate permanently enabled, direct downgrades from Strimzi 0.35 and newer to Strimzi 0.27 or earlier are not possible. You must first downgrade through one of the Strimzi versions in-between, disable the `UseStrimziPodSets` feature gate, and then downgrade to Strimzi 0.27 or earlier.
 
 [id='ref-operator-stable-connect-identities-feature-gate-{context}']
-== StableConnectIdentities feature gate
+=== StableConnectIdentities feature gate
 
-The `StableConnectIdentities` feature gate has moved to GA, which means it is now permanently enabled and cannot be disabled.
-The `StrimziPodSet` resources are now always used to manage Kafka Connect and Kafka MirrorMaker 2 pods instead of using Kubernetes `Deployment` resources.
-`StrimziPodSet` resources give the pods stable names and stable addresses, which do not change during rolling upgrades.
-This helps to minimize the number of rebalances of connector tasks.
+The `StableConnectIdentities` feature gate introduced the `StrimziPodSet` custom resource for managing Kafka Connect and Kafka MirrorMaker 2 pods, replacing the use of Kubernetes `Deployment` resources.
 
-IMPORTANT: With the `StableConnectIdentities` feature gate permanently enabled, it is no longer possible to downgrade directly from Strimzi 0.39 and newer to Strimzi 0.33 or earlier.
-You have to first downgrade through one of the Strimzi versions in-between, disable the `StableConnectIdentities` feature gate, and then downgrade to Strimzi 0.33 or earlier.
+`StrimziPodSet` resources give the pods stable names and stable addresses, which do not change during rolling upgrades, replacing the use of Kubernetes `Deployment` resources.
+
+IMPORTANT: With the `StableConnectIdentities` feature gate permanently enabled, direct downgrades from Strimzi 0.39 and newer to Strimzi 0.33 or earlier are not possible.
+You must first downgrade through one of the Strimzi versions in-between, disable the `StableConnectIdentities` feature gate, and then downgrade to Strimzi 0.33 or earlier.
+
+== Stable feature gates (Beta)
+
+Stable feature gates have reached a beta level of maturity, and are generally enabled by default for all users.
+Stable feature gates are production-ready, but they can still be disabled.
 
 [id='ref-operator-use-kraft-feature-gate-{context}']
 == UseKRaft feature gate
 
 The `UseKRaft` feature gate has a default state of _enabled_.
 
-The `UseKRaft` feature gate deploys the Kafka cluster in the KRaft (Kafka Raft metadata) mode without ZooKeeper.
+The `UseKRaft` feature gate deploys a Kafka cluster in KRaft (Kafka Raft metadata) mode without ZooKeeper.
 ZooKeeper and KRaft are mechanisms used to manage metadata and coordinate operations in Kafka clusters. 
 KRaft mode eliminates the need for an external coordination service like ZooKeeper. 
 In KRaft mode, Kafka nodes take on the roles of brokers, controllers, or both. 
@@ -89,7 +86,7 @@ Currently, the KRaft mode in Strimzi has the following major limitations:
 To disable the `UseKRaft` feature gate, specify `-UseKRaft` in the `STRIMZI_FEATURE_GATES` environment variable in the Cluster Operator configuration.
 
 [id='ref-operator-kafka-node-pools-feature-gate-{context}']
-== KafkaNodePools feature gate
+=== KafkaNodePools feature gate
 
 The `KafkaNodePools` feature gate has a default state of _enabled_.
 
@@ -119,7 +116,7 @@ The `Kafka` custom resource using the node pools must also have the annotation `
 If your cluster already uses `KafkaNodePool` custom resources, and you wish to downgrade to an older version of Strimzi that does not support them or with the `KafkaNodePools` feature gate disabled, you must first migrate from `KafkaNodePool` custom resources to managing Kafka nodes using only `Kafka` custom resources.
 
 [id='ref-operator-unidirectional-topic-operator-feature-gate-{context}']
-== UnidirectionalTopicOperator feature gate
+=== UnidirectionalTopicOperator feature gate
 
 The `UnidirectionalTopicOperator` feature gate has a default state of _enabled_.
 
@@ -132,3 +129,25 @@ For more information on topic management, see xref:ref-operator-topic-str[].
 .Disabling the `UnidirectionalTopicOperator` feature gate
 
 To disable the `UnidirectionalTopicOperator` feature gate, specify `-UnidirectionalTopicOperator` in the `STRIMZI_FEATURE_GATES` environment variable in the Cluster Operator configuration.
+
+== Early access feature gates (Alpha)
+
+Early access feature gates have not yet reached the beta stage, and are disabled by default. 
+An early access feature gate provides an opportunity for assessment before its functionality is permanently incorporated into Strimzi.
+
+Currently, there are no feature gates in alpha stage.
+
+== Enabling feature gates
+
+To modify a feature gate's default state, use the `STRIMZI_FEATURE_GATES` environment variable in the operator's configuration.
+You can modify multiple feature gates using this single environment variable.
+Specify a comma-separated list of feature gate names and prefixes.
+A `+` prefix enables the feature gate and a `-` prefix  disables it.
+
+.Example feature gate configuration that enables `FeatureGate1` and disables `FeatureGate2`
+[source,yaml,options="nowrap"]
+----
+env:
+  - name: STRIMZI_FEATURE_GATES
+    value: +FeatureGate1,-FeatureGate2
+----

documentation/shared/attributes.adoc

@@ -62,6 +62,7 @@
 // External links
 :aws-ebs: link:https://aws.amazon.com/ebs/[Amazon Elastic Block Store (EBS)^]
 :JavaServiceProvider: link:https://www.baeldung.com/java-spi[Java Service Provider Interface^]
+:JQTool: link:https://github.com/jqlang/jq[command line JSON parser tool^]
 :kubernetes-docs: link:https://kubernetes.io/docs/home/
 :kafkaDoc: link:https://kafka.apache.org/documentation/[Apache Kafka documentation^]
 :K8sAffinity: link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/[Kubernetes node and pod affinity documentation^]