跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

Update a cell's configuration or addresses

loom cell update reserves a configuration before the cell accepts it. Run it with that cell’s stores, LOOM_CELL, and the router operator credential configured. It holds the cell’s ATTACH lock on one direct Postgres session. Prepare, attach, restore, another update, and the documented state cleanup cannot run concurrently. An interrupted command exits unsuccessfully; rerun the same action after correcting the reported cause.

Reserve a configuration

Write a nonsecret settings file:

version: 1
settings:
  tracker_org: operations
loom cell update --cell first --config target.yaml

The file overlays the CLI’s effective settings. Every supplied setting is validated, including values outside the fingerprint. Secret fields are refused. The command neither installs the file nor changes the running processes’ configuration. It prints fingerprint digests and changed field names.

The deployment id, registered public and OAuth host, and bucket and prefix cannot change. The root-secret fingerprint must match the directory’s locked value.

A SCIM-on target requires this cell’s valid SCIM token, OIDC login and required authentication. The CLI freshly checks active accounts, live refresh sessions and personal service-account creators against the target provisioning policy before claiming the directory generation, after durable local acceptance, and after participant turnover before releasing the reservation. It uses the same bounded provisioning census as attach; a cached admission decision does not establish this precondition. Run the CLI with the target’s SCIM credentials and authentication settings configured.

Provision every required identity before updating. Alternatively, add --revoke-unprovisioned to --config, --finish or --revert to end tokens issued before the update for subjects that cannot meet its SCIM policy. Accepted SCIM cutoffs are reported immediately and remain if a later check fails; the command does not roll them back. Correct the reported cause and rerun the same action. This flag does not apply to address refresh. Reverting to SCIM-off current does not require provisioning.

After attach has begun, the directory reserves both current and next values and places newly configured orgs before the cell’s Postgres accepts next. Overlap checks include both values of every other attached or attaching cell. A different pending value refuses. Repeating the identical candidate repairs an interrupted local write without placing an org twice.

New configured placements obey the cell’s closed flag and quota. Existing winners in that cell remain valid while closed or full. An org held elsewhere refuses the whole reservation. A later cell still attaching refuses configured-org changes; a first cell attaching after begin accepts them through the normal placement gate.

Before attach/begin has recorded the directory fingerprint, update claims the registration’s generation and changes only the local pair. It places no org and reserves no issuer or pattern. Attach checks and reserves both local values later.

Finish or revert

Install and roll out the reserved configuration, then run:

loom cell update --cell first --finish --wait 600

To keep current instead:

loom cell update --cell first --revert --wait 600

These forms first repair local tenancy for actual same-cell configured placements from both directory values. Their operator read compares the exact generation, registration, pair, and root-secret fingerprint, writes an audit and WAL fence, and waits for synchronous commit. Public lookup’s first-cell fallback is not proof that an immutable placement exists. A missing placement outside the attaching first cell requires directory metadata recovery.

Finalization durably narrows local acceptance first. The directory keeps both reservations until every participant captured by a complete post-cutoff census has permanently retired or its exact process is proved dead with no outstanding ClickHouse query. Captured target processes also turn over. A target-serving replacement must join a live instance, a marked cell heartbeat, and a guarded participant outside the captured set. A workers-only process cannot satisfy this.

Every configured ClickHouse replica must answer. Replicated participant tables synchronize after the local cutoff; the census unions their newest rows without age filters, sampling, caches, or partial-result limits. Heartbeat expiry, drained, a missing row, an empty query list alone, a request deadline, or deletion of a pod object does not prove permanent retirement. An uninspectable process or unreadable topology refuses finalization.

Online finalization requires the participant lifecycle baseline and controller fencing. Positively terminate or fence every legacy server, worker, one-off command and control writer, including paused boots, before using this protocol. Prevent old binaries from returning. Inventory actual process/container termination or independent node fencing; an expired heartbeat or missing API object is insufficient. The CLI cannot establish this external inventory from its census. Unknown legacy identities remain blockers. No command flag asserts or bypasses this prerequisite.

--wait is finite and between 0 and 86400 seconds. Zero still makes a bounded initial attempt. Local transactions and complete census reads have their own bounded attempts. If turnover times out, local acceptance stays single and the directory stays dual. Keep the target replacement serving, resolve the named participants and rerun the same action. Each rerun takes a fresh census. Retrying --config can widen local acceptance again and requires another cutoff and census before finalization. All directory placements and local tenancy rows remain after revert, including orgs introduced by the pending value.

Interruption Recorded state Recovery
Directory reservation commits before local write Directory dual; local pair may be old Repeat config, finish, or revert explicitly
Local cutoff commits before turnover or final directory commit Directory dual; local single Repeat the selected finish or revert
Generation or ATTACH backend changes An in-flight directory reply may be stale Stop; a fresh invocation claims again and recomputes
Final directory singleton already matches local Both single The no-op still proves synchronous local durability

Refresh addresses

For a later cell:

loom cell update --cell second --probe-url https://second-probe.example.test

For the first cell, roll out the intended LOOM_ROUTER_UPSTREAM_URL and LOOM_ROUTER_UPSTREAM_PROBE_URL to every router first, then run without an action flag:

loom cell update --cell first

The contacted router supplies its normalized first-cell addresses. The probe must echo fresh Postgres, ClickHouse, and configured bucket nonces and the registered deployment id, bucket and prefix. A main listener cannot substitute for the probe. The first cell’s main upstream must independently report that deployment id. The router rechecks its configured addresses at commit. A later refresh changes only its probe URL; it cannot move the registered host, stores or upstream.

A generation and address comparison excludes stale requests; it does not establish fleet-wide configuration agreement. An old router can read the current expected row and reverse the addresses if it still runs the old configuration. Keep the old endpoints reachable until every router demonstrably refreshes its routing table or restarts after the directory change. A configuration rollout alone does not flush cached routes. During a directory outage a router can keep its last routing table indefinitely. The command cannot certify all-router agreement.

Configuration actions, finish, revert and probe refresh are mutually exclusive. Probe readiness retries use --wait; invalid proofs refuse immediately. Nonce cleanup uses a value-qualified Postgres delete and a Keeper compare-and-delete. Bucket cleanup reads and compares this run’s value before an unconditional delete. If the ATTACH backend is lost, a successor can replace the object between that read and delete and lose its nonce. Rerun the affected proof; bucket cleanup does not guarantee preservation of a successor’s nonce.

这个页面有帮助吗?