[FEATURE] Kafka: add principal field to operation binding for ACL documentation
- Dominant language
- No language data
- Stars
- 79
- Forks
- 81
- PR merge metrics
- No merged PRs in 30d
Description
### Why do we need this improvement?
Kafka access is controlled via ACLs, but there is no way to document which
principal an operation requires in an AsyncAPI document. Teams have to look
outside the spec to find out what service account to use and what permissions
to request.
### How will this change help?
The principal and its required permission become part of the contract.
The permission direction is already implicit in the operation `action`:
`send` implies write, `receive` implies read.
Tooling that generates Kafka ACLs or RBAC assignments from AsyncAPI documents
can derive the full access rule from the operation alone.
### Screenshots
_No response_
### How could it be implemented/designed?
Add a single `principal` string field to the Operation Binding Object.
| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
| `principal` | string | The Kafka principal (service account or user) that requires access to perform this operation. | OPTIONAL | The implied permission is `write` for `send` operations and `read` for `receive` operations. |
Example:
```yaml
operations:
publishPaymentEvent:
action: send
bindings:
kafka:
principal: 'payments-service'
bindingVersion: '0.6.0'
consumePaymentEvents:
action: receive
bindings:
kafka:
principal: 'payments-service'
bindingVersion: '0.6.0'
```
In `spec-json-schemas`, the addition to `operation.json` is straightforward:
```json
"principal": {
"type": "string",
"description": "The Kafka principal (service account or user) that requires access to perform this operation. The implied permission is write for send operations and read for receive operations."
}
```
### 🚧 Breaking changes
No
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find a similar issue
### 🏢 Have you read the Contributing Guidelines?
- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)
### Are you willing to work on this issue?
Yes I am willing to submit a PR!
Contributor guide
Research direction
Start with spec-json-schemas/operation.json, where the issue identifies the required schema change. Add the optional principal field with its stated description and constraints, then verify the provided send and receive examples validate and that the operation binding schema accepts the new field.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kafka
- Domain
- api
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100