Secure Aerospike Backup Service

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike Backup Service (ABS) stores cluster passwords, cloud keys, and backup encryption keys. Treat the configuration file and the REST API as sensitive.

The REST API does not implement user authentication or authorization. Restrict who can reach the listen ports with network policy, Kubernetes NetworkPolicy, or an authenticating proxy. Optional service.https encrypts the listen port (and can require client certificates). service.http.rate is a request rate limiter, not authentication; an empty white-list rate-limits all clients, and only 0.0.0.0/0 disables it.

Applies to

Product: Aerospike Backup Service (ABS) 3.7.x.
Audience: operators and security engineers who deploy ABS or manage its credentials, keys, and certificates.
Prerequisites: ABS is installed. See Install Aerospike Backup Service.
Outcome: only trusted clients can reach the ABS listen port, the configuration file holds no plaintext passwords or keys, and GET /v1/config returns literal secrets as "[secret]".

What this page covers

Topic	When to use it
HTTPS listener	TLS on the ABS listen port, including mutual TLS, CRLs, and certificate rotation
API secrets	GET/PUT of configuration that contains passwords or keys
Logs	What ABS records and what it redacts
Secret Agent	Production passwords and keys that must not sit in plaintext YAML
`password-path`	A password file mounted into the ABS host or Pod
Cluster TLS	Aerospike Database with TLS or mTLS
Backup encryption	`.asb` files encrypted at rest in storage
Cloud credentials	S3, GCS, and Azure authentication
Rotation	How long ABS keeps using an old secret
Helm	Hardened chart defaults and writable volumes

CLI details for Secret Agent itself are in Secret usage with backup and restore and Aerospike Secret Agent.

HTTPS listener

Omit service.https to keep plaintext HTTP on service.http.port (default 8080). To terminate TLS on ABS:

service:
  http:
    disabled: true
  https:
    address: 0.0.0.0
    port: 8443
    cert-file: /etc/aerospike-backup-service/tls/tls.crt
    key-file: /etc/aerospike-backup-service/tls/tls.key
    min-version: "1.2"
    client-auth: none

You can leave HTTP enabled on a different port while HTTPS is running. At least one listener must stay enabled.

When omitted, client-auth defaults to none. For mutual TLS, set client-auth to require-and-verify (or request) and client-ca-file to a PEM bundle of trusted client CAs.

To revoke client certificates, set crl-file as well. crl-file requires client-ca-file and client-auth: require-and-verify. The file is one DER-encoded CRL or one or more PEM-encoded CRLs. Every accepted client certificate must have a matching, authentic, current issuer CRL. A missing matching CRL, or an expired or future-dated CRL, rejects the handshake. OCSP and OCSP stapling are not supported.

service:
  https:
    cert-file: /etc/aerospike-backup-service/tls/tls.crt
    key-file: /etc/aerospike-backup-service/tls/tls.key
    client-auth: require-and-verify
    client-ca-file: /etc/aerospike-backup-service/tls/clients-ca.pem
    crl-file: /etc/aerospike-backup-service/tls/clients.crl

key-file-password is a passphrase for an encrypted private key. Supply a literal value or a Secret Agent path (secrets:RESOURCE_LABEL:KEY).

When https.disabled is true, ABS does not probe certificate files at startup, so placeholder paths in a template are valid until you enable the listener.

Rotate certificates without a restart

Rewrite cert-file, key-file, client-ca-file, and crl-file at the same paths. ABS polls about every 10 seconds and uses successfully loaded material on new TLS handshakes. In-flight connections are not dropped.

Changing the configured path values is a static-field change and requires a restart.
An invalid replacement (parse failure, certificate/key mismatch, or unreadable CRL) is ignored. The last good material stays in service.
For client-ca-file, append the new CA before removing the old one so clients can migrate.
TLS session resumption is disabled when crl-file is set, so a new CRL cannot be bypassed by a resumed session. Existing connections are not closed when the CRL changes.

Mount certificates from Kubernetes Secrets or cert-manager at stable paths so rotation does not require a configuration change. See Install ABS on Kubernetes with Helm.

API secrets

GET endpoints such as /v1/config, /v1/config/clusters, and /v1/config/storage replace literal secret values with the sentinel "[secret]". Secret Agent references (secrets:...) are returned unchanged.

If you use a GET → edit other fields → PUT workflow, leave every unchanged secret field as "[secret]". ABS treats that sentinel as “keep the stored value” and does not overwrite the real secret.

To change a secret, send the new literal value or a new Secret Agent reference. Sending "[secret]" for a newly added entity that has no stored secret yet is invalid.

Keep configuration YAML in version control without literals, and prefer POST /v1/config/apply after editing the file on disk. See API usage examples.

Logs

