定制安装配置

先决条件

开始之前，检查下列先决条件：

1. 下载 Istio 发行版。
2. 执行必要的平台安装。
3. 检查 Pod 和服务的要求。

除了安装 Istio 内置的 配置档， istioctl install 提供了一套完整的用于定制配置的 API。

• IstioOperator API

此 API 中的配置参数能用命令行选项 --set 独立设置。 例如，要在 default 配置档中启动调试日志特性，使用这个命令：

$ istioctl install --set values.global.logging.level=debug

或者，可以在 YAML 文件中指定 IstioOperator 的配置，然后用 -f 选项传递给 istioctl：

$ istioctl install -f samples/operator/pilot-k8s.yaml

为了向后兼容，以前的 Helm 安装选项，除了 Kubernetes 资源设置之外，均被完整的支持。 为了在命令行设置他们，在选项名前面加上 “values.“。 例如，下面的命令覆盖了 Helm 配置选项 pilot.traceSampling：

$ istioctl install --set values.pilot.traceSampling=0.1

Helm 值也可以在 IstioOperator CR（YAML 文件）中设置，就像使用 Helm API 定制 Istio 设置 中描述的那样。

如果您需要配置 Kubernetes 资源方面的设置，请用定制 Kubernetes 设置中介绍的 IstioOperator API。

识别 Istio 组件

IstioOperator API 定义的组件如下面表格所示：

针对每一个组件的配置内容通过 components.<component name> 下的 API 中提供。 例如，要用 API 改变（改为 false）pilot 组件的 enabled 设置， 使用 --set components.pilot.enabled=false， 或在 IstioOperator 资源中就像这样来设置：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    pilot:
      enabled: false

所有的组件共享一个通用 API，用来修改 Kubernetes 特定的设置，它在 components.<component name>.k8s 路径下， 后续章节将会进一步描述它。

定制 Kubernetes 设置

IstioOperator API 支持以一致性的方式定制每一个组件的 Kubernetes 设置。

每个组件都有一个 KubernetesResourceSpec，它允许修改如下设置。 使用此列表标识要定制的设置：

1. Resources
2. Readiness probes
3. Replica count
4. HorizontalPodAutoscaler
5. PodDisruptionBudget
6. Pod annotations
7. Service annotations
8. ImagePullPolicy
9. Priority class name
10. Node selector
11. Affinity and anti-affinity
12. Service
13. Toleration
14. Strategy
15. Env
16. Pod security context

所有这些 Kubernetes 设置均使用 Kubernetes API 定义，因此可以参考 Kubernetes 文档

下面覆盖文件的例子调整 Pilot 的资源限制和 Pod 水平伸缩的设置：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    pilot:
      k8s:
        resources:
          requests:
            cpu: 1000m # override from default 500m
            memory: 4096Mi # ... default 2048Mi
        hpaSpec:
          maxReplicas: 10 # ... default 5
          minReplicas: 2  # ... default 1

用 istioctl install 把改变的设置应用到集群：

$ istioctl install -f samples/operator/pilot-k8s.yaml

使用 Helm API 定制 Istio 设置

IstioOperator API 使用 values 字段为 Helm API 保留了一个透传接口。

下面的 YAML 文件通过 Helm API 来配置 global 和 Pilot 的设置：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  values:
    pilot:
      traceSampling: 0.1 # override from 1.0
    global:
      monitoringPort: 15014

诸如 Kubernetes 资源、命名空间和开关设置等参数暂时并存在 Helm 和 IstioOperator API 中。 Istio 社区推荐使用 IstioOperator API ，因为它更一致、更有效、且遵循社区毕业流程.

配置网关

网关因为支持定义多个入站、出站网关，所以它是一种特殊类型的组件。 在 IstioOperator API 中，网关被定义为列表类型。 default 配置档会安装一个名为 istio-ingressgateway 的入站网关。 您可以检查这个网关的默认值：

$ istioctl profile dump --config-path components.ingressGateways
$ istioctl profile dump --config-path values.gateways.istio-ingressgateway

这些命令显示了网关的 IstioOperator 和 Helm 两种设置，它们一起用于定义生成的网关资源。 内置的网关就像其他组件一样的可以被定制。

从 1.7 开始，覆盖路由配置时必须指定路由名称。 不指定名称时，也不会再设置 istio-ingressgateway 或 istio-egressgateway 做为默认名称。

新的用户网关可以通过添加新的列表条目来创建：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    ingressGateways:
      - name: istio-ingressgateway
        enabled: true
      - namespace: user-ingressgateway-ns
        name: ilb-gateway
        enabled: true
        k8s:
          resources:
            requests:
              cpu: 200m
          serviceAnnotations:
            cloud.google.com/load-balancer-type: "internal"
          service:
            ports:
            - port: 8060
              targetPort: 8060
              name: tcp-citadel-grpc-tls
            - port: 5353
              name: tcp-dns

