---
title: "Aerospike Configuration (asconfig)"
description: "Guide to using asconfig for validating, converting, and comparing Aerospike Database configurations."
---

# Aerospike Configuration (asconfig)

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

This page describes the primary features of Aerospike Configuration (`asconfig`), how to use them, and 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](https://github.com/aerospike/asconfig).
:::

`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](https://aerospike.com/download/tools/) 8.3.0 and later in Debian, RPM, and macOS .pkg formats automatically installs `asconfig`. See [Install Aerospike tools](https://aerospike.com/docs/database/tools/install) 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](https://github.com/aerospike/asconfig) for the source code and compiling instructions.

## Usage examples

To test `asconfig`, load an [Aerospike configuration schema file](https://github.com/aerospike/schemas/tree/main/json/aerospike) into your IDE. For simple testing, you can copy the schema file example from the [Configuration example](#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](https://aerospike.com/docs/database/manage/database/as-config). 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`.

Terminal window

```shell
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.

Terminal window

```shell
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`.

Terminal window

```shell
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.

::: note
Running `asconfig diff` without a subcommand defaults to `files` mode for backward compatibility, but displays a deprecation warning. Use `diff files` explicitly.
:::

#### Compare two configuration files

`diff files` finds differences between two Aerospike configuration files.

diff files

```shell
asconfig diff files cluster_1.conf cluster_2.conf
```

Preview

Terminal window

```shell
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:

Terminal window

```shell
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.

Terminal window

```shell
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.

Terminal window

```shell
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:**

Terminal window

```shell
# 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:**

Terminal window

```shell
# 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`.

Terminal window

```shell
asconfig list versions [flags]
```

**Flags:**

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

**Examples:**

Terminal window

```shell
# 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:

Terminal window

```shell
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:

Terminal window

```shell
asconfig generate -U USERNAME -P PASSWORD -F yaml
```

### validate command

The `validate` command checks an Aerospike configuration file against an [Aerospike configuration schema file](https://github.com/aerospike/schemas/tree/main/json/aerospike) 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.

Terminal window

```shell
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.

Terminal window

```shell
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.

::: 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.
:::

Terminal window

```shell
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](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). 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](https://github.com/aerospike/schemas/tree/main/json). 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](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
    
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.
    
    ```json
    "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](https://aerospike.com/docs/database/manage/database/as-config) for Database 6.2.0.x.

### YAML configuration file

example.yaml

```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 from YAML format

Terminal window

```shell
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](https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/config/samples).

## 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` |