Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add essential Kafka client security parameters to bindings #56

Closed
wants to merge 1 commit into from
Closed

docs: add essential Kafka client security parameters to bindings #56

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 22 additions & 2 deletions kafka/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.


<a name="server"></a>

## 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the whole "Constraints" column is empty, shouldn't we just get rid of it entirely?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was doing that to avoid the merge conflict if both this and #55 get approved

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I see. Thanks for the explanation 👍

---|:---:|:---:|:---:|---
`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. <br>Example values include `GSSAPI`, `PLAIN`, `OAUTHBEARER`, `SCRAM-SHA-256`, `SCRAM-SHA-512` | OPTIONAL [`GSSAPI`] | -
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really the default value is GSSAPI? Isn't it PLAIN?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, shouldn't we have something like a NONE value to disable the saslMechanism?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did that to mirror what Kafka does by default - which is GSSAPI

https://github.com/apache/kafka/blob/fc68c0fc9b1199b4eb63d9d486b012667c1d448f/clients/src/main/java/org/apache/kafka/common/config/SaslConfigs.java#L32

image

But I think adding a NONE option for when using kafka instead of kafka-secure might make sense, and make a better default.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. In any case, if we move this to the Security Schemes Object, we would not need the NONE value anymore. Sorry, for the messed-up review. I realized about the other comments after I made the review.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no problem at all - it's been a useful thread, thanks to both you and @smoya !

`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. <br>Example values include `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL` | OPTIONAL [`PLAINTEXT`] | -
<a name="serverBindingObjectBindingVersion"></a>`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'
```


<a name="channel"></a>
Expand Down