openchoreo-developer-gitops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenChoreo Developer GitOps Guide

OpenChoreo 开发者GitOps指南

Git is the source of truth; the cluster is its reflection. This skill writes OpenChoreo application resources to Git (Project / Component / Workload / ComponentRelease / ReleaseBinding), lets Flux reconcile them, and reads cluster state with

occ

to verify.

This skill is scoped to application-developer GitOps work. Repo scaffolding, Flux wiring, and authoring platform CRDs (ComponentTypes, Traits, Workflows, Environments, DeploymentPipelines, SecretReferences, AuthzRoles, planes) are out of scope — they're done by whoever owns the platform side. Don't edit GitOps-managed resources via

occ apply -f

or any other direct write path; Flux will revert them on the next reconcile.

Git是事实来源；集群是其映射。本技能将OpenChoreo的应用资源写入Git（Project / Component / Workload / ComponentRelease / ReleaseBinding），由Flux进行同步，并通过

occ

读取集群状态以验证。

本技能的适用范围为应用开发者的GitOps工作。仓库脚手架搭建、Flux配置、平台CRD（ComponentTypes、Traits、Workflows、Environments、DeploymentPipelines、SecretReferences、AuthzRoles、planes）编写均不在本技能范围内——这些由平台侧负责人完成。请勿通过

occ apply -f

或其他直接写入方式编辑GitOps管理的资源；Flux会在下一次同步时将其还原。

Step 0 — Hard preconditions

步骤0 — 硬性前置条件

Two checks; both must pass before proceeding.

bash

undefined

需完成两项检查，且均通过后方可继续。

bash

undefined

0a — occ configured against the right cluster

0a — 确认occ已针对正确集群配置

command -v occ && occ config context list && occ namespace list

0b — cwd is inside a scaffolded GitOps repo

0b — 当前工作目录位于脚手架生成的GitOps仓库内

ls flux 2>/dev/null && ls platform-shared 2>/dev/null && ls namespaces 2>/dev/null


If `occ` is missing / unconfigured, stop and tell the user to install + configure it. If the cwd isn't a scaffolded repo (no `flux/` or `clusters/<name>/`, no `platform-shared/`, no `namespaces/`), ask the user for the repo path; if no repo exists, the repo needs scaffolding upstream of this skill — don't start creating components in a non-scaffolded directory.

**Always show the active `occ` context and confirm with the user** before any cluster-touching action.

ls flux 2>/dev/null && ls platform-shared 2>/dev/null && ls namespaces 2>/dev/null


若`occ`未安装/未配置，请停止操作并告知用户安装并配置它。若当前工作目录不是脚手架生成的仓库（无`flux/`或`clusters/<name>/`、`platform-shared/`、`namespaces/`目录），请询问用户仓库路径；若仓库不存在，则需要在本技能上游完成仓库脚手架搭建——不要在非脚手架目录中开始创建组件。

**在执行任何涉及集群的操作前，务必展示当前`occ`上下文并与用户确认**。

Step 1 — Load concepts (MANDATORY)

步骤1 — 加载概念（必填）

Read
references/concepts.md
in full before anything else. Not optional, even if the task looks simple — you'll get the two-resource deploy model / immutability / workload-descriptor tradeoffs / verification ladder wrong from memory. Load once per session; if you catch yourself acting without it, stop and load now.

Load other references on-demand:

```
references/authoring.md
```
—
```
occ
```
file-mode generators, docs lookup via
```
scripts/fetch-page.sh
```
, repo paths, git workflow, DCO.
```
scripts/fetch-page.sh
```
— fetch any OpenChoreo docs page by title (resolves against
```
llms.txt
```
, picks a stable version). Use this for full CRD schemas with optional fields.
```
./scripts/fetch-page.sh --list
```
dumps the full index.
```
references/getting-started.md
```
— first-time deploys (no Project yet, or first time the user touches this repo).

