コンテンツにスキップ

ふ--- 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:
    - <Amazon 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:
    - <Amazon 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