Aerospike Configuration (asconfig)

This page describes the primary features of Aerospike Configuration (asconfig), how to use them, and usage examples for the tool’s main functions.

asconfig validates and compares Aerospike configurations using a versioned YAML schema directory. You can use asconfig to do the following:

Convert between YAML and Aerospike Database configuration format
Generate a configuration file from a running node
Validate configuration files against versioned schemas
Compare configuration files with a diff
Compare a local configuration file with the live configuration of a running Aerospike node
Compare Aerospike configuration schemas between two server versions to show what configurations have changed between one version and the other
List all available Aerospike server versions that asconfig supports

The configuration format is shared with the Aerospike cluster Custom Resource file in a Kubernetes deployment.

Install asconfig

Installing the Aerospike tools package 8.3.0 and later in Debian, RPM, and macOS .pkg formats automatically installs asconfig. See Install Aerospike tools for details.

To install only asconfig without the tools package, or modify the source code for your own deployment needs, see the asconfig GitHub repository for the source code and compiling instructions.

Usage examples

To test asconfig, load an Aerospike configuration schema file into your IDE. For simple testing, you can copy the schema file example from the Configuration example section. Run asconfig convert -a AEROSPIKE_VERSION YAML_CONFIG_FILE -o aerospike.config to convert your YAML configuration to an Aerospike configuration file. You can use the converted file to configure Aerospike Database.

convert command

Use the convert command to convert between YAML and Aerospike configurations while performing schema validation. This validation ensures that Aerospike configuration files used with asconfig run with the specified version of the Aerospike server.

Convert the local file aerospike.yaml to the Aerospike configuration format, validating for Database 6.2.0.x, and write it to a new local file, aerospike.conf.

asconfig convert --aerospike-version "6.2.0" --output aerospike.conf aerospike.yaml

Short form flags and source file only conversions are also supported. In this case, -a is the Aerospike Database version. Without the --output flag, the result is written to stdout.

asconfig convert -a "6.2.0" aerospike.yaml

In the following example, asconfig converts the local file aerospike.conf to YAML format, validating for Database 6.2.0.x, and writes it to a new local file, aerospike.yaml.

asconfig convert --aerospike-version "6.2.0" --output aerospike.yaml aerospike.conf

diff command

Use diff to added, deleted, and changed items in the Aerospike configuration. The diff command has three subcommands:

Subcommand	Description
`diff files`	Compare two local configuration files
`diff server`	Compare a local file with a running server (beta)
`diff versions`	Compare configuration schemas between server versions

diff works with any format supported by asconfig. For file‑to‑file comparisons, both inputs must be the same format.

Compare two configuration files

diff files finds differences between two Aerospike configuration files.

asconfig diff files cluster_1.conf cluster_2.conf

Preview

Differences shown from cluster_1.conf to cluster_2.conf, '<' are from file1, '>' are from file2.
namespaces.{test}.index-type.mounts:
        <: [/test/dev/xvdf-index]
        >: [/mnt/pmem1]
namespaces.{test}.index-type.mounts-size-limit:
        <: 4294967296
        >: 1073741824
namespaces.{test}.index-type.type:
        <: flash
        >: pmem
<: namespaces.{test}.storage-engine.devices
>: namespaces.{test}.storage-engine.files
>: namespaces.{test}.storage-engine.filesize
namespaces.{test}.storage-engine.type:
        <: device
        >: pmem
network.heartbeat.mode:
        <: mesh
        >: multicast

You can also specify the format explicitly:

asconfig diff files --format yaml aerospike1.yaml aerospike2.yaml

Compare a node configuration with a file

diff server compares a local configuration file to the live configuration of the specified server, and supports the Aerospike connection flags. Use this to detect configuration drift between your file and a running node.

asconfig diff server -h HOST -U USER -P PASSWORD file.conf
asconfig diff server -h HOST -U USER -P PASSWORD file.yaml

Compare configuration schemas between versions

diff versions compares Aerospike configuration schemas between two server versions to show what has changed between the two versions. This helps you plan upgrades by identifying new, removed, or modified configuration options.

asconfig diff versions VERSION1 VERSION2 [flags]

Features:

