WL#16904: AdminAPI: Reset ReplicaSet and ClusterSet Internal Replication Account Passwords

Affects: Server-9.x   —   Status: Complete

BACKGROUND

The operation:

  • Cluster.reset_recovery_accounts_password()

allows DBAs to rotate internal recovery accounts used by InnoDB Cluster. Over time, its behavior was extended to also rotate replication accounts used by Read Replica instances.

However:

  • The name no longer accurately reflects its behavior.
  • The operation is available only for InnoDB Cluster.
  • ReplicaSet and ClusterSet do not provide an equivalent mechanism.

As AdminAPI manages multiple MySQL architectures (Cluster, ReplicaSet, ClusterSet), replication account management should be consistently supported across all topologies.

MOTIVATION

Credential rotation for internal replication accounts is required for:

  • Security best practices and periodic password rotation
  • Compliance with password lifetime policies
  • Incident response after credential compromise
  • Operational consistency across AdminAPI-managed architectures

Additionally, the current function name is misleading, as it rotates more than just recovery accounts.

A unified and accurately named API is required.

USER-STORIES

  • As a DBA, I want to rotate the passwords of all internal Cluster replication accounts through a single command.

  • As a DBA, I want to rotate the passwords of all internal ReplicaSet replication accounts through a single command.

  • As a DBA, I want to rotate the passwords of all internal ClusterSet replication accounts through a single command.

SUMMARY

This WL introduces a unified API for resetting internal replication account passwords across all AdminAPI topologies.

The following changes are introduced:

1. Deprecation

The operation:

  • cluster.reset_recovery_accounts_password()

is deprecated. It remains available during the deprecation period and emits a warning.

2. The following operations are introduced:

  • Cluster.reset_replication_accounts_password([options])
  • ReplicaSet.reset_replication_accounts_password([options])
  • ClusterSet.reset_replication_accounts_password([options])

Functional Requirements

  • FR1: The function cluster.reset_recovery_accounts_password() must be marked as deprecated and emit a deprecation warning that clearly instructs users to migrate to cluster.reset_replication_accounts_password().

  • FR2: A new function cluster.reset_replication_accounts_password() must be introduced and must preserve the behavior and execution semantics of cluster.reset_recovery_accounts_password().

    • FR2.1: When executed on a Cluster that belongs to a ClusterSet, cluster.reset_replication_accounts_password() must fail and instruct the user to execute the ClusterSet equivalent instead.

  • FR3: A new function replicaset.reset_replication_accounts_password() must be introduced to rotate all AdminAPI-managed internal replication accounts used by a ReplicaSet.

    • FR3.1: The function must abort and error out if the ReplicaSet status is different from AVAILABLE or AVAILABLE_PARTIAL.

  • FR4: A new function clusterset.reset_replication_accounts_password() must be introduced to rotate all AdminAPI-managed internal replication accounts used within a ClusterSet, including:

    • The AdminAPI-managed internal replication accounts of each individual Cluster that is part of the ClusterSet (same scope as cluster.reset_replication_accounts_password()), for eligible clusters.

    • The AdminAPI-managed replication accounts used by the ClusterSet replication channel between the Primary Cluster and each Replica Cluster.

    • FR4.1: The function must skip Clusters with global-status INVALIDATED. No password rotation or replication credential updates shall be attempted for INVALIDATED clusters, regardless of the force option.

    • FR4.2: The function must abort and error out if any required Cluster (Primary or Replica) has a global-status different from OK, except for clusters skipped under FR4.1.

    • FR4.3: When rotating ClusterSet replication credentials for a Replica Cluster, the operation must first synchronize replication on that Replica Cluster up to a consistent point before applying any credential changes for the ClusterSet replication channel, in order to minimize additional replication lag.

  • FR5: All new functions must:

    • Generate new random passwords.
    • Update replication channel credentials accordingly.
    • Abort by default if any required instance is not reachable (OFFLINE, UNREACHABLE, or (MISSING)).
    • Abort if any required instance is in a state where changing replication credentials is not permitted (RECOVERING or ERROR).
    • Accept an optional force option, following the same semantics as the existing Cluster implementation.

Non-Functional Requirements

  • NFR1: The new Cluster operation must not introduce behavior changes beyond renaming and deprecation.

  • NFR2: Backward compatibility shall be preserved during the deprecation period.

  • NFR3: The operations shall not expose generated passwords in logs or output.

Deprecated Operation

  • cluster.reset_recovery_accounts_password([options])

    • Marked as deprecated.
    • Emits a warning.
    • Internally delegates to:

  • cluster.reset_replication_accounts_password([options])

    • Behavior remains identical.

