Skip to content

Commit 6c6ff4e

Browse files
carlydfcarlydf
committed
reorder migration guide to emphasize simplicity
1 parent cc7a170 commit 6c6ff4e

2 files changed

Lines changed: 44 additions & 41 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ How to install and upgrade the Temporal Worker Controller Custom Resource Defini
3030
Technical constraints and limitations of the Temporal Worker Controller system, including maximum field lengths and other operational boundaries.
3131

3232
### [CRD Rename Migration Guide](migration-crd-rename.md)
33-
How to migrate from the deprecated `TemporalWorkerDeployment` and `TemporalConnection` CRDs to the new `WorkerDeployment` and `Connection` CRDs introduced in Chart Version v0.27.0 / App Version v1.7.0. Includes zero-downtime step-by-step migration instructions.
33+
How to migrate from the deprecated `TemporalWorkerDeployment` and `TemporalConnection` CRDs to the new `WorkerDeployment` and `Connection` CRDs introduced in Chart Version v0.27.0 / App Version v1.7.0.
3434

3535
### [Migration Guide](migration-to-versioned.md)
3636
Comprehensive guide for migrating from existing unversioned worker deployment systems to the Temporal Worker Controller. Includes step-by-step instructions, configuration mapping, and common patterns.

‎docs/migration-crd-rename.md‎

Lines changed: 43 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -15,47 +15,10 @@ In App Version v1.7, the old CRD kinds are **not actively managed**: new objects
1515
The `Temporal` prefix was redundant — all resources in the `temporal.io` API group are already scoped to Temporal. The shorter names are consistent with Kubernetes naming conventions and reduce verbosity in manifests and CLI commands.
1616
After this release, the Worker Controller will be Generally Available (GA), which means no more breaking changes will be introduced. We wanted to make this transition before GA, and make it as clean as possible.
1717

18-
## What happens to deprecated resources in App Version v1.7?
19-
Existing `TemporalWorkerDeployment` and `TemporalConnection` objects remain in your cluster but are no longer reconciled against Temporal server state. The controller will not manage worker versions, route traffic, or connect to Temporal on behalf of these resources. New resources of these kinds cannot be created.
20-
21-
The deprecated resources will have a `Ready=False` status condition set by a migration helper controller. The condition progresses through three states:
22-
23-
**Before migration** — if no `WorkerDeployment` with the same name exists:
24-
```
25-
Ready=False reason=Deprecated
26-
message: "TemporalWorkerDeployment is deprecated. Create a WorkerDeployment with the same name and spec to migrate."
27-
```
28-
29-
**Migration in progress** — a `WorkerDeployment` with the same name exists, and the controller is transferring ownership of child `Deployments` and `WorkerResourceTemplates` from the old owner to the new one:
30-
```
31-
Ready=False reason=WorkerDeploymentExists
32-
message: "A WorkerDeployment with the same name exists. Migration is in progress."
33-
```
34-
35-
**Migration complete** — ownership transfer is done (the controller labels the `TemporalWorkerDeployment` with `temporal.io/migrated-to-wd: "true"` once all child resources have been re-owned):
36-
```
37-
Ready=False reason=MigratedToWorkerDeployment
38-
message: "Migration complete. Delete this TemporalWorkerDeployment."
39-
```
40-
41-
For `TemporalConnection`, the same `Deprecated` → `MigratedToConnection` pattern applies (there is no ownership transfer step, so there is no intermediate state).
42-
43-
## Deletion protection
44-
45-
After upgrading to v1.7, the controller adds a `temporal.io/migration-guard` finalizer to every `TemporalWorkerDeployment` and `TemporalConnection`. This finalizer prevents the resource from being fully deleted until migration is confirmed:
46-
47-
- A `TemporalWorkerDeployment` can only be deleted once the controller has labeled it `temporal.io/migrated-to-wd: "true"` (set automatically after ownership transfer completes).
48-
- A `TemporalConnection` can only be deleted once a `Connection` with the same name exists.
49-
50-
If you delete a deprecated resource before creating its replacement, the resource will enter `Terminating` state and remain there until you create the new resource. Once the matching `WorkerDeployment` or `Connection` is created and migration is confirmed, the finalizer is removed and deletion completes automatically. The condition during this wait will be:
51-
52-
```
53-
Ready=False reason=DeletingPendingMigration
54-
message: "This TemporalWorkerDeployment is marked for deletion. Create a WorkerDeployment with the same name and spec to complete migration; deletion will proceed automatically once migration is confirmed."
55-
```
56-
5718
## Migration steps
5819