在进行任何操作前，请完整阅读
references/concepts.md
。这并非可选步骤，即使任务看似简单——仅凭记忆会错误理解双资源部署模型、不可变性、工作负载描述权衡、验证流程。每个会话只需加载一次；若发现自己未加载就开始操作，请立即停止并加载。

按需加载其他参考文档：

```
references/authoring.md
```
—
```
occ
```
文件模式生成器、通过
```
scripts/fetch-page.sh
```
查找文档、仓库路径、Git工作流、DCO。
```
scripts/fetch-page.sh
```
— 根据标题获取任意OpenChoreo文档页面（基于
```
llms.txt
```
解析，选择稳定版本）。可用于获取包含可选字段的完整CRD schema。执行
```
./scripts/fetch-page.sh --list
```
可导出完整索引。
```
references/getting-started.md
```
— 首次部署（尚无Project，或用户首次接触本仓库）。

What this skill can do

本技能可完成的操作

Onboard a Component — BYO image or source-build →

recipes/onboard-component-byo.md

recipes/onboard-component-source-build.md

Update a Workload — edit YAML (BYO) or push + rebuild (source-build) →
```
recipes/update-workload.md
```
Configure a Workload — endpoints, env, files, secrets →
```
recipes/configure-workload.md
```
Attach a PE-authored Trait →
```
recipes/attach-trait.md
```
Wire component dependencies —
```
dependencies.endpoints[]
```
with env-var injection →
```
recipes/connect-components.md
```
Generate ComponentReleases / ReleaseBindings via
occ
file-mode — produced through the onboard recipes.
Promote releases — single component or bulk (project / all) →
```
recipes/promote.md
```
,
```
recipes/bulk-promote.md
```
Per-environment overrides — replicas, resources, env vars, trait config →
```
recipes/override-per-environment.md
```
Soft-undeploy / rollback — flip
```
spec.state: Undeploy
```
or repoint at a prior
```
ComponentRelease
```
→
```
recipes/promote.md
```
Rollback
Verify Flux + ReleaseBinding reconciliation →
```
recipes/verify-and-debug.md
```

接入组件 — 自带镜像或源码构建 →

recipes/onboard-component-byo.md

、

recipes/onboard-component-source-build.md

更新工作负载 — 编辑YAML（自带镜像）或推送并重建（源码构建） →
```
recipes/update-workload.md
```
配置工作负载 — 端点、环境变量、文件、密钥 →
```
recipes/configure-workload.md
```
附加PE编写的特性 →
```
recipes/attach-trait.md
```

连接组件依赖 — 通过

dependencies.endpoints[]

注入环境变量 →

recipes/connect-components.md

通过
occ
文件模式生成ComponentReleases / ReleaseBindings — 由接入流程生成。
发布版本 — 单个组件或批量（项目/全部） →
```
recipes/promote.md
```
、
```
recipes/bulk-promote.md
```
按环境配置覆盖 — 副本数、资源配置、环境变量、特性配置 →
```
recipes/override-per-environment.md
```
软卸载/回滚 — 将
```
spec.state: Undeploy
```
或重新指向之前的
```
ComponentRelease
```
→
```
recipes/promote.md
```
回滚部分
验证Flux + ReleaseBinding同步状态 →
```
recipes/verify-and-debug.md
```

What this skill cannot do

本技能无法完成的操作

Repo scaffolding or Flux wiring. Out of scope; assumes the repo is already scaffolded and Flux is wired.
Authoring ComponentTypes / Traits / Workflows. Platform-side. Pick from what
```
occ clustercomponenttype list
```
/
```
occ clustertrait list
```
/
```
occ clusterworkflow list
```
show; the developer attaches what the platform offers.
Plane registration, AuthzRole / SecretReference authoring. Platform-side.
Imperative ops — triggering a
```
WorkflowRun
```
, runtime log tail, pod-level debugging via
```
kubectl exec
```
.
```
WorkflowRun
```
does not go in Git (per
```
gitops/overview.md
```
); trigger via the UI, webhook, or
```
occ component workflow run
```
. For pod-level runtime debugging, use
```
kubectl
```
directly against the data plane or the cluster's observability backend.
Editing GitOps-managed resources via
occ apply -f
or any other direct write path — Flux reverts them on the next reconcile. Always go through Git.

