コンテンツにスキップ

ふ--- title: 【IT技術の知見】ConfigMap系＠リソース定義 description: ConfigMap系＠リソース定義の知見を記録しています。

ConfigMap系＠リソース定義

はじめに

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


01. 専用ConfigMap

Istioの各コンポーネントの機密でない変数やファイルを管理する。


02 istio-ca-root-cert

istio-ca-root-certとは

Istiodコントロールプレーン (discovery コンテナ) による中間認証局を使用する場合、istio-ca-root-cert を自動的に作成する。

ルート認証局から発行されたCA証明書 (ルート証明書) をもち、各マイクロサービスのPodにマウントされる。

各マイクロサービスに配布された証明書を検証するために使用される。

Istioコントロールプレーンのログから、CA証明書の作成を確認できる。

2025-01-26T11:21:09.391516Z info    initializing Istiod DNS certificates host: istiod-1-24-2.istio-system.svc, custom host:
2025-01-29T11:43:03.694183Z info    Generating istiod-signed cert for [istio-pilot.istio-system.svc istiod-1-24-2.istio-system.svc istiod-remote.istio-system.svc istiod.istio-system.svc]:

-----BEGIN CERTIFICATE-----
*****
-----END CERTIFICATE-----

istio_istio-ca-root-cert


root-cert.pem

▼ root-cert.pemとは

CA証明書 (ルート証明書) を設定する。

kind: ConfigMap
apiVersion: v1
metadata:
  name: istio-ca-root-cert
  namespace: app # マイクロサービスのNamespace
data:
  root-cert.pem: |
    -----BEGIN CERTIFICATE-----
    *****
    -----END CERTIFICATE-----


03. istio-cni-config

kind: ConfigMap
apiVersion: v1
metadata:
  name: istio-cni-config
  namespace: kube-system
data:
  CURRENT_AGENT_VERSION: 1.24.2
  AMBIENT_ENABLED: "true"
  AMBIENT_DNS_CAPTURE: "false"
  AMBIENT_IPV6: "true"
  CHAINED_CNI_PLUGIN: "true"
  EXCLUDED_NAMESPACES: kube-system
  REPAIR_ENABLED: "true"
  REPAIR_LABEL_PODS: "false"
  REPAIR_DELETE_PODS: "false"
  REPAIR_REPAIR_PODS: "true"
  REPAIR_INIT_CONTAINER_NAME: istio-validation
  REPAIR_BROKEN_POD_LABEL_KEY: cni.istio.io/uninitialized
  REPAIR_BROKEN_POD_LABEL_VALUE: "true"


04. istio-<リビジョン>

istio-<リビジョン>とは

Istiodコントロールプレーン (discovery コンテナ) のため、全てのistio-proxyへグローバルに設定する変数を管理する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    ...
  meshNetworks: |
    ...

代わりに、IstioOperatorの .spec.meshConfig キーで定義できるが、これは非推奨である。

# これは非推奨
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  name: istio-operator
  namespace: istio-system
spec:
  meshConfig: ...


04-01. mesh

accessLogEncoding

▼ accessLogEncodingとは

istio-proxyで作成するアクセスログのファイル形式を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    accessLogEncoding: JSON


accessLogFile

▼ accessLogFileとは

istio-proxyで作成するアクセスログの出力先を設定する。

設定しないと、Envoyはアクセスログを出力しない。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    accessLogFile: /dev/stdout


caCertificates

▼ caCertificatesとは

ルート認証局のCA証明書や、中間認証局名を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_CERT_SIGNER: istio-system
    caCertificates:
        # ルート認証局のCA証明書 
      - pem: |
          Ci0tLS0tQk...
        # 中間認証局名
        certSigners:
          - clusterissuers.cert-manager.io/istio-system
          - clusterissuers.cert-manager.io/foo
          - clusterissuers.cert-manager.io/bar


discoverySelectors

▼ discoverySelectorsとは

ENHANCED_RESOURCE_SCOPING を有効化し、IstiodコントロールプレーンがwatchするNamespaceを限定する。 Istiodは全てのNamespaceをwatchするが、特定のNamespaceのみをwatchするようにできる。

これは、サイドカーをインジェクションする istio.io/rev キーよりも強い影響力がある。

例えば、サイドカーをインジェクションしているNamespaceのみをwatchすることにより、Istiodコントロールプレーンの負荷を下げられる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    discoverySelectors:
      - matchLabels:
          istio.io/rev: default

▼ REGISTRY_ONLY

サービスメッシュ外へのリクエストの宛先を BlackHoleCluster (502 Bad Gateway で通信負荷) として扱う。

また、ServiceEntryとして登録した宛先には固有の名前がつく。

サービスメッシュ外への通信のたびにServiceEntryを作成しなければならず、少しめんどくさくなる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    outboundTrafficPolicy:
      mode: REGISTRY_ONLY


defaultHttpRetryPolicy

▼ defaultHttpRetryPolicyとは

リトライポリシーのデフォルト値を設定する。

