Skip to main content
Aerospike Vector opens new approaches to AI-driven recommendationsWebinar registration
Loading

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, 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​

CommandDescription
completion [flags] SHELLGenerate the autocompletion script for the specified shell
convert [flags] PATH/TO/CONFIGConvert between YAML and Aerospike configuration format
generate [flags] PATH/TO/CONFIGGenerate a configuration file from a running Aerospike node
diff [flags] PATH/TO/CONFIG1 PATH/TO/CONFIG2Find differences between configuration files
validate [flags] PATH/TO/CONFIGValidate an Aerospike configuration file
help [command]Display help information for any command

Usage examples​

Convert​

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 local file aerospike.yaml to the Aerospike configuration format, validating for Database 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 Database 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 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​

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​

Following is an example 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.

Tags:
Last updated on