仓库脚手架搭建或Flux配置。不在范围内；假设仓库已完成脚手架搭建且Flux已配置。
编写ComponentTypes / Traits / Workflows。属于平台侧操作。从
```
occ clustercomponenttype list
```
/
```
occ clustertrait list
```
/
```
occ clusterworkflow list
```
的结果中选择；开发者仅能附加平台提供的内容。
Plane注册、AuthzRole / SecretReference编写。属于平台侧操作。
命令式操作 — 触发
```
WorkflowRun
```
、实时日志查看、通过
```
kubectl exec
```
进行Pod级调试。
```
WorkflowRun
```
不应存入Git（参考
```
gitops/overview.md
```
）；需通过UI、Webhook或
```
occ component workflow run
```
触发。对于Pod级实时调试，请直接针对数据平面或集群可观测性后端使用
```
kubectl
```
。
通过
occ apply -f
或其他直接写入方式编辑GitOps管理的资源 — Flux会在下一次同步时将其还原。请始终通过Git进行操作。

Working style

工作风格

Git is the source of truth. Application resources change only through Git.
```
occ apply -f
```
is reserved for pre-Flux bootstrap (which is a PE concern; this skill rarely needs it).
Use
occ
file-mode generators for the four kinds they own (Workload, ComponentRelease, ReleaseBinding, Component scaffold). For everything else (Project, dependency wiring on a Workload, ReleaseBinding overrides), fetch the full schema with
```
./scripts/fetch-page.sh --exact --title "<Kind>"
```
.
Always
git commit -s
(DCO is required upstream; harmless on forks).
Verify, don't assume. Reconciliation is interval-based (
```
GitRepository: 1m
```
,
```
Kustomization: 5m
```
). Read the result back with
```
occ <kind> get
```
after merge.
Don't open a PR or push without explicit user confirmation. Local commits are reversible; remote-visible actions are not.
Path A vs Path B for source-build Workloads. Decide once whether
```
workload.yaml
```
in the source repo is the source of truth (Path A) or direct edits to the Workload CR in the GitOps repo are (Path B). Mixing them is a one-way migration trap. See
```
recipes/onboard-component-source-build.md
```
.

Git是事实来源。应用资源仅能通过Git变更。
```
occ apply -f
```
仅用于Flux引导前的场景（属于PE职责；本技能极少需要使用）。
对四种资源使用
occ
文件模式生成器（Workload、ComponentRelease、ReleaseBinding、Component脚手架）。对于其他所有资源（Project、工作负载的依赖连接、ReleaseBinding覆盖），使用
```
./scripts/fetch-page.sh --exact --title "<Kind>"
```
获取完整schema。
始终执行
git commit -s
（上游要求DCO；在分支上执行无影响）。
验证而非假设。同步是基于时间间隔的（
```
GitRepository: 1分钟
```
，
```
Kustomization: 5分钟
```
）。合并后通过
```
occ <kind> get
```
读取结果。
未经用户明确确认，请勿推送或提交PR。本地提交可撤销；远程可见操作不可撤销。
源码构建工作负载的路径A与路径B。需一次性决定是将源码仓库中的
```
workload.yaml
```
作为事实来源（路径A），还是直接编辑GitOps仓库中的Workload CR（路径B）。混合使用会陷入单向迁移陷阱。参考
```
recipes/onboard-component-source-build.md
```
。

Stable guardrails

稳定准则