20+
> **Dev / non-production environments:** If you don't need to preserve any worker state, the simplest path is to delete all your `TemporalWorkerDeployment` and `TemporalConnection` resources while the v1.6 controller is still running. At that point no migration-guard finalizer has been added yet, so deletion completes after the v1.6 finalizer completes. Note that all related Worker Deployment state in the Temporal server will also be deleted. Then upgrade the controller and create fresh `WorkerDeployment` and `Connection` resources.
21+
5922
### Step 1: Upgrade the CRDs chart
6023

6124
```bash
@@ -76,7 +39,7 @@ helm upgrade temporal-worker-controller \
7639
--namespace temporal-system
7740
```
7841

79-
When the v1.7 controller starts, it adds the `temporal.io/migration-guard` finalizer to all existing `TemporalWorkerDeployment` and `TemporalConnection` resources.
42+
When the v1.7 controller starts, it adds the `temporal.io/migration-guard` finalizer to all existing `TemporalWorkerDeployment` and `TemporalConnection` resources. See [Deletion protection](#deletion-protection) for what this means.
8043

8144
### Step 3: Migrate your resources
8245

@@ -116,3 +79,43 @@ spec:
11679
### Step 5: Update tooling and scripts
11780
11881
Update any scripts, CI/CD pipelines, runbooks, monitoring alerts, or other tooling that references the old CRD kind names (`TemporalWorkerDeployment`, `TemporalConnection`) or their short names (`twd`, `tconn`).
82+
83+
## What happens to deprecated resources in App Version v1.7?
84+
85+
Existing `TemporalWorkerDeployment` and `TemporalConnection` objects remain in your cluster but are no longer reconciled against Temporal server state. The controller will not manage worker versions, route traffic, or connect to Temporal on behalf of these resources. New resources of these kinds cannot be created.
86+
87+
The deprecated resources will have a `Ready=False` status condition set by a migration helper controller. The condition progresses through three states:
88+
89+
**Before migration** — if no `WorkerDeployment` with the same name exists:
90+
```
91+
Ready=False reason=Deprecated
92+
message: "TemporalWorkerDeployment is deprecated. Create a WorkerDeployment with the same name and spec to migrate."
93+
```
94+
95+
**Migration in progress** — a `WorkerDeployment` with the same name exists, and the controller is transferring ownership of child `Deployments` and `WorkerResourceTemplates` from the old owner to the new one:
96+
```
97+
Ready=False reason=WorkerDeploymentExists
98+
message: "A WorkerDeployment with the same name exists. Migration is in progress."
99+
```
100+
101+
**Migration complete** — ownership transfer is done (the controller labels the `TemporalWorkerDeployment` with `temporal.io/migrated-to-wd: "true"` once all child resources have been re-owned):
102+
```
103+
Ready=False reason=MigratedToWorkerDeployment
104+
message: "Migration complete. Delete this TemporalWorkerDeployment."
105+
```
106+
107+
For `TemporalConnection`, the same `Deprecated` → `MigratedToConnection` pattern applies (there is no ownership transfer step, so there is no intermediate state).
108+
109+
## Deletion protection
110+
111+
After upgrading to v1.7, the controller adds a `temporal.io/migration-guard` finalizer to every `TemporalWorkerDeployment` and `TemporalConnection`. This finalizer prevents the resource from being fully deleted until migration is confirmed:
112+
113+
- A `TemporalWorkerDeployment` can only be deleted once the controller has labeled it `temporal.io/migrated-to-wd: "true"` (set automatically after ownership transfer completes).
114+
- A `TemporalConnection` can only be deleted once a `Connection` with the same name exists.
115+
116+
If you delete a deprecated resource before creating its replacement, the resource will enter `Terminating` state and remain there until you create the new resource. Once the matching `WorkerDeployment` or `Connection` is created and migration is confirmed, the finalizer is removed and deletion completes automatically. The condition during this wait will be:
117+
118+
```
119+
Ready=False reason=DeletingPendingMigration
120+
message: "This TemporalWorkerDeployment is marked for deletion. Create a WorkerDeployment with the same name and spec to complete migration; deletion will proceed automatically once migration is confirmed."
121+
```

0 commit comments

Comments
 (0)