> ## 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. # API reference > Field reference for the vantage.abbyy.com/v1alpha1 Vantage custom resource that drives Vantage 3.0 self-hosted installations. The Vantage 3.0 self-hosted installer is driven by a single Kubernetes custom resource: a `Vantage` object in the `vantage.abbyy.com/v1alpha1` API group. The fields below are the full contract between you and the operator. For a conceptual overview of how the operator consumes this resource, see [Architecture](/vantage/self-hosted/v3.0/architecture). For an installation procedure, choose [Azure](/vantage/self-hosted/v3.0/providers/azure) or [Self-Managed Kubernetes](/vantage/self-hosted/v3.0/providers/self-managed). ## API group | Group | Version | Resource | | ------------------- | ---------- | --------- | | `vantage.abbyy.com` | `v1alpha1` | `Vantage` | ## Vantage The top-level Vantage resource. The `vantage-selfhosted` chart contains a `Vantage` CR instance, created in the namespace where you installed that chart. | Field | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------------- | | `apiVersion` | `string` | Yes | vantage.abbyy.com/v1alpha1 | | `kind` | `string` | Yes | Vantage | | `metadata` | `object` | Yes | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | | `spec` | `object` | Yes | spec defines the desired state of Vantage. See [`Vantage.spec`](#vantagespec). | | `status` | `object` | No | status defines the observed state of Vantage. See [`Vantage.status`](#vantagestatus). | ## Vantage.spec spec defines the desired state of Vantage | Field | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `databaseProvider` | `string` | No | Database engine used by Vantage services. Accepted values are `SqlServer` and `PostgreSQL`; the value is case-sensitive. Default: `SqlServer`. | | `dnsRecord` | `string` | Yes | dnsRecord is the DNS record for the vantage installation Format: `hostname`. | | `mailFrom` | `string` | Yes | mailFrom is the email address used as the sender for outgoing emails Format: `email`. | | `platformAdminEmail` | `string` | Yes | platformAdminEmail is the email address of the platform administrator Format: `email`. | | `secrets` | `object` | Yes | secrets selects and configures the secrets provider. Exactly one provider must be specified. See [`secrets`](#vantagespecsecrets). | | `updatePolicy` | `object` | Yes | updatePolicy controls how the operator handles Vantage upgrades. Use `manual: {}`; automatic updates are not yet supported. See [`updatePolicy`](#vantagespecupdatepolicy). | | `vantageVersion` | `string` | Yes | vantageVersion is the version of Vantage to install. | | `workloads` | `object` | Yes | workloads configures the ConfigMap containing data about charts and images. See [`workloads`](#vantagespecworkloads). | | `idReadingEnabled` | `boolean` | No | idReadingEnabled enables ID reading features Default: `false`. | | `keda` | `object` | No | keda configures KEDA-based autoscaling. See [`keda`](#vantagespeckeda). | | `ociMigration` | `object` | No | ociMigration configures copying artifacts from a source registry to a destintion before install. Omit entirely or set enabled=false to skip migration. When enabled, destination is required. See [`ociMigration`](#vantagespecocimigration). | | `reportingEnabled` | `boolean` | No | reportingEnabled enables SQL Server reporting features. It must remain `false` when `databaseProvider` is `PostgreSQL`. Default: `false`. | | `serviceAccountName` | `string` | No | serviceAccountName is the name of the ServiceAccount to use for Vantage workloads. Omit to use the default ServiceAccount. Default: `default`. Image pulls for Vantage workloads are configured here: add your registry pull Secret to this ServiceAccount's `imagePullSecrets`. See [Azure image pull access](/vantage/self-hosted/v3.0/providers/azure#image-pull-access) or [self-managed registry access](/vantage/self-hosted/v3.0/providers/self-managed#configure-registry-access). | | `smtp` | `object` | No | smtp configures the SMTP mail server. If not specified, SendGrid is used as the mail provider. See [`smtp`](#vantagespecsmtp). | | `storage` | `object` | No | storage configures advanced storage options. Defaults to Azure Blob (using the `storage*ConnectionString` aliases) when omitted. See [`storage`](#vantagespecstorage). | | `techcore` | `object` | No | techcore contains configuration for the TechCore processing engine. See [`techcore`](#vantagespectechcore). | **`secrets` validation**: `has(self.kubernetes) != has(self.azure)`: exactly one provider must be specified. **`updatePolicy` validation**: `!has(self.auto)`: automatic updates are not yet supported. **`updatePolicy` validation**: `(has(self.auto) ? 1 : 0) + (has(self.manual) ? 1 : 0) == 1`: exactly one update policy must be specified. **`ociMigration` validation**: `!has(self.enabled) || self.enabled == false || has(self.destination)`: destination is required when ociMigration is enabled. **Database and reporting validation**: PostgreSQL is selected with the exact value `PostgreSQL`. Reporting is SQL Server-only; the resource is rejected when `databaseProvider` is `PostgreSQL` and `reportingEnabled` is `true`. **`techcore` validation**: `!self.keepPreviousVersion || has(self.previousVersion)`: previousVersion is required when keepPreviousVersion is true. ## Vantage.spec.keda keda configures KEDA-based autoscaling for supported Vantage workloads. Install KEDA and the required Prometheus service before enabling it. | Field | Type | Required | Description | | --------- | --------- | -------- | -------------------------------------------------------------------------------- | | `enabled` | `boolean` | No | Enables KEDA `ScaledObject` resources for supported workloads. Default: `false`. | The current Vantage workload charts require KEDA 2.17.x. Some `ScaledObject` resources query `http://prometheus-operated.observability.svc.cluster.local:9090`; see [Autoscaling with KEDA](/vantage/self-hosted/v3.0/performance/autoscaling). ## Vantage.spec.smtp smtp configures the SMTP mail server. Optional alternative to SendGrid; used only when set. | Field | Type | Required | Description | | ---------- | --------- | -------- | -------------------------------------------------------------- | | `host` | `string` | Yes | host is the SMTP server hostname | | `login` | `string` | No | login for SMTP authentication | | `password` | `string` | No | password for SMTP authentication | | `port` | `integer` | No | port is the SMTP server port Default: `587` · Format: `int32`. | | `useSSL` | `boolean` | No | useSSL enables TLS for SMTP connections Default: `false`. | ## Vantage.spec.workloads workloads configures the ConfigMap containing data about charts and images | Field | Type | Required | Description | | --------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `configMap` | `string` | Yes | configMap is name of the ConfigMap containing the workloads data | | `metadataTemplateKey` | `string` | Yes | metadataTemplateKey is the key within the ConfigMap containing the metadata template about installing the charts | | `secretsKey` | `string` | Yes | secretsKey is the key within the ConfigMap containing the secrets metadata | | `workloadsKey` | `string` | Yes | workloadsKey is the key within the ConfigMap containing the list of charts and images | ## Vantage.spec.secrets secrets configures the secrets provider used to supply application secrets (database connection strings, API keys, certificates) to Vantage workloads. Exactly one provider must be specified. See [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault) for the conceptual model and the full alias inventory. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `azure` | `object` | No | azure configures secrets via Azure Key Vault and the Secrets Store CSI driver. See [`azure`](#vantagespecsecretsazure). | | `kubernetes` | `object` | No | kubernetes uses pre-existing Kubernetes `Secret` resources in the install namespace. See [`kubernetes`](#vantagespecsecretskubernetes). | ## Vantage.spec.secrets.azure azure configures Azure Key Vault (via the Secrets Store CSI Driver) as the secrets source. | Field | Type | Required | Description | | ------------------------ | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `keyVaultName` | `string` | Yes | keyVaultName is the Azure Key Vault that holds the secrets. | | `tenantId` | `string` | Yes | tenantId is the Azure AD tenant that owns the Key Vault. | | `clientId` | `string` | No | clientId is the Azure AD client ID of the user-assigned managed identity that has read access to the Key Vault. Required when `identityMode` is `workloadIdentity` (the default). | | `identityMode` | `enum` | No | identityMode selects how the CSI driver authenticates against Azure. Default: `workloadIdentity` · Enum: `workloadIdentity, podIdentity, vmManagedIdentity`. | | `objects` | `map[string]object` | No | objects optionally overrides the mapping from a secret alias to a specific Key Vault object. When an alias is not present in this map, the alias itself is used as the Key Vault object name and the object is fetched as type `secret`. See [`objects`](#vantagespecsecretsazureobjectsalias). | | `userAssignedIdentityID` | `string` | No | userAssignedIdentityID is the client ID of the user-assigned managed identity to use when `identityMode` is `vmManagedIdentity`. | ## Vantage.spec.secrets.azure.objects\[alias] `AzureSecretObjectConfig` describes a single Key Vault object that backs a secret alias. | Field | Type | Required | Description | | --------------- | -------- | -------- | --------------------------------------------------------------------------------------- | | `objectName` | `string` | Yes | objectName is the name of the object in Azure Key Vault. | | `objectType` | `enum` | No | objectType is the Key Vault object kind. Default: `secret` · Enum: `secret, key, cert`. | | `objectVersion` | `string` | No | objectVersion pins a specific Key Vault object version. Defaults to the latest version. | ## Vantage.spec.secrets.kubernetes kubernetes uses pre-existing Kubernetes `Secret` resources in the install namespace. | Field | Type | Required | Description | | --------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `objects` | `map[string]object` | No | objects defines the Kubernetes secrets used, mapping secret aliases to `Secret` names. If not defined, the default secret names will be used. See [`objects`](#vantagespecsecretskubernetesobjectsalias). | ## Vantage.spec.secrets.kubernetes.objects\[alias] Each entry maps a secret alias to a Kubernetes `Secret` name. | Field | Type | Required | Description | | ------------ | -------- | -------- | -------------------------------------------------------------------- | | `secretName` | `string` | Yes | secretName is the Kubernetes `Secret` name in the install namespace. | ## Vantage.spec.storage storage configures advanced storage options. When omitted, Vantage uses the default Azure Blob backend and reads connection strings from the `storage*ConnectionString` secret aliases. See [Secrets and Key Vault](/vantage/self-hosted/v3.0/secrets-and-keyvault#storage). | Field | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------------------------------------------------------- | | `custom` | `object` | No | custom configures a custom storage backend. See [`custom`](#vantagespecstoragecustom). | ## Vantage.spec.storage.custom custom configures a custom storage backend (PVC-backed via a Kubernetes `StorageClass`). The referenced Kubernetes `StorageClass` must already be configured in the cluster before you install Vantage with a custom storage backend. | Field | Type | Required | Description | | -------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- | | `size` | `int or string` | Yes | size defines the size of the PVC. Default: `300Gi`. | | `storageClass` | `string` | Yes | storageClass defines the storage class to use for PVCs to mount custom storage backend volumes. | ## Vantage.spec.updatePolicy updatePolicy controls how the operator handles Vantage upgrades. | Field | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `auto` | `object` | No | auto enables automatic version upgrades. Not yet implemented. See [`auto`](#vantagespecupdatepolicyauto). | | `manual` | `object` | No | manual disables automatic upgrades. Upgrades are performed by installing a new version of the operator Helm chart. | ## Vantage.spec.updatePolicy.auto auto enables automatic version upgrades. Not yet implemented. | Field | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------ | | `releaseURL` | `string` | Yes | releaseURL is the URL to fetch the Vantage release bundle from. Format: `uri`. | ## Vantage.spec.ociMigration ociMigration configures copying artifacts from a source registry to a destintion before install. Omit entirely or set enabled=false to skip migration. When enabled, destination is required. | Field | Type | Required | Description | | -------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `concurrency` | `integer` | Yes | concurrency is the number of artifacts to copy in parallel. Default: `5` · Minimum: `1`. | | `destination` | `object` | No | destination is where artifacts are copied to. See [`destination`](#vantagespecocimigrationdestination). | | `enabled` | `boolean` | No | enabled enables OCI migration. Default: `true`. | | `imagePullSecrets` | `[]object` | No | imagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling the operator image which is used to run the OCI migration job in this namespace. See [`imagePullSecrets`](#vantagespecocimigrationimagepullsecretsindex). | | `labels` | `map[string]JSON` | No | labels is the set of of labels that should be applied to the OCI migration job and pod template. Non-string values will be converted to strings with \[fmt.Sprint] | | `serviceAccountName` | `string` | No | serviceAccountName is the name of the ServiceAccount to use to run the OCI migration job. Add your registry pull secret to this ServiceAccount's `imagePullSecrets` to give the job image pull access. | | `sources` | `[]object` | No | sources are credentials for accessing registries that artifacts are copied from (the ABBYY-distributed source registry). Max length 20. See [`sources`](#vantagespecocimigrationsourcesindex). | **`destination` validation**: !self.host.contains('/'): host must not contain a path; use the repository field for the registry path **`destination` validation**: !self.host.contains('://'): host must not include a scheme (e.g., https\://) **Image pull access for the migration job**: run the job under a ServiceAccount that carries your registry pull secret (`serviceAccountName`), or reference the secret on the source entry (`sources[].credentialsRef.name`). On Azure, granting `AcrPull` to the AKS managed identity is the simpler alternative to pull secrets. ArgoCD's access to your registry is configured separately, as an ArgoCD repository connection. See [Image pull access](/vantage/self-hosted/v3.0/providers/azure#image-pull-access) and [Connect ArgoCD to your OCI registry](/vantage/self-hosted/v3.0/providers/azure#connect-argocd-to-your-oci-registry). ## Vantage.spec.ociMigration.destination destination is where artifacts are copied to. | Field | Type | Required | Description | | ------------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `host` | `string` | Yes | host is the registry hostname and optional port (e.g., registry.example.com, registry.example.com:5000) | | `credentialsRef` | `object` | No | credentialsRef references a Secret containing username and password keys or a kubernetes.io/dockerconfigjson-type Secret. Takes precedence over username/password if specified. See [`credentialsRef`](#vantagespecocimigrationdestinationcredentialsref). | | `password` | `string` | No | password for registry authentication (plaintext, use credentialsRef for production) | | `repository` | `string` | No | repository is the registry path/namespace for artifacts (e.g., `my-registry-namespace`, `vantage/images`). | | `username` | `string` | No | username for registry authentication (plaintext, use credentialsRef for production) | | `workloadIdentity` | `object` | No | workloadIdentity defines settings for using the identity of the workload (Kubernetes service account) to access the registry. See [`workloadIdentity`](#vantagespecocimigrationdestinationworkloadidentity). | ## Vantage.spec.ociMigration.destination.credentialsRef credentialsRef references a Secret containing username and password keys or a kubernetes.io/dockerconfigjson-type Secret. Takes precedence over username/password if specified. | Field | Type | Required | Description | | ------ | -------- | -------- | ------------------------------ | | `name` | `string` | Yes | name is the name of the Secret | ## Vantage.spec.ociMigration.destination.workloadIdentity workloadIdentity defines settings for using the identity of the workload (Kubernetes service account) to access the registry. | Field | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `audience` | `string` | No | audience is the endpoint that should be used to exchange the service acccount token for an OAuth access token. | | `clientId` | `string` | No | clientId is the client ID that should be used to exchange the service acccount token for an OAuth access token. | | `tokenEndpoint` | `string` | No | tokenEndpoint is the endpoint that should be used to exchange the service acccount token for an OAuth access token. | ## Vantage.spec.ociMigration.imagePullSecrets\[index] LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. | Field | Type | Required | Description | | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | No | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) | ## Vantage.spec.ociMigration.sources\[index] ContainerRegistryConfig defines container registry connection settings. | Field | Type | Required | Description | | ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `host` | `string` | Yes | host is the registry hostname and optional port (e.g., registry.example.com, registry.example.com:5000) | | `credentialsRef` | `object` | No | credentialsRef references a Secret containing username and password keys or a kubernetes.io/dockerconfigjson-type Secret. Takes precedence over username/password if specified. Referencing a pull secret here is the alternative to running the migration job under a ServiceAccount that carries the secret. See [`credentialsRef`](#vantagespecocimigrationsourcesindexcredentialsref). | | `password` | `string` | No | password for registry authentication (plaintext, use credentialsRef for production) | | `repository` | `string` | No | repository is the registry path/namespace for artifacts (e.g., `my-registry-namespace`, `vantage/images`). | | `username` | `string` | No | username for registry authentication (plaintext, use credentialsRef for production) | | `workloadIdentity` | `object` | No | workloadIdentity defines settings for using the identity of the workload (Kubernetes service account) to access the registry. See [`workloadIdentity`](#vantagespecocimigrationsourcesindexworkloadidentity). | ## Vantage.spec.ociMigration.sources\[index].credentialsRef credentialsRef references a Secret containing username and password keys or a kubernetes.io/dockerconfigjson-type Secret. Takes precedence over username/password if specified. | Field | Type | Required | Description | | ------ | -------- | -------- | ------------------------------ | | `name` | `string` | Yes | name is the name of the Secret | ## Vantage.spec.ociMigration.sources\[index].workloadIdentity workloadIdentity defines settings for using the identity of the workload (Kubernetes service account) to access the registry. | Field | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `audience` | `string` | No | audience is the endpoint that should be used to exchange the service acccount token for an OAuth access token. | | `clientId` | `string` | No | clientId is the client ID that should be used to exchange the service acccount token for an OAuth access token. | | `tokenEndpoint` | `string` | No | tokenEndpoint is the endpoint that should be used to exchange the service acccount token for an OAuth access token. | ## Vantage.spec.techcore techcore contains configuration for the TechCore processing engine | Field | Type | Required | Description | | --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `version` | `integer` | Yes | version is the TechCore version to deploy (e.g. 4). Minimum: `1`. | | `keepPreviousVersion` | `boolean` | No | keepPreviousVersion retains the previous version during upgrades Default: `false`. | | `nnTrainingWorkers` | `object` | No | nnTrainingWorkers configures neural network training workers. See [`nnTrainingWorkers`](#vantagespectechcorenntrainingworkers). | | `previousVersion` | `integer` | No | previousVersion is the version being upgraded from. Required when keepPreviousVersion is true. Minimum: `1`. | ## Vantage.spec.techcore.nnTrainingWorkers nnTrainingWorkers configures neural network training workers | Field | Type | Required | Description | | --------- | --------- | -------- | ------------------------------------------------------------------- | | `enabled` | `boolean` | No | enabled enables neural network training workers Default: `false`. | | `gpu` | `boolean` | No | gpu enables GPU acceleration for training workers Default: `false`. | ## Vantage.status status defines the observed state of Vantage | Field | Type | Required | Description | | ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `availableVersions` | `[]string` | No | availableVersions is the list of versions available from the release URL. | | `conditions` | `[]object` | No | conditions represent the current state of the Vantage resource. Each condition has a unique type and reflects the status of a specific aspect of the resource. Standard condition types include: - "Available": the resource is fully functional - "Progressing": the resource is being created or updated - "Degraded": the resource failed to reach or maintain its desired state The status of each condition is one of True, False, or Unknown. See [`conditions`](#vantagestatusconditionsindex). | | `degradationReasons` | `[]object` | No | degradationReasons represent the reasons for the installation's degraded state. See [`degradationReasons`](#vantagestatusdegradationreasonsindex). | | `installedVantageVersion` | `string` | No | installedVantageVersion is the version currently running. | | `observedGeneration` | `integer` | No | observedGeneration is the generation of the spec that has been "processed" by the controller Format: `int64`. | Skill installation runs as a separate Kubernetes job that is not reflected in `status.conditions[]` and is not surfaced via ArgoCD. Vantage is usable while the job runs. See [Lifecycle](/vantage/self-hosted/v3.0/lifecycle#skill-installation-runs-separately) for the monitoring commands. ## Vantage.status.conditions\[index] Condition contains details for one aspect of the current state of this API Resource. | Field | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lastTransitionTime` | `string` | Yes | lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. Format: `date-time`. | | `message` | `string` | Yes | message is a human readable message indicating details about the transition. This may be an empty string. | | `reason` | `string` | Yes | reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. | | `status` | `enum` | Yes | status of the condition, one of True, False, Unknown. Enum: `True, False, Unknown`. | | `type` | `string` | Yes | type of condition in CamelCase or in foo.example.com/CamelCase. | | `observedGeneration` | `integer` | No | observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions\[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. Format: `int64` · Minimum: `0`. | ## Vantage.status.degradationReasons\[index] DegradationReason represents a reason why a single component of the installation is degraded. | Field | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `component` | `string` | Yes | component is the part of the installation that is degraded. | | `message` | `string` | Yes | message is human readable description for the component's degradation. | | `reason` | `string` | Yes | reason contains a programmatic identifier indicating the reason for the component's degradation. The value should be a CamelCase string. |