シークレットと Key Vault

Vantage 3.0 セルフホスト型では、pod の起動時に、すべてのデータベース接続文字列、API キー、TLS 証明書をシークレットプロバイダーから読み込みます。これらの値は values.yaml ファイルには一切保存されません。サポートされるプロバイダーは 2 種類で、インストールごとに vantage.secrets で必ず 1 つだけ設定します。

サポートされているプロバイダー

プロバイダー	Helm 値	説明
Azure Key Vault	`vantage.secrets.azure`	Azure Key Vault provider と連携する Secrets Store CSI Driver を使用します。オペレーターはチャートごとに `SecretProviderClass` をプロビジョニングし、ドライバーはシークレットをファイルとして pod にマウントします。
Kubernetes Secrets	`vantage.secrets.kubernetes`	既存の Kubernetes `Secret` リソースを直接使用します。外部のシークレット管理インフラストラクチャは不要です。

この 2 つのプロバイダーは、同じ シークレットエイリアス の仕様を共有しています。Vantage のワークロードは、値の取得元に関係なく、エイリアスでシークレットを参照します。プロビジョニングを計画するには、以下のエイリアス一覧を参照してください。

Azure Key Vault プロバイダー

vantage:
  secrets:
    azure:
      keyVaultName: mykeyvault
      tenantId: 00000000-0000-0000-0000-000000000000
      clientId: 00000000-0000-0000-0000-000000000000  # Key Vault 読み取りアクセス権を持つ UAMI のクライアント ID
      identityMode: workloadIdentity                   # workloadIdentity (デフォルト) | podIdentity | vmManagedIdentity

Identity モード

モード	CSI ドライバーの認証方法
`workloadIdentity` (default)	Azure Workload Identity。各チャートの ServiceAccount は、ここで `clientId` を指定するユーザー割り当てマネージド ID (UAMI) にフェデレーションされます。その UAMI には、そのチャートで使用するエイリアスの参照先となる Key Vault オブジェクトへの読み取りアクセス権が必要です。
`podIdentity`	従来の AAD Pod Identity バインディング。このモードは検証済みのシナリオではありません。使用する前に、ABBYY のアカウント担当チームにお問い合わせください。
`vmManagedIdentity`	VM に割り当てられたマネージド ID。UAMI のクライアント ID は `vantage.secrets.azure.userAssignedIdentityID` で指定します。この ID には Key Vault への読み取りアクセス権が必要です。

仕組み

Vantage は、Azure Key Vault provider とともに Secrets Store CSI driver を使用します。各チャートの SecretProviderClass は、それを使用する pod に CSI ボリュームとしてマウントされ、このマウントをきっかけに、ドライバーが値をチャートごとの Kubernetes Secret (SPC の secretObjects 機能) に同期します。pod はそれを envFrom とボリュームマウント経由で使用します。流れは次のとおりです:

┌──────────────────────┐
│  Azure Key Vault     │  顧客がプロビジョニングしたシークレット/証明書オブジェクト
└──────────┬───────────┘
           │ ① 設定済みのIDを使用して読み取り
           ▼
┌──────────────────────────────────────────────────┐
│  SecretProviderClass  (チャートごとに1つ)        │  オペレーターが作成
│  alias → Key Vault objectName                    │
│  alias → チャートごとのKubernetes Secretのキー   │
└──────────┬───────────────────────────────────────┘
           │ ② Secrets Store CSI driverが値を同期
           ▼
┌──────────────────────────────────────────────────┐
│  Kubernetes Secret  (チャートごとに1つ)          │  例: mail-helm-secrets
└──────────┬───────────────────────────────────────┘
           │ ③ envFrom (環境変数) および/または volumeMounts (ファイル)
           ▼
┌──────────────────────────────────────────────────┐
│  Vantage pod                                     │
└──────────────────────────────────────────────────┘