ただし、.spec.http[*].retries.perTryTimeout キーは各VirtualServiceで設定する必要がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultHttpRetryPolicy: 
      attempts: 3
      retryOn: connect-failure,deadline-exceeded,refused-stream,unavailable

▼ アウトバウンド通信時のリトライ条件

istio-proxyのアウトバウンド通信時リトライ条件は以下である。

宛先に通信が届いておらず、リトライすれば問題が解決する可能性のあるステータスコードは、リトライしてもよい。

  • リトライすると解決する可能性がある
  • リクエストを繰り返しても状態が変わらずに冪等性がある (二重処理にならない) がある

503 と reset によるリトライは冪等性に問題があり、設定に注意が必要である。

istio_inbound-retry_reset

HTTP/1.1、HTTP/2のステータスコード マイクロサービスに通信が届いている リトライが有効 リトライ条件
connect-failure ⭕️ ✅ マイクロサービスからのアウトバウンド通信時、接続タイムアウト (Connection timeout) が起こった場合に、リトライを実行する。
gateway-error ⭕️ マイクロサービスからのアウトバウンド通信時、Gateway系ステータスコード (502、503、504) が返信された場合に、リトライを実行する。冪性がない可能性がある。
retriable-status-codes (5xx のように任意のステータスコードを設定する) ⭕️ マイクロサービスからのアウトバウンド通信時、指定したHTTPステータスであった場合に、リトライを実行する。冪等性がない可能性がある。
reset ⭕️ マイクロサービスからのアウトバウンド通信時、接続切断／接続リセット／読み取りタイムアウト (Read timeout) が起こった場合に、リトライを実行する。冪等性がない可能性がある。
HTTP/2のステータスコード マイクロサービスに通信が届いている リトライが有効 リトライ条件
cancelled ⭕️ マイクロサービスからのアウトバウンド通信時、gRPCステータスコードが Cancelled であった場合に、リトライを実行する。送信元がリクエストを切断しているため、リトライするべきではない可能性がある。
deadline-exceeded ⭕️ ✅ マイクロサービスからアウトバウンド通信時、gRPCステータスコードが DeadlineExceeded であった場合に、リトライを実行する。
refused-stream ⭕️ ✅ 同時接続上限数を超過するストリームをマイクロサービスが作成しようとした場合に、リトライを実行する。
resource-exhausted ⭕️ ✅ マイクロサービスからのアウトバウンド通信時、gRPCステータスコードが ResourceExhausted であった場合に、リトライを実行する。
unavailable ⭕️ ✅ マイクロサービスからのアウトバウンド通信時、マイクロサービスにリクエストをフォワーディングできなかった場合に、リトライを実行する。

▼ インバウンド通信時のリトライ条件

istio-proxyのインバウンド通信時のリトライ条件は以下である。

執筆時点 (2025/02/26) では、ENABLE_INBOUND_RETRY_POLICY 変数を true (デフォルト値) にすると使用できる。

HTTP/1.1のステータスコード マイクロサービスに通信が届いている 冪等性がある 理由
reset-before-request × ✅ マイクロサービスへのインバウンド通信時、マイクロサービスにリクエストをフォワーディングできなかった。


defaultProviders

▼ defaultProvidersとは

extensionProviders キーで定義したもののうち、デフォルトで使用するプロバイダーを設定する。

Telemetryで自動的に選択される、

Envoyを使用してアクセスログを収集する場合、.mesh.defaultProviders.accessLogging キーには何も設定しなくてよい。

また、Istioがデフォルトで用意している分散トレースツールを使用する場合も同様に不要である。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultProviders:
       metrics:
         - prometheus
       accessLogging:
         - stackdriver
       tracing:
         - opentelemetry-grpc
    enableTracing: true
    extensionProviders:
      - name: opentelemetry-grpc
        opentelemetry:
          # OpenTelemetry Collectorを宛先として設定する
          service: opentelemetry-collector.foo-namespace.svc.cluster.local
          # gRPC用のエンドポイントを設定する
          port: 4317

Envoyのアクセスログの場合、代わりに .mesh.accessLogEncoding キーと .mesh.accessLogFile キーを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    accessLogEncoding: JSON
    accessLogFile: /dev/stdout

分散トレースの場合、代わりに .mesh.enableTracing キーと .mesh.extensionProviders キーを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableTracing: true
    extensionProviders:
      - name: opentelemetry-grpc
        opentelemetry:
          service: opentelemetry-collector.foo-namespace.svc.cluster.local
          port: 4317


enablePrometheusMerge

▼ enablePrometheusMergeとは

マイクロサービスとistio-proxyをマージするかどうかを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enablePrometheusMerge: true


enableTracing

▼ enableTracingとは

istio-proxyでトレースIDとスパンIDを作成するか否かを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableTracing: true


inboundClusterStatName

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    inboundClusterStatName: inbound|%SERVICE_PORT%|%SERVICE_PORT_NAME%|%SERVICE_FQDN%


ingressSelector

▼ ingressSelectorとは

全てのistio-proxyに関して、使用するGatewayの .metadata.labels.istio キーの値を設定する。

