Kubernetes Envoy

この例では、Next-Gen WAF エージェントは Docker サイドカーで実行され、アプリケーションにデプロイされた Envoy プロキシと直接通信します。

Next-Gen WAF エージェントを統合する

Next-Gen WAF エージェントは、各 Pod にサイドカーとしてインストールすることも、特定の要件向けに Service としてインストールすることもできます。

Kubernetes における Next-Gen WAF エージェントの推奨インストール方法は、sigsci-agent を Pod にサイドカーとして統合することです。これは、sigsci-agent を Kubernetes Pod の追加コンテナとして追加することを意味します。サイドカーとして動作することで、エージェントは Pod 内のアプリケーション/Service と共にスケーリングすることになり、個別にスケーリングする必要がなくなります。ただし、状況によっては sigsci-agent コンテナを Service としてインストールし、アプリケーションとは別にスケーリングした方が適している場合もあります。

sigsci-agent コンテナは、インストールタイプや使用するモジュールに応じてさまざまな方法で設定できます。

コンテナフック preStop を使用すると、Pod のシャットダウンを遅らせ、ドレインタイムアウトを確実に満たすことができます。

preStop:
  exec:
    command:
      - sleep
      - "30"

デフォルトでは、エージェントは予備的な検査のために迅速な起動とパフォーマンス準備を優先します。ただし、ルールや設定データを読み込んだ後にのみトラフィックを検査したい場合、迅速な起動が必ずしも望ましいとは限りません。その場合は、Startup Probe を設定してエージェントの起動を遅延させることを検討してください。

エージェントコンテナイメージを取得および更新する

公式の signalsciences/sigsci-agent コンテナイメージが Docker Hub で利用可能です。

独自のイメージをビルドしたい場合や、イメージをカスタマイズする必要がある場合は、sigsci-agent のビルド手順に従ってください。

これらの手順では、latest バージョンのエージェントを imagePullPolicy: Always で参照しており、ローカルにすでにエージェントが存在する場合でも最新のエージェントバージョンを取得します。これは、ドキュメントが古くならないようにし、このドキュメントを参照するすべての人が古い状態のままのエージェントを使うことを防ぐためです。ただし、インストールの一貫性を維持する必要がある場合や、特定バージョンのエージェントを維持する必要がある場合は、この方法が適さない可能性があります。このような場合は、エージェントのバージョンを指定する必要があります。Docker Hub 上のイメージにはバージョンがタグ付けされており、バージョンのリストは Docker Hub で確認できます。

latest イメージを使用するか特定のバージョンを使用するかにかかわらず、エージェントを最新の状態に保つために考慮すべき項目がいくつかあります。

`latest` コンテナイメージを使用する

latest イメージを使用することを選択した場合は、エージェントを最新の状態に保つ方法を検討する必要があります。

imagePullPolicy: Always オプションを使用した場合、起動のたびに最新のイメージが取得され、エージェントは継続的に更新を受け取ります。
あるいは、起動時に常にプルするのではなく、定期的に手動でローカルキャッシュを更新する方法もあります。
```
$ docker pull signalsciences/sigsci-agent:latest
```
次に、latest を imagePullPolicy: Never 設定で使用して、スタートアップ時にプルが実行されないようにします (上記のように手動でのみ)。
```
- name: sigsci-agent
    image: signalsciences/sigsci-agent:latest
    imagePullPolicy: Never
    ...
```

バージョン管理されたコンテナイメージをご利用ください

特定のバージョンのエージェントを使用するには、latest をエージェントのバージョン (ここでは x.xx.x で表されます) に置き換えてください。この場合、イメージは更新されるべきではないため、imagePullPolicy: IfNotPresent に変更することもおすすめします。

- name: sigsci-agent
    image: signalsciences/sigsci-agent:x.xx.x
    imagePullPolicy: IfNotPresent
    ...

この方法では、指定したエージェントバージョンがプルされ、ローカルにキャッシュされます。この方法を使用する場合、後からエージェントイメージを更新しやすくするため、Helm などを使ってエージェントイメージをパラメータ化することを推奨します。

コンテナイメージにカスタムタグを使用する

ローカルエージェントイメージにカスタムタグを適用することも可能です。これを行うには、エージェントイメージを (バージョンまたは latest で) プルし、カスタムタグを適用し、そのカスタムタグを設定で使用します。ローカルイメージは手動でのみ更新されるように imagePullPolicy: Never を指定する必要があります。その後、エージェントを最新の状態に保つために、ローカルイメージを定期的に更新する必要があります。

例:

$ docker pull signalsciences/sigsci-agent:latest
$ docker tag signalsciences/sigsci-agent:latest signalsciences/sigsci-agent:testing

次に、このイメージタグを設定で使用します。

- name: sigsci-agent
    image: signalsciences/sigsci-agent:testing
    imagePullPolicy: Never
...

エージェントコンテナを設定する

エージェントの設定は通常、環境変数を通じて行います。ほとんどの設定オプションは環境変数として利用可能です。環境変数名は、設定オプション名をすべて大文字にし、SIGSCI_ を接頭辞として付け、ダッシュ (-) をアンダースコア (_) に置き換えたものになります。たとえば、max-procs オプションは SIGSCI_MAX_PROCS 環境変数になります。利用可能なオプションの詳細については、エージェント設定ドキュメントを参照してください。

sigsci-agent コンテナには設定が必要ないくつかのオプションがあります。

エージェント認証情報（Agent Access Key と Agent Secret Key）。
一時ファイルを書き込むためのボリューム。

エージェントの認証情報

sigsci-agent の認証情報は、2つの環境変数で設定されます。これらの変数が設定されていない場合、エージェントは起動しません。

SIGSCI_ACCESSKEYID : Agent Access Key は、エージェントが設定されている Next-Gen WAF コントロールパネル上のサイト (ワークスペース) を識別します。
SIGSCI_SECRETACCESSKEY : Agent Secret Key はエージェントを認証・認可するための共有秘密鍵です。

これらの値は非常に機密性が高いため、Kubernetes の組み込み secrets 機能を使用することを推奨します。この構成では、エージェントは Deployment 設定内にハードコードされた値を読み取るのではなく、Secrets データから値を取得します。これにより、エージェント認証情報のローテーションも、1か所を変更するだけで管理しやすくなります。

secrets 機能を使うには、value オプションではなく valueFrom オプションを使用します。例 :

env:
  - name: SIGSCI_ACCESSKEYID
    valueFrom:
      secretKeyRef:
        # Update my-site-name-here to the correct site (workspace) name or similar identifier
        name: sigsci.my-site-name-here
        key: accesskeyid
  - name: SIGSCI_SECRETACCESSKEY
    valueFrom:
      secretKeyRef:
        # Update my-site-name-here to the correct site (workspace) name or similar identifier
        name: sigsci.my-site-name-here
        key: secretaccesskey

secrets機能は、Kubernetes内のさまざまなストアに秘密を保持します。このガイドでは、例として汎用のsecret storeを使用していますが、同等のstoreであればどれでも使用できます。エージェントのシークレットは、以下の例のようなYAMLを使用して汎用secret storeに追加できます。

apiVersion: v1
kind: Secret
metadata:
  name: sigsci.my-site-name-here
stringData:
  accesskeyid: 12345678-abcd-1234-abcd-1234567890ab
  secretaccesskey: abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD

これは、次のように kubectl を使用してコマンドラインから作成することもできます。

$ kubectl create secret generic sigsci.my-site-name-here \
  --from-literal=accesskeyid=12345678-abcd-1234-abcd-1234567890ab \
  --from-literal=secretaccesskey=abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD

Kubernetes の secrets 機能に関する詳細は、Kubernetes のドキュメントを参照してください。

エージェント一時ボリューム

セキュリティ強化のため、sigsci-agent コンテナはルートファイルシステムを読み取り専用としてマウントして実行することを推奨します。ただし、エージェントは RPC 通信用のソケットファイルのような一時ファイルや、位置情報データなどの定期的に更新されるファイルを書き込む必要があります。

読み取り専用のルートファイルシステムでこれを実現するには、書き込み可能なボリュームをマウントする必要があります。この書き込み可能なボリュームは、同じポッド内の他のコンテナにRPCソケットファイルを公開するために共有することもできます。

書き込み可能なボリュームを作成する推奨方法は、組み込みの emptyDir ボリュームタイプを使用することです。これは通常、次の例のように Deployment の volumes セクションで設定します。

volumes:
  - name: sigsci-tmp
    emptyDir: {}

その後、コンテナはこのボリュームを /sigsci/tmp にマウントします。

volumeMounts:
  - name: sigsci-tmp
    mountPath: /sigsci/tmp

公式エージェントコンテナイメージのデフォルト設定では、一時ボリュームが /sigsci/tmp にマウントされます。エージェントコンテナ用にこれを変更する必要がある場合、次のエージェント設定オプションもデフォルトから新しいマウント場所に合わせて変更する必要があります。

rpc-address (デフォルト : /sigsci/tmp/sigsci.sock)
shared-cache-dir (デフォルト : /sigsci/tmp/cache)

Next-Gen WAFエージェントをEnvoyプロキシに統合する

Next-Gen WAF エージェントは、外部認可 (ext_authz) HTTP フィルターを介して Envoy プロキシと統合できます。このフィルターは、gRPC を通じて sigsci-agent と通信します。

Generic Envoy プロキシ

Envoy と Next-Gen WAF エージェントの設定は、Envoy インストールガイドで他のモジュールと共に記載されています。このガイドは、既存の Envoy 設定に対して Next-Gen WAF エージェントをサイドカーとしてデプロイするためのものです。sigsci-agent コンテナを Envoy のサイドカーとしてデプロイする点は一般的なモジュールベースのデプロイと似ていますが、設定はやや異なります。

Envoy のサイドカーとして Next-Gen WAF エージェントをデプロイするには、以下の手順が必要です。

Envoy インストールガイドに記載されているとおり、既存の Envoy 設定を変更します。
Envoy gRPC リスナーモードで設定された sigsci-agent コンテナを Pod に追加します。
emptyDir{} ボリュームを追加して、sigsci-agent が一時的なデータを書き込む場所とします。

Envoy Proxy 設定を変更する

Envoy インストールガイドに記載されているとおり、既存の Envoy 設定を変更します。

Envoy gRPC サービスとして Next-Gen WAF エージェントを追加します。

...
      containers:
      # Example Envoy front proxy running on port 8000
      - name: envoy-frontproxy
        image: signalsciences/envoy-frontproxy:latest
        imagePullPolicy: IfNotPresent
        args:
        - -c
        - /etc/envoy/envoy.yaml
        - --service-cluster
        - front-proxy
        - -l
        - info
        ports:
        - containerPort: 8000
      # Example helloworld app running on port 8080 without sigsci configured (accessed via Envoy proxy)
      - name: helloworld
        image: signalsciences/example-helloworld:latest
        imagePullPolicy: IfNotPresent
        args:
        # Address for the app to listen on
        - localhost:8080
        ports:
        - containerPort: 8080
      # Next-Gen WAF agent running in Envoy gRPC mode (SIGSCI_ENVOY_GRPC_ADDRESS configured)
      - name: sigsci-agent
        image: signalsciences/sigsci-agent:latest
        imagePullPolicy: IfNotPresent
        # Configure the agent to use Envoy gRPC on port 9999
        env:
        - name: SIGSCI_ACCESSKEYID
          valueFrom:
            secretKeyRef:
              # This secret needs added (see docs on sigsci secrets)
              name: sigsci.my-site-name-here
              key: accesskeyid
        - name: SIGSCI_SECRETACCESSKEY
          valueFrom:
            secretKeyRef:
              # This secret needs added (see docs on sigsci secrets)
              name: sigsci.my-site-name-here
              key: secretaccesskey
        # Configure the Envoy to expect response data (if using a gRPC access log config for Envoy)
        - name: SIGSCI_ENVOY_EXPECT_RESPONSE_DATA
          value: "1"
        # Configure the Envoy gRPC listener address on any unused port
        - name: SIGSCI_ENVOY_GRPC_ADDRESS
          value: localhost:9999
        ports:
        - containerPort: 9999
        securityContext:
          # The sigsci-agent container should run with its root filesystem read only
          readOnlyRootFilesystem: true

Deployment に Next-Gen WAF エージェント用の一時ボリュームの定義を追加する

エージェント用の一時ボリュームは、Pod 内の他のコンテナで使用できるよう定義する必要があります。この例では、組み込みの emptyDir: {} ボリュームタイプを使用しています。

...
      volumes:
      # Define a volume where sigsci-agent will write temp data and share the socket file,
      # which is required with the root filesystem is mounted read only
      - name: sigsci-tmp
        emptyDir: {}

Network services

Security

Compute

Quick start

Building blocks

Integrations

Tutorials

Demos

Use Cases

Code Examples

Starter Kits

Next-Gen WAF エージェントを統合する

エージェントコンテナイメージを取得および更新する

`latest` コンテナイメージを使用する

バージョン管理されたコンテナイメージをご利用ください

コンテナイメージにカスタムタグを使用する

エージェントコンテナを設定する

エージェントの認証情報

エージェント一時ボリューム

Next-Gen WAFエージェントをEnvoyプロキシに統合する

Generic Envoy プロキシ

Envoy Proxy 設定を変更する

Deployment に Next-Gen WAF エージェント用の一時ボリュームの定義を追加する

Network services

Security

Compute

Quick start

Building blocks

Integrations

Tutorials

Demos

Use Cases

Code Examples

Starter Kits

Kubernetes Envoy

Next-Gen WAF エージェントを統合する

エージェントコンテナイメージを取得および更新する

latest コンテナイメージを使用する

バージョン管理されたコンテナイメージをご利用ください

コンテナイメージにカスタムタグを使用する

エージェントコンテナを設定する

エージェントの認証情報

エージェント一時ボリューム

Next-Gen WAFエージェントをEnvoyプロキシに統合する

Generic Envoy プロキシ

Envoy Proxy 設定を変更する

Deployment に Next-Gen WAF エージェント用の一時ボリュームの定義を追加する

関連コンテンツ

`latest` コンテナイメージを使用する