ABS does not log HTTP request bodies or raw configuration dumps. Literal secret values are redacted in structured logs. Use Prometheus metrics and the backup and restore job APIs when you investigate a failure. See Monitor ABS.

Secret Agent

Configure one or more agents under secret-agents. Reference an agent from a cluster, storage backend, or routine with secret-agent-name, or embed a secret-agent block.

A value that starts with secrets: is a Secret Agent path: secrets:RESOURCE_LABEL:KEY. RESOURCE_LABEL is the label you configured in Secret Agent. KEY is the secret name inside that resource.

ABS validates secrets: references when it loads or applies configuration. A malformed path, or a reference without a Secret Agent, fails then rather than when a backup starts.

secret-agents:
  secret-agent:
    address: secret-agent.example.com
    port: 3005
    connection-type: TCP
    ca-file: /etc/ssl/certs/ca.pem

aerospike-clusters:
  prod:
    seed-nodes:
      - host-name: 10.0.1.10
        port: 3000
    credentials:
      user: backup-user
      password: secrets:cluster-creds:password
      secret-agent-name: secret-agent

For mutual TLS to Secret Agent, set cert-file, key-file, and name (SNI) together with ca-file.

ABS does not read Kubernetes Secrets by name. Mount the Secret as a file and use password-path, or put the value in Secret Agent.

Literal passwords in YAML work for tests. Do not use them in production.

File-based cluster password

credentials:
  user: backup-user
  password-path: /etc/aerospike-backup-service/secrets/cluster-password

password and password-path are mutually exclusive.

Cluster TLS

aerospike-clusters:
  prod:
    seed-nodes:
      - host-name: asd.example.com
        port: 4333
        tls-name: asd.example.com
    credentials:
      user: backup-user
      password-path: /etc/aerospike-backup-service/secrets/cluster-password
      auth-mode: INTERNAL
    tls:
      name: asd.example.com
      ca-file: /etc/ssl/certs/ca.pem
      cert-file: /etc/ssl/certs/client.pem
      key-file: /etc/ssl/private/client.key

tls.name is the TLS name (SNI) ABS uses to verify the server certificate. Seed tls-name must match how the Database node is configured. For PKI authentication, set auth-mode: PKI and provide client certificates.

Backup encryption

Set encryption on the backup policy. Restore must use the same key.

backup-policies:
  daily:
    parallel: 8
    encryption:
      mode: AES256
      key-file: /etc/aerospike-backup-service/secrets/backup.key

mode is NONE, AES128, or AES256. Supply the key with key-file, key-env, or key-secret (Secret Agent).

Store encryption keys separately from backup objects. Anyone with both the objects and the key can read records.

Cloud storage credentials

Prefer the cloud SDK default chain (instance role, workload identity, environment) when the ABS host already has it.

For static keys, set them on the storage object. You can use Secret Agent paths for the secret values:

storage:
  s3-backups:
    s3-storage:
      bucket: company-as-backups
      path: prod
      s3-region: us-east-1
      access-key-id: secrets:s3-creds:access-key-id
      secret-access-key: secrets:s3-creds:secret-access-key
      secret-agent-name: secret-agent

Azure accepts a shared access signature (SAS) in the endpoint URL. Treat that URL as a secret and give the token only the permissions ABS needs, for a short lifetime.

Credential rotation

ABS keeps resolved credentials only as long as a job needs them. A change does not always apply on the next API call. ABS does not cache Secret Agent values across jobs. If Secret Agent is unreachable, new jobs that need a secret fail. Running jobs keep the values they resolved at start.

Credential	When the new value is used
Storage (S3, GCS, Azure)	When ABS refreshes the storage client, up to about 10 minutes
Cluster password	When ABS opens a new Database connection after the previous one is idle
Encryption key	When a new backup job starts. Running jobs keep the old key
HTTPS server certificate and key (`service.https` `cert-file` and `key-file`)	Rewrite the files at the same paths. ABS polls about every 10 seconds and serves a successfully loaded pair on new handshakes
HTTPS client CA bundle (`service.https` `client-ca-file`)	Rewrite the file at the same path. Append the new CA before removing the old one
HTTPS client CRL (`service.https` `crl-file`)	Rewrite the file at the same path. ABS polls about every 10 seconds and applies a successfully parsed DER or PEM CRL to new connections

Plan rotation so a backup is not mid-flight when you replace storage credentials or encryption keys. After you rotate cluster passwords, wait for idle connections or restart ABS if you need the new password immediately.

Helm and Kubernetes

The ABS Helm chart defaults to a hardened container:

runAsNonRoot with UID 65532
readOnlyRootFilesystem: true
drop all capabilities
seccompProfile: RuntimeDefault
automountServiceAccountToken: false

The chart mounts an emptyDir volume at /tmp. File-based local storage or a log file on disk need an extra writable volume. See Install ABS on Kubernetes with Helm.