デフォルトでは、Ingressとして ingressgateway が設定される。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    ingressSelector: ingressgateway


ingressService

▼ ingressServiceとは

全てのistio-proxyに関して、使用するIngress Controllerの .metadata.labels.istio キーの値を設定する。

デフォルトでは、Ingressとして ingressgateway が設定される。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    ingressService: ingressgateway


proxyHttpPort

▼ proxyHttpPortとは

全てのistio-proxyに関して、Cluster外からのインバウンド通信 (特にHTTPプロトコル) を待ち受けるポート番号を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    proxyHttpPort: 80


outboundClusterStatName

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    outboundClusterStatName: outbound|%SERVICE_PORT%|%%SUBSET_NAME%%|%SERVICE_FQDN%


outboundTrafficPolicy

▼ outboundTrafficPolicyとは

サービスメッシュ外へのリクエストの宛先の種類 (PassthroughCluster、BlackHoleCluster) を設定する。

▼ ALLOW_ANY (デフォルト)

サービスメッシュ外へのリクエストの宛先を PassthroughCluster として扱う。

また、ServiceEntryとして登録した宛先には固有の名前がつく。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    outboundTrafficPolicy:
      mode: ALLOW_ANY

▼ ALLOW_ANYの注意点

サービスメッシュ外の "クラスター外" の宛先であれば、ALLOW_ANY のため接続可能である (Kiali上は PassthroughClusterという表記) 。

一方で、サービスメッシュ外の "クラスター内" であると、Istioリソースで宛先を登録する必要がある。

方法として、以下がある。

  • OpenTelemetry Collectorをサービスメッシュ内に置いて、VirtualServiceを作成する
  • 〃 をサービスメッシュ外に置いて、ServiceEntryを作成する


proxyListenPort

▼ proxyListenPortとは

全てのistio-proxyに関して、他マイクロサービスからのインバウンド通信を待ち受けるポート番号を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    proxyListenPort: 80


04-01-02. defaultConfig

defaultConfigとは

Istioの全てのコンポーネントに適用する変数のデフォルト値を設定する。

他にProxyConfig (と思ったが、ProxyConfigのドキュメントに載っていない設定は無理みたい) 、Podの .metadata.annotations.proxy.istio.io/config キーでも設定できる。

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

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

3つの箇所で設定できる。

meshConfig:
  defaultConfig:
    discoveryAddress: istiod:15012

apiVersion: apps/v1
kind: Deployment
metadata:
  name: foo
spec:
  selector:
    ...
  template:
    metadata:
      ...
      annotations:
        proxy.istio.io/config: |
          # 表にある設定

# APIがまだ用意されておらず、現状は設定できない
apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  discoveryAddress: istiod:15012


controlPlaneAuthPolicy

データプレーン (istio-proxy) とコントロールプレーン間の通信に相互TLS認証を実施する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      controlPlaneAuthPolicy: MUTUAL_TLS

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  controlPlaneAuthPolicy: MUTUAL_TLS

discoveryAddress

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      discoveryAddress: istiod-<リビジョン>.istio-system.svc:15012

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  discoveryAddress: istiod-<リビジョン>.istio-system.svc:15012


drainDuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      drainDuration: 45s

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  drainDuration: 45s


envoyAccessLogService

Envoyのアクセスログを、標準出力に出力するのではなく宛先 (例：レシーバー) に送信する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableEnvoyAccessLogService: true
    defaultConfig:
      envoyAccessLogService: 
        address: <Envoyのアクセスログの宛先Service名>:15000
        # Istioコントロールプレーンをルート認証局とする
        tlsSettings: ISTIO_MUTUAL
        # TCP KeepAliveを実施する
        tcpKeepalive:
          probes: 9
          time: 2
          interval: 75


envoyMetricsService

Envoyのメトリクスを、Prometheusにスクレイピングしてもらうのではなく宛先 (例：レシーバー) に送信する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    # enableEnvoyMetricsService: true という設定がありそうだが、ドキュメントに記載がない
    defaultConfig:
      envoyMetricsService: 
        address: <Envoyのメトリクスの宛先Service名>:15000
        # Istioコントロールプレーンをルート認証局とする
        tlsSettings: ISTIO_MUTUAL
        # TCP KeepAliveを実施する
        tcpKeepalive:
          probes: 9
          time: 2
          interval: 75


holdApplicationUntilProxyStarts

istio-proxyが、必ずマイクロサービスよりも先に起動するか否かを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      holdApplicationUntilProxyStarts: true

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  holdApplicationUntilProxyStarts: true

オプションを有効化すると、istio-proxyの .spec.containers[*].lifecycle.postStart.exec.command キーに、pilot-agent -wait コマンドが挿入される。

.spec.containers[*].lifecycle.preStop.exec.command キーへの自動設定は、EXIT_ON_ZERO_ACTIVE_CONNECTIONS 変数で対応する。

...

spec:
  containers:
    - name: istio-proxy

      ...

      lifecycle:
        postStart:
          exec:
            command: |
              pilot-agent wait

...


image