オペレーターは、チャートごとに SecretProviderClass (SPC) を生成し、そのチャートに必要な Key Vault エイリアスと、それぞれをチャートごとの Kubernetes Secret 内のキーにどのようにマップするかを定義します。
pod が SPC のボリュームをマウントすると、Secrets Store CSI driver は identityMode で選択された ID として認証を行い、Key Vault から指定されたオブジェクトを取得して、SPC の secretObjects 機能を通じてチャートごとの Kubernetes Secret に同期します。
チャートの pod は、チャートごとの Secret を使用します。
- ほとんどのシークレット は、envFrom を介して環境変数としてロードされます。
- 証明書 (authSigningTlsCrt など) も、volumeMounts を介してファイルとしてマウントされます (通常は /var/run/certs/ 配下) 。

シークレットの値は、チャートごとの Kubernetes Secret と、ランタイム時の pod の環境に存在するため、kubectl get secret から見えなくなるわけではありません。ただし、CSI driver が pod の起動時にそれらを設定するため、values.yaml、ArgoCD の差分、Git には現れません。 Secrets Store CSI driver と Azure Key Vault provider プラグインは、Vantage より前にクラスターへインストールしておく必要があります。前提条件を参照してください。

チャートごとのリソース

シークレットを使用する各 Vantage チャートには、それぞれ専用のリソース一式があります。

リソース	名前のパターン	用途
`SecretProviderClass`	`{chart}-secret-provider` (移行ジョブの場合は `{chart}-migr-secret-provider`)	そのチャートに必要な Key Vault エイリアスと、それらをチャートごとの Kubernetes `Secret` にどうマッピングするかを定義します。
`Secret`	`{chart}-secrets` (および `{chart}-migr-secrets`)	CSI ドライバーによって生成され、`envFrom` を介してチャートの pod にマウントされます。
Volume `Secret`s	`{chart}-secrets-volume-N`	ファイルとしてマウントする必要がある内容 (証明書など) のための、チャートごとの追加の `Secret` です。

このようにチャートごとに分けることで、Key Vault へのアクセスを最小権限に保てます。つまり、あるチャートの SPC が参照するのは、そのチャートが実際に必要とするエイリアスだけです。

Service accounts and identity scope

オペレーターは ServiceAccount リソースを作成したり、アノテーションを追加したりしません。各チャートは、標準の Helm 値を通じて独自の SA を提供します。SPC をマウントする各チャートの ServiceAccount を、vantage.secrets.azure.clientId で clientId を指定したユーザー割り当てマネージド ID (UAMI) とフェデレーションするのは、顧客の責任です。その ID には、チャートのエイリアスの参照先となる Key Vault オブジェクトへの読み取りアクセスが必要です。

Key Vault へのアクセスとイメージのプルアクセスは別の要件であり、同じ ServiceAccount に適用されることがあります。UAMI フェデレーション (このページ) はシークレットの読み取りを許可しますが、イメージのプル認証は行いません。プルを行うには、vantage.serviceAccountName で指定された ServiceAccount の imagePullSecrets にレジストリのプル用シークレットを追加するか、代わりに AKS の kubelet ID に AcrPull を付与してください。詳しくは、Image pull access を参照してください。

Kubernetes Secrets のプロバイダー

vantage:
  secrets:
    kubernetes:
      # objects:                           # オプション: デフォルトのシークレット名を上書きする
      #   sendgridApiKey:
      #     secretName: my-sendgrid-secret

