> ## 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.

# アーキテクチャ

> Vantage Kubernetes オペレーター、Vantage カスタムリソース、ArgoCD がどのように連携して Vantage 3.0 セルフホスト型 のインストール、設定、更新を行うかを説明します。

Vantage 3.0 セルフホスト型 は、Kubernetes オペレーター、ユーザー向けの単一のカスタムリソース (`Vantage`) 、および ArgoCD の 3 つのコンポーネントを中心に構成されています。目的のインストール内容を記述した `Vantage` オブジェクトを適用すると、オペレーターはそのリソースに合致するようにインストール状態をリコンシルし、コンポーネントごとの同期は ArgoCD に委ねます。このページでは、これらの構成要素を概念的に説明します。field レベルの詳細については、[API リファレンス](/ja/vantage/self-hosted/v3.0/api-reference) を参照してください。

<div id="why-this-pattern">
  ## なぜこのパターンなのか
</div>

Vantage 2.7 セルフホスト型では、ABBYY が提供する Ansible プレイブックと Azure CLI スクリプトを使用して、アプリケーションとそれを支えるインフラストラクチャの両方を一括でインストールしていました。この方式は 3.0 ではサポートされていません。3.0 のオペレーターでは、責務が分離されています。

* **Infrastructure**: オペレーターの対象外であり、お客様がプロビジョニングします。ABBYY は 3.0 向けのプロビジョニング自動化を提供していません。
* **Application**: `Vantage` リソースで宣言的に記述されます。オペレーターは、Vantage Core コンポーネントの依存関係の解決、アーティファクトの移行、ArgoCD による整合性の維持を処理します。

ArgoCD、使用している service mesh や ingress controller、secrets 連携、monitoring スタックなど、Vantage が依存するサードパーティ ソフトウェアは、そのどちらにも含まれません。これらは、Vantage をインストールする前にお客様自身でインストールする必要があります。

その結果、アップグレードは `vantage-operator` と `vantage-selfhosted` Helm チャートの対応する新しいバージョンをインストールすることで実行されます。

<div id="the-vantage-custom-resource">
  ## `Vantage` カスタムリソース
</div>

CRD は `vantage.abbyy.com/v1alpha1` に登録されています。最小構成のリソースは次のとおりです (例示用です。完全な仕様については [API リファレンス](/ja/vantage/self-hosted/v3.0/api-reference) を参照してください) :

```yaml theme={null}
apiVersion: vantage.abbyy.com/v1alpha1
kind: Vantage
metadata:
  name: vantage
  namespace: vantage
spec:
  dnsRecord: vantage.example.com
  mailFrom: noreply@example.com
  platformAdminEmail: admin@example.com
  vantageVersion: "3.0.x"
  secrets:
    azure:
      keyVaultName: mykeyvault
      tenantId: 00000000-...
      clientId: 00000000-... # Key Vault 読み取りアクセス権を持つ UAMI のクライアント ID
      identityMode: workloadIdentity # workloadIdentity (デフォルト) | podIdentity | vmManagedIdentity
  smtp:
    host: smtp.example.com
    port: 587
  workloads:
    configMap: vantage-workloads
    metadataTemplateKey: metadata
    secretsKey: secrets
    workloadsKey: workloads
```

`spec.secrets` は必須で、プロバイダー (`azure` または `kubernetes`) は必ず 1 つだけ指定する必要があります。`spec.smtp` は任意です。省略すると、デフォルトの SendGrid メールプロバイダーが使用されます (`sendgridApiKey` はシークレットプロバイダー経由で指定してください) 。サポートされているプロバイダーについては、[シークレットと Key Vault](/ja/vantage/self-hosted/v3.0/secrets-and-keyvault) を参照してください。

実際には、これらのほとんどは `vantage-selfhosted` Helm チャートで設定します。[Azure](/ja/vantage/self-hosted/v3.0/providers/azure) または [自己管理型 Kubernetes](/ja/vantage/self-hosted/v3.0/providers/self-managed) を参照してください。

<div id="key-concepts">
  ## 基本概念
