From 898f545bcb55d8f69f3bf97cbcc5b27344d8a56a Mon Sep 17 00:00:00 2001 From: Dale Lane Date: Wed, 24 Feb 2021 12:21:49 +0000 Subject: [PATCH] docs: add essential Kafka client security parameters to bindings There are a huge number of Kafka client configs we could add to server bindings, but I'm skeptical of the value of just copying them all across. Most client config values have sensible defaults that are suitable in most cases. cf. https://kafka.apache.org/documentation/#consumerconfigs Two values are essential for code generation with secured Kafka clusters, however - identifying the security mechanism and protocol to use. This commit adds these two most commonly-used parameters to the Kafka server bindings. I suggest we start with these and gauge usage before starting to add many more, as these are enough to enable code generation for secured Kafka clusters. Closes: asyncapi/asyncapi#466 Signed-off-by: Dale Lane --- kafka/README.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/kafka/README.md b/kafka/README.md index c3ea466f..10188d81 100644 --- a/kafka/README.md +++ b/kafka/README.md @@ -6,16 +6,36 @@ This document defines how to describe Kafka-specific information on AsyncAPI. ## Version -Current version is `0.1.0`. +Current version is `0.2.0`. ## Server Binding Object -This object MUST NOT contain any properties. Its name is reserved for future use. +This object contains information about the server representation in Kafka. + +##### Fixed Fields +Field Name | Type | Description | Applicability [default] | Constraints +---|:---:|:---:|:---:|--- +`saslMechamism` | string | Specifies the [`sasl.mechanism`](https://kafka.apache.org/documentation/#consumerconfigs_sasl.mechanism) config property that must be specified by Kafka clients connecting to this server.
Example values include `GSSAPI`, `PLAIN`, `OAUTHBEARER`, `SCRAM-SHA-256`, `SCRAM-SHA-512` | OPTIONAL [`GSSAPI`] | - +`securityProtocol` | string | Specifies the [`security.protocol`](https://kafka.apache.org/documentation/#consumerconfigs_security.protocol) config property that must be specified by Kafka clients connecting to this server.
Example values include `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL` | OPTIONAL [`PLAINTEXT`] | - +`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] + +This object MUST contain only the properties defined above. +##### Example + +```yaml +servers: + production: + bindings: + kafka: + saslMechanism: 'SCRAM-SHA-512' + securityProtocol: 'SASL_PLAINTEXT' + bindingVersion: '0.2.0' +```