istio-proxyのコンテナイメージのタイプを設定する。

これは、ConfigMapではなくProxyConfigでも設定できる。

distroless 型を選ぶと、istio-proxyにログインできなくなり、より安全なイメージになる。

一方で、デバッグしにくくなる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      image:
        imageType: distroless

istio-cni でも、Helmチャートで別に設定すれば、distroless 型を選べる。


privateKeyProvider

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      privateKeyProvider:


proxyHeaders

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

x-envoy ヘッダーを有効化するか否かを設定する。

例えば、接続プール上限超過によるサーキットブレイカーが起こったことを示す x-envoy-overloaded ヘッダーがある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyHeaders:
        envoyDebugHeaders: 
          forwardedClientCert: SANITIZE
        server:
          disabled: true
        requestId:
          disabled: true
        attemptCount:
          disabled: true
        envoyDebugHeaders:
          disabled: true
        metadataExchangeHeaders:
          mode: IN_MESH


proxyMetadata

istio-proxyに環境変数を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        # ここに環境変数を設定する

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  proxyMetadata: ...


rootNamespace

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      rootNamespace: istio-system

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  rootNamespace: istio-system


tracing (非推奨)

いずれのトレース仕様 (例：Zipkin、Datadog、LightStepなど) でトレースIDとスパンIDを作成するかを設定する。

ZipkinとJaegerはトレースコンテキスト仕様が同じであるため、zipkinパッケージをJaegerのクライアントとしても使用できる。

.mesh.defaultConfig.enableTracing キーも有効化する必要がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      enableTracing: true
      tracing:
        sampling: 100
        zipkin:
          address: "jaeger-collector.observability:9411"

ただし、非推奨であるため extensionProviders キーを使用したほうが良い

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      tracing: {}
    extensionProviders:
      ...


tracingServiceName

スパンの service.name 属性の値を設定する。

マイクロサービスがバージョニングされている場合、マイクロサービスの正式名 (canonical-name) でグループ化できる。

デフォルトでは APP_LABEL_AND_NAMESPACE であり、<Namespace>.<appラベル値> になる。

appラベルがないマイクロサービスのために、canonical名に基づく CANONICAL_NAME_AND_NAMESPACE を使用したほうが良い。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      tracingServiceName: APP_LABEL_AND_NAMESPACE

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  tracingServiceName: APP_LABEL_AND_NAMESPACE


trustDomain

相互TLS認証を採用している場合、送信元として許可する信頼ドメインを設定する。

例えば、信頼ドメインはServiceAccountごとに異なる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      trustDomain: cluster.local

apiVersion: networking.istio.io/v1beta1
kind: ProxyConfig
metadata:
  name: foo-proxyconfig
spec:
  trustDomain: cluster.local


04-01-03. defaultConfig.proxyMetadata

BOOTSTRAP_XDS_AGENT

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        BOOTSTRAP_XDS_AGENT: "true"


ENABLE_DEFERRED_CLUSTER_CREATION

pilot-discovery コマンドでも設定できるため、そちらを参照せよ。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ENABLE_DEFERRED_CLUSTER_CREATION: "true"


EXCLUDE_UNSAFE_503_FROM_DEFAULT_RETRY

デフォルトで true である。

pilot-discovery コマンドでも設定できるため、そちらを参照せよ。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        EXCLUDE_UNSAFE_503_FROM_DEFAULT_RETRY: "true"


ENABLE_INBOUND_RETRY_POLICY

デフォルトで true である。

pilot-discovery コマンドでも設定できるため、そちらを参照せよ。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ENABLE_INBOUND_RETRY_POLICY: "true"


EXIT_ON_ZERO_ACTIVE_CONNECTIONS

pod_terminating_process_istio-proxy

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

istio-proxyへのリクエストが無くなってから、Envoyのプロセスを終了する。

具体的には、downstream_cx_active メトリクスの値 (アクティブな接続数) を監視し、0 になるまでドレイン処理を実行し続ける。

ドレイン処理前の待機時間は、MINIMUM_DRAIN_DURATION で設定する。

オプションを有効化すると、istio-proxyの .spec.containers[*].lifecycle.preStop.exec.command キーに、sleep コマンドが自動で挿入される。

.spec.containers[*].lifecycle.postStart.exec.command キーへの自動設定は、.mesh.defaultConfig.holdApplicationUntilProxyStarts キーで対応する。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        EXIT_ON_ZERO_ACTIVE_CONNECTIONS: "false"


ISTIO_META_CERT_SIGNER

デフォルトで "" (空文字) である。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_CERT_SIGNER: ""


ISTIO_META_DNS_AUTO_ALLOCATE

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

固定IPアドレスが設定されていないServiceEntryに対して、IPアドレスを動的に設定する。

ISTIO_META_DNS_CAPTURE を有効にしないと、ISTIO_META_DNS_AUTO_ALLOCATE は機能しない。

PILOT_ENABLE_IP_AUTOALLOCATE と同じであり、Istio 1.25以降で、PILOT_ENABLE_IP_AUTOALLOCATE のほうが推奨になった。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_AUTO_ALLOCATE: "false"

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-address
spec:
  hosts:
    - address.internal
  ports:
    - name: http
      number: 80
      protocol: HTTP


