From 404884e2957e92717f3724daaf4f71391a9eb6c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=83=AD=E6=97=AD=E4=B8=9C?= Date: Fri, 24 May 2019 13:31:11 +0800 Subject: [PATCH 1/2] chinese helloworld doc --- examples/zh/README-CN.md | 2 +- examples/zh/helloWorld.md | 303 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 304 insertions(+), 1 deletion(-) create mode 100644 examples/zh/helloWorld.md diff --git a/examples/zh/README-CN.md b/examples/zh/README-CN.md index d237659d8..8c82748ab 100644 --- a/examples/zh/README-CN.md +++ b/examples/zh/README-CN.md @@ -11,7 +11,7 @@ go get sigs.k8s.io/kustomize ``` - * [hello world](../helloWorld/README.md) - 部署多个不同配置的 Hello World 服务。 + * [hello world](helloWorld.md) - 部署多个不同配置的 Hello World 服务。 * [last mile helm](../chart.md) - 对 helm chart 进行 last mile 修改。 diff --git a/examples/zh/helloWorld.md b/examples/zh/helloWorld.md new file mode 100644 index 000000000..423ef0555 --- /dev/null +++ b/examples/zh/helloWorld.md @@ -0,0 +1,303 @@ +[base]: ../../docs/glossary.md#base +[config]: https://github.com/kinflate/example-hello +[gitops]: ../../docs/glossary.md#gitops +[hello]: https://github.com/monopole/hello +[kustomization]: ../../docs/glossary.md#kustomization +[original]: https://github.com/kinflate/example-hello +[overlay]: ../../docs/glossary.md#overlay +[overlays]: ../../docs/glossary.md#overlay +[patch]: ../../docs/glossary.md#patch +[variant]: ../../docs/glossary.md#variant +[variants]: ../../docs/glossary.md#variant + +# Demo: hello world with variants + +步骤： + + 1. 拉取已经存在的的 [base] 配置。 + 1. 进行定制。 + 1. 基于定制后的 base 新建2个不同的 [overlays] (_staging_ 和 _production_)。 + 1. 运行 kustomize 和 kubectl 来部署 staging 和 production 。 + +首先创建一个工作空间： + + +``` +DEMO_HOME=$(mktemp -d) +``` + +或者： + +> ``` +> DEMO_HOME=~/hello +> ``` + +## 创建 base + +让我们开始运行 [hello] 服务。 + +如果要使用 [overlays] 创建 [variants] ，必须先创建一个共同的 [base] 。 + +为了使本文档保持简洁，base 的资源位于补充目录中，并不在此处，请按照下面的方法下载它们： + + +``` +BASE=$DEMO_HOME/base +mkdir -p $BASE + +curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\ +/kubernetes-sigs/kustomize\ +/master/examples/helloWorld\ +/{configMap,deployment,kustomization,service}.yaml" +``` + +观察该目录： + + +``` +tree $DEMO_HOME +``` + +可以看到： + +> ``` +> /tmp/tmp.IyYQQlHaJP +> └── base +> ├── configMap.yaml +> ├── deployment.yaml +> ├── kustomization.yaml +> └── service.yaml +> ``` + +这些 resources 可以立即在 k8s 集群中部署： + +> ``` +> kubectl apply -f $DEMO_HOME/base +> ``` + +实例化 _hello_ 服务， `kubectl` 只能识别 resources 文件。 + + +### The Base Kustomization + +`base` 目录中包含一个 [kustomization] 文件： + + +``` +more $BASE/kustomization.yaml +``` + +（可选）在 base 上运行 `kustomize` 将自定义 resources 输出到 `stdout` ： + + +``` +kustomize build $BASE +``` + +### 定制 base + +定制 _app label_ 并应用于所有的 resources ： + + +``` +sed -i.bak 's/app: hello/app: my-hello/' \ + $BASE/kustomization.yaml +``` + +查看效果： + +``` +kustomize build $BASE | grep -C 3 app: +``` + +## 创建 Overlays + +创建包含 _staging_ 和 _production_ 的 [overlay]： + + * _Staging_ 包含生产环境中无法应用的带有风险的功能。 + * _Production_ 包含更多的副本数。 + * 来自这些集群 [variants] 的问候将与来自其他集群的不同。 + + +``` +OVERLAYS=$DEMO_HOME/overlays +mkdir -p $OVERLAYS/staging +mkdir -p $OVERLAYS/production +``` + +#### Staging Kustomization + +在 `staging` 目录中创建一个 kustomization 文件，用来定义一个新的 name 前缀和一些不同的 labels 。 + + +``` +cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml +namePrefix: staging- +commonLabels: + variant: staging + org: acmeCorporation +commonAnnotations: + note: Hello, I am staging! +bases: +- ../../base +patchesStrategicMerge: +- map.yaml +EOF +``` + +#### Staging Patch + +新增一个自定义的 configMap 将问候从 _Good Morning!_ 改为 _Have a pineapple!_ 。 + +同时，将 _risky_ 标记设置为 true 。 + + +``` +cat <$OVERLAYS/staging/map.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: the-map +data: + altGreeting: "Have a pineapple!" + enableRisky: "true" +EOF +``` + +#### Production Kustomization + +在 `production` 目录中创建一个 kustomization 文件，用来定义一个新的 name 前缀和 labels 。 + + +``` +cat <$OVERLAYS/production/kustomization.yaml +namePrefix: production- +commonLabels: + variant: production + org: acmeCorporation +commonAnnotations: + note: Hello, I am production! +bases: +- ../../base +patchesStrategicMerge: +- deployment.yaml +EOF +``` + + +#### Production Patch + +因为生产环境需要处理更多的流量，新建一个 production patch 来增加副本数。 + + +``` +cat <$OVERLAYS/production/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 10 +EOF +``` + +## 比较 overlays + + +`DEMO_HOME` 现在包含： + + - _base_ 目录：对拉取到的源配置进行了简单定制 + + - _overlays_ 目录：包含在集群中创建不同 _staging_ 和 _production_ [variants] 的 kustomizations 和 patches 。 + +查看目录结构和差异： + + +``` +tree $DEMO_HOME +``` + +可以看到： + +> ``` +> /tmp/tmp.IyYQQlHaJP1 +> ├── base +> │   ├── configMap.yaml +> │   ├── deployment.yaml +> │   ├── kustomization.yaml +> │   └── service.yaml +> └── overlays +> ├── production +> │   ├── deployment.yaml +> │   └── kustomization.yaml +> └── staging +> ├── kustomization.yaml +> └── map.yaml +> ``` + +直接比较 _staging_ 和 _production_ 输出的不同： + + +``` +diff \ + <(kustomize build $OVERLAYS/staging) \ + <(kustomize build $OVERLAYS/production) |\ + more +``` + +部分比较输出： + +> ```diff +> < altGreeting: Have a pineapple! +> < enableRisky: "true" +> --- +> > altGreeting: Good Morning! +> > enableRisky: "false" +> 8c8 +> < note: Hello, I am staging! +> --- +> > note: Hello, I am production! +> 11c11 +> < variant: staging +> --- +> > variant: production +> 13c13 +> (...truncated) +> ``` + + +## 部署 + +输出不同 _overlys_ 的配置： + + +``` +kustomize build $OVERLAYS/staging +``` + + +``` +kustomize build $OVERLAYS/production +``` + +将上述命令传递给 kubectl 进行部署： + +> ``` +> kustomize build $OVERLAYS/staging |\ +> kubectl apply -f - +> ``` + +> ``` +> kustomize build $OVERLAYS/production |\ +> kubectl apply -f - +> ``` + +也可使用 `kubectl` (v1.14.0 以上版本)： + +> ``` +> kubectl apply -k $OVERLAYS/staging +> ``` + +> ``` +> kubectl apply -k $OVERLAYS/production +> ``` \ No newline at end of file From 7765bdd9670082255f609119e188e355852cd2d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=83=AD=E6=97=AD=E4=B8=9C?= Date: Wed, 29 May 2019 15:22:41 +0800 Subject: [PATCH 2/2] fix some doc --- examples/README.md | 2 +- examples/zh/README-CN.md | 44 ------------------------------- examples/zh/README.md | 55 +++++++++++++++++++++++++++++++++++++++ examples/zh/helloWorld.md | 20 +++++++------- 4 files changed, 65 insertions(+), 56 deletions(-) delete mode 100644 examples/zh/README-CN.md create mode 100644 examples/zh/README.md diff --git a/examples/README.md b/examples/README.md index 1954fd60b..3c8a50865 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,4 +1,4 @@ -English | [简体中文](zh/README-CN.md) +English | [简体中文](zh/README.md) # Examples diff --git a/examples/zh/README-CN.md b/examples/zh/README-CN.md deleted file mode 100644 index 1c3c5d7a5..000000000 --- a/examples/zh/README-CN.md +++ /dev/null @@ -1,44 +0,0 @@ -[English](../README.md) | 简体中文 - -# 示例 - -这些示例默认 `kustomize` 在您的 `$PATH` 中。 - -这些示例通过了 [pre-commit](../../bin/pre-commit.sh) 测试，并且应该与 HEAD 一起使用。 - -``` -go get sigs.k8s.io/kustomize -``` - - * [hello world](helloWorld.md) - 部署多个不同配置的 Hello World 服务。 - - * [last mile helm](../chart.md) - 对 helm chart 进行 last mile 修改。 - - * [LDAP](../ldap/README.md) - 部署多个配置不同的 LDAP 服务。 - - * [mySql](../mySql/README.md) - 从头开始创建一个 MySQL 的生产配置。 - - * [springboot](../springboot/README.md) - 从头开始创建一个 Spring Boot 项目的生产配置。 - - * [combineConfigs](../combineConfigs.md) - - 融合来自不同用户的配置数据（例如来自 devops/SRE 和 developers）。 - - * [configGenerations](../configGeneration.md) - 当 ConfigMapGenerator 修改时进行滚动更新。 - - * [secret generation](../secretGeneratorPlugin.md) - 生成 Secret。 - - * [generatorOptions](../generatorOptions.md) -修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。 - - * [breakfast](../breakfast.md) - 给 Alice 和 Bob 定制一顿早餐 :) - - * [vars](../wordpress/README.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。 - - * [image names and tags](../image.md) - 在不使用 patch 的情况下更新镜像名称和标签。 - - * [multibases](../multibases/README.md) - 使用相同的 base 生成三个 variants（dev，staging，production）。 - - * [remote target](../remoteBuild.md) - 通过 github URL 来构建 kustomization 。 - - * [json patch](../jsonpatch.md) -在 kustomization 中应用 json patch 。 - - * [transformer configs](../transformerconfigs/README.md) - 自定义 transformer 配置。 diff --git a/examples/zh/README.md b/examples/zh/README.md new file mode 100644 index 000000000..52099654a --- /dev/null +++ b/examples/zh/README.md @@ -0,0 +1,55 @@ +[English](../README.md) | 简体中文 + +# 示例 + +这些示例默认 `kustomize` 在您的 `$PATH` 中。 + +这些示例通过了 [pre-commit](../../bin/pre-commit.sh) 测试，并且应该与 HEAD 一起使用。 + +``` +go get sigs.k8s.io/kustomize +``` + +基本用法 + + * [configGenerations](../configGeneration.md) - 当 ConfigMapGenerator 修改时进行滚动更新。 + + * [combineConfigs](../combineConfigs.md) - 融合来自不同用户的配置数据（例如来自 devops/SRE 和 developers）。 + + * [generatorOptions](../generatorOptions.md) -修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。 + + * [vars](../wordpress/README.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。 + + * [image names and tags](../image.md) - 在不使用 patch 的情况下更新镜像名称和标签。 + + * [remote target](../remoteBuild.md) - 通过 github URL 来构建 kustomization 。 + + * [json patch](../jsonpatch.md) -在 kustomization 中应用 json patch 。 + +高级用法 + + - generator 插件: + + * [last mile helm](../chart.md) - 对 helm chart 进行 last mile 修改。 + + * [secret generation](../secretGeneratorPlugin.md) - 生成 Secret。 + + - 定制内建 transformer 配置 + + * [transformer configs](../transformerconfigs/README.md) - 自定义 transformer 配置。 + +多 Variant 示例 + + * [hello world](helloWorld.md) - 部署多个不同配置的 Hello World 服务。 + + * [LDAP](../ldap/README.md) - 部署多个配置不同的 LDAP 服务。 + + * [springboot](../springboot/README.md) - 从头开始创建一个 Spring Boot 项目的生产配置。 + + * [mySql](../mySql/README.md) - 从头开始创建一个 MySQL 的生产配置。 + + * [breakfast](../breakfast.md) - 给 Alice 和 Bob 定制一顿早餐 :) + + * [multibases](../multibases/README.md) - 使用相同的 base 生成三个 variants（dev，staging，production）。 + +>声明：部分文档可能稍微滞后于英文版本，同步工作持续进行中 \ No newline at end of file diff --git a/examples/zh/helloWorld.md b/examples/zh/helloWorld.md index 423ef0555..9ecf87294 100644 --- a/examples/zh/helloWorld.md +++ b/examples/zh/helloWorld.md @@ -14,10 +14,10 @@ 步骤： - 1. 拉取已经存在的的 [base] 配置。 - 1. 进行定制。 - 1. 基于定制后的 base 新建2个不同的 [overlays] (_staging_ 和 _production_)。 - 1. 运行 kustomize 和 kubectl 来部署 staging 和 production 。 + 1. 下载 [base] 配置。 + 2. 进行定制。 + 3. 基于定制后的 base 新建2个不同的 [overlays] (_staging_ 和 _production_)。 + 4. 运行 kustomize 和 kubectl 来部署 staging 和 production 。 首先创建一个工作空间： @@ -34,8 +34,6 @@ DEMO_HOME=$(mktemp -d) ## 创建 base -让我们开始运行 [hello] 服务。 - 如果要使用 [overlays] 创建 [variants] ，必须先创建一个共同的 [base] 。 为了使本文档保持简洁，base 的资源位于补充目录中，并不在此处，请按照下面的方法下载它们： @@ -87,7 +85,7 @@ tree $DEMO_HOME more $BASE/kustomization.yaml ``` -（可选）在 base 上运行 `kustomize` 将自定义 resources 输出到 `stdout` ： +（可选）在 base 目录上运行 `kustomize` 将定制过的 resources 打印到标准输出： ``` @@ -116,7 +114,7 @@ kustomize build $BASE | grep -C 3 app: * _Staging_ 包含生产环境中无法应用的带有风险的功能。 * _Production_ 包含更多的副本数。 - * 来自这些集群 [variants] 的问候将与来自其他集群的不同。 + * 来自这些集群 [variants] 的问候消息将与来自其他集群的不同。 ``` @@ -127,7 +125,7 @@ mkdir -p $OVERLAYS/production #### Staging Kustomization -在 `staging` 目录中创建一个 kustomization 文件，用来定义一个新的 name 前缀和一些不同的 labels 。 +在 `staging` 目录中创建一个 kustomization 文件，用来定义一个新的名称前缀和一些不同的 labels 。 ``` @@ -147,7 +145,7 @@ EOF #### Staging Patch -新增一个自定义的 configMap 将问候从 _Good Morning!_ 改为 _Have a pineapple!_ 。 +新增一个自定义的 configMap 将问候消息从 _Good Morning!_ 改为 _Have a pineapple!_ 。 同时，将 _risky_ 标记设置为 true 。 @@ -166,7 +164,7 @@ EOF #### Production Kustomization -在 `production` 目录中创建一个 kustomization 文件，用来定义一个新的 name 前缀和 labels 。 +在 `production` 目录中创建一个 kustomization 文件，用来定义一个新的名称前缀和 labels 。 ```