Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/case-studies/multi-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,8 +417,10 @@ spec:
Sometimes, you may want to use the same policy across multiple applications or reuse previous workflow to deploy different resources.
To reduce the repeated code, you can leverage the external policies and workflow and refer to them in your applications.

:::caution
You can only refer to Policy and Workflow within your application's namespace.
:::note
A Policy is looked up in your application's namespace only. A Workflow is looked up there first, then in the system definition namespace (`vela-system` unless the controller sets `--system-definition-namespace`), 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

:::

```yaml
Expand Down
6 changes: 3 additions & 3 deletions docs/end-user/components/references.md
Original file line number Diff line number Diff line change
Expand Up @@ -692,7 +692,7 @@ The rendered chart sees `replicaCount: 5` (from inline), `resources.limits.memor

#### Authenticating with private chart registries

Add `chart.auth.secretRef` to point at a Secret in the vela-core namespace (`vela-system` by default). The Secret type controls how credentials are extracted:
Add `chart.auth.secretRef` to point at a Secret in the Application's own namespace; a Secret in any other namespace, the release namespace included, is refused. The Secret type controls how credentials are extracted:

| Secret type | Keys read | Use case |
|---|---|---|
Expand Down Expand Up @@ -770,7 +770,7 @@ The same `auth` block works for HTTPS repos (`source` + `repoURL`) and direct `.
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
name | Name of the Secret | string | true |
namespace | Namespace of the Secret. Defaults to the release namespace, which itself defaults to the Application namespace when `release.namespace` is unset. Must be either the release namespace or the Application namespace; cross-namespace references are rejected. | string | false |
namespace | Namespace of the Secret. Defaults to, and must be, the Application's own namespace; any other is refused, the release namespace included. | string | false |

Supported Secret types:

Expand All @@ -793,7 +793,7 @@ An `Opaque` Secret can also include these optional TLS fields: `caFile` (custom
---- | ----------- | ---- | -------- | -------
kind | Source kind. Only `Secret` and `ConfigMap` are supported. `OCIRepository` is not yet supported. | "Secret" or "ConfigMap" | true |
name | Name of the Secret or ConfigMap. | string | true |
namespace | Namespace of the Secret or ConfigMap. Defaults to the release namespace. An explicit value must match either the release namespace or the Application's own namespace; other namespaces are rejected to prevent cross-tenant reads via the controller's cluster-wide RBAC. | string | false |
namespace | Namespace of the Secret or ConfigMap. Defaults to, and must be, the Application's own namespace; any other is refused, the release namespace included. | string | false |
key | Key inside `.data` whose value is parsed as YAML. Only `.data` is read; `ConfigMap.binaryData` is rejected. | string | false | "values.yaml"
optional | If true, a missing Secret/ConfigMap or missing key is skipped silently. Parse errors and permission errors still fail the render. | bool | false | false

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@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


Follow [Upgrading to v1.12](upgrade-to-v1.12.md) for the full procedure, what changes after the upgrade, and the scripted downgrade.

### Config templates and configs

v1.12 turns config templates and configs into Kubernetes resources, `ConfigTemplate` and `Config`,
Expand Down
Loading
Loading