ISTIO_META_DNS_CAPTURE

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

マイクロサービスからのリクエストに、Pod内のistio-proxyやztunnelプロキシをDNSプロキシとして使用できるようになる。

もしistio-proxyやztunnelプロキシがドメインに紐づくIPアドレスのキャッシュを持つ場合、マイクロサービスにレスポンスを返信する。

一方でキャッシュを持たない場合、istio-proxyやztunnelプロキシは宛先Podにリクエストを送信する。

なお、DNSキャッシュのドメインとIPアドレスを固定で紐付けることもできる。

▼ 固定 (HTTPリクエスト)

ServiceEntryでHTTPリクエストを受信した場合、DNSキャッシュのドメインとIPアドレスを固定で紐づける。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-address
spec:
  hosts:
    - address.internal
  ports:
    - name: http
      number: 80
      protocol: HTTP

▼ 動的 (HTTPリクエスト)

ServiceEntryでHTTPリクエストを受信した場合、DNSキャッシュのドメインとIPアドレスを動的に紐づける。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-address
spec:
  hosts:
    - address.internal
  addresses:
    - 198.51.100.1
  ports:
    - name: http
      number: 80
      protocol: HTTP

▼ 動的 (TCP接続)

ServiceEntryで、TCP接続として扱われるホストヘッダー持ち独自プロトコル (例：MySQLやRedis以外の非対応プロトコルなど) を受信した場合、DNSキャッシュのドメインとIPアドレスを動的に紐づける。

注意点として、Istio Egress Gatewayを経由してServiceEntryに至る場合には、この設定が機能しない。

Pod ➡️ Istio Egress Gateway ➡️ ServiceEntry

Istio Ingress Gateway (厳密に言うとGateway) は、独自プロトコルをTCPプロコトルとして扱う。

そのため、受信した独自プロトコルリクエストにホストヘッダーがあったとしても、これを宛先にフォワーディングできない。

宛先が独自プロトコルリクエストのポート番号だけで宛先 (例：ServiceEntry、外部サーバーなど) を決めてしまう。

同じポート番号で待ち受ける複数のServiceEntryがあると、.spec.hosts キーを設定していたとしても、誤ったほうのServiceEntryを選ぶ可能性がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: aws-aurora-endpoint
spec:
  hosts:
    - <AWS AuroraのDBクラスター名>.cluster-<id>.ap-northeast-1.rds.amazonaws.com
  ports:
    - name: cluster-endpoint
      number: 3306
      protocol: TCP
  resolution: DNS
---
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: aws-aurora-endpoint
spec:
  hosts:
    - <AWS AuroraのDBクラスター名>.cluster-ro-<id>.ap-northeast-1.rds.amazonaws.com
  ports:
    - name: reader-endpoint
      number: 3306
      protocol: TCP
  resolution: DNS


MINIMUM_DRAIN_DURATION

pod_terminating_process_istio-proxy

デフォルト値は 5 である (対応する .metadata.annotations.proxy.istio.io/config.terminationDrainDuration キーと同じ) 。

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

false の場合は、代わりに .metadata.annotations.proxy.istio.io/config.terminationDrainDuration を設定する。

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

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

terminationDrainDuration との違いとして、MINIMUM_DRAIN_DURATION の時間だけ待機した後、ドレイン処理を開始し、EXIT_ON_ZERO_ACTIVE_CONNECTIONS によって downstream_cx_active メトリクスが0になるまでドレイン処理をし続ける点である。

Podの .metadata.annotations.proxy.istio.io/config.drainDuration キーで起こるレースコンディションを解決するための設定で、同じ値を設定するとよい。

＊実装例＊

Envoyプロセスの接続のドレイン処理前に 5 秒間待機し、downstream_cx_active メトリクスが0になるまでドレイン処理を続ける。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        MINIMUM_DRAIN_DURATION: "5s"


PILOT_ENABLE_IP_AUTOALLOCATE

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

ISTIO_META_DNS_AUTO_ALLOCATE と同じであり、Istio 1.25以降で、PILOT_ENABLE_IP_AUTOALLOCATE のほうが推奨になった。

ISTIO_META_DNS_CAPTURE を有効にしないと、PILOT_ENABLE_IP_AUTOALLOCATE は機能しない。


04-01-04. extensionProviders (認証／認可系)

extensionProviders (認証／認可系) とは

AuthorizationPolicyによる認可処理を外部の認可プロバイダーに委譲する。


envoyExtAuthzHttp

▼ envoyExtAuthzHttpとは

外部の認可プロバイダーへの通信にHTTP/1.1プロトコルを使用する。

▼ OAuth2 Proxyの場合

OAuth2 Proxyを任意の認可プロバイダーの前段に置き、OAuth2 Proxyで認可プロバイダーを宛先に設定する。

