Skip to content

Docs: v1.12 upgrade guide and migration notes - #1473

Open
briankane wants to merge 4 commits into
kubevela:mainfrom
briankane:release-1.12/fixes
Open

briankane wants to merge 4 commits into
kubevela:mainfrom
briankane:release-1.12/fixes

Conversation

@briankane

@briankane briankane commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Description of your changes

Docs for v1.12, from the release testing:

  • Docs: a workflow ref falls back to a shared Workflow in vela-system
  • Docs: add the upgrade guide for v1.12
  • Docs: add v1.11 to v1.12 to the migration guide
  • Docs: helmchart reads chart credentials and values only from the Application's namespace

The upgrade guide lists what changes for users on upgrade, by area, with what to do before and after. It goes with
kubevela/kubevela#7587, kubevela/velaux#984 and kubevela/workflow#287.

I have:

  • All commits are signed off (DCO).

How has this code been tested

Content only. Not built locally; the site build runs in CI.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/case-studies/multi-cluster.md">

<violation number="1" location="docs/case-studies/multi-cluster.md:423">
P2: This note ties the Workflow `get` requirement to definition permissions as well as `AuthenticateApplication`. The upgrade guide ties it only to `AuthenticateApplication`; definition validation checks read access to the definitions the Workflow's steps name. Limit the sentence to the feature gate so the two pages agree.</violation>
</file>

<file name="docs/platform-engineers/system-operation/upgrade-to-v1.12.md">

<violation number="1" location="docs/platform-engineers/system-operation/upgrade-to-v1.12.md:87">
P2: This says Helm credentials and values in the release namespace are refused, but the Helm reference permits both the release and Application namespaces. Correct the namespace rule before users unnecessarily move valid Secrets and ConfigMaps.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

:::note
A Policy is looked up in your application's namespace only. A Workflow is looked up there first, then in `vela-system`, so a platform team can share one Workflow with every namespace. A Workflow of the same name in your application's namespace takes precedence, and the application's `status.workflow.ref` shows which one it ran.

Where definition permissions or `AuthenticateApplication` are enforced, the application's author needs `get` on the Workflow it refers to, in whichever namespace it is found.

@cubic-dev-ai cubic-dev-ai Bot Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This note ties the Workflow get requirement to definition permissions as well as AuthenticateApplication. The upgrade guide ties it only to AuthenticateApplication; definition validation checks read access to the definitions the Workflow's steps name. Limit the sentence to the feature gate so the two pages agree.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/case-studies/multi-cluster.md, line 423:

<comment>This note ties the Workflow `get` requirement to definition permissions as well as `AuthenticateApplication`. The upgrade guide ties it only to `AuthenticateApplication`; definition validation checks read access to the definitions the Workflow's steps name. Limit the sentence to the feature gate so the two pages agree.</comment>

<file context>
@@ -417,8 +417,10 @@ spec:
+:::note
+A Policy is looked up in your application's namespace only. A Workflow is looked up there first, then in `vela-system`, so a platform team can share one Workflow with every namespace. A Workflow of the same name in your application's namespace takes precedence, and the application's `status.workflow.ref` shows which one it ran.
+
+Where definition permissions or `AuthenticateApplication` are enforced, the application's author needs `get` on the Workflow it refers to, in whichever namespace it is found.
 :::
 
</file context>
Suggested change
Where definition permissions or `AuthenticateApplication` are enforced, the application's author needs `get` on the Workflow it refers to, in whichever namespace it is found.
With the `AuthenticateApplication` feature gate on, the application's author needs `get` on the Workflow it refers to, in whichever namespace it is found.
Fix with cubic

Comment thread docs/case-studies/multi-cluster.md Resolved
- A component placed by a topology policy into a namespace other than the Application's own now works, which is VelaUX's default environment layout. Definitions that need the Application's own namespace there can read the new `context.appNamespace`.
- `release.namespace` without `release.name` now names the release after the component.
- With authentication enabled, releases are installed as the Application's user, who needs rights to the chart's objects on every cluster the topology places it on.
- **Chart credentials and values are read from the Application's own namespace.** The Secret `chart.auth.secretRef` names, and every `valuesFrom` Secret and ConfigMap, must be in the Application's namespace, which is also the default when none is named. One in the release namespace, or anywhere else, is refused. Move them into the Application's namespace before the upgrade.

@cubic-dev-ai cubic-dev-ai Bot Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This says Helm credentials and values in the release namespace are refused, but the Helm reference permits both the release and Application namespaces. Correct the namespace rule before users unnecessarily move valid Secrets and ConfigMaps.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/platform-engineers/system-operation/upgrade-to-v1.12.md, line 87:

<comment>This says Helm credentials and values in the release namespace are refused, but the Helm reference permits both the release and Application namespaces. Correct the namespace rule before users unnecessarily move valid Secrets and ConfigMaps.</comment>

