Skip to content

Latest commit

 

History

History
426 lines (326 loc) · 14.6 KB

api-spec.adoc

File metadata and controls

426 lines (326 loc) · 14.6 KB

API Specification

Table of Contents

Base Types

AerospikeCluster

The AerospikeCluster type represents an Aerospike cluster.

Field

Description

Scheme

Required

metadata

Standard object metadata.

metav1.ObjectMeta

true

spec

The specification of the Aerospike cluster.

AerospikeClusterSpec

true

More info:

Validations

  • metadata must be non-null.

  • metadata.name cannot exceed 60 characters.

  • spec must be non-null.

AerospikeNamespaceBackup

The AerospikeNamespaceBackup type represents a single backup operation targeting a single Aerospike namespace.

Field

Description

Scheme

Required

metadata

Standard object metadata.

metav1.ObjectMeta

true

spec

The specification of the backup operation.

AerospikeNamespaceBackupSpec

true

More info:

Validations

  • metadata must be non-null.

  • spec must be non-null.

AerospikeNamespaceRestore

The AerospikeNamespaceRestore type represents a single restore operation targeting a single Aerospike namespace.

Field

Description

Scheme

Required

metadata

Standard object metadata.

metav1.ObjectMeta

true

spec

The specification of the restore operation.

AerospikeNamespaceRestoreSpec

true

More info:

Validations

  • metadata must be non-null.

  • spec must be non-null.

Nested Types

AerospikeClusterSpec

The AerospikeClusterSpec type specifies the desired state of an Aerospike cluster.

Field

Description

Scheme

Required

version

The version of Aerospike to be deployed.

string

true

nodeCount

The number of nodes in the Aerospike cluster.

int32

true

namespaces

The specification of the Aerospike namespaces in the cluster. Must have exactly one element [1].

[]AerospikeNamespaceSpec

true

backupSpec

The specification of how Aerospike namespace backups made by aerospike-operator should be performed and stored. It is only required to be present if one wants to perform version upgrades on the Aerospike cluster.

AerospikeBackupSpec

false

resources

Standard requests and limits for Server Aerospike Container.

v1.ResourceRequirements

false

nodeSelector

Standard node selectors for Server Aerospike Pods.

v1.NodeSelector

false

tolerations

Standard tolerations for Aerospike Pods.

v1.Tolerations

false

Validations

  • version must be a supported version. Check README for a list of supported versions.

  • nodeCount must be an integer between 1 and 8. It must also be greater than or equal to the replication factor defined for the Aerospike namespace managed by a given Aerospike cluster.

  • namespaces must have exactly one AerospikeNamespaceSpec object.

Example

apiVersion: aerospike.travelaudience.com/v1alpha2
kind: AerospikeCluster
metadata:
  name: example-aerospike-cluster
  namespace: example-namespace
spec:
  version: "4.2.0.3"
  nodeCount: 3
  backupSpec:
      storage:
        type: gcs
        bucket: test-bucket
        secret: bucket-secret
  namespaces:
  - name: as-namespace-0
    replicationFactor: 2
    memorySize: 4G
    defaultTTL: 0s
    storage:
      type: file
      size: 150G
  resources:
    requests:
        cpu: "250m"
    limits:
        cpu: "500m"

AerospikeClusterBackupSpec

The AerospikeClusterBackupSpec type specifies how Aerospike namespace backups made by aerospike-operator before a version upgrade should be stored.

Field

Description

Scheme

Required

ttl

The retention period (days) during which to keep backup data in cloud storage, suffixed with d. Defaults to 0d, meaning the backup data will be kept forever.

string

false

storage

Specifies how the backup should be stored.

BackupStorageSpec

true

Validations

  • ttl must represent a non-negative quantity.

  • storage must be non-null.

AerospikeNamespaceSpec

The AerospikeNamespaceSpec type specifies the configuration for an Aerospike namespace.

Field

Description

Scheme

Required

name

The name of the Aerospike namespace.

string

true

replicationFactor

The number of replicas (including the master copy) for this Aerospike namespace. If absent, the default value provided by Aerospike will be used.

int32

false

memorySize

The amount of memory (gibibytes) to be used for index and data, suffixed with G. If absent, the default value provided by Aerospike will be used.

string

false

defaultTTL

Default record time-to-live (seconds) since it is created or last updated, suffixed with s. When TTL is reached, the record is deleted automatically. A TTL of 0s means the record never expires. If absent, the default value provided by Aerospike will be used.

string

false

storage

Specifies how data for the Aerospike namespace will be stored.

StorageSpec

true

More info:

Validations

  • name must be a non-empty string having at most 23 characters.

  • replicationFactor must be an integer between 1 and nodeCount (if present).

  • memorySize must represent a positive quantity (if present).

  • defaultTTL must represent a non-negative quantity (if present).

  • storage must be non-null.

ℹ️

The minimum value for replicationFactor is 1 since, in Aerospike, the "master copy" counts as a replica. This contrasts with other databases where replicas are the number of aditional copies of data that should exist. Similarly, the maximum value is nodeCount since it is the maximum number of copies that may exist.

StorageSpec

The StorageSpec type specifies how data in a given Aerospike namespace will be stored.

Field

Description

Scheme

Required

type

The storage engine to be used for the namespace (file or device).

string

true

size

The size (gibibytes) of the persistent volume to use for storing data in this namespace, suffixed with G.

string

true

storageClassName

The name of the storage class to use to create persistent volumes.

string

false

persistentVolumeClaimTTL

