[FEATURE] Kafka Channel Binding Property for Environment-Specific Overrides
- Dominant language
- No language data
- Stars
- 79
- Forks
- 81
- PR merge metrics
- No merged PRs in 30d
Description
### Why do we need this improvement?
## Motivation
Kafka topics frequently require different settings per environment:
- Lower partitions / replicas in dev environments
- Shorter retention policies in non-production
- Reduced storage limits for cost control
- Different cleanup strategies
Without native support, teams can not use AsyncAPI as the single source of truth for both API contract and infrastructure deployment. They typically rely on:
- External deployment logic
- Custom templating systems
This increases complexity and reduces portability. Embedding overrides improves clarity, reduces duplication, and aligns infrastructure intent with the API contract.
### How will this change help?
## Summary
This proposal introduces a Kafka channel binding property that enables environment-specific overrides of topic configuration within an AsyncAPI document. This property provides a standardized, explicit mechanism to declare such differences directly within channel bindings so AsyncAPI can be the single source of truth for both API contract and infrastructure deployment.
### Screenshots
_No response_
### How could it be implemented/designed?
## Proposed Property
Introduce a new property at the Kafka channel binding level:
``` yaml
channelBindings:
someKafkaChannelBinding:
kafka:
partitions: 20
replicas: 3
topicConfiguration:
cleanup.policy: ["delete", "compact"]
retention.ms: 604800000
retention.bytes: 1000000000
delete.retention.ms: 86400000
max.message.bytes: 1048588
envServerOverrides:
dev:
partitions: 1
replicas: 1
topicConfiguration:
cleanup.policy: ["delete"]
retention.ms: 604800
staging:
partitions: 3
replicas: 2
```
## Semantics
- The base `kafka` binding defines the default topic configuration.
- `env-server-overrides` defines partial overrides applied conditionally.
- Keys under `env-server-overrides` correspond to server names defined in the AsyncAPI document.
- Each override object follows the same schema as the Kafka channel binding but allows partial definitions.
- Overrides are applied as a merge on top of the base binding.
## Resolution Rules
When using AsyncAPI channel bindings to provision Kafka topics, the following rules apply:
1. Identify the active server (tooling / runtime decision).
2. Match the server name against `env-server-overrides`.
3. Merge override fields onto the base Kafka binding.
4. Unspecified properties inherit base values.
## Validation Considerations
- Override keys are expected to correspond to existing `servers` entries.
- Override objects should follow the Kafka channel binding structure.
## Naming Discussion
The proposed name is `env-server-overrides`.
Rationale:
- `env` communicates intent (environment-dependent behavior)
- `server` aligns with AsyncAPI's existing server model
- `overrides` clearly expresses merge semantics
`env-server-overrides` explicitly ties overrides to AsyncAPI server definitions rather than arbitrary environment labels.
## Future Considerations
- Would this property be useful for other protocols?
### 🚧 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
No repository files or tests are named in the issue, so first locate the Kafka channel-binding schema, server definitions, validation, and related tests. Compare existing binding properties and server handling, then define the override shape and merge behavior; done means the schema, validation rules, and tests cover the proposed server-specific overrides.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kafka
- Domain
- backend-api-design, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100