＊実装例＊

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      # 認可プロバイダーのエイリアス名を設定する
      - name: oauth2-proxy
        # 認可プロバイダーを設定する
        envoyExtAuthzHttp:
          service: oauth2-proxy.foo.svc.cluster.local
          port: 4180
        # HTTPリクエストに含めるヘッダー
        includeHeadersInCheck:
          - cookie
          - authorization

AuthorizationPolicyで、認可処理をOAuth2 Proxyへ委譲できるようになる。

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: oauth2-proxy-authorization-policy
  namespace: istio-system
spec:
  action: CUSTOM
  provider:
    name: oauth2-proxy
  rules:
    # ルールは外部の認可プロバイダーに定義されている
    - to:
        - operation:
            paths: ["/login"]

▼ Open Agent Policyの場合

Open Agent Policyを外部の認可プロバイダーとして設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      # 認可プロバイダーのエイリアス名を設定する
      - name: open-policy-agent
        # 認可プロバイダーを設定する
        envoyExtAuthzHttp:
          service: open-policy-agent.foo.svc.cluster.local
          port: 9191
        # HTTPリクエストに含めるヘッダー
        includeHeadersInCheck:
          - cookie
          - authorization

実装例

▼ Keycloakの場合

Keycloakは、IDプロバイダーとしてだけでなく認可プロバイダーとしても使用できる。

ただし、前段にOAuth2 Proxyを置くことが一般的である。


envoyExtAuthzGrpc

認可プロバイダーへの通信にHTTP/2プロトコルを使用する。


04-01-05. extensionProviders (可観測系)

extensionProviders (可観測系) とは

監視バックエンドの宛先情報を設定する。

プロバイダーによって、いずれのテレメトリーを送信するのかが異なる。


datadog

▼ datadogとは

datadogのトレースコンテキスト仕様 (datadogの独自仕様) でトレースIDとスパンIDを作成する。

datadogエージェントの宛先情報をIstioに登録する必要があるため、これのPodをサービスメッシュ内に配置するか、サービスメッシュ外に配置してIstio Egress GatewayやServiceEntry経由で接続できるようにする。

ただ、datadogエージェントをサービスメッシュ内に配置すると、Telemetryリソースがdatadogエージェント自体の分散トレースを作成してしまうため、メッシュ外に配置するべきである。

.mesh.enableTracing キーも有効化する必要がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableTracing: true
    extensionProviders:
      - name: datadog-http
        datadog:
          # datadogエージェントを宛先として設定する
          service: datadog-agent.foo-namespace.svc.cluster.local
          port: 8126
      - name: envoy-log
        envoyFileAccessLog

▼ Telemetryの定義

Datadogに送信するためには、.mesh.extensionProviders[*].datadog キーに設定した宛先情報を使用して、Telemetryを定義する必要がある。

分散トレースの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: tracing-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # Datadogにスパンを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  tracing:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: datadog-http
      randomSamplingPercentage: 100

アクセスログの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: access-log-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # Datadogにアクセスログを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  # Envoyをアクセスログプロバイダーとして設定する
  accessLogging:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: envoy-log


opentelemetry

▼ opentelemetryとは

OpenTelemetryのトレースコンテキスト仕様 (W3C Trace Context) でトレースIDとスパンIDを作成する。

OTLP形式のエンドポイントであればよいため、OpenTelemetry Collectorも指定できる。

OpenTelemetry Collectorの宛先情報をIstioに登録する必要があるため、これのPodをサービスメッシュ内に配置するか、サービスメッシュ外に配置してIstio Egress GatewayやServiceEntry経由で接続できるようにする。

ただ、OpenTelemetry Collectorをサービスメッシュ内に配置すると、TelemetryリソースがOpenTelemetry Collector自体の分散トレースを作成してしまうため、メッシュ外に配置するべきである。

.mesh.enableTracing キーも有効化する必要がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableTracing: true
    extensionProviders:
      - name: opentelemetry-grpc
        opentelemetry:
          # OpenTelemetry Collectorを宛先として設定する
          service: opentelemetry-collector.foo-namespace.svc.cluster.local
          # gRPC用のエンドポイントを設定する
          port: 4317
      - name: opentelemetry-http
        opentelemetry:
          # OpenTelemetry Collectorを宛先として設定する
          service: opentelemetry-collector.foo-namespace.svc.cluster.local
          # HTTP用のエンドポイントを設定する
          port: 4318
            http:
            # HTTPリクエストの場合はパスが必要である
            path: /v1/traces
      - name: envoy-log
        envoyFileAccessLog:
          path: /dev/stdout

▼ Telemetryの定義

OpenTelemetryに送信するためには、.mesh.extensionProviders[*].opentelemetry キーに設定した宛先情報を使用して、Telemetryを定義する必要がある。

分散トレースの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: tracing-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # Opentelemetryにスパンを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  tracing:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: opentelemetry-grpc
      randomSamplingPercentage: 100

アクセスログの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: access-log-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # OpenTelemetryにアクセスログを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  # Envoyをアクセスログプロバイダーとして設定する
  accessLogging:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: envoy-log


prometheus

▼ prometheusとは

