From d4418417116ec9f6fe398dde35b871a69aea2a82 Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:01:48 +0530 Subject: [PATCH 1/9] Pause label document update Signed-off-by: sreejith-rajashekaran --- docs/end-user/workflow/suspending-application-reconciliation.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/end-user/workflow/suspending-application-reconciliation.md diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md new file mode 100644 index 00000000..e69de29b From 27e4ef8d2efee4ce329230db9a7e460e5466d6ad Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:03:24 +0530 Subject: [PATCH 2/9] Pause label document update2 Signed-off-by: sreejith-rajashekaran --- .../suspending-application-reconciliation.md | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index e69de29b..909e3ed2 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -0,0 +1,93 @@ +--- +title: Pause Application Reconciliation +description: How to temporarily stop KubeVela from reconciling an Application using the controller.core.oam.dev/pause label. +# sidebar_position: 20 +--- + +## Dependency + +KubeVela can **temporarily ignore** an `Application` when you add the label: + +```yaml +metadata: + labels: + controller.core.oam.dev/pause: "true" + +This is useful when you need to: + +Perform manual operations on underlying resources (e.g., debug/triage in staging) without KubeVela reverting your changes. + +Downscale or quiet non-critical services during weekends/off-hours. + +Prevent State Keep (periodic re-apply) from overwriting temporary/manual changes while you investigate incidents. + +Availability: controller.core.oam.dev/pause is supported in KubeVela v1.9+. Older releases (≤ v1.8) do not support this label. + + +### How to Use + +Pause reconciliation + +kubectl label application \ + controller.core.oam.dev/pause=true -n --overwrite + +Resume reconciliation + +# Remove the label +kubectl label application controller.core.oam.dev/pause- -n + +Full YAML example + +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: my-app + namespace: staging + labels: + controller.core.oam.dev/pause: "true" +spec: + components: + - name: web + type: webservice + properties: + image: ghcr.io/example/web:1.2.3 + port: 8080 +``` + +### Expected Outcome + +While the label is set to "true", the Application is ignored by the controller: + +- No reconcile loop for that Application + +- No State Keep (drift correction) + +- No garbage collection of Application-owned resources + +When you remove the label (or set it to something other than "true"), the controller resumes reconciliation and brings actual state back in line with the Application spec. + + +**Reminder:** Because reconcile is paused, any manual edits you make can drift from the desired spec. They will be reconciled back once you resume. + + +### Differences vs. other controls + +| Control | Scope | Reconcile / State-Keep | Typical use case | +| ----------------------------------------- | ------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| **`controller.core.oam.dev/pause` label** | Whole Application | **Stopped** | Temporary, explicit “hands-off” period for the entire app (e.g., staging triage, maintenance) | +| **Workflow `suspend`** | Workflow engine only | **Continues** | Pause an in-progress workflow step (e.g., manual approval) while still maintaining desired state | +| **Workflow `terminate`** | Workflow engine only | Stops workflow; be careful with drift | Abort an executing workflow and later `restart` to re-run from the beginning | +| **Policy: `apply-once`** | Selected fields/resources | Runs, but **skips** chosen fields | Let other controllers (HPA/KEDA/Istio) mutate fields like `spec.replicas` without Vela fighting back | +| **Policy: `read-only`** | Selected resources | Runs, does **not** update selected resources | Freeze updates to specific resources while keeping the Application active | + + + +### Best practices +- Use labels intentionally: Add the pause label only when you need a hands-off window; remove it as soon as you’re done. + +- Audit & visibility: Label changes are regular Kubernetes metadata updates—monitor via Events/audit logs. + +- Staging first: Prefer pausing in staging or non-prod contexts. In production, consider safer alternatives (e.g., apply-once on replicas + KEDA/CronHPA) unless you fully understand the operational impact. + +- Multi-cluster: Pausing happens at the control plane (where the Application lives). No further changes will be pushed to registered target clusters while paused. \ No newline at end of file From 87799a8ee7c45c119393bea9adcc802ca8e2c812 Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:05:18 +0530 Subject: [PATCH 3/9] Pause label document update3 Signed-off-by: sreejith-rajashekaran --- docs/end-user/workflow/suspending-application-reconciliation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index 909e3ed2..4d575751 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -12,6 +12,7 @@ KubeVela can **temporarily ignore** an `Application` when you add the label: metadata: labels: controller.core.oam.dev/pause: "true" +``` This is useful when you need to: From 711f0277e9a99cfaa4cc52168b349f270eea047a Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:07:24 +0530 Subject: [PATCH 4/9] Pause label document update4 Signed-off-by: sreejith-rajashekaran --- .../workflow/suspending-application-reconciliation.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index 4d575751..20d8b5f9 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -29,13 +29,17 @@ Availability: controller.core.oam.dev/pause is supported in KubeVela v1.9+. Olde Pause reconciliation +```yaml kubectl label application \ controller.core.oam.dev/pause=true -n --overwrite +``` Resume reconciliation +```yaml # Remove the label kubectl label application controller.core.oam.dev/pause- -n +``` Full YAML example From a5d74562dd6510fc6c66f4d1f1fadeaded98aba7 Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:14:15 +0530 Subject: [PATCH 5/9] Pause label document update5 Signed-off-by: sreejith-rajashekaran --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index f4b4d7a0..346335f8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -173,6 +173,7 @@ module.exports = { 'tutorials/debug-app', 'tutorials/cloud-shell', 'tutorials/vela-top', + 'end-user/workflow/component-dependency-parameter.md', { type: 'category', label: 'Config Management', From 5cc0c04020977760042289efbdde8c907cbb66ee Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 10:16:07 +0530 Subject: [PATCH 6/9] Pause label document update6 Signed-off-by: sreejith-rajashekaran --- sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index 346335f8..13252b19 100644 --- a/sidebars.js +++ b/sidebars.js @@ -173,7 +173,7 @@ module.exports = { 'tutorials/debug-app', 'tutorials/cloud-shell', 'tutorials/vela-top', - 'end-user/workflow/component-dependency-parameter.md', + 'end-user/workflow/suspending-application-reconciliation', { type: 'category', label: 'Config Management', From 923ad2c2261bfca15e609fd9c271f89a8e5c3d77 Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Tue, 23 Sep 2025 11:47:12 +0530 Subject: [PATCH 7/9] Pause label document final Signed-off-by: sreejith-rajashekaran --- .../workflow/suspending-application-reconciliation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index 20d8b5f9..07497ec1 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -76,7 +76,7 @@ When you remove the label (or set it to something other than "true"), the contro **Reminder:** Because reconcile is paused, any manual edits you make can drift from the desired spec. They will be reconciled back once you resume. -### Differences vs. other controls +## Differences vs. other controls | Control | Scope | Reconcile / State-Keep | Typical use case | | ----------------------------------------- | ------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | @@ -88,7 +88,7 @@ When you remove the label (or set it to something other than "true"), the contro -### Best practices +## Best practices - Use labels intentionally: Add the pause label only when you need a hands-off window; remove it as soon as you’re done. - Audit & visibility: Label changes are regular Kubernetes metadata updates—monitor via Events/audit logs. From a3ae6e176410a096772a1314976e930bcebcfdb8 Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Wed, 24 Sep 2025 10:02:27 +0530 Subject: [PATCH 8/9] Pause label document PR changes Signed-off-by: sreejith-rajashekaran --- docs/end-user/workflow/suspending-application-reconciliation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index 07497ec1..1e8f4ad8 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -6,7 +6,7 @@ description: How to temporarily stop KubeVela from reconciling an Application us ## Dependency -KubeVela can **temporarily ignore** an `Application` when you add the label: +KubeVela will not reconcile an `Application` when you add the label. Reconciling will only resume after the label is removed. ```yaml metadata: From d6fabe19e6966b426b7c12f19c759081ab62411c Mon Sep 17 00:00:00 2001 From: sreejith-rajashekaran Date: Wed, 24 Sep 2025 10:05:06 +0530 Subject: [PATCH 9/9] Pause label document PR changes2 Signed-off-by: sreejith-rajashekaran --- .../workflow/suspending-application-reconciliation.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/end-user/workflow/suspending-application-reconciliation.md b/docs/end-user/workflow/suspending-application-reconciliation.md index 1e8f4ad8..1de914a8 100644 --- a/docs/end-user/workflow/suspending-application-reconciliation.md +++ b/docs/end-user/workflow/suspending-application-reconciliation.md @@ -16,11 +16,12 @@ metadata: This is useful when you need to: -Perform manual operations on underlying resources (e.g., debug/triage in staging) without KubeVela reverting your changes. +- Perform manual operations on underlying resources (e.g., debug/triage in staging) without KubeVela reverting your changes. -Downscale or quiet non-critical services during weekends/off-hours. +- Downscale or quiet non-critical services during weekends/off-hours. -Prevent State Keep (periodic re-apply) from overwriting temporary/manual changes while you investigate incidents. +- Prevent State Keep (periodic re-apply) from overwriting temporary/manual changes while you investigate incidents. + Availability: controller.core.oam.dev/pause is supported in KubeVela v1.9+. Older releases (≤ v1.8) do not support this label.