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	A unique ID for this node, formatted as a hexadecimal long number (e.g., 7f0000011388).	A unique ID derived from the node’s service IP address and port.
cluster-name	yes	Unique name for the AVS cluster (e.g, 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.

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

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

Client policy

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

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 (e.g., get, put, exists, etc.) 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	The 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	Should 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	The 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	The 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.

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	The number of IO threads to read incoming parse requests.	Number of available processors
worker-threads	no	The 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 via 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 describes 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	The 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
    override-tls-hostname: avs.aerospike.com

  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
    override-tls-hostname: asd.aerospike.com

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	Default	Description
store-type	Yes		Value should be PEM.
store-file	Yes		The private key in PEM format. Can be in encrypted or cleartext format.
store-password-file	Optional		The 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

If present configures secure authentication of AVS clients.

Option	Required	Default	Description
auth-token	yes	none	Configures access token management. See auth token 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	The 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	The public key PEM file for securing the access token.
token-expiry	no	30000	The expiry (TTL) for an issued access token.

Indexing

Use indexing to configure index usage and maintenance operations as it relates to caching and healer. See the subsection for complete details.

Option	Required	Default	Description
max-mem-queue-size	no	1000000	Default maximum size of in-memory queue for inserted/updated vector records. If the queue is full the record upsert will either be rejected with a RESOURCE_EXHAUSTED error or written to storage for index healer to later pick the record for indexing based on the put option.
cache	no		Default cache properties. See Cache for details.
healer	no		Default healer properties. See Healer for details.

Cache

Option	Required	Default	Description
max-entries	no	2000000	The default maximum number of vector graph vertices to cache for indices that have not configured the cache parameters.
expiry-millis	no	no expiry	The default cache expiry in milliseconds for indices that have not configured the cache parameters. Entries in cache will expire after this interval when written to cache.

Healer

Option	Required	Default	Description
max-scan-rate-per-node	no	1000	The default value for maximum allowed record scan rate per vector db node.
max-scan-page-size	no	10000	The default value for maximum number of records in a single scanned page.
reindex-percent	no	10	The default value for percentage of good records randomly selected for reindexing in a healer cycle.

Logging

# The logging properties.
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