The retention period (days) during which to keep PVCs after they are unmounted from an AerospikeCluster node, suffixed with d. Defaults to 0d, meaning the PVCs will be kept forever.

string

false

dataInMemory

Whether to always keep a copy of all Aerospike namespace data in memory. Defaults to false.

boolean

false

More info:

Validations

  • type must be one of file or device.

  • size must represent a positive quantity and cannot exceed 2000G (i.e., two terabytes).

  • storageClassName must be a non-empty string (if present).

  • persistentVolumeClaimTTL must represent a non-negative quantity (if present).

AerospikeNamespaceBackupSpec

The AerospikeNamespaceBackupSpec type specifies the configuration for a backup operation.

Field

Description

Scheme

Required

target

The specification of the Aerospike cluster and Aerospike namespace to backup.

TargetNamespace

true

storage

The specification of how the backup will be stored.

BackupStorageSpec

false

ttl

The retention period (days) during which to keep backup data in cloud storage, suffixed with d. Defaults to 0d, meaning the backup data will be kept forever.

string

false

More info:

Validations

  • target must be non-null.

  • ttl must represent a non-negative quantity.

Example

apiVersion: aerospike.travelaudience.com/v1alpha2
kind: AerospikeNamespaceBackup
metadata:
  name: example-aerospike-backup
  namespace: example-namespace
spec:
  target:
    cluster: example-aerospike-cluster
    namespace: example-aerospike-namespace
  storage:
    type: gcs
    bucket: bucket-name
    secret: secret-name
  ttl: 30d

AerospikeNamespaceRestoreSpec

The AerospikeNamespaceRestoreSpec type specifies the configuration for a restore operation.

Field

Description

Scheme

Required

target

The specification of the Aerospike cluster and namespace the backup will be restored to.

TargetNamespace

true

storage

The specification of how the backup should be retrieved.

BackupStorageSpec

false

More info:

Validations

  • target must be non-null.

Example

apiVersion: aerospike.travelaudience.com/v1alpha2
kind: AerospikeNamespaceRestore
metadata:
  name: example-aerospike-restore
  namespace: example-namespace
spec:
  target:
    cluster: example-aerospike-cluster
    namespace: example-aerospike-namespace
  storage:
    type: gcs
    bucket: bucket-name
    secret: secret-name

TargetNamespace

The TargetNamespace type specifies the Aerospike cluster and Aerospike namespace a single backup or restore operation will target.

Field

Description

Scheme

Required

cluster

The name of the Aerospike cluster against which the backup/restore operation will be performed.

string

true

namespace

The name of the Aerospike namespace to backup/restore.

string

true

Validations

  • cluster must be a non-empty string.

  • namespace must be a non-empty string.

BackupStorageSpec

The BackupStorageSpec type specifies the configuration for the storage of a backup.

Field

Description

Scheme

Required

type

The type of cloud storage to use for the backup (e.g., gcs)

string

true

bucket

The name of the bucket where the backup is stored.

string

true

secret

The name of the secret containing credentials to access the bucket.

string

true

secretNamespace

The Kubernetes namespace containing the secret with the credentials to access the bucket. Defaults to the namespace where the AerospikeCluster resource exists.

string

false

secretKey

The name of the file containing the credentials. Defaults to key.json.

string

false

Validations

  • type must be a supported type. Currently only gcs is supported.

  • bucket must be a non-empty string.

  • secret must be a non-empty string.

  • secretNamespace must be a non-empty string (if present).

  • secretKey must be a non-empty string (if present).

Status Types

The following base types have an associated status type whose structure mirrors the type’s spec:

  • AerospikeCluster

  • AerospikeNamespaceBackup

  • AerospikeNamespaceRestore

This mirroring happens because the status type is used to report information about a resource’s most recently observed status (as described by the Kubernetes API conventions). This allows users to know, at any given time, the actual state of the managed resources.

For instance, during a scale-up operation, an AerospikeCluster resource may show the following:

apiVersion: aerospike.travelaudience.com/v1alpha2
kind: AerospikeCluster
metadata:
  name: example-aerospike-cluster
  namespace: example-namespace
spec:
  version: "4.2.0.3"
  nodeCount: 5
  namespaces:
  - name: as-namespace-0
    replicationFactor: 2
    memorySize: 4G
    defaultTTL: 0s
    storage:
      type: file
      size: 4G
status:
  version: "4.2.0.3"
  nodeCount: 3
  namespaces:
  - name: as-namespace-0
    replicationFactor: 2
    memorySize: 4G
    defaultTTL: 0s
    storage:
      type: file
      size: 4G

This means that a size of 5 (i.e., .spec.nodeCount) was requested for the cluster but at the moment only 3 (i.e., .status.nodeCount) members have been created. When the size of the cluster meets the desired size the AerospikeCluster resource will report the following:

apiVersion: aerospike.travelaudience.com/v1alpha2
kind: AerospikeCluster
metadata:
  name: example-aerospike-cluster
  namespace: example-namespace
spec:
  version: "4.2.0.3"
  nodeCount: 5
  namespaces:
  - replicationFactor: 2
    memorySize: 4G
    defaultTTL: 0s
    storage:
      type: file
      size: 4G
status:
  version: "4.2.0.3"
  nodeCount: 5
  namespaces:
  - replicationFactor: 2
    memorySize: 4G
    defaultTTL: 0s
    storage:
      type: file
      size: 4G

Resources are acted upon by aerospike-operator until their .spec and .status fields match.

1. Even though the .spec.namespaces field must have exactly one element, it was decided to make it an array in order to allow extensibility of the API in the future.