From a4e1ba0593a19b34089f2d963cc8a1475315629b Mon Sep 17 00:00:00 2001 From: guoxudong Date: Tue, 27 Aug 2019 13:57:17 +0800 Subject: [PATCH] update zh doc --- examples/zh/README.md | 4 +- examples/zh/image.md | 74 +++++++++++ examples/zh/jsonpatch.md | 2 +- examples/zh/patchMultipleObjects.md | 186 ++++++++++++++++++++++++++++ examples/zh/remoteBuild.md | 68 ++++++++++ 5 files changed, 331 insertions(+), 3 deletions(-) create mode 100644 examples/zh/image.md create mode 100644 examples/zh/patchMultipleObjects.md create mode 100644 examples/zh/remoteBuild.md diff --git a/examples/zh/README.md b/examples/zh/README.md index 42c628ef8..80e37757c 100644 --- a/examples/zh/README.md +++ b/examples/zh/README.md @@ -20,9 +20,9 @@ go get sigs.k8s.io/kustomize/v3/cmd/kustomize * [vars](vars.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。 - * [image names and tags](../image.md) - 在不使用 patch 的情况下更新镜像名称和标签。 + * [image names and tags](image.md) - 在不使用 patch 的情况下更新镜像名称和标签。 - * [remote target](../remoteBuild.md) - 通过 github URL 来构建 kustomization 。 + * [remote target](remoteBuild.md) - 通过 github URL 来构建 kustomization 。 * [json patch](jsonpatch.md) -在 kustomization 中应用 json patch 。 diff --git a/examples/zh/image.md b/examples/zh/image.md new file mode 100644 index 000000000..eb55264fc --- /dev/null +++ b/examples/zh/image.md @@ -0,0 +1,74 @@ +# 示例: 改变镜像名称和标签 + +首先构建一个工作空间： + + +```bash +DEMO_HOME=$(mktemp -d) +``` + +创建包含pod资源的 `kustomization` + + +```bash +cat <$DEMO_HOME/kustomization.yaml +resources: +- pod.yaml +EOF +``` + +创建pod资源声明 + + +```bash +cat <$DEMO_HOME/pod.yaml +apiVersion: v1 +kind: Pod +metadata: + name: myapp-pod + labels: + app: myapp +spec: + containers: + - name: myapp-container + image: busybox:1.29.0 + command: ['sh', '-c', 'echo The app is running! && sleep 3600'] + initContainers: + - name: init-mydb + image: busybox:1.29.0 + command: ['sh', '-c', 'until nslookup mydb; do echo waiting for mydb; sleep 2; done;'] +EOF +``` + +`myapp-pod` 包含一个init容器和一个普通容器，两者都使用 `busybox：1.29.0` 镜像。 + +在 `kustomization.yaml` 中添加 `images` 字段来更改镜像 `busybox` 和标签 `1.29.0` 。 + +- 通过 `kustomize` 添加 `images`： + + ```bash + cd $DEMO_HOME + kustomize edit set image busybox=alpine:3.6 + ``` + +- 将`images`字段将被添加到`kustomization.yaml`： + > ```yaml + > images: + > - name: busybox + > newName: alpine + > newTag: 3.6 + > ``` + +构建 `kustomization` + +```bash +kustomize build $DEMO_HOME +``` + +确认`busybox`镜像和标签是否被替换为`alpine：3.6`： + +``` +test 2 = \ + $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \ + echo $? +``` diff --git a/examples/zh/jsonpatch.md b/examples/zh/jsonpatch.md index 4d218b8ac..454cdf5e4 100644 --- a/examples/zh/jsonpatch.md +++ b/examples/zh/jsonpatch.md @@ -1,4 +1,4 @@ -# 例子: 应用 json patch（json补丁） +# 示例: 应用 json patch（json补丁） kustomization文件支持通过[JSON patches](https://tools.ietf.org/html/rfc6902)来修改已有的资源. diff --git a/examples/zh/patchMultipleObjects.md b/examples/zh/patchMultipleObjects.md new file mode 100644 index 000000000..dc04a8d04 --- /dev/null +++ b/examples/zh/patchMultipleObjects.md @@ -0,0 +1,186 @@ +[Strategic Merge Patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md +[JSON patches]: https://tools.ietf.org/html/rfc6902 +[label selector]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors + + +# 示例：通过一个 patch 来修改多个资源 + +kustomization 文件支持通过 [Strategic Merge Patch] 和 [JSON patch] 来自定义资源。 现在，一个 patch 可以应用于多个资源。 + +可以通过指定 patch 和 target 选择器来完成，如下所示： +```yaml +patches: +- path: + target: + group: + version: + kind: + name: + namespace: + labelSelector: + annotationSelector: +``` +`labelSelector` 和 `annotationSelector` 都应遵循 [label selector] 中的约定。Kustomize 选择匹配`target`中所有字段的目标来应用 patch 。 + +下面的示例展示了如何为所有部署资源注入 sidecar 容器。 + +创建一个包含 Deployment 资源的 `kustomization` 。 + + +```bash +DEMO_HOME=$(mktemp -d) + +cat <$DEMO_HOME/kustomization.yaml +resources: +- deployments.yaml +EOF + +cat <$DEMO_HOME/deployments.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: deploy1 +spec: + template: + metadata: + labels: + old-label: old-value + spec: + containers: + - name: nginx + image: nginx + args: + - one + - two +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: deploy2 +spec: + template: + metadata: + labels: + key: value + spec: + containers: + - name: busybox + image: busybox +EOF +``` + +声明 [Strategic Merge Patch] 文件以注入 sidecar 容器： + + +```bash +cat <$DEMO_HOME/patch.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: not-important +spec: + template: + spec: + containers: + - name: istio-proxy + image: docker.io/istio/proxyv2 + args: + - proxy + - sidecar +EOF +``` + +在 kustomization.yaml 中添加 _patches_ 字段 + + +```bash +cat <>$DEMO_HOME/kustomization.yaml +patches: +- path: patch.yaml + target: + kind: Deployment +EOF +``` + +运行 `kustomize build $DEMO_HOME`，可以在输出中确认两个 Deployment 资源都已正确应用。 + + +```bash +test 2 == \ + $(kustomize build $DEMO_HOME | grep "image: docker.io/istio/proxyv2" | wc -l); \ + echo $? +``` + +输出如下： + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: deploy1 +spec: + template: + metadata: + labels: + old-label: old-value + spec: + containers: + - args: + - proxy + - sidecar + image: docker.io/istio/proxyv2 + name: istio-proxy + - args: + - one + - two + image: nginx + name: nginx +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: deploy2 +spec: + template: + metadata: + labels: + key: value + spec: + containers: + - args: + - proxy + - sidecar + image: docker.io/istio/proxyv2 + name: istio-proxy + - image: busybox + name: busybox +``` + +## Target selector + +- 选择名称与 `name*` 匹配的资源 + ```yaml + target: + name: name* + ``` +- 选择所有 Deployment 资源 + ```yaml + target: + kind: Deployment + ``` +- 选择 label 与 `app=hello` 匹配的资源 + ```yaml + target: + labelSelector: app=hello + ``` +- 选择 annotation 与 `app=hello` 匹配的资源 + ```yaml + target: + annotationSelector: app=hello + ``` +- 选择所有 label 与 `app=hello` 匹配的 Deployment 资源 + ```yaml + target: + kind: Deployment + labelSelector: app=hello + ``` \ No newline at end of file diff --git a/examples/zh/remoteBuild.md b/examples/zh/remoteBuild.md new file mode 100644 index 000000000..2485b7f99 --- /dev/null +++ b/examples/zh/remoteBuild.md @@ -0,0 +1,68 @@ +# remote targets + +`kustomize build` 可以将 URL 作为参数传入并运行. + +运行效果与 clone repo，checkout 特定的 _ref_（commit hash, branch 名称, release tag 等），然后针对所需的目录运行 `kustomize build`。 + +如果想要要立即尝试此操作，可以按照 [multibases](../multibases/README.md) 示例运行 kustomization 运行构建。然后查看输出中的pod： + + + +```bash +target="github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6" +test 1 == \ + $(kustomize build $target | grep dev-myapp-pod | wc -l); \ + echo $? +``` + +在该示例中运行 overlay 将获得三个 pod（在此 overlay 结合了dev、staging 和 prod 的 bases，以便同时将它们全部发送给所有人）： + + +```bash +target="https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6" +test 3 == \ + $(kustomize build $target | grep cluster-a-.*-myapp-pod | wc -l); \ + echo $? +``` + +将 URL 作为 base ： + + +```bash +DEMO_HOME=$(mktemp -d) + +cat <$DEMO_HOME/kustomization.yaml +resources: +- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 +namePrefix: remote- +EOF +``` + +构建该 base 以确定所有的三个 pod 都有 `remote-` 前缀。 + + +```bash +test 3 == \ + $(kustomize build $DEMO_HOME | grep remote-.*-myapp-pod | wc -l); \ + echo $? +``` + +## URL format + +URL 需要遵循 [hashicorp/go-getter URL 格式](https://github.com/hashicorp/go-getter#url-format) 。下面是一些遵循此约定的 Github repos 示例url。 + +- kustomization.yaml 在根目录 + + `github.com/Liujingfang1/mysql` +- kustomization.yaml 在 test 分支的根目录 + + `github.com/Liujingfang1/mysql?ref=test` +- kustomization.yaml 在 v1.0.6 版本的子目录 + + `github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6` +- kustomization.yaml repoUrl2 分支的子目录 + + `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=repoUrl2` +- kustomization.yaml commit `7050a45134e9848fca214ad7e7007e96e5042c03` 的子目录 + + `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=7050a45134e9848fca214ad7e7007e96e5042c03`