コンテンツにスキップ

ConfigMap系＠リソース定義

はじめに

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


01. 専用ConfigMap

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


02 istio-ca-root-cert

istio-ca-root-certとは

Istiodコントロールプレーン (discoveryコンテナ) による中間認証局を使用する場合に、ルート認証局から発行されたCA証明書を設定する。


root-cert.pem

▼ root-cert.pemとは

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

kind: ConfigMap
apiVersion: v1
metadata:
  name: istio-ca-root-cert
  namespace: istio-system
data:
  root-cert.pem: |
    -----BEGIN CERTIFICATE-----
    *****
    -----END CERTIFICATE-----


03. istio-mesh-cm

istio-mesh-cmとは

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

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

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


accessLogEncoding

▼ accessLogEncodingとは

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    accessLogEncoding: JSON


accessLogFile

▼ accessLogFileとは

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    accessLogFile: /dev/stdout


caCertificates

▼ caCertificatesとは

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  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を限定する。

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    discoverySelectors:
      - matchLabels:
          istio.io/rev: stable


outboundTrafficPolicy

▼ outboundTrafficPolicyとは

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

▼ ALLOW_ANY

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    outboundTrafficPolicy:
      mode: ALLOW_ANY

▼ REGISTRY_ONLY

サービスメッシュ外へのリクエストの宛先を、デフォルトでBlackHoleCluster (502 Bad Gateway) として扱う。

PassthroughClusterとして扱いたい宛先は、ServiceEntryに設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    outboundTrafficPolicy:
      mode: REGISTRY_ONLY


defaultConfig

▼ defaultConfigとは

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

各Podで個別に設定したい場合、.metadata.annotations.proxy.istio.io/config.configPathキーにオプションを設定する。

▼ discoveryAddress

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

▼ enablePrometheusMerge

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      enablePrometheusMerge: "true"

▼ holdApplicationUntilProxyStarts

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      holdApplicationUntilProxyStarts: "true"

▼ proxyMetadata

istio-proxyコンテナに環境変数を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"
        BOOTSTRAP_XDS_AGENT: "true"
        # ServiceからPod内のistio-proxyへのリクエストがなくなったら、istio-proxyコンテナを終了させる
        EXIT_ON_ZERO_ACTIVE_CONNECTIONS: "true"

▼ rootNamespace

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      rootNamespace: istio-system

▼ tracing

istio-proxyコンテナでトレースIDとスパンIDを作成する場合に、いずれのパッケージ (例：Zipkin、Datadog、LightStepなど) で計装するかを設定する。

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

ただし、これを使用するよりはextensionProvidersキーを使用した方が良い

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      enableTracing: "true"
      tracing:
        sampling: 100
        zipkin:
          address: "jaeger-collector.observability:9411"

▼ trustDomain

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultConfig:
      trustDomain: cluster.local


defaultProviders

▼ defaultProvidersとは

テレメトリーの収集ツールを設定する。

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    defaultProviders:
       metrics:
         - prometheus
       accessLogging:
         - stackdriver

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    accessLogEncoding: JSON
    accessLogFile: /dev/stdout

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    enableTracing: "true"
    defaultConfig:
      tracing:
        sampling: 100
        zipkin:
          address: "jaeger-collector.observability:9411"


enablePrometheusMerge

▼ enablePrometheusMergeとは

アプリケーションのメトリクスをistio-proxyコンテナを介して取得できるようにする (マージする) かどうかを設定する。


enableTracing

▼ enableTracingとは

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

これを有効化した場合に、.mesh.defaultConfigキー配下で、いずれのパッケージ (例：Zipkin、Jaegerなど) で計装するかを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    enableTracing: "true"
    defaultConfig:
      tracing:
        sampling: 100
        zipkin:
          # パッケージが提供する Collectorの宛先を設定する。
          address: "jaeger-collector.observability:9411"


extensionProviders (認証/認可系)

▼ 認証/認可系

SSOの認証フェーズの委譲先となるIDプロバイダーの宛先情報を設定する。

▼ envoyExtAuthzHttp

認可エンドポイントにHTTPで認可リクエストを送信する場合に、SSOのIDプロバイダーの情報を設定する。

AuthorizationPolicyによる認可の実施に、認可フェーズを外部のIDプロバイダーに委譲できるようにする。