チャートを実行する前に、インストール先の名前空間に Secret リソースを事前に作成しておいてください。objects が定義されていない場合は、デフォルトのシークレット名が使用されます。名前の異なるシークレットを参照するには、objects マッピング (エイリアスごとの secretName) を指定します。このプロバイダーでは、Secrets Store CSI driver もクラウドの Key Vault も必要ありません。値はクラスター内の Secret オブジェクトから直接読み取られます。事前チェック時に、オペレーターはシークレット構成を検証します。matched operator チャートと Vantage チャートは、Secret-reader ClusterRole をインストールし、それをオペレーターの ServiceAccount に Vantage リリースの名前空間内でのみバインドします。resourceNames で Secret へのアクセスを制限する場合は、デフォルトおよび上書き後のすべての Secret 名を含めてください。外部のシークレット管理システムは、引き続き信頼できる情報源として利用できます。たとえば、External Secrets Operator は HashiCorp Vault から Kubernetes Secrets を生成できます。Vantage が使用するのは、生成された Kubernetes Secrets のみであり、External Secrets や Vault に直接接続することはありません。

PostgreSQL とサービスごとの Secrets

PostgreSQL を使用するには、vantage.databaseProvider: PostgreSQL を設定します。各サービスには、それぞれ別の論理データベースを指定する接続文字列が必要です。1 つのデータベースを共有すると、サービス間でマイグレーション状態が衝突します。ワークロードによっては、名前が一意の接続文字列キーを読み取るため、1 つの Secret を共有できます。一方、汎用キー Database__ConnectionString を読み取るワークロードもあります。その場合は、各サービスごとに個別の Secret を作成し、vantage.secrets.kubernetes.objects でそのエイリアスをマップします。

vantage:
  databaseProvider: PostgreSQL
  reportingEnabled: false
  secrets:
    kubernetes:
      objects:
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions
        workspaceDatabaseConnectionString:
          secretName: vantage-db-workspace

マッピングされた各シークレットには同じキーが含まれていますが、データベース接続文字列はそれぞれ異なります。

apiVersion: v1
kind: Secret
metadata:
  name: vantage-db-subscriptions
  namespace: <install-namespace>
type: Opaque
stringData:
  Database__ConnectionString: "Host=<host>;Port=5432;Database=subscriptions;Username=<user>;Password=<password>;Ssl Mode=Require"

認証情報をソース管理にコミットせずに済むよう、シークレット管理システムを使用してこれらの Secrets を作成してください。接続文字列は、先頭・末尾・途中のいずれにも改行文字を含まない 1 行である必要があります。レポート機能は SQL Server でのみ使用できます。PostgreSQL を使用する場合は、reportingEnabled: false のままにしてください。

シークレットのエイリアス

以下のエイリアスは、Vantage のワークロードとお使いのシークレットプロバイダーとの間の取り決めです。Azure プロバイダーでは、最も簡単なのは、Key Vault シークレットの名前をエイリアスに合わせることです。どちらのプロバイダーでも、シークレット構成内の objects マッピングを使って名前を再マッピングできます。

プラットフォーム

Alias	説明
`sendgridApiKey`†	SendGrid の API key。`spec.smtp` を Configure しない限り必須です。
`redisConnectionString`	Redis の接続文字列。
`redisCacheConnectionString`	Redis キャッシュ / ロック / クライアントキャッシュ用の接続文字列。`redisConnectionString` を再利用できます。
`secretStorageUserKeyVaultUri`	シークレット保存に使用する Azure Key Vault の URI。同じ Key Vault を使用することも、別のものを使用することもできます (別にすることを推奨) 。

ストレージ

デフォルトの Azure Blob ストレージバックエンドを使用する場合にのみ必要です。spec.storage.custom が Kubernetes の StorageClass ベースのバックエンド (たとえば NFS) 用に設定されている場合、これらのエイリアスは使用されません。各エイリアスはストレージアカウントの接続文字列です。各ストレージ型の用途については、Vantage の基本システムドキュメントを参照してください。

エイリアス	説明
`storageArchiveConnectionString`	ストレージアカウントの接続文字列 (“archive”) 。
`storageLegacyTemporaryConnectionString`	ストレージアカウントの接続文字列 (“temporary (old)”) 。
`storageTemporaryConnectionString`	ストレージアカウントの接続文字列 (“temporary”) 。
`storagePermanentConnectionString`	ストレージアカウントの接続文字列 (“permanent”) 。
`storageStandardConnectionString`	ストレージアカウントの接続文字列 (“standard”) 。