メトリクスの監視バックエンドとするPrometheusの宛先情報を設定する。


zipkin (jaeger)

▼ zipkin (jaeger) とは

Zipkinのトレースコンテキスト仕様 (B3コンテキスト) でトレースIDとスパンIDを作成する。

JaegerはB3をサポートしているため、Jaegerのクライアントとしても使用できる。

jaegerエージェントの宛先情報をIstioに登録する必要があるため、これのPodをサービスメッシュ内に配置するか、サービスメッシュ外に配置してIstio Egress GatewayやServiceEntry経由で接続できるようにする。

ただ、jaegerエージェントをサービスメッシュ内に配置すると、Telemetryリソースがjaegerエージェント自体の分散トレースを作成してしまうため、メッシュ外に配置するべきである。

.mesh.enableTracing キーも有効化する必要がある。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    enableTracing: true
    extensionProviders:
      - name: jaeger-http
        jaeger:
          # jaegerエージェントを宛先として設定する
          service: jaeger-agent.foo-namespace.svc.cluster.local
          port: 8126
      - name: envoy-log
        envoyFileAccessLog:
          path: /dev/stdout

ZipkinやJaegerに送信するためには、.mesh.extensionProviders[*].zipkin キーに設定した宛先情報を使用して、Telemetryを定義する必要がある。

分散トレースの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: tracing-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # Datadogにスパンを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  tracing:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: jaeger-http
      randomSamplingPercentage: 100

アクセスログの設定は以下の通りである。

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: access-log-provider
  # サイドカーをインジェクションしている各Namespaceで作成する
  # もしistio-systemを指定した場合は、istio-proxyコンテナのある全てのNamespaceが対象になる
  namespace: foo
spec:
  # ZipkinやJaegerにアクセスログを送信させるPodを設定する
  selector:
    matchLabels:
      name: app
  # Envoyをアクセスログプロバイダーとして設定する
  accessLogging:
    - providers:
        # mesh.extensionProviders[*].nameキーで設定した名前
        - name: envoy-log


envoyFileAccessLog

▼ envoyFileAccessLogとは

Envoyのアクセスログを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      - name: envoy-grpc
        envoyFileAccessLog:
          logFormat:
            labels:
              access_log_type: '%ACCESS_LOG_TYPE%'
              bytes_received: '%BYTES_RECEIVED%'
              bytes_sent: '%BYTES_SENT%'
              downstream_transport_failure_reason: '%DOWNSTREAM_TRANSPORT_FAILURE_REASON%'
              downstream_remote_port: '%DOWNSTREAM_REMOTE_PORT%'
              duration: '%DURATION%'
              grpc_status: '%GRPC_STATUS(CAMEL_STRING)%'
              method: '%REQ(:METHOD)%'
              path: '%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%'
              protocol: '%PROTOCOL%'
              response_code: '%RESPONSE_CODE%'
              response_flags: '%RESPONSE_FLAGS%'
              start_time: '%START_TIME%'
              trace_id: '%TRACE_ID%'
              traceparent: '%REQ(TRACEPARENT)%'
              upstream_remote_port: '%UPSTREAM_REMOTE_PORT%'
              upstream_transport_failure_reason: '%UPSTREAM_TRANSPORT_FAILURE_REASON%'
              user_agent: '%REQ(USER-AGENT)%'
              x_forwarded_for: '%REQ(X-FORWARDED-FOR)%'


04-02-03. meshNetworks

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  meshNetworks: |
    networks:
        foo-cluster:
          endpoints:
            - fromCidr: "192.168.0.1/24"
          gateways:
            - address: 1.1.1.1
              port: 80
        bar-cluster:
          endpoints:
            - fromRegistry: reg1
          gateways:
            - registryServiceName: istio-ingressgateway.istio-system.svc.cluster.local
              port: 443


05. istio-sidecar-injector

config

▼ configとは

Istiodコントロールプレーン (discovery コンテナ) のため、Istioのサイドカーインジェクションの変数やpatch処理の内容を管理する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-sidecar-injector-<リビジョン>
  namespace: istio-system
data:
  config: |
    defaultTemplates: [sidecar]
    policy: enabled
    alwaysInjectSelector: []
    neverInjectSelector:[]
    injectedAnnotations:
    template: "{{ Template_Version_And_Istio_Version_Mismatched_Check_Installation }}"
    templates:
      sidecar: |
        # Helmのテンプレート

▼ .templates.sidecar

istio-proxyコンテナの設定値をHelmテンプレートの状態で管理する。

Istioは、istio-sidecar-injectorの .values キーを使用してテンプレートを動的に完成させる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-sidecar-injector-<リビジョン>
  namespace: istio-system
data:
  config: |
    templates:
      sidecar: |

        ... # Helmのテンプレート


values

istio-sidecar-injectorの .templates.sidecar キーに出力する値を values ファイルとして管理する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-sidecar-injector-<リビジョン>
  namespace: istio-system
data:
  values: |
    { 
      global: { ... }
      revision: <リビジョン>
      sidecarInjectorWebhook: { ... }
    }


