|
| 1 | +--- |
| 2 | +title: Resource Application Logic |
| 3 | +description: Control deploy ordering with sync waves, run lifecycle hooks, and clean them up via hook delete policies |
| 4 | +--- |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +Plural’s deployment operator supports sync controls on any Kubernetes manifest you manage with Plural. You can: |
| 9 | + |
| 10 | +- Order resource application using sync waves |
| 11 | +- Run lifecycle hooks at specific phases of a sync |
| 12 | +- Automatically clean up hook resources with delete policies |
| 13 | + |
| 14 | +This lets you do things like run database migrations before an app rollout, seed data after, |
| 15 | +and strictly order dependencies across services. |
| 16 | + |
| 17 | +## Sync waves |
| 18 | + |
| 19 | +Sync waves allow you to define the order within a sync phase in which resources are applied. Lower waves run first. |
| 20 | + |
| 21 | +You can use sync waves on any Kubernetes resource by simply adding an `deployment.plural.sh/sync-wave` annotation. |
| 22 | +We also support the Argo CD `argocd.argoproj.io/sync-wave` and Helm `helm.sh/hook-weight` annotations for compatibility. |
| 23 | +The value is an integer (as a quoted string) and can be negative. |
| 24 | + |
| 25 | +Annotations are checked in that order of precedence, with `deployment.plural.sh/sync-wave` |
| 26 | +taking the highest precedence, then `argocd.argoproj.io/sync-wave`, then `helm.sh/hook-weight`. If none is set, |
| 27 | +then the default ordering will be used. |
| 28 | + |
| 29 | +Default wave ordering is: |
| 30 | +- 0 - Non-namespaced resources (namespaces, CRDs, persistent volumes, cluster roles, etc.). |
| 31 | +- 1 - Core namespaced configuration resources (config maps, secrets, roles etc.). |
| 32 | +- 2 - Core namespaced workload resources (deployments, daemon sets, jobs, pods, etc.). |
| 33 | +- 3 - Core namespaced networking resources (services, ingresses, etc.). |
| 34 | +- 4 - All other resources. |
| 35 | + |
| 36 | +The operator applies all resources in ascending wave order. |
| 37 | + |
| 38 | +### Example |
| 39 | + |
| 40 | +```yaml |
| 41 | +# Create a config map in wave -1, before the deployment in wave 6 and other resources in default waves |
| 42 | +apiVersion: v1 |
| 43 | +kind: ConfigMap |
| 44 | +metadata: |
| 45 | + name: my-config |
| 46 | + annotations: |
| 47 | + deployment.plural.sh/sync-wave: "-1" |
| 48 | +--- |
| 49 | +# Create the deployment in wave 6, after the config map and other resources in default waves |
| 50 | +apiVersion: apps/v1 |
| 51 | +kind: Deployment |
| 52 | +metadata: |
| 53 | + name: my-app |
| 54 | + annotations: |
| 55 | + deployment.plural.sh/sync-wave: "6" |
| 56 | +``` |
| 57 | +
|
| 58 | +## Sync hooks (phases) |
| 59 | +
|
| 60 | +Hook resources are created and monitored at specific phases of a sync. |
| 61 | +
|
| 62 | +Use the `deployment.plural.sh/sync-hook` annotation to designate a manifest as a hook. Alternatively, |
| 63 | +you can use Helm `helm.sh/hook` for compatibility. Commonly, jobs are used for hooks. |
| 64 | + |
| 65 | +Supported phases are: |
| 66 | +- `pre-sync`: Run before `sync`. Use for DB migrations, pre-flight checks, or draining traffic. |
| 67 | +- `sync`: The default phase if none is specified. |
| 68 | +- `post-sync`: Run after `sync`. Useful for seeding data, smoke tests, or notifications. |
| 69 | +- `sync-fail`: Run only if the `sync` phase fails. Useful for rollbacks, alerts, or diagnostics. |
| 70 | +- `skip`: Do not apply this resource. Useful for temporarily disabling a resource without deleting it. |
| 71 | + |
| 72 | +For `helm.sh/hook` we support the following values: |
| 73 | +- `pre-install` and `pre-upgrade`: equivalent to `pre-sync`. |
| 74 | +- `post-install` and `post-upgrade`: equivalent to `post-sync`. |
| 75 | + |
| 76 | +A resource may belong to multiple phases, for example `pre-sync,post-sync`. |
| 77 | + |
| 78 | +A resource can be both a hook and have a sync wave. This allows you to control the ordering of hooks relative |
| 79 | +to other hooks and resources. |
| 80 | + |
| 81 | +The operator executes hooks starting in the described order and proceeds to the next phase only when all hooks |
| 82 | +in the current phase will apply and achieve a healthy state. |
| 83 | + |
| 84 | +### Example |
| 85 | + |
| 86 | +```yaml |
| 87 | +# Create a pre-sync migration job in wave -1 |
| 88 | +apiVersion: batch/v1 |
| 89 | +kind: Job |
| 90 | +metadata: |
| 91 | + name: migrate-db |
| 92 | + annotations: |
| 93 | + deployment.plural.sh/sync-hook: pre-sync |
| 94 | + deployment.plural.sh/sync-wave: "-1" |
| 95 | +spec: |
| 96 | + template: |
| 97 | + spec: |
| 98 | + restartPolicy: Never |
| 99 | + containers: |
| 100 | + - name: migrate |
| 101 | + image: myrepo/migrate:latest |
| 102 | + args: ["up"] |
| 103 | +``` |
| 104 | + |
| 105 | +## Hook delete policies (cleanup) |
| 106 | + |
| 107 | +By default, hook resources are left in the cluster after they run. You can opt into automatic cleanup with |
| 108 | +`deployment.plural.sh/sync-hook-delete-policy` annotation. You can also use Helm `helm.sh/hook-delete-policy` |
| 109 | +annotation. Multiple policies can be comma-separated. |
| 110 | + |
| 111 | +Use `hook-succeeded` and/or `hook-failed` to delete the resource after it completes successfully or fails, respectively. |
| 112 | +If no delete policy is set, the resource will be kept. |
| 113 | + |
| 114 | +{% callout severity="warning" %} |
| 115 | +When a manifest of a hook is updated, the operator will reapply the resource even if it has already completed. |
| 116 | +{% /callout %} |
| 117 | + |
| 118 | +### Example |
| 119 | + |
| 120 | +```yaml |
| 121 | +# Create a pre-sync migration job that is deleted on success |
| 122 | +apiVersion: batch/v1 |
| 123 | +kind: Job |
| 124 | +metadata: |
| 125 | + name: migrate-db |
| 126 | + annotations: |
| 127 | + deployment.plural.sh/sync-hook: pre-sync |
| 128 | + deployment.plural.sh/sync-hook-delete-policy: hook-succeeded |
| 129 | +spec: |
| 130 | + template: |
| 131 | + spec: |
| 132 | + restartPolicy: Never |
| 133 | + containers: |
| 134 | + - name: migrate |
| 135 | + image: myrepo/migrate:latest |
| 136 | + args: ["up"] |
| 137 | +``` |
| 138 | + |
| 139 | +## FAQ |
| 140 | +- Do I need a separate tool for these annotations to work? |
| 141 | + No. The operator understands these annotations and applies them as described. |
| 142 | + |
| 143 | +- What happens if I don’t set a delete policy on a hook? |
| 144 | + The hook resource will be kept in the cluster so you can inspect logs and status. Add `hook-succeeded` and/or |
| 145 | + `hook-failed` to enable automatic cleanup. |
| 146 | + |
| 147 | +- Can I control ordering between different hooks? |
| 148 | + Yes. Combine `deployment.plural.sh/sync-hook` with `deployment.plural.sh/sync-wave` on each hook. |
| 149 | + |
| 150 | +- Are negative waves allowed? |
| 151 | + Yes. Negative, zero, and positive integers are supported. Lower numbers run first. |
0 commit comments