Aerospike Configuration (asconfig)

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

Note

asconfig is in beta. Functionality may change rapidly and issues may exist. If you have suggestions, issues, or would like to contribute code, post an issue or open a pull request on the asconfig GitHub repository.

Overview

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

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

Install asconfig

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

If you need 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.

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
generate [flags] PATH/TO/CONFIG	Generate a configuration file from a running Aerospike node
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
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.

Usage examples

To test asconfig, load an Aerospike configuration schema file into your IDE. You can also copy a schema file example from one of the following sections for testing. Run asconfig convert -a AEROSPIKE-VERSION CONFIG.YAML 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 find missing and differing items in the Aerospike configuration. You can compare two local files with diff files, or compare a local file with a running server with diff server. diff works with any format supported by asconfig. For file‑to‑file comparisons, both inputs must be the same format.

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.

asconfig diff server -h <host> -U <user> -P <password> file.conf
asconfig diff server -h <host> -U <user> -P <password> file.yaml

Compare two configuration files

diff files finds differences between two Aerospike configuration files, and is compatible with diff (no files), which was deprecated in Tools 12.0.1.

diff 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

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.

Note

asconfig reports changes necessary to make a valid configuration compatible with the version of the Aerospike Database specified by the --aerospike-version flag.

It does not report how the functionality specified in the older configuration file is affected by the conversion. Changes suggested by asconfig may change the functionality that the configuration file invokes.

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:

1. Install the Red Hat YAML VS Code extension.

2. Open Settings and search for YAML schema . Click Edit in settings.json.

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

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.

example.yaml

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

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

example.conf is now ready to configure the Aerospike database.

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