diff --git a/api/src/main/java/io/strimzi/api/kafka/model/kafka/KafkaClusterSpec.java b/api/src/main/java/io/strimzi/api/kafka/model/kafka/KafkaClusterSpec.java index c72e1159454..e13d25346f8 100644 --- a/api/src/main/java/io/strimzi/api/kafka/model/kafka/KafkaClusterSpec.java +++ b/api/src/main/java/io/strimzi/api/kafka/model/kafka/KafkaClusterSpec.java @@ -56,14 +56,14 @@ public class KafkaClusterSpec implements HasConfigurableMetrics, HasConfigurable public static final String FORBIDDEN_PREFIXES = "listeners, advertised., broker., listener., host.name, port, " + "inter.broker.listener.name, sasl., ssl., security., password., log.dir, " + "zookeeper.connect, zookeeper.set.acl, zookeeper.ssl, zookeeper.clientCnxnSocket, authorizer., super.user, " - + "cruise.control.metrics.topic, cruise.control.metrics.reporter.bootstrap.servers," + + "cruise.control.metrics.topic, cruise.control.metrics.reporter.bootstrap.servers, " + "node.id, process.roles, controller., metadata.log.dir"; // KRaft options - public static final String FORBIDDEN_PREFIX_EXCEPTIONS = "zookeeper.connection.timeout.ms, sasl.server.max.receive.size," - + "ssl.cipher.suites, ssl.protocol, ssl.enabled.protocols, ssl.secure.random.implementation," - + "cruise.control.metrics.topic.num.partitions, cruise.control.metrics.topic.replication.factor, cruise.control.metrics.topic.retention.ms," - + "cruise.control.metrics.topic.auto.create.retries, cruise.control.metrics.topic.auto.create.timeout.ms," - + "cruise.control.metrics.topic.min.insync.replicas," + public static final String FORBIDDEN_PREFIX_EXCEPTIONS = "zookeeper.connection.timeout.ms, sasl.server.max.receive.size, " + + "ssl.cipher.suites, ssl.protocol, ssl.enabled.protocols, ssl.secure.random.implementation, " + + "cruise.control.metrics.topic.num.partitions, cruise.control.metrics.topic.replication.factor, cruise.control.metrics.topic.retention.ms, " + + "cruise.control.metrics.topic.auto.create.retries, cruise.control.metrics.topic.auto.create.timeout.ms, " + + "cruise.control.metrics.topic.min.insync.replicas, " + "controller.quorum.election.backoff.max.ms, controller.quorum.election.timeout.ms, controller.quorum.fetch.timeout.ms"; // KRaft options protected Storage storage; diff --git a/crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java b/crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java index 1b57055a7ed..690f611dbe8 100644 --- a/crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java +++ b/crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java @@ -39,7 +39,6 @@ import static io.strimzi.crdgenerator.Property.subtypeMap; import static io.strimzi.crdgenerator.Property.subtypeNames; import static io.strimzi.crdgenerator.Property.subtypes; -import static java.lang.Integer.max; import static java.util.Collections.emptySet; import static java.util.Collections.singletonList; @@ -140,62 +139,54 @@ private void appendCommonTypeDoc(Crd crd, Class cls) throws IOException { appendUsedIn(crd, cls); appendDescription(cls); appendDiscriminator(crd, cls); - - out.append("[options=\"header\"]").append(NL); + + out.append("[cols=\"2,2,3\",options=\"header\"]").append(NL); out.append("|====").append(NL); - out.append("|Property"); - String gunk = "1.2+<.<"; - final Map properties = properties(crApiVersion, cls); - int maxLen = computePadding(gunk, properties); - appendRepeated(' ', maxLen - "Property".length() + 1); - out.append("|Description"); - out.append(NL); - + out.append("|Property |Property type |Description").append(NL); + LinkedHashSet> types = new LinkedHashSet<>(); - - for (Map.Entry entry: properties.entrySet()) { + + for (Map.Entry entry : properties(crApiVersion, cls).entrySet()) { String propertyName = entry.getKey(); final Property property = entry.getValue(); PropertyType propertyType = property.getType(); - out.append("|").append(propertyName); - appendRepeated(' ', maxLen - propertyName.length() - gunk.length()); - out.append(' '); - out.append(gunk); - out.append("a|"); - - // Set warning message for deprecated fields - addDeprecationWarning(property); - - // Set the field description - addDescription(cls, property); - + // Set the external link to Kubernetes docs or the link for fields distinguished by `type` KubeLink kubeLink = property.getAnnotation(KubeLink.class); String externalUrl = linker != null && kubeLink != null ? linker.link(kubeLink) : null; - addExternalUrl(property, kubeLink, externalUrl); - + + // Add the property name + out.append("|").append(propertyName); + + // Add the property type description + appendPropertyType(crd, out, propertyType, externalUrl); + + // Set warning message for deprecated fields + addDeprecationWarning(property); + // Add the version the field was added in addAddedIn(property); - + // Add the types to the `types` array to also generate the docs for the type itself Class documentedType = propertyType.isArray() ? propertyType.arrayBase() : propertyType.getType(); - + if (externalUrl == null - && !Schema.isJsonScalarType(documentedType) - && !documentedType.equals(Map.class) - && !documentedType.equals(Object.class)) { + && !Schema.isJsonScalarType(documentedType) + && !documentedType.equals(Map.class) + && !documentedType.equals(Object.class)) { types.add(documentedType); } - - // TODO Minimum?, Maximum?, Pattern? - - // Add the property type description - appendPropertyType(crd, out, propertyType, externalUrl); + + // Add the property description + addDescription(cls, property); + + out.append(NL); } + out.append("|====").append(NL).append(NL); - + appendNestedTypes(crd, types); - } + } /** * Sets warning message for deprecated fields @@ -250,7 +241,7 @@ private void addAddedIn(Property property) throws IOException { AddedIn addedIn = property.getAnnotation(AddedIn.class); if (addedIn != null) { - out.append(" Added in Strimzi " + addedIn.value() + "."); + out.append("Added in Strimzi " + addedIn.value() + ". "); } } @@ -316,18 +307,14 @@ private void appendNestedTypes(Crd crd, LinkedHashSet> types) throws IO } } - private int computePadding(String gunk, Map properties) { - int maxLen = 0; - for (Map.Entry entry: properties.entrySet()) { - maxLen = max(maxLen, entry.getKey().length() + 1 + gunk.length()); - } - return maxLen; - } - @SuppressWarnings("unchecked") private void appendPropertyType(Crd crd, Appendable out, PropertyType propertyType, String externalUrl) throws IOException { Class propertyClass = propertyType.isArray() ? propertyType.arrayBase() : propertyType.getType(); - out.append(NL).append("|"); + + + out.append(NL); + out.append("|"); + // Now the type link if (externalUrl != null) { out.append(externalUrl).append("[").append(propertyClass.getSimpleName()).append("]"); @@ -367,7 +354,10 @@ private void appendPropertyType(Crd crd, Appendable out, PropertyType propertyTy out.append(" of dimension ").append(String.valueOf(dim)); } } + out.append(NL); + out.append("|"); + } private void appendTypeDeprecation(Crd crd, Class cls) throws IOException { diff --git a/crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc b/crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc index 50772743f1f..a9e5e6d0efe 100644 --- a/crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc +++ b/crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc @@ -2,91 +2,129 @@ = `Example` schema reference -[options="header"] +[cols="2,2,3",options="header"] |==== -|Property |Description -|affinity 1.2+<._. +|Property |Property type |Description +|listenerConfig |map -|sasl 1.2+<._. +|sasl |boolean -|secrets 1.2+<.-_/__. +|Enable or disable SASL on this listener. +|secrets |xref:type-GenericSecretSource-{context}[`GenericSecretSource`] array -|type 1.2+<.-_/__. +|type |string +|Must be `custom`. |==== [id='type-GenericKafkaListenerConfiguration-{context}'] @@ -331,34 +411,48 @@ include::../api/io.strimzi.api.kafka.model.kafka.listener.GenericKafkaListenerCo == `GenericKafkaListenerConfiguration` schema properties -[options="header"] +[cols="2,2,3",options="header"] |==== -|Property |Description -|brokerCertChainAndKey 1.2+<._:__ pairs. +|The container image used for Kafka Connect pods. If no image name is explicitly specified, it is determined based on the `spec.version` configuration. The image names are specifically mapped to corresponding versions in the Cluster Operator configuration. +|bootstrapServers |string -|tls 1.2+<._:__ pairs. +|tls |xref:type-ClientTls-{context}[`ClientTls`] -|authentication 1.2+<.` format. -Authentication is optional. If authentication is not configured, no credentials are generated. ACLs and quotas set for the user are configured in the `` format suitable for SASL authentication. The type depends on the value of the `authentication.type` property within the given object, which must be one of [tls, tls-external, scram-sha-512]. -|xref:type-KafkaUserTlsClientAuthentication-{context}[`KafkaUserTlsClientAuthentication`], xref:type-KafkaUserTlsExternalClientAuthentication-{context}[`KafkaUserTlsExternalClientAuthentication`], xref:type-KafkaUserScramSha512ClientAuthentication-{context}[`KafkaUserScramSha512ClientAuthentication`] -|authorization 1.2+<.` format suitable for SASL authentication. +|authorization |xref:type-KafkaUserAuthorizationSimple-{context}[`KafkaUserAuthorizationSimple`] -|quotas 1.2+<.