导入单位粒度
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 运维部署
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# import-unit-granularity
A decision helper for one question: **how many Units, and what goes in each?** Produces a concrete split — Unit slugs + the `--where-resource` predicate (or equivalent) for each — and hands off to the import skill that will execute it.
## When to use
- User has a YAML bundle, a rendered chart, a namespace full of running resources, or a pile of overlays, and is asking "should this be one Unit or several?"
- User has already picked an import path (`import-from-helm` / `-kustomize` / `-argocd` / `-flux` / `-cluster`) but is unsure how many Units it should produce.
- User is mid-import and wants to validate the split before running the command.
## Do not load for
- Authoring new YAML from scratch — use `config-as-data`.
- Running the actual import — hand off to the matching `import-from-*` skill after the decision is made here.
- Decisions about *where* the Units go (which Space) — that's `space-topology`.
- Cases where the tool already decided for the user: `cub helm install` always produces `<release>` + `<release>-crds`; `cub gitops import` always produces dry + wet + crds with the right link predicates. Don't re-litigate their defaults.
## Rules, in priority order
### 1. CRDs always in their own Unit
Independent of everything else, CustomResourceDefinitions go in a Unit separate from anything that uses them. This is not negotiable:
- CRDs must be applied and established before the custom resources that reference them (`kubectl wait --for=condition=established`). Separate Units let you sequence apply cleanly without a shell script around one big Unit.
- CRDs have different lifecycle and blast radius than workloads: deleting a CRD cascades to every CR; deleting a Deployment doesn't.
- `cub helm install` and `cub gitops import` already split CRDs (`<release>-crds` / `-crds` wet Unit linked with `where-resource "kind = 'CustomResourceDefinition'"`). Hand-rolled imports should match.
Slug convention: `<app>-crds`.
### 2. Rendered from a generator → keep as one bundle (minus CRDs)
If the source is Helm, Kustomize, Argo, or Flux, the generator already reasoned about what belongs together. Don't re-split unless there's a concrete reason. One workload-Unit + one CRDs-Unit is the default.
Reasons that *would* justify further splitting from a generator:
- The chart ships with its own cluster-scoped resources (ClusterRole, StorageClass, PriorityClass) mixed with namespaced workloads and you need to grant different permissions — split cluster-scoped into its own Unit.
- The chart bundles an operator *and* instances of the operator's CRs — split the CRs out so they have a different change cadence.
- The user needs ApplyGates or approval policies that differ across parts of the chart.
Otherwise, one Unit. Run `cub helm install` or `cub gitops import` and stop.
### 3. Hand-rolled or `import-from-cluster` → split by Kubernetes best practices
When there's no generator to defer to, split by how the resources actually want to be operated. Axes, in order:
- **Ownership.** Who edits this? Platform team vs. app team. Different owners ⇒ different Units.
- **References.** Does resource A not work without resource B? They stay together.
- **Lifecycle.** Does this change daily vs. monthly vs. yearly? Different cadences ⇒ different Units, so low-churn config doesn't generate revision noise.
- **Blast radius.** If I break this, what else breaks? Contain the blast in a single Unit.
## Recommended groupings (for hand-rolled / cluster imports)
| Unit slug | Contents | Rationale |
|---|---|---|
| `<ns>-namespace` | The `Namespace` resource itself | Cluster-scoped; platform-team owned; changes almost never; different lifecycle from anything inside the namespace. |
| `<ns>-policy` | `NetworkPolicy`, `ServiceAccount`, `Role`, `RoleBinding`, per-namespace `ResourceQuota`, `LimitRange` | Namespace-scoped policy; usually platform- or platform-plus-app co-owned; changes with policy updates, not app releases. |
| `<app>` | `Deployment` (or `StatefulSet` / `DaemonSet`), `Service`, `ConfigMap`, `HorizontalPodAutoscaler`, `PodDisruptionBudget`, `ServiceMonitor` | App-team owned; day-to-day change cadence; tightly cross-referenced. Blast radius is the workload. |
| `<app>-crds` | Any CRDs the app ships | Lifecycle + apply-order distinct from the workload. |
| `<infra>-cluster` | `ClusterRole`, `ClusterRoleBinding`, `StorageClass`, `PriorityClass`, cluster-scoped `CRDs` | Cluster-wide blast radius; typically platform-team owned. |
| `<operator>-crs` | Custom resources (`Certificate`, `HelmRelease`, etc.) | Referenced resources; change independently of the operator itself. |
Multi-workload apps: one `<app>` Unit per workload (`<app>-api`, `<app>-worker`), not one mega-Unit with every workload — they usually have different replica counts, different canary policies, and different incident ownership.
## Anti-patterns
- **One Unit per resource by default.** Only split that far when a specific resource truly has its own lifecycle (e.g., a ConfigMap rotated by a separate process). Otherwise it's noise: twice the revisions, twice the ApplyGates, cross-referenced resources that must be applied in order but live in different Units.
- **Everything in one Unit (including CRDs).** Apply-order breaks (`CRD` not established before `CR`), rollback of a workload accidentally takes down its CRDs.
- **Cluster-scoped mixed with namespaced.** Different permissions to apply; different ownership; different blast radius. Splits cleanly along the line cub already draws for `import.include_cluster`.
- **Splitting purely by `kind`.** Doesn't map to ownership or lifecycle; produces "all ConfigMaps" or "all Services" Units that cut across unrelated apps.
## The splitting trick (for `cub unit import` and hand rolls)
To execute a split with `cub unit import`: pre-create each Unit, bind it to the same cluster Target, then call `cub unit import` per Unit with a scoped `--where-resource`. This is exactly what `cub gitops import` does internally when it splits CRDs off the wet Unit.
Example for splitting a namespace's state into three Units:
```bash
SPACE=<app>-<env>
TARGET=<workers-space>/<cluster-target>
NS=<namespace>
# Shell
for u in <ns>-namespace <ns>-policy <app> <app>-crds; do
cub unit create --space "$SPACE" "$u"
cub unit set-target --space "$SPACE" "$u" "$TARGET"
done
# CRDs (cluster-scoped; needs include_cluster)
cub unit import --space "$SPACE" <app>-crds \
--where-resource "kind = 'CustomResourceDefinition' AND import.include_cluster = true AND metadata.labels.app = '<app>'" \
--dry-run
# Namespace (cluster-scoped; platform-team owned).
cub unit import --space "$SPACE" <ns>-namespace \
--where-resource "kind = 'Namespace' AND metadata.name = '$NS' AND import.include_cluster = true" \
--dry-run
# Namespace-scoped policy (NetworkPolicy, RBAC, ResourceQuota, LimitRange).
# `--where-resource` supports AND only — if you'd want Namespace + policy in a
# single Unit, do two imports into separate Units rather than trying to OR.
cub unit import --space "$SPACE" <ns>-policy \
--where-resource "metadata.namespace = '$NS' AND kind IN ('NetworkPolicy','ServiceAccount','Role','RoleBinding','ResourceQuota','LimitRange')" \
--dry-run
# Workload
cub unit import --space "$SPACE" <app> \
--where-resource "metadata.namespace = '$NS' AND kind IN ('Deployment','StatefulSet','DaemonSet','Service','ConfigMap','HorizontalPodAutoscaler','PodDisruptionBudget','ServiceMonitor') AND metadata.labels.app = '<app>'" \
--dry-run
```
Dry-run each, confirm the resource set, then re-run without `--dry-run`. Same pattern for Helm-rendered bundles split by hand: store the output of `helm template` in files, then `cub unit create` each from its scoped file. (Though unless you have a specific reason, `cub helm install` already does CRD splitting correctly — prefer it.)
## The decision flow
1. What's the source? → Helm / Kustomize / ArgoCD / Flux / live cluster / hand-rolled YAML.
2. If a generator, default to `<release>` + `<release>-crds` (Helm) or dry/wet/crds (Argo/Flux) per the matching import skill. Only split further if ownership / lifecycle / blast radius diverge within the render.
3. If hand-rolled or cluster-imported: walk the four axes (ownership, references, lifecycle, blast radius). Map to the recommended groupings above. Produce slugs and `--where-resource` predicates.
4. Hand off to the right `import-from-*` skill for execution.
## Preflight (for making a recommendation)
1. User has told you the source (Helm / Kustomize / ArgoCD / Flux / cluster / hand-rolled). If not, ask once.
2. For cluster / hand-rolled cases: `kubectl get -n <ns> -o yaml > /tmp/inventory.yaml` or a similar inventory is available for reference — you need to see what's actually there before prescribing a split.
3. User has picked a Space layout per `space-topology` (or will as part of this). Units don't exist in a vacuum.
## Tool boundary
Read-only and decision-making only. `kubectl get`, `cub ... list/get` to inspect inventory. No `cub unit create / import / update` — hand that off to the specialized import skill after the decision is made.
## Stop conditions
- User hasn't disclosed the source. Ask; don't guess.
- User is importing generator-rendered output and wants a per-resource split without a stated reason. Push back: match the generator's bundle + CRD split.
- User is hand-rolling and insists on one mega-Unit including CRDs. Push back: CRD separation is non-negotiable for apply-order correctness.
## Verify chain
There's nothing to apply here; the skill's output is a split proposal. The user (or the import skill called next) verifies by running `--dry-run` and reviewing the per-Unit resource set before importing.
## Evidence
- `kubectl get -n <ns> --show-labels` — source inventory the recommendation was based on.
- The matching import skill's Evidence section once execution starts.
## References
- `references/cub-cli.md` — `--where-resource` / `--where-data` scoping mechanics (including `ConfigHub.ResourceType`, `ConfigHub.ResourceName`, `import.include_system`, `import.include_cluster`, `import.include_custom`).
- `https://docs.confighub.com/markdown/guide/rendered-manifests.md` — the `cub gitops import` splitting flow this skill mirrors.
- `https://docs.confighub.com/markdown/guide/helm-charts.md` — `cub helm install` release + crds default.
- Companion skills: `space-topology` (where the Units go), `import-from-helm`, `import-from-kustomize`, `import-from-argocd`, `import-from-flux`, `import-from-cluster`, `config-as-data` (post-import doctrine).
---
> Source: [confighub/confighub-skills](https://github.com/confighub/confighub-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用
不要加载
1. CRD 始终位于自己的单元中
2. 从生成器渲染 → 保留为一个包(减去 CRD)
3. 手动滚动或从集群导入 → 按 Kubernetes 最佳实践进行拆分
文件/命令 -> --where-resource · import-from-helm · -kustomize · -argocd · -flux · -cluster · config-as-data · import-from-*
内容校验值 -> 048be61d05cd
当前原文的自动摘译,尚未人工审校。
何时使用
用户有一个 YAML 包、一个渲染的图表、一个充满运行资源的命名空间或一堆覆盖层,并且询问“这应该是一个单元还是多个单元?”用户已经选择了导入路径(
import-from-helm/-kustomize/-argocd/-flux/-cluster),但不确定应该生产多少单位。用户正在导入过程中,希望在运行命令之前验证分割。不要加载
从头开始编写新的 YAML — 使用
config-as-data。运行实际的导入——在此处做出决定后将其移交给匹配的import-from-*技能。关于单位去哪里(哪个空间)的决定——那就是space-topology。工具已经为用户决定的情况:cub helm install总是生成<release>+<release>-crds;cub gitops import总是使用正确的链接谓词生成干+湿+crd。不要对他们的违约行为重新提起诉讼。1. CRD 始终位于自己的单元中
独立于其他一切,CustomResourceDefinitions 位于与使用它们的任何东西分开的单元中。这是不可协商的:CRD 必须在引用它们的自定义资源之前应用和建立 (
kubectl wait --for=condition=established)。单独的单元让您可以干净地排序应用,无需围绕一个大单元使用 shell 脚本。 CRD 与工作负载具有不同的生命周期和爆炸半径:删除 CRD 会级联到每个 CR;删除部署则不会。2. 从生成器渲染 → 保留为一个包(减去 CRD)
如果源是 Helm、Kustomize、Argo 或 Flux,则生成器已经推理出哪些内容属于同一组。除非有具体原因,否则不要重新分割。默认为 1 个工作负载单元 + 1 个 CRD 单元。 将证明从生成器进一步拆分的理由:图表附带了自己的集群范围资源(ClusterRole、StorageClass、PriorityClass),与命名空间工作负载混合,您需要授予不同的权限 - 将集群范围拆分为自己的单元。
3. 手动滚动或从集群导入 → 按 Kubernetes 最佳实践进行拆分
当没有可以遵循的生成器时,按资源实际想要的操作方式进行划分。轴,按顺序:所有权。谁编辑这个?平台团队与应用程序团队。不同的所有者⇒不同的单位。参考。如果没有资源 B,资源 A 就无法工作吗?他们呆在一起。生命周期。每天、每月、每年都会发生变化吗?不同的节奏⇒不同的单位,因此低流失配置不会产生修订噪音。