Skip to content

feat(mongodb-runner): add configShard option for sharded clusters - #963

Open
autarch wants to merge 1 commit into
mainfrom
11-05-mongodb-runner_config-shard-topology
Open

autarch wants to merge 1 commit into
mainfrom
11-05-mongodb-runner_config-shard-topology

Conversation

@autarch

@autarch autarch commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Description

This adds a new configShard option to mongodb-runner for the sharded topology. If it's set, then after the cluster is up and shards are added, the runner runs transitionFromDedicatedConfigServer through mongos, waits until the config server appears in listShards (so start returns with the topology fully usable), and serializes configShard: true so start --json and ls --json report it.

Open Questions

None

Checklist

@autarch
autarch requested review from a team as code owners November 5, 2026 21:23
@autarch
autarch requested review from esvm and a balanced review from Copilot November 5, 2026 21:23
@autarch
autarch marked this pull request as draft November 5, 2026 21:28
@autarch
autarch removed the request for review from esvm November 5, 2026 21:28
@autarch

autarch commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

Doh, this should've been a draft.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The temporary authentication account can be deleted without a replacement, blocking administrator bootstrapping, and the readiness request can hang indefinitely without a client-side timeout.

2 open issues
What changed in this PR

Adds optional config shards to mongodb-runner’s sharded clusters, allowing callers to delegate the transition and readiness checks to the runner.

Changes:

  • Adds configShard CLI and programmatic options, validation, and serialized state.
  • Implements the transition, readiness polling, and temporary-user handling for authenticated clusters.
  • Adds integration tests and usage documentation.
File Description
packages/​mongodb-runner/​src/​mongoserver.ts Exposes keyfile contents for authentication detection.
packages/​mongodb-runner/​src/​mongocluster.ts Implements config-shard startup, authentication handling, and serialization.
packages/​mongodb-runner/​src/​mongocluster.spec.ts Tests transitions, authenticated startup, serialization, and topology validation.
packages/​mongodb-runner/​src/​cli.ts Adds the --configShard option.
packages/​mongodb-runner/​src/​cli.spec.ts Tests CLI startup and ls --json reporting.
packages/​mongodb-runner/​README.md Documents config-shard usage and requirements.

Review effort: Balanced

autarch added a commit that referenced this pull request Nov 5, 2026
Review follow-ups on #963:

- On clusters that enforce authentication, configShard now requires at
  least one configured user. Without one, the temporary transition user
  would have been the only account on the cluster, and dropping it after
  the transition would leave no users and a permanently closed localhost
  exception, locking out any administrator bootstrap.
- The transition/readiness clients now set a client-side timeoutMS so a
  mongos that stops responding cannot hang start() indefinitely
  (maxTimeMS only bounds server-side execution).
autarch added a commit that referenced this pull request Nov 6, 2026
Review follow-ups on #963:

- On clusters that enforce authentication, configShard now requires at
  least one configured user. Without one, the temporary transition user
  would have been the only account on the cluster, and dropping it after
  the transition would leave no users and a permanently closed localhost
  exception, locking out any administrator bootstrap.
- The transition/readiness clients now set a client-side timeoutMS so a
  mongos that stops responding cannot hang start() indefinitely
  (maxTimeMS only bounds server-side execution).
@autarch
autarch force-pushed the 11-05-mongodb-runner_config-shard-topology branch from 7e34847 to a5df849 Compare November 6, 2026 21:46
autarch added a commit that referenced this pull request Nov 9, 2026
Review follow-ups on #963:

- On clusters that enforce authentication, configShard now requires at
  least one configured user. Without one, the temporary transition user
  would have been the only account on the cluster, and dropping it after
  the transition would leave no users and a permanently closed localhost
  exception, locking out any administrator bootstrap.
- The transition/readiness clients now set a client-side timeoutMS so a
  mongos that stops responding cannot hang start() indefinitely
  (maxTimeMS only bounds server-side execution).
@autarch
autarch force-pushed the 11-05-mongodb-runner_config-shard-topology branch from a5df849 to b2c1f2d Compare November 9, 2026 15:59
Passing --configShard (or configShard: true in the config file /
programmatic options) turns the config server replica set into a config
shard once the cluster is up, by running
transitionFromDedicatedConfigServer through mongos. start waits until the
transition completes (the config server appears in listShards), and ls
--json and start --json report configShard: true for such clusters, so
consumers can distinguish a config shard from a dedicated config server
without connecting.

This is the topology mongosync's test clusters previously built by
running the transition themselves after mongodb-runner finished
(REP-8055).

Details, verified empirically:

- transitionFromDedicatedConfigServer requires MongoDB 8.0 or newer (it
  existed briefly in 5.0 and is absent from 6.0.x and 7.0.x binaries),
  so the option is rejected with a clear error for other versions, for
  the standalone and replset topologies, and in the option docs, CLI
  help, and README.
- The localhost exception does not permit the transition, and __system
  cannot authenticate through mongos without enableTestCommands. On
  clusters that enforce authentication (keyfile or --auth), the runner
  therefore creates a temporary root user through the localhost
  exception, runs the transition and readiness poll as that user, and
  creates the cluster's own users as it (the localhost exception closes
  once any user exists and does not reopen after a drop) before dropping
  it.
- configShard requires at least one configured user on clusters that
  enforce authentication: without one, the temporary transition user
  would be the only account on the cluster, and dropping it would leave
  no users and a permanently closed localhost exception, locking out any
  administrator bootstrap.
- The transition and readiness-poll clients set a client-side timeoutMS,
  and each listShards poll is bounded by maxTimeMS from the remaining
  time budget, so a mongos that stops responding cannot hang start().

Tests cover the config shard topology and serialize round trip, config
shard with keyfile auth (asserting the temporary transition user is
removed and only the configured user remains), rejection with
authentication but no configured users, rejection for non-sharded
topologies, and CLI start --json / ls --json reporting.
@autarch
autarch force-pushed the 11-05-mongodb-runner_config-shard-topology branch from b2c1f2d to c208d69 Compare November 17, 2026 17:56
@autarch
autarch requested a balanced review from Copilot November 17, 2026 17:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the opt-in config shard support.

No open issues 🎉

2 resolved since last review

Review effort: Balanced

@autarch
autarch marked this pull request as ready for review November 17, 2026 18:32
@autarch
autarch requested a review from esvm November 17, 2026 20:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants