From ed2dfa6d2247d32abd0696f1f506c215e9b789d8 Mon Sep 17 00:00:00 2001 From: prmellor Date: Fri, 13 Sep 2024 11:20:11 +0100 Subject: [PATCH] docs(review): minor doc updates and improvements from review Signed-off-by: prmellor --- ...a.listener.KafkaListenerAuthenticationCustom.adoc | 4 ++-- .../assemblies/deploying/assembly-deploy-tasks.adoc | 8 ++++---- .../metrics/assembly-metrics-config-files.adoc | 8 ++++++-- .../modules/con-common-configuration-properties.adoc | 3 +++ .../modules/configuring/con-config-examples.adoc | 4 ++-- .../modules/deploying/con-deploy-prereqs.adoc | 12 ++++++------ .../oauth/con-oauth-authentication-client.adoc | 8 ++++---- .../ref-operator-cluster-feature-gate-releases.adoc | 2 +- .../modules/upgrading/con-upgrade-paths.adoc | 2 +- documentation/shared/attributes.adoc | 6 ------ documentation/shared/ref-document-conventions.adoc | 6 ++---- 11 files changed, 31 insertions(+), 32 deletions(-) diff --git a/documentation/api/io.strimzi.api.kafka.model.kafka.listener.KafkaListenerAuthenticationCustom.adoc b/documentation/api/io.strimzi.api.kafka.model.kafka.listener.KafkaListenerAuthenticationCustom.adoc index f5783657ffd..f1986602bae 100644 --- a/documentation/api/io.strimzi.api.kafka.model.kafka.listener.KafkaListenerAuthenticationCustom.adoc +++ b/documentation/api/io.strimzi.api.kafka.model.kafka.listener.KafkaListenerAuthenticationCustom.adoc @@ -53,9 +53,9 @@ This is because an OAuth listener appends its own principle builder to the Kafka Custom principal builders must support peer certificates for authentication, as Strimzi uses these to manage the Kafka cluster. -ifdef::Downloading[] +ifdef::Section[] A custom OAuth principal builder might be identical or very similar to the Strimzi https://github.com/strimzi/strimzi-kafka-oauth/blob/main/oauth-server/src/main/java/io/strimzi/kafka/oauth/server/OAuthKafkaPrincipalBuilder.java[OAuth principal builder]. -endif::Downloading[] +endif::Section[] NOTE: link:https://github.com/apache/kafka/blob/trunk/clients/src/main/java/org/apache/kafka/common/security/authenticator/DefaultKafkaPrincipalBuilder.java#L73-L79[Kafka's default principal builder class] supports the building of principals based on the names of peer certificates. The custom principal builder should provide a principal of type `user` using the name of the SSL peer certificate. diff --git a/documentation/assemblies/deploying/assembly-deploy-tasks.adoc b/documentation/assemblies/deploying/assembly-deploy-tasks.adoc index cb5cc0d42e0..abb7ebd491a 100644 --- a/documentation/assemblies/deploying/assembly-deploy-tasks.adoc +++ b/documentation/assemblies/deploying/assembly-deploy-tasks.adoc @@ -9,14 +9,14 @@ Having xref:deploy-tasks-prereqs_{context}[prepared your environment for a deployment of Strimzi], you can deploy Strimzi to a Kubernetes cluster. Use the installation files provided with the release artifacts. -ifdef::Downloading[] +ifdef::Section[] You can deploy Strimzi {ProductVersion} on Kubernetes {KubernetesVersion}. -endif::Downloading[] +endif::Section[] -ifndef::Downloading[] +ifndef::Section[] Strimzi is based on {StrimziVersion}. You can deploy Strimzi {ProductVersion} on OpenShift {OpenShiftVersion}. -endif::Downloading[] +endif::Section[] The steps to deploy Strimzi using the installation files are as follows: diff --git a/documentation/assemblies/metrics/assembly-metrics-config-files.adoc b/documentation/assemblies/metrics/assembly-metrics-config-files.adoc index 3e5ee628ce5..d57e60a05c0 100644 --- a/documentation/assemblies/metrics/assembly-metrics-config-files.adoc +++ b/documentation/assemblies/metrics/assembly-metrics-config-files.adoc @@ -20,7 +20,9 @@ metrics │ ├── strimzi-kafka-connect.json │ ├── strimzi-kafka-exporter.json │ ├── strimzi-kafka-mirror-maker-2.json +| ├── strimzi-kafka-oauth.json │ ├── strimzi-kafka.json +| ├── strimzi-kraft.json │ ├── strimzi-operators.json │ └── strimzi-zookeeper.json ├── grafana-install @@ -38,7 +40,9 @@ metrics ├── kafka-connect-metrics.yaml <10> ├── kafka-cruise-control-metrics.yaml <11> ├── kafka-metrics.yaml <12> -└── kafka-mirror-maker-2-metrics.yaml <13> +├── kafka-mirror-maker-2-metrics.yaml <13> +└── oauth-metrics.yaml <14> + -- <1> Example Grafana dashboards for the different Strimzi components. <2> Installation file for the Grafana image. @@ -52,7 +56,7 @@ metrics <10> Metrics configuration that defines Prometheus JMX Exporter relabeling rules for Kafka Connect. <11> Metrics configuration that defines Prometheus JMX Exporter relabeling rules for Cruise Control. <12> Metrics configuration that defines Prometheus JMX Exporter relabeling rules for Kafka and ZooKeeper. -<13> Metrics configuration that defines Prometheus JMX Exporter relabeling rules for Kafka MirrorMaker 2. +<13> Metrics configuration that defines Prometheus JMX Exporter relabeling rules for OAuth 2.0. //Example Prometheus metrics files include::../../modules/metrics/ref-prometheus-metrics-config.adoc[leveloffset=+1] diff --git a/documentation/modules/con-common-configuration-properties.adoc b/documentation/modules/con-common-configuration-properties.adoc index dc7a5c0e2cb..fc7cf2f01db 100644 --- a/documentation/modules/con-common-configuration-properties.adoc +++ b/documentation/modules/con-common-configuration-properties.adoc @@ -725,3 +725,6 @@ spec: - name: example-pvc-volume mountPath: /mnt/data ---- + +You can use volumes to store files containing configuration values for a Kafka component and then load those values using a configuration provider. +For more information, see link:{BookURLDeploying}#assembly-loading-config-with-providers-str[Loading configuration values from external sources^]. diff --git a/documentation/modules/configuring/con-config-examples.adoc b/documentation/modules/configuring/con-config-examples.adoc index 09438ca8a7c..4a0318595ed 100644 --- a/documentation/modules/configuring/con-config-examples.adoc +++ b/documentation/modules/configuring/con-config-examples.adoc @@ -8,10 +8,10 @@ [role="_abstract"] Further enhance your deployment by incorporating additional supported configuration. Example configuration files are provided with the downloadable release artifacts from the {ReleaseDownload}. -ifdef::Downloading[] +ifdef::Section[] You can also access the example files directly from the link:https://github.com/strimzi/strimzi-kafka-operator/tree/{GithubVersion}/examples/[`examples` directory^]. -endif::Downloading[] +endif::Section[] The example files include only the essential properties and values for custom resources by default. You can download and apply the examples using the `kubectl` command-line tool. diff --git a/documentation/modules/deploying/con-deploy-prereqs.adoc b/documentation/modules/deploying/con-deploy-prereqs.adoc index 71e366ff346..9d36728b7e9 100644 --- a/documentation/modules/deploying/con-deploy-prereqs.adoc +++ b/documentation/modules/deploying/con-deploy-prereqs.adoc @@ -7,7 +7,7 @@ To deploy Strimzi, you will need the following: -ifdef::Downloading[] +ifdef::Section[] * A Kubernetes {KubernetesVersion} cluster. + * The `kubectl` command-line tool is installed and configured to connect to the running cluster. @@ -26,22 +26,22 @@ In almost all cases the example `kubectl` commands used in this guide can be don In other words, instead of using: [source,shell,subs=+quotes] -kubectl apply -f _your-file_ +kubectl apply -f when using OpenShift you can use: [source,shell,subs=+quotes] -oc apply -f _your-file_ +oc apply -f NOTE: As an exception to this general rule, `oc` uses `oc adm` subcommands for _cluster management_ functionality, whereas `kubectl` does not make this distinction. For example, the `oc` equivalent of `kubectl taint` is `oc adm taint`. -endif::Downloading[] -ifndef::Downloading[] +endif::Section[] +ifndef::Section[] * An OpenShift {OpenShiftVersion} cluster. + Strimzi is based on {StrimziVersion}. * The `oc` command-line tool is installed and configured to connect to the running cluster. -endif::Downloading[] +endif::Section[] diff --git a/documentation/modules/oauth/con-oauth-authentication-client.adoc b/documentation/modules/oauth/con-oauth-authentication-client.adoc index 0a1ce82eb65..56e79dafded 100644 --- a/documentation/modules/oauth/con-oauth-authentication-client.adoc +++ b/documentation/modules/oauth/con-oauth-authentication-client.adoc @@ -95,9 +95,9 @@ sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginMo oauth.token.endpoint.uri="" \ # <4> oauth.client.id="" \ # <5> oauth.client.secret="" \ # <6> - oauth.ssl.truststore.location="/tmp/oauth-truststore.p12" \ <7> - oauth.ssl.truststore.password="$STOREPASS" \ <8> - oauth.ssl.truststore.type="PKCS12" \ <9> + oauth.ssl.truststore.location="/tmp/oauth-truststore.p12" \ # <7> + oauth.ssl.truststore.password="$STOREPASS" \ # <8> + oauth.ssl.truststore.type="PKCS12" \ # <9> oauth.scope="" \ # <10> oauth.audience="" ; # <11> sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler @@ -138,7 +138,7 @@ sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginMo sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler ---- <1> Path to the client assertion file used for authenticating the client. This file is a private key file as an alternative to the client secret. -Alternatively, use `oauth.client.assertion` option to specify the client assertion value in clear text. +Alternatively, use the `oauth.client.assertion` option to specify the client assertion value in clear text. <2> (Optional) Sometimes you may need to specify the client assertion type. In not specified, the default value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. [id='con-oauth-authentication-password-grants-{context}'] diff --git a/documentation/modules/operators/ref-operator-cluster-feature-gate-releases.adoc b/documentation/modules/operators/ref-operator-cluster-feature-gate-releases.adoc index 5ee24437d73..9e61ffb6bbd 100644 --- a/documentation/modules/operators/ref-operator-cluster-feature-gate-releases.adoc +++ b/documentation/modules/operators/ref-operator-cluster-feature-gate-releases.adoc @@ -24,7 +24,7 @@ Alpha and beta stage features are removed if they do not prove to be useful. It is now permanently enabled and cannot be disabled. * The `KafkaNodePools` feature gate moved to GA stage in Strimzi 0.41. It is now permanently enabled and cannot be disabled. - To use the Kafka Node Pool resources, you still need to use the `strimzi.io/node-pools: enabled` annotation on the `Kafka` custom resources. + To use `KafkaNodePool` resources, you still need to use the `strimzi.io/node-pools: enabled` annotation on the `Kafka` custom resources. * The `UnidirectionalTopicOperator` feature gate moved to GA stage in Strimzi 0.41. It is now permanently enabled and cannot be disabled. * The `UseKRaft` feature gate moved to GA stage in Strimzi 0.42. diff --git a/documentation/modules/upgrading/con-upgrade-paths.adoc b/documentation/modules/upgrading/con-upgrade-paths.adoc index 8dae7fd0e31..c63c22363df 100644 --- a/documentation/modules/upgrading/con-upgrade-paths.adoc +++ b/documentation/modules/upgrading/con-upgrade-paths.adoc @@ -13,7 +13,7 @@ An incremental upgrade involves upgrading Strimzi from the previous minor versio Multi-version upgrade:: A multi-version upgrade involves upgrading an older version of Strimzi to version {ProductVersion} within a single upgrade, skipping one or more intermediate versions. -For example, upgrading directly from Strimzi 0.30.0 to Strimzi {ProductVersion} is possible. +Upgrading from any earlier Strimzi version to the latest version is possible. [id='con-upgrade-paths-kafka-versions-{context}'] == Support for Kafka versions when upgrading diff --git a/documentation/shared/attributes.adoc b/documentation/shared/attributes.adoc index 0b6d446ccba..576f23a61ba 100644 --- a/documentation/shared/attributes.adoc +++ b/documentation/shared/attributes.adoc @@ -169,14 +169,8 @@ :KafkaBridgeApiVersion: kafka.strimzi.io/v1beta2 // Section enablers -:InstallationAppendix: -:Metrics: -:Downloading: :Section: -//EXCLUSIVE TO STRIMZI -:sectlinks: - // Helm Chart - deploy cluster operator :ChartReleaseCoordinate: strimzi/strimzi-kafka-operator :ChartRepositoryUrl: https://strimzi.io/charts/ diff --git a/documentation/shared/ref-document-conventions.adoc b/documentation/shared/ref-document-conventions.adoc index a34c0a87629..68a70f0f75c 100644 --- a/documentation/shared/ref-document-conventions.adoc +++ b/documentation/shared/ref-document-conventions.adoc @@ -3,15 +3,13 @@ // assembly-overview.adoc [id='document-conventions-{context}'] -= Document Conventions - -.User-replaced values += Document conventions User-replaced values, also known as _replaceables_, are shown in with angle brackets (< >). Underscores ( _ ) are used for multi-word values. If the value refers to code or commands, `monospace` is also used. -For example, the following code shows that `__` must be replaced by the correct namespace name: +For example, the following code shows that `` must be replaced by the correct namespace name: [source, subs="+quotes"] ----