Automatic version ordering: If you provide versions in reverse order, the tool automatically reorders them (for example, 8.0.0 7.0.0 becomes 7.0.0 8.0.0)
Detailed output by default: Shows property types, defaults, descriptions, and enterprise-only markers

Flags:

Flag	Description
`--compact`, `-c`	Compact mode. Show minimal output with only configuration names
`--filter-path`, `-f`	Path filtering. Filter output to specific, comma-separated configuration sections

Examples:

# Compare configuration changes between versions (detailed by default)
asconfig diff versions 7.0.0 7.2.0

# Versions are automatically reordered if needed
asconfig diff versions 8.1.0 7.0.0  # Shows 7.0.0 → 8.1.0

# Show minimal output with only configuration names
asconfig diff versions 6.4.0 7.0.0 --compact

# Focus on specific configuration areas
asconfig diff versions 7.0.0 8.0.0 --filter-path "logging,namespaces"

# Combine compact view with filtering
asconfig diff versions 7.0.0 8.0.0 --compact --filter-path "service"

Output format:

The tool groups changes by configuration section (service, network, namespaces, logging, security, xdr, and others) and shows three types of changes:

✅ NEW CONFIGURATIONS: Additions in the newer version
❌ REMOVED CONFIGURATIONS: Removals from the older version
🔄 MODIFIED CONFIGURATIONS: Changes to existing properties

In detailed mode (default), the output includes property information including type, defaults, allowed values, min/max limits, and enterprise-only markers.

Use cases:

# Before upgrading from 7.0.0 to 8.0.0, check what changed
asconfig diff versions 7.0.0 8.0.0 --filter-path "namespaces,service"

# Get a compact list of all changes between versions
asconfig diff versions 7.0.0 8.1.0 --compact

list command

Use list to display information about available resources in asconfig.

List available versions

list versions displays all Aerospike server versions that asconfig supports. Use this command to find valid version numbers before running other commands like diff versions or validate.

asconfig list versions [flags]

Flags:

Flag	Description
`--verbose`, `-v`	Display output with numbering and totals

Examples:

# Simple list (default)
asconfig list versions

# Verbose format with numbering and total count
asconfig list versions --verbose

The tool lists supported versions sorted from earliest to latest. In verbose mode, the tool displays a numbered list that indicates the total number of supported versions.

generate command

The generate command has the following limitations:

Community Edition is not supported
Generated static configuration is missing:
- logging.syslog context
- mod-lua context
- service.user parameter
- server.group parameter

The generate command generates an Aerospike configuration file from a running node.

The following example generates a configuration file from host 172.22.0.1 with authentication enabled, and writes to an output file:

asconfig generate -h 172.22.0.1 -U USERNAME -P PASSWORD -o aerospike.conf

The following example generates a configuration file from localhost and writes the output to stdout in YAML format:

asconfig generate -U USERNAME -P PASSWORD -F yaml

validate command

The validate command checks an Aerospike configuration file against an Aerospike configuration schema file and ensures that it is valid for the given version of the Aerospike Database. You must include the --aerospike-version or -a flag to indicate which version of the Aerospike Database you want to validate the configuration file for. A configuration file that passes validation prints no output.

asconfig validate --aerospike-version 7.0.0 aerospike_7.0.0_config.YAML

Configuration files that fail validation print errors describing the problem. In the following example, "aerospike_7.0.0_config.conf" is missing the required cluster-name service field, and has a evict-used-pct field greater than the maximum allowed value.

asconfig validate -a 6.4.0 aerospike_7.0.0_config.conf
context: (root).namespaces.0.storage-engine
context: (root).namespaces.0.storage-engine.evict-used-pct
        - description: Must be less than or equal to 100, error-type: number_lte
context: (root).service
        - description: cluster-name is required, error-type: required

The validate command specifies what changes to make to configuration files when upgrading Aerospike Database versions. The following example validates aerospike_6.4.0_config.conf against the Aerospike 7.0.0 schema, showing values that must change in order for the configuration to run with Aerospike Database 7.0.0.

asconfig validate -a 7.0.0 aerospike_6.4.0_config.conf
context: (root).namespaces.0
        - description: Additional property memory-size is not allowed, error-type: additional_property_not_allowed
