メタデータ＠Istio

はじめに

本サイトにつきまして、以下をご認識のほど宜しくお願いいたします。

• https://hiroki-it.github.io/tech-notebook/

01. Namespaceの .metadata.labels キー

istio-injection

指定したNamespaceに所属するPod内へ、istio-proxyを自動的にインジェクションするか否かを設定する。

.metadata.labels.istio.io/rev キーとはコンフリクトを発生させるため、どちらかしか使えない (.metadata.labels.istio-injection キーの値が disabled の場合は共存できる) 。

.metadata.labels.istio-injection キーを使用する場合、Istioのアップグレードがインプレース方式になる。

＊実装例＊

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    istio-injection: enabled

アプリケーション以外のNamespaceでは disabled 値を設定することが多い。

apiVersion: v1
kind: Namespace
metadata:
  name: observability
  labels:
    istio-injection: disabled # disabledであれば、istio.io/revキーと共存できる。
---
apiVersion: v1
kind: Namespace
metadata:
  name: chaos-mesh
  labels:
    istio-injection: disabled # disabledであれば、istio.io/revキーと共存できる。

• https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#controlling-the-injection-policy

istio.io/rev

▼ サイドカーモードの場合

指定したNamespaceに所属するPod内へ、istio-proxyを自動的にインジェクションするか否かを設定する。

また、サイドカーモードのカナリアアップグレードにも使用できる。

IstoOperatorの .spec.revision キーと同じである。

.metadata.labels.istio-injection キーとはコンフリクトを発生させるため、どちらかしか使えない (.metadata.labels.istio-injection キーの値が disabled の場合は共存できる) 。

.metadata.labels.istio.io/rev キーを使用する場合、Istioのアップグレードがカナリア方式になる。

＊実装例＊

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    istio.io/rev: default
---
apiVersion: v1
kind: Namespace
metadata:
  name: observability
  labels:
    istio-injection: disabled # disabledであれば、istio.io/revキーと共存できる。
---
apiVersion: v1
kind: Namespace
metadata:
  name: chaos-mesh
  labels:
    istio-injection: disabled # disabledであれば、istio.io/revキーと共存できる。

• https://istio.io/latest/blog/2021/direct-upgrade/#upgrade-from-18-to-110

▼ アンビエントモードの場合

istio-proxyからwaypoint-proxyを作成する。

また、アンビエントモードのカナリアアップグレードにも使用できる。

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    istio.io/dataplane-mode: ambient
    istio.io/use-waypoint: istio-waypoint
    istio.io/rev: default

• https://istio.io/latest/docs/ambient/upgrade/helm/

istio.io/dataplane-mode

▼ istio.io/dataplane-modeとは

アンビエントモードの場合、設定したNamespaceでztunnel Podを有効化する。

このラベルがついているNamespaceのみで、ztunnel PodへのリダイレクトによってPodは L4 のトラフィックを送受信できる。

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    istio.io/dataplane-mode: ambient
---
apiVersion: v1
kind: Namespace
metadata:
  name: istio-egress
  # istio-engressにはラベルは不要である
---
apiVersion: v1
kind: Namespace
metadata:
  name: istio-ingress
  # istio-engressにはラベルは不要である

• https://istio.io/latest/docs/reference/config/labels/#IoIstioDataplaneMode
• https://istio.io/latest/docs/ambient/architecture/data-plane/
• https://istio.io/latest/docs/ambient/usage/add-workloads/#ambient-labels

istio.io/use-waypoint

▼ istio.io/use-waypointとは

アンビエントモードの場合、設定したNamespaceでwaypoint-proxyを有効化する。

waypoint-proxyと紐づくGateway名 (Gateway API) を指定する。

このラベルがついているNamespaceのみで、waypoint-proxyへのリダイレクトによってPodは L7 のトラフィックを送受信できる。