注意：Helm 的值（spec.values.gateways.istio-ingressgateway/egressgateway）被所有的入/出站网关共享。 如果必须为每个网关定制这些选项，建议您使用一个独立的 IstioOperator CR 来生成用户网关的清单，并和 Istio 主安装清单隔离。

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  profile: empty
  components:
    ingressGateways:
      - name: ilb-gateway
        namespace: user-ingressgateway-ns
        enabled: true
        # Copy settings from istio-ingressgateway as needed.
  values:
    gateways:
      istio-ingressgateway:
        debug: error

高级安装定制

定制外部 chart 和配置项

istioctl 的 install、 manifest generate 和 profile 命令可以使用以下任意源来生成 chart 和 配置档：

• 内置的 chart。如果没有设置 --manifests，则用 default。 内置的 chart 和 Istio .tgz 发行包内 manifests/ 目录下的内容相同。
• 本地文件系统中的 chart，例如 istioctl install --manifests istio-1.17.0/manifests。

本地文件系统的 chart 和配置档可以通过编辑 manifests/ 目录下的文件定制。 要进行广泛的更改，建议拷贝 manifests 目录，然后修改副本。 但请注意，manifests 目录中的内容结构必须要保留。

存放在目录 manifests/profiles/ 下面配置档，可编辑，也可通过创建一个指定配置档名称和 .yaml 新文件的方式来添加。 istioctl 扫描 profiles 子目录，所有找到的配置档都可以在 IstioOperatorSpec 的 profile 字段中通过名称引用。 在用户的覆盖配置被应用前，内建 profile 默认的 YAML 文件被覆写。 例如，您可以创建一个名为 custom1.yaml 的新profile，新配置档在 default 配置档的基础上定制了部分设置，然后应用用户的覆盖文件：

$ istioctl manifest generate --manifests mycharts/ --set profile=custom1 -f path-to-user-overlay.yaml

在此用例中，文件 custom1.yaml 和 user-overlay.yaml 将覆盖 default.yaml 文件，以得到作为 manifest generation 输入的最终值。

通常，没有必要创建新的配置档，这是因为传入多个覆盖文件也可以达到同样的效果。 例如，上面命令等价于传入两个用户覆盖文件：

$ istioctl manifest generate --manifests mycharts/ -f manifests/profiles/custom1.yaml -f path-to-user-overlay.yaml

只有需要在 IstioOperatorSpec 中指向一个配置档名称时，才需要创建定制配置档。

为输出清单打补丁

传递给 istioctl 的 IstioOperator CR，用于生成输出清单，该清单包含将应用到集群的 Kubernetes 资源。 在输出的清单已经生成但没有应用之时，此清单可以通过 IstioOperator 覆盖 API 深度定制以增加、修改或删除资源。

下面例子覆盖文件（patch.yaml）展示输出清单补丁这种类型可以做什么：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  profile: empty
  hub: docker.io/istio
  tag: 1.1.6
  components:
    pilot:
      enabled: true
      namespace: istio-control
      k8s:
        overlays:
          - kind: Deployment
            name: istiod
            patches:
              # Select list item by value
              - path: spec.template.spec.containers.[name:discovery].args.[30m]
                value: "60m" # overridden from 30m
              # Select list item by key:value
              - path: spec.template.spec.containers.[name:discovery].ports.[containerPort:8080].containerPort
                value: 1234
              # Override with object (note | on value: first line)
              - path: spec.template.spec.containers.[name:discovery].env.[name:POD_NAMESPACE].valueFrom
                value: |
                  fieldRef:
                    apiVersion: v2
                    fieldPath: metadata.myPath
              # Deletion of list item
              - path: spec.template.spec.containers.[name:discovery].env.[name:REVISION]
              # Deletion of map item
              - path: spec.template.spec.containers.[name:discovery].securityContext
          - kind: Service
            name: istiod
            patches:
              - path: spec.ports.[name:https-dns].port
                value: 11111 # OVERRIDDEN

将此文件传给 istioctl manifest generate -f patch.yaml 会把上面的补丁应用到 default 配置档的输出清单。 两个打了补丁的资源将做如下修改（为了简洁，只显示资源的部分内容）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
spec:
  template:
    spec:
      containers:
      - args:
        - 60m
        env:
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              apiVersion: v2
              fieldPath: metadata.myPath
        name: discovery
        ports:
        - containerPort: 1234
---
apiVersion: v1
kind: Service
metadata:
  name: istiod
spec:
  ports:
  - name: https-dns
    port: 11111
---

注意：补丁按照给定的顺序执行。每个补丁基于前面补丁的输出来执行。 在补丁中的路径，如果在输出清单不存在，将被创建。

列出选中的项目目录

istioctl --set 参数和 IstioOperator CR 中的 k8s.overlays 字段，两者均支持由 [index]、[value] 或 [key:value] 选中的列表项。 –set 参数也为资源中缺少的路径创建所有的中间节点。