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

# Azure

> Deploy Vantage 3.0 self-hosted on Azure Kubernetes Service with Azure Key Vault, the Secrets Store CSI driver, and Azure Workload Identity.

Azure is the validated provider for Vantage 3.0 self-hosted: Azure Kubernetes Service (AKS) with Azure Key Vault. This page is the complete vertical slice for installing on Azure: prerequisites, identity setup, the Helm install commands, and operational notes. Individual components offer Kubernetes-native alternatives where the CRD supports them, such as the [Kubernetes Secrets provider](/vantage/self-hosted/v3.0/secrets-and-keyvault#kubernetes-secrets-provider) and [custom storage](/vantage/self-hosted/v3.0/api-reference#vantagespecstoragecustom).

## Prerequisites

Before working through this page, confirm the [platform prerequisites](/vantage/self-hosted/v3.0/prerequisites) are in place: Kubernetes, ArgoCD, Helm, and the underlying SQL / Redis / SMTP / OCI registry / object storage services. The Azure-specific items below are layered on top.

| Component                                                                                                                | Tested version                                                          | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Azure Kubernetes Service (AKS)                                                                                           | 1.33.6                                                                  | The CRD and operator chart are installed into the cluster.                                                                                                                                                                                                                                                                                                                                                                           |
| Azure SQL                                                                                                                | 12.0.2000.8 (compatibility level 170, General Purpose Serverless Gen 5) | Backs the Vantage databases, one per connection-string alias (23 today). See [Database connection strings](#database-connection-strings).                                                                                                                                                                                                                                                                                            |
| Azure Managed Redis                                                                                                      | 7.4 (EnterpriseCluster)                                                 | Cache, locks, and client cache usage.                                                                                                                                                                                                                                                                                                                                                                                                |
| Azure Container Registry                                                                                                 | n/a                                                                     | Destination registry for OCI migration; your workloads pull Vantage images from it. Migration auth: no auth, basic auth, or Workload Identity + Azure RBAC. For image pulls, see [Image pull access](#image-pull-access).                                                                                                                                                                                                            |
| Azure StorageV2                                                                                                          | general purpose v2                                                      | Backs the five storage account connection strings (archive, temporary (old), temporary, permanent, standard). See [Storage account connection strings](#storage-account-connection-strings).                                                                                                                                                                                                                                         |
| Azure Key Vault                                                                                                          | n/a                                                                     | Holds every Vantage secret (including the PEM-encoded TLS materials) when using the Azure secrets provider. The identity selected by `identityMode` must have read access.                                                                                                                                                                                                                                                           |
| AKS Istio Add-on                                                                                                         | `asm-1-28`                                                              | An external ingress gateway must be deployed.                                                                                                                                                                                                                                                                                                                                                                                        |
| [Azure Key Vault Provider for Secrets Store CSI Driver](https://azure.github.io/secrets-store-csi-driver-provider-azure) | 1.7.2 (Helm chart 1.7.2)                                                | The CSI provider plugin that fetches secrets at pod startup.                                                                                                                                                                                                                                                                                                                                                                         |
| Azure Workload Identity                                                                                                  | n/a                                                                     | Federate each Vantage chart's ServiceAccount to a user-assigned managed identity with read access to that chart's Key Vault aliases. The operator does not create or annotate ServiceAccounts. Also used by the OCI migration job (Workload Identity + Azure RBAC auth) and the in-mesh Prometheus (Azure Monitor). See [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault#service-accounts-and-identity-scope). |
| AKS KEDA Add-on (optional, recommended)                                                                                  | `2.17.3-5`                                                              | Required for [KEDA](https://keda.sh/) autoscaling support.                                                                                                                                                                                                                                                                                                                                                                           |

Two more setup tasks must be done before you install. Both are covered below, after the install variables they reference: [Connect ArgoCD to your OCI registry](#connect-argocd-to-your-oci-registry) and [Image pull access](#image-pull-access).

## Azure Key Vault secrets

The Vantage operator addresses secrets by **alias**. The simplest setup on Azure is to create Key Vault secrets named to match each alias; if your provisioning process uses different names, supply an `objects` mapping under `vantage.secrets.azure` to remap them. The identity selected by `identityMode` (see [Install variables](#install-variables)) must have **read** access to every secret listed below.

The full alias inventory (Platform, Storage, Databases, OAuth) is documented in [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault#secret-aliases). The list below is the same set, reproduced here for the Azure install.

### Platform

| Alias                          | Description                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `sendgridApiKey`               | API key for SendGrid. Required unless you configure `spec.smtp`.                                                       |
| `redisConnectionString`        | Connection string for Redis.                                                                                           |
| `redisCacheConnectionString`   | Connection string for Redis cache / locks / client cache. May reuse `redisConnectionString`.                           |
| `secretStorageUserKeyVaultUri` | URI to the Azure Key Vault used for secret storage. May be the same vault or a separate one (separate is recommended). |

### Storage account connection strings

| Alias                                    | Description                                            |
| ---------------------------------------- | ------------------------------------------------------ |
| `storageArchiveConnectionString`         | Storage account connection string ("archive").         |
| `storageLegacyTemporaryConnectionString` | Storage account connection string ("temporary (old)"). |
| `storageTemporaryConnectionString`       | Storage account connection string ("temporary").       |
| `storagePermanentConnectionString`       | Storage account connection string ("permanent").       |
| `storageStandardConnectionString`        | Storage account connection string ("standard").        |

Defer to the base Vantage documentation for what each storage type means.

### Database connection strings

One alias per distinct database. The database names below are illustrative; use whatever your provisioning process produces, as long as the connection string points to the right database.

| Alias                                        | Database                                         |
| -------------------------------------------- | ------------------------------------------------ |
| `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` (must support Columnstore Indexing). |
| `secretStorageDatabaseConnectionString`      | `secretstorage`                                  |
| `skillInfoDatabaseConnectionString`          | `skillinfo`                                      |
| `skillMonitorDatabaseConnectionString`       | `skillmonitor`                                   |
| `subscriptionDatabaseConnectionString`       | `subscriptions`                                  |
| `tokenManagementDatabaseConnectionString`    | `tokenmanagement`                                |
| `transactionsDatabaseConnectionString`       | `transactions`                                   |
| `urlShortenerDatabaseConnectionString`       | `urlshortener`                                   |
| `workspaceDatabaseConnectionString`          | `workspace`                                      |

### OAuth

| Alias                        | Description                    |
| ---------------------------- | ------------------------------ |
| `oAuthGoogleClientId`        | OAuth Google client ID.        |
| `oAuthGoogleClientSecret`    | OAuth Google client secret.    |
| `oAuthMicrosoftClientId`     | OAuth Microsoft client ID.     |
| `oAuthMicrosoftClientSecret` | OAuth Microsoft client secret. |

## Azure Key Vault TLS secrets

The following PEM-encoded TLS materials must be stored as **secrets** in the Azure Key Vault (not Key Vault certificate objects). The identity selected by `identityMode` must have read access to all four secret aliases.

| Alias                   | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `authSigningTlsCrt`     | PEM-encoded certificate for auth signing.            |
| `authSigningTlsKey`     | PEM-encoded private key for auth signing.            |
| `authDeactivatedTlsCrt` | PEM-encoded certificate for auth deactivated tokens. |
| `authDeactivatedTlsKey` | PEM-encoded private key for auth deactivated tokens. |

The simplest approach is to create two self-signed certificates in Key Vault named `auth-signing` and `auth-deactivated` (Common Name = your Vantage `dnsRecord` value), then create four Key Vault secrets named to match the aliases above. If you use different names, provide an `objects` mapping in your secrets configuration.

For the conceptual model behind how the Secrets Store CSI driver surfaces these into pods, see [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault).

## Install variables

Have these values on hand before running the install commands:

| Variable                                                    | Description                                                                                                                    |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `$operator_namespace`                                       | Namespace to install the Vantage operator into.                                                                                |
| `$install_namespace`                                        | Namespace to install Vantage into. Any namespace; commonly `app`.                                                              |
| `$operator_version`                                         | Version of the `vantage-operator` Helm chart.                                                                                  |
| `$selfhosted_version`                                       | Version of the `vantage-selfhosted` Helm chart.                                                                                |
| `$charts_uri`                                               | OCI URI hosting the Vantage operator Helm chart.                                                                               |
| `$chart_uri`                                                | OCI URI hosting the `vantage-selfhosted` Helm chart.                                                                           |
| `$release_name`                                             | Helm release name for `vantage-selfhosted`.                                                                                    |
| `$your_vantage_hostname`                                    | DNS hostname Vantage will be reachable at.                                                                                     |
| `$ingress_tls_secret_name`                                  | Name of the `kubernetes.io/tls` secret in the ingress gateway namespace.                                                       |
| `$key_vault_name`, `$tenant_id`, `$client_id`               | Azure Key Vault name, tenant ID, and client ID of the UAMI with Key Vault read access.                                         |
| `$your_mailfrom`                                            | Sender address for outbound mail.                                                                                              |
| `$smtp_host`, `$smtp_port`, `$smtp_login`, `$smtp_password` | Outbound SMTP settings. **Optional**: omit if using SendGrid (the default; supply `sendgridApiKey` via your secrets provider). |
| `$your_platformadmin_email`                                 | Initial platform admin email.                                                                                                  |
| `$your_oci_host`                                            | OCI registry host that Vantage artifacts will be migrated into.                                                                |
| `$abbyy_oci_source_host`, `$abbyy_oci_source_repository`    | Source registry and repository for ABBYY-distributed artifacts. The documented values are `abbyy.jfrog.io` and `abbyy-docker`. |

## Connect ArgoCD to your OCI registry

ArgoCD pulls Vantage component charts from your OCI registry, so set up a connection in ArgoCD that gives it access to that registry. ArgoCD is third-party software that you install and maintain, so you create this connection yourself by registering the registry as an ArgoCD repository. See [Private Repositories](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/) in the ArgoCD documentation.

On Azure, the recommended method is [Azure Workload Identity](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/#azure-container-registryazure-repos-using-azure-workload-identity), as described in the ArgoCD documentation.

## Image pull access

Your workloads need to pull images from your registry. Configure pull access in one of two ways. The names `my-pull-secret` and `my-service-account` below are example names; substitute your own.

**Option 1 (Azure): grant `AcrPull` to the AKS managed identity.** Azure deployments can be simplified by granting [`AcrPull`](https://learn.microsoft.com/azure/aks/cluster-container-registry-integration) on your Azure Container Registry to the AKS managed identity (the kubelet identity), instead of configuring pull secrets. With this in place you can skip the pull-secret `--set` flags in Steps 1 and 2.

**Option 2: Kubernetes image pull secrets.** Create a registry pull secret ([Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)), then wire it in per component:

| Component         | Configuration                                                                                                                                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operator pods     | `--set "manager.imagePullSecrets[0].name=my-pull-secret"` on the `vantage-operator` chart. See [Step 1](#step-1-install-the-vantage-operator).                                                                                                                                                    |
| OCI migration job | Either run the job under a ServiceAccount that carries the pull secret (`vantage.ociMigration.serviceAccountName=my-service-account`), or reference the secret on the source entry (`vantage.ociMigration.sources[0].credentialsRef.name=my-pull-secret`). See [Step 2](#step-2-install-vantage). |
| Vantage workloads | Add the pull secret to the `imagePullSecrets` of the ServiceAccount named by `vantage.serviceAccountName`. See [Step 2](#step-2-install-vantage).                                                                                                                                                 |

You create and maintain the role assignments, ServiceAccounts, and pull secrets yourself.

## Step 1: Install the Vantage operator

Pick a namespace for the operator (it does not need to be `app`) and install the chart:

```bash theme={null}
helm upgrade --install vantage-operator $charts_uri/vantage-operator \
  --version $operator_version \
  --namespace $operator_namespace \
  --wait
```

If you use pull secrets instead of `AcrPull` (see [Image pull access](#image-pull-access)), append:

```bash theme={null}
  --set "manager.imagePullSecrets[0].name=my-pull-secret"
```

See the [`vantage-operator` chart values](/vantage/self-hosted/v3.0/helm-chart#vantage-operator) for additional values you can supply.

## Step 2: Install Vantage

Install the `vantage-selfhosted` chart into your chosen namespace, supplying secrets configuration and OCI migration settings:

```bash theme={null}
helm upgrade --install $release_name $chart_uri/vantage-selfhosted \
  --version $selfhosted_version \
  --namespace $install_namespace \
  --set "operator.namespace=$operator_namespace" \
  --set "ingress.tls.secretName=$ingress_tls_secret_name" \
  --set "vantage.dnsRecord=$your_vantage_hostname" \
  --set "vantage.mailFrom=$your_mailfrom" \
  --set "vantage.platformAdminEmail=$your_platformadmin_email" \
  --set "vantage.secrets.azure.keyVaultName=$key_vault_name" \
  --set "vantage.secrets.azure.tenantId=$tenant_id" \
  --set "vantage.secrets.azure.clientId=$client_id" \
  --set "vantage.ociMigration.enabled=true" \
  --set "vantage.ociMigration.sources[0].host=$abbyy_oci_source_host" \
  --set "vantage.ociMigration.sources[0].repository=$abbyy_oci_source_repository" \
  --set "vantage.ociMigration.destination.host=$your_oci_host" \
  --wait
```

If you use pull secrets instead of `AcrPull` (see [Image pull access](#image-pull-access)), append the pull configuration for the Vantage workloads and the migration job:

```bash theme={null}
  --set "vantage.serviceAccountName=my-service-account" \
  --set "vantage.ociMigration.serviceAccountName=my-service-account"
```

`my-service-account` is a ServiceAccount you create in `$install_namespace` with your registry pull secret listed under `imagePullSecrets`. As an alternative for the migration job, reference the pull secret on the source entry instead:

```bash theme={null}
  --set "vantage.ociMigration.sources[0].credentialsRef.name=my-pull-secret"
```

SendGrid is the default mail provider: supply a `sendgridApiKey` in your Key Vault and no further mail configuration is needed. To use SMTP instead, append:

```bash theme={null}
  --set "vantage.smtp.host=$smtp_host" \
  --set "vantage.smtp.port=$smtp_port" \
  --set "vantage.smtp.login=$smtp_login" \      # optional
  --set "vantage.smtp.password=$smtp_password"  # optional
```

<Note>
  `vantage.secrets.azure.identityMode` defaults to `workloadIdentity`. To use the legacy pod-identity or VM-managed-identity model, see [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault#identity-modes).
</Note>

The `--set` flags above map directly to fields on the [Vantage custom resource](/vantage/self-hosted/v3.0/api-reference) and on the [`vantage-selfhosted` chart](/vantage/self-hosted/v3.0/helm-chart).

## Step 3: Monitor installation progress

Wait for the Vantage custom resource to report `Ready`:

```bash theme={null}
kubectl -n $install_namespace wait \
  --for=condition=Ready vantages.vantage.abbyy.com/$release_name \
  --timeout=30m
```

This is the coarse-grained signal; it indicates the Vantage Core installation is complete. Skill installation is tracked by a separate job and may still be running (see below).

For finer-grained visibility into the artifact migration, watch the OCI migration job separately:

```bash theme={null}
kubectl -n $install_namespace wait --for=create job/$release_name-oci-migration --timeout=2m
kubectl -n $install_namespace wait --for=condition=Complete job/$release_name-oci-migration --timeout=20m
```

Once migration is complete, ArgoCD (API or UI) gives the deepest visibility into individual chart sync status. The one exception is skill installation: skills are installed by a separate Kubernetes job that is not surfaced via ArgoCD.

You can use Vantage while skill installation is ongoing. Monitor the job directly:

```bash theme={null}
kubectl -n $install_namespace wait --for=create job/$install_namespace-skill-installer-job
kubectl -n $install_namespace wait --for=condition=Complete job/$install_namespace-skill-installer-job
```

## Step 4: Access Vantage

Once the resource reports `Ready`, your Vantage instance is available at:

```
https://$your_vantage_hostname
```

<Note>
  The skill installer job may still be running at this point. You can sign in and use Vantage while skill installation is ongoing; monitor the job with the commands in [Step 3](#step-3-monitor-installation-progress).
</Note>

## Azure-specific operational notes

* **Monitoring**: On AKS, the recommended pattern is Azure Monitor Workspace + Azure Managed Grafana with an in-mesh Prometheus that scrapes Vantage over Istio mTLS. See [Azure Managed Monitoring](/vantage/self-hosted/v3.0/monitoring/azure-managed) for the full setup.
* **Workload Identity**: The default authentication mode for the Secrets Store CSI driver. Also a supported auth scenario for the OCI migration job (Workload Identity + Azure RBAC) and used by the in-mesh Prometheus that remote-writes to Azure Monitor. See [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault#identity-modes).

## What's next

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/vantage/self-hosted/v3.0/architecture">
    How the operator + ArgoCD + CRD pattern works.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/vantage/self-hosted/v3.0/monitoring/overview">
    Azure Monitor Workspace + Managed Grafana with an in-mesh Prometheus.
  </Card>

  <Card title="Upgrading" icon="arrow-up" href="/vantage/self-hosted/v3.0/upgrading">
    Manual upgrade workflow for moving between Vantage 3.0 versions.
  </Card>

  <Card title="Troubleshooting" icon="stethoscope" href="/vantage/self-hosted/v3.0/troubleshooting">
    Common operator, ArgoCD, Istio, and Key Vault issues.
  </Card>
</CardGroup>