> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# シークレットと Key Vault

> Vantage 3.0 セルフホスト型がシークレットと証明書を読み込む方法: Azure Key Vault から Secrets Store CSI driver 経由で読み込むか、既存の Kubernetes Secret リソースから読み込みます。

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

<div id="supported-providers">
  ## サポートされているプロバイダー
</div>

| プロバイダー                 | 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 のワークロードは、値の取得元に関係なく、エイリアスでシークレットを参照します。プロビジョニングを計画するには、以下の [エイリアス一覧](#secret-aliases) を参照してください。

<div id="azure-key-vault-provider">
  ## Azure Key Vault プロバイダー
</div>

```yaml theme={null}
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
```

<div id="identity-modes">
  ### Identity モード
</div>

| モード                          | 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 への読み取りアクセス権が必要です。                                               |

<div id="how-it-works">
  ### 仕組み
</div>

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                                     │
└──────────────────────────────────────────────────┘
```

1. オペレーターは、チャートごとに `SecretProviderClass` (SPC) を生成し、そのチャートに必要な Key Vault エイリアスと、それぞれをチャートごとの Kubernetes `Secret` 内のキーにどのようにマップするかを定義します。
2. pod が SPC のボリュームをマウントすると、Secrets Store CSI driver は `identityMode` で選択された ID として認証を行い、Key Vault から指定されたオブジェクトを取得して、SPC の `secretObjects` 機能を通じてチャートごとの Kubernetes `Secret` に同期します。
3. チャートの 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 プラグイン](https://azure.github.io/secrets-store-csi-driver-provider-azure) は、Vantage より前にクラスターへインストールしておく必要があります。[前提条件](/ja/vantage/self-hosted/v3.0/prerequisites)を参照してください。

<div id="per-chart-resources">
  ### チャートごとのリソース
</div>

シークレットを使用する各 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 が参照するのは、そのチャートが実際に必要とするエイリアスだけです。

<div id="service-accounts-and-identity-scope">
  ### Service accounts and identity scope
</div>

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

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

<div id="kubernetes-secrets-provider">
  ## Kubernetes Secrets のプロバイダー
</div>

```yaml theme={null}
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 に直接接続することはありません。

<div id="postgresql-and-per-service-secrets">
  ### PostgreSQL とサービスごとの Secrets
</div>

PostgreSQL を使用するには、`vantage.databaseProvider: PostgreSQL` を設定します。各サービスには、それぞれ別の論理データベースを指定する接続文字列が必要です。1 つのデータベースを共有すると、サービス間でマイグレーション状態が衝突します。

ワークロードによっては、名前が一意の接続文字列キーを読み取るため、1 つの Secret を共有できます。一方、汎用キー `Database__ConnectionString` を読み取るワークロードもあります。その場合は、各サービスごとに個別の Secret を作成し、`vantage.secrets.kubernetes.objects` でそのエイリアスをマップします。

```yaml theme={null}
vantage:
  databaseProvider: PostgreSQL
  reportingEnabled: false
  secrets:
    kubernetes:
      objects:
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions
        workspaceDatabaseConnectionString:
          secretName: vantage-db-workspace
```

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

```yaml theme={null}
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` のままにしてください。

<div id="secret-aliases">
  ## シークレットのエイリアス
</div>

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

<div id="platform">
  ### プラットフォーム
</div>

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

<div id="storage">
  ### ストレージ
</div>

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

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

<div id="databases">
  ### データベース
</div>

データベースごとに、それぞれ異なる 接続文字列 を 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`                                           |

<div id="oauth">
  ### OAuth
</div>

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

† `sendgridApiKey` は、SMTP を使用しない場合にのみ必須です。[既知の制限事項](/ja/vantage/self-hosted/v3.0/known-limitations#smtp-supports-basic-auth-only)を参照してください。

<div id="certificate-aliases">
  ## 証明書エイリアス
</div>

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 名を再マッピングします。

<div id="naming-and-remapping">
  ## 命名と再マッピング
</div>

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

プロビジョニング プロセスで別の名前を使用している場合は、シークレット設定で `objects` マッピングを指定してください。

```yaml theme={null}
vantage:
  secrets:
    azure:
      # ...
      objects:
        sendgridApiKey:
          objectName: my-sendgrid-key            # Azure Key Vault オブジェクト名
        reportingDatabaseConnectionString:
          objectName: vantage-reporting-conn
```

```yaml theme={null}
vantage:
  secrets:
    kubernetes:
      objects:
        sendgridApiKey:
          secretName: my-sendgrid-secret         # Kubernetes Secret 名
        reportingDatabaseConnectionString:
          secretName: my-reporting-secret
```

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

<div id="required-permissions">
  ## 必須の権限
</div>

**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 はそれらを直接使用します。

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

<div id="whats-next">
  ## 次のステップ
</div>

<CardGroup cols={2}>
  <Card title="前提条件" icon="list-check" href="/ja/vantage/self-hosted/v3.0/prerequisites">
    インストール方法を問わず必要となる、クラスターレベルおよび外部サービスの要件。
  </Card>

  <Card title="Azure へのインストール" icon="cloud" href="/ja/vantage/self-hosted/v3.0/providers/azure">
    Azure Key Vault の構成項目と、インストール手順を順を追って説明します。
  </Card>

  <Card title="セルフマネージド Kubernetes" icon="server" href="/ja/vantage/self-hosted/v3.0/providers/self-managed">
    ネイティブな Kubernetes Secrets と PostgreSQL の構成。
  </Card>
</CardGroup>