Configure AVS

Overview

Aerospike Vector Search (AVS) uses a single configuration file located at /etc/aerospike-vector-search/aerospike-vector-search.yml.

The configuration file is divided into different configuration sections, or stanzas. A stanza can be further divided into sub-stanzas, and stanzas can be in any order in the configuration file.
Some stanzas are required and some are optional.
The maximum length of a line in the configuration file is 1,024 characters.
You can find working configuration file examples in the aerospike-vector-search-examples repository.

The following sections describe the stanzas that comprise aerospike-vector-search.yml, including sample excerpts and description of available configuration options.

Cluster

Use cluster to configure the AVS cluster.

cluster:
  # Custom node-id. It will be auto-generated if not specified.
  # node-id: a1

  # Unique identifier for this cluster.
  cluster-name: aerospike-avs

Option	Required	Description	Default
`node-id`	no	Unique ID for this node, formatted as a hexadecimal long number. For example, 7f0000011388.	Unique ID derived from the node’s service IP address and port.
`cluster-name`	yes	Unique name for the AVS cluster. For example, `avs-db-1`.

Feature-key file

Use feature-key-file to define the path to an Aerospike feature key file that has the vector-service key enabled. Contact your AVS point of contact or Aerospike account manager if you need assistance.

# Aerospike vector-service enabled license file  
feature-key-file: /etc/aerospike-vector-search/features.conf

Option	Required	Description	Default
`feature-key-file`	yes	Full path to a valid feature key file.

Storage

Use storage to configure the connection properties that AVS uses when connecting to the target (destination) Aerospike Database.

# Target Aerospike cluster
storage:
  seeds:
    - localhost:
        port: 3000

Option	Required	Description	Default
`seeds`	yes	List of Aerospike seeds. See seeds
`client-policy`	no	See Aerospike client policy properties.

Seeds

The seeds stanza is required and defines the Aerospike Database cluster nodes to which you want AVS to connect. AVS iterates through the seed nodes. After connecting to a node, AVS discovers all of the nodes in the cluster.

storage:
  seeds:
    - 192.168.50.1:
        port: 3000
        tls-name: red
    - 192.168.50.2

Option	Required	Description	Default
`port`	no	Port to use when making connections to the Aerospike Database.	3000
`tls-name`	no	TLS name of the Aerospike Database.

Client policy

Use client-policy to configure connection details between AVS and Aerospike.

client-policy:
  max-conns-per-node: 1000
  # If TLS is required to connect to Aerospike
  #tls-id: aerospike-tls
  #
  # Aerospike credentials if required.
  credentials:
    username: admin
    password-file: /path/to/password/file.txt