New Unified Operations

  • cluster.reset_replication_accounts_password([options])
  • replicaset.reset_replication_accounts_password([options])
  • clusterset.reset_replication_accounts_password([options])

Common Syntax

    NAME
          reset_replication_accounts_password - Resets the passwords for all AdminAPI-managed internal replication accounts used by the target topology

    SYNTAX
          <Topology>.reset_replication_accounts_password([options])

    WHERE
          options: Dictionary with options for the operation.

    RETURNS
          Nothing.

    DESCRIPTION

    Resets the passwords for all AdminAPI-managed internal replication
    accounts used by the target topology and updates the corresponding
    replication channel credentials.

    New passwords are generated using the same password generation
    mechanism used by the AdminAPI when creating internal replication
    accounts.

    This function can be used:

      - Periodically, to comply with password lifetime policies.
      - After a security event.
      - Whenever internal replication credentials must be rotated.

    Only replication accounts created and managed by the AdminAPI are affected.

    Execution constraints:

    - The operation aborts by default if any required instance is not reachable (e.g., OFFLINE, UNREACHABLE, or MISSING).

    - The operation aborts if any required instance is in RECOVERING or ERROR state.

    - For ClusterSet deployments, the operation aborts if any required  Cluster has globalStatus different from OK. Clusters with globalStatus = INVALIDATED are skipped and are not modified.

    The options dictionary may contain the following attribute:

    - force: boolean, indicating that the operation will continue when some required instances are not reachable. Instances that cannot be reached are skipped and reported.

    The force option does not override topology-level safety constraints (e.g., globalStatus != OK) or instance-level unsafe states (RECOVERING or ERROR).

    The use of the force option is not recommended unless instances are permanently unavailable.

Topology Scope and Execution Rules

Cluster Belonging to a ClusterSet

When cluster.reset_replication_accounts_password() is executed on a Cluster that belongs to a ClusterSet, the operation must fail.

Rationale:

  • In a ClusterSet deployment, replication accounts between clusters are managed at the ClusterSet level.
  • Rotating replication credentials at the Cluster level would not be sufficient and could result in inconsistent state.
  • ClusterSet is the authoritative topology object for cross-cluster replication.

Behavior:

  • The command must detect that the Cluster is part of a ClusterSet.
  • The operation must abort before performing any changes.

  • The error message must instruct the user to execute:

    • clusterset.reset_replication_accounts_password()

This guarantees:

  • Correct operational boundaries.
  • Prevention of partial credential rotation.
  • Clear user guidance.

Topology-Specific Behavior

InnoDB Cluster

cluster.reset_replication_accounts_password() rotates:

  • AdminAPI-managed internal recovery accounts used by Group Replication.
  • AdminAPI-managed replication accounts used by Read Replica instances (if any).

The operation applies to all ONLINE instances in the Cluster, following the same semantics as the existing Cluster implementation.

If the Cluster belongs to a ClusterSet, the operation fails.

InnoDB ReplicaSet

replicaset.reset_replication_accounts_password():

  • Rotates all AdminAPI-managed internal replication accounts used by all members of the ReplicaSet.
  • Updates the replication channel credentials for each member.
  • Applies to all ONLINE members by default.
  • Aborts if required members are not reachable, unless force=true.

InnoDB ClusterSet

clusterset.reset_replication_accounts_password():

  • Rotates the AdminAPI-managed internal replication accounts of each eligible Cluster in the ClusterSet (same scope as cluster.reset_replication_accounts_password()).
  • Rotates the AdminAPI-managed replication accounts used for the ClusterSet replication channel between the Primary Cluster and each eligible Replica Cluster.
  • Skips Clusters with globalStatus = INVALIDATED.
  • Aborts if any required Cluster has globalStatus != OK. This condition is not overridden by the force option.
  • For each eligible Replica Cluster, synchronizes replication before applying any credential changes on that Replica Cluster.
  • Aborts if any required Cluster or instance is not reachable, unless force=true.

Execution Semantics and Failure Handling

The password rotation operations are not undoable.

Once a password change has been successfully applied to a given instance or cluster, the previous password cannot be automatically restored by the AdminAPI.

In case of an unexpected failure during execution (e.g. a network interruption or a member becoming unreachable), the operation may be safely re-executed.

Re-execution will:

  • Detect the current replication accounts in use.
  • Generate new passwords as needed.
  • Apply the required credential updates to instances that were not successfully updated in the previous attempt.

The operations are therefore retryable but not transactional.

No automatic rollback mechanism is provided.



Copyright (c) 2000, 2026, Oracle Corporation and/or its affiliates. All rights reserved.