06. pilot-discoveryコマンドの環境変数

CITADEL_SELF_SIGNED_CA_CERT_TTL

Istioコントロールプレーンが自身を署名するオレオレ証明書の有効期限を設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: CITADEL_SELF_SIGNED_CA_CERT_TTL
            value: 87600h0m0s


CITADEL_SELF_SIGNED_ROOT_CERT_CHECK_INTERVAL

Istioコントロールプレーンのオレオレ証明書の検証間隔を設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: CITADEL_SELF_SIGNED_ROOT_CERT_CHECK_INTERVAL
            value: 1h0m0s


CLUSTER_ID

Istiodのサービスレジストリを設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: CLUSTER_ID
              value: Kubernetes


DEFAULT_WORKLOAD_CERT_TTL

istio-proxyの証明書の有効期限を設定する。

最大値は MAX_WORKLOAD_CERT_TTL (90日) で決まっている。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
  　spec:
    containers:
      - name: discovery
        env:
          - name: DEFAULT_WORKLOAD_CERT_TTL
            value: 24h0m0s


ENABLE_DEFERRED_CLUSTER_CREATION

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

リクエストがある場合にのみ、Envoyのクラスターを作成する。

実際に使用されていないEnvoyのクラスターを作成しないことにより、ハードウェアリソースを節約できる。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: ENABLE_DEFERRED_CLUSTER_CREATION
              value: "true"


ENABLE_DEFERRED_STATS_CREATION

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

Envoyの統計情報を遅延初期化する。

ハードウェアリソースを節約できる。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: ENABLE_DEFERRED_STATS_CREATION
              value: "true"


ENABLE_ENHANCED_RESOURCE_SCOPING

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

meshConfig.discoverySelectors キーを使用できるようにする。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: ENABLE_ENHANCED_RESOURCE_SCOPING
              value: "true"


ENABLE_ENHANCED_DESTINATIONRULE_MERGE

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

複数のDestinationRuleで .spec.exportTo キーの対象のNamespaceが同じ場合、これらの設定をマージして処理する。

もし対象のNamespaceが異なる場合、独立した設定として処理する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: ENABLE_ENHANCED_DESTINATIONRULE_MERGE
              value: "true"


ENABLE_INBOUND_RETRY_POLICY

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

istio-proxyがインバウンド通信をマイクロサービスに送信するときのリトライ (執筆時点2025/02/26では reset-before-request のみ) を設定する。

今後は、宛先istio-proxyがマイクロサービスに対してリトライできるようになる。

istio-proxy間の問題の切り分けがしやすくなる。

false の場合、送信元istio-proxyから宛先istio-proxyへ通信時、送信元istio-proxyしかリトライできない。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: ENABLE_INBOUND_RETRY_POLICY
              value: "true"


EXCLUDE_UNSAFE_503_FROM_DEFAULT_RETRY

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

POSTリクエストの結果で、マイクロサービスから 503 ステータスが返信された場合、未処理とは限らない。

この場合にリトライすると結果的に二重で処理が実行されてしまう。

そのため、マイクロサービスから 503 ステータスが返信された場合は、リトライしないようにする。

なおこの問題は、reset によるリトライでも起こりうるため、reset もデフォルトから外れている。

リトライの結果でistio-proxyが 503 レスポンスを返信する場合とは区別する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    spec:
      containers:
        - name: discovery
          env:
            - name: EXCLUDE_UNSAFE_503_FROM_DEFAULT_RETRY
              value: "true"


PILOT_TRACE_SAMPLING

分散トレースの収集率を設定する。

基本的には 100% (値は 1) を設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: PILOT_TRACE_SAMPLING
            value: 1


PILOT_CERT_PROVIDER

istio-proxyに設定するサーバー証明書のプロバイダーを設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: PILOT_CERT_PROVIDER
            value: istiod
設定値 説明
istiod Istiodが提供するサーバー証明書を使用する。
kubernetes KubernetesのSecretで管理するサーバー証明書を使用する。
none サーバー証明書を使用しない。


PILOT_ENABLE_MYSQL_FILTER

Envoyの mysql_proxy を有効化し、MySQLのメトリクスを収集できるようにする。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: PILOT_ENABLE_MYSQL_FILTER
            value: "true"

proxyStatsMatcher でも設定が必要である。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyStatsMatcher:
        inclusionRegexps:
          - ".*mysql.*"


PILOT_ENABLE_REDIS_FILTER

Envoyの redis_proxy を有効化し、MySQLのメトリクスを収集できるようにする。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: PILOT_ENABLE_REDIS_FILTER
            value: "true"

proxyStatsMatcher でも設定が必要である。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-<リビジョン>
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyStatsMatcher:
        inclusionRegexps:
          - ".*redis.*"


PILOT_JWT_PUB_KEY_REFRESH_INTERVAL

アクセストークンの検証の間隔を設定する。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: istiod
  namespace: istio-system
spec:
  template:
    containers:
      - name: discovery
        env:
          - name: PILOT_JWT_PUB_KEY_REFRESH_INTERVAL
            value: 20m0s