context: (root).namespaces.0.storage-engine
        - description: data-size is required, error-type: required
context: (root).namespaces.1
        - description: Additional property memory-size is not allowed, error-type: additional_property_not_allowed
context: (root).namespaces.1.index-type
        - description: Additional property mounts-high-water-pct is not allowed, error-type: additional_property_not_allowed
        - description: Additional property mounts-size-limit is not allowed, error-type: additional_property_not_allowed
        - description: mounts-budget is required, error-type: required
context: (root).namespaces.1.sindex-type
        - description: Additional property mounts-high-water-pct is not allowed, error-type: additional_property_not_allowed
        - description: Additional property mounts-size-limit is not allowed, error-type: additional_property_not_allowed
        - description: mounts-budget is required, error-type: required
context: (root).namespaces.1.storage-engine
        - description: data-size is required, error-type: required
context: (root).service
        - description: cluster-name is required, error-type: required

Editor-supported, real-time schema validation

Although asconfig validates your configuration file at conversion time, we recommend that you install the Red Hat YAML VS Code extension. The extension supports the Aerospike configuration JSON schema files for code suggestions in VS Code when you create your own YAML configuration.

The JSON schema files used by asconfig and in this example are stored in the Aerospike schemas GitHub repository. To write your own YAML configuration file, clone the repository and follow the example below.

Example

You can load schema files into most IDEs to get code suggestions. The following steps detail this process in VS Code:

Install the Red Hat YAML VS Code extension.
Open Settings and search for YAML schema . Click Edit in settings.json.
Use the following example to add a yaml.schemas mapping to your settings.json file. Replace /absolute/path/to/schemas/repo with the path to your local clone of the Aerospike schemas repo.
```
"yaml.schemas": {
   "/absolute/path/to/schemas/repo/json/aerospike/6.2.0.json": ["/*aerospike.yaml"]
}
```
This associates all files ending in “aerospike.yaml” with the 6.2.0 Aerospike YAML schema.

Now you can use the code suggestions from the 6.2.0 Aerospike YAML schema to write your YAML configuration.

Configuration example

The following example contains a YAML configuration file and the command to convert it to an Aerospike configuration file for Database 6.2.0.x.

YAML configuration file

service:
  feature-key-file: /etc/aerospike/features.conf

logging:
- name: console
  any: info
network:
  service:
    port: 3000
  fabric:
    port: 3001
  heartbeat:
    mode: mesh
    port: 3002
    addresses:
      - local

xdr:
  dcs:
    - name: elastic
      connector: true
      node-address-ports:
        -  0.0.0.0 8080
      namespaces:
        - name: test

namespaces:
  - name: test
    memory-size: 3000000000
    replication-factor: 2
    storage-engine:
      type: device
      files:
        - /opt/aerospike/data/test.dat
      filesize: 2000000000
      data-in-memory: true

Convert from YAML format

asconfig convert -a 6.2.0 example.yaml -o aerospike.conf

You can now use aerospike.conf to configure the Aerospike database.

For more examples, see the aerospikeConfig property from the Aerospike Kubernetes Operator examples.

Command list

Run asconfig commands with the following syntax: asconfig COMMAND [flags] [arguments]

Command	Description
`completion [flags] SHELL`	Generate the autocompletion script for the specified shell
`convert [flags] PATH/TO/CONFIG`	Convert between YAML and Aerospike configuration format
`diff files [flags] PATH/TO/CONFIG1 PATH/TO/CONFIG2`	Find differences between configuration files
`diff server [flags] PATH/TO/CONFIG`	Compare a local configuration file with the live configuration of a running Aerospike node (beta)
`diff versions [flags] VERSION1 VERSION2`	Compare configuration schemas between two server versions
`generate [flags] PATH/TO/CONFIG`	Generate a configuration file from a running Aerospike node
`list versions [flags]`	List all available Aerospike server versions supported by `asconfig`
`validate [flags] PATH/TO/CONFIG`	Validate an Aerospike configuration file
`diff [flags] PATH/TO/CONFIG1 PATH/TO/CONFIG2`	Find differences between configuration files. Deprecated in Tools 12.0.1 in favor of `diff files`