</div>

<div id="workloads-configmap">
  ### ワークロード ConfigMap
</div>

`spec.workloads` は、Vantage の特定のバージョンを構成するチャートとイメージのマニフェストを含む `ConfigMap` をオペレーターが参照するよう指定します。オペレーターはこのマニフェストを読み取り、OCI 移行を実行してアーティファクトを使用中のレジストリにコピーした後、各コンポーネントの ArgoCD `Application` マニフェストを生成します。この ConfigMap は、ABBYY が Vantage の各リリースの一部としてビルドし、公開しています。

<div id="secrets-and-certificates">
  ### シークレットと証明書
</div>

オペレーターはシークレットを直接保存しません。サポートされているシークレットプロバイダーは 2 つあり (Secrets Store CSI driver 経由の Azure Key Vault と、既存の Kubernetes `Secret` リソース) 、インストールごとに設定できるのはそのうち 1 つのみです。サポートされているプロバイダー、ID モード、エイリアスの完全な一覧については、[シークレットと Key Vault](/ja/vantage/self-hosted/v3.0/secrets-and-keyvault) を参照してください。

<div id="oci-migration">
  ### OCI 移行
</div>

`spec.ociMigration` は、インストール前に、構成済みの 1 つ以上のソースレジストリから宛先レジストリへ artifacts をコピーする 1 回限りの job を定義します。移行が完了すると、それ以降のすべてのコンポーネントのプル元はお客様自身のレジストリになります。ArgoCD は、お客様が設定したリポジトリ Connection を介して、そのレジストリからコンポーネントのチャートをプルします。宛先の authentication では、認証なし、basic auth、または Azure RBAC を使用する Azure Workload Identity をサポートしています。workload には、Kubernetes image pull Secrets、または Azure の場合は AKS managed identity に付与された `AcrPull` を通じたプルアクセスも必要です。[Azure の image pull アクセス](/ja/vantage/self-hosted/v3.0/providers/azure#image-pull-access) または [セルフマネージド レジストリ アクセス](/ja/vantage/self-hosted/v3.0/providers/self-managed#configure-registry-access) を参照してください。

<div id="skill-installation">
  ### Skill のインストール
</div>

Skill は、オペレーター が生成する ArgoCD アプリケーションではなく、インストール用の名前空間で個別の Kubernetes job によってインストールされるため、ArgoCD には Skill のインストール進行状況は表示されません。`Vantage` resource は、job がまだ実行中でも `Ready` を報告することがあり、その間も Vantage は使用できます。監視コマンドは [ライフサイクル](/ja/vantage/self-hosted/v3.0/lifecycle#skill-installation-runs-separately) にあります。

<div id="runtime-contract">
  ## ランタイムコントラクト
</div>

オペレーターのランタイムコントラクト (`Vantage` resource をどのように処理するか、どの condition を返すか、また再試行を強制する方法) については、この概念的な概要とは別に記載されています。詳しくは [ライフサイクル](/ja/vantage/self-hosted/v3.0/lifecycle) を参照してください。

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

<CardGroup cols={2}>
  <Card title="API リファレンス" icon="code" href="/ja/vantage/self-hosted/v3.0/api-reference">
    spec とステータスの各プロパティを、field ごとに参照できます。
  </Card>

  <Card title="ライフサイクル" icon="arrows-rotate" href="/ja/vantage/self-hosted/v3.0/lifecycle">
    リコンシルのフェーズ、ステータス条件、再試行を強制する方法。
  </Card>

  <Card title="Helm チャートの値" icon="screwdriver-wrench" href="/ja/vantage/self-hosted/v3.0/helm-chart">
    オペレーター と Vantage チャートで使用できる、すべての Helm 値のリファレンス。
  </Card>

  <Card title="トラブルシューティング" icon="stethoscope" href="/ja/vantage/self-hosted/v3.0/troubleshooting">
    オペレーター、ArgoCD、secrets、データベース、ingress、mesh に関する一般的な問題を診断します。
  </Card>
</CardGroup>