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. For an installation procedure, choose Azure or Self-Managed Kubernetes.

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.
status	object	No	status defines the observed state of Vantage. See Vantage.status.

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.
updatePolicy	object	Yes	updatePolicy controls how the operator handles Vantage upgrades. Use manual: {}; automatic updates are not yet supported. See updatePolicy.
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.
idReadingEnabled	boolean	No	idReadingEnabled enables ID reading features Default: false.
keda	object	No	keda configures KEDA-based autoscaling. See keda.
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.
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 or self-managed registry access.
smtp	object	No	smtp configures the SMTP mail server. If not specified, SendGrid is used as the mail provider. See smtp.
storage	object	No	storage configures advanced storage options. Defaults to Azure Blob (using the storage*ConnectionString aliases) when omitted. See storage.
techcore	object	No	techcore contains configuration for the TechCore processing engine. See techcore.

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.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 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.
kubernetes	object	No	kubernetes uses pre-existing Kubernetes Secret resources in the install namespace. See kubernetes.

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

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.

Field	Type	Required	Description
custom	object	No	custom configures a custom storage backend. See custom.

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. Its provisioned volumes must be writable by a non-root user; see Configure persistent storage.

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. A PVC’s storageClassName is immutable: moving an existing installation to a different class requires deleting and recreating the operator’s PVCs.

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

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

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

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

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.
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.
degradationReasons	[]object	No	degradationReasons represent the reasons for the installation’s degraded state. See degradationReasons.
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 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.