Unlock new workflows with YAML based config for Aerospike.
Tags: yaml, yml, asconfig, aerospike
Published: 2023-08-17 02:07:46

Aerospike's configuration format can be difficult to learn and lacks the ecosystem of more standard configuration formats.
Using the [asconfig](https://docs.aerospike.com/tools/asconfig) tool, new in [Aerospike tools 8.3.0](https://download.aerospike.com/download/tools/notes.html#8.3.0), you can write an Aerospike configuration in a standard YAML format with schema validation and IDE suggestions.

*In this article we:*
1. Setup an IDE for Aerospike configuration suggestions.
2. Write an Aerospike configuration file in YAML.
3. Run an Aerospike cluster using the YAML configuration.
4. Convert an existing Aerospike configuration to YAML.

## IDE Setup

Many IDEs support YAML schema files.  We use VS Code in this example.

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). To write your own YAML configuration file, clone the repository and use the following example below for VS Code.

1. Install the Red Hat YAML VS Code extension.

![gif](https://developer-hub.s3.us-west-1.amazonaws.com/2122467609/install-yaml-extension_1689122848860.gif)

2. In VS Code, go to Code->Preferences->Settings. Search for "YAML schema" and click "edit in settings.json".

![gif](https://developer-hub.s3.us-west-1.amazonaws.com/2122467609/schema-json-settings_1689122946560.gif)

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

```shell
"yaml.schemas": {
    "/absolute/path/to/schemas/repo/json/aerospike/6.3.0.json": ["/*aerospike.yaml"]
}
```

This associates all files ending in "aerospike.yaml" with the 6.3.0 Aerospike YAML schema.

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

![gif](https://developer-hub.s3.us-west-1.amazonaws.com/2122467609/paste-settings-see-suggestions_1689123001708.gif)

## Write Aerospike Configuration in YAML

Now that your IDE is using the Aerospike YAML schemas, you can write a yaml configuration with suggestions.
Aerospike configuration sections like 'service' will be suggested and possible fields and default values will be inserted.

![gif](https://developer-hub.s3.us-west-1.amazonaws.com/2122467609/suggestions-snippet_1689123049467.gif)

_YAML Schema Suggestions!_


Invalid fields and incorrect values will be highlighted in red.

![gif](https://developer-hub.s3.us-west-1.amazonaws.com/2122467609/suggestions-errors_1689123145868.gif)

_YAML Schema error highlighting._


## Convert an existing Aerospike Configuration to YAML

Another way to get started with configuring Aerospike in yaml is to use the asconfig tool to convert
an existing configuration file. Make sure to supply the version of the Aerospike database the 
configuration will be used with via the -a or --aerospike-version option.

Here we convert the default [Aerospike configuration to YAML](https://docs.aerospike.com/server/operations/configure) .

```console
asconfig convert --aerospike-version 6.3.0 aerospike.conf
```

*output*
```text
logging:
    - any: info
      name: /var/log/aerospike/aerospike.log
namespaces:
    - memory-size: 4294967296
      name: test
      replication-factor: 2
      storage-engine:
        type: memory
    - memory-size: 4294967296
      name: bar
      replication-factor: 2
      storage-engine:
        type: memory
network:
    fabric:
        port: 3001
    heartbeat:
        interval: 150
        mode: multicast
        multicast-groups:
            - 239.1.99.222
        port: 9918
        timeout: 10
    info:
        port: 3003
    service:
        addresses:
            - any
        port: 3000
service:
    group: root
    pidfile: /var/run/aerospike/asd.pid
    proto-fd-max: 15000
    user: root

```

## Launch an Aerospike cluster with YAML configuration

Launching an Aerospike cluster in Docker using the YAML configuration is easy with asconfig.

The Aerospike server only understands configuration files in its .conf format for now, so we need to use asconfig to
convert the YAML file we wrote into Aerospike .conf format.

```console
asconfig convert -a 6.3.0 aerospike.yaml -o aerospike.conf
```

Then we map the converted configuration file into an Aerospike Docker container.

```console
docker run -d -v ${PWD}:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 aerospike:ce-6.3.0.5 --config-file /opt/aerospike/etc/aerospike.conf
```

Now we have an Aerospike node running in Docker using the configuration file we wrote in YAML.

Putting it all together, the one line command to convert the YAML configuration and run Aerospike using it is below.

```console
asconfig convert -a 6.3.0 aerospike.yaml -o aerospike.conf; docker run -d -v ${PWD}:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 aerospike:ce-6.3.0.5 --config-file /opt/aerospike/etc/aerospike.conf
```

The Docker portion of the command launches the Aerospike server container, maps the current working directory as a volume, and points it to the custom configuration file that we converted.

## Learn more about Aerospike Observability & Management 

Learn how Aerospike is adopting open standards like YAML, Open Telemetry and how to find clarity in complex systems in our [upcoming Webinar - September 6th, 2023](https://aerospike.zoom.us/webinar/register/5116909188905/WN_ZZLrBxBcT3WyJZTEXSwtIw#/registration).

## More Information

- [Asconfig documentation](https://docs.aerospike.com/tools/asconfig) 
- [Asconfig Github repository](https://github.com/aerospike/asconfig) 
- [Aerospike configuration documentation](https://docs.aerospike.com/server/operations/configure) 
- [Aerospike Docker images](https://hub.docker.com/_/aerospike) 
- [Aerospike configuration reference](https://docs.aerospike.com/reference/configuration)