Create a cluster link
POST/kafka/v3/clusters/:cluster_id/links
Cluster link creation requires source cluster security configurations in the configs JSON section of the data request payload.
Request
Responses
- 204
- 400
- 401
- 429
- 5XX
Operation succeeded, no content in the response
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
Indicates that a rate limit threshold has been reached, and the client should retry again later.
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
OpenAPI definition (YAML)
paths:
/kafka/v3/clusters/{cluster_id}/links:
post:
operationId: createKafkaLink
description: '[](#section/Versioning/API-Lifecycle-Policy)
Cluster link creation requires source cluster security configurations in
the configs JSON section of the data request payload.'
tags:
- Cluster Linking (v3)
security:
- resource-api-key: []
- external-access-token: []
parameters:
- name: link_name
description: The link name
in: query
required: true
schema:
type: string
example: link-sb1
- name: validate_only
description: 'To validate the action can be performed successfully or not. Default: false'
in: query
required: false
schema:
type: boolean
example: false
- name: validate_link
description: 'To synchronously validate that the source cluster ID is expected and the dest cluster
has the permission to read topics in the source cluster. Default: true'
in: query
required: false
schema:
type: boolean
example: false
- name: cluster_id
description: The Kafka cluster ID.
in: path
required: true
schema:
type: string
example: cluster-1
requestBody:
description: Create a cluster link
content:
application/json:
schema:
properties:
source_cluster_id:
type: string
destination_cluster_id:
type: string
remote_cluster_id:
description: The expected remote cluster ID.
type: string
cluster_link_id:
description: The expected cluster link ID. Can be provided when creating the second
side of a bidirectional link for validating the link ID is as expected. If it's not
provided, it's inferred from the remote cluster.
type: string
configs:
items:
example:
name: name
value: value
properties:
name:
type: string
value:
nullable: true
type: string
required:
- name
- value
title: ConfigData
type: array
type: object
title: CreateLinkRequestData
examples:
destination_initiated_link:
description: Create a destination initiated cluster link
value:
source_cluster_id: cluster-1
configs:
- name: bootstrap.servers
value: cluster-1-bootstrap-server
- name: acl.sync.enable
value: 'false'
- name: consumer.offset.sync.ms
value: '30000'
- name: sasl.mechanism
value: PLAIN
- name: security.protocol
value: SASL_SSL
- name: sasl.jaas.config
value: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username='<Kafka API Key>' password='<Kafka API Secret>';
source_initiated_link_at_source_cluster:
description: Create a source initiated cluster link at source cluster
value:
destination_cluster_id: cluster-2
configs:
- name: bootstrap.servers
value: cluster-2-bootstrap-server
- name: link.mode
value: SOURCE
- name: sasl.mechanism
value: PLAIN
- name: security.protocol
value: SASL_SSL
- name: sasl.jaas.config
value: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username='<Remote Kafka API Key>' password='<Remote Kafka API Secret>';
- name: local.sasl.mechanism
value: PLAIN
- name: local.security.protocol
value: SASL_SSL
- name: local.sasl.jaas.config
value: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username='<Local Kafka API Key>' password='<Local Kafka API Secret>';
source_initiated_link_at_destination_cluster:
description: Create a source initiated cluster link at destination cluster
value:
destination_cluster_id: cluster-1
configs:
- name: link.mode
value: DESTINATION
- name: connection.mode
value: INBOUND
- name: acl.sync.enable
value: 'false'
bidirectional_link_east:
description: Create a bidirectional cluster link in east
value:
remote_cluster_id: cluster-west
configs:
- name: bootstrap.servers
value: cluster-west-bootstrap-server
- name: link.mode
value: BIDIRECTIONAL
- name: cluster.link.prefix
value: west.
- name: sasl.mechanism
value: PLAIN
- name: security.protocol
value: SASL_SSL
- name: sasl.jaas.config
value: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username='<Kafka API Key>' password='<Kafka API Secret>';
bidirectional_link_west:
description: Create a bidirectional cluster link in west
value:
remote_cluster_id: cluster-east
cluster_link_id: eEBkTffYSESld6EO898x3w
configs:
- name: bootstrap.servers
value: cluster-east-bootstrap-server
- name: link.mode
value: BIDIRECTIONAL
- name: cluster.link.prefix
value: east.
- name: sasl.mechanism
value: PLAIN
- name: security.protocol
value: SASL_SSL
- name: sasl.jaas.config
value: sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required
username='<Kafka API Key>' password='<Kafka API Secret>';
responses:
'204':
description: Operation succeeded, no content in the response
'400':
description: Indicates a bad request error. It could be caused by an unexpected request body
format or other forms of request validation failure.
content:
application/json:
schema:
type: object
description: Describes a particular error encountered while performing an operation.
properties:
id:
description: A unique identifier for this particular occurrence of the problem.
type: string
maxLength: 255
status:
description: The HTTP status code applicable to this problem, expressed as a string
value.
type: string
code:
description: An application-specific error code, expressed as a string value.
type: string
title:
description: A short, human-readable summary of the problem. It **SHOULD NOT** change
from occurrence to occurrence of the problem, except for purposes of localization.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
source:
type: object
description: If this error was caused by a particular part of the API request, the
source will point to the query string parameter or request body property that caused
it.
properties:
pointer:
description: A JSON Pointer [RFC6901] to the associated entity in the request
document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
type: string
parameter:
description: A string indicating which query parameter caused the error.
type: string
error_code:
type: integer
format: int32
message:
type: string
nullable: true
additionalProperties: false
title: Error
examples:
bad_request_cannot_deserialize:
description: Thrown when trying to deserialize an integer from non-integer data.
value:
error_code: 400
message: 'Cannot deserialize value of type `java.lang.Integer` from String "A": not
a valid `java.lang.Integer` value'
unsupported_version_exception:
description: Thrown when the version of this API is not supported in the underlying
Kafka cluster.
value:
error_code: 40035
message: The version of this API is not supported in the underlying Kafka cluster.
'401':
description: Indicates a client authentication error. Kafka authentication failures will contain
error code 40101 in the response body.
content:
application/json:
schema:
type: object
description: Describes a particular error encountered while performing an operation.
properties:
id:
description: A unique identifier for this particular occurrence of the problem.
type: string
maxLength: 255
status:
description: The HTTP status code applicable to this problem, expressed as a string
value.
type: string
code:
description: An application-specific error code, expressed as a string value.
type: string
title:
description: A short, human-readable summary of the problem. It **SHOULD NOT** change
from occurrence to occurrence of the problem, except for purposes of localization.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
source:
type: object
description: If this error was caused by a particular part of the API request, the
source will point to the query string parameter or request body property that caused
it.
properties:
pointer:
description: A JSON Pointer [RFC6901] to the associated entity in the request
document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
type: string
parameter:
description: A string indicating which query parameter caused the error.
type: string
error_code:
type: integer
format: int32
message:
type: string
nullable: true
additionalProperties: false
title: Error
examples:
kafka_authentication_failed:
description: Thrown when using Basic authentication with wrong Kafka credentials.
value:
error_code: 40101
message: Authentication failed
'429':
description: Indicates that a rate limit threshold has been reached, and the client should retry
again later.
content:
text/html:
schema:
type: string
example:
description: A sample response from Jetty's DoSFilter.
value: <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many
Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr>
<th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td>
</tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>
5XX:
description: A server-side problem that might not be addressable from the client side. Retriable
Kafka errors will contain error code 50003 in the response body.
content:
application/json:
schema:
type: object
description: Describes a particular error encountered while performing an operation.
properties:
id:
description: A unique identifier for this particular occurrence of the problem.
type: string
maxLength: 255
status:
description: The HTTP status code applicable to this problem, expressed as a string
value.
type: string
code:
description: An application-specific error code, expressed as a string value.
type: string
title:
description: A short, human-readable summary of the problem. It **SHOULD NOT** change
from occurrence to occurrence of the problem, except for purposes of localization.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
source:
type: object
description: If this error was caused by a particular part of the API request, the
source will point to the query string parameter or request body property that caused
it.
properties:
pointer:
description: A JSON Pointer [RFC6901] to the associated entity in the request
document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
type: string
parameter:
description: A string indicating which query parameter caused the error.
type: string
error_code:
type: integer
format: int32
message:
type: string
nullable: true
additionalProperties: false
title: Error
examples:
generic_internal_server_error:
description: Thrown for generic HTTP 500 errors.
value:
error_code: 500
message: Internal Server Error
servers:
- url: https://pkc-00000.region.provider.confluent.cloud
x-audience: business-unit-internal
description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud
jsonRequestBodyExample:
source_cluster_id: string
destination_cluster_id: string
remote_cluster_id: string
cluster_link_id: string
configs:
- name: name
value: value