データベース

データベースごとに、それぞれ異なる接続文字列を 1 つずつ設定します。データベース名はあくまで例です。接続文字列が正しいデータベースを指していれば、プロビジョニング処理で生成される名前であればどのようなものでも問題ありません。

エイリアス	データベース
`apiRegistryDatabaseConnectionString`	`apiregistry`
`auth2DatabaseConnectionString`	`auth`
`authIdentityDatabaseConnectionString`	`auth-identity`
`cronServiceDatabaseConnectionString`	`cron`
`documentSetStorageDatabaseConnectionString`	`documentset`
`mailDatabaseConnectionString`	`mail`
`securityAuditDatabaseConnectionString`	`security-audit`
`storageDatabaseConnectionString`	`storage`
`workflowDatabaseConnectionString`	`workflows`
`catalogStorageDatabaseConnectionString`	`catalogstorage`
`folderImportDatabaseConnectionString`	`folderimport`
`interactiveJobsDatabaseConnectionString`	`interactive-jobs`
`mailImportDatabaseConnectionString`	`mailimport`
`permissionsDatabaseConnectionString`	`permissions`
`reportingDatabaseConnectionString`	`reporting` (Columnstore Indexing をサポートしている必要があります) 。
`secretStorageDatabaseConnectionString`	`secretstorage`
`skillInfoDatabaseConnectionString`	`skillinfo`
`skillMonitorDatabaseConnectionString`	`skillmonitor`
`subscriptionDatabaseConnectionString`	`subscriptions`
`tokenManagementDatabaseConnectionString`	`tokenmanagement`
`transactionsDatabaseConnectionString`	`transactions`
`urlShortenerDatabaseConnectionString`	`urlshortener`
`workspaceDatabaseConnectionString`	`workspace`

OAuth

エイリアス	説明
`oAuthGoogleClientId`	OAuth Google クライアント ID。
`oAuthGoogleClientSecret`	OAuth Google クライアントシークレット。
`oAuthMicrosoftClientId`	OAuth Microsoft クライアント ID。
`oAuthMicrosoftClientSecret`	OAuth Microsoft クライアントシークレット。

† sendgridApiKey は、SMTP を使用しない場合にのみ必須です。既知の制限事項を参照してください。

証明書エイリアス

PEM エンコードされた TLS 関連データが 4 つ必要です。これらは、2 組のシークレットエイリアス (証明書 + 秘密鍵) として扱われます。Azure プロバイダーでは、Key Vault の証明書オブジェクトではなく、Key Vault シークレットとして保存してください。

Alias	Description
`authSigningTlsCrt`	認証署名用の PEM エンコード証明書 (`auth-signing` Key Vault 証明書から取得) 。
`authSigningTlsKey`	認証署名用の PEM エンコード秘密鍵。
`authDeactivatedTlsCrt`	非アクティブ化された認証トークン用の PEM エンコード証明書 (`auth-deactivated` Key Vault 証明書から取得) 。
`authDeactivatedTlsKey`	非アクティブ化された認証トークン用の PEM エンコード秘密鍵。

Azure プロバイダーでは、Key Vault に auth-signing と auth-deactivated という名前の自己署名証明書を 2 つ作成し (Common Name = Vantage の dnsRecord 値) 、続いて上記のエイリアス名に合わせて 4 つの Key Vault シークレットを作成するのが最も簡単です。Kubernetes プロバイダーでは、PEM データを含む Secret リソースを事前に作成します。既定の data キーは auth-signing-tls-crt、auth-signing-tls-key、auth-deactivated-tls-crt、auth-deactivated-tls-key です。objects マッピングを使用して Secret 名を再マッピングします。

命名と再マッピング

