flux-gitops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flux GitOps Platform

Flux GitOps平台

The homelab Kubernetes platform uses Flux ResourceSets for centralized, declarative management of Helm releases and configurations.

For ResourceSet patterns, version management, and platform architecture, see kubernetes/platform/CLAUDE.md.

家庭实验室Kubernetes平台使用Flux ResourceSets对Helm版本和配置进行集中式声明式管理。

关于ResourceSet模式、版本管理和平台架构，请参阅kubernetes/platform/CLAUDE.md。

How to Add a New Helm Release

如何添加新的Helm版本

Step 1: Add to helm-charts.yaml

步骤1：添加到helm-charts.yaml

Add an entry to the

inputs

array:

yaml

inputs:
  - name: "my-new-chart"           # Unique release name (kebab-case)
    namespace: "my-namespace"       # Target namespace
    chart:
      name: "actual-chart-name"    # Chart name in repository
      version: "1.0.0"             # Pinned version
      url: "https://example.com/charts"  # Helm repository URL
    dependsOn: [cilium]            # Array of release names this depends on

For OCI registries:

yaml

    chart:
      name: "app-template"
      version: "3.6.1"
      url: "oci://ghcr.io/bjw-s/helm"  # Prefix with oci://

在

inputs

数组中添加条目：

yaml

inputs:
  - name: "my-new-chart"           # Unique release name (kebab-case)
    namespace: "my-namespace"       # Target namespace
    chart:
      name: "actual-chart-name"    # Chart name in repository
      version: "1.0.0"             # Pinned version
      url: "https://example.com/charts"  # Helm repository URL
    dependsOn: [cilium]            # Array of release names this depends on

对于OCI注册表：

yaml

    chart:
      name: "app-template"
      version: "3.6.1"
      url: "oci://ghcr.io/bjw-s/helm"  # Prefix with oci://

Step 2: Create Values File

步骤2：创建Values文件

Create

charts/<release-name>.yaml

with Helm values:

yaml

undefined

创建

charts/<release-name>.yaml

文件并写入Helm配置值：

yaml

undefined

yaml-language-server: $schema=<chart-schema-url>

Helm values for the chart

replicas: 1 image: repository: myapp tag: v1.0.0

undefined

replicas: 1 image: repository: myapp tag: v1.0.0

undefined

Step 3: Add to kustomization.yaml

步骤3：添加到kustomization.yaml

Add the values file to the

configMapGenerator

yaml

configMapGenerator:
  - name: platform-values
    files:
      # ... existing entries
      - charts/my-new-chart.yaml

将Values文件添加到

configMapGenerator

中：

yaml

configMapGenerator:
  - name: platform-values
    files:
      # ... existing entries
      - charts/my-new-chart.yaml

Step 4: Add Config Resources (Optional)

步骤4：添加配置资源（可选）

If the chart needs additional resources (secrets, configs), add to

config/

config/my-new-chart/
├── kustomization.yaml
├── secret.yaml
└── config.yaml

Then reference in

config.yaml

ResourceSet.

如果该Chart需要额外资源（如密钥、配置），请添加到

config/

config/my-new-chart/
├── kustomization.yaml
├── secret.yaml
└── config.yaml

然后在

config.yaml

ResourceSet中引用该目录。

Step 5: Verify PodSecurity Compliance

步骤5：验证PodSecurity合规性

Before finalizing values, check the target namespace's PodSecurity level in

namespaces.yaml

Identify the namespace security level: Look for
```
security: restricted
```
,
```
baseline
```
, or
```
privileged
```
in the namespace inputs
If
restricted
: Add full security context to chart values (see below)
Check the container image's default user: If it runs as root, set
```
runAsUser: 65534
```
Verify all init containers and sidecars also have security context set

Required security context for
restricted
namespaces:

yaml

undefined

在最终确定配置值之前，请检查目标命名空间在

namespaces.yaml

中的PodSecurity级别：

确定命名空间安全级别：在命名空间输入中查找
```
security: restricted
```
、
```
baseline
```
或
```
privileged
```
字段
如果是
restricted
级别：在Chart配置值中添加完整的安全上下文（见下文）
检查容器镜像的默认用户：如果镜像以root用户运行，请设置
```
runAsUser: 65534
```
验证所有初始化容器和边车容器也已设置安全上下文

restricted
级命名空间所需的安全上下文：

yaml

undefined

Pod-level (chart-specific key varies: podSecurityContext, securityContext, pod.securityContext)

Pod级（Chart对应的键可能不同：podSecurityContext、securityContext、pod.securityContext）

podSecurityContext: runAsNonRoot: true seccompProfile: type: RuntimeDefault

Container-level (every container)

容器级（每个容器都需要）

securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"] readOnlyRootFilesystem: true runAsNonRoot: true seccompProfile: type: RuntimeDefault


**Restricted namespaces**: cert-manager, external-secrets, system, database, kromgo. See [kubernetes/platform/CLAUDE.md](../../kubernetes/platform/CLAUDE.md) for the full list.

**Validation gap**: `task k8s:validate` does NOT catch PodSecurity violations. These are only caught at admission time in the cluster.

securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"] readOnlyRootFilesystem: true runAsNonRoot: true seccompProfile: type: RuntimeDefault


**Restricted级命名空间列表**：cert-manager、external-secrets、system、database、kromgo。完整列表请参阅[kubernetes/platform/CLAUDE.md](../../kubernetes/platform/CLAUDE.md)。

**验证缺口**：`task k8s:validate`无法检测PodSecurity违规，这些违规仅会在集群准入阶段被捕获。

ResourceSet Template Syntax

ResourceSet模板语法

