Trigger a failover on a switchover pair
POST/switchover/v1/switchover-pairs/:id:failover
Triggers a failover (or switchback) on the switchover pair. Optionally promotes a specific
member to active and/or selects the failover semantics (PLANNED, UNPLANNED, or RESTORE).
Returns the updated SwitchoverPair whose status.phase transitions to UPDATING.
Request
Responses
- 202
- 400
- 401
- 403
- 404
- 409
- 429
- 500
The failover has been accepted; the switchover pair transitions to UPDATING while
the operation completes asynchronously.
Bad Request
Response Headers
X-Request-Id
The unique identifier for the API request.
The request lacks valid authentication credentials for this resource.
Response Headers
X-Request-Id
The unique identifier for the API request.
WWW-Authenticate
The unique identifier for the API request.
Example:
Basic error="invalid_key", error_description="The API Key is invalid"The access credentials were considered insufficient to grant access
Response Headers
X-Request-Id
The unique identifier for the API request.
Not Found
Response Headers
X-Request-Id
The unique identifier for the API request.
The request is in conflict with the current server state
Response Headers
X-Request-Id
The unique identifier for the API request.
Location
Resource URI of conflicting resource
Rate Limit Exceeded
Response Headers
X-Request-Id
The unique identifier for the API request.
X-RateLimit-Limit
The maximum number of requests you're permitted to make per time period.
X-RateLimit-Remaining
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The relative time in seconds until the current rate-limit window resets.
Important: This differs from Github and Twitter's same-named header which uses UTC epoch seconds. We use relative time to avoid client/server time synchronization issues.
Retry-After
The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
Oops, something went wrong!
Response Headers
X-Request-Id
The unique identifier for the API request.
OpenAPI definition (YAML)
paths:
/switchover/v1/switchover-pairs/{id}:failover:
post:
description: '[](#section/Versioning/API-Lifecycle-Policy)
[](mailto:ccloud-api-access+switchover-v1-early-access@confluent.io?subject=Request%20to%20join%20switchover/v1%20API%20Early%20Access&body=I%E2%80%99d%20like%20to%20join%20the%20Confluent%20Cloud%20API%20Early%20Access%20for%20switchover/v1%20to%20provide%20early%20feedback%21%20My%20Cloud%20Organization%20ID%20is%20%3Cretrieve%20from%20https%3A//confluent.cloud/settings/billing/payment%3E.)
Triggers a failover (or switchback) on the switchover pair. Optionally promotes a specific
member to active and/or selects the failover semantics (`PLANNED`, `UNPLANNED`, or `RESTORE`).
Returns the updated `SwitchoverPair` whose `status.phase` transitions to `UPDATING`.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Request body for the `:failover` operation on a `SwitchoverPair`.
required:
- spec
properties:
spec:
type: object
required:
- environment_crn
- failover_type
properties:
environment_crn:
type: string
format: uri
pattern: ^crn://confluent\.cloud/organization=[^/]+/environment=[^/]+$
description: 'The CRN of the switchover pair''s environment. Required; unlike the
other operations,
this endpoint takes it from the request body rather than a query parameter.
'
example: crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000
active_member:
type: string
description: 'The name of the member to promote to active. If type is PLANNED/UNPLANNED,
then
`active_member` must be provided.
'
example: east
failover_type:
type: string
description: "The failover semantics to apply. Required — this field decides whether\
\ the operation\ncan lose data, so it must be stated on every call rather than\
\ defaulted.\n PLANNED: graceful failover after replication lag reaches zero\
\ (cluster link is reversed);\n UNPLANNED: immediate failover without waiting\
\ for replication (cluster link is stopped);\n RESTORE: re-establish the cluster\
\ link after an unplanned failover.\n"
example: PLANNED
enum:
- PLANNED
- UNPLANNED
- RESTORE
title: switchover.v1.SwitchoverPairFailoverRequest
x-lifecycle-stage: Early Access
x-self-access: false
x-request-access-name: Switchover API (Kafka Disaster Recovery)
x-name: switchover.v1.SwitchoverPair
operationId: failoverSwitchoverV1SwitchoverPair
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier for the switchover pair.
tags:
- Switchover Pairs (switchover/v1)
security:
- cloud-api-key: []
- global-api-key: []
responses:
'202':
description: 'The failover has been accepted; the switchover pair transitions to `UPDATING`
while
the operation completes asynchronously.
'
content:
application/json:
schema:
type: object
description: '`SwitchoverPair` represents a cluster-level Disaster Recovery pairing between
two Kafka
clusters in different regions of the same environment. Exactly one member is active
at any
time; the other is passive and kept in sync via a bidirectional cluster link.
The API allows you to list, create, read, update, and delete switchover pairs, and to
trigger
a failover (promotion of the passive member) via the `:failover` operation.
Related guide: [Disaster Recovery for Kafka in Confluent Cloud](https://docs.confluent.io/cloud/current/clusters/cluster-linking/index.html).
'
properties:
api_version:
type: string
enum:
- switchover/v1
description: APIVersion defines the schema version of this representation of a resource.
readOnly: true
kind:
type: string
description: Kind defines the object this REST resource represents.
readOnly: true
enum:
- SwitchoverPair
id:
description: ID is the "natural identifier" for an object within its scope/namespace;
it is normally unique across time but not space. That is, you can assume that the
ID will not be reclaimed and reused after an object is deleted ("time"); however,
it may collide with IDs for other object `kinds` or objects of the same `kind` within
a different scope/namespace ("space").
type: string
maxLength: 255
readOnly: true
example: dlz-f3a90de
metadata:
allOf:
- description: ObjectMeta is metadata that all persisted resources must have, which
includes all objects users must create.
required:
- self
properties:
self:
description: Self is a Uniform Resource Locator (URL) at which an object can
be addressed. This URL encodes the service location, API version, and other
particulars necessary to locate the resource at a point in time
type: string
format: uri
readOnly: true
example: https://api.confluent.cloud/v2/kafka-clusters/lkc-f3a90de
resource_name:
description: Resource Name is a Uniform Resource Identifier (URI) that is globally
unique across space and time. It is represented as a Confluent Resource Name
type: string
format: uri
readOnly: true
example: crn://confluent.cloud/kafka=lkc-f3a90de
created_at:
type: string
format: date-time
example: '2006-01-02T15:04:05-07:00'
readOnly: true
description: The date and time at which this object was created. It is represented
in RFC3339 format and is in UTC.
updated_at:
type: string
format: date-time
example: '2006-01-02T15:04:05-07:00'
readOnly: true
description: The date and time at which this object was last updated. It is
represented in RFC3339 format and is in UTC.
deleted_at:
type: string
format: date-time
example: '2006-01-02T15:04:05-07:00'
readOnly: true
description: The date and time at which this object was (or will be) deleted.
It is represented in RFC3339 format and is in UTC.
readOnly: true
title: ObjectMeta
- properties:
self:
example: https://api.confluent.cloud/switchover/v1/switchover-pairs/sw-12345
resource_name:
example: crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/switchover-pair=sw-12345
spec:
type: object
description: The desired state of the Switchover Pair
properties:
environment_crn:
type: string
format: uri
pattern: ^crn://confluent\.cloud/organization=[^/]+/environment=[^/]+$
description: 'The CRN of the environment this resource belongs to.
Every reference in a request body is a CRN (see `member_crn`), so this is one
too rather
than an `{id}` relationship object — callers learn a single convention, and
the
organization always travels with the reference. A CRN that names no environment
is
rejected; it is not defaulted.
The `?environment=` query parameter on the other operations remains a bare environment
ID:
it is the standard Confluent collection filter, not a reference to a stored
resource.
'
example: crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000
display_name:
type: string
description: A human-readable name for the switchover pair.
example: prod-kafka-dr
maxLength: 256
members:
type: array
description: 'The two clusters participating in this switchover pair. Must contain
exactly 2 members.
'
minItems: 2
maxItems: 2
items:
type: object
description: One side (cluster) of a `SwitchoverPair`.
required:
- name
- member_crn
properties:
name:
type: string
description: A logical name for this member (e.g. "west" or "east"), unique
within the pair.
example: west
member_crn:
type: string
format: uri
pattern: ^crn://confluent\.cloud/organization=[^/]+/environment=[^/]+/.+$
description: 'The Confluent Resource Name (CRN) of the resource this member
represents.
A CRN rather than an ID plus an environment because member types do not
share a parent
hierarchy: a Kafka cluster is `environment → cloud-cluster`, a Flink compute
pool is
`environment → flink-region → compute-pool`, and a Connect connector is
`environment → cloud-cluster → connector` with a *name* as its leaf, unique
only within its
cluster. A single `environment` field cannot address the latter two unambiguously.
The environment is read from the CRN, so a pair whose two members live
in different
environments needs no separate per-member environment field.
For a Kafka cluster both the canonical form and the variant carrying the
redundant trailing
`/kafka=<lkc>` (which the cmk API returns in `metadata.resource_name`)
are accepted. The
short `crn://confluent.cloud/kafka=<lkc>` form is rejected: it is a valid
CRN but carries no
environment. In Terraform the value is available as
`confluent_kafka_cluster.<name>.rbac_crn`.
'
example: crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000/cloud-cluster=lkc-00000
location:
type: object
description: 'The cloud location of this member''s cluster. Derived server-side
from the cluster the
member''s CRN names; not settable by the client.
'
readOnly: true
properties:
cloud:
type: string
description: The cloud provider hosting this member (e.g. `aws`, `gcp`,
`azure`).
example: aws
region:
type: string
description: The cloud region hosting this member (e.g. `us-west-2`).
example: us-west-2
title: switchover.v1.SwitchoverPairMember
x-immutable: true
active_member:
type: string
description: 'The name of the member that is currently active. On create, this
selects which member
starts as active; it must match one of the `members[].name` values. Use the
`:failover`
operation to change the active member after creation.
'
example: west
x-immutable: true
first_active:
type: string
description: 'The member that was active when the pair was created. Output-only
and immutable; set
implicitly at create time and never accepted as input. Comparing it with `active_member`
distinguishes a pair that has failed over (they differ) from one still on its
original
active member (they match).
'
readOnly: true
example: west
failover_type:
type: string
description: 'The failover semantics most recently applied to this pair via the
`:failover` operation.
Not settable directly; empty until a failover has been triggered.
'
readOnly: true
example: PLANNED
enum:
- PLANNED
- UNPLANNED
- RESTORE
x-enable-id: true
x-enable-listmeta: true
x-enable-objectmeta: true
title: switchover.v1.SwitchoverPairSpec
status:
type: object
required:
- phase
description: The status of the Switchover Pair
properties:
phase:
type: string
description: "The lifecycle phase of the switchover pair:\n PROVISIONING: \
\ the pair is being created and validated;\n READY_TO_FAILOVER: the pair\
\ is validated and a failover (planned or unplanned) can be triggered;\n UPDATING:\
\ a failover, failback, or restore operation is in progress;\n READY_TO_RESTORE:\
\ an unplanned failover has completed; the cluster link can be restored;\n\
\ FAILED: resource validation failed for the pair; it must be deleted\
\ and recreated;\n DEPROVISIONING: the pair is being deleted.\n"
readOnly: true
example: READY_TO_FAILOVER
enum:
- PROVISIONING
- READY_TO_FAILOVER
- UPDATING
- READY_TO_RESTORE
- FAILED
- DEPROVISIONING
conditions:
type: array
description: Status conditions providing detailed information about the switchover
pair's current state.
items:
type: object
description: A single status condition, following the standard Kubernetes/Confluent
condition pattern.
required:
- type
- status
properties:
member:
type: string
description: 'The `SwitchoverPair` member this condition belongs to. Conditions
are recorded per
member and flattened into a single list, so the same condition `type`
can appear once
per member; this field disambiguates them. Empty for pair-level conditions
that have no
member dimension.
'
example: east
type:
type: string
description: 'The condition type — one of `ResourceValidationComplete`,
`ResourcePlannedFailoverComplete`,
`ResourceUnplannedFailoverComplete`, or `ResourceRestoreComplete`.
'
example: ResourceValidationComplete
enum:
- ResourceValidationComplete
- ResourcePlannedFailoverComplete
- ResourceUnplannedFailoverComplete
- ResourceRestoreComplete
status:
type: string
description: The status of the condition.
example: 'True'
enum:
- 'True'
- 'False'
- Unknown
reason:
type: string
description: A machine-readable reason for the condition's current status.
example: Reconciled
message:
type: string
description: A human-readable message providing additional detail about
the condition.
example: The resource is ready.
title: switchover.v1.Condition
readOnly: true
readOnly: true
title: switchover.v1.SwitchoverPairStatus
title: switchover.v1.SwitchoverPair
'400':
description: Bad Request
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '400'
code: invalid_filter
title: Invalid Filter
detail: The 'delorean' resource can't be filtered by 'num_doors'
source:
parameter: num_doors
'401':
x-summary: Unauthorized
description: The request lacks valid authentication credentials for this resource.
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
WWW-Authenticate:
schema:
type: string
description: The unique identifier for the API request.
example: Basic error="invalid_key", error_description="The API Key is invalid"
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '401'
code: user_unauthenticated
title: Authentication Required
detail: Valid authentication credentials must be provided
'403':
x-summary: Forbidden
description: The access credentials were considered insufficient to grant access
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '403'
code: user_unauthorized
title: User Access Unauthorized
detail: The user 'mcfly' is not allowed to access the 'delorean' resource without the
'plutonium' role.
'404':
description: Not Found
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '404'
title: Not Found
'409':
x-summary: Conflict
description: The request is in conflict with the current server state
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
Location:
schema:
type: string
format: uri
example: https://api.confluent.cloud/{object}/{id}
description: Resource URI of conflicting resource
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '409'
code: resource_already_exists
title: Resource Already exists
detail: The entitlement '91e3e86f-fca6-4f14-98f5-a48e64113ce2' already exists.
'429':
description: Rate Limit Exceeded
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
X-RateLimit-Limit:
schema:
type: integer
description: The maximum number of requests you're permitted to make per time period.
X-RateLimit-Remaining:
schema:
type: integer
description: The number of requests remaining in the current rate limit window.
X-RateLimit-Reset:
schema:
type: integer
description: "The relative time in seconds until the current rate-limit window resets. \
\ \n \n**Important:** This differs from Github and Twitter's same-named header which\
\ uses UTC epoch seconds. We use relative time to avoid client/server time synchronization\
\ issues."
Retry-After:
schema:
type: integer
description: The number of seconds to wait until the rate limit window resets. Only sent
when the rate limit is reached.
'500':
description: Oops, something went wrong!
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
content:
application/json:
schema:
type: object
description: Provides information about problems encountered while performing an operation.
required:
- errors
properties:
errors:
description: List of errors which caused this operation to fail
type: array
items:
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
uniqueItems: true
title: Failure
example:
errors:
- id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
status: '500'
code: out_of_gas
title: DeLorean Out Of Gas
detail: The DeLorean has run out of gas, but Doc Brown will fill 'er up for you asap
servers:
- url: https://api.confluent.cloud
description: Confluent Cloud API
jsonRequestBodyExample:
spec:
environment_crn: crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000
active_member: east
failover_type: PLANNED