Skip to content
HomeUsageChange Plans

Change Plans ​

Change Plans add an approval gate in front of sensitive operations. Instead of applying a change immediately, KubeOsprey records it as a plan with explicit steps; an approver reviews and approves it; only then is the change executed, and every applied plan can be rolled back.

Change Plans

When plans are created ​

Two switches in Settings → General control which operations are gated:

  • AI change plan mode (aiChangePlanMode) — when enabled, write operations requested through the AI Assistant do not run directly. The assistant records the intended steps as a plan and hands it to a human for approval.
  • Webhook change plan mode (webhookChangePlanMode) — when enabled, Helm upgrades submitted through the CI webhook endpoint (POST /api/v1/webhooks/helm-upgrade) are held as pending plans instead of executing immediately. This turns your CI/CD pipeline into a review-before-deploy flow.
  • The webhook payload accepts an optional chartVersion: the upgrade then pulls that version from the release's repository catalog instead of keeping the current chart. chartUrl, when provided, takes precedence; without either, the upgrade re-uses the currently deployed chart with the submitted values.

Plan lifecycle ​

created → pending → approved → applying → applied
                  ↘ rejected        ↘ failed
pending → expired (approval not given before the deadline)
  • A plan contains one or more steps, each describing one operation together with its dry-run result, so the approver sees what would happen before approving.
  • Approval requires a separate permission — the person who created the plan cannot approve it themselves.
  • Pending plans expire if no decision is made in time.
  • Applied plans support rollback (see Resource History for the underlying revision trail).

Notifications ​

KubeOsprey can push plan events (plan_pending, plan_applied, plan_failed) to DingTalk, WeCom, Feishu, Slack, or a generic webhook. See Notification Channels.

API ​

MethodPathPurpose
GET/api/v1/change-plansList plans
GET/api/v1/change-plans/:idPlan detail with steps
GET/api/v1/change-plans/pending-countBadge count of pending plans
POST/api/v1/change-plans/:id/approveApprove a pending plan
POST/api/v1/change-plans/:id/rejectReject a pending plan
POST/api/v1/change-plans/:id/rollbackRoll back an applied plan

Released under the Apache License.