Package org.apache.kafka.clients.admin

Interface ConfluentAdmin

All Superinterfaces:
Admin, AutoCloseable
All Known Implementing Classes:
KafkaAdminClient
@Confluent public interface ConfluentAdmin extends Admin
This interface contains admin client methods that:
  1. are only present in Confluent Server, or
  2. existing Admin methods that return or take extra information only available in Confluent Server.

Any new or update to admin client api that need these features should be done here.

  • Method Details

    • create

      static ConfluentAdmin create(Properties props)
      Create a new ConfluentAdmin with the given configuration.
      Parameters:
      props - The configuration.
      Returns:
      The new KafkaAdminClient.

    • create

      static ConfluentAdmin create(Map<String,Object> conf)
      Create a new ConfluentAdmin with the given configuration.
      Parameters:
      conf - The configuration.
      Returns:
      The new KafkaAdminClient.

    • replicaStatus

      @Confluent ReplicaStatusResult replicaStatus(Set<TopicPartition> partitions, ReplicaStatusOptions options)
      Retrieves the status of the replicas for a set of partitions, including observers.

      The status of the replicas will be as witnessed by the partition leader. That is, the replicas themselves may be further in progress than what's provided, however the leader has not yet processed that state update.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned ReplicaStatusResult:

      Parameters:
      partitions - The partitions to retrieve replica status for.
      options - The options to use.
      Returns:
      The resulting replica status of every requested partition.

    • createCentralizedAcls

      @Confluent CreateAclsResult createCentralizedAcls(Collection<AclBinding> acls, CreateAclsOptions options, String clusterId, int writerBrokerId)
      Creates access control lists (ACLs) which are bound to specific resources.

      This operation is not transactional so it may succeed for some ACLs while fail for others.

      If you attempt to add an ACL that duplicates an existing ACL, no error will be raised, but no changes will be made.

      This operation is supported by brokers with version 0.11.0.0 or higher.

      Parameters:
      acls - The ACLs to create
      options - The options to use when creating the ACLs.
      clusterId - Cluster id for which ACLs are being updated
      writerBrokerId - Broker id of the current centralized metadata master writer
      Returns:
      The CreateAclsResult.

    • deleteCentralizedAcls

      @Confluent DeleteAclsResult deleteCentralizedAcls(Collection<AclBindingFilter> filters, DeleteAclsOptions options, String clusterId, int writerBrokerId)
      Deletes access control lists (ACLs) according to the supplied filters.

      This operation is not transactional so it may succeed for some ACLs while fail for others.

      This operation is supported by brokers with version 0.11.0.0 or higher.

      Parameters:
      filters - The filters to use.
      options - The options to use when deleting the ACLs.
      clusterId - Cluster id for which ACLs are being updated
      writerBrokerId - Broker id of the current centralized metadata master writer
      Returns:
      The DeleteAclsResult.

    • removeBrokers

      @Confluent default RemoveBrokersResult removeBrokers(List<Integer> brokersToRemove)
      Drain data off a given set of brokers and remove them from the cluster via shutdown. This API initiates the removal. It is suggested that the user tracks it via describeBrokerRemovals()

      Once initiated, the brokers will be shut down and replicas will be reassigned away from them.

      This is a convenience method for removeBrokers(List, RemoveBrokersOptions) with default options. See the overload for more details.

      Parameters:
      brokersToRemove - The broker IDs to drain off partition replicas and shut down. Must not be empty.
      Returns:
      The result of the broker removal operation.

    • removeBrokers

      @Confluent RemoveBrokersResult removeBrokers(List<Integer> brokersToRemove, RemoveBrokersOptions options)
      Drain data off a given set of brokers and remove them from the cluster via shutdown. This API initiates the removal. It is suggested that the user tracks it via describeBrokerRemovals()

      Once initiated, the brokers will be shut down and replicas will be reassigned away from them.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned RemoveBrokersResult:

    • ClusterAuthorizationException If we didn't have sufficient permission to initiate the broker removal. None of the requests started.
    • TimeoutException If the request timed out before the controller could initiate the broker removal. It cannot be guaranteed whether the removal was initiated or not.
    • BalancerOfflineException If the Confluent Balancer component is disabled or not started yet. Query its status with describeBalancerStatus() for more information
    • BalancerLoadError If the Confluent Balancer component failed to load. Query its status with describeBalancerStatus() for more information
    • BalancerOperationFailedException If the operation failed during execution of the removal.
    • InsufficientRebalancePlanMetricsException If computing the rebalance plan for broker removal failed due to insufficient metrics.
    • RebalancePlanComputationException If computing the rebalance plan for broker removal failed for reasons other than insufficient metrics like not enough disk space, replication factor same as the cluster size in case of broker removal etc.
    • InvalidBrokerRemovalException If requested broker removal operation is invalid, examples being a non-existent broker ID or some partitions (RF=1) becoming unavailable as a result of the removal.
    • BrokerRemovalInProgressException If the broker is already being removed.
    • BrokerRemovedException If the broker was already removed successfully.
    • BalancerBrokerExcludedForReplicaPlacementException If there are active broker replica exclusions in the cluster for brokers that are not part of the removal request. See describeBrokerReplicaExclusions() for more information
      • Parameters:
      brokersToRemove - The broker IDs to drain off partition replicas and shut down. Must not be empty.
      options - The options to use for the request.
      Returns:
      The result of the broker removal operation.

    • describeBrokerRemovals

      @Confluent default DescribeBrokerRemovalsResult describeBrokerRemovals()
      Describes all the broker removals in the cluster. Note that a removal is considered cleared once a broker starts up with 0 partitions.

      This is a convenience method for describeBrokerRemovals(DescribeBrokerRemovalsOptions) with default options. See the overload for more details.

    • describeBrokerRemovals

      @Confluent DescribeBrokerRemovalsResult describeBrokerRemovals(DescribeBrokerRemovalsOptions options)
      Describes all the broker removals in the cluster. Note that a removal is considered cleared once a broker starts up with 0 partitions.

      A broker removal consists of broker shutdown and partition reassignments that move all replicas the now-shutdown broker hosted away from it. The status of the removal is tracked by two separate status fields: 1. #BrokerRemovalDescription.shutdownStatus(), a #BrokerShutdownStatus denoting the status of the shutdown operation 2. #BrokerRemovalDescription.reassignmentsStatus(), a #PartitionReassignmentsStatus denoting the status of the partition reassignments operation

      When at least one of the two has a failed status, the broker removal operation is considered failed. The user is expected to retry the removal via #removeBrokers(List).

      When both have a completed status, the broker removal operation is considered a success.

      Parameters:
      options - The options to use when describing the broker removals.
      Returns:
      The DescribeBrokerRemovalResult.

    • describeBrokerAdditions

      @Confluent default DescribeBrokerAdditionsResult describeBrokerAdditions()
      Describes all the broker additions in the cluster.

      This is a convenience method for describeBrokerAdditions(DescribeBrokerAdditionsOptions) with default options. See the overload for more details.

      Returns:
      The DescribeBrokerAdditionsResult

    • describeBrokerAdditions

      @Confluent DescribeBrokerAdditionsResult describeBrokerAdditions(DescribeBrokerAdditionsOptions options)
      Describes all the broker additions in the cluster.

      Note that broker additions can be interrupted by subsequent higher-priority operations (e.g broker removal operations, even if operating on different brokers).

      A broker addition's partition reassignment task can be in one of multiple statuses: 1. PartitionReassignmentsStatus.ERROR - when the broker addition operation failed midway 2. PartitionReassignmentsStatus.PENDING - when the intent of addition is registered but the balancer is yet to start on it (e.g still collecting metrics) 3. PartitionReassignmentsStatus.CANCELED - when the addition is canceled (e.g due to a higher priority operation coming through) 4. PartitionReassignmentsStatus.IN_PROGRESS - when the addition is in progress (replicas are being reassigned) 5. PartitionReassignmentsStatus.COMPLETED - when the broker has successfully been added to the cluster

      The operation's status is also exposed through the general #BalancerOperationStatus, which can be in one of the following statuses: 1. #BalancerOperationStatus.FAILED - when the operation has ceased before completing due to an external influence canceling it or an internal error failing it. 2. #BalancerOperationStatus.IN_PROGRESS - when the intent of the operation is registered and is in the process of being completed. 3. #BalancerOperationStatus.SUCCESS - when the balancer operation has completed successfully.

      Additionally, each broker addition exposes a #BrokerAdditionDescription.additionError() that provides additional context regarding the reason the operation is in the given status

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DescribeBrokerAdditionsResult:

      Parameters:
      options - The options to use when describing the broker additions
      Returns:
      The DescribeBrokerAdditionsResult

    • describeBalancerStatus

      @Confluent default DescribeBalancerStatusResult describeBalancerStatus()
      Describes status of Confluent Balancer component.

      This is a convenience method for describeBalancerStatus(DescribeBalancerStatusOptions) with default options. See the overload for more details.

      Returns:
      The DescribeBalancerStatusResult

    • describeBalancerStatus

      @Confluent DescribeBalancerStatusResult describeBalancerStatus(DescribeBalancerStatusOptions options)
      Describes status of confluent balancer component. The Confluent Balancer can have one of the state from BalancerStatus.

      In addition to the status field, the #BalancerStatusDescription.balancerOperationError() gives context about the status of the balancer, e.g. why the balancer is in error state etc.

      The following exceptions can be anticipated when calling get() on the future obtained from the returned DescribeBalancerStatusResult:

      Parameters:
      options - The options to use when fetching the balancer status.
      Returns:
      The DescribeBalancerStatusResult

    • triggerEvenClusterLoad

      @Confluent default TriggerEvenClusterLoadResult triggerEvenClusterLoad()
      Triggers the even cluster load operation. See the overload for more details. It is suggested that the user tracks it via describeEvenClusterLoadStatus()
      Returns:
      The result of the even cluster load request whether it was accepted or denied.

    • triggerEvenClusterLoad

      @Confluent default TriggerEvenClusterLoadResult triggerEvenClusterLoad(List<String> goalList)
      Triggers the even cluster load operation. See the overload for more details. It is suggested that the user tracks it via describeEvenClusterLoadStatus()
      Parameters:
      goalList - The list of goals to use for manual rebalance, or an empty list for default goals
      Returns:
      The result of the even cluster load request whether it was accepted or denied.

    • triggerEvenClusterLoad

      @Confluent TriggerEvenClusterLoadResult triggerEvenClusterLoad(List<String> goalList, TriggerEvenClusterLoadOptions options)
      Triggers the even cluster load operation.

      If ConfluentConfigs.BALANCER_AUTO_HEAL_MODE_CONFIG is configured to ConfluentConfigs.BalancerSelfHealMode.ANY_UNEVEN_LOAD, then Confluent Balancer is continuously monitoring the cluster and determining whether it can improve the balance of the cluster's load. This API helps manually trigger the operation.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned TriggerEvenClusterLoadResult:

    • ClusterAuthorizationException If we didn't have sufficient permission to request rebalance. The request would not be started.
    • TimeoutException If the request timed out as no response was received from the controller, possible reasons could be request was faulted or response being dropped due to some network issue etc. The status of the even cluster load is unknown in this case.
    • BalancerOfflineException If the Confluent Balancer component is disabled or not started yet. Query its status with describeBalancerStatus() for more information
    • BalancerLoadError If the Confluent Balancer component failed to load. Query its status with describeBalancerStatus() for more information
    • BrokerRemovalInProgressException If a broker removal operation is in progress.
    • BrokerAdditionInProgressException If a broker addition operation is in progress.
    • EvenClusterLoadTaskInProgressException If an even cluster load operation is already in progress.
      • Parameters:
      goalList - The list of goals to use for manual rebalance, or an empty list for default goals
      options - The options to use for the request.
      Returns:
      The result of the even cluster load request whether it was accepted or denied.

    • computeEvenClusterLoadPlan

      @Confluent default ComputeEvenClusterLoadPlanResult computeEvenClusterLoadPlan()
      Compute even cluster load plan for the cluster. See the overload for more details. This API returns plan based on the rebalance goals.
      Returns:
      The result of even cluster load plan computation.

    • computeEvenClusterLoadPlan

      @Confluent default ComputeEvenClusterLoadPlanResult computeEvenClusterLoadPlan(List<String> goalList)
      Compute even cluster load plan for the cluster. See the overload for more details. This API returns plan based on the rebalance goals.
      Parameters:
      goalList - The list of goals to use for manual rebalance, or an empty list for default goals
      Returns:
      The result of even cluster load plan computation.

    • computeEvenClusterLoadPlan

      @Confluent ComputeEvenClusterLoadPlanResult computeEvenClusterLoadPlan(List<String> goalList, ComputeEvenClusterLoadPlanOptions evenClusterLoadPlanOptions)
      Compute and return an even cluster load plan for the cluster based on the rebalance goals.

      The following exceptions can be anticipated for when calling get() on the futures obtained from the returned ComputeEvenClusterLoadPlanResult:

    • ClusterAuthorizationException If we didn't have sufficient permission to request rebalance plan. The request would not be started.
    • TimeoutException If the request timed out as no response was received from the controller, possible reasons could be request was faulted or response being dropped due to some network issue etc.
    • BalancerOfflineException If the Confluent Balancer component is disabled or not started yet. Query its status with describeBalancerStatus() for more information.
    • BalancerLoadError If the Confluent Balancer component failed to load. Query its status with describeBalancerStatus() for more information.
    • BrokerRemovalInProgressException If a broker removal operation is in progress.
    • BrokerAdditionInProgressException If a broker addition operation is in progress.
    • EvenClusterLoadTaskInProgressException If an even cluster load operation is in progress.
    • BrokerFailureFixInProgressException If there's an ongoing broker failure anomaly fix.
    • RebalancePlanComputationException If there's an issue with SBC's plan computation process.
      • Parameters:
      goalList - The list of goals to use for manual rebalance, or an empty list for default goals
      evenClusterLoadPlanOptions - The options to use for the request.
      Returns:
      The result of the even cluster load plan computation.

    • describeEvenClusterLoadStatus

      @Confluent default DescribeEvenClusterLoadStatusResult describeEvenClusterLoadStatus()
      Describe the status of the even cluster load operation.

      This is a convenience method for describeEvenClusterLoadStatus(DescribeEvenClusterLoadStatusOptions) with default options. See the overload for more details.

      Returns:
      The DescribeEvenClusterLoadStatusResult

    • describeEvenClusterLoadStatus

      @Confluent DescribeEvenClusterLoadStatusResult describeEvenClusterLoadStatus(DescribeEvenClusterLoadStatusOptions options)
      Describe the status of the even cluster load operation.

      If enabled, Confluent Balancer is continuously monitoring the cluster and determining whether it can improve the balance of the cluster's load. This API helps describe the status of the operation.

      The following exceptions can be anticipated when calling get() on the future obtained from the returned DescribeEvenClusterLoadStatusResult:

      Parameters:
      options - The options to use when fetching the even cluster load status.
      Returns:
      The DescribeEvenClusterLoadStatusResult

    • alterBrokerReplicaExclusions

      @Confluent AlterBrokerReplicaExclusionsResult alterBrokerReplicaExclusions(Map<Integer,ExclusionOp> operations, AlterBrokerReplicaExclusionsOptions options)
      Alters the broker replica exclusions in the cluster. A replica exclusion on a broker ensures that the broker is prohibited from having any new replicas placed on it (be it from partition creation or reassignment).

      Updates are atomic, meaning that the call will either succeed for all ExclusionOps or fail for all.

      The following exceptions can be anticipated when calling get() on the future obtained from the returned AlterBrokerReplicaExclusionsResult:

      Parameters:
      operations - a map of broker ID to the desired ExclusionOp to be performed on that broker.
      options - The options to use when altering the broker replica exclusions.
      Returns:
      The AlterBrokerReplicaExclusionsResult consisting of the attempted broker replica exclusions.

    • alterBrokerReplicaExclusions

      @Confluent default AlterBrokerReplicaExclusionsResult alterBrokerReplicaExclusions(Map<Integer,ExclusionOp> operations)
      Alters the broker replica exclusions in the cluster. A replica exclusion on a broker ensures that the broker is prohibited from having any new replicas placed on it (be it from partition creation or reassignment).

      Updates are atomic, meaning that the call will either succeed for all ExclusionOps or fail for all.

      This is a convenience method for alterBrokerReplicaExclusions(Map, AlterBrokerReplicaExclusionsOptions) with default options. See the overload for more details.

      Parameters:
      operations - a map of broker ID to the desired ExclusionOp to be performed on that broker.
      Returns:
      The AlterBrokerReplicaExclusionsResult consisting of the attempted broker replica exclusions.

    • describeBrokerReplicaExclusions

      @Confluent DescribeBrokerReplicaExclusionsResult describeBrokerReplicaExclusions(DescribeBrokerReplicaExclusionsOptions options)
      Describes the active broker replica exclusions in the cluster. An active replica exclusion on a broker ensures that the broker is prohibited from having any new replicas placed on it (be it from partition creation or reassignment).

      The following exceptions can be anticipated when calling get() on the future obtained from the returned DescribeBrokerReplicaExclusionsResult:

      Parameters:
      options - The options to use when describing the broker replica exclusions.
      Returns:
      The DescribeBrokerReplicaExclusionsResult consisting of the successfully-altered broker replica exclusions.

    • describeBrokerReplicaExclusions

      @Confluent default DescribeBrokerReplicaExclusionsResult describeBrokerReplicaExclusions()
      Describes the active broker replica exclusions in the cluster. An active replica exclusion on a broker ensures that the broker is prohibited from having any new replicas placed on it (be it from partition creation or reassignment).

      This is a convenience method for describeBrokerRemovals(DescribeBrokerRemovalsOptions) with default options. See the overload for more details.

      Returns:
      The DescribeBrokerReplicaExclusionsResult consisting of the successfully-altered broker replica exclusions.

    • createClusterLinks

      @Confluent CreateClusterLinksResult createClusterLinks(Collection<NewClusterLink> clusterLinks, CreateClusterLinksOptions options)
      Creates links to remote clusters with the specified configurations for performing inter-cluster communications. Once established, the cluster links can referenced by their link names for issuing requests. The following exceptions can be anticipated when calling get() on the futures obtained from the returned CreateClusterLinksResult:
      Parameters:
      clusterLinks - The cluster links to create.
      options - The options to use when creating the cluster links.
      Returns:
      The CreateClusterLinksResult.

    • listClusterLinks

      @Confluent ListClusterLinksResult listClusterLinks(ListClusterLinksOptions options)
      Lists the cluster links.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned ListClusterLinksResult:

      Parameters:
      options - The options to use when listing the cluster links.
      Returns:
      The ListClusterLinksResult.

    • deleteClusterLinks

      @Confluent DeleteClusterLinksResult deleteClusterLinks(Collection<String> linkNames, DeleteClusterLinksOptions options)
      Deletes established links to remote clusters with the provided link names.

      Deleting a cluster link does not affect the cluster link's data in any way.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DeleteClusterLinksResult:

      Parameters:
      linkNames - The names of the cluster links to delete.
      options - The options to use when deleting the cluster links.
      Returns:
      The DeleteClusterLinksResult.

    • alterMirrors

      @Confluent AlterMirrorsResult alterMirrors(Map<String,AlterMirrorOp> ops, AlterMirrorsOptions options)
      Performs a state alteration for topic mirroring. Used only for operations on mirror topics.

      The future of the individual alter mirror ops should be used for obtaining the result.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned AlterMirrorsResult:

      Parameters:
      ops - The mirror alteration operation for each topic.
      options - The options to use when altering mirrors.
      Returns:
      The AlterMirrorsResult.

    • listMirrors

      @Confluent ListMirrorsResult listMirrors(ListMirrorsOptions options)
      Lists the mirrored topics, i.e. topics that are mirrors of another over a cluster link.

      The following exceptions can be anticipated when calling get() on the future obtained from the returned ListMirrorsResult:

      Parameters:
      options - The options to use when listing mirrors.
      Returns:
      The ListMirrorsResult.

    • describeMirrors

      @Confluent DescribeMirrorsResult describeMirrors(Collection<String> topics, DescribeMirrorsOptions options)
      Describes the state of mirrored topics, i.e. topics that are mirrors of another over a cluster link.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DescribeMirrorsResult:

      Parameters:
      options - The options to use when describing mirrors.
      Returns:
      The DescribeMirrorsResult.

    • alterLeadershipPriority

      @Confluent AlterLeadershipPriorityResult alterLeadershipPriority(AlterLeadershipPrioritySpec spec, AlterLeadershipPriorityOptions options)
      Change broker leadership priority by promoting / demoting a list of brokerIds for a given reason.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned AlterLeadershipPriorityResult:

      Parameters:
      spec - The request arguments for changing leadership priority request.
      options - The options to use when changing leadership priority.
      Returns:
      The AlterLeadershipPriorityResult.

    • describeLeadershipPriority

      @Confluent DescribeLeadershipPriorityResult describeLeadershipPriority(DescribeLeadershipPriorityOptions options)
      Describe all brokers with demoted leadership priority and their list of reasons for demotion.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DescribeLeadershipPriorityResult:

      Parameters:
      options - The options to use when describing leadership priority.
      Returns:
      The DescribeLeadershipPriorityResult.

    • describeClusterLinks

      @Confluent DescribeClusterLinksResult describeClusterLinks(DescribeClusterLinksOptions options)
      Describe the cluster links.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DescribeClusterLinksResult:

      Parameters:
      options - The options to use when describing the cluster links. When no link name is provided, all the cluster links descriptions will be returned.
      Returns:
      The DescribeClusterLinksResult.

    • resolveOffsetRange

      @Confluent ResolveOffsetRangeResult resolveOffsetRange(Map<TopicIdAndPartition,ResolveOffsetRangeSpec> topicPartitionOffsets, ResolveOffsetRangeOptions options)

    • describeSwitchoverStatus

      @Confluent DescribeSwitchoverStatusResult describeSwitchoverStatus(String linkName)
      Describe the cluster link switchover status.

      The following exceptions can be anticipated when calling get() on the futures obtained from the returned DescribeSwitchoverStatusResult:

      Parameters:
      linkName - The link name of the cluster
      Returns:
      The DescribeSwitchoverStatusResult.