ComponentRelease
is immutable. Regenerate with
```
occ componentrelease generate
```
; never hand-edit.
Workload.spec.owner
(projectName + componentName) is immutable after creation. Pick names carefully.
Component.spec.componentType
and
spec.workflow
kinds default to cluster-scoped when omitted. Set
```
kind: ComponentType
```
/
```
kind: Workflow
```
explicitly when referencing namespace-scoped variants.
Project.spec.deploymentPipelineRef
is an object (since v1.0.0), not a plain string.
```
kind
```
defaults to
```
DeploymentPipeline
```
.
For third-party / public apps: default to BYO image, not source build. Multi-platform Dockerfiles (
```
ARG BUILDPLATFORM
```
) commonly fail in the buildah-based builder. If you see exit-125
```
BUILDPLATFORM
```
errors, switch to BYO.
No plaintext secrets in Git. Use a PE-authored
```
SecretReference
```
; consume from a Workload via
```
valueFrom.secretKeyRef
```
.
Workload
env
/
files
entries need exactly one of
value
or
valueFrom
— not both, not neither. Validation fails otherwise.

ComponentRelease
是不可变的。需通过
```
occ componentrelease generate
```
重新生成；切勿手动编辑。
Workload.spec.owner
（projectName + componentName）创建后不可变。请谨慎选择名称。
当省略时，
Component.spec.componentType
与
spec.workflow
类型默认为集群级。引用命名空间级变体时，请显式设置
```
kind: ComponentType
```
/
```
kind: Workflow
```
。
Project.spec.deploymentPipelineRef
是一个对象（自v1.0.0起），而非纯字符串。
```
kind
```
默认为
```
DeploymentPipeline
```
。
对于第三方/公共应用：默认使用自带镜像，而非源码构建。多平台Dockerfile（
```
ARG BUILDPLATFORM
```
）在基于buildah的构建器中常失败。若遇到exit-125
```
BUILDPLATFORM
```
错误，请切换为自带镜像。
Git中不得包含明文密钥。使用PE编写的
```
SecretReference
```
；通过Workload的
```
valueFrom.secretKeyRef
```
引用。
Workload的
env
/
files
条目必须且仅能包含
value
或
valueFrom
中的一个 — 不可同时存在，也不可都不存在。否则验证会失败。

Anti-patterns

反模式

Creating a Component without first reading the available
```
ClusterComponentType
```
/
```
ComponentType
```
/
```
Trait
```
/
```
Workflow
```
lists on the cluster. Author the spec against the live platform shape.
Hand-authoring a Workload spec when
```
occ workload create --mode file-system
```
could do it from a descriptor + image.
Hand-editing a
```
ComponentRelease
```
file (it's immutable; regenerate instead).
Adding
```
workload.yaml
```
to a source repo whose Component's Workload has been iterated on directly (Path B) without first dumping the live Workload and reconstructing the descriptor (one-way destructive migration — overwrites the cluster spec).
Setting
```
visibility: external
```
on a service-to-service dependency between Components in the same project —
```
project
```
is the right default.
```
external
```
is for public-internet ingress only.
Pushing or opening a PR before the user has seen the commit list.
Assuming a deployment is healthy because
```
Ready=True
```
—
```
Ready
```
means reconciled, not necessarily working. Curl an
```
external
```
endpoint or pull logs via
```
occ component logs <component> -n <ns> --env <env>
```
when in doubt.

在未先查看集群上可用的
```
ClusterComponentType
```
/
```
ComponentType
```
/
```
Trait
```
/
```
Workflow
```
列表的情况下创建组件。需根据平台实际形态编写spec。
当
```
occ workload create --mode file-system
```
可通过描述文件+镜像生成时，手动编写Workload spec。
手动编辑
```
ComponentRelease
```
文件（它是不可变的；应重新生成）。
直接迭代组件的Workload后（路径B），将
```
workload.yaml
```
添加到源码仓库，而未先导出当前Workload并重建描述文件（单向破坏性迁移——会覆盖集群spec）。
对同一项目内组件间的服务依赖设置
```
visibility: external
```
—
```
project
```
是正确的默认值。
```
external
```
仅适用于公网入口。
在用户查看提交列表前推送或提交PR。
仅因
```
Ready=True
```
就假设部署健康 —
```
Ready
```
表示已同步，而非一定可用。若有疑问，请调用
```
external
```
端点或通过
```
occ component logs <component> -n <ns> --env <env>
```
拉取日志。