Option	Required	Description	Default
`cluster-name`	no	Cluster name of the destination Aerospike cluster.
`unary-event-loops`	no	Number of event loops to process unary requests such as `get`, `put`, or `exists` from the client.	Number of available processors.
`batch-event-loops`	no	Number of event loops to process batch requests from the client.	2
`query-event-loops`	no	Number of event loops to process query requests from the client.	4
`auth-mode`	no	Aerospike auth mode, which can be `INTERNAL` or `EXTERNAL`	INTERNAL
`timeout`	no	Cluster tend info call timeout in milliseconds. The timeout when opening a connection to the server node for the first time and when polling each node for cluster status.	1000
`login-timeout`	no	Login timeout in milliseconds. The timeout is used when user authentication is enabled and a node login is being performed.	5000
`close-timeout`	no	Cluster close timeout in milliseconds. Time to wait for pending async commands to complete. Use `0` for no timeout.	0
`min-conns-per-node`	no	Minimum number of synchronous connections allowed per server node. Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.	0
`max-conns-per-node`	no	Maximum number of synchronous connections allowed per server node. Transactions will go through retry logic and potentially fail with "ResultCode.NO_MORE_CONNECTIONS" if the maximum number of connections would be exceeded.	100
`conn-pools-per-node`	no	Number of synchronous connection pools used for each node. Machines with 8 CPU cores or less usually need only one connection pool per node. Machines with a large number of CPU cores may have their synchronous performance limited by contention for pooled connections. Contention for pooled connections can be reduced by creating multiple mini connection pools per node.	1
`max-socket-idle`	no	Maximum socket idle in seconds. Socket connection pools will discard sockets that have been idle longer than the maximum.	0
`max-error-rate`	no	Maximum number of errors allowed per node before backoff algorithm throws exception on database commands to that node. If set to zero, there is no error limit and the exception will never be thrown.	0
`error-rate-window`	no	Number of cluster tend iterations that defines the window for `maxErrorRate`. One tend iteration is defined as `tendInterval` plus the time to tend all nodes. At the end of the window, the error count is reset to zero and backoff state is removed on all nodes.	1
`tend-interval`	no	Interval between cluster tends by maintenance thread in milliseconds.	1000
`keep-alive`	no	See keepAlive.
`ip-map`	no	See ipMap.
`use-services-alternate`	no	Use `services-alternate` instead of `services` in info request during cluster tending. `services-alternate` returns server configured external IP addresses that the client uses to talk to nodes. `services-alternate` can be used in place of providing a client ipMap.	false
`rack-aware`	no	See rackAware.
`rack-id`	no	See rackId.
`rack-ids`	no	See rackIds.
`tls-id`	no	Name of the TLS configuration to use if TLS is desired.
`credentials`	no	Use the optional `credentials` stanza to provide authentication details when connecting to ASDB. See Security in the Database documentation for more details.
`username`	no	Username to send for connecting to ASDB.
`password-file`	no	Full path to a file from which to read the password for `username`. Everything after the first newline is ignored. Trailing spaces in the first line are not ignored.

Node Roles

By default, AVS nodes perform both indexing and query functionality, but you can also configure them to to perform just one of the two. This allows you to isolate and scale your nodes separately for indexing and query SLAs. This configuration requires a restart or scaling of your cluster and cannot be updated through an API.

These roles include:

query - Making a node available for query means the node is responsible for performing HNSW traversals and caching the index and results in memory.
index-update - Nodes available for indexing handle upsert calls and HNSW index healing.

node-roles:
  - query
  - index-update

Option	Required	Description	Default
`node-roles`	yes	Allows for specific role functionality of the node. At least one value required.	[query, index-update]

tip

Our Kubernetes deployment guide deploys by default two query nodes and one indexing node. You can check node roles of your cluster using the asvec CLI

danger

The node role string values required for the AVS service configuration do not match the values returned in the asvec CLI tool. The configuration uses lowercase strings, while asvec returns uppercase strings. You must use the lowercase strings in configuration rather than copying and pasting the asvec strings.

Service

Use service to configure networking between AVS and AVS clients.

# The AVS service listening ports, TLS and network interface.
service:
  ports:
    5000:
      addresses:
        localhost
      # Required when running behind NAT
      #advertised-listeners:
      #  default:
      #    # List of externally accessible addresses and ports for this AVS instance.
      #    - address: 10.0.0.1
      #      port: 5000

Option	Required	Description	Default
`ports`	yes	The map of ports on which AVS listens. See Ports for details.
`advertised-listeners`	no	A map of advertised listener names to advertised endpoint. See Advertised Listener for details.
`io-threads`	no	Number of IO threads to read incoming parse requests.	Number of available processors
`worker-threads`	no	Number of threads that will invoke AVS to dispatch a record.	Number of available processors
`cluster-name`	no	Group or cluster to which this AVS node belongs, used for grouping instances in Prometheus.	product-name
`max-inbound-message-size`	no	Maximum uncompressed size (in bytes) for inbound messages.	8388608
`metadata-namespace`	no	Aerospike namespace where AVS stores its system metadata.	avs-meta

Manage

Use manage to specify the endpoint and optional TLS settings for securing connections to AVS. You can use the Management and Metrics API to query and manage outbound server metrics and logs using a REST endpoint.

# Management API listening ports, TLS and network interface.
manage:
  ports:
    5040: { }