もし、istio.io/use-waypoint を設定したNamespaceにwaypoint-proxy (Gateway APIのNamespaceによって決まる) が一緒にいない場合は、istio.io/use-waypoint-namespace でwaypoint-proxyにいるNamespaceを指定する必要がある。

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    # Gatewayの名前
    istio.io/use-waypoint: istio-waypoint

• https://istio.io/latest/docs/reference/config/labels/#IoIstioUseWaypoint
• https://istio.io/latest/docs/ambient/architecture/data-plane/
• https://istio.io/latest/docs/ambient/usage/waypoint/#configure-resources-to-use-a-cross-namespace-waypoint-proxy

istio.io/use-waypoint-namespace

▼ istio.io/use-waypoint-namespaceとは

istio.io/use-waypoint を設定したNamespaceにwaypoint-proxy (Gateway APIのNamespaceによって決まる) が一緒にいない場合は、istio.io/use-waypoint-namespace でwaypoint-proxyにいるNamespaceを指定する必要がある。

例えば、app でGatewayとistio-waypointを作成している場合、waypoint-proxyを使用する他のNamespaceでは、istio.io/use-namespace: app とする。

apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    # Gatewayの名前
    istio.io/use-waypoint: istio-waypoint
---
apiVersion: v1
kind: Namespace
metadata:
  name: istio-egress
  labels:
    # Gatewayの名前
    istio.io/use-waypoint: istio-waypoint
    # appにwaypoint-proxyがある
    istio.io/use-namespace: app
---
apiVersion: v1
kind: Namespace
metadata:
  name: istio-ingress
  labels:
    # Gatewayの名前
    istio.io/use-waypoint: istio-waypoint
    # appにwaypoint-proxyがある
    istio.io/use-namespace: app

• https://www.solo.io/blog/istio-ambient-waypoint-proxy-deployment-model-explained
• https://istio.io/latest/docs/ambient/usage/waypoint/#configure-resources-to-use-a-cross-namespace-waypoint-proxy

istio.io/waypoint-for

▼ istio.io/waypoint-forとは

waypoint-proxyの宛先とするKubernetesリソースを設定する。

• service (Service)
• workload (Pod、Virtual Machine)
• all (Service、Pod、Virtual Machine)
• none (無効にする)

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  labels:
    istio.io/waypoint-for: service
  name: istio-waypoint
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: tcp-ztunnel
      port: 15008
      protocol: HBONE
      allowedRoutes:
        namespaces:
          from: All

02. Podの .metadata.annotations キー

annotationsとは

Deploymentの .spec.template キーや、Podの .metadata. キーにて、istio-proxyごとのオプション値を設定する。Deploymentの .metadata. キーで定義しないように注意する。

• https://istio.io/latest/docs/reference/config/annotations/

istio.io/rev

IstoOperatorの .spec.revision キーと同じ。

特定のPodで、Istioとこれのカナリアリリースを有効化するか否かを設定する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        istio.io/rev: 1-10-0

proxy.istio.io/config

▼ proxy.istio.io/configとは

istio-proxyの envoy プロセスの設定値を上書きし、ユーザー定義の値を設定する。

これを使用するよりは、Istiodコントロールプレーンの .meshConfig.defaultConfig キーやProxyConfigの .spec.environmentVariables キーを使用したほうがいいかもしれない。

ProxyConfigが最優先であり、これらの設定はマージされる。

.meshConfig.defaultConfig キーにデフォルト値を設定しておき、ProxyConfigでNamespaceやマイクロサービスPodごとに上書きするのがよい。

▼ configPath

デフォルトでは、./etc/istio/proxy ディレクトリ配下に最終的な設定値ファイルを作成する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          configPath: ./etc/istio/proxy

• https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig

▼ drainDuration

デフォルト値は 45 である。

istio-proxy内のEnvoyプロセスは、ホットリスタート時に接続のドレイン処理を実施する。

この接続のドレイン処理時間で、新しい接続を受け入れ続ける時間を設定する。

