mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-14 10:30:59 +00:00
add zh docsy
This commit is contained in:
guoxudong
11
site/content/zh/api-reference/_index.md
Normal file
11
site/content/zh/api-reference/_index.md
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: "API 参考"
|
||||
linkTitle: "API 参考"
|
||||
type: docs
|
||||
weight: 4
|
||||
menu:
|
||||
main:
|
||||
weight: 40
|
||||
description: >
|
||||
Kustomize 客户端 API 参考。
|
||||
---
|
||||
311
site/content/zh/api-reference/glossary/_index.md
Normal file
311
site/content/zh/api-reference/glossary/_index.md
Normal file
@@ -0,0 +1,311 @@
|
||||
---
|
||||
title: "术语表"
|
||||
linkTitle: "术语表"
|
||||
type: docs
|
||||
weight: 99
|
||||
description: >
|
||||
术语表
|
||||
---
|
||||
|
||||
[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
|
||||
[CRD]: #custom-resource-definition
|
||||
[DAM]: #declarative-application-management
|
||||
[Declarative Application Management]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md
|
||||
[JSON]: https://www.json.org/
|
||||
[JSONPatch]: https://tools.ietf.org/html/rfc6902
|
||||
[JSONMergePatch]: https://tools.ietf.org/html/rfc7386
|
||||
[Resource]: #resource
|
||||
[YAML]: http://www.yaml.org/start.html
|
||||
[application]: #application
|
||||
[apply]: #apply
|
||||
[apt]: https://en.wikipedia.org/wiki/APT_(Debian)
|
||||
[base]: #base
|
||||
[bases]: #base
|
||||
[bespoke]: #bespoke-configuration
|
||||
[gitops]: #gitops
|
||||
[k8s]: #kubernetes
|
||||
[kubernetes]: #kubernetes
|
||||
[kustomize]: #kustomize
|
||||
[kustomization]: #kustomization
|
||||
[kustomizations]: #kustomization
|
||||
[off-the-shelf]: #off-the-shelf-configuration
|
||||
[overlay]: #overlay
|
||||
[overlays]: #overlay
|
||||
[patch]: #patch
|
||||
[patches]: #patch
|
||||
[patchJson6902]: #patchjson6902
|
||||
[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md
|
||||
[patchesJson6902]: #patchjson6902
|
||||
[proposal]: https://github.com/kubernetes/community/pull/1629
|
||||
[rebase]: https://git-scm.com/docs/git-rebase
|
||||
[resource]: #resource
|
||||
[resources]: #resource
|
||||
[root]: #kustomization-root
|
||||
[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
|
||||
[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md
|
||||
[target]: #target
|
||||
[transformer]: #transformer
|
||||
[variant]: #variant
|
||||
[variants]: #variant
|
||||
[workflow]: /kustomize/zh/guides
|
||||
|
||||
## 应用
|
||||
|
||||
**应用**是为某种目的关联起来的一组 Kubernetes 资源，例如一个前有负载均衡器，后有数据库的 Web 服务器。用标签、命名和元数据将[资源]组织起来，可以进行**添加**或**删除**等操作。
|
||||
|
||||
有提案（[Declarative Application Management]）描述了一种称为应用的新的 Kubernetes 资源。更加正式的描述了这一思路，并在应用程序级别提供了运维和仪表盘的支持。
|
||||
|
||||
[Kustomize] 对 Kubernetes 资源进行配置，其中描述的应用程序资源只是另一种普通的资源。
|
||||
|
||||
## apply
|
||||
|
||||
**Apply** 这个动词在 Kubernetes 的上下文中，指的是一个 Kubernetes 命令以及能够对集群施加影响的进程内 [API 端点](https://goo.gl/UbCRuf)。
|
||||
|
||||
用户可以将对集群的运行要求用一组完整的资源列表的形式进行表达，通过 **apply** 命令进行提交。
|
||||
|
||||
集群把新提交的资源和之前提交的状态以及当前的实际状态进行合并，形成新的状态。这就是 Kubernetes 的状态管理过程。
|
||||
|
||||
## base
|
||||
|
||||
**Base** 指的是会被其它 [Kustomization] 引用的 [Kustomization]。
|
||||
|
||||
包括 [Overlay] 在内的任何 Kustomization，都可以作为其它 Kustomization 的 Base。
|
||||
|
||||
Base 对引用自己的 Overlay 并无感知。
|
||||
|
||||
Base 和 [Overlay] 可以作为 Git 仓库中的唯一内容，用于简单的 [GitOps] 管理。对仓库的变更可以触发构建、测试以及部署过程。
|
||||
|
||||
## 定制配置
|
||||
|
||||
**定制**配置是由组织为满足自身需要，在内部创建和管理的 [Kustomization] 和[资源]。
|
||||
|
||||
和**定制配置**关联的 [Workflow] 比关联到通用配置的 [Workflow] 要简单一些，原因是通用配置是共享的，需要周期性的跟踪他人作出的变更。
|
||||
|
||||
## custom resource definition
|
||||
|
||||
可以通过定制 CRD ([CRD spec]) 的方式对 Kubernetes API 进行扩展。
|
||||
|
||||
CRD 定义的[资源]是一种全新的资源，可以和 ConfigMap、Deployment 之类的原生资源以相同的方式来使用。
|
||||
|
||||
Kustomize 能够生成自定义资源，但是要完成这个目标，必须给出对应的 CRD，这样才能正确的对这种结构进行处理。
|
||||
|
||||
## 声明式应用程序管理
|
||||
|
||||
Kustomize 鼓励对声明式应用程序管理（[Declarative Application Management]）的支持，这种方式是一系列 Kubernetes 集群管理的最佳实践。Kustomize 应该可以：
|
||||
|
||||
- 适用于任何配置，例如自有配置、共享配置、无状态、有状态等。
|
||||
- 支持通用配置，以及创建变体（例如开发、预发布、生产）。
|
||||
- 开放使用原生 Kubernetes API，而不是隐藏它们。
|
||||
- 不会给版本控制系统和集成的评审和审计工作造成困难。
|
||||
- 用 Unix 的风格和其它工具进行协作。
|
||||
- 避免使用模板、领域特定的语言等额外的学习内容。
|
||||
|
||||
## 生成器
|
||||
|
||||
生成器生成的资源，可以直接使用，也可以输出给转换器（[transformer]）。
|
||||
|
||||
## gitops
|
||||
|
||||
**Kustomization** 这个词可以指 `kustomization.yaml` 这个文件，更常见的情况是一个包含了 `kustomization.yaml` 及其所有直接引用文件的相对路径（所有不需要 URL 的本地数据）。
|
||||
|
||||
也就是说，如果在 [Kustomize] 的上下文中说到 **Kustomization**，可能是以下的情况之一：
|
||||
|
||||
- 一个叫做 `kustomization.yaml` 的文件。
|
||||
- 一个压缩包（包含 YAML 文件以及它的引用文件）。
|
||||
- 一个 Git 压缩包。
|
||||
- 一个 Git 仓库的 URL。
|
||||
|
||||
一个 Kustomization 文件包含的[字段](fields.md)，分为四个类别：
|
||||
|
||||
- `resources`：待定制的现存[资源]，示例字段：`resources`、`crds`。
|
||||
- `generator`：将要创建的**新**资源，示例字段：`configMapGenerator`（传统）、`secretGenerator`（传统）、`generators`（v2.1）
|
||||
- `transformer`：对前面提到的新旧资源进行**处理**的方式。示例字段：`namePrefix`、`nameSuffix`、`images`、`commonLabels`、`patchesJson6902` 等。在 v2.1 中还有更多的 `transformer`。
|
||||
- `meta`：会对上面几种字段产生影响。示例字段：`vars`、`namespace`、`apiVersion`、`kind` 等。
|
||||
|
||||
## kustomization root
|
||||
|
||||
直接包含 `kustomization.yaml` 文件的目录。
|
||||
|
||||
处理 Kustomization 文件时，可能访问到该目录以内或以外的文件。
|
||||
|
||||
像 YAML 资源这样的数据文件，或者用于生成 ConfigMap 或 Secret 的包含 `name=value` 的文本文件，或者用于补丁转换的补丁文件，必须**在这个目录的内部**，需要显式的使用**相对路径**来表达。
|
||||
|
||||
v2.1 中有一个特殊选项 `--load_restrictions none` 能够放宽这个限制，从而让不同的 Kustomization 可以共享补丁文件。
|
||||
|
||||
可以用 URL、绝对路径或者相对路径引用其它的 Kustomization（包含 `kustomization.yaml` 文件的其它目录）。
|
||||
|
||||
如果 `A` Kustomization 依赖 `B` Kustomization，那么：
|
||||
|
||||
- `B` 不能包含 `A`。
|
||||
- `B` 不能依赖 `A`，间接依赖也不可以。
|
||||
|
||||
`A` 可以包含 `B`，但是这样的话，最简单的方式可能是让 `A` 直接依赖 `B` 的资源，并去除 `B` 的 `kustomization.yaml` 文件（就是把 `B` 合并到 `A`）。
|
||||
|
||||
通常情况下，`B` 和 `A` 处于同级目录，或者 `B` 放在一个完全独立的 Git 仓库里，可以从任意的 Kustomization 进行引用。
|
||||
|
||||
常见布局大致如下：
|
||||
|
||||
> ```
|
||||
> ├── base
|
||||
> │ ├── deployment.yaml
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── service.yaml
|
||||
> └── overlays
|
||||
> ├── dev
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── patch.yaml
|
||||
> ├── prod
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── patch.yaml
|
||||
> └── staging
|
||||
> ├── kustomization.yaml
|
||||
> └── patch.yaml
|
||||
> ```
|
||||
|
||||
`dev`、`prod` 以及 `staging` 是否依赖于 `base`，要根据 `kustomization.yaml` 具体判断。
|
||||
|
||||
## kubernetes
|
||||
|
||||
[Kubernetes](https://kubernetes.io) 是一个开源软件，为容器化应用提供了自动部署、伸缩和管理的能力。
|
||||
|
||||
它经常会被简写为 `k8s`。
|
||||
|
||||
## Kubernetes 风格的对象
|
||||
|
||||
[必要字段]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|
||||
|
||||
用 YAML 或者 JSON 文件表达一个对象，其中包含一些[必要字段]。`kind` 字段用于标识对象类型，`metadata/name` 字段用于区分实例，`apiVersion` 表示的是版本（如果有多个版本的话）。
|
||||
|
||||
## kustomize
|
||||
|
||||
`kustomize` 是一个面向 Kubernetes 的命令行工具，用一种无模板、结构化的的方式为为声明式配置提供定制支持。
|
||||
|
||||
`面向 Kubernetes` 的意思是 Kustomize 对 API 资源、Kubernetes 概念（例如名称、标签、命名空间等）、以及资源补丁是有支持的。
|
||||
|
||||
Kustomize 是 [DAM] 的一个实现。
|
||||
|
||||
## 通用配置
|
||||
|
||||
通用配置是一种用于共享的 Kustomization 以及资源。
|
||||
|
||||
例如创建一个这样的 Github 仓库：
|
||||
|
||||
> ```
|
||||
> github.com/username/someapp/
|
||||
> kustomization.yaml
|
||||
> deployment.yaml
|
||||
> configmap.yaml
|
||||
> README.md
|
||||
> ```
|
||||
|
||||
其他人可以 `fork` 这个仓库，并把它们的 Fork `clone` 到本地进行定制。
|
||||
|
||||
用户可以用这个克隆回来的版本作为 [Base]，在此基础上定制 [Overlay] 来满足自身需求。
|
||||
|
||||
## overlay
|
||||
|
||||
`Overlay` 是一个 依赖于其它 Kustomization 的 Kustomization。
|
||||
|
||||
Overlay 引用（通过文件路径、URI 或者别的什么方式）的 [Kustomization] 被称为 [Base]。
|
||||
|
||||
Overlay 无法脱离 Base 独立生效。
|
||||
|
||||
Overlay 可以作为其它 Overlay 的 Base。
|
||||
|
||||
通常 Overlay 都是不止一个的，因为实际情况中就需要为单一 Base 创建不同的[变体]，例如 `development`、`QA`、`production` 等。
|
||||
|
||||
总的说来，这些变体使用的资源基本是一致的，只有一些简单的差异，例如 Deployment 的实例数量、特定 Pod 的 CPU 资源、ConfigMap 中的数据源定义等。
|
||||
|
||||
可以这样把配置提交到集群：
|
||||
|
||||
> ```
|
||||
> kustomize build someapp/overlays/staging |\
|
||||
> kubectl apply -f -
|
||||
>
|
||||
> kustomize build someapp/overlays/production |\
|
||||
> kubectl apply -f -
|
||||
> ```
|
||||
|
||||
对 Base 的使用是隐性的——Overlay 的依赖是指向 Base 的。
|
||||
|
||||
请参考 [root]。
|
||||
|
||||
## 包
|
||||
|
||||
在 Kustomize 中，`包`是没有意义的，Kustomize 并无意成为 [apt]、[rpm] 那样的传统包管理工具。
|
||||
|
||||
## patch
|
||||
|
||||
修改资源的通用指令。
|
||||
|
||||
有两种功能类似但是实现不同的补丁方式：[strategic merge patch](#patchstrategicmerge) 和 [JSON patch](#patchjson6902)。
|
||||
|
||||
## patchStrategicMerge
|
||||
|
||||
`patchStrategicMerge` 是 [strategic-merge] 风格的补丁（SMP）。
|
||||
|
||||
SMP 看上去像个不完整的 Kubernetes 资源 YAML。SMP 中包含 `TypeMeta` 字段，用于表明这个补丁的目标[资源]的 `group/version/kind/name`，剩余的字段是一个嵌套的结构，用于指定新的字段值，例如镜像标签。
|
||||
|
||||
缺省情况下，SMP 会**替换**目标值。如果目标值是一个字符串，这种行为是合适的，但是如果目标值是个列表，可能就不合适了。
|
||||
|
||||
可以加入 `directive` 来修改这种行为，，可以接受的 `directive` 包括 `replace`（缺省）、`merge`（不替换列表）、`delete` 等（[相关说明][strategic-merge]）。
|
||||
|
||||
注意对自定义资源来说，SMP 会被当作 [json merge patches][JSONMergePatch].
|
||||
|
||||
有趣的事实：所有的资源文件都可以当作 SMP 使用，相同 `group/version/kind/name` 资源中的匹配字段会被替换，其它内容则保持不变。
|
||||
|
||||
## patchJson6902
|
||||
|
||||
`patchJson6902` 引用一个 Kubernetes 资源，并用 [JSONPatch] 指定了修改这一资源的方法。
|
||||
|
||||
`patchJson6902` 几乎可以做到所有 `patchStrategicMerge` 的功能，但是语法更加简单，参考[示例][patchExampleJson6902]
|
||||
|
||||
## 插件
|
||||
|
||||
Kustomize 可以使用的一段代码，但是无需编译到 Kustomize 内部，可以作为 Kustomization 的一部分，生成或转换 Kubernetes 资源。
|
||||
|
||||
[插件](../../guides/plugins)的细节。
|
||||
|
||||
## 资源
|
||||
|
||||
在 REST-ful API 的上下文中，资源是 `GET`、`PUT` 或者 `POST` 等 HTTP 操作的目标。Kubernetes 提供了 REST-ful API 界面，用于和客户端进行交互。
|
||||
|
||||
在 Kustomization 的上下文中，资源是一个相对于 [root] 的相对路径，指向 [YAML] 或者 [JSON] 文件，描述了一个 Kubernetes API 对象，例如 Deployment 或者 ConfigMap，或者一个 Kustomization、或者一个指向 Kustomization 的 URL。
|
||||
|
||||
或者说任何定义了[对象](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)的格式正确的 YAML 文件，其中包含了 `kind` 和 `metadata/name` 字段，都是资源。
|
||||
|
||||
## root
|
||||
|
||||
参看 [kustomization root][root].
|
||||
|
||||
## sub-target / sub-application / sub-package
|
||||
|
||||
不存在 `sub-xxx`，只有 [Base] 和 [Overlay]。
|
||||
|
||||
## target
|
||||
|
||||
`target` 是 `kustomize build` 的参数，例如：
|
||||
|
||||
> ```bash
|
||||
> kustomize build $target
|
||||
> ```
|
||||
|
||||
`$target` 必须是一个指向 [Kustomization] 的路径或者 URL。
|
||||
|
||||
要创建用于进行 [Apply] 操作的资源，`target` 中必须包含或者引用所有相关信息。
|
||||
|
||||
[Base] 或者 [Overlay] 都可以作为 `target`。
|
||||
|
||||
## transformer
|
||||
|
||||
转换器能够修改资源，或者在 `kustomize build` 的过程中获取资源的信息。
|
||||
|
||||
## 变体
|
||||
|
||||
在集群中把 [Overlay] 应用到 [Base] 上的产物称为**变体**。
|
||||
|
||||
比如 `staging` 和 `production` 两个 Overlay，都修改了同样的 Base，来创建各自的变体。
|
||||
|
||||
`staging` 变体包含了一组用来保障测试过程的资源，或者一些想要看到生产环境下一个版本的外部用户。
|
||||
|
||||
`production` 变体用于承载生产流量，可能使用大量的副本，分配更多的 CPU 和内存。
|
||||
11
site/content/zh/api-reference/kustomization/_index.md
Normal file
11
site/content/zh/api-reference/kustomization/_index.md
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: "kustomization.yaml"
|
||||
linkTitle: "kustomization.yaml"
|
||||
type: docs
|
||||
weight: 10
|
||||
description: >
|
||||
kustomization.yaml fields and API
|
||||
---
|
||||
|
||||
|
||||
|
||||
13
site/content/zh/api-reference/kustomization/bases/_index.md
Normal file
13
site/content/zh/api-reference/kustomization/bases/_index.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: "bases"
|
||||
linkTitle: "bases"
|
||||
type: docs
|
||||
description: >
|
||||
在 Kustomization 目录中添加资源。
|
||||
---
|
||||
|
||||
{{% pageinfo color="warning" %}}
|
||||
`bases` 字段在 v2.1.0 中已被弃用。
|
||||
{{% /pageinfo %}}
|
||||
|
||||
该条目已被移动到 [resources](/kustomize/zh/api-reference/kustomization/resource) 字段中，其仍是[核心概念](/kustomize/zh/api-reference/kustomization/glossary#base)，这使得相对于其他输入资源 base 可以进行排序。
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: "commonAnnotations"
|
||||
linkTitle: "commonAnnotations"
|
||||
type: docs
|
||||
description: >
|
||||
为所有字段添加注释。
|
||||
---
|
||||
|
||||
为所有资源添加注释，如果资源上已经存在注解键，该值将被覆盖。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonAnnotations:
|
||||
oncallPager: 800-555-1212
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
### 输入文件
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonAnnotations:
|
||||
oncallPager: 800-555-1212
|
||||
|
||||
resources:
|
||||
- deploy.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
spec:
|
||||
...
|
||||
```
|
||||
|
||||
### 构建输出
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
annotations:
|
||||
oncallPager: 800-555-1212
|
||||
spec:
|
||||
...
|
||||
```
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: "commonLabels"
|
||||
linkTitle: "commonLabels"
|
||||
type: docs
|
||||
description: >
|
||||
为所有资源和 selectors 增加标签。
|
||||
---
|
||||
|
||||
为所有资源和 selectors 增加标签。如果资源上已经存在注解键，该值将被覆盖。
|
||||
|
||||
{{% pageinfo color="warning" %}}
|
||||
一旦将资源应用于集群，就不应更改诸如 Deployments 和 Services 之类的资源选择器。
|
||||
|
||||
将 commonLabels 更改为可变资源可能会导致部署失败。
|
||||
{{% /pageinfo %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonLabels:
|
||||
someName: someValue
|
||||
owner: alice
|
||||
app: bingo
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
### 文件输入
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonLabels:
|
||||
someName: someValue
|
||||
owner: alice
|
||||
app: bingo
|
||||
|
||||
resources:
|
||||
- deploy.yaml
|
||||
- service.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
```
|
||||
|
||||
```yaml
|
||||
# service.yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: example
|
||||
```
|
||||
|
||||
### 构建输出
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
name: example
|
||||
spec:
|
||||
selector:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
name: example
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: "components"
|
||||
linkTitle: "components"
|
||||
type: docs
|
||||
description: >
|
||||
Compose kustomizations.
|
||||
---
|
||||
|
||||
*Coming soon*
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "configMapGenerator"
|
||||
linkTitle: "configMapGenerator"
|
||||
type: docs
|
||||
description: >
|
||||
生成 ConfigMap 资源.
|
||||
---
|
||||
|
||||
列表中的每个条目都将生成一个 ConfigMap （合计可以生成 n 个 ConfigMap）。
|
||||
|
||||
下面的示例会生成 3 个ConfigMap：第一个带有给定文件的名称和内容，第二个将在 data 中添加 key/value，第三个通过 `options` 为单个 ConfigMap 设置注释和标签。
|
||||
|
||||
每个 configMapGenerator 项均接受的参数 `behavior: [create|replace|merge]`，这个参数允许修改或替换父级现有的 configMap。
|
||||
|
||||
此外，每个条目都有一个 `options` 字段，该字段具有与 kustomization 文件的 `generatorOptions` 字段相同的子字段。
|
||||
|
||||
`options` 字段允许用户为生成的实例添加标签和（或）注释，或者分别禁用该实例名称的哈希后缀。此处添加的标签和注释不会被 kustomization 文件 `generatorOptions` 字段关联的全局选项覆盖。但是如果全局 `generatorOptions` 字段指定 `disableNameSuffixHash: true`，其他 `options` 的设置将无法将其覆盖。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
# 这个标签将添加到所有的 ConfigMap 和 Secret 中。
|
||||
generatorOptions:
|
||||
labels:
|
||||
fruit: apple
|
||||
|
||||
configMapGenerator:
|
||||
- name: my-java-server-props
|
||||
behavior: merge
|
||||
files:
|
||||
- application.properties
|
||||
- more.properties
|
||||
- name: my-java-server-env-vars
|
||||
literals:
|
||||
- JAVA_HOME=/opt/java/jdk
|
||||
- JAVA_TOOL_OPTIONS=-agentlib:hprof
|
||||
options:
|
||||
disableNameSuffixHash: true
|
||||
labels:
|
||||
pet: dog
|
||||
- name: dashboards
|
||||
files:
|
||||
- mydashboard.json
|
||||
options:
|
||||
annotations:
|
||||
dashboard: "1"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app1"
|
||||
```
|
||||
|
||||
这里也可以[定义一个 key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) 来为文件设置不同名称。
|
||||
|
||||
下面这个示例会创建一个 ConfigMap，并将 `whatever.ini` 重命名为 `myFileName.ini`：
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
configMapGenerator:
|
||||
- name: app-whatever
|
||||
files:
|
||||
- myFileName.ini=whatever.ini
|
||||
```
|
||||
34
site/content/zh/api-reference/kustomization/crds/_index.md
Normal file
34
site/content/zh/api-reference/kustomization/crds/_index.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "crds"
|
||||
linkTitle: "crds"
|
||||
type: docs
|
||||
description: >
|
||||
增加对 CRD 的支持。
|
||||
---
|
||||
|
||||
此列表中的每个条目都应该是自定义资源定义（CRD）文件的相对路径。
|
||||
|
||||
该字段的存在是为了让 kustomize 识别用户自定义的 CRD ，并对这些类型中的对象应用适当的转换。
|
||||
|
||||
典型用例：CRD 引用 ConfigMap 对象
|
||||
|
||||
在 kustomization 中，ConfigMap 对象名称可能会通过 `namePrefix` 、`nameSuffix` 或 `hashing` 来更改 CRD 对象中该 ConfigMap 对象的名称，
|
||||
引用时需要以相同的方式使用 `namePrefix` 、 `nameSuffix` 或 `hashing` 来进行更新。
|
||||
|
||||
Annotations 可以放入 openAPI 的定义中：
|
||||
|
||||
- "x-kubernetes-annotation": ""
|
||||
- "x-kubernetes-label-selector": ""
|
||||
- "x-kubernetes-identity": ""
|
||||
- "x-kubernetes-object-ref-api-version": "v1",
|
||||
- "x-kubernetes-object-ref-kind": "Secret",
|
||||
- "x-kubernetes-object-ref-name-key": "name",
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
crds:
|
||||
- crds/typeA.yaml
|
||||
- crds/typeB.yaml
|
||||
```
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: "generatorOptions"
|
||||
linkTitle: "generatorOptions"
|
||||
type: docs
|
||||
description: >
|
||||
控制生成 [ConfigMap](/kustomize/zh/api-reference/kustomization/configmapgenerator) 和 [Secret](/kustomize/zh/api-reference/kustomization/secretgenerator) 的行为。
|
||||
---
|
||||
|
||||
此外，在每个生成器中，还可以按每个资源级别设置 generatorOptions，具体使用方法请参见[configMapGenerator](/kustomize/zh/api-reference/kustomization/configmapgenerator)和[secretGenerator](/kustomize/zh/api-reference/kustomization/secretgenerator)。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
generatorOptions:
|
||||
# labels to add to all generated resources
|
||||
labels:
|
||||
kustomize.generated.resources: somevalue
|
||||
# annotations to add to all generated resources
|
||||
annotations:
|
||||
kustomize.generated.resource: somevalue
|
||||
# disableNameSuffixHash is true disables the default behavior of adding a
|
||||
# suffix to the names of generated resources that is a hash of
|
||||
# the resource contents.
|
||||
disableNameSuffixHash: true
|
||||
```
|
||||
51
site/content/zh/api-reference/kustomization/images/_index.md
Normal file
51
site/content/zh/api-reference/kustomization/images/_index.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "images"
|
||||
linkTitle: "images"
|
||||
type: docs
|
||||
description: >
|
||||
修改镜像的名称、tag 或 image digest。
|
||||
---
|
||||
|
||||
修改镜像的名称、tag 或 image digest ，而无需使用 patches 。例如，对于这种 kubernetes Deployment 片段：
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
...
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: mypostgresdb
|
||||
image: postgres:8
|
||||
- name: nginxapp
|
||||
image: nginx:1.7.9
|
||||
- name: myapp
|
||||
image: my-demo-app:latest
|
||||
- name: alpine-app
|
||||
image: alpine:3.7
|
||||
```
|
||||
|
||||
想要将 `image` 做如下更改：
|
||||
|
||||
- 将 `postgres:8` 改为 `my-registry/my-postgres:v1`
|
||||
- 将 nginx tag 从 `1.7.9` 改为 `1.8.0`
|
||||
- 将镜像名称 `my-demo-app` 改为 `my-app`
|
||||
- 将 alpine 的 tag `3.7` 改为 digest 值
|
||||
|
||||
只需在 *kustomization* 中添加以下内容：
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
images:
|
||||
- name: postgres
|
||||
newName: my-registry/my-postgres
|
||||
newTag: v1
|
||||
- name: nginx
|
||||
newTag: 1.8.0
|
||||
- name: my-demo-app
|
||||
newName: my-app
|
||||
- name: alpine
|
||||
digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
|
||||
```
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: "namePrefix"
|
||||
linkTitle: "namePrefix"
|
||||
type: docs
|
||||
description: >
|
||||
为所有资源和引用的名称添加前缀。
|
||||
---
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
namePrefix: alices-
|
||||
```
|
||||
|
||||
deployment 名称从 `wordpress` 变为 `alices-wordpress`。
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: "namespace"
|
||||
linkTitle: "namespace"
|
||||
type: docs
|
||||
description: >
|
||||
为所有资源添加 namespace。
|
||||
---
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
namespace: my-namespace
|
||||
```
|
||||
|
||||
如果在资源上设置了现有 namespace，则将覆盖现有 namespace；如果在资源上未设置现有 namespace，则使用现有 namespace。
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "nameSuffix"
|
||||
linkTitle: "nameSuffix"
|
||||
type: docs
|
||||
description: >
|
||||
为所有资源和引用的名称添加后缀。
|
||||
---
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
nameSuffix: -v2
|
||||
```
|
||||
|
||||
deployment 名称从 `wordpress` 变为 `wordpress-v2`。
|
||||
|
||||
**注意:** 如果资源类型是 ConfigMap 或 Secret，则在哈希值之前添加后缀。
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: "patches"
|
||||
linkTitle: "patches"
|
||||
type: docs
|
||||
description: >
|
||||
Patch resources
|
||||
---
|
||||
|
||||
[strategic merge]: /kustomize/zh/api-reference/glossary#patchstrategicmerge
|
||||
[JSON]: /kustomize/zh/api-reference/glossary#patchjson6902
|
||||
|
||||
|
||||
Patches 在资源上添加或覆盖字段，Kustomization 使用 `patches` 字段来提供该功能。
|
||||
|
||||
`patches` 字段包含要按指定顺序应用的 patch 列表。
|
||||
|
||||
patch 可以:
|
||||
|
||||
- 是一个 [strategic merge] patch，或者是一个 [JSON] patch。
|
||||
- 也可以是 patch 文件或 inline string
|
||||
- 针对单个资源或多个资源
|
||||
|
||||
目标选择器可以通过 group、version、kind、name、namespace、标签选择器和注释选择器来选择资源，选择一个或多个匹配所有**指定**字段的资源来应用 patch。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patches:
|
||||
- path: patch.yaml
|
||||
target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: deploy.*
|
||||
labelSelector: "env=dev"
|
||||
annotationSelector: "zone=west"
|
||||
- patch: |-
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
target:
|
||||
kind: MyKind
|
||||
labelSelector: "env=dev"
|
||||
```
|
||||
|
||||
patch 目标选择器的 `name` 和 `namespace` 字段是自动锚定的正则表达式。这意味着 `myapp` 的值相当于 `^myapp$`。
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "patchesStrategicMerge"
|
||||
linkTitle: "patchesStrategicMerge"
|
||||
type: docs
|
||||
description: >
|
||||
使用 strategic merge patch 标准 Patch resources.
|
||||
---
|
||||
|
||||
此列表中的每个条目都应可以解析为 [StrategicMergePatch](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md).
|
||||
|
||||
这些（也可能是部分的）资源文件中的 name 必须与已经通过 `resources` 加载的 name 字段匹配，或者通过 `bases` 中的 name 字段匹配。这些条目将用于 _patch_（修改）已知资源。
|
||||
|
||||
推荐使用小的 patches，例如：修改内存的 request/limit，更改 ConfigMap 中的 env 变量等。小的 patches 易于维护和查看，并且易于在 overlays 中混合使用。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesStrategicMerge:
|
||||
- service_port_8888.yaml
|
||||
- deployment_increase_replicas.yaml
|
||||
- deployment_increase_memory.yaml
|
||||
```
|
||||
|
||||
patch 内容也可以是一个inline string：
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesStrategicMerge:
|
||||
- |-
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: nginx
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nignx:latest
|
||||
```
|
||||
|
||||
请注意，kustomize 不支持同一个 patch 对象中包含多个 _删除_ 指令。要从一个对象中删除多个字段或切片元素，需要创建一个单独的 patch，以执行所有需要的删除。
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: "patchesJson6902"
|
||||
linkTitle: "patchesJson6902"
|
||||
type: docs
|
||||
description: >
|
||||
使用 [json 6902 标准](https://tools.ietf.org/html/rfc6902) Patch resources
|
||||
---
|
||||
|
||||
patchesJson6902 列表中的每个条目都应可以解析为 kubernetes 对象和将应用于该对象的 [JSON patch](https://tools.ietf.org/html/rfc6902)。
|
||||
|
||||
目标字段指向的 kubernetes 对象的 group、 version、 kind、 name 和 namespace 在同一 kustomization 内 path 字段内容是 JSON patch 文件的相对路径。
|
||||
|
||||
patch 文件中的内容可以如下这种 JSON 格式：
|
||||
|
||||
```json
|
||||
[
|
||||
{"op": "add", "path": "/some/new/path", "value": "value"},
|
||||
{"op": "replace", "path": "/some/existing/path", "value": "new value"}
|
||||
]
|
||||
```
|
||||
|
||||
也可以使用 YAML 格式表示：
|
||||
|
||||
```yaml
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
path: add_init_container.yaml
|
||||
- target:
|
||||
version: v1
|
||||
kind: Service
|
||||
name: my-service
|
||||
path: add_service_annotation.yaml
|
||||
```
|
||||
|
||||
patch 内容也可以是一个inline string：
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
patch: |-
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: "new value"
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "replicas"
|
||||
linkTitle: "replicas"
|
||||
type: docs
|
||||
description: >
|
||||
修改资源的副本数。
|
||||
---
|
||||
|
||||
对于如下 kubernetes Deployment 片段：
|
||||
|
||||
```yaml
|
||||
# deployment.yaml
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: deployment-name
|
||||
spec:
|
||||
replicas: 3
|
||||
```
|
||||
|
||||
在 kustomization 中添加以下内容，将副本数更改为 5：
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
replicas:
|
||||
- name: deployment-name
|
||||
count: 5
|
||||
```
|
||||
|
||||
该字段内容为列表，所以可以同时修改许多资源。
|
||||
|
||||
由于这个声明无法设置 `kind:` 或 `group:`，所以他只能匹配如下资源中的一种：
|
||||
- `Deployment`
|
||||
- `ReplicationController`
|
||||
- `ReplicaSet`
|
||||
- `StatefulSet`
|
||||
|
||||
对于更复杂的用例，请使用 patch 。
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: "resources"
|
||||
linkTitle: "resources"
|
||||
type: docs
|
||||
description: >
|
||||
包含的资源。
|
||||
---
|
||||
|
||||
该条目可以是指向本地目录的相对路径，也可以是指向远程仓库中的目录的 URL，例如：
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- myNamespace.yaml
|
||||
- sub-dir/some-deployment.yaml
|
||||
- ../../commonbase
|
||||
- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6
|
||||
- deployment.yaml
|
||||
- github.com/kubernets-sigs/kustomize/examples/helloWorld?ref=test-branch
|
||||
```
|
||||
|
||||
将以深度优先的顺序读取和处理资源。
|
||||
|
||||
文件应包含 YAML 格式的 k8s 资源。一个资源描述文件可以含有多个由（`---`）分隔的资源。
|
||||
应该包含 `resources` 字段的 kustomization 文件的指定文件目录的相对路径。
|
||||
|
||||
[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format
|
||||
|
||||
目录规范可以是相对、绝对或部分的 URL。URL 规范应遵循 [hashicorp URL] 格式。该目录必须包含 `kustomization.yaml` 文件。
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "secretGenerator"
|
||||
linkTitle: "secretGenerator"
|
||||
type: docs
|
||||
description: >
|
||||
生成 Secret 资源。
|
||||
---
|
||||
|
||||
列表中的每个条目都将生成一个 Secret（合计可以生成 n 个 Secrets）。
|
||||
|
||||
功能与之前描述的 [configMapGenerator](/kustomize/zh/api-reference/kustomization/configmapgenerator) 字段类似。
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
secretGenerator:
|
||||
- name: app-tls
|
||||
files:
|
||||
- secret/tls.cert
|
||||
- secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: app-tls-namespaced
|
||||
# you can define a namespace to generate
|
||||
# a secret in, defaults to: "default"
|
||||
namespace: apps
|
||||
files:
|
||||
- tls.crt=catsecret/tls.cert
|
||||
- tls.key=secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: env_file_secret
|
||||
envs:
|
||||
- env.txt
|
||||
type: Opaque
|
||||
- name: secret-with-annotation
|
||||
files:
|
||||
- app-config.yaml
|
||||
type: Opaque
|
||||
options:
|
||||
annotations:
|
||||
app_config: "true"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app2"
|
||||
```
|
||||
65
site/content/zh/api-reference/kustomization/vars/_index.md
Normal file
65
site/content/zh/api-reference/kustomization/vars/_index.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: "vars"
|
||||
linkTitle: "vars"
|
||||
type: docs
|
||||
description: >
|
||||
Substitute name references.
|
||||
---
|
||||
|
||||
Vars 用于从一个 resource 字段中获取值，并将该值插入指定位置 - 反射功能。
|
||||
|
||||
例如，假设需要在容器的 command 中指定了 Service 对象的名称，并在容器的 env 中指定了 Secret 对象的名称来确保以下内容可以正常工作：
|
||||
|
||||
```yaml
|
||||
|
||||
containers:
|
||||
- image: myimage
|
||||
command: ["start", "--host", "$(MY_SERVICE_NAME)"]
|
||||
env:
|
||||
- name: SECRET_TOKEN
|
||||
value: $(SOME_SECRET_NAME)
|
||||
```
|
||||
|
||||
则可以在 `vars：` 中添加如下内容：
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
vars:
|
||||
- name: SOME_SECRET_NAME
|
||||
objref:
|
||||
kind: Secret
|
||||
name: my-secret
|
||||
apiVersion: v1
|
||||
- name: MY_SERVICE_NAME
|
||||
objref:
|
||||
kind: Service
|
||||
name: my-service
|
||||
apiVersion: v1
|
||||
fieldref:
|
||||
fieldpath: metadata.name
|
||||
- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
|
||||
objref:
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
apiVersion: apps/v1
|
||||
fieldref:
|
||||
fieldpath: spec.template.spec.restartPolicy
|
||||
```
|
||||
|
||||
var 是包含该对象的变量名、对象引用和字段引用的元组。
|
||||
|
||||
字段引用是可选的，默认为 `metadata.name`，这是正常的默认值，因为 kustomize 用于生成或修改 resources 的名称。
|
||||
|
||||
在撰写本文档时，仅支持字符串类型字段，不支持 ints，bools，arrays 等。例如，在某些pod模板的容器编号2中提取镜像的名称是不可能的。
|
||||
|
||||
变量引用，即字符串 '$(FOO)' ，只能放在 kustomize 配置指定的特定对象的特定字段中。
|
||||
|
||||
关于 vars 的默认配置数据可以查看：
|
||||
[/api/konfig/builtinpluginconsts/varreference.go](/api/konfig/builtinpluginconsts/varreference.go)
|
||||
|
||||
默认目标是所有容器 command args 和 env 字段。
|
||||
|
||||
Vars _不应该_ 被用于 kustomize 已经处理过的配置中插入 names 。
|
||||
例如， Deployment 可以通过 name 引用 ConfigMap ，如果 kustomize 更改 ConfigMap 的名称，则知道更改 Deployment 中的引用的 name 。
|
||||
Reference in New Issue
Block a user