Option	Required	Description	Default
`ports`	yes	The map of ports the AVS management API listens on, to each port specific configuration. See Ports for details.

Interconnect

Use interconnect to configure networking between AVS clusters.

# Intra cluster interconnect listening ports, TLS and network interface.
interconnect:
# client-tls-id: interconnect-tls
  ports:
    5001:
      addresses:
        localhost

Option	Required	Description	Default
`client-tls-id`	no	Interconnect client-side TLS configuration when TLS is enabled for interconnect.
`ports`	yes	The map of ports on which the AVS interconnect listens. See Ports for details.

Heartbeat

Use heartbeat to configure heartbeat communication over interconnect ports between AVS cluster instances for discovery, cluster formation, and maintenance.

heartbeat:
  seeds:
    - address: 10.32.20.54
      port: 5001

Option	Required	Description	Default
`interval`	no	Heartbeat message interval in milliseconds.	500
`timeout`	no	Peer node timeout interval in milliseconds. If no heartbeat is received from the peer in this interval, it is considered unreachable.	5000
`seeds`	no	A seed list of Advertised Listeners for AVS peer instances.

Ports

Use ports to describe the configuration for each listening port.

Option	Required	Description	Default
`addresses`	no	The list of interface IP addresses to which the connector binds. Use `0.0.0.0` for all interfaces.	0.0.0.0
`tls-id`	no	Name of the TLS configuration to use with this port if TLS is desired.

Advertised Listener

An advertised listener is an external (NATed) address and port combination that differs from the actual address and port where AVS is listening. Clients can access AVS on a node using the advertised listener address and port.

Option	Required	Description	Default
`address`	yes	Advertised IP address or hostname.
`port`	yes	Advertised port.

TLS (optional)

Use TLS to configure certificates used on interconnect and storage sections.

The TLS section is a map from a TLS configuration name, used from various sections using TLS to refer to a particular TLS configuration.

tls:
  service-tls:
    trust-store:
      store-file: tls/ca.aerospike.com.truststore.jks
      store-password-file: tls/storepass
    key-store:
      store-file: tls/avs.aerospike.com.keystore.jks
      store-password-file: tls/storepass
      key-password-file: tls/keypass

  interconnect-tls:
    trust-store:
      store-file: tls/ca.aerospike.com.truststore.jks
      store-password-file: tls/storepass
    key-store:
      store-file: tls/avs.aerospike.com.keystore.jks
      store-password-file: tls/storepass
      key-password-file: tls/keypass

  aerospike-tls:
    trust-store:
      store-file: tls/ca.aerospike.com.truststore.jks
      store-password-file: tls/storepass
    key-store:
      store-file: tls/avs.aerospike.com.keystore.jks
      store-password-file: tls/storepass
      key-password-file: tls/keypass

Option	Required	Default	Description
`key-store`	no		The keystore configuration containing the server-side certificate and key. See Configuring a TLS Store.
`trust-store`	no	Default Java trust store	The keystore configuration containing the trusted CA certificates. See Configuring a TLS Store.
`protocols`	no	TLSv1.2	List of allowed TLS protocols.
`ciphers`	no	Default Java ciphers	List of allowed ciphers.
`allowed-peer-names`	no		List of AVS client peer names for mutual authentication. If set, only those clients that present certificates matching the peer names will be allowed to connect.
`mutual-auth`	no	false	Specifies whether the AVS must perform mutual authentication with the AVS client.

Keystores and truststores

Use key-store and trust-store to configure TLS keystores and truststores. All file paths are considered relative to the directory in which the configuration file is located. See Setting Up TLS Keystores for Aerospike Connect for information about creating keystores.

Option	Required	Default	Description
`store-file`	yes		The store file.
`store-password-file`	yes		Read store password from this file.
`key-password-file`	no		Read key password from this file.
`store-type`	no	JKS	The keystore type. Valid values are JKS, JCEKS, PKCS12, PKCS11, DKS, Windows_MY, BKS, PEM.

