Sveltos イベントフレームワークで ServiceAccount にフィールドを追加する方法

Posted at 2025-02-21

Kubernetesクラスター(バージョン1.30以上)で、ServiceAccountリソースに特定のフィールド（例: automountServiceAccountToken: false 等）を自動付与するには、Project Sveltosのイベント駆動フレームワーク（EventSourceとEventTrigger）を利用できます。SveltosのEventSourceで監視対象となるリソース種別（ServiceAccount）を定義し、EventTriggerでそのイベント発生時に適用する変更（追加フィールドのパッチ）を指定します。以下に、具体的な設定例と手順を示します。

前提条件と準備 (Prerequisites)

Sveltosの導入: 管理クラスタにSveltosコントローラをインストールしておきます。例えば、公式マニフェストを適用します (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community)。これによりEventSourceやEventTriggerなど必要なCRDが作成され、イベント管理機能（event-manager）が有効になります。
```
kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/<VERSION>/manifest/manifest.yaml
```
※<VERSION>には適切なバージョン番号（例: v0.46.1）を指定します。
クラスタの登録とラベル付け: Sveltosが管理対象とするクラスターを登録し、適用対象となるクラスタにラベルを付与します。例えば、env=productionというラベルでクラスターを登録しておけば、EventTriggerのsourceClusterSelectorでこのラベルを指定することで対象クラスタを選択できます (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community)。
```
# 例: "production"環境クラスタを登録しラベル付与
sveltosctl register cluster --namespace=<cluster-namespace> --cluster=<cluster-name> \
    --kubeconfig=<kubeconfig-file> --labels=env=production
```
上記により、管理クラスタ上に対象クラスタを表すリソース（例: SveltosCluster）が作成され、env=productionのラベルが付与されます (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community)。EventTriggerでこのラベルをマッチさせることで当該クラスタにのみ変更を適用できます。
権限: Sveltosコントローラ（event-manager）はServiceAccountの変更を行うため、管理対象クラスタ上でServiceAccountを読み書きできる権限を持っています。通常、Sveltosインストール時に適切なClusterRoleが設定されるため追加作業は不要ですが、万一を考え事前に確認してください。

以上の前提を満たしたら、イベント検出とパッチ適用の設定を行います。

EventSourceの設定例（ServiceAccountの監視定義）

まず、ServiceAccountに対するイベントを検知するEventSourceを定義します。EventSourceは「どのリソースのイベントを監視するか」を指定するCRDです。以下はServiceAccountリソースの作成/更新を監視するEventSourceの例です。

apiVersion: lib.projectsveltos.io/v1beta1
kind: EventSource
metadata:
  name: serviceaccount-events    # EventSourceの名前
spec:
  collectResources: true         # マッチしたリソース全文を収集（テンプレートで .Resource として参照可能にする） ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=The%20,management%20cluster%20for%20template%20instantiation))
  resourceSelectors:
  - group: ""                    # 空文字はCore APIグループを示す
    version: "v1"
    kind: "ServiceAccount"       # 監視対象リソース種別 ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=collectResources%3A%20true%20resourceSelectors%3A%20,version%3A%20v2%20aggregatedSelection%3A))

設定のポイント:

