diff --git a/site/content/zh/api-reference/_index.md b/site/content/zh/api-reference/_index.md index bd8a2c631..11df50f50 100644 --- a/site/content/zh/api-reference/_index.md +++ b/site/content/zh/api-reference/_index.md @@ -9,3 +9,7 @@ menu: description: > Kustomize 客户端 API 参考。 --- + + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/glossary/_index.md b/site/content/zh/api-reference/glossary/_index.md index 8737ee7bd..475cb3a94 100644 --- a/site/content/zh/api-reference/glossary/_index.md +++ b/site/content/zh/api-reference/glossary/_index.md @@ -7,305 +7,6 @@ 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 和内存。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/_index.md b/site/content/zh/api-reference/kustomization/_index.md index 29443fbff..754e572b6 100644 --- a/site/content/zh/api-reference/kustomization/_index.md +++ b/site/content/zh/api-reference/kustomization/_index.md @@ -7,5 +7,7 @@ description: > kustomization.yaml fields and API --- + +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/bases/_index.md b/site/content/zh/api-reference/kustomization/bases/_index.md index eeb8abc8a..246d713d0 100644 --- a/site/content/zh/api-reference/kustomization/bases/_index.md +++ b/site/content/zh/api-reference/kustomization/bases/_index.md @@ -6,8 +6,6 @@ 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 可以进行排序。 +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/commonannotations/_index.md b/site/content/zh/api-reference/kustomization/commonannotations/_index.md index 23ebe57e7..a9c4a430a 100644 --- a/site/content/zh/api-reference/kustomization/commonannotations/_index.md +++ b/site/content/zh/api-reference/kustomization/commonannotations/_index.md @@ -6,51 +6,6 @@ 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: - ... -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/commonlabels/_index.md b/site/content/zh/api-reference/kustomization/commonlabels/_index.md index 6cca0ad67..374f83b6b 100644 --- a/site/content/zh/api-reference/kustomization/commonlabels/_index.md +++ b/site/content/zh/api-reference/kustomization/commonlabels/_index.md @@ -6,94 +6,6 @@ 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 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/components/_index.md b/site/content/zh/api-reference/kustomization/components/_index.md index 7ba60f812..46ea9c512 100644 --- a/site/content/zh/api-reference/kustomization/components/_index.md +++ b/site/content/zh/api-reference/kustomization/components/_index.md @@ -6,4 +6,6 @@ description: > Compose kustomizations. --- -*Coming soon* + + +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/configmapgenerator/_index.md b/site/content/zh/api-reference/kustomization/configmapgenerator/_index.md index 02c187b6a..3e84eeb33 100644 --- a/site/content/zh/api-reference/kustomization/configmapgenerator/_index.md +++ b/site/content/zh/api-reference/kustomization/configmapgenerator/_index.md @@ -6,68 +6,6 @@ description: > 生成 ConfigMap 资源. --- -列表中的每个条目都将生成一个 ConfigMap （合计可以生成 n 个 ConfigMap）。 + -以下示例创建四个 ConfigMap： - -- 第一个使用给定文件的名称和内容创建数据 -- 第二个使用文件中的键/值对将数据创建为键/值 -- 第三个使用 `literals` 中的键/值对创建数据作为键/值 -- 第四个通过 `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-file-vars - envs: - - my-server-env.properties - - more-server-props.env -- 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 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/crds/_index.md b/site/content/zh/api-reference/kustomization/crds/_index.md index e04b8df57..2bfce7d8b 100644 --- a/site/content/zh/api-reference/kustomization/crds/_index.md +++ b/site/content/zh/api-reference/kustomization/crds/_index.md @@ -6,29 +6,6 @@ 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 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/api-reference/kustomization/generatoroptions/_index.md b/site/content/zh/api-reference/kustomization/generatoroptions/_index.md index dbf487911..823b5601a 100644 --- a/site/content/zh/api-reference/kustomization/generatoroptions/_index.md +++ b/site/content/zh/api-reference/kustomization/generatoroptions/_index.md @@ -6,21 +6,6 @@ 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 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/images/_index.md b/site/content/zh/api-reference/kustomization/images/_index.md index 31e81fc9f..5dda144dd 100644 --- a/site/content/zh/api-reference/kustomization/images/_index.md +++ b/site/content/zh/api-reference/kustomization/images/_index.md @@ -6,46 +6,6 @@ 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 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/nameprefix/_index.md b/site/content/zh/api-reference/kustomization/nameprefix/_index.md index eec58a800..2c5cbe16f 100644 --- a/site/content/zh/api-reference/kustomization/nameprefix/_index.md +++ b/site/content/zh/api-reference/kustomization/nameprefix/_index.md @@ -6,11 +6,6 @@ description: > 为所有资源和引用的名称添加前缀。 --- -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization + -namePrefix: alices- -``` - -deployment 名称从 `wordpress` 变为 `alices-wordpress`。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/namespace/_index.md b/site/content/zh/api-reference/kustomization/namespace/_index.md index 758084639..5d7156105 100644 --- a/site/content/zh/api-reference/kustomization/namespace/_index.md +++ b/site/content/zh/api-reference/kustomization/namespace/_index.md @@ -6,11 +6,6 @@ description: > 为所有资源添加 namespace。 --- -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization + -namespace: my-namespace -``` - -如果在资源上设置了现有 namespace，则将覆盖现有 namespace；如果在资源上未设置现有 namespace，则使用现有 namespace。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/namesuffix/_index.md b/site/content/zh/api-reference/kustomization/namesuffix/_index.md index a01bec474..b6826c90c 100644 --- a/site/content/zh/api-reference/kustomization/namesuffix/_index.md +++ b/site/content/zh/api-reference/kustomization/namesuffix/_index.md @@ -6,13 +6,6 @@ description: > 为所有资源和引用的名称添加后缀。 --- -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization + -nameSuffix: -v2 -``` - -deployment 名称从 `wordpress` 变为 `wordpress-v2`。 - -**注意:** 如果资源类型是 ConfigMap 或 Secret，则在哈希值之前添加后缀。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/patches/_index.md b/site/content/zh/api-reference/kustomization/patches/_index.md index 036cc9cc1..bcb548fa4 100644 --- a/site/content/zh/api-reference/kustomization/patches/_index.md +++ b/site/content/zh/api-reference/kustomization/patches/_index.md @@ -6,144 +6,6 @@ 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$`。 - -示例 1 和示例 2 都将使用以下 `deployment.yaml`： - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - name: the-container - image: registry/conatiner:latest -``` - -## 示例1 - -### 目的 - -将容器镜像指向特定版本，代替 latest 版本。 - -### 文件输入 - -```yaml -# kustomization.yaml -resources: -- deployment.yaml - -patches: -- path: patch.yaml -``` - -```yaml -# patch.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - template: - containers: - - name: the-container - image: registry/conatiner:1.0.0 -``` - -### 构建输出 - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - image: registry/conatiner:1.0.0 - name: the-container -``` - -## 示例2 - -### 目的 - -同上。 - -### 文件输入 - -```yaml -# kustomization.yaml -resources: -- deployment.yaml - -patches: -- target: - kind: Deployment - name: the-deployment - path: patch.json -``` - -```yaml -# patch.json -[ - {"op": "replace", "path": "/spec/template/containers/0/image", "value": "registry/conatiner:1.0.0"} -] - -``` - -### 构建输出 - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - image: registry/conatiner:1.0.0 - name: the-container -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/patchesStrategicMerge/_index.md b/site/content/zh/api-reference/kustomization/patchesStrategicMerge/_index.md index 178cd4aeb..a48fefbfd 100644 --- a/site/content/zh/api-reference/kustomization/patchesStrategicMerge/_index.md +++ b/site/content/zh/api-reference/kustomization/patchesStrategicMerge/_index.md @@ -6,40 +6,6 @@ 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，以执行所有需要的删除。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/patchesjson6902/_index.md b/site/content/zh/api-reference/kustomization/patchesjson6902/_index.md index 650d4477f..f8e48b4c3 100644 --- a/site/content/zh/api-reference/kustomization/patchesjson6902/_index.md +++ b/site/content/zh/api-reference/kustomization/patchesjson6902/_index.md @@ -6,63 +6,6 @@ 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" -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/replicas/_index.md b/site/content/zh/api-reference/kustomization/replicas/_index.md index 33b7ea569..703ea8086 100644 --- a/site/content/zh/api-reference/kustomization/replicas/_index.md +++ b/site/content/zh/api-reference/kustomization/replicas/_index.md @@ -6,35 +6,6 @@ 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 。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/resources/_index.md b/site/content/zh/api-reference/kustomization/resources/_index.md index 38e335311..52c0d0c5a 100644 --- a/site/content/zh/api-reference/kustomization/resources/_index.md +++ b/site/content/zh/api-reference/kustomization/resources/_index.md @@ -6,26 +6,6 @@ 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` 文件。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/secretegenerator/_index.md b/site/content/zh/api-reference/kustomization/secretegenerator/_index.md index 8b1961607..513f8761c 100644 --- a/site/content/zh/api-reference/kustomization/secretegenerator/_index.md +++ b/site/content/zh/api-reference/kustomization/secretegenerator/_index.md @@ -6,39 +6,6 @@ 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" -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/api-reference/kustomization/vars/_index.md b/site/content/zh/api-reference/kustomization/vars/_index.md index de6d17e8d..294405cc7 100644 --- a/site/content/zh/api-reference/kustomization/vars/_index.md +++ b/site/content/zh/api-reference/kustomization/vars/_index.md @@ -6,60 +6,6 @@ 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 。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/_index.md b/site/content/zh/blog/_index.md index 0feb14e98..ad4a55c14 100644 --- a/site/content/zh/blog/_index.md +++ b/site/content/zh/blog/_index.md @@ -5,3 +5,8 @@ menu: main: weight: 80 --- + + + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/_index.md b/site/content/zh/blog/releases/_index.md index ffae15b86..44cfbf99e 100644 --- a/site/content/zh/blog/releases/_index.md +++ b/site/content/zh/blog/releases/_index.md @@ -4,3 +4,6 @@ linkTitle: "Releases" weight: 20 --- + + +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/blog/releases/v1.0.1.md b/site/content/zh/blog/releases/v1.0.1.md index aa5923520..806feb929 100644 --- a/site/content/zh/blog/releases/v1.0.1.md +++ b/site/content/zh/blog/releases/v1.0.1.md @@ -6,17 +6,6 @@ description: > Kustomize v1.0.1 --- -Initial release after move from github.com/kubernetes/kubectl to github.com/kubernetes-sigs/kustomize. + -History - -* May 2018: v1.0 after move to github.com/kubernetes-sigs/kubectl - from github.com/kubernetes/kubectl. - Has kustomization file, bases, overlays, basic transforms. -* Apr 2018: s/kinflate/kustomize/, s/manifest/kustomization/ -* Oct 2017: s/kexpand/kinflate/ -* Sep 2017: kexpand [starts](https://github.com/kubernetes/kubectl/pull/65) - in github.com/kubernetes/kubectl -* Aug 2017: [DAM] authored by Brian Grant - -[DAM]: https://docs.google.com/document/d/1cLPGweVEYrVqQvBLJg6sxV-TrE5Rm2MNOBA_cxZP2WU +Moved to https://github.com/kubernetes-sigs/cli-experimental diff --git a/site/content/zh/blog/releases/v2.0.0.md b/site/content/zh/blog/releases/v2.0.0.md index bc4bd4780..02345b4c9 100644 --- a/site/content/zh/blog/releases/v2.0.0.md +++ b/site/content/zh/blog/releases/v2.0.0.md @@ -6,132 +6,6 @@ description: > Kustomize v2.0.0 --- -[security concern]: https://docs.google.com/document/d/1FYgLVdq-siB_Cef9yuQBmit0PbrE8lsyTBdGI2eA2y8/edit + -After security review, a field used in secret -generation (see below) was removed from the -definition of a kustomization file with no -mechanism to convert it to a new form. Also, the -set of files accessible from a kustomization file -has been further constrained. - -Per the [versioning policy](/kustomize/faq/versioningpolicy), -backward incompatible changes trigger an increment -of the major version number, hence we go -from 1.0.11 to 2.0.0. We're taking this major -version increment opportunity to remove some -already deprecated fields, and the code paths -associated with them. - -## Backward Incompatible Changes - -### Kustomization Path Constraints - -A kustomization file can specify paths to other -files, including resources, patches, configmap -generation data, secret generation data and -bases. In the case of a base, the path can be a -git URL instead. - -In 1.x, these paths had to be relative to the -current kustomization directory (the location of -the kustomization file used in the `build` -command). - -In 2.0, bases can continue to specify, via -relative paths, kustomizations outside the current -kustomization directory. But non-base paths are -constrained to terminate in or below the current -kustomization directory. Further, bases specified -via a git URL may not reference files outside of -the directory used to clone the repository. - -### Kustomization Field Removals - -#### patches - -`patches` was deprecated and replaced by -`patchesStrategicMerge` when `patchesJson6902` was -introduced. In Kustomize 2.0.0, `patches` is -removed. Please use `patchesStrategicMerge` -instead. - -#### imageTags - -`imageTags` is replaced by `images` since `images` -can provide more features to change image names, -registries, tags and digests. - -#### secretGenerator/commands - -`commands` is removed from SecretGenerator due to -a [security concern]. One can use `files` or -`literals`, similar to ConfigMapGenerator, to -generate a secret. - -``` -secretGenerator: -- name: app-tls - files: - - secret/tls.cert - - secret/tls.key - type: "kubernetes.io/tls" -``` - -## Compatible Changes (New Features) - -As this release is triggered by a security change, -there are no major new features to announce. A few -things that are worth mentioning in this release -are: - -* More than _40_ issues closed since 1.0.11 - release (including many extensions to - transformation rules). - -* Users can run `kustomize edit fix` to migrate a - kustomization file working with previous - versions to one working with 2.0.0. For example, - a kustomization.yaml with following content - - ``` - patches: - - deployment-patch.yaml - imageTags: - - name: postgres - newTag: v1 - ``` - - will be converted to - - ``` - apiVersion: kustomize.config.k8s.io/v1beta1 - kind: Kustomization - patchesStrategicMerge: - - deployment-patch.yaml - images: - - name: postgres - newTag: v1 - ``` - -* Kustomization filename - - In previous versions, the name of a - kustomization file had to be - `kustomization.yaml`. - Kustomize allows `kustomization.yaml`, - `kustomization.yml` and - `Kustomization`. In a directory, only one of - those filenames is allowed. If there are more - than one found, Kustomize will exit with an - error. Please select the best filename for your - use cases. - -* Cancelled plans to deprecate applying prefix/suffix to namespace. - The deprecation warning - - ``` - Adding nameprefix and namesuffix to Namespace resource will be deprecated in next release. - ``` - - was removed. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v2.1.0.md b/site/content/zh/blog/releases/v2.1.0.md index 126103fc9..3ea76a502 100644 --- a/site/content/zh/blog/releases/v2.1.0.md +++ b/site/content/zh/blog/releases/v2.1.0.md @@ -6,243 +6,6 @@ description: > Kustomize v2.1.0 --- -[Go modules]: https://github.com/golang/go/wiki/Modules -[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md -[imgModules]: /kustomize/images/goModules.png -[imgPlugins]: /kustomize/images/plugins.png -[imgPruning]: /kustomize/images/pruning.png -[imgSorted]: /kustomize/images/sorted.png -[imgWheels]: /kustomize/images/abandonedTrainingWheels.png -[kustomization]: glossary#kustomization -[_kustomization_]: /kustomize/api-reference/glossary#kustomization -[base]: /kustomize/api-reference/glossary#base -[bases]: /kustomize/api-reference/glossary#base -[_base_]: /kustomize/api-reference/glossary#base -[kustomize inventory object documentation]: https://github.com/kubernetes-sigs/kustomize/tree/master/docs/inventory_object.md -[kustomize plugin documentation]: plugins -[root]: /kustomize/api-reference/glossary#kustomization-root -[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs -[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9 -[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9releases/tag/v2.0.3 -[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9releases/tag/v2.1.0 -[versioning policy]: /kustomize/faq/versioningpolicy + -Go modules, resource ordering respected, generator and transformer plugins, eased -loading restrictions, the notion of inventory, eased replica count modification. -About ~90 issues closed since [v2.0.3] in ~400 commits. - -Download [here][v2.1.0]. - -## Go modules - -![gopher with boxes][imgModules] - -Kustomize now defines its dependencies in a top -level `go.mod` file. This is the first step -towards a package structure intentially exported -as one or more [Go modules] for use in other -programs (kubectl, kubebuilder, etc.) and in -kustomize plugins (see below). - -## Resource ordering - -![sort order retained][imgSorted] - -Kustomize now retains the depth-first order of -resources as read, a frequently requested -feature. - -This means resource order can be controlled -by editting kustomization files. This is -also vital to applying user-defined -transformations (plugins) in a particular -order. - -Nothing needs to be done to activate this; -it happens automatically. - -The `build` command now accepts a `--reorder` -flag with values `legacy` and `none`, -with a default value of `legacy`. - -`legacy` means apply an ordering based on -GVK, that currently emits `Namespace` objects -first, and `ValidatingWebhookConfiguration` -objects last. This means that despite -automatic retention of load order, your -`build` output won't change by default. - -`none` means _don't_ reorder the resources before -output. Specify this to see output order -respect input order. - -## Generator and transformer plugins - -![kid putting knife in electrical outlet][imgPlugins] - -Since the beginning (as `kinflate` back in Sep -2017), kustomize has read or generated resources, -applied a series of pipelined transformation to -them, and emitted the result to `stdout`. - -At that time, the only way to change the behavior -of a generator (e.g. a secret generator), or -change the behavior of a transformer (e.g. a name -changer, or json patcher), was to modify source -code and put out a release. - -[v1.0.9] introduced [generator options] as a means -to change the behavior of the only two generators -available at the time - Secret and ConfigMap -generators. It also introduced -[transformer configs] as a way to fine tune the -targets of transformations (e.g. to which fields -_selectors_ should be added). Most of the feature -requests for kustomize revolve around changing the -behavior of the builtin generators and -transformers. - -[v2.1.0] adds an _alpha_ plugin framework, that -encourages users to write their own generators or -transformers, _declaring them as kubernetes -objects just like everything else_, and apply them -as part of the `kustomize build` process. - -To inform the API exposed to plugins, and to -confirm that the plugin framework can offer plugin -authors the same capabilities as builtin -operations, all the builtin generators and -tranformers have been converted to plugin form -(with one exceptions awaiting Go module -refinements). This means that adding, say, a -`secretGenerator` or `commonAnnotations` directive -to your kustomization will (in [v2.1.0]) trigger -execution of -[code committed as a plugin](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin). - -For more information, see the -[kustomize plugin documentation]. - -## Remove load restrictions - -![removed training wheels][imgWheels] - -The following usage: - -``` -kustomize build --load_restrictor none $target -``` - -allows a `kustomization.yaml` file used in this -build to refer to files outside its own directory -(i.e. outside its [root]). - -This is an opt-in to suppress a security feature -that denies this precise behavior. - -This feature should only be used to allow multiple -overlays (e.g. prod, staging and dev) to share a -patch file. To share _resources_, use a relative -path or URL to a kustomization directory in the -`resources` directive. - -## Inventory generation for pruning - -![pruning dead branches][imgPruning] - -_Alpha_ - -Users can add an `inventory` stanza to their -kustomization file, to add a special _inventory -object_ to the `build` result. - -This object applies to the cluster along with -everything else in the build result and can be -used by other clients to intelligently _prune_ -orphaned cluster resources. - -For more information see the -[kustomize inventory object documentation]. - -## Field changes / deprecations - -### `resources` expanded, `bases` deprecated - -The `resources` field has been generalized; it now -accepts what formerly could only be specified in -the `bases` field. - -This change was made to allow users fine control -over resource processing order. With a distinct -`bases` field, bases had to be loaded separately -from resources as a group. Now, base loading may -be interleaved as desired with the loading of -resource files from the current -directory. [Resource ordering](#resource-ordering) -had to be respected before this feature could be -introduced. - -The `bases` field is now deprecated, and will be -deleted in some future major release. Manage the -deprecation simply moving the arguments of the -`bases` field to the `resources` field in the -desired order, e.g. - -> ``` -> resources: -> - someResouceFile.yaml -> - someOtherResourceFile.yaml -> bases: -> - ../../someBaseDir -> ``` - -could become - -> ``` -> resources: -> - someResouceFile.yaml -> - ../../someBaseDir -> - someOtherResourceFile.yaml -> ``` - -The `kustomized edit fix` command will do this for -you, though it will always put the bases at the -end. - -As an aside, the `resources`, `generators` and -`transformers` fields now all accept the same -argument format. - -> Each field's argument is a _string list_, -> where each entry is either a _resource_ (a -> relative path to a YAML file) or a -> [_kustomization_] (a path or URL -> pointing to a directory with a kustomization -> file). A kustomization directory used in this -> context is called a [_base_]. - -The fact that the `generators` and `transformers` -field accept [bases] and the fact that generator -and transformer configuration objects are just -normal k8s resources means that one can generate -or transform a generator or a transformer (see -[TestTransformerTransformers]). - -[TestTransformerTransformers]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/internal/target/transformerplugin_test.go - -### `replicas` field - -The common task of patching a deployment to edit -the number of replicas is now made easier -with the new [replicas](/kustomize/api-reference/kustomization/replicas) field. - -### `envs` field - -An `envs` sub-field has been added to both -`configMapGenerator` and `secretGenerator`, -replacing the now deprecated (and singular) -`env` field. The new field accepts lists, just -like its sibling fields `files` and `literals`. - -Optionally use `kustomize edit fix` to merge -singular `env` field into a plural field. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v3.0.0.md b/site/content/zh/blog/releases/v3.0.0.md index f3489789d..2ea092af8 100644 --- a/site/content/zh/blog/releases/v3.0.0.md +++ b/site/content/zh/blog/releases/v3.0.0.md @@ -6,67 +6,6 @@ description: > Kustomize v3.0.0 --- -This release is basically [v2.1.0](v2.1.0.md), -with many post-v2.1.0 bugs fixed (in about 150 -commits) and a `v3` in Go package paths. + -[plugin]: /docs/plugins - -The major version increment to `v3` puts a new -floor on a stable API for [plugin] developers -(both _Go_ plugin developers and _exec_ plugin -developers who happen to use Go). - -### Why so soon after v2.1.0 - -[semantic versioning]: https://semver.org -[Go modules doc]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher -[versioning policy]: /kustomize/faq/versioningpolicy - -We made a mistake - v2.1.0 should have been -v3.0.0. Per the [Go modules doc] (which have -improved a great deal recently), a release that's -already tagged v2 or higher should increment the -major version when performing their first Go -module-based release. - -This advice applies to kustomize, since it was -already at major version 2 when it began using Go -modules to state _its own_ dependencies in v2.1.0. - -But the more important reason for `v3` is a change -to the kustomize [versioning policy], forced by -the introduction of plugins. - -Historically, kustomize's [versioning policy] -didn't involve Go modules and addressed _only_ the -command line tool's behavior and the fields in a -kustomization file. The underlying packages were -an implementation detail, not under semantic -versioning, because they weren't intended for -export (and should have all been under -`internal`). Thus although the v2.1.0 CLI is -backward compatible with v2.0.3, the underlying -package APIs are not. - -[minimal version selection]: https://research.swtch.com/vgo-mvs - -With Go modules, the `go` tool must assume that Go -packages respect [semantic versioning], so it can -perform [minimal version selection]. - -With the introduction of alpha plugins, kustomize -sub-packages - in particular `loader` and -`resmap` - become part of an API formally exposed -to plugin authors, and so must be semantically -versioned. This allows plugins defined in other -repositories to clarify that they depend on -kustomize v3.0.0, and not see confusing errors -arising from incompatibilities between v2.1.0 and -v2.0.3. Hence, the jump to v3. - -Aside - the set of kustomize packages outside -`internal` is too large, and over time, informed -by package use, this API surface must shrink. -Such shrinkage will trigger a major version -increment. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v3.1.0.md b/site/content/zh/blog/releases/v3.1.0.md index fe3cde365..bdd0f41c6 100644 --- a/site/content/zh/blog/releases/v3.1.0.md +++ b/site/content/zh/blog/releases/v3.1.0.md @@ -6,128 +6,6 @@ description: > Kustomize v3.1.0 --- -## Extended patches + -Since this version, Kustomize allows applying one patch to multiple resources. This works for both Strategic Merge Patch and JSON Patch. Take a look at [patch multiple objects](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/patchMultipleObjects.md). - -## Improved Resource Matching - -Multiple improvements have been made to allow the user to leverage "namespace" -instead/or with "name suffix/prefix" to segregate resources. - -### Patch resolution improvement - -The following example demonstrates how using the namespace field in the patch definition, -will let the user define two different patches against two different Deployment having the -same "deploy1" name but in different namespaces in the same Kustomize context/folder. -Unless the `namespace:` field has been specified in the kustomization.yaml, no namespace -value will be handled as Kubernetes `default` namespace. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: deploy1 - namespace: main -spec: - template: - spec: - containers: - - name: nginx - env: - - name: ANOTHERENV - value: TESTVALUE ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: deploy1 - namespace: production -spec: - template: - spec: - containers: - - name: main - env: - - name: ANOTHERENV - value: PRODVALUE -``` - -### Variable resolution improvement - -It is possible to add namespace field to the variable declaration. In the following example, -two `Service` objects with the same `elasticsearch` name have been declared. -Specifying the namespace in the objRef of the corresponding varriables, allows Kustomize to -resovlve thoses variables. -If the namespace is not specified, Kustomize will handle it has a "wildcard" value. - -Extract of kustomization.yaml: - -```yaml -vars: -- name: elasticsearch-test-protocol - objref: - kind: Service - name: elasticsearch - namespace: test - apiVersion: v1 - fieldref: - fieldpath: spec.ports[0].protocol -- name: elasticsearch-dev-protocol - objref: - kind: Service - name: elasticsearch - namespace: dev - apiVersion: v1 - fieldref: - fieldpath: spec.ports[0].protocol - -``` - -### Simultaneous change of names and namespaces - -Kustomize is now able to deal with simultaneous changes of name and namespace. -Special attention has been paid the handling of: - -- ClusterRoleBinding/RoleBinding "subjects" field, -- ValidatingWebhookConfiguration "webhooks" field. - -The user should be able to use a kustomization.yaml as shown in the example bellow -even if ClusterRoleBind,RoleBinding and ValidatingWebookConfiguration are part of the -resources he needs to declare. - -Extract of kustomization.yaml: - -```yaml -namePrefix: pfx- -nameSuffix: -sfx -namespace: testnamespace - -resources: -... -``` - -### Resource and Kustomize Context matching - -Kustomize is now able to support more aggregation patterns. - -If for instance, the top level of kustomization.yaml, is simply -combining sub-components, (as in the following example), Kustomize has improved -resource matching capabilities. This removes some of the constraints which were -present on the utilization of prefix/suffix and namespace transformers in the -individual components. - -```yaml -resources: -- ../component1 -- ../component2 -- ../component3 -``` - -## Other improvements - -- Image transformation has been improved. This allows the user to update the sha256 of - an image with another sha256. -- Multiple default transformer configuration entries have been added, removing the need for the - user to add them as part of the `configurations:` section of the kustomization.yaml. -- `kustomize` help command has been tidied up. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v3.2.0.md b/site/content/zh/blog/releases/v3.2.0.md index fc52a39e9..e5240cef0 100644 --- a/site/content/zh/blog/releases/v3.2.0.md +++ b/site/content/zh/blog/releases/v3.2.0.md @@ -6,32 +6,6 @@ description: > Kustomize v3.2.0 --- -## Inline Patch + -Since this version, Kustomize allows inline patches in all three of `patchesStrategicMerge`, `patchesJson6902` and `patches`. Take a look at [inline patch](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/examples/inlinePatch.md). - -## New Subcommand - -Since this version, one can create a kustomization.yaml file in a directory through a `create` subcommand. - -Create a new overlay from the base ../base - -``` -kustomize create --resources ../base -``` - -Create a new kustomization detecing resources in the current directory - -``` -kustomize create --autodetect -``` - -Once can also add all resources in the current directory recursively by - -``` -kustomize create --autodetect --recursive -``` - -### New Example Generator - -A new example generator of using go-getter to download resources is added. Take a look at [go-getter generator](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/goGetterGeneratorPlugin.md). +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v3.2.1.md b/site/content/zh/blog/releases/v3.2.1.md index 3daa2b2d3..258d07e60 100644 --- a/site/content/zh/blog/releases/v3.2.1.md +++ b/site/content/zh/blog/releases/v3.2.1.md @@ -6,14 +6,6 @@ description: > Kustomize v3.2.1 --- -This is a patch release, with no new features from 3.2.0. + -It reflects a change in dependence. - -The kustomize binary is now built as a client, with no special -consideration, of the set of public packages represented by the Go -module at [https://github.com/kubernetes-sigs/kustomize]. - -kustomize the binary is now a client of the kustomize API -represented by the public package surface presented by -`https://github.com/kubernetes-sigs/kustomize/v{whatever}` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/blog/releases/v3.3.0.md b/site/content/zh/blog/releases/v3.3.0.md index 17c69cd85..b6fe55541 100644 --- a/site/content/zh/blog/releases/v3.3.0.md +++ b/site/content/zh/blog/releases/v3.3.0.md @@ -7,114 +7,6 @@ description: > --- -[versioning policy documentation]: /site/content/en/faq/versioningPolicy.md -[release process documentation]: /releasing + -## Summary of changes - -### First release of the Go API-only module - -Many of the PRs since the last vrelease were -around restructuring the _sigs.k8s.io/kustomize_ -repository into three Go modules instead of just one. - -The reasons for this are detailed in the [versioning -policy documentation], and what it means for releasing -is explained in the [release process documentation]. - -The tl;dr is that the top level module -`sigs.k8s.io/kustomize` now defines the kustomize Go -API, and the _kustomize_ CLI sits below it in an -independent module `sigs.k8s.io/kustomize/kustomize`. - -The modules release independently, though in practice a -new release of the kustomize Go API will likely be -followed quickly by a new release of the `kustomize` -executable. - -This is a necessary step to creating a much smaller -kustomize Go API surface that has some hope of -conforming to semantic versioning and being of some use -to clients. - -The kustomize CLI will see the same kustomize Go API as -any other client. - -The new semver-able API will begin with `v4.0.0` (not -yet released) and be a clean break with `v3` etc. - -### Change log since v3.2.0 - -``` -3c9d828f - Have kustomize CLI depend on kustomize Go API v3.3.0 (Jeffrey Regan) -5d800f0b - Merge pull request #1595 from monopole/threeReleases (Jeff Regan) -4eb2d5bc - Three builders. (Jeffrey Regan) -988af1ff - Update README.md (Jeff Regan) -1617183e - Merge pull request #1590 from monopole/releaseProcessUpdate (Kubernetes Prow Robot) -ee727464 - update release process doc (jregan) -c9e7dc3b - Merge pull request #1589 from monopole/moreTestsAroundKustFileName (Jeff Regan) -07e0e46a - improve tests for alternative kustomization file names (Jeffrey Regan) -404d2d63 - Merge pull request #1587 from monopole/reducePgmconfig (Jeff Regan) -baa0296a - Reduce size of pgmconfig package (Jeffrey Regan) -0f665ac1 - Merge pull request #1544 from ptux/add-transformer-href (Jeff Regan) -14b0a650 - Merge pull request #1581 from monopole/refactorFs (Jeff Regan) -2d58f8b8 - Break the dep between fs and pgmconfig. (Jeffrey Regan) -9a43ca53 - Merge pull request #1578 from nlamirault/fix/build-plugins-doc (Jeff Regan) -5372fc6f - Merge pull request #1579 from monopole/fsPackageCleanup (Jeff Regan) -86bc3440 - Merge pull request #1513 from nimohunter/fix_empty_list_item (Kubernetes Prow Robot) -a014f7d4 - Merge pull request #1561 from beautytiger/dev-190925 (Jeff Regan) -9a94bcb8 - Improve fs package and doc in prep to officially go public (Jeffrey Regan) -07634ef0 - Merge pull request #1575 from monopole/versioning (Jeff Regan) -995f88d6 - Update versioning notes. (jregan) -334a6467 - Fix: documentation link for plugins (Nicolas Lamirault) -08963ba5 - improve test code coverage in transformers (Guangming Wang) -326fb689 - Merge pull request #1570 from bzub/1234-go_plugin_doc (Jeff Regan) -970ce67c - Update goPluginCaveats.md (Jeff Regan) -98d18930 - Update INSTALL.md (Jeff Regan) -d89b448c - Fix git tag recovery in cloud build. (Jeff Regan) -17bf9d32 - Update releasing README. (Jeff Regan) -a99aff1d - Merge pull request #1571 from monopole/updateCloudBuildProcess (Kubernetes Prow Robot) -a694ac7b - Update cloud build process for kustomize. (Jeffrey Regan) -b5b11ef6 - Fix compile kustomize example. (bzub) -fa1af6f5 - Merge pull request #1473 from richardmarshall/execpluginhash (Jeff Regan) -9288dec0 - Fix failing BashedConfigMapTest (Jeff Regan) -1a45dd0b - Merge pull request #1566 from monopole/releaseNotes3.2.1 (Kubernetes Prow Robot) -592c5acf - docs: Exec plugin generator options (Richard Marshall) -ac9424fa - tests: Add unit tests for update resource options (Richard Marshall) -79fbe7c4 - Support resource generator options in exec plugins (Richard Marshall) -f69d526f - v3.2.1 release notes (Jeff Regan) -07a95a60 - Merge pull request #1565 from monopole/tweakBinaryDepsBeforeTagging (Jeff Regan) -032b3857 - Pin the kustomize binary's dependence on kustomize libs. (jregan) -81062959 - Merge pull request #1564 from monopole/moveKustomizeBinaryToOwnModule (Kubernetes Prow Robot) -b82a8fd3 - Move the kustomize binary to its own module. (Jeffrey Regan) -2d0c22d6 - Merge pull request #1562 from keleustes/tools (Kubernetes Prow Robot) -aa342def - Pin tool versions using go modules (Ian Howell) -10786ec0 - Merge pull request #1554 from keleustes/readme (Kubernetes Prow Robot) -7c705687 - Update README.md to include Kubernetes 1.16 (Jerome Brette) -e8933d97 - Merge pull request #1560 from monopole/precommitTuneup (Jeff Regan) -9d7b6544 - Make pre-commit more portable and less tricky. (jregan) -7a0946a9 - Merge pull request #1558 from monopole/dependOnNewPluginatorModule (Jeff Regan) -def4f045 - Depend on new pluginator location. (Jeffrey Regan) -2f2408f1 - Merge pull request #1559 from monopole/compressCopyright (Jeff Regan) -3b9bcc48 - Compress copyright in the commands package. (Jeffrey Regan) -d0429ff4 - Merge pull request #1557 from monopole/pluginatorModule (Jeff Regan) -33deefc3 - Copy pluginator to its own module. (Jeffrey Regan) -9b3de82b - Merge pull request #1506 from Liujingfang1/release (Jeff Regan) -d217074f - Merge pull request #1550 from keleustes/apiversion (Kubernetes Prow Robot) -1d90ba7c - Fix typo in apiVersion yaml declaration (Jerome Brette) -eeeb4c36 - Merge pull request #1547 from keleustes/extensions (Kubernetes Prow Robot) -b1faa989 - Update Ingress apiVersion to networking.k8s.io/v1beta1 (Jerome Brette) -d8250c9e - move test case (nimohunter) -c9500466 - add transformer href (Wang(わん)) -0c32691e - Merge pull request #1537 from jaypipes/gomod-install-note (Kubernetes Prow Robot) -88b1d627 - Merge pull request #1541 from rtnpro/patch-1 (Jeff Regan) -aec82066 - Update INSTALL.md (Jeff Regan) -20c2b53a - Merge pull request #1542 from monopole/tweakFilePathsInTest (Jeff Regan) -274b5c3b - Tweak file path handling and logging in test. (Jeffrey Regan) -b1fdaa23 - Fix typo in transformerconfigs README (Ratnadeep Debnath) -b5d5e70b - empty list or map item return error (nimohunter) -2e829853 - empty list or map item return error (nimohunter) -55941f57 - add note about GO111MODULE for source install (Jay Pipes) -9e226001 - empty list or map item return error (nimohunter) -77b63f96 - add release note for v3.2.0 (jingfangliu) -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/_index.md b/site/content/zh/contributing/_index.md index 26efdce47..3c0fe5af2 100644 --- a/site/content/zh/contributing/_index.md +++ b/site/content/zh/contributing/_index.md @@ -8,3 +8,7 @@ menu: --- 以下是 Kustomize 贡献指南。 + + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/bugs/_index.md b/site/content/zh/contributing/bugs/_index.md index a8a7ed4c8..bd0708ed4 100644 --- a/site/content/zh/contributing/bugs/_index.md +++ b/site/content/zh/contributing/bugs/_index.md @@ -8,50 +8,6 @@ description: > --- -[krusty package]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty -[reusable custom transformer test]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty/customconfigreusable_test.go + -File issues as desired, but if you've found a problem -with how `kustomize build` works, please report - -* the output of `kustomize version`, -* the input (the content of `kustomization.yaml` - and any files it refers to), -* the expected YAML output. - -## If you have `go` installed - -kustomize has a simple test harness in the [krusty -package] for specifying a kustomization's input and the -expected output. - -Copy one of those tests, e.g. this [reusable custom -transformer test], to a new test file in the -krusty package. - -Insert the inputs you want to use, and run it as -you'd run the reusable custom transformer test: - -``` -(cd api; go test -run TestReusableCustomTransformers ./krusty) -``` - -The output will demonstrate the bug or missing feature. - -Record this output in the test file in a call to -`AssertActualEqualsExpected`, per all the other tests -in the [krusty package]. This makes the test pass, -albeit with output demonstrating behavior you -presumably want to change. - -Send the new test in a PR, along with commentary (in -the test) on what you'd prefer to see. - -The person who fixes the bug then has a clear bug -reproduction and a test to modify when the bug is -fixed. - -Any bug fix first requires a test demonstrating the bug -(so we have permanent regression coverage), so if the -_bug reporter_ does this, it saves time and avoids -misunderstandings. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/community/_index.md b/site/content/zh/contributing/community/_index.md index 4fd045497..e3c9788c0 100644 --- a/site/content/zh/contributing/community/_index.md +++ b/site/content/zh/contributing/community/_index.md @@ -7,17 +7,6 @@ description: > Joining SIG-CLI and the Kubernetes community --- -[CLI special interest group]: https://github.com/kubernetes/community/tree/master/sig-cli#cli-special-interest-group -[contributor roles]: https://github.com/kubernetes/community/blob/master/community-membership.md#community-membership -[mailing list]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli -[bi-weekly meetings]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit?usp=sharing -[slack channel]: https://kubernetes.slack.com/messages/sig-cli + -Kustomize is a sub project of the Kubernetes [CLI special interest group] and follows the Kubernetes -project [contributor roles]. - -If you are interested in contributing towards Kustomize or getting more involved with the community: - -- join the [mailing list] and reach out -- join the [slack channel] and reach out -- attend one of the [bi-weekly meetings] (alternating Wednesdays at 9:00am Pacific Time) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/docs/_index.md b/site/content/zh/contributing/docs/_index.md index d57e48d8f..05bbd650e 100644 --- a/site/content/zh/contributing/docs/_index.md +++ b/site/content/zh/contributing/docs/_index.md @@ -7,75 +7,6 @@ description: > How to make Kustomize docs contributions --- -Kustomize uses [Docsy](https://www.docsy.dev) for the site, and was -forked from the [docsy-example](https://github.com/google/docsy-example) + -## Prerequisites - -- [Install hugo](https://gohugo.io/getting-started/installing/#fetch-from-github) -- Clone kustomize - - `git clone git@github.com:kubernetes-sigs/kustomize && cd kustomize/` - -## Development - -The doc input files are in the `site` directory. The site can be hosted locally using -`hugo serve`. - -```shell script -cd site/ -hugo serve -``` - -```shell script -... -Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender -Web Server is available at http://localhost:1313/kustomize/ (bind address 127.0.0.1) -``` - -## Publishing - -Hugo compiles the files under `site` Hugo into html which it puts in the `docs` folder: - -```shell script -cd site/ -hugo -``` - -```shell script - | EN --------------------+----- - Pages | 99 - Paginator pages | 0 - Non-page files | 0 - Static files | 47 - Processed images | 0 - Aliases | 2 - Sitemaps | 1 - Cleaned | 0 -``` - -Add the `site/` and `docs/` folders to a commit, then create a PR. - -## Publishing docs to your kustomize fork - -It is possible to have the kustomize docs published to your forks github pages. - -### Setup GitHub Pages for the fork - -1. Go to the *forked repo's* **Settings** tab - - e.g. [https://github.com/pwittrock/kustomize](https://github.com/pwittrock/kustomize) -2. Go to the **GitHub Pages** section -3. Set the source to master branch **/docs folder** - -### Publish to the fork's GitHub Pages - -{{% pageinfo color="info" %}} -Changes must be pushed to the fork's **master branch** to be served as the fork's GitHub Page. -{{% /pageinfo %}} - -1. Make a change to a file under `site/content` -2. Run `hugo` from the `site/` directory -3. Add the `site` and `docs` directories to the **master branch** -4. Commit and push the changes to the *remote fork's* **master branch** -5. After a few minutes, the docs should be served from the fork's GitHub Page - - e.g. [https://pwittrock.github.io/kustomize/](https://pwittrock.github.io/kustomize/) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/features/_index.md b/site/content/zh/contributing/features/_index.md index d241a136a..c4f69e739 100644 --- a/site/content/zh/contributing/features/_index.md +++ b/site/content/zh/contributing/features/_index.md @@ -7,31 +7,6 @@ description: > How to contribute features --- -[issue]: https://github.com/kubernetes-sigs/kustomize/issues -[sig-cli]: /kustomize/contributing/community/ -[meeting agenda]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit#heading=h.himo1st0tqyy -[KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli -[table-driven]: https://github.com/kubernetes-sigs/kustomize/blob/a8b9741866cf8e0c43e643ab7a9f40a3bd7e2a4d/api/filters/imagetag/imagetag_test.go#L15 -[eschewed feature list]: https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/ -[kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature + -Following is the process for proposing a new Kustomize feature: - -1. Check the [eschewed feature list] to see if the feature has already been proposed -2. File an [issue] describing the desired feature - - label it [kind/feature] - - the motivation for the feature - - example of how you would accomplish the motivating task *without* the feature - - example of how you would accomplish the motivating task *with* the feature -3. Email the [sig-cli] mailing list with the issue -4. Present the issue at [sig-cli] bi-weekly meeting on Zoom - - add it to the [meeting agenda] doc - - be present to discuss the feature - - response may be -- move forward with a PoC, not to move forward, defer and come back later, - or more information is needed. -5. Address the feedback on the issue - - Possibly write a KEP for tracking the feature -6. Implement the feature and send a PR - - Add [table-driven] tests - - Expect comments on the PR within 2 weeks -7. Kustomize team will release the kustomize `api` and `kustomize` modules +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/howitworks/_index.md b/site/content/zh/contributing/howitworks/_index.md index 1e204efe4..892f3817f 100644 --- a/site/content/zh/contributing/howitworks/_index.md +++ b/site/content/zh/contributing/howitworks/_index.md @@ -7,59 +7,6 @@ description: > How to modify Kustomize --- -{{% pageinfo color="info" %}} -To build kustomize using the locally modified modules, `replace` statements must be added to -the `kustomize/go.mod`. + -e.g. if code in `api` was modified, a `replace` statement would need to be added for the -`kustomize/api` module. -{{% /pageinfo %}} - -Call stack when running `kustomize build`, with links to code. - -## Run build - -* [RunBuild](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L121) - * [MakeKustomizer](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L32) - * [Run](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L47): performs a kustomization. It uses its internal filesystem reference to read the file at the given path argument, interpret it as a kustomization.yaml file, perform the kustomization it represents, and return the resulting resources. - * Create factories - * [tranformer.NewFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/k8sdeps/transformer/factory.go#L17) - * [resmap.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resmap/factory.go#L21) - * [resource.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resource/factory.go#L23) - * [kustruct.NewKunstructuredFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/kunstruct/factory.go#L28) - * [loader.NewLoader](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/loader/loader.go#L19) - * [validator.NewKustValidator](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/validator/validators.go#L23) - * [NewKustTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L38) - * [Load](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L54) - * [MakeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L109): details in next section - * [emitResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L143) - -## Make resource map - -* [makeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L117) - * [AccumulateTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L196): returns a new ResAccumulator, holding customized resources and the data/rules used to do so. The name back references and vars are not yet fixed. - * [accummulateResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L302): fills the given resourceAccumulator with resources read from the given list of paths. - * Merge config from builtin and CRDs - * [runGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L239) - * [configureBuiltinGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L28) - * ConfigMapGenerator - * SecretGenerator - * [configureExternalGenerators]() - * Iterate all generators - * [runTransfomers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L274) - * [configureBuiltinTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L44) - * PatchStrategicMergeTransformer - * PatchTransformer - * NamespaceTransformer - * PrefixSuffixTransformer - * LabelTransformer - * AnnotationsTransformer - * PatchJson6902Transformer - * ReplicaCountTransformer - * ImageTagTransformer - * [configureExternalTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L291) - * [MergeVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L64) - * The following steps must be done last, not as part of the recursion implicit in AccumulateTarget. - * [addHashesToNames](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L153) - * [FixBackReferences](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L160): Given that names have changed (prefixs/suffixes added), fix all the back references to those names. - * [ResolveVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L141) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/mac/_index.md b/site/content/zh/contributing/mac/_index.md index 0960c30ae..bdb3359fe 100644 --- a/site/content/zh/contributing/mac/_index.md +++ b/site/content/zh/contributing/mac/_index.md @@ -7,40 +7,6 @@ description: > How to develop on MacOS --- -First install the tools to build and run tests + -### Install go 1.13 - -[Instructions](https://golang.org/doc/install) - -Add `go` to your PATH - -### Install kubeval - -[Instructions](https://github.com/instrumenta/kubeval) - -```sh -go get github.com/instrumenta/kubeval -``` - -Add `kubeval` to your PATH - -### Install gnu tools - -[Instructions](https://www.topbug.net/blog/2013/04/14/install-and-use-gnu-command-line-tools-in-mac-os-x/) - -```sh -brew install coreutils wget gnu-sed tree -``` - -Add the new tools to your PATH - -## Make everything - -Verify your install by running `make`: - -```sh -make -``` - -Be default, this runs all tests needed to qualify a pull request. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/contributing/windows/_index.md b/site/content/zh/contributing/windows/_index.md index a0ec49a13..c65a49ccc 100644 --- a/site/content/zh/contributing/windows/_index.md +++ b/site/content/zh/contributing/windows/_index.md @@ -7,60 +7,6 @@ description: > How to develop on Windows --- -This is the PowerShell script to run all go tests for Kustomize on a windows based platform which mimics /build/pre-commit.sh + -## Pre-Reqs - -- PowerShell installed - - PowerShell Core is supported -- go installed -- golangci-lint installed -- mdrip installed - -This script should output to the current console and return an exit code if all tests are successful(0) or any failed(1). - -### If you are tryin to run these tests locally you can follow these instructions - -Assume: - -- Running a stock Windows 10 system -- Local Admin rights. -- You can open [PowerShell as administrator](http://lmgtfy.com/?iie=1&q=How+to+open+powershell+as+administrator) -- You should be knowledgeable enough to pull source for packages into your GO ```src``` directory - - Yes, this means you also need to know a bit about **git** usually - -#### Step 1 - Install Go - -- [Install Go](https://golang.org/dl/) - please use the msi - - If you use chocolatey - it's using the zip not msi and assumptions on where go is located are made for you. - -#### Step 2 - Install Go Packages - -- Open new PowerShell Administrative window - - Install golangci-lint - - ```go get -u github.com/golangci/golangci-lint/cmd/golangci-lint``` - - Install mdrip - - ```go get github.com/monopole/mdrip``` - -You should now be able to issue these commands and see comparable responses - -``` -C:\...> golangci-lint --help -Smart, fast linters runner. Run it in cloud for every GitHub pull request on https://golangci.com -... - -C:\...> mdrip --help -Usage: C:\_go\bin\mdrip.exe {fileName}... -... -``` - -#### Step 3 - Get Source and Test - -- In your GoRoot src - - ```Example: C:\_go\src``` -- Navigate to the Kustomize `travis` directory - - ```Example: C:\_go\src\sigs.k8s.io\kustomize\scripts``` -- Now Execute: - - ```.\Invoke-PreCommit.ps1``` - -This should run all pre-commit tests thus defined in the script. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/faq/_index.md b/site/content/zh/faq/_index.md index a226d9d2d..f3b0e5984 100644 --- a/site/content/zh/faq/_index.md +++ b/site/content/zh/faq/_index.md @@ -7,59 +7,6 @@ menu: weight: 70 --- -## security: file 'foo' is not in or below 'bar' + -v2.0 added a security check that prevents -kustomizations from reading files outside their own -directory root. - -This was meant to help protect the person inclined to -download kustomization directories from the web and use -them without inspection to control their production -cluster -(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693), -[#700](https://github.com/kubernetes-sigs/kustomize/pull/700), -[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and -[#998](https://github.com/kubernetes-sigs/kustomize/pull/998)) - -Resources (including configmap and secret generators) -can _still be shared_ via the recommended best practice -of placing them in a directory with their own -kustomization file, and referring to this directory as a -[`base`](/kustomize/api-reference/glossary#base) from any kustomization that -wants to use it. This encourages modularity and -relocatability. - -To disable this, use v3, and the `load_restrictor` flag: - -``` -kustomize build --load_restrictor none $target -``` - -## Some field is not transformed by kustomize - -Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc. - -The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -configurations: -- kustomizeconfig.yaml -``` - -The configuration directive allows customization of the following transformers: - -```yaml -commonAnnotations: [] -commonLabels: [] -nameprefix: [] -namespace: [] -varreference: [] -namereference: [] -images: [] -replicas: [] -``` - -To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/faq/eschewedfeatures/_index.md b/site/content/zh/faq/eschewedfeatures/_index.md index dc6332a14..99ea63899 100644 --- a/site/content/zh/faq/eschewedfeatures/_index.md +++ b/site/content/zh/faq/eschewedfeatures/_index.md @@ -7,156 +7,6 @@ description: > Eschewed Features --- -The maintainers established this list to -place bounds on the kustomize feature -set. The bounds can be changed with -a consensus on the risks. + -For a bigger picture about why kustomize -does some things and not others, see the -glossary entry for [DAM]. - -## Removal directives - -`kustomize` supports configurations that can be reasoned about as -_compositions_ or _mixins_ - concepts that are widely accepted as -a best practice in various programming languages. - -To this end, `kustomize` offers various _addition_ directives. -One may add labels, annotations, patches, resources, bases, etc. -Corresponding _removal_ directives are not offered. - -Removal semantics would introduce many possibilities for -inconsistency, and the need to add code to detect, report and -reject it. It would also allow, and possibly encourage, -unnecessarily complex configuration layouts. - -When faced with a situation where removal is desirable, it's -always possible to remove things from a base like labels and -annotations, and/or split multi-resource manifests into individual -resource files - then add things back as desired via the -[kustomization]. - -If the underlying base is outside of one's control, an [OTS -workflow] is the recommended best practice. Fork the base, remove -what you don't want and commit it to your private fork, then use -kustomize on your fork. As often as desired, use _git rebase_ to -capture improvements from the upstream base. - -## Unstructured edits - -_Structured edits_ are changes controlled by -knowledge of the k8s API, and YAML or JSON syntax. - -Most edits performed by kustomize can be expressed as -[JSON patches] or [SMP patches]. -Those can be verbose, so common patches, -like adding labels or annotatations, get dedicated -transformer plugins - `LabelTransformer`, -`AnnotationsTransformer`, etc. -These accept relatively simple YAML configuration -allowing easy targeting of any number of resources. - -Another class of edits take data from one specific -object's field and use it in another (e.g. a service -object's name found and copied into a container's -command line). These reflection-style edits -are called _replacements_. - -The above edits create valid output given valid input, -and can provide syntactically and semantically -informed error messages if inputs are invalid. - -_Unstructured edits_, edits that don't limit -themselves to a syntax or object structure, -come in many forms. A common one in the -configuration domain is the template or -parameterization approach. - -In this technique, the source -material is sprinkled with strings of the -form `${VAR}`. A scanner replaces them -with a value taken from a map using `VAR` -as the map key. It's trivial to implement. - -kustomize eschews parameterization, because - -- The source yaml gets polluted with `$VARs` - and can no longed be applied as is - to the cluster (it _must_ be processed). -- The source material is no longer structured, - making it unusable with any YAML processor. - It's no longer _data_, it's now logic that - must be compiled. -- Errors in the output are disconnected from - the edit that caused it. -- The input becomes [unintelligible] as the project - scales in any number of dimensions (resource - count, cluster count, environment count, etc.) - -Kustomizations are meant to be sharable and stackable. -Imagine tracing down a problem rooted in a -clever set of stacked regexp replacements -performed by various overlays on some remote base. -We've used such systems, and never want to again. - -Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet, -etc.) provide varying degrees of unstructured editting -and/or embedded languages, and can be used instead -of, or in a pipe with, kustomize. If you want to -go all-in on _configuration as a language_, consider [cue]. - -kustomize is going to stick to YAML in / YAML out. - -## Build-time side effects from CLI args or env variables - -`kustomize` supports the best practice of storing one's -entire configuration in a version control system. - -Changing `kustomize build` configuration output as a result -of additional arguments or flags to `build`, or by -consulting shell environment variable values in `build` -code, would frustrate that goal. - -`kustomize` insteads offers [kustomization] file `edit` -commands. Like any shell command, they can accept -environment variable arguments. - -For example, to set the tag used on an image to match an -environment variable, run - -``` -kustomize edit set image nginx:$MY_NGINX_VERSION -``` - -as part of some encapsulating work flow executed before -`kustomize build`. - -## Globs in kustomization files - -`kustomize` supports the best practice of storing one's -entire configuration in a version control system. - -Globbing the local file system for files not explicitly -declared in the [kustomization] file at `kustomize build` time -would violate that goal. - -Allowing globbing in a kustomization file would also introduce -the same problems as allowing globbing in [java import] -declarations or BUILD/Makefile dependency rules. - -`kustomize` will instead provide kustomization file editting -commands that accept globbed arguments, expand them at _edit -time_ relative to the local file system, and store the resulting -explicit names into the kustomization file. - -[base]: /kustomize/api-reference/glossary#base -[DAM]: /kustomize/api-reference/glossary#declarative-application-management -[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards -[JSON patches]: /kustomize/api-reference/glossary#patchjson6902 -[kustomization]: /kustomize/api-reference/glossary#kustomization -[OTS workflow]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[SMP patches]: /kustomize/api-reference/glossary#patchstrategicmerge -[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls -[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml -[cue]: https://cuelang.org/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/faq/versioningPolicy.md b/site/content/zh/faq/versioningPolicy.md index fa44f3937..090f35083 100644 --- a/site/content/zh/faq/versioningPolicy.md +++ b/site/content/zh/faq/versioningPolicy.md @@ -5,266 +5,6 @@ weight: 99 type: docs --- -Running `kustomize` means one is running a -particular version of a program (a CLI), using a -particular version of underlying packages (a Go -API), and reading a particular version of a -[kustomization] file. + -> If you're having trouble with `go get`, please -> read [Go API Versioning](#go-api-versioning) -> and be patient. - -## CLI Program Versioning - -The command `kustomize version` prints a three -field version tag (e.g. `v3.0.0`) that aspires to -[semantic versioning]. - -This notion of semver applies only to the CLI; -the command names, their arguments and their flags. - -The major version changes when some backward -incompatibility appears in how the commands -behave. - -### Installation - -See the [installation docs](INSTALL.md). - -## Go API Versioning - -The public methods in the public packages -of module `sigs.k8s.io/kustomize/api` constitute -the _kustomize Go API_. - -#### Version sigs.k8s.io/kustomize/v3 and earlier - -[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher - -In `kustomize/v3` (and preceding major versions), the -kustomize program and the API live the same Go -module at `sigs.k8s.io/kustomize`, at [import path] -`sigs.k8s.io/kustomize/v3`. - -This has been fine for the CLI, but it presents a -problem for the Go API. - -[minimal version selection]: https://research.swtch.com/vgo-mvs - -The process around Go modules, in particular the -notion of [minimal version selection], demands -that the module respect semver. - -Almost all the code in module -`sigs.k8s.io/kustomize/v3` is exposed (not in a -directory named `internal`). Even a minor -refactor changing a method name or argument type -in some deeply buried (but still public) method is -a backward incompatible change. As a result, Go -API semver hasn't been followed. This was a mistake. - -Some options are - -- continue to ignore Go API semver and stick to - CLI semver (eliminating the usefullness of - minimal version selection), - -- obey semver, and increment the module's major - version number with every release (drastically - reducing the usefullness of minimal version - selection - since virtually all releases will - be major), - -- slow down change in the huge API in favor of - stability, yet somehow continue to deliver - features, - -- drastically reduce the API surface, stabilize on - semver there, and refactor as needed inside - `internal`. - -The last option seems the most appealing. - -#### The first stable API version is coming - -The first stable API version will launch -as the Go module - -``` -sigs.k8s.io/kustomize/api -``` - -The _kustomize_ program itself (`main.go` -and CLI specific code) will have moved out of -`sigs.k8s.io/kustomize` and into the new module -`sigs.k8s.io/kustomize/kustomize`. This is a -submodule in the same repo, and it will retain its -current notion of semver (e.g. a backward -incompatible change in command behavior will -trigger a major version bump). This module will -not export packages; it's just home to a `main` -package. - -The `sigs.k8s.io/kustomize/api` module will -obey semver with a sustainable public -surface, informed by current usage. Clients -should import packages from this module, i.e. -from import paths prefixed by -`sigs.k8s.io/kustomize/api/` at first, -and later by `sigs.k8s.io/kustomize/api/v2/`. -The kustomize binary -itself is an API client requiring this module. - -The clients and API will evolve independently. - -## Kustomization File Versioning - -The kustomization file is a struct that is part of -the kustomize Go API (the `sigs.k8s.io/kustomize` -module), but it also evolves as a k8s API object - -it has an `apiVersion` field containing its -own version number. - -### Field Change Policy - -- A field's meaning cannot be changed. -- A field may be deprecated, then removed. -- Deprecation means triggering a _minor_ (semver) - version bump in the kustomize Go API, and - defining a migration path in a non-fatal error - message. -- Removal means triggering a _major_ (semver) - version bump in the kustomize Go API, and fatal - error if field encountered (as with any unknown - field). Likewise a change in `apiVersion`. - -### The `edit fix` Command - -This `kustomize` command reads a Kustomization -file, converts deprecated fields to new -fields, and writes it out again in the latest -format. - -This is a type version upgrade mechanism that -works within _major_ API revisions. There is no -downgrade capability, as there's no use case for -it (see discussion below). - -### Examples - -With the 2.0.0 release, there were three field -removals: - -- `imageTag` was deprecated when `images` was - introduced, because the latter offers more - general features for image data manipulation. - `imageTag` was removed in v2.0.0. -- `patches` was deprecated and replaced by - `patchesStrategicMerge` when `patchesJson6902` - was introduced, to make a clearer - distinction between patch specification formats. - `patches` was removed in v2.0.0. -- `secretGenerator/commands` was removed - due to security concerns in v2.0.0 - with no deprecation period. - -The `edit fix` command in a v2.0.x binary -will no longer recognize these fields. - -## Relationship to the k8s API - -### Review of k8s API versioning - -The k8s API has specific [conventions] and a -process for making [changes]. - -The presence of an `apiVersion` field in a k8s -native type signals: - -- its reliability level (alpha vs beta vs - generally available), -- the existence of code to provide default values - to fields not present in a serialization, -- the existence of code to provide both forward - and backward conversion between different - versions of types. - -The k8s API promises a lossless _conversion_ -between versions over a specific range. This -means that a recent client can write an object -bearing the newest possible value for its version, -the server will accept it and store it in -"versionless" JSON form in storage, and can -convert it to a range of older versions should -an older client request data. - -For native k8s types, this all requires writing Go -code in the kubernetes core repo, to provide -defaulting and conversions. - -For CRDs, there's a [proposal] on how to manage -versioning (e.g. a remote service can offer type -defaulting and conversions). - -### Differences - -- A k8s API server is able to go _forward_ and - _backward_ in versioning, to work with older - clients, over [some range]. -- The `kustomize edit fix` command only moves - _forward_ within a _major_ API - version. - -At the time of writing, the YAML in a -kustomization file does not represent a [k8s API] -object, and the kustomize command and associated -library is neither a server of, nor a client to, -the k8s API. - -### Additional Kustomization file rules - -In addition to the [field change policy] described -above, kustomization files conform to -the following rules. - -#### Eschew classic k8s fields - -Field names with dedicated meaning in k8s -(`metadata`, `spec`, `status`, etc.) aren't used. -This is enforced via code review. - -#### Default values for k8s `kind` and `apiVersion` - -In `v3` or below, the two [special] k8s -resource fields [`kind`] and [`apiVersion`] may -be omitted from the kustomization file. - -If either field is present, they both must be. -If present, the value of `kind` must be: - -> ``` -> kind: Kustomization -> ``` - -If missing, the value of `apiVersion` defaults to - -> ``` -> apiVersion: kustomize.config.k8s.io/v1beta1 -> ``` - -[field change policy]: #field-change-policy -[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy -[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md -[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions -[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md -[adapt]: /types/kustomization.go#L166 -[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources -[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md -[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md -[release page]: https://github.com/kubernetes-sigs/kustomize/releases -[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md -[kustomization]: /kustomize/api-reference/glossary#kustomization -[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds -[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning -[semantic versioning]: https://semver.org +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/_index.md b/site/content/zh/guides/_index.md index 50d94d93c..044e47034 100644 --- a/site/content/zh/guides/_index.md +++ b/site/content/zh/guides/_index.md @@ -9,3 +9,7 @@ menu: description: > Kustomize CLI 命令参考。 --- + + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/bespoke/_index.md b/site/content/zh/guides/bespoke/_index.md index 54067d022..12a129752 100644 --- a/site/content/zh/guides/bespoke/_index.md +++ b/site/content/zh/guides/bespoke/_index.md @@ -7,69 +7,6 @@ description: > 自定义配置的工作流。 --- -在这个工作流方式中，所有的配置文件（ YAML 资源）都为用户所有，存储在用户的私有 repo 中。其他用户是无法使用的。 + -![bespoke config workflow image][workflowBespoke] - -#### 1) 创建一个目录用于版本控制 - -我们希望将一个名为 _ldap_ 的 Kubernetes 集群应用的配置保存在自己的 repo 中。 -这里使用 git 进行版本控制。 - -> ``` -> git init ~/ldap -> ``` - -#### 2) 创建一个 [base] - -> ``` -> mkdir -p ~/ldap/base -> ``` - -在这个目录中创建并提交 [kustomization] 文件及一组资源 [resources] 配置。 - -#### 3) 创建 [overlays] - -> ``` -> mkdir -p ~/ldap/overlays/staging -> mkdir -p ~/ldap/overlays/production -> ``` - -每个目录都包含需要一个 [kustomization] 文件以及一或多个 [patches]。 - -在 _staging_ 目录可能会有一个用于在 configmap 中打开一个实验标记的补丁。 - -在 _production_ 目录可能会有一个在 deployment 中增加副本数的补丁。 - -#### 4) 生成 [variants] - -运行 kustomize，将生成的配置用于 kubernetes 应用发布。 - -> ``` -> kustomize build ~/ldap/overlays/staging | kubectl apply -f - -> kustomize build ~/ldap/overlays/production | kubectl apply -f - -> ``` - -也可以在 [kubectl-v1.14.0] 版，使用 ```kubectl``` 命令发布你的 [variants] 。 -> -> ``` -> kubectl apply -k ~/ldap/overlays/staging -> kubectl apply -k ~/ldap/overlays/production -> ``` - -[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[apply]: /kustomize/api-reference/glossary#apply -[applying]: /kustomize/api-reference/glossary#apply -[base]: /kustomize/api-reference/glossary#base -[fork]: https://guides.github.com/activities/forking/ -[variants]: /kustomize/api-reference/glossary#variant -[kustomization]: /kustomize/api-reference/glossary#kustomization -[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[overlays]: /kustomize/api-reference/glossary#overlay -[patch]: /kustomize/api-reference/glossary#patch -[patches]: /kustomize/api-reference/glossary#patch -[rebase]: https://git-scm.com/docs/git-rebase -[resources]: /kustomize/api-reference/glossary#resource -[workflowBespoke]: /kustomize/images/workflowBespoke.jpg -[workflowOts]: /kustomize/images/workflowOts.jpg -[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/offtheshelf/_index.md b/site/content/zh/guides/offtheshelf/_index.md index 7347a5a85..3b4b1ca16 100644 --- a/site/content/zh/guides/offtheshelf/_index.md +++ b/site/content/zh/guides/offtheshelf/_index.md @@ -7,73 +7,6 @@ description: > 使用通用配置的工作流。 --- -在这个工作流程中，所有文件都由用户拥有，并维护在他们控制的存储库中，但它们是基于一个现成的（[off-the-shelf]）配置，定期查询更新。 + -![off-the-shelf config workflow image][workflowOts] - -#### 1) 寻找并且 [fork] 一个 [OTS] 配置 - -#### 2) 将其克隆为你自己的 [base] - -这个 [base] 目录维护在上游为 [OTS] 配置的 repo ，在这个示例中使用 `ladp` 的 repo 。 - -> ```bash -> mkdir ~/ldap -> git clone https://github.com/$USER/ldap ~/ldap/base -> cd ~/ldap/base -> git remote add upstream git@github.com:$USER/ldap -> ``` - -#### 3) 创建 [overlays] - -如配置定制方法一样，创建并完善 _overlays_ 目录中的内容。 - -所有的 [overlays] 都依赖于 [base] 。 - -> ```bash -> mkdir -p ~/ldap/overlays/staging -> mkdir -p ~/ldap/overlays/production -> ``` - -用户可以将 `overlays` 维护在不同的 repo 中。 - -#### 4) 生成 [variants] - -> ```bash -> kustomize build ~/ldap/overlays/staging | kubectl apply -f - -> kustomize build ~/ldap/overlays/production | kubectl apply -f - -> ``` - -也可以在 [kubectl-v1.14.0] 版，使用 ```kubectl``` 命令发布你的 [variants] 。 -> -> ```bash -> kubectl apply -k ~/ldap/overlays/staging -> kubectl apply -k ~/ldap/overlays/production -> ``` - -#### 5) （可选）从上游更新 - -用户可以定期从上游 repo 中 [rebase] 他们的 [base] 以保证及时更新。 - -> ```bash -> cd ~/ldap/base -> git fetch upstream -> git rebase upstream/master -> ``` - -[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[apply]: /kustomize/api-reference/glossary#apply -[applying]: /kustomize/api-reference/glossary#apply -[base]: /kustomize/api-reference/glossary#base -[fork]: https://guides.github.com/activities/forking/ -[variants]: /kustomize/api-reference/glossary#variant -[kustomization]: /kustomize/api-reference/glossary#kustomization -[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[overlays]: /kustomize/api-reference/glossary#overlay -[patch]: /kustomize/api-reference/glossary#patch -[patches]: /kustomize/api-reference/glossary#patch -[rebase]: https://git-scm.com/docs/git-rebase -[resources]: /kustomize/api-reference/glossary#resource -[workflowBespoke]: /kustomize/images/workflowBespoke.jpg -[workflowOts]: /kustomize/images/workflowOts.jpg -[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/plugins/_index.md b/site/content/zh/guides/plugins/_index.md index 14291a97b..acda5ebc4 100644 --- a/site/content/zh/guides/plugins/_index.md +++ b/site/content/zh/guides/plugins/_index.md @@ -7,263 +7,6 @@ description: > Kustomize 插件指南 --- -Kustomize 提供一个插件框架，允许用户开发自己的 _生成器_ 和 _转化器_。 + -[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md -[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs - -通过插件，实现 [generatorOptions] 和 [transformerconfigs] 无法满足的需求。 - -[12-factor]: https://12factor.net - -* _generator_ 插件生成 k8s 资源，比如 [helm chart inflator] 是一个 generator 插件，基于少量自由变量生成一个 [12-factor] 应用所包含的全部组件 deployment，service，scaler，ingress 等）也是一个 generator 插件。 -* _transformer_ 插件转化（修改）k8s 资源，比如可能会执行对特殊容器命令行的编辑，或为其他内置转换器（`namePrefix`、`commonLabels` 等）无法转换的内容提供转换。 - -## `kustomization.yaml` 的格式 - -从为添加 `generators` 或 `transformers` 字段开始。 - -字段内容为一个 string list： - -> ```yaml -> generators: -> - relative/path/to/some/file.yaml -> - relative/path/to/some/kustomization -> - /absolute/path/to/some/kustomization -> - https://github.com/org/repo/some/kustomization -> -> transformers: -> - {as above} -> ``` - -格式要求与 `resources` 字段相同，`generators` 或 `transformers` 列表的每一列内容都必须是一个 YAML 文件的相对路径或者指向 [kustomization] 的 URL。 - -[kustomization]: /kustomize/zh/api-reference/glossary#kustomization - -从磁盘上读取 YAML 文件，kustomization 的路径或 URL 会触发 kustomization 的运行。由此产生的每个的对象都会被 kustomize 进一步解析为 _plugin configuration_ 对象。 - -## 配置 - -kustomization 文件可以包含如下内容： - -```yaml -generators: -- chartInflator.yaml -``` - -像这样，kustomization 进程将在 [kustomization root](glossary.md#kustomization-root) 下寻找到一个名为 `chartInflator.yaml` 的文件。 - -`chartInflator.yaml` 为插件配置文件，该文件包含 YAML 配置对象，内容如下： - -```yaml -apiVersion: someteam.example.com/v1 -kind: ChartInflator -metadata: - name: notImportantHere -chartName: minecraft -``` - -__`apiVersion` 和 `kind` 字段用于定位插件。__ - -[k8s 对象]: /kustomize/zh/api-reference/glossary#Kubernetes-风格的对象 - -同时由于 kustomize 插件配置对象也是一个 [k8s 对象]，因此这些字段是必要的。 - -为了让插件准备好生成或转换，它包含了配置文件的全部内容。 - -[NameTransformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go -[ChartInflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go -[plugins]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin - -更多关于插件配置 YAML 的例子，请浏览根目录下 [plugins] 中的单元测试，例如 [ChartInflator] 或 [NameTransformer]。 - -## 植入 - -每个插件都有自己的专用目录，名为： - -[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - -```bash -$XDG_CONFIG_HOME/kustomize/plugin - /${apiVersion}/LOWERCASE(${kind}) -``` - -The default value of [`XDG_CONFIG_HOME`] is -`$HOME/.config`. - -[`XDG_CONFIG_HOME`] 的默认值为 `$HOME/.config`。 - -为了便于插件包（源码、测试、插件数据文件等）的共享，要求每个目录存放一个插件。 - -在 [Go 插件](#go-插件)中，还可以为单个插件提供一个 `go.mod` 文件，可以缓解包版本依赖性偏移的问题。 - -加载时，kustomize 首先会寻找一个 _可执行_ 文件，名为： - -```bash -$XDG_CONFIG_HOME/kustomize/plugin - /${apiVersion}/LOWERCASE(${kind})/${kind} -``` - -如果没有找到这个文件，或者这个文件不是可执行的，kustomize 会在同一目录下寻找一个名为 `${kind}.so` 的文件，并尝试将其作为 [Go插件](#go-插件) 加载。 - -如果这两项检查都失败，则插件加载失败，`kustomize build` 失败。 - -## 执行情况 - -插件只有在运行 `kustomize build` 命令时使用。 - -生成器插件是在处理完 `resources` 字段后运行的（`resources` 字段本身也可以看成是一个简单地从磁盘上读取对象的生成器）。 - -之后所有资源将被传递到转换管道中，由其中内置的转换器，如 `namePrefix` 和 `commonLabel` 等先转换应用（如果 kustomization 文件中指定了他们），然后再转换用户指定的 `transformers` 字段。 - -由于无法指定转化的顺序，所以需要遵守 `transformers` 字段中指定的顺序。 - -#### No Security - -Kustomize 插件不会在任何形式的 kustomize 提供的沙盒中运行。不存在 _"plugin security"_ 的概念。 - -`kustomize build` 会尝试使用插件，但如果省略了 `--enable_alpha_plugins`，将导致插件无法加载，并且会有一个关于插件使用的警告。 - -使用这个 flag 就是承认使用不稳定的插件 API（alpha）、承认使用缺少出处插件，以及插件不属于 kustomize 的事实。 - -简单的说，一些从网上下载的 kustomize 插件可能会奇妙地将 k8s 的配置以理想的方式进行改造，同时也会悄悄地对运行 `kustomize build` 的系统做任何用户可以做的事情。 - -## 编写插件 - -插件有 [exec](#exec-插件) 和 [Go](#go-插件) 两种. - -### Exec 插件 - -_exec 插件_ 是一个可以在命令行中接收参数可执行文件，该参数指向包含 kustomization 配置的 YAML 文件。 - -> TODO: 对插件的限制，允许同一个 _exec 插件_ 同时被 `generators` 和 `transformers` 字段所触发。 -> -> - 第一个参数可以是固定的字符串 `generate` 或 `transform`，（配置文件的名称移动到第2个参数） -> - 默认情况下，exec plugin 会作为一个转化器,除非提供了标志 `-g`，将 exec 插件切换为生成器。 - -[helm chart inflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator -[bashed config map]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap -[sed transformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer -[hashicorp go-getter]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter - -#### 示例 - -* [helm chart inflator] - helm chart inflates 生成器。 -* [bashed config map] - 使用 bash 生成十分简单的 configMap。 -* [sed transformer] - 使用插件来定义非结构化的编辑。 -* [hashicorp go-getter] - 下载 kustomize layes 并通过构建它来生成资源。 - -生成器插件无需在 `stdin` 上输入任何东西，就会将生成的资源输出到 `stdout`。 - -转化器插件需要在 `stdin` 上输入资源的 YAML，并转化后的资源输出到 `stdout`。 - -kustomize 会使用 exec 插件适配器，为 `stdin` 提供的资源，并获取 `stdout` 以进行下一步的处理。 - -#### Generator 选项 - -生成器 exec 插件可以通过设置以下内部注释中的一个来调整生成器选项。 - -> 注意：这些注释只会在本地的 kustomize 中，不会出现在最终输出中。 - -**`kustomize.config.k8s.io/needs-hash`** - -通过包含 `needs-hash` 注释，可以将资源标记为需要由内部哈希转换器处理的资源。当设置注释的有效值为 `"true"` 和 `"false"` 时，分别启用或禁用资源的哈希后缀。忽略该注解相当于将值设置为 `"false"`。 - -如果此注释被设置在不受哈希转换器支持的资源上，将导致构建将失败。 - -示例： - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cm-test - annotations: - kustomize.config.k8s.io/needs-hash: "true" -data: - foo: bar -``` - -**`kustomize.config.k8s.io/behavior`** - -`behavior` 注释为当资源发生冲突时插件的处理方式，有效值包括："create"、"merge "和 "replace"，默认为 "create"。 - -示例： - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cm-test - annotations: - kustomize.config.k8s.io/behavior: "merge" -data: - foo: bar -``` - -### Go 插件 - -请务必阅读 [Go 插件注意事项](goPluginCaveats.md)。 - -[Go 插件]: https://golang.org/pkg/plugin/ - -如果一个 `.go` 文件声明 `package main`，并附加了有用的功能标志，那么它就可以成为一个 [Go 插件]。 - -如果标志被命名为 “KustomizePlugin”，并且附加的函数实现了 `Configurable`、`Generator` 和 `Transformer` 接口，那么它可以进一步作为 _kustomize_ 插件使用。 - -kustomize 的一个 Go 插件看起来是这样的： - -> ```go -> package main -> -> import ( -> "sigs.k8s.io/kustomize/api/ifc" -> "sigs.k8s.io/kustomize/api/resmap" -> ... -> ) -> -> type plugin struct {...} -> -> var KustomizePlugin plugin -> -> func (p *plugin) Config( -> ldr ifc.Loader, -> rf *resmap.Factory, -> c []byte) error {...} -> -> func (p *plugin) Generate() (resmap.ResMap, error) {...} -> -> func (p *plugin) Transform(m resmap.ResMap) error {...} -> ``` - -需要使用标识符 `plugin`，`KustomizePlugin` 并且需要实现方法签名 `Config`。 - -实现 `Generatoror` 或 `Transformer` 方法允许（分别）将插件的配置文件添加到 kustomization 文件的 `generatorsor` 或 `transformers` 字段中，并根据需要执行。 - -[secret generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase -[service generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator -[string prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer -[date prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer -[sops encoded secrets]: https://github.com/monopole/sopsencodedsecrets - -#### 示例 - -* [service generator] - 使用 name 和 port 参数生成一个 service。 -* [string prefixer] - 使用 `metadata/name` 值作为前缀。这个特殊的示例是为了展示插件的转化行为。详见 `target` 包中的 `TestTransformedTransformers` 测试。 -* [date prefixer] - 将当前日期作为前缀添加到资源名称上，这是一个用于修改刚才提到的字符串前缀插件的简单示例。 -* [secret generator] - 从 toy 数据库生成 secret。 -* [sops encoded secrets] - 一个更复杂的 secret 生成器。 -* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin). - 用户自制的插件与内置插件是一样的。 - -Go 插件既可以是生成器，也可以是转化器。`Generate` 方法将在 `Transform` 方法运行之前与所有其他生成器一起运行。 - -如下的构建命令，假设插件源代码位于 kustomize 期望查找 `.so` 文件的目录中： - -```bash -d=$XDG_CONFIG_HOME/kustomize/plugin\ -/${apiVersion}/LOWERCASE(${kind}) - -go build -buildmode plugin \ - -o $d/${kind}.so $d/${kind}.go -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/plugins/builtins.md b/site/content/zh/guides/plugins/builtins.md index 86c270135..33f924f2e 100644 --- a/site/content/zh/guides/plugins/builtins.md +++ b/site/content/zh/guides/plugins/builtins.md @@ -7,644 +7,6 @@ description: > 内置插件 --- -内置插件包括生成器和转化器。 + -每个插件都可以通过如下两种方式触发： - -* 通过 kustomization 文件的字段隐式触发插件，例如 `AnnotationsTransformer` 就是由 `commonAnnotations` 字段触发的。 - -* 通过 `generators` 或 `transformers` 字段显式触发插件（通过指定插件的配置文件）。 - -直接使用 `kustomization.yaml` 文件中的字段比如 `commonLables`、`commonAnnotation` 他们可以修改一些默认的字段，如果用户想要添加或减少能被 `commonLabel` 所修改的字段，则不是很容易做到；而使用 `transformers` 的话，用户可以指定哪些字段能被修改，而不受默认值的影响。 - -[types.GeneratorOptions]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/generatoroptions.go -[types.SecretArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/secretargs.go -[types.ConfigMapArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/configmapargs.go -[config.FieldSpec]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/fieldspec.go -[types.ObjectMeta]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/objectmeta.go -[types.Selector]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/selector.go -[types.Replica]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/replica.go -[types.PatchStrategicMerge]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchstrategicmerge.go -[types.PatchTarget]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchtarget.go -[image.Image]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/image.go - -## _AnnotationTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`commonAnnotations` - -为所有资源添加注释，和标签一样以 key: value 的形式。 - -```yaml -commonAnnotations: - oncallPager: 800-555-1212 -``` - -### 使用插件 - -#### Arguments - -> Annotations map\[string\]string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: AnnotationsTransformer -> metadata: -> name: not-important-to-example -> annotations: -> app: myApp -> greeting/morning: a string with blanks -> fieldSpecs: -> - path: metadata/annotations -> create: true -> ``` - -## _ConfigMapGenerator_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`configMapGenerator` - -列表中的每个条目都将生成一个 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 -# These labels are added to all configmaps and secrets. -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 -configMapGenerator: -- name: app-whatever - files: - - myFileName.ini=whatever.ini -``` - -### 使用插件 - -#### Arguments - -> [types.ConfigMapArgs] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: ConfigMapGenerator -> metadata: -> name: mymap -> envs: -> - devops.env -> - uxteam.env -> literals: -> - FRUIT=apple -> - VEGETABLE=carrot -> ``` - -## _ImageTagTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`images` - -修改镜像的名称、tag 或 image digest ，而无需使用 patches 。例如，对于这种 kubernetes Deployment 片段： - -```yaml -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 -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 -``` - -### 使用插件 - -#### Arguments - -> ImageTag [image.Image] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: ImageTagTransformer -> metadata: -> name: not-important-to-example -> imageTag: -> name: nginx -> newTag: v2 -> ``` - -## _LabelTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`commonLabels` - -为所有资源和 selectors 增加标签。 - -```yaml -commonLabels: - someName: someValue - owner: alice - app: bingo -``` - -### 使用插件 - -#### Arguments - -> Labels map\[string\]string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: LabelTransformer -> metadata: -> name: not-important-to-example -> labels: -> app: myApp -> env: production -> fieldSpecs: -> - path: metadata/labels -> create: true -> ``` - -## _NamespaceTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`namespace` - -为所有资源添加 namespace。 - -```yaml -namespace: my-namespace -``` - -### 使用插件 - -#### Arguments - -> [types.ObjectMeta] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: NamespaceTransformer -> metadata: -> name: not-important-to-example -> namespace: test -> fieldSpecs: -> - path: metadata/namespace -> create: true -> - path: subjects -> kind: RoleBinding -> group: rbac.authorization.k8s.io -> - path: subjects -> kind: ClusterRoleBinding -> group: rbac.authorization.k8s.io -> ``` - -## _PatchesJson6902_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`patchesJson6902` - -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 -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 -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" -``` - -### 使用插件 - -#### Arguments - -> Target [types.PatchTarget] -> -> Path string -> -> JsonOp string - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: PatchJson6902Transformer -> metadata: -> name: not-important-to-example -> target: -> group: apps -> version: v1 -> kind: Deployment -> name: my-deploy -> path: jsonpatch.json -> ``` - -## _PatchesStrategicMerge_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`patchesStrategicMerge` - -此列表中的每个条目都应可以解析为 [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 -patchesStrategicMerge: -- service_port_8888.yaml -- deployment_increase_replicas.yaml -- deployment_increase_memory.yaml -``` - -patch 内容也可以是一个inline string： - -```yaml -patchesStrategicMerge: -- |- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: nginx - spec: - template: - spec: - containers: - - name: nginx - image: nignx:latest -``` - -请注意，kustomize 不支持同一个 patch 对象中包含多个 _删除_ 指令。要从一个对象中删除多个字段或切片元素，需要创建一个单独的 patch，以执行所有需要的删除。 - -### 使用插件 - -#### Arguments - -> Paths \[\][types.PatchStrategicMerge] -> -> Patches string - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: PatchStrategicMergeTransformer -> metadata: -> name: not-important-to-example -> paths: -> - patch.yaml -> ``` - -## _PatchTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`patches` - -这个列表中的每个条目应该解析到一个 Patch 对象，其中包括一个 patch 和一个目标选择器。patch 可以是 Strategic Merge Patch 或 JSON patch，也可以是 patch 文件或 inline string。目标选择器可以通过 group、version、kind、name、namespace、标签选择器和注释选择器来选择资源，选择一个或多个匹配所有指定字段的资源来应用 patch。 - -```yaml -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" -``` - -The `name` and `namespace` fields of the patch target selector are -automatically anchored regular expressions. This means that the value `myapp` -is equivalent to `^myapp$`。 - -### 使用插件 - -#### Arguments - -> Path string -> -> Patch string -> -> Target \*[types.Selector] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: PatchTransformer -> metadata: -> name: not-important-to-example -> patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]' -> target: -> name: .*Deploy -> kind: Deployment -> ``` - -## _PrefixSuffixTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`namePrefix`, `nameSuffix` - -为所有资源的名称添加前缀或后缀。 - -例如：将 deployment 名称从 `wordpress` 变为 `alices-wordpress` 或 `wordpress-v2` 或 `alices-wordpress-v2`。 - -```yaml -namePrefix: alices- -nameSuffix: -v2 -``` - -如果资源类型是 ConfigMap 或 Secret，则在哈希值之前添加后缀。 - -### 使用插件 - -#### Arguments - -> Prefix string -> -> Suffix string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: PrefixSuffixTransformer -> metadata: -> name: not-important-to-example -> prefix: baked- -> suffix: -pie -> fieldSpecs: -> - path: metadata/name -> ``` - -## _ReplicaCountTransformer_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`replicas` - -修改资源的副本数。 - -例如：对于如下 kubernetes Deployment 片段： - -```yaml -kind: Deployment -metadata: - name: deployment-name -spec: - replicas: 3 -``` - -在 kustomization 中添加以下内容，将副本数更改为 5： - -```yaml -replicas: -- name: deployment-name - count: 5 -``` - -该字段内容为列表，所以可以同时修改许多资源。 - -由于这个声明无法设置 `kind:` 或 `group:`，所以他只能匹配如下资源中的一种： - -- `Deployment` -- `ReplicationController` -- `ReplicaSet` -- `StatefulSet` - -对于更复杂的用例，请使用 patch 。 - -### 使用插件 - -#### Arguments - -> Replica [types.Replica] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example -> -> ```yaml -> apiVersion: builtin -> kind: ReplicaCountTransformer -> metadata: -> name: not-important-to-example -> replica: -> name: myapp -> count: 23 -> fieldSpecs: -> - path: spec/replicas -> create: true -> kind: Deployment -> - path: spec/replicas -> create: true -> kind: ReplicationController -> ``` - -## _SecretGenerator_ - -### 使用 `kustomization.yaml` - -#### 字段名称：`secretGenerator` - -列表中的每个条目都将生成一个 Secret（合计可以生成 n 个 Secrets）。 - -功能与之前描述的 `configMapGenerator` 字段类似。 - -```yaml -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" -``` - -### 使用插件 - -#### Arguments - -> [types.ObjectMeta] -> -> [types.SecretArgs] - -#### Example - -> ```yaml -> apiVersion: builtin -> kind: SecretGenerator -> metadata: -> name: my-secret -> namespace: whatever -> behavior: merge -> envs: -> - a.env -> - b.env -> files: -> - obscure=longsecret.txt -> literals: -> - FRUIT=apple -> - VEGETABLE=carrot -> ``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/plugins/execPluginGuidedExample.md b/site/content/zh/guides/plugins/execPluginGuidedExample.md index 7ef50cdb8..4a3ec8ab2 100644 --- a/site/content/zh/guides/plugins/execPluginGuidedExample.md +++ b/site/content/zh/guides/plugins/execPluginGuidedExample.md @@ -7,206 +7,6 @@ description: > 60 秒在 Linux 构建一个 Exec 插件 --- -本教程只是一个快速开始的示例，完整的插件文档请看：[kustomize 插件](..) + -本示例将使用 bash 编写了一个简单的 _exec_ 插件，用来生成一个 `ConfigMap`。 - -尝试本教程不会破坏你的当前设置。 - -#### 环境要求 - -* `linux` -* `git` -* `curl` -* `Go 1.13` - -## 创建一个工作空间/目录 - -```bash -DEMO=$(mktemp -d) -``` - -## 编写 kustomization - -新建一个目录来保存所有的配置： - -```bash -MYAPP=$DEMO/myapp -mkdir -p $MYAPP -``` - -编写一个 Deployment 配置： - -```bash -cat <<'EOF' >$MYAPP/deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 3 - template: - spec: - containers: - - name: the-container - image: monopole/hello:1 - command: ["/hello", - "--port=8080", - "--date=$(THE_DATE)", - "--enableRiskyFeature=$(ENABLE_RISKY)"] - ports: - - containerPort: 8080 - env: - - name: THE_DATE - valueFrom: - configMapKeyRef: - name: the-map - key: today - - name: ALT_GREETING - valueFrom: - configMapKeyRef: - name: the-map - key: altGreeting - - name: ENABLE_RISKY - valueFrom: - configMapKeyRef: - name: the-map - key: enableRisky -EOF -``` - -编写一个 service 配置： - -```bash -cat <$MYAPP/service.yaml -kind: Service -apiVersion: v1 -metadata: - name: the-service -spec: - type: LoadBalancer - ports: - - protocol: TCP - port: 8666 - targetPort: 8080 -EOF -``` - -现在为您要编写的插件创建一个配置文件。 - -这个配置文件的内容也是 k8s 资源对象。其中 `apiVersion` 和 `kind` 字段的值用于在文件系统中查找插件代码（稍后会对此进行更多介绍）。 - -```bash -cat <<'EOF' >$MYAPP/cmGenerator.yaml -apiVersion: myDevOpsTeam -kind: SillyConfigMapGenerator -metadata: - name: whatever -argsOneLiner: Bienvenue true -EOF -``` - -最后在 kustomization 文件中引用以上所有内容： - -```bash -cat <$MYAPP/kustomization.yaml -commonLabels: - app: hello -resources: -- deployment.yaml -- service.yaml -generators: -- cmGenerator.yaml -EOF -``` - -检查这些文件 - -```bash -ls -C1 $MYAPP -``` - -## 为插件创建目录 - -插件必须位于特定的目录，以便 Kustomize 能够找到它们。 - -该示例将使用临时目录： - -```bash -PLUGIN_ROOT=$DEMO/kustomize/plugin -``` - -在上面定义的插件配置 `$MYAPP/cmGenerator.yaml` 中指定： - -> ```yaml -> apiVersion: myDevOpsTeam -> kind: SillyConfigMapGenerator -> ``` - -这意味着该插件必须位于以下目录中： - -```bash -MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator - -mkdir -p $MY_PLUGIN_DIR -``` - -插件的目录结构为： `apiVersion 的 value/小写 kind 的 value`。 - -插件拥有自己的目录，不但可以保存插件代码，还可以保存测试代码以需要的补充数据文件。 - -## 编写插件 - -插件有 _exec_ 和 _Go_ 两种. - -编写一个 _exec_ 插件，将其安装到正确的目录，文件名必须与插件的类型匹配（在本例中为 `SillyConfigMapGenerator`）： - -```bash -cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator -#!/bin/bash -# Skip the config file name argument. -shift -today=`date +%F` -echo " -kind: ConfigMap -apiVersion: v1 -metadata: - name: the-map -data: - today: $today - altGreeting: "$1" - enableRisky: "$2" -" -EOF -``` - -根据定义，_exec_ 插件必须是可执行的： - -```bash -chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator -``` - -## 安装 kustomize - -根据[文档](/kustomize/zh/installation)安装 kustomize: - -```bash -curl -s "https://raw.githubusercontent.com/\ -kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -mkdir -p $DEMO/bin -mv kustomize $DEMO/bin -``` - -## 检查目录结构 - -```bash -tree $DEMO -``` - -## 使用插件构建 APP - -```bash -XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP -``` - -之前如果您已经设置了 `PLUGIN_ROOT=$HOME/.config/kustomize/plugin`，则无需在 _kustomize_ 命令前使用 `XDG_CONFIG_HOME`。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/plugins/goPluginCaveats.md b/site/content/zh/guides/plugins/goPluginCaveats.md index 499bdb24c..a889b4139 100644 --- a/site/content/zh/guides/plugins/goPluginCaveats.md +++ b/site/content/zh/guides/plugins/goPluginCaveats.md @@ -7,67 +7,6 @@ description: > Go 插件注意事项 --- -[plugin package]: https://golang.org/pkg/plugin -[Go modules]: https://github.com/golang/go/wiki/Modules -[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format -[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op + -_Go 插件_ 是一个编译产品/组件，其定义见 [plugin package]，需要特殊的构建标志，不能单独运行，必须加载到正在运行的 Go 程序中。 - -> 用 Go 编写的普通程序可以作为 _exec 插件_，但是不能作为 _Go 插件_。 - -Go 插件允许运行 kustomize 扩展，而无需在每次运行时将资源分配到子流程或从子流程中解封所有资源数据。Go 插件 API 确保一定程度的一致性，以避免混淆下游转换器。 - -Go 插件的工作方式与 [plugin package] 中所述的相同，但与 _plugin_ 一词相关的常见概念不同。 - -## The skew problem - -Go 插件编译会创建一个 [ELF] 格式的 `.so` 文件，根据定义，该文件不包含有关目标代码来源的信息。 - -主程序 ELF 和插件 ELF 的编译条件（软件包依赖项的版本 `GOOS`，`GOARCH`）之间的偏移会导致插件加载失败，并带有无用的错误消息。 - -Exec 插件也会缺乏来源，但不会因编译不正确而失败。 - -在任何情况下，共享插件的最好方法是使用某种 _捆绑包_（git repo URL、git 存档文件、tar 包等），其中包含可解包至 `$XDG_CONFIG_HOME/kustomize/plugin` 的源代码，测试和相关数据。 - -对于 Go 插件，使用共享插件的最终用户 _必须同时编译 kustomize 和 plugin_。 - -这意味着一次性运行 - -```bash -# Or whatever is appropriate at time of reading -GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api -``` - -然后使用一个正常的开发周期 - -```bash -go build -buildmode plugin \ - -o ${wherever}/${kind}.so ${wherever}/${kind}.go -``` - -并根据需要调整路径和发行版本标记（例如 `v3.0.0`）。 - -为了进行比较，可以参考编写 [tensorflow plugin] 必须做的事情。 - -## 为什么支持 Go 插件 - -### 安全 - -Go 插件开发者可以操作与原生 kustomize 操作相同的 API，可确保某些语义、变量和检查等一致。exec 插件子进程通过 stdin/stdout 来处理这些问题，但对于下游的转化器和使用者来说，会更容易把事情搞砸。 - -关键点：如果插件通过 kustomize 提供的文件 `Loader` 接口读取文件，则会受到 kustomize 文件加载限制的约束。当然，除了代码审计之外，没有什么可以阻止 Go 插件导入 io 包并执行其所需的任何操作。 - -### Debugging - -Go 插件开发者可以在功能测试中运行插件时，在 _本地_ 调试插件，并在插件内部和其他位置设置断点。 - -为了获得两全其美的方式（共享性和安全性），开发人员可以编写一个 `.go` 程序作为 _exec 插件_，同时可以被 `go generate` 程序处理生成 Go 插件（反之亦然）。 - -### 贡献单元化 - -所有内置的生成器和转换器本身都是 Go 插件。这意味着 kustomize 维护者可以将贡献的插件升级为内置插件，而无需更改代码（超出常规代码审阅要求的范围）。 - -### 围绕生态系统发展 - -工具可以简化 Go 插件的 _共享_，但是这需要大量的 Go 插件的创作，而这又会导致围绕共享插件的混乱。[Go modules] 一旦被更广泛地采用，将解决共享插件最大的难题：含糊不清的插件 vs 主机依赖性。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/guides/plugins/goPluginGuidedExample.md b/site/content/zh/guides/plugins/goPluginGuidedExample.md index 91a1ba28d..8fb3b0835 100644 --- a/site/content/zh/guides/plugins/goPluginGuidedExample.md +++ b/site/content/zh/guides/plugins/goPluginGuidedExample.md @@ -7,301 +7,6 @@ description: > Go 插件示例 --- -[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets -[Go plugin]: https://golang.org/pkg/plugin -[Go plugin caveats]: ../goplugincaveats + -本教程只是一个快速开始的示例，完整的插件文档请看：[kustomize 插件](..) - -请务必阅读 [Go 插件注意事项](../goplugincaveats)。 - -该示例使用 Go 插件 `SopsEncodedSecrets`，该插件位于 [sopsencodedsecrets repository]中。这是一个进程内的 Go 插件，而不是恰巧用 Go 编写的 exec 插件（这是 Go 作者的另一种选择）。 - -尝试本教程不会破坏你的当前设置。 - -#### 环境要求 - -* `linux` -* `git` -* `curl` -* `Go 1.13` - -用于加密 - -* gpg - -或 - -* Google cloud (gcloud) 安装 -* 具有 KMS 权限的 Google帐户 - -## 创建一个工作空间/目录 - -```shell -# 将这些目录分开，以免造成 DEMO 目录的混乱。 -DEMO=$(mktemp -d) -tmpGoPath=$(mktemp -d) -``` - -## 安装 kustomize - -需要安装 kustomize v3.0.0，并且必须对其进行 _编译_（而不是从 release 页面下载二进制文件）： - -```shell -GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize -``` - -## 为插件创建目录 - -kustomize 插件完全由其配置文件和源代码确定。 - -Kustomize 插件的配置文件的格式与 kubernetes 资源对象相同，这就意味着在配置文件中 `apiVersion`，`kind` 和 `metadata` 都是[必须的字段](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)。 - -因为配置文件名出现在 kustomization 文件的 `generatorsor` 或 `transformers` 字段中，kustomize 会读取配置文件，然后在以下位置找到 Go 插件的目标代码： - -> ```shell -> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so -> ``` - -`lKind` 必须是小写字母的，然后将插件加载并提供其配置，插件的输出将成为整个 `kustomize build` 程序的一部分 。 - -同一插件在一个 kustomize 构建中可能会多次使用不同的配置文件。此外，kustomize 可能会先自定义 config 数据，然后再发送给插件。由于这些原因，插件不能自己去读取配置文件，而需要通过 kustomize 来读取配置。 - -该示例将在如下临时目录中存放其使用的插件： - -```shell -PLUGIN_ROOT=$DEMO/kustomize/plugin -``` - -并在下面的命令行中临时设置 `XDG_CONFIG_HOME`。 - -### 使用什么 apiVersion 和 kind - -在 kustomize 插件的开发时，插件代码不关心也不知道配置文件中的 `apiVersion` 或 `kind`。 - -插件会检查这些字段，但是剩下的字段提供了实际的配置数据，在这一点上，成功解析其他字段对于插件很重要。 - -本示例使用一个名为 _SopsEncodedSecrets_ 的插件，其位于 [SopsEncodedSecrets repository] 中。 - -我们选择安装插件到 - -```shell -apiVersion=mygenerators -kind=SopsEncodedSecrets -``` - -### 定义插件的主目录 - -按照惯例，存放插件代码和补充数据，测试，文档等的目录名称必须是 kind 的小写形式。 - -```shell -lKind=$(echo $kind | awk '{print tolower($0)}') -``` - -### 下载 SopsEncodedSecrets 插件 - -在这种情况下，存储库名称已经与小写字母的 kind 匹配，因此我们只需克隆存储库并自动获取正确的目录名称即可： - -```shell -mkdir -p $PLUGIN_ROOT/${apiVersion} -cd $PLUGIN_ROOT/${apiVersion} -git clone git@github.com:monopole/sopsencodedsecrets.git -``` - -记住这个目录： - -```shell -MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind} -``` - -### 尝试测试插件 - -插件可能会自己带有测试文件。因此可以通过如下方式： - -```shell -cd $MY_PLUGIN_DIR -go test SopsEncodedSecrets_test.go -``` - -构建对象代码以供 kustomize 使用： - -```shell -cd $MY_PLUGIN_DIR -GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go -``` - -此步骤可能会成功，但是由于依赖关系 [skew]，kustomize 最终可能无法加载该插件。 - -[skew]: /docs/plugins/README.md#caveats - -在加载失败时 - -* 确保使用相同版本的Go (_go1.13_)，在相同的 `$GOOS`(_linux_)和 `$GOARCH`(_amd64_) 上构建插件，用于构建本演示中使用的 [kustomize](#安装-kustomize)。 - -* 修改插件中的依赖文件 `go.mod` 以匹配 kustomize 使用的版本。 - -缺乏工具和元数据来实现自动化，就不会有一个完整的 Go 插件生态。 - -Kustomize 采用了 Go 插件架构，可以轻松的接受新的生成器和转换器（只需编写一个插件），并确保本机操作（也已作为插件构建和测试）是分段的、可排序的和可重用的，而不是奇怪的插入在整体代码中。 - -## 编写 kustomization - -新建一个 kustomization 目录存放你的配置： - -```shell -MYAPP=$DEMO/myapp -mkdir -p $MYAPP -``` - -为 SopsEncodedSecrets 插件编写一个配置文件。 - -插件可以通过 `apiVersion` 和 `kind` 找到： - -```shell -cat <$MYAPP/secGenerator.yaml -apiVersion: ${apiVersion} -kind: ${kind} -metadata: - name: mySecretGenerator -name: forbiddenValues -namespace: production -file: myEncryptedData.yaml -keys: -- ROCKET -- CAR -EOF -``` - -插件可以在 `myEncryptedData.yaml` 中找到更多的数据。 - -编写一个引用插件配置的 kustomization 文件： - -```shell -cat <$MYAPP/kustomization.yaml -commonLabels: - app: hello -generators: -- secGenerator.yaml -EOF -``` - -接下来生成真实的加密数据。 - -### 确保您已安装加密工具 - -我们将使用 [sops](https://github.com/mozilla/sops) 对文件进行编码。选择 GPG 或 Google Cloud KMS 作为加密提供者以继续。 - -#### GPG - -尝试这个命令： - -```shell -gpg --list-keys -``` - -如果返回 list，则您已经成功创建了密钥。如果不是，请尝试从 sops 导入测试密钥。 - -```shell -curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import -SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A" -``` - -#### Google Cloude KMS - -尝试这个命令： - -```shell -gcloud kms keys list --location global --keyring sops -``` - -如果成功了，想必你已经创建了密钥，并将其放置在一个名为 sops 的钥匙圈中。如果没有，那就这样做： - -```shell -gcloud kms keyrings create sops --location global -gcloud kms keys create sops-key --location global \ - --keyring sops --purpose encryption -``` - -通过如下方法，获取你的 keyLocation： - -```shell -keyLocation=$(\ - gcloud kms keys list --location global --keyring sops |\ - grep GOOGLE | cut -d " " -f1) -echo $keyLocation -``` - -### 安装 `sops` - -```shell -GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops -``` - -### 用你的私钥创建加密数据 - -创建需要加密的原始数据： - -```shell -cat <$MYAPP/myClearData.yaml -VEGETABLE: carrot -ROCKET: saturn-v -FRUIT: apple -CAR: dymaxion -EOF -``` - -将数据加密插入到插件要读取的文件中： - -使用 PGP - -```shell -$tmpGoPath/bin/sops --encrypt \ - --pgp $SOPS_PGP_FP \ - $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml -``` - -或者使用 GCP KMS - -```shell -$tmpGoPath/bin/sops --encrypt \ - --gcp-kms $keyLocation \ - $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml -``` - -查看文件 - -```shell -tree $DEMO -``` - -结果如下： - -> ```shell -> /tmp/tmp.0kIE9VclPt -> ├── kustomize -> │   └── plugin -> │   └── mygenerators -> │   └── sopsencodedsecrets -> │   ├── go.mod -> │   ├── go.sum -> │   ├── LICENSE -> │   ├── README.md -> │   ├── SopsEncodedSecrets.go -> │   ├── SopsEncodedSecrets.so -> │   └── SopsEncodedSecrets_test.go -> └── myapp -> ├── kustomization.yaml -> ├── myClearData.yaml -> ├── myEncryptedData.yaml -> └── secGenerator.yaml -> ``` - -## 使用插件构建您的应用 - -```shell -XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP -``` - -这将生成一个 kubernetes secret，并对名称 `ROCKET` 和 `CAR` 的数据进行加密。 - -之前如果您已经设置了 `PLUGIN_ROOT=$HOME/.config/kustomize/plugin`，则无需在 _kustomize_ 命令前使用 `XDG_CONFIG_HOME`。 +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/installation/_index.md b/site/content/zh/installation/_index.md index 96cf02418..e056d0b71 100644 --- a/site/content/zh/installation/_index.md +++ b/site/content/zh/installation/_index.md @@ -7,3 +7,8 @@ menu: main: weight: 10 --- + + + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/installation/binaries/_index.md b/site/content/zh/installation/binaries/_index.md index 01d698d7c..8b53259fa 100644 --- a/site/content/zh/installation/binaries/_index.md +++ b/site/content/zh/installation/binaries/_index.md @@ -7,14 +7,6 @@ description: > 下载编译好的二进制文件来安装 Kustomize。 --- -适用于 Linux、MacOS 和 Windows 的各版本的二进制可执行文件可以在 [releases 页面] 上手动下载。 + -下面的[脚本]会检测你的操作系统，并下载相应的 kustomize 二进制文件到你当前的工作目录中。 - -```bash -curl -s "https://raw.githubusercontent.com/\ -kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -``` - -[releases 页面]: https://github.com/kubernetes-sigs/kustomize/releases -[脚本]: https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/installation/chocolatey/_index.md b/site/content/zh/installation/chocolatey/_index.md index aa01e96dc..a853b554a 100644 --- a/site/content/zh/installation/chocolatey/_index.md +++ b/site/content/zh/installation/chocolatey/_index.md @@ -7,11 +7,6 @@ description: > Windows 系统可以使用 Chocolatey 安装 Kustomize。 --- -``` -choco install kustomize -``` + -有关软件包管理器 chocolatey 的使用以及对之前版本的支持，请参考以下链接： - -- [Choco Package](https://chocolatey.org/packages/kustomize) -- [Package Source](https://github.com/kenmaglio/choco-kustomize) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/installation/homebrew/_index.md b/site/content/zh/installation/homebrew/_index.md index 90fd8a6ae..15c67d343 100644 --- a/site/content/zh/installation/homebrew/_index.md +++ b/site/content/zh/installation/homebrew/_index.md @@ -7,14 +7,6 @@ description: > MacOS 系统可以使用 Homebrew 或 MacPorts 来安装 Kustomize。 --- -[Homebrew](https://brew.sh) 用户可以： + -``` -brew install kustomize -``` - -[MacPorts](https://www.macports.org) 用户可以： - -``` -sudo port install kustomize -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/zh/installation/source/_index.md b/site/content/zh/installation/source/_index.md index af544a0bc..9e10ec8e9 100644 --- a/site/content/zh/installation/source/_index.md +++ b/site/content/zh/installation/source/_index.md @@ -7,35 +7,6 @@ description: > 使用 Go 源码安装 Kustomize。 --- -需要先安装 [Go]。 + -## 无需克隆源码库直接构建 kustomize CLI - -```bash -GOBIN=$(pwd)/ GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3 -``` - -## 在本地克隆源码库构建 kustomize CLI - -```bash -# 需要 go 1.13 或更高版本 -unset GOPATH -# 详见 https://golang.org/doc/go1.13#modules -unset GO111MODULES - -# 拉取 repo -git clone git@github.com:kubernetes-sigs/kustomize.git -# 进入目录 -cd kustomize - -# 如果您不想从 HEAD 开始构建， 则可以选择切换特定的标签 -git checkout kustomize/v3.2.3 - -# 开始构建 -(cd kustomize; go install .) - -# 运行 -~/go/bin/kustomize version -``` - -[Go]: https://golang.org +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file