Use asconfig to manage your Aerospike configuration.

info

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

Overview

Manage your Aerospike configuration

The main features of asconfig are:

• converts between YAML and Aerospike Database configuration format,
• generates a config file from a running node,
• validates configuration files against versioned schemas, and
• compares configuration files with a diff. The configuration format is shared with the Aerospike cluster Custom Resource.

To get started you can copy an example below or load an Aerospike configuration schema file into your IDE. 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 the Aerospike database.

Installing

asconfig is included in Aerospike tools package 8.3.0 and later in deb, RPM, and Mac .pkg formats.

Directions for installing from source are at the asconfig GitHub repository.

Usage

asconfig COMMAND [flags] [arguments]

Supported Commands

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 [flags] PATH/TO/CONFIG1 PATH/TO/CONFIG2	Find differences between configuration files
validate [flags] PATH/TO/CONFIG	Validate an Aerospike configuration file
help [command]	Display help information for any command

Usage examples

Convert

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

Convert local file aerospike.yaml to the Aerospike configuration format, validating for Aerospike server 6.2.0.x, and write it to 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 server version and using only a source file means the result is written to stdout.

    asconfig convert -a "6.2.0" aerospike.yaml

Convert local file aerospike.conf to YAML format, validating for Aerospike server 6.2.0.x, and write it to local file, aerospike.yaml.

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

Diff

The diff command points out missing and differing items in Aerospike configuration files. diff works with any file format supported by asconfig, as long as all input files are the same format.

Find differences in Aerospike configuration files.

asconfig diff cluster_1.conf cluster_2.conf
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

danger

The generate command is currently in beta and 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 writing to an output file:

        asconfig -h 172.22.0.1 -U <user> -P <pwd> -o aerospike.conf

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

        asconfig -U <user> -P <pwd> -F yaml

Validate

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 prints 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 which is 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. Ensuring that a configuration file invokes the desired functionality is up to the user.

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 allows using the Aerospike configuration JSON schema files for code suggestions in VS Code when creating 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 IDE's to get code suggestions. The following steps detail this process in VS Code.

• Install the Red Hat YAML VS Code extension.

• In VS Code, go to preferences, then settings. Search for "YAML schema" and click "edit in settings.json".

• Use the following example to add a yaml.schemas mapping to your settings.json. 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 will associate 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

Here is an example YAML configuration file and the command to convert it to an Aerospike configuration file for server 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.