resourceSelectors: ここで監視対象とするリソース種別を指定します。上記では Core API グループの v1 に属する ServiceAccount を対象にしています（グループ名が空文字列""なのは、ServiceAccountがCore APIリソースだからです） (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。これによりServiceAccountの生成・削除・更新イベントが監視対象となります。
collectResources: trueを指定すると、イベント検出時にそのリソースの内容全体が管理クラスタに送信され、後述のテンプレート中で .Resource として参照できます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。フィールドを追加するパッチを当てる場合、既存のServiceAccountの情報（名前や名前空間、既存フィールドなど）をテンプレート内で利用したいのでtrue推奨です。
- 補足: collectResources: falseの場合は .Resource は使えず、代わりに基本的なメタデータ（kind, namespace, nameなど）のみを持つ.MatchingResources参照になります (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。今回はServiceAccountに具体的フィールドを追加するので、.Resourceとして詳細にアクセスできるようtrueに設定しています。
フィルタ条件の拡張（必要に応じて）: すべてのServiceAccountを対象にせず特定の条件に合致する場合のみトリガーしたい場合、aggregatedSelectionフィールドでLuaスクリプトによる追加フィルタリングが可能です (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。例えば「automountServiceAccountTokenフィールドを持たないServiceAccountのみ対象にする」等のロジックをLuaで記述できます。ただし設定が複雑になるため、まずは基本形を動かしてから必要に応じて追加すると良いでしょう。

EventSourceを作成すると、Sveltosは管理対象クラスタ内のServiceAccountリソースを監視し、変更があればイベントとして検出する準備が整います。

EventTriggerの設定例（適用対象クラスタとパッチの指定）

次に、上記EventSourceで検出されたイベントに応じて実行するアクション（パッチの適用）を定義するEventTriggerを作成します。EventTriggerでは「どのEventSourceに対して」「どのクラスタに」「何を適用するか」を宣言します (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。以下はEventTriggerの例です。

apiVersion: lib.projectsveltos.io/v1beta1
kind: EventTrigger
metadata:
  name: add-sa-field-trigger           # EventTriggerの名前
spec:
  eventSourceName: serviceaccount-events       # 紐づけるEventSource名 ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=sourceClusterSelector%3A%20matchLabels%3A%20env%3A%20fv%20eventSourceName%3A,policy%20namespace%3A%20default%20kind%3A%20ConfigMap))
  sourceClusterSelector:
    matchLabels:
      env: production                  # 適用対象クラスタのラベルセレクタ（例：env=production） ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=sourceClusterSelector%3A%20matchLabels%3A%20env%3A%20fv%20eventSourceName%3A,policy%20namespace%3A%20default%20kind%3A%20ConfigMap))
  oneForEvent: true                    # リソース毎に個別のパッチを適用 ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=The%20EventTrigger%20,or%20one%20for%20all%20resources)) ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=two%20NetworkPolicies%20will%20be%20created%2C,one%20per%20Service))
  policyRefs:
  - kind: ConfigMap
    namespace: default
    name: sa-patch-template            # 適用するリソース定義を格納したConfigMapの参照 ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=oneForEvent%3A%20true%20policyRefs%3A%20,apiVersion%3A%20v1%20kind%3A%20ConfigMap%20metadata))

設定のポイント:

eventSourceName: 対応するEventSourceの名前を指定します。ここでは先ほど作成したserviceaccount-eventsを参照しています。このEventSourceで検出されたイベントがトリガーとなります (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。
sourceClusterSelector: イベントに反応して変更を適用する対象クラスタをラベルで選択します (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。上記例ではenv: productionというラベルを持つクラスタ群が対象です。単一クラスタの場合でも、そのクラスタに任意のラベル（例: env=production）を付与しここで指定することで対象に含めます。
（補足: Sveltosでは管理クラスタ上に登録された各クラスターリソースにラベルを付与し、それをセレクタでマッチさせることでデプロイ対象クラスタを動的に選択します (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community)。）
oneForEvent: trueにすると、検出されたリソースごとに別個のアクションを実行します (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。具体的には、対象リソースごとに個別のClusterProfile（内部的なデプロイ単位）が生成され、各リソースに対するパッチが適用されます。ServiceAccountごとに異なる名前空間・名前がありますので、通常この値はtrueで問題ありません（各ServiceAccountごとにフィールド追加を適用）。
falseにすると、テンプレートを用いず単一のアドオンをデプロイするケースに向きます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。例えば「あるイベントが一度でも起きたクラスタにKyvernoをインストールする」等、リソース個別ではない処理の場合はfalseを選びます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。今回のようにテンプレートによるリソースごとの変更を行う場合はtrueとします。
policyRefs: イベント発生時に適用するリソース定義への参照を指定します (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。SveltosではConfigMapやSecretに実際のKubernetesマニフェスト（テンプレート可）を格納し、それを参照することでリソースをデプロイします。上記ではdefaultネームスペースに作成するConfigMap（名前:sa-patch-template）を参照に指定しています。このConfigMap内に、ServiceAccountへフィールドを追加するためのYAMLテンプレートを記述します。policyRefsはリストなので、複数のリソーステンプレートをまとめて適用することも可能です。

EventTriggerを適用すると、Sveltosのevent-managerが起動している管理クラスタ上で、指定EventSourceの条件にマッチするイベントが検出された際に、対応するConfigMapの内容をテンプレート展開して対象クラスタへリソースをデプロイする動作が有効化されます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。

ServiceAccountにフィールドを追加するテンプレートYAML例

次に、EventTriggerから参照されるConfigMap (sa-patch-template) の中身を定義します。このConfigMapには、ServiceAccountに特定フィールドを追加するためのテンプレート化されたマニフェストを格納します。重要な点は、ConfigMapに特別なアノテーションを付与してSveltosにテンプレートとして認識させることです (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。

以下にConfigMapの例と、そのdataフィールド内に記述するYAMLテンプレートを示します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: sa-patch-template
  namespace: default
  annotations:
    projectsveltos.io/instantiate: "ok"  # SveltosにこのConfigMap内容をテンプレートとして実体化させる指示 ([Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation](https://projectsveltos.github.io/sveltos/events/addon_event_deployment/#:~:text=namespace%3A%20default%20annotations%3A%20projectsveltos,io%2Fv1))
data:
  patch-serviceaccount.yaml: |           # 好きなキー名でテンプレートを格納
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: {{ .Resource.metadata.name }}
      namespace: {{ .Resource.metadata.namespace }}
    {{- /* 既存のServiceAccountの名前・ネームスペースをそのまま利用 */ -}}
    {{- /* 以下に追加したいフィールドを指定 */}}
    automountServiceAccountToken: false

テンプレートYAMLのポイント:

.Resource.metadata.name / .Resource.metadata.namespace: EventSourceでcollectResources: trueを指定したことで、テンプレート内で.Resourceオブジェクトとしてイベント発生元のServiceAccount本体にアクセスできます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。上記では、そのメタデータ（名前と名前空間）を利用して、同名同NamespaceのServiceAccountリソースをテンプレート出力しています。これにより、「イベント検出されたServiceAccount自身」を更新するYAMLが生成されます。
automountServiceAccountToken: false: 追加したいフィールドを記述します。この例ではセキュリティ強化のため、ServiceAccountのトークン自動マウントを無効化するフィールドを追加しています。
※注意: ServiceAccountリソースではautomountServiceAccountTokenやimagePullSecrets等のフィールドはmetadata直下（トップレベル）に配置する仕様です (Configure Service Accounts for Pods - Kubernetes)。テンプレート中でもこの位置にフィールドを記述してください。誤ってspec:下に入れないよう注意します。
既存フィールドの維持: テンプレートでは上記のように追加フィールドのみ記述しています。Sveltosはこのテンプレートを適用する際、既存ServiceAccountリソースとマージする形で適用します（kubectl applyに近い動作）。そのため、元のServiceAccountに他のフィールド（例: secretsやimagePullSecretsなど）があっても、テンプレート側に記述が無ければ削除されることは基本的にありません（差分適用） (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。必要に応じて、既存のシークレット参照等も残したい場合は、テンプレート内で.Resource.secretsや.Resource.imagePullSecretsをループ展開して引き継ぐことも可能です。
```
  secrets:
  {{`{{- range $s := .Resource.secrets -}}`}}
    - name: {{`{{ $s.name }}`}}
  {{`{{- end -}}`}}
```
上記のように記述すれば、元のServiceAccountに紐づくSecrets一覧も維持できます。同様にimagePullSecretsもテンプレート展開可能です。もっとも、Kubernetes 1.24以降ではデフォルトのトークンSecretは自動作成されなくなっており（必要時に自動生成）、1.30ではレガシートークンのクリーンアップ機能もGAになっています (Kubernetes 1.30 release notes - Container Service ... - Alibaba Cloud) (Kubernetes 1.30 Release Notes - 华为云)。このため、新規ServiceAccount作成時点ではsecretsフィールドは空のことが多く、シークレット維持の問題は少ないでしょう。
projectsveltos.io/instantiate: "ok" アノテーション: このアノテーションが付与されたConfigMapは、Sveltosによってテンプレートとして扱われます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。EventTriggerから参照された際に中身をそのままデプロイするのではなく、{{ }}で囲まれたテンプレート変数を評価し実体化した上でリソース作成/更新が行われます。必ずこのアノテーションを付けてください。

ConfigMapを作成（kubectl apply -f）し、前述のEventTriggerでpolicyRefsとして参照設定しておけば準備完了です。

適用の流れと動作確認

以上で設定は揃いました。実際にEventSource・EventTrigger・ConfigMapを作成すると、Sveltosのイベントマネージャが次のように動作します。

イベント検出: 管理対象クラスタでServiceAccountが新規作成または更新されると、Sveltosはそのイベントを検知し、対応するEventSource (serviceaccount-events)の条件と一致するか確認します。一致した場合、当該ServiceAccountリソース（の内容）が管理クラスタに送られ、EventReportという内部リソースが生成されます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。
テンプレート展開とClusterProfile生成: event-managerはEventReportを消費し、該当EventTrigger (add-sa-field-trigger)を見つけます。すると以下の処理が自動で行われます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation):
- 指定されたConfigMap (sa-patch-template)をもとに新しいConfigMapを内部的に作成します（管理クラスタ内のprojectsveltos Namespaceに配置）。この新しいConfigMapには、テンプレート内の変数がイベント発生元のServiceAccount情報で置き換えられた具体的なマニフェストが格納されます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。例えば{{ .Resource.metadata.name }}は実際のServiceAccount名（例: defaultなど）に置換され、automountServiceAccountToken: falseフィールドを含む完全なServiceAccount定義YAMLになります。
- 次に、そのマニフェストを適用するためのClusterProfileリソースが自動生成されます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。ClusterProfileはSveltosにおける「このクラスタにこれらのリソースを適用する」という指示を表すカスタムリソースです。イベントごとに生成されたClusterProfileには、先ほど生成した具体的マニフェスト（ServiceAccountパッチ）が紐づけられ、対象クラスタ（env=productionのラベルで指定）への適用が指示されます。
対象クラスタへの適用: Sveltosは生成されたClusterProfileに従って、対象クラスタ上にServiceAccountリソースをデプロイ/更新します。具体的には、既存のServiceAccountに対してkubectl apply相当の更新が行われ、テンプレートで追加したフィールドが付加されます (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。これにより、該当ServiceAccountのspecに望みのフィールドが追加されます。例えばautomountServiceAccountToken: falseが付与されたことを確認できます。
結果の検証: 実際に対象クラスタでServiceAccountを取得し、フィールドが追加されたことを確認します。例:
```
kubectl get serviceaccount <対象SA名> -n <対象Namespace> -o yaml
```
出力されたYAMLにautomountServiceAccountToken: false行が含まれていれば成功です。

Sveltos自体のステータスを確認するには、管理クラスタ上でEventTriggerやEventSourceのステータス、また自動生成されたClusterProfileをチェックできます。kubectl get eventtrigger,eventsources,eventreport -A等で関連リソースの一覧を見ることができます。また、sveltosctl show addonsコマンドで各クラスタに適用されたアドオンリソースを一覧できます (5-Step Approach: Dry Run Kubernetes Resources with ProjectSveltos - DEV Community) (5-Step Approach: Dry Run Kubernetes Resources with ProjectSveltos - DEV Community)。
自動クリーンアップ: なお、対象クラスタでServiceAccountが削除された場合、Sveltosは対応するClusterProfileおよび適用リソースを自動的にクリーンアップします (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)。これによりイベントに紐づくリソースの孤児化を防ぎます（もっとも今回のケースではServiceAccountそのものが削除されるため追加フィールドも同時になくなります）。

参考情報

Sveltos公式ドキュメント: Event Driven Addon Distribution（イベント駆動型アドオン配布） (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) – EventSource/EventTriggerの概要と使用例（NetworkPolicyテンプレート適用）
Sveltos公式ドキュメント: EventTrigger OneForEvent setting (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) – oneForEventフィールドの意味と動作例
Sveltos公式ドキュメント: Template ConfigMap Example (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) – ConfigMapにテンプレートを記述し.Resource変数でイベントリソース情報を参照する方法
Sveltos開発者ブログ: Kubernetes on Autopilot: Event-Driven Automation Across Clusters (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community) (Kubernetes on Autopilot: Event-Driven Automation Across Clusters - DEV Community) – Sveltosのインストール方法とクラスタ登録例（マルチクラスタ環境でのイベント自動化解説）
その他: Kubernetes公式ドキュメント「ServiceAccountの構成方法」 (Configure Service Accounts for Pods - Kubernetes)（ServiceAccountマニフェストでのautomountServiceAccountToken: false指定例）、Kubernetes 1.30リリースノート（ServiceAccountトークンのクリーンアップ機能） (Kubernetes 1.30 release notes - Container Service ... - Alibaba Cloud) (Kubernetes 1.30 Release Notes - 华为云)なども参考になります。

以上の設定により、Sveltosを用いてKubernetesクラスタ内のServiceAccountに自動的にフィールドを追加する仕組みを構築できます。公式ドキュメントやサンプルコード (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation) (Event Driven Addon Distribution - Project Sveltos - Projectsveltos Documentation)も参考にしつつ、自身の環境に合わせてリソース名やラベルを調整してください。これにより、手作業を介さずポリシーとなる設定を一貫して適用できるようになります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up