＊実装例＊

OAuth2 ProxyのPodに紐づくServiceを識別できるようにする。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      - name: OAuth2 Proxy
        envoyExtAuthzHttp:
          service: oauth2-proxy.foo-namespace.svc.cluster.local
          port: 80
        includeHeadersInCheck:
          - cookie
          - authorization

AuthorizationPolicyで、認可フェーズの委譲先のIDプロバイダーを設定できるようになる。

ここでは、OAuth2 ProxyをIDプロバイダーとして使用する。

apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: oauth2-proxy-authorization-policy
  namespace: istio-system
spec:
  action: CUSTOM
  provider:
    name: oauth2-proxy
  rules:
    - to:
        - operation:
            paths: ["/login"]

▼ envoyExtAuthzGrpc

認可エンドポイントにHTTPで認可リクエストを送信する場合に、SSOのIDプロバイダーの情報を設定する。


extensionProviders (可観測系)

▼ 可観測性系とは

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

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

▼ datadog

分散トレースのクライアントをdatadogパッケージで計装する。

Datadogでは、トレースコンテキスト仕様がdatadogコンテキストになる。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      - name: foo-provider
        datadog:
          # datadogエージェントを宛先として設定する
          service: datadog-agent.foo-namespace.svc.cluster.local
          port: 8126
      - name: bar-provider
        envoyFileAccessLog

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

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

apiVersion: telemetry.istio.io/v1alpha1
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: foo-provider
      randomSamplingPercentage: 100

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

apiVersion: telemetry.istio.io/v1alpha1
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: bar-provider

▼ opentelemetry

分散トレースのクライアントをOpenTelemetryで計装する。

OpenTelemetryでは、トレースコンテキスト仕様はW3C Trace Contextになる。

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      - name: foo-provider
        opentelemetry:
          # OpenTelemetry Collectorを宛先として設定する
          service: opentelemetry-collector.foo-namespace.svc.cluster.local
          # gRPC用のエンドポイントを設定する
          port: 4317
      - name: bar-provider
        envoyFileAccessLog:
          path: /dev/stdout

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

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

apiVersion: telemetry.istio.io/v1alpha1
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: foo-provider
      randomSamplingPercentage: 100

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

apiVersion: telemetry.istio.io/v1alpha1
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: bar-provider

▼ prometheus

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

▼ zipkin (jaeger)

分散トレースのクライアントをzipkinパッケージで計装する。

Zipkinでは、トレースコンテキスト仕様がB3コンテキストになる。

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    extensionProviders:
      - name: foo-provider
        jaeger:
          # jaegerエージェントを宛先として設定する
          service: jaeger-agent.foo-namespace.svc.cluster.local
          port: 8126
      - name: bar-provider
        envoyFileAccessLog:
          path: /dev/stdout

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

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

apiVersion: telemetry.istio.io/v1alpha1
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: foo-provider
      randomSamplingPercentage: 100

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

apiVersion: telemetry.istio.io/v1alpha1
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: bar-provider


holdApplicationUntilProxyStarts

▼ holdApplicationUntilProxyStartsとは

istio-proxyコンテナが、必ずアプリコンテナよりも先に起動するか否かを設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    holdApplicationUntilProxyStarts: "true"

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

...

spec:
  containers:
    - name: istio-proxy

      ...

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

...


ingressSelector

▼ ingressSelectorとは

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    ingressSelector: ingressgateway


ingressService

▼ ingressServiceとは

全てのistio-proxyコンテナに関して、使用するIngressコントローラーの.metadata.labels.istioキーの値を設定する。

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    ingressService: ingressgateway


proxyHttpPort

▼ proxyHttpPortとは

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    proxyHttpPort: 80


proxyListenPort

▼ proxyListenPortとは

全てのistio-proxyコンテナに関して、他アプリコンテナからのインバウンド通信を待ち受けるポート番号を設定する。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-mesh-cm
  namespace: istio-system
data:
  mesh: |
    proxyListenPort: 80


04. 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: { ... }
    }


05. 環境変数

Istiod

▼ CLUSTER_ID

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

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

▼ 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コンテナに設定するSSL証明書のプロバイダーを設定する。

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が提供するSSL証明書を使用する。
kubernetes KubernetesのSecretで管理するSSL証明書を使用する。
none SSL証明書を使用しない。