Skip to content

docs: update staged update docs with resource creation change #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
britaniar merged 3 commits into from
Mar 4, 2026
Merged

docs: update staged update docs with resource creation change #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
359342b
update docs with resource creation change"
britaniar Feb 26, 2026
9dae98e
address comments
britaniar Mar 4, 2026
3edeb7a
Merge branch 'main' into updateStagedUpdateDocs
ryanzhang-oss Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions content/en/docs/concepts/staged-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,7 @@ metadata:
name: example-run
spec:
placementName: example-placement # Required: Name of Target ClusterResourcePlacement
resourceSnapshotIndex: "0" # Optional: Resource version (omit for latest)
resourceSnapshotIndex: "0" # Optional: Resource version (omit to use the latest snapshot, creating one if it does not already exist)
stagedRolloutStrategyName: example-strategy # Required: Name of the strategy to execute
state: Run # Optional: Initialize (default), Run, or Stop
```
Expand All @@ -317,12 +317,12 @@ metadata:
namespace: my-app-namespace
spec:
placementName: example-namespace-placement # Required: Name of target ResourcePlacement. The StagedUpdateRun must be created in the same namespace as the ResourcePlacement
resourceSnapshotIndex: "5" # Optional: Resource version (omit for latest)
resourceSnapshotIndex: "5" # Optional: Resource version (omit to use the latest snapshot, creating one if it does not already exist)
stagedRolloutStrategyName: app-rollout-strategy # Required: Name of the strategy to execute. Must be in the same namespace
state: Initialize # Optional: Initialize (default), Run, or Stop
```

**Using Latest Resource Snapshot:**
**Creating Latest Resource Snapshot:**

```yaml
apiVersion: placement.kubernetes-fleet.io/v1beta1
Expand All @@ -331,7 +331,7 @@ metadata:
name: example-run-latest
spec:
placementName: example-placement
# resourceSnapshotIndex omitted - system uses latest snapshot automatically
# resourceSnapshotIndex omitted - system uses the latest snapshot (creates one if it does not already exist)
stagedRolloutStrategyName: example-strategy
state: Run
```
Expand Down Expand Up @@ -375,7 +375,7 @@ kubectl patch csur example-run --type='merge' -p '{"spec":{"state":"Run"}}'

UpdateRuns execute in three phases:

1. **Initialization**: Validates placement, captures latest strategy snapshot, collects target bindings, generates cluster update sequence, captures specified resource snapshot or latest resource snapshot if unspecified & records override snapshots. Occurs once on creation when state is `Initialize`, `Run` or `Stop`.
1. **Initialization**: Validates placement, captures latest strategy snapshot, collects target bindings, generates cluster update sequence, uses the specified resource snapshot or the latest snapshot (creating one if it does not already exist) if unspecified & records override snapshots. Occurs once on creation when state is `Initialize`, `Run` or `Stop`.
2. **Execution**: Processes stages sequentially, updates clusters within each stage (respecting maxConcurrency), enforces before-stage and after-stage tasks. Only occurs when state is `Run`
3. **Stopping/Stopped** When state is `Stop`, the updateRun pauses execution at the current cluster/stage and can be resumed by changing state back to `Run`. If there are updating/deleting clusters we wait after marking updateRun as `Stopping` for the in-progress clusters to reach a deterministic state: succeeded, failed or stuck before marking updateRun as `Stopped`

Expand Down Expand Up @@ -434,7 +434,9 @@ UpdateRuns serve as the trigger that initiates rollouts for their respective pla

### Before an UpdateRun is Created

When you create a Placement with `strategy.type: External`, the system schedules which clusters should receive the resources, but **does not deploy anything yet**. The Placement remains in a scheduled but not available state, waiting for an UpdateRun to trigger the actual rollout.
When you create a Placement with `spec.strategy.type: External`, the system schedules which clusters should receive the resources, but **does not deploy anything yet**. The Placement remains in a scheduled but not available state, waiting for an UpdateRun to trigger the actual rollout.

> **Note:** Resource snapshots are not automatically created for placements with `spec.strategy.type: External`. If you create a new placement directly with `External` strategy, you must omit the `resourceSnapshotIndex` field in your UpdateRun spec to have the system create a new snapshot during initialization.

### After an UpdateRun is Created

Expand Down
Loading