From 6cf8b9e2b821195f85342d6813fe0a41cce4397e Mon Sep 17 00:00:00 2001 From: guoxudong Date: Thu, 8 Aug 2019 10:16:13 +0800 Subject: [PATCH] update examples-zh --- examples/zh/README.md | 6 +- examples/zh/combineConfigs.md | 230 ++++++++++++++++++++++++++++++++ examples/zh/generatorOptions.md | 60 +++++++++ examples/zh/vars.md | 148 ++++++++++++++++++++ 4 files changed, 441 insertions(+), 3 deletions(-) create mode 100644 examples/zh/combineConfigs.md create mode 100644 examples/zh/generatorOptions.md create mode 100644 examples/zh/vars.md diff --git a/examples/zh/README.md b/examples/zh/README.md index af91f0ec8..42c628ef8 100644 --- a/examples/zh/README.md +++ b/examples/zh/README.md @@ -14,11 +14,11 @@ go get sigs.k8s.io/kustomize/v3/cmd/kustomize * [configGenerations](configGeneration.md) - 当 ConfigMapGenerator 修改时进行滚动更新。 - * [combineConfigs](../combineConfigs.md) - 融合来自不同用户的配置数据（例如来自 devops/SRE 和 developers）。 + * [combineConfigs](combineConfigs.md) - 融合来自不同用户的配置数据（例如来自 devops/SRE 和 developers）。 - * [generatorOptions](../generatorOptions.md) -修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。 + * [generatorOptions](generatorOptions.md) -修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。 - * [vars](../wordpress/README.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。 + * [vars](vars.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。 * [image names and tags](../image.md) - 在不使用 patch 的情况下更新镜像名称和标签。 diff --git a/examples/zh/combineConfigs.md b/examples/zh/combineConfigs.md new file mode 100644 index 000000000..460a02aaf --- /dev/null +++ b/examples/zh/combineConfigs.md @@ -0,0 +1,230 @@ +[overlay]: ../docs/glossary.md#overlay +[target]: ../docs/glossary.md#target + +# 示例：devops和开发配合管理配置数据 + +场景：你在生产环境中有一个基于 Java 由多个内部开发团队（注册、结账和搜索等）开发的商店。 + +这个服务在不同的环境中运行：_development_、 _testing_、 _staging_ 和 _production_，从 Java 的 properties 文件中读取配置。 + +为每个环境维护一个大的 properties 文件时很困难的。这个文件需要频繁的修改，并且这些修改都需要由 devops 工程师来进行，因为： + + 1. 这个文件包含 devops 工程师需要知道，而开发人员不必知道的值 + 2. 比如生产环境的 properties 包含敏感数据，比如生产数据库的登录凭据。 + +## Property sharding + +通过一些研究，我们注意到属性可以分为不同的类别。 + +### Property sharding + +例如：国际化数据、物理常量，外部服务位置等静态数据。 + +_这些无论哪个环境，都一样的配置。_ + +这些都只需要一组配置。将这组配置放在一个文件中： + + * `common.properties` + +### Plumbing properties + +例如：静态资源（HTML、CSS、JavaScript）的位置，产品和用户的数据表，负载均衡的端口，日志收集等。 + +_这些属性的不同，恰恰是环境的不同之处。_ + +DevOps 或 SRE 工程师需要完全控制生产环境中的这些配置；测试需要调整数据库来支持测试；而开发则希望尝试开发中遇到的各种不同的情景。 + +将这些值放入 + + * `development/plumbing.properties` + * `staging/plumbing.properties` + * `production/plumbing.properties` + + +### Secret properties + +例如：用户表的位置、数据库凭证、解密密钥等。 + +_这些需要 devops 工程师控制，其他人没有访问权限。_ + +将这些值放入 + + * `development/secret.properties` + * `staging/secret.properties` + * `production/secret.properties` + +[kubernetes secret]: https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/ + +例如使用 unix 文件权限和模式来限制访问控制，或者使用更好的方法-使用专门用于存储密码的服务，并且使用 kustomize 中的 `secretGenerator` 字段在 Kubernetes 中创建 secret 来存储密码。 + + + +## 混合管理方法 + +基于相同的 base 创建 _n_ 个 overlays 来创建 _n_ 个集群环境的方法。 + +在本例的其余部分，我们将使用 _n==2_，这里只使用 _development_ 和 _production_ ，可以使用相同的方法来增加更多的环境。 + +运行 `kustomize build` 基于 [overlay] 的 [target] 来创建集群环境。 + +[helloworld]: helloWorld.md + +以下示例将执行此操作，但将侧重于 configMap 构建，而不用担心如何将 configMaps 关联到 Deployment（[helloworld] 示例中介绍的）。 + +所有文件（包括共享 property 文件）都将在目录树中创建，目录中包含 base 和 overlay 文件的目录，这些都与 [helloworld] 中演示的一致。 + +它将全部存在于此工作目录中： + + +```bash +DEMO_HOME=$(mktemp -d) +``` + +### 创建 base + + + +创建放置 base 配置的路径： + + +```bash +mkdir -p $DEMO_HOME/base +``` + +向 base 中的插入数据，base 中应该包含所有环境共有的资源，这里我们只定义一个 java properties 文件，以及一个引用他们的 `kustomization` 文件。 + + +```bash +cat <$DEMO_HOME/base/common.properties +color=blue +height=10m +EOF + +cat <$DEMO_HOME/base/kustomization.yaml +configMapGenerator: +- name: my-configmap + files: + - common.properties +EOF +``` + +### 创建并使用 overlay 用于 _开发_ + +创建一个 overlays 目录： + + +```bash +OVERLAYS=$DEMO_HOME/overlays +``` + +创建 _development_ overlay： + + +```bash +mkdir -p $OVERLAYS/development + +cat <$OVERLAYS/development/plumbing.properties +port=30000 +EOF + +cat <$OVERLAYS/development/secret.properties +dbpassword=mothersMaidenName +EOF + +cat <$OVERLAYS/development/kustomization.yaml +resources: +- ../../base +namePrefix: dev- +nameSuffix: -v1 +configMapGenerator: +- name: my-configmap + behavior: merge + files: + - plumbing.properties + - secret.properties +EOF +``` + +现在可以生成开发使用的 configMaps ： + + +```bash +kustomize build $OVERLAYS/development +``` + +#### 检查 ConfigMap 名称 + +可以在输出中看到生成的 `ConfigMap` 名称。 + +名称应该是这样的：`dev-my-configmap-v1-2gccmccgd5`： + + * `"dev-"` 来自 `namePrefix` 字段 + * `"my-configmap"` 来自 `configMapGenerator/name` 字段 + * `"-v1"` 来自 `nameSuffix` 字段 + * `"-2gccmccgd5"` 为哈希值，是 `kustomize` 根据 configMap 的内容计算的 + +哈希后缀很关键，如果 configMap 内容发生变化， configMap 的名称也会发生变化，以及从 `kustomize` 出现在 YAML 输出中的对该名称的所有引用。 + +名称更改意味着如果使用类似命令将此 YAML 应用于群集，则 Deployment 将执行滚动更新重启以获取新数据。 + +> ```bash +> kustomize build $OVERLAYS/development | kubectl apply -f - +> ``` + +Deployment 无法自动感知 configMap 是否发生改变。 + +如果更改 configMap 而不更改其名称以及对该名称的所有引用，则必须重新启动以获取更改。 + +最佳的做法就是将 configMap 视为不变的。 + +不去编辑 configMap ，而是使用 _新_ 的名称的 _新_ configMap，并在 Deployment 中引用新的 configMap 。而 `kustomize` 使用 `configMapGenerator` 指令和相关的命名控件使这很容易。k8s master 中的 GC 则会回收并且删除未使用的 configMap 。 + +### 创建并且使用 overlay 用于 _生产_ + +接下来创建 _production_ overlay 的文件： + + +```bash +mkdir -p $OVERLAYS/production + +cat <$OVERLAYS/production/plumbing.properties +port=8080 +EOF + +cat <$OVERLAYS/production/secret.properties +dbpassword=thisShouldProbablyBeInASecretInstead +EOF + +cat <$OVERLAYS/production/kustomization.yaml +resources: +- ../../base +namePrefix: prod- +configMapGenerator: +- name: my-configmap + behavior: merge + files: + - plumbing.properties + - secret.properties +EOF +``` + +现在可以生成用于生产的 configMap： + + +```bash +kustomize build $OVERLAYS/production +``` + +可以直接在 CI/CD 流程中执行如下命令，将应用部署到集群： + +> ```bash +> kustomize build $OVERLAYS/production | kubectl apply -f - +> ``` diff --git a/examples/zh/generatorOptions.md b/examples/zh/generatorOptions.md new file mode 100644 index 000000000..1dd137842 --- /dev/null +++ b/examples/zh/generatorOptions.md @@ -0,0 +1,60 @@ +# Generator Options + +Kustomize 提供了修改 ConfigMapGenerator 和 SecretGenerator 行为的选项，这些选项包括： + + - 不再将内容生成的哈希后缀添加到资源名称后 + - 为生成的资源添加 labels + - 为生成的资源添加 annotations + +这个示例将展示如何运用这些选项，首先创建一个工作空间： +```bash +DEMO_HOME=$(mktemp -d) +``` + +创建 kustomization 并且为其添加一个 ConfigMapGenerator + + +```bash +cat > $DEMO_HOME/kustomization.yaml << EOF +configMapGenerator: +- name: my-configmap + literals: + - foo=bar + - baz=qux +EOF +``` + +添加如下 generatorOptions + +```bash +cat >> $DEMO_HOME/kustomization.yaml << EOF +generatorOptions: + disableNameSuffixHash: true + labels: + kustomize.generated.resource: somevalue + annotations: + annotations.only.for.generated: othervalue +EOF +``` +运行 `kustomize build` 并且确定生成的 ConfigMap 。 + + - 确定没有名称后缀 + + ``` + test 1 == \ + $(kustomize build $DEMO_HOME | grep "name: my-configmap$" | wc -l); \ + echo $? + ``` + - 确定 label `kustomize.generated.resource: somevalue` + ``` + test 1 == \ + $(kustomize build $DEMO_HOME | grep -A 1 "labels" | grep "kustomize.generated.resource" | wc -l); \ + echo $? + ``` + - 确定 annotation `annotations.only.for.generated: othervalue` + ``` + test 1 == \ + $(kustomize build $DEMO_HOME | grep -A 1 "annotations" | grep "annotations.only.for.generated" | wc -l); \ + echo $? + ``` + diff --git a/examples/zh/vars.md b/examples/zh/vars.md new file mode 100644 index 000000000..82b637020 --- /dev/null +++ b/examples/zh/vars.md @@ -0,0 +1,148 @@ +# 示例: 将 k8s runtime 数据注入容器 + +在本教程中，将会介绍如何使用 `kustomize` 声明变量并将其替换为容器中的命令。要注意的是，替换并不适用于任意字段，它仅适用于容器的env，args和command。 + +运行WordPress，以下是必须的： + +- WordPress 连接 MySQL 数据库 +- MySQL 服务可以被 WordPress 容器访问 + +首先构建一个工作空间： + +```bash +DEMO_HOME=$(mktemp -d) +MYSQL_HOME=$DEMO_HOME/mysql +mkdir -p $MYSQL_HOME +WORDPRESS_HOME=$DEMO_HOME/wordpress +mkdir -p $WORDPRESS_HOME +``` + +### 下载 resources + +下载 WordPress 的 resources 和 `kustomization.yaml` 。 + + +```bash +CONTENT="https://raw.githubusercontent.com\ +/kubernetes-sigs/kustomize\ +/master/examples/wordpress/wordpress" + +curl -s -o "$WORDPRESS_HOME/#1.yaml" \ + "$CONTENT/{deployment,service,kustomization}.yaml" +``` + +下载 MySQL 的 resources 和 `kustomization.yaml` 。 + + +```bash +CONTENT="https://raw.githubusercontent.com\ +/kubernetes-sigs/kustomize\ +/master/examples/wordpress/mysql" + +curl -s -o "$MYSQL_HOME/#1.yaml" \ + "$CONTENT/{deployment,service,secret,kustomization}.yaml" +``` + +### 创建 kustomization.yaml + +基于 `wordpress` 和 `mysql` 的两个 bases 创建一个新的 `kustomization.yaml` ： + + +```bash +cat <$DEMO_HOME/kustomization.yaml +resources: +- wordpress +- mysql +namePrefix: demo- +patchesStrategicMerge: +- patch.yaml +EOF +``` + +### 下载 WordPress 的 patchs + +在新的 kustomization 中应用 WordPress Deployment 的 patch ，该 patch 包含： +- 添加初始容器来显示mysql的服务名称 +- 添加允许 wordpress 查找到 mysql 数据库的环境变量 + + +```bash +CONTENT="https://raw.githubusercontent.com\ +/kubernetes-sigs/kustomize\ +/master/examples/wordpress" + +curl -s -o "$DEMO_HOME/#1.yaml" \ + "$CONTENT/{patch}.yaml" +``` +该 patch 内容如下： +> ```yaml +> apiVersion: apps/v1beta2 +> kind: Deployment +> metadata: +> name: wordpress +> spec: +> template: +> spec: +> initContainers: +> - name: init-command +> image: debian +> command: +> - "echo $(WORDPRESS_SERVICE)" +> - "echo $(MYSQL_SERVICE)" +> containers: +> - name: wordpress +> env: +> - name: WORDPRESS_DB_HOST +> value: $(MYSQL_SERVICE) +> - name: WORDPRESS_DB_PASSWORD +> valueFrom: +> secretKeyRef: +> name: mysql-pass +> key: password +> ``` +初始化容器的命令需要依赖于k8s资源对象字段的信息，由占位符变量 $(WORDPRESS_SERVICE) 和 $(MYSQL_SERVICE) 表示。 + +### 将变量绑定到k8s对象字段 + + +```bash +cat <>$DEMO_HOME/kustomization.yaml +vars: + - name: WORDPRESS_SERVICE + objref: + kind: Service + name: wordpress + apiVersion: v1 + fieldref: + fieldpath: metadata.name + - name: MYSQL_SERVICE + objref: + kind: Service + name: mysql + apiVersion: v1 +EOF +``` +`WORDPRESS_SERVICE` 来自 `wordpress` 服务的 `metadata.name` 字段。如果不指定 `fieldref` ，则使用默认的 `metadata.name` 。因此 `MYSQL_SERVICE` 来自 `mysql` 服务的 `metadata.name` 字段。 + +### 替换 + +运行命令查看替换结果： + + +```bash +kustomize build $DEMO_HOME +``` + +预期的输出为： + +> ```yaml +> (truncated) +> ... +> initContainers: +> - command: +> - echo demo-wordpress +> - echo demo-mysql +> image: debian +> name: init-command +> +> ```