<file context>
@@ -0,0 +1,194 @@
+- A component placed by a topology policy into a namespace other than the Application's own now works, which is VelaUX's default environment layout. Definitions that need the Application's own namespace there can read the new `context.appNamespace`.
+- `release.namespace` without `release.name` now names the release after the component.
+- With authentication enabled, releases are installed as the Application's user, who needs rights to the chart's objects on every cluster the topology places it on.
+- **Chart credentials and values are read from the Application's own namespace.** The Secret `chart.auth.secretRef` names, and every `valuesFrom` Secret and ConfigMap, must be in the Application's namespace, which is also the default when none is named. One in the release namespace, or anywhere else, is refused. Move them into the Application's namespace before the upgrade.
+- `oci://` charts are pulled through the same outbound address checks as other chart sources.
+- **Chart cache:** each Application caches its charts separately by default, so many Applications on one chart hold one copy each on every vela-core pod, and a new leader fetches them all again. Set `options.cache.key` to a shared value for widely used charts. A version-pinned chart stays cached for 24 hours even if it is re-pushed, and an OCI chart with the default `version: latest` needs a real `latest` tag.
</file context>
Suggested change
- **Chart credentials and values are read from the Application's own namespace.** The Secret `chart.auth.secretRef` names, and every `valuesFrom` Secret and ConfigMap, must be in the Application's namespace, which is also the default when none is named. One in the release namespace, or anywhere else, is refused. Move them into the Application's namespace before the upgrade.
- **Chart credentials and values can come from the Application's or release namespace.** The Secret `chart.auth.secretRef` and every `valuesFrom` Secret and ConfigMap may use either namespace. When none is named, the release namespace is used, and it defaults to the Application's namespace.
Fix with cubic

Since 1.12 a Workflow named in spec.workflow.ref is looked up in the
application's namespace, then in vela-system. Say so, say which one
wins and where to see it, and the permission it needs where definition
permissions or AuthenticateApplication are enforced.

Signed-off-by: Brian Kane <briankane1@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 existing issue remains and 1 new issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/platform-engineers/system-operation/migration-from-old-version.md">

<violation number="1" location="docs/platform-engineers/system-operation/migration-from-old-version.md:11">
P2: This absolute statement conflicts with the existing rollback procedure: after deleting the v1.12 admission webhook, `config-migration.md` runs `helm rollback` successfully. Say that the direct rollback can fail and point users to the scripted downgrade instead.</violation>
</file>

Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.

View guided diff | Re-trigger cubic


## From v1.11.x to v1.12.x

v1.12.x adds the `SourceDefinition`, `Config` and `ConfigTemplate` CRDs, validates more on admission, and changes several builtin definitions. Some steps must happen before `helm upgrade`, and `helm rollback` cannot take you back to v1.11.

@cubic-dev-ai cubic-dev-ai Bot Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This absolute statement conflicts with the existing rollback procedure: after deleting the v1.12 admission webhook, config-migration.md runs helm rollback successfully. Say that the direct rollback can fail and point users to the scripted downgrade instead.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/platform-engineers/system-operation/migration-from-old-version.md, line 11:

<comment>This absolute statement conflicts with the existing rollback procedure: after deleting the v1.12 admission webhook, `config-migration.md` runs `helm rollback` successfully. Say that the direct rollback can fail and point users to the scripted downgrade instead.</comment>

<file context>
@@ -8,6 +8,10 @@ KubeVela has [release cadence](../../contributor/release-process.md) for every 2
 
 ## From v1.11.x to v1.12.x
 
+v1.12.x adds the `SourceDefinition`, `Config` and `ConfigTemplate` CRDs, validates more on admission, and changes several builtin definitions. Some steps must happen before `helm upgrade`, and `helm rollback` cannot take you back to v1.11.
+
+Follow [Upgrading to v1.12](upgrade-to-v1.12.md) for the full procedure, what changes after the upgrade, and the scripted downgrade.
</file context>
Suggested change
v1.12.x adds the `SourceDefinition`, `Config` and `ConfigTemplate` CRDs, validates more on admission, and changes several builtin definitions. Some steps must happen before `helm upgrade`, and `helm rollback` cannot take you back to v1.11.
v1.12.x adds the `SourceDefinition`, `Config` and `ConfigTemplate` CRDs, validates more on admission, and changes several builtin definitions. Some steps must happen before `helm upgrade`, and a direct `helm rollback` can fail part-way; follow the scripted downgrade in [Upgrading to v1.12](upgrade-to-v1.12.md).
Fix with cubic

What to do before upgrading from v1.11 (CRDs first, admission checks,
values on the new chart defaults, clients), what changes right after
and on each Application's first edit, the behaviour changes by area,
and the scripted downgrade to v1.11.

Signed-off-by: Brian Kane <briankane1@gmail.com>
Point to the v1.12 upgrade guide from the list of version migrations.

Signed-off-by: Brian Kane <briankane1@gmail.com>
…ication's namespace

The helmchart reference still said the chart auth Secret lives in the
vela-core namespace, and that it and valuesFrom sources may also be in
the release namespace. Both are read only from the Application's own
namespace, which is also the default.

Signed-off-by: Brian Kane <briankane1@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant