1. Home
  2. Next-Gen WAF
  3. セットアップと設定
  4. Kubernetes

Kubernetes エージェント + モジュール

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

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 コンテナイメージの依存関係をすべて含まず、sigsci-agent のみを含む公式の signalsciences/sigsci-agent-slim コンテナイメージも提供しています。これは Docker Hub でも利用可能です。利用方法は通常の sigsci-agent コンテナイメージと同じですが、イメージのデバッグが難しくなる場合があります。

独自のイメージをビルドしたい場合や、イメージをカスタマイズする必要がある場合は、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：エージェントアクセスキーは、エージェントがどのサイト（ワークスペースとも呼ばれる）用に構成されているかを識別します。

  • SIGSCI_SECRETACCESSKEY : Agent Secret Key はエージェントを認証・認可するための共有秘密鍵です。

これらの値は非常に機密性が高いため、Kubernetes の組み込み secrets 機能を使用することを推奨します。この構成では、エージェントは Deployment 設定内にハードコードされた値を読み取るのではなく、Secret データから値を取得します。これにより、エージェント認証情報のローテーションも、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 内のさまざまなストアにシークレットを保持します。このガイドでは、例として汎用のシークレットストアを使用していますが、同等のストアであればどれでも使用できます。エージェントのシークレットは、以下の例のような YAML を使用して汎用のシークレットストアに追加できます。

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 通信用のソケットファイルのような一時ファイルや、位置情報データなどの定期的に更新されるファイルを書き込む必要があります。

読み取り専用のルートファイルシステムでこれを実現するには、書き込み可能なボリュームをマウントする必要があります。この書き込み可能なボリュームは、同じ Pod 内の他のコンテナに 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)

Web アプリケーションと Next-Gen WAF モジュールがインストールされた Next-Gen WAF エージェント

このデプロイ例では、helloworld アプリケーションを設定し、RPC 経由で sigsci-agent を使用するように設定します。また、sigsci-agent コンテナをサイドカーとしてデプロイして、これらの RPC リクエストを処理します。

このデプロイタイプで Next-Gen WAF を設定するには、次のことを行う必要があります。

  • アプリケーションを修正して、適切な Next-Gen WAF モジュールを追加し、RPC 経由で sigsci-agent と通信するように設定します。

  • RPC モードで設定された Pod に sigsci-agent コンテナを追加します。

  • emptyDir{} ボリュームを追加し、sigsci-agent が一時データを書き込む場所として使用し、RPC アドレスを共有します。

アプリケーションコンテナを修正および設定する

helloworld の例は、sigsci-agent との RPC による通信を可能にするために既に修正された言語ベースのモジュール (Golang) です (そのように設定されている場合) 。この設定は、helloworld の例示アプリケーションに渡される引数によって次のように行われます。

  • リスニングアドレス (デフォルトは localhost:8000)。

  • オプションの Next-Gen WAF エージェントの RPC アドレス (デフォルトでは sigsci-agent は使用しません)。他の言語ベースのモジュールも同様です。Web サーバーベースのモジュールでは、Next-Gen WAF モジュールをコンテナに追加する必要があります。

この helloworld アプリケーションが sigsci-agent で動作するためには、sigsci-agent アドレスが2番目のプログラム引数として設定され、sigsci-tmp ボリュームがマウントされてソケットファイルに書き込めるようにする必要があります。

...
      containers:
      # Example helloworld app running on port 8000 against sigsci-agent via UDP /sigsci/tmp/sigsci.sock
      - name: helloworld
        image: signalsciences/example-helloworld:latest
        imagePullPolicy: IfNotPresent
        args:
          # Address for the app to listen on
          - localhost:8000
          # Address sigsci-agent RPC is listening on
          - /sigsci/tmp/sigsci.sock
        ports:
        - containerPort: 8000
        volumeMounts:
        # Shared mount with sigsci-agent container where the socket is shared via emptyDir volume
        - name: sigsci-tmp
          mountPath: /sigsci/tmp

エージェントコンテナをサイドカーとして追加および設定する

sigsci-agent コンテナはデフォルトで RPC モードになり、/sigsci/tmp/sigsci.sock に Unix ドメインソケット (UDS) ファイルが配置されます。このソケットファイルをキャプチャするには、/sigsci/tmp に一時的なボリュームがマウントされている必要があり、Pod と共有されていなければなりません。Web アプリケーションは、この UDS ソケットを介して sigsci-agent と通信するように設定される必要があります。デプロイ YAML は、上記の例から修正し、2番目の引数を追加して /sigsci/tmp/sigsci.sock の sigsci-agent RPC アドレスを指定する必要があります。

ヒント : sigsci-agent RPC に TCP ベースのリスナーを使用することもできますが、パフォーマンス上の理由からお勧めしません。TCP が必要な場合 (または Windows などで UDS が使用できない場合)、RPC アドレスは UDS パスの代わりに ip:port または host:port として指定できます。この場合、ボリュームをアプリと共有する必要はありませんが、地理データなどの一時データを書き込む場所として sigsci-agent コンテナ用にボリュームを作成する必要があります。

sigsci-agent コンテナをサイドカーとして追加する

...
      containers:
      # Example helloworld app running on port 8000 against sigsci-agent via UDP /sigsci/tmp/sigsci.sock
      - name: helloworld
        image: signalsciences/example-helloworld:latest
        imagePullPolicy: IfNotPresent
        args:
          # Address for the app to listen on
          - localhost:8000
          # Address sigsci-agent RPC is listening on
          - /sigsci/tmp/sigsci.sock
        ports:
        - containerPort: 8000
        volumeMounts:
        # Shared mount with sigsci-agent container where the socket is shared via emptyDir volume
        - name: sigsci-tmp
          mountPath: /sigsci/tmp
      # Next-Gen WAF agent running in default RPC mode
      - name: sigsci-agent
        image: signalsciences/sigsci-agent:latest
        imagePullPolicy: Always
        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
        # If required (default is /sigsci/tmp/sigsci.sock for the container)
        #- name: SIGSCI_RPC_ADDRESS
        #  value: /path/to/socket for UDS OR host:port if TCP
        securityContext:
          # The sigsci-agent container should run with its root filesystem read only
          readOnlyRootFilesystem: true
        volumeMounts:
        # Default volume mount location for sigsci-agent writeable data
        # NOTE: Also change `SIGSCI_SHARED_CACHE_DIR` (default `/sigsci/tmp/cache`)
        #       if mountPath is changed, but best not to change.
        - name: sigsci-tmp
          mountPath: /sigsci/tmp

注 : 上記の sigsci-agent 設定は、sigsci 個のシークレットが上記のシステムセクションに追加されたことを前提としています。

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

最後に、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: {}

関連コンテンツ

Fastly
© Fastly 2026