The

resourcesTemplate

uses Go text/template with

<<

>>

delimiters:

yaml

resourcesTemplate: |
  apiVersion: helm.toolkit.fluxcd.io/v2
  kind: HelmRelease
  metadata:
    name: << inputs.name >>
    namespace: << inputs.provider.namespace >>
  spec:
    <<- if inputs.dependsOn >>
    dependsOn:
    <<- range $dep := inputs.dependsOn >>
      - name: << $dep >>
    <<- end >>
    <<- end >>
    chart:
      spec:
        chart: << inputs.chart.name >>
        version: << inputs.chart.version >>

resourcesTemplate

使用Go text/template模板，分隔符为

<<

>>

：

yaml

resourcesTemplate: |
  apiVersion: helm.toolkit.fluxcd.io/v2
  kind: HelmRelease
  metadata:
    name: << inputs.name >>
    namespace: << inputs.provider.namespace >>
  spec:
    <<- if inputs.dependsOn >>
    dependsOn:
    <<- range $dep := inputs.dependsOn >>
      - name: << $dep >>
    <<- end >>
    <<- end >>
    chart:
      spec:
        chart: << inputs.chart.name >>
        version: << inputs.chart.version >>

Template Functions

模板函数

```
<< inputs.field >>
```
- Access input field
```
<<- if condition >>
```
- Conditional (with
```
-
```
to trim whitespace)
```
<<- range $item := inputs.array >>
```
- Loop over array
```
hasPrefix "oci://" inputs.chart.url
```
- String prefix check

```
<< inputs.field >>
```
- 访问输入字段
```
<<- if condition >>
```
- 条件判断（
```
-
```
用于修剪空白）
```
<<- range $item := inputs.array >>
```
- 遍历数组
```
hasPrefix "oci://" inputs.chart.url
```
- 字符串前缀检查

Dependency Management

依赖管理

Release Dependencies

版本依赖

yaml

inputs:
  - name: "grafana"
    dependsOn: [kube-prometheus-stack, alloy]  # Waits for these

yaml

inputs:
  - name: "grafana"
    dependsOn: [kube-prometheus-stack, alloy]  # 等待这些版本就绪

ResourceSet Dependencies

ResourceSet依赖

yaml

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: platform-namespaces  # Waits for namespaces ResourceSet

yaml

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: platform-namespaces  # 等待命名空间ResourceSet就绪

Debugging Flux

调试Flux

Check ResourceSet Status

检查ResourceSet状态

bash

kubectl get resourcesets -n flux-system
kubectl describe resourceset platform-resources -n flux-system

bash

kubectl get resourcesets -n flux-system
kubectl describe resourceset platform-resources -n flux-system

Check HelmRelease Status

检查HelmRelease状态

bash

kubectl get helmreleases -A
kubectl describe helmrelease <name> -n <namespace>

bash

kubectl get helmreleases -A
kubectl describe helmrelease <name> -n <namespace>

Check Reconciliation Logs

检查调和日志

bash

kubectl logs -n flux-system deploy/flux-controller -f | grep <release-name>

bash

kubectl logs -n flux-system deploy/flux-controller -f | grep <release-name>

Force Reconciliation

强制调和

bash

flux reconcile helmrelease <name> -n <namespace>
flux reconcile kustomization flux-system -n flux-system

bash

flux reconcile helmrelease <name> -n <namespace>
flux reconcile kustomization flux-system -n flux-system

Common Issues

常见问题

Symptom	Cause	Solution
`waiting for dependencies`	Dependency not ready	Check `dependsOn` releases
`values key not found`	Missing values file	Add to kustomization.yaml configMapGenerator
`chart not found`	Wrong chart name/URL	Verify chart exists in repository
`namespace not found`	Namespace not created	Add to namespaces.yaml

症状	原因	解决方案
`waiting for dependencies`	依赖未就绪	检查 `dependsOn` 中指定的版本
`values key not found`	缺少Values文件	添加到kustomization.yaml的configMapGenerator中
`chart not found`	Chart名称/URL错误	验证Chart在仓库中是否存在
`namespace not found`	命名空间未创建	添加到namespaces.yaml中

Version Management

版本管理

When adding a new Helm release, you must also add a version entry to

kubernetes/platform/versions.env

with the correct Renovate annotation. Use

${variable_name}

helm-charts.yaml

to reference the version:

yaml

chart:
  version: "${my_chart_version}"  # Substituted from platform-versions ConfigMap

For annotation syntax, datasource selection, and debugging Renovate, see the versions-renovate skill.

添加新的Helm版本时，您还必须在

kubernetes/platform/versions.env

中添加版本条目，并附带正确的Renovate注解。在

helm-charts.yaml

中使用

${variable_name}

引用该版本：

yaml

chart:
  version: "${my_chart_version}"  # 从platform-versions ConfigMap中替换

关于注解语法、数据源选择和Renovate调试，请参阅versions-renovate技能。

OCI Registry Specifics

OCI注册表注意事项

When using OCI registries like GHCR:

yaml

chart:
  name: "app-template"           # Just the chart name
  version: "3.6.1"
  url: "oci://ghcr.io/bjw-s/helm"  # Registry URL with oci:// prefix

The ResourceSet template automatically detects OCI URLs and sets

type: oci

on the HelmRepository.

使用GHCR等OCI注册表时：

yaml

chart:
  name: "app-template"           # 仅填写Chart名称
  version: "3.6.1"
  url: "oci://ghcr.io/bjw-s/helm"  # 以oci://为前缀的注册表URL

ResourceSet模板会自动检测OCI URL，并在HelmRepository中设置

type: oci

。