asyncapi / asyncapi/bindings

[FEATURE] Kafka Channel Binding Property for Environment-Specific Overrides

Open
#292 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.