Azure プロバイダーでは、objects マッピングに記載されていないエイリアスについては、エイリアス自体が Key Vault オブジェクト名として使用されます (secret 型として取得) 。Key Vault オブジェクトの名前がすでにエイリアスと一致している場合、objects マッピングは不要です。Kubernetes プロバイダーでは、objects が定義されていない場合、デフォルトのシークレット名が使用されます。プロビジョニングプロセスで別の名前を使用している場合は、シークレット設定で objects マッピングを指定してください。

vantage:
  secrets:
    azure:
      # ...
      objects:
        sendgridApiKey:
          objectName: my-sendgrid-key            # Azure Key Vault オブジェクト名
        reportingDatabaseConnectionString:
          objectName: vantage-reporting-conn

vantage:
  secrets:
    kubernetes:
      objects:
        sendgridApiKey:
          secretName: my-sendgrid-secret         # Kubernetes Secret 名
        reportingDatabaseConnectionString:
          secretName: my-reporting-secret

エイリアスはAPIの取り決めであり、オブジェクト名は自由に決められます。

必須の権限

Azure Key Vault provider では、Secrets Store CSI driver が使用する ID に、上記に記載されているすべてのシークレットと証明書への 読み取り アクセスが必要です。

workloadIdentity (デフォルト) : vantage.secrets.azure.clientId に clientId が指定されているユーザー割り当てマネージド ID。
vmManagedIdentity: vantage.secrets.azure.userAssignedIdentityID にクライアント ID が指定されている ID。
podIdentity: 検証済みのシナリオではありません。これに依存する前に、ABBYY account team にお問い合わせください。

Kubernetes Secrets provider では、Key Vault やクラウド ID の権限は不要です。インストール先の名前空間に Secret リソースを事前に作成してください。Vantage はそれらを直接使用します。

CSI driver の workload ID (ここでのもの) は、クラスター内の他の workload が使用する workload ID (たとえば、monitoring 用にデプロイする in-mesh Prometheus。Vantage installer は Prometheus をデプロイしません) とは別です。同じ UAMI を使用することも、異なる UAMI を使用することもできます。

次のステップ

前提条件

インストール方法を問わず必要となる、クラスターレベルおよび外部サービスの要件。

Azure へのインストール

Azure Key Vault の構成項目と、インストール手順を順を追って説明します。

セルフマネージド Kubernetes

ネイティブな Kubernetes Secrets と PostgreSQL の構成。

Configuration

Lifecycle

Monitoring

Performance

Diagnostics

Migration

サポートされているプロバイダー

Azure Key Vault プロバイダー

Identity モード

仕組み

チャートごとのリソース

Service accounts and identity scope

Kubernetes Secrets のプロバイダー

PostgreSQL とサービスごとの Secrets

シークレットのエイリアス

プラットフォーム

ストレージ

データベース

OAuth

証明書エイリアス

命名と再マッピング

必須の権限

次のステップ

前提条件

Azure へのインストール

セルフマネージド Kubernetes

​サポートされているプロバイダー

​Azure Key Vault プロバイダー

​Identity モード

​仕組み

​チャートごとのリソース

​Service accounts and identity scope

​Kubernetes Secrets のプロバイダー

​PostgreSQL とサービスごとの Secrets

​シークレットのエイリアス

​プラットフォーム

​ストレージ

​データベース

​OAuth

​証明書エイリアス

​命名と再マッピング

​必須の権限

​次のステップ

前提条件

Azure へのインストール

セルフマネージド Kubernetes

サポートされているプロバイダー

Azure Key Vault プロバイダー

Identity モード

仕組み

チャートごとのリソース

Service accounts and identity scope

Kubernetes Secrets のプロバイダー

PostgreSQL とサービスごとの Secrets

シークレットのエイリアス

プラットフォーム

ストレージ

データベース

OAuth

証明書エイリアス

命名と再マッピング

必須の権限

次のステップ