Envoyの --drain-time-s オプションに相当する。

設定した時間が短過ぎると、処理中の接続を終了することなく、強制的に切断してしまう。

レースコンディションを解決するための .mesh.defaultConfig.proxyMetadata.MINIMUM_DRAIN_DURATION キーでも、同じ値を設定するとよい。

似た設定の terminationDrainDuration は、istio-proxyの終了時のドレイン処理時間である。

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          drainDuration: "10s"

• https://speakerdeck.com/nagapad/abema-niokeru-gke-scale-zhan-lue-to-anthos-service-mesh-huo-yong-shi-li-deep-dive?slide=80
• https://github.com/istio/istio/pull/35059#discussion_r711500175

▼ parentShutdownDuration

執筆時点 (2023/10/31) ですでに廃止されている。

istio-proxy上のEnvoyの親プロセスを終了するまでに待機する時間を設定する。

Podの .metadata.annotations.proxy.istio.io/config.terminationDrainDuration キーよりも、最低 5 秒以上長くすると良い。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          parentShutdownDuration: "80s"

• https://zenn.dev/yatoum/articles/d927c58d74ff05
• https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig
• https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-parent-shutdown-time-s
• https://christina04.hatenablog.com/entry/k8s-graceful-stop-with-istio-proxy

▼ terminationDrainDuration

デフォルト値は 5 である (対応する .mesh.defaultConfig.proxyMetadata.MINIMUM_DRAIN_DURATION キーと同じ) 。

EXIT_ON_ZERO_ACTIVE_CONNECTIONS 変数が false な場合にのみ設定できる。

true の場合は、代わりにPodの .mesh.defaultConfig.proxyMetadata.MINIMUM_DRAIN_DURATION 変数と ## EXIT_ON_ZERO_ACTIVE_CONNECTIONS 変数を設定する。

istio-proxy内のEnvoyプロセスは、終了時に接続のドレイン処理を実施する。

この接続のドレイン処理時間を設定する。

似た設定の drainDuration は、istio-proxy内のEnvoyのホットリスタート時のドレイン処理時間である。

＊実装例＊

Envoyプロセスの接続のドレイン処理 5 秒間に実施する。

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          terminationDrainDuration: "5s"

• https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig
• https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-drain-time-s
• https://christina04.hatenablog.com/entry/k8s-graceful-stop-with-istio-proxy

sidecar.istio.io/excludeInboundPorts、sidecar.istio.io/excludeOutboundPorts

特定のポート番号に対するインバウンド通信／アウトバウンド通信に関して、istio-iptablesがistio-proxyへリダイレクトしないようにする。

例えば、Pod間でレプリケーション通信をする場合 (例：Keycloakクラスター、Redisクラスターなど) 、istio-proxyを経由する必要はない。

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        sidecar.istio.io/excludeInboundPorts: "7800"
        sidecar.istio.io/excludeOutboundPorts: "7800"

sidecar.istio.io/inject

特定のPod (例：DB) にサイドカーを注入するか否かを設定する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"

• https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#controlling-the-injection-policy

sidecar.istio.io/proxyCPU

istio-proxyで使用するCPUサイズを設定する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        sidecar.istio.io/proxyCPU: 2

• https://istio.io/latest/docs/reference/config/annotations/

sidecar.istio.io/proxyImage

istio-proxyの作成に使用するコンテナイメージを設定する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        sidecar.istio.io/proxyImage: foo-envoy

• https://istio.io/latest/docs/reference/config/annotations/

sidecar.istio.io/proxyMemory

istio-proxyで使用するメモリサイズを設定する。

＊実装例＊

apiVersion: apps/v1
kind: Deployment # もしくはPod
metadata:
  name: foo-deployment
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: foo-pod
  template:
    metadata:
      annotations:
        sidecar.istio.io/proxyMemory: 4

• https://istio.io/latest/docs/reference/config/annotations/