使用 Istioctl 安装

跟随本指南安装、配置 Istio 网格,用于深入评估、及生产发布。 如果你是 Istio 新手,只想简单尝试,请参考快速入门指南

本安装指南使用命令行工具 istioctl, 它提供丰富的定制功能,用于定制 Istio 控制平面,以及数据平面 sidecar。 它还提供用户输入验证功能,这有助于防止安装错误;提供定制选项,可以覆盖配置的任何方面。

使用这些说明,你可以选取任意一个 Istio 内置的 配置档, 为你的特定需求进一步定制配置。

istioctl 命令通过命令行的选项支持完整的 IstioOperator API, 这些选项用于单独设置、以及接收包含 IstioOperator 定制资源(CR)的 yaml 文件,

先决条件

开始之前,检查下列先决条件:

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

使用默认配置档安装 Istio

最简单的选择是用下面命令安装 Istio 默认 配置档

$ istioctl install

此命令在 Kubernetes 集群上安装 default 配置档。 default 配置档是建立生产环境的一个良好起点, 这和较大的 demo 配置档不同,后者常用于评估一组广泛的 Istio 特性。

可以配置各种设置来修改安装。比如,要启动访问日志:

$ istioctl install --set meshConfig.accessLogFile=/dev/stdout

从外部 chart 安装

默认情况下,istioctl 使用内置 chart 生成安装清单。 这些 chart 随同 istioctl 一起发布,用以满足审计和定制,你可以在发行包的 manifests 目录下找到它们。 istioctl 除了使用内置 chart 外,还可以使用外部 chart。 为了选择外部 chart,可以设置参数 manifests 指向本地文件系统路径:

$ istioctl install --manifests=manifests/

如果使用 istioctl 1.9.5 版本的二进制文件,此命令将得到和独立运行 istioctl install 相同的结果, 这是因为它指向了和内置 chart 相同的 chart。 除非要实验或测试新特性,我们建议使用内置的 chart,而不是外部 chart,以保障 istioctl 与 chart 的兼容性。

安装一个不同的配置档

其他的 Istio 配置档,可以通过在命令行传递配置档名称的方式,安装到集群。 例如,下面命令可以用来安装 demo 配置档。

$ istioctl install --set profile=demo

检查安装了什么

istioctl 命令把安装 Istio 的 IstioOperator CR 保存到一个叫 installed-state 的 CR 副本中。 故无须检查 Istio 安装的 deployments、 pods、 services等其他资源,例如:

$ kubectl -n istio-system get deploy
NAME                   READY   UP-TO-DATE   AVAILABLE   AGE
istio-ingressgateway   1/1     1            1           49m
istiod                 1/1     1            1           49m

可以查看 installed-state CR,来了解集群中都安装了什么,也可以看到所有的定制设置。 例如:用下面命令将它的内容导出到一个 YAML 文件:

$ kubectl -n istio-system get IstioOperator installed-state -o yaml > installed-state.yaml

在一些 istioctl 命令中,installed-state CR 被用于执行检查任务,因此不能删除:

展示可用配置档的列表

你可以用下面命令展示 istioctl 可以访问到的 Istio 配置档的名称:

$ istioctl profile list
Istio configuration profiles:
    default
    demo
    empty
    minimal
    openshift
    preview
    remote

展示配置档的配置信息

你可以浏览一个配置档的配置信息。例如,运行下面命令浏览 demo 配置档的设置信息:

$ istioctl profile dump demo
components:
  egressGateways:
  - enabled: true
    k8s:
      resources:
        requests:
          cpu: 10m
          memory: 40Mi
    name: istio-egressgateway

...

只浏览配置文件的某个部分的话,可以用 --config-path 参数,它将只选择配置文件中指定路径的局部内容:

$ istioctl profile dump --config-path components.pilot demo
enabled: true
k8s:
  env:
  - name: PILOT_TRACE_SAMPLING
    value: "100"
  readinessProbe:
    httpGet:
      path: /ready
      port: 8080
    initialDelaySeconds: 1
    periodSeconds: 3
    timeoutSeconds: 5
  resources:
    requests:
      cpu: 10m
      memory: 100Mi
  strategy:
    rollingUpdate:
      maxSurge: 100%
      maxUnavailable: 25%

显示配置文件的差异

profile diff 子命令可用于显示配置档之间的差异, 它在把更改应用到集群之前,检查定制效果方面非常有用。

你可以使用此命令显示 default 和 demo 两个配置档之间的差异:

$ istioctl profile diff default demo
 gateways:
   egressGateways:
-  - enabled: false
+  - enabled: true
...
     k8s:
        requests:
-          cpu: 100m
-          memory: 128Mi
+          cpu: 10m
+          memory: 40Mi
       strategy:
...

安装前生成清单文件

在安装 Istio 之前,可以用 manifest generate 子命令生成清单文件。 例如,用下面命令生成 default 配置档的清单文件:

$ istioctl manifest generate > $HOME/generated-manifest.yaml

生成的清单文件可用于检查具体安装了什么,也可用于跟踪清单是如何随着时间而改变的。 虽然 IstioOperator CR 代表完整的用户配置,足以用于跟踪, 但 manifest generate 命令的输出还能截获底层 chart 潜在的改变,因此可以用于跟踪实际安装过的资源。

manifest generate 的输出还能传递给 kubectl apply 或类似的命令,用来安装 Istio。 然而,这些替代的安装方法不能像 istioctl install 那样,将相同的依赖顺序应用于资源, 并且也没有在 Istio 发行版中测试过。

显示清单的差异

使用这一组命令,以 YAML 风格的差异对比方式,显示 default 配置项和定制安装生成的两个清单之间的差异:

$ istioctl manifest generate > 1.yaml
$ istioctl manifest generate -f operator/samples/pilot-k8s.yaml > 2.yaml
$ istioctl manifest diff 1.yaml 2.yaml
Differences of manifests are:

Object Deployment:istio-system:istio-pilot has diffs:

spec:
  template:
    spec:
      containers:
        '[0]':
          resources:
            requests:
              cpu: 500m -> 1000m
              memory: 2048Mi -> 4096Mi
      nodeSelector: -> map[master:true]
      tolerations: -> [map[effect:NoSchedule key:dedicated operator:Exists] map[key:CriticalAddonsOnly
        operator:Exists]]


Object HorizontalPodAutoscaler:istio-system:istio-pilot has diffs:

spec:
  maxReplicas: 5 -> 10
  minReplicas: 1 -> 2

验证安装是否成功

你可以用 verify-install 命令检查 Istio 是否安装成功,此命令用你指定的清单对比集群中实际的安装情况。

如果你在部署前还没有生成清单文件,那现在就运行下面命令生成一个:

$ istioctl manifest generate <your original installation options> > $HOME/generated-manifest.yaml

紧接着运行 verify-install 命令,查看安装是否成功:

$ istioctl verify-install -f $HOME/generated-manifest.yaml

定制配置

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

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

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

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

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

识别 Istio 组件

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

组件
base
pilot
ingressGateways
egressGateways
cni
istiodRemote

针对每一个组件的配置内容通过 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
        nodeSelector:
          master: "true"
        tolerations:
        - key: dedicated
          operator: Exists
          effect: NoSchedule
        - key: CriticalAddonsOnly
          operator: Exists

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: 15050

一些参数,比如 Kubernetes resources、namespaces、和开关设置,暂时并存在 Helm 和 IstioOperator APIs 中。 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 两种设置,它们一起用于定义生成的网关资源。 内置的网关就像其他组件一样的可以被定制。

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

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 和配置项

istioctlinstallmanifest generateprofile 命令可以使用以下任意源来生成 chart 和 配置档:

  • 内置的 chart。如果没有设置 --manifests,则用 default。 内置的 chart 和 Istio .tgz 发行包内 manifests/ 目录下的内容相同。
  • 本地文件系统中的chart,例如,istioctl install --manifests istio-1.9.5/manifests
  • GitHub 上的 chart,例如,istioctl install --manifests https://github.com/istio/istio/releases/download/1.9.5/istio-1.9.5-linux-arm64.tar.gz

本地文件系统的 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.yamluser-overlay.yaml 将覆盖 default.yaml 文件,以得到作为 manifest generation 输入的最终值。

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

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

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

为输出清单打补丁

传递给 istioctlIstioOperator 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 参数也为资源中缺少的路径创建所有的中间节点。

卸载 Istio

要从集群中完整卸载 Istio,运行下面命令:

$ istioctl x uninstall --purge

或者,只删除指定的 Istio 控制平面,运行以下命令:

$ istioctl x uninstall <your original installation options>

$ istioctl manifest generate <your original installation options> | kubectl delete -f -

控制平面的命名空间(例如:istio-system)默认不会删除, 如果确认不再需要,用下面命令删除它:

$ kubectl delete namespace istio-system
这些信息有用吗?
Do you have any suggestions for improvement?

Thanks for your feedback!