Configure a TLS keystore

OpenSSL default format and PKCS #8 format are supported for private keys.

key-store:
  store-type: PEM
  store-file: key.pem # Cleartext private key.
  certificate-chain-files: # Certificate chain in multiple PEM files.
    - cert-1.pem
    - cert-2.pem

key-store:
  store-type: PEM
  store-file: key.pem
  store-password-file: storepass # Password protecting key.pem.
  certificate-chain-files: certchain.pem

Option	Required	Description
`store-type`	Yes	Value should be PEM.
`store-file`	Yes	Private key in PEM format. Can be in encrypted or cleartext format.
`store-password-file`	Optional	Password that protects the private key specified as the value of the store-file parameter.
`certificate-chain-files`	Yes	List of files containing X.509 certificates corresponding to the private key specified in `store-file`. Multiple entries in each certificate file are allowed. All entries from all files are concatenated in order, with the first X.509 certificate from the first file being added at index 0, and the last X.509 certificate from the last file being added last. The chain must be ordered and contain an X.509 certificate at index 0 corresponding to the private key specified in `store-file`. Any entries not corresponding to an X.509 certificate are ignored when reading the PEM format certificate files.

Configure a TLS truststore

OpenSSL default format and PKCS #8 format are supported for private keys.

trust-store:
  store-type: PEM
  certificate-files: certs.pem

trust-store:
  store-type: PEM
  certificate-files:
    - certs-1.pem
    - certs-2.pem

Option	Required	Default	Description
`store-type`	Yes		The value must be PEM.
`certificate-files`	Yes		The X.509 certificates to trust. All X.509 PEM entries in all the files are added to the trust store. Any entries not corresponding to X.509 certificate are ignored.

Security (optional)

# To enable client authentication
security:
  auth-token:
    private-key: samples/auth/private_key.pem
    public-key: samples/auth/public_key.pem
    token-expiry: 300_000

Configures secure authentication of AVS clients.

Option	Required	Default	Description
`auth-token`	yes	none	Configures access token management. See auth token section for details.
`cache-expiry`	no	10000	Auth data cache expiry in milliseconds. A value of zero disables caching.

Auth token

Configures how the AVS issues access tokens to the AVS clients.

Option	Required	Default	Description
`private-key`	yes	none	Private key PEM file for securing and validating the access token.
`private-key-password`	yes	none	Plain text file containing the private key password.
`public-key`	yes	none	Public key PEM file for securing the access token.
`token-expiry`	no	30000	The expiry (TTL) for an issued access token.

Logging

logging:
  #format: json
  #file: /var/log/aerospike-vector-search/aerospike-vector-search.log
  enable-console-logging: true
  #levels:
  #  metrics-ticker: info
  #  root: debug

Option	Required	Description	Default
`file`	no	Specifies the path to the log file. Rotated log files are placed in the same folder as the current log file.
`format`	no	Logging format: `simple` (space delimited) or `json` (JSON formatted)	Simple
`enable-console-logging`	no	When set to `true` and a log file is also specified, log messages are sent to both the console and the log file. Although `enable-console-logging` is `false` by default, it is forced to `true` if you do not specify a log file.	`false`
`max-history`	no	Specifies the maximum number of log files to retain.	30
`levels`	no	Specifies the types of messages to include in the log file. Valid log levels are `error`, `warn`, `info`, `debug`, and `trace`. Each successive level includes the messages from the previous levels. For example, `trace`, being the highest level, includes messages from `error`, `warn`, `info`, and `debug`.
`ticker-interval`	no	Specifies how frequently messages are written to the log file, if there are any messages to write. The interval in measured in seconds.	10

Overview​

Cluster​

Feature-key file​

Storage​

Seeds​

Client policy​

Node Roles​

Service​

Manage​

Interconnect​

Heartbeat​

Ports​

Advertised Listener​

TLS (optional)​

Keystores and truststores​

Configure a TLS keystore​

Configure a TLS truststore​

Security (optional)​

Auth token​

Logging​