From 2080be13d3823293dcbdde78502d48b03e91b1a0 Mon Sep 17 00:00:00 2001 From: Ted Kim Date: Mon, 13 Jul 2026 22:00:35 -0400 Subject: [PATCH 1/3] docs(config): clarify no-statefile model and apply-phase failure retry --- docs/project-configuration.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/project-configuration.md b/docs/project-configuration.md index fe9af96..beaca66 100644 --- a/docs/project-configuration.md +++ b/docs/project-configuration.md @@ -49,10 +49,42 @@ Key semantics: - `volcano config deploy --dry-run` prints the projected actions without changing anything. Validation failures exit non-zero with Volcano's error list, and nothing is applied. +- If some entries fail to apply (a provider call failing mid-deploy), + `config deploy` still prints a full report — succeeded entries included — + and then exits non-zero because `summary.errors > 0`. Already-applied + changes are not rolled back. Re-running `config deploy` with the same file + is always safe: entries that already landed report `unchanged`, and only + the entries that failed or still differ are retried. - Write-only secrets, such as SMTP passwords, OAuth client secrets, and TLS material, are omitted from `config pull` exports. Keep them in your environment and set them via `${ENV_VAR}` interpolation. +## Coming from Terraform? + +There is no state file (`.tfstate` or equivalent) behind `volcano-config.yaml`. +Every `deploy` — including `--dry-run` — asks Volcano to diff the manifest +against the project's actual live configuration, not a cached snapshot of a +prior apply. Practical implications: + +- No `import` / `state rm` / `state mv`: point the manifest at an existing + project and `deploy`; there's nothing to reconcile into a state file first. +- No drift-detection step: the plan is always computed against live + configuration, so it can't disagree with reality the way a stale state file + can. +- `--dry-run` is a live report, not a saved plan artifact — you can't inspect + it later or hand it to a later `deploy`; running `deploy` always recomputes + the plan from scratch. +- No workspaces, no `-target`: the whole manifest reconciles against the + currently selected project (`volcano use` / `VOLCANO_PROJECT_ID`) as one + unit. To leave something alone, omit it from the file. +- A failed deploy doesn't need an explicit resume step — see the apply-phase + failure bullet above; re-running the same manifest picks up only what's + still outstanding. + +See the server-side +[configuration manifest reference](https://github.com/Kong/volcano-hosting/blob/main/docs/projects/configuration.md) +for the full reconciliation semantics. + Behavior changes from older CLI releases: - Buckets are no longer auto-created. From bf4053565c8650a6bfc597c9b0d2064fc3a6f985 Mon Sep 17 00:00:00 2001 From: Ted Kim Date: Mon, 13 Jul 2026 22:36:37 -0400 Subject: [PATCH 2/3] docs(config): make local vs cloud export/apply commands explicit --- docs/project-configuration.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/project-configuration.md b/docs/project-configuration.md index beaca66..490ffd6 100644 --- a/docs/project-configuration.md +++ b/docs/project-configuration.md @@ -13,9 +13,18 @@ validates and applies the full project configuration: - Function visibility and schedulers - Frontend custom domains -The same manifest applies to local development and cloud projects. -`volcano config pull` downloads the current configuration as a canonical -manifest rendered by Volcano. +The same manifest applies to local development and cloud projects — only the +command namespace changes: + +| Target | Export to file | Apply from file | +|---|---|---| +| Local dev (`volcano start`) | `volcano config pull` | `volcano config deploy` | +| Cloud project (`volcano login` + `volcano use`) | `volcano cloud config pull` | `volcano cloud config deploy` | + +`pull` downloads the target's current configuration as a canonical manifest +rendered by Volcano; `deploy` uploads a manifest and reconciles the target to +match it. Both commands take the same flags (`-f/--file`, `--force` for +`pull`, `--dry-run` for `deploy`) regardless of namespace. ```yaml version: 1 @@ -34,6 +43,18 @@ functions: payload: { job: refresh } ``` +Cloud example — export the current cloud project's configuration to a file, +edit it, and apply it back: + +```sh +volcano login +volcano use my-project +volcano cloud config pull -f volcano-config.yaml # export to file +$EDITOR volcano-config.yaml +volcano cloud config deploy -f volcano-config.yaml --dry-run # preview +volcano cloud config deploy -f volcano-config.yaml # apply +``` + Key semantics: - Declared config sections are the source of truth. Variables, bucket policies, From 157b62e161991c9e73a939cb92ecd5ff887903de Mon Sep 17 00:00:00 2001 From: Ted Kim Date: Tue, 14 Jul 2026 13:31:05 -0400 Subject: [PATCH 3/3] =?UTF-8?q?docs(config):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20fix=20unsafe=20omission=20advice=20and=20command=20?= =?UTF-8?q?naming?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/project-configuration.md | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/project-configuration.md b/docs/project-configuration.md index 490ffd6..b3a6bab 100644 --- a/docs/project-configuration.md +++ b/docs/project-configuration.md @@ -21,10 +21,10 @@ command namespace changes: | Local dev (`volcano start`) | `volcano config pull` | `volcano config deploy` | | Cloud project (`volcano login` + `volcano use`) | `volcano cloud config pull` | `volcano cloud config deploy` | -`pull` downloads the target's current configuration as a canonical manifest -rendered by Volcano; `deploy` uploads a manifest and reconciles the target to -match it. Both commands take the same flags (`-f/--file`, `--force` for -`pull`, `--dry-run` for `deploy`) regardless of namespace. +`config pull` downloads the target's current configuration as a canonical +manifest rendered by Volcano; `config deploy` uploads a manifest and +reconciles the target to match it. Both take the same flags (`-f/--file`, +`--force` for `pull`, `--dry-run` for `deploy`) regardless of namespace. ```yaml version: 1 @@ -83,21 +83,28 @@ Key semantics: ## Coming from Terraform? There is no state file (`.tfstate` or equivalent) behind `volcano-config.yaml`. -Every `deploy` — including `--dry-run` — asks Volcano to diff the manifest -against the project's actual live configuration, not a cached snapshot of a -prior apply. Practical implications: +Every `config deploy` — including `--dry-run` — asks Volcano to diff the +manifest against the project's actual live configuration, not a cached +snapshot of a prior apply. Practical implications: - No `import` / `state rm` / `state mv`: point the manifest at an existing - project and `deploy`; there's nothing to reconcile into a state file first. -- No drift-detection step: the plan is always computed against live - configuration, so it can't disagree with reality the way a stale state file - can. + project and run `config deploy`; there's nothing to reconcile into a state + file first. +- No separate drift-detection step: there's no stored copy to go stale — + every plan reads live configuration directly, so any actual drift just + shows up as the next diff and gets reconciled. - `--dry-run` is a live report, not a saved plan artifact — you can't inspect - it later or hand it to a later `deploy`; running `deploy` always recomputes - the plan from scratch. + it later or hand it to a later `config deploy`; running `config deploy` + always recomputes the plan from scratch. - No workspaces, no `-target`: the whole manifest reconciles against the currently selected project (`volcano use` / `VOLCANO_PROJECT_ID`) as one - unit. To leave something alone, omit it from the file. + unit. Omitting an entire section or field leaves it untouched. That does + **not** apply within a section you've already declared as fully synced + (`variables`, `buckets[].policies`, `auth.providers.oauth`, + `auth.email.templates`, `functions[].schedulers`) — omitting one entry + from an otherwise-declared list still deletes that entry, since the + declared list is the source of truth for the whole section. See "Key + semantics" above. - A failed deploy doesn't need an explicit resume step — see the apply-phase failure bullet above; re-running the same manifest picks up only what's still outstanding.