Copying a name is not copying a stable version
Cloud Storage objects have generation identifiers. If a source object changes during a migration, copying its name without recording the intended generation can produce an inconsistent destination. Likewise, retrying a destination write without a precondition can overwrite a newer object that another process created.
The rewrite API handles copies that may require several requests. A response can report that work is incomplete and provide a rewrite token for continuation. The migration must keep following the supported continuation until completion, not treat the first successful HTTP response as a finished object. Tokens have documented lifetime limits, so durable migration state needs enough information to restart deliberately if a continuation expires.
Prepare source and destination inventory access, an approved destination namespace, a migration identity, and a rollback route for consumers. Record required metadata, storage class, encryption, and retention behavior. Use a small test population before any broad production copy. This procedure does not require deleting source objects.
Build a verifiable copy unit
- Inspect each selected source with
gcloud storage objects describe gs://SOURCE_BUCKET/OBJECT_NAME. Build a manifest containing object name, generation, size, available checksum, and relevant metadata. If writes continue, define whether the migration captures a fixed inventory or follows a documented later-delta process. - Choose destination preconditions. For an object that must not already exist, use the supported generation-match value for nonexistence. For an approved replacement, match the expected destination generation. Use source-generation conditions to prevent silently copying a changed source. A precondition failure is evidence to reconcile, not a reason to remove safeguards automatically.
- Execute the copy through a supported library or rewrite workflow. Persist progress, continuation tokens where relevant, source identity, and completion state. Continue until the API reports completion. Make retries conditional on the same intended source and destination contract.
- Verify destination content and metadata against the manifest. Use the appropriate available checksum, size, and application read tests; do not assume every object exposes the same checksum fields. Reconcile missing, failed, changed, and intentionally excluded objects before switching consumers.
Illustrative scenario
A hypothetical archive migration copies daily manifests while a producer can replace the current day's object. A naive retry copies the newer source over a destination that was already validated against the older file. The corrected workflow pins source generations and rejects unexpected destination changes. The changed object becomes an explicit reconciliation item, allowing the team to choose the intended version instead of silently mixing states.
| Evidence | Meaning | Correct response |
|---|---|---|
| Rewrite returns incomplete status | Multi-request copy still active | Continue with its supported token |
| Precondition fails | Source or destination changed | Reconcile the recorded generation |
| Size matches, consumer fails | Metadata or content contract differs | Compare checksum and application behavior |
| Token no longer works | Continuation expired or invalid | Restart from recorded state deliberately |
Verify cutover independently
Read representative destination objects through the same client path consumers will use. Confirm IAM, content type, cache metadata, encryption access, and retention expectations. Switch a controlled consumer first and monitor errors. Retain the source until the approved acceptance and rollback window ends; a completed copy is not authorization to erase the original dataset.
Operating procedure
Monitor manifest completion, precondition failures, retry age, and destination validation failures. Keep migration logs free of signed URLs or customer payloads. Require explicit reconciliation of every unresolved object before final acceptance. Store the source-generation mapping with the migration record so later investigators can explain exactly which version was copied.
Explore Clouvenix cloud architecture for implementation and operational handover.