a9s CLI

anynines provides a command line tool called a9s to facilitate application development, devops tasks and interact with selected anynines products.

Use Cases

The a9s CLI can be used to install and use the following stacks:

a8s Stack

• Install a local Kubernetes cluster (minikube or kind).
• Install the cert-manager.
• Install a local Minio object store for storing Backups.
• Install the a8s PostgreSQL Operator PostgreSQL supporting
  • creating dedicated PostgreSQL clusters with
    • synchronous and asynchronous streaming replication.
    • automatic failure detection and automatic failover.
  • backup and restore capabilities storing backups in an S3 compatible object store such as AWS S3 or Minio.
  • ability to easily create database users and Kubernetes Secrets by using the Service Bindings abstraction
• Easily apply .sql files and SQL commands to PostgreSQL clusters.

Prerequisites

• Using the backup/restore feature of a8s PostgreSQL requires an S3 compatible endpoint.
• Install Go (if you want go env to identify your OS and arch).
• Install Git.
• Install Docker.
• Install Kubectl.
• Install Kind and/or Minikube.
• Install the cert-manager CLI.

Installing the CLI

In order to install the a9s CLI execute the following shell script:

RELEASE=$(curl -L -s https://a9s-cli-v2-fox4ce5.s3.eu-central-1.amazonaws.com/stable.txt); OS=$(go env GOOS); ARCH=$(go env GOARCH); curl -fsSL -o a9s https://a9s-cli-v2-fox4ce5.s3.eu-central-1.amazonaws.com/releases/$RELEASE/a9s-$OS-$ARCH
    
sudo chmod 755 a9s
sudo mv a9s /usr/local/bin

This will download the a9s binary suitable for your architecture and move it to /usr/local/bin. Depending on your system you have to adjust the PATH variable or move the binary to a folder that's already in the PATH.

Using the CLI

a9s

Creating a Local a8s Postgres Cluster

Create a local Kubernetes cluster using Minikube or Kind, install a8s PostgreSQL including its dependencies as well as a local Minio object store.

Get ready for local development of applications with PostgreSQL and/or experimentation with a8s Postgres by issuing the command:

a9s create cluster a8s

Recommended is 12 GB of free memory for the creation of three cluster nodes with each 4 GB. The number of nodes and memory size can be adjusted.

Cold-Run

When creating a cluster for the first time, a few setup steps will have to be taken which need to be performed only once:

1. Setting up a working directory for the use with the a9s CLI. This step asks for your confirmation of the proposed directory.
2. Configuring the access credentials for the S3 compatible object store which is needed to use the backup/restore feature of a8s Postgres. This step is performed automatically.
3. Cloning deployment resources required by the a9s CLI to create a cluster. This step is performed automatically.

Setting Up a Working Directory

The working directory is where are a9s CLI related resources will go. This includes yaml specifications being cloned from remote repositories, but also those generated by the a9s CLI for your convenience.

Once established, the working directory is stored in the ~/.a9s configuration file.

The default working directory is ~/a9s.

Alternatively, provide a custom working directory at the corresponding prompt.

Configuring the Backup Store

A non-prod Minio object store is installed in your local Kubernetes cluster and is automatically configured as the default backup store for a8s PostgreSQL backups.

If you want to use an alternative backup store, see a9s create cluster a8s --help for the defaults of your particular CLI version and list of configuration options.

Most S3 compatible object stores, including AWS S3 itself of course, should work.

Skip Checking Prerequisites

It is possible to skip the verification of prerequisites. This includes skipping the search for: required shell commands, a running Docker daemon and a running Kubernetes cluster.

In order to skip precheck use the --no-precheck option:

a9s create cluster a8s --no-precheck

Number of Kubernetes Nodes

Specifying the number of Nodes in the Kubernetes cluster:

a9s create cluster a8s --cluster-nr-of-nodes 1

Cluster Memory

Specifying the memory of each Node of the Kubernetes cluster:

a9s create cluster a8s --cluster-memory 4gb

Deployment Version

The deployment version refers to the version of manifests used for installing software. Deployment versions are managed by anynines in a Git repository. The deployment version option allows you to select a particular version of the deployment manifests identified by Git tags.

Select a particular release by providing the --deployment-version parameter:

a9s create cluster a8s --deployment-version v1.2.0

Use:

a9s create cluster a8s --deployment-version latest

To get the latest, untagged version of the deployment manifests.

Kubernetes Provider

When creating a Kubernetes cluster, the mechanism to manage the cluster can be selected by specifying the --provider option:

a9s create cluster a8s -p kind 
a9s create cluster a8s -p minikube (default)

Follow the instructions to learn about available sub commands.

Backup Infrastructure Region

When using the backup and restore functionality, a backup infrastructure region must be specified by using the --backup-region option:

a9s create cluster a8s --backup-region us-east-1

Note: By default, an existing backup-config.yaml will be used. Hence, if you intend to change your backup config, remove the existing backup-config.yaml, first:

rm a8s-deployment/deploy/a8s/backup-config/backup-store-config.yaml

Unattended Mode

It is possible to skip all yes-no questions by enabling the unattended mode by passing the -y or --yes flag:

a9s create cluster a8s --yes

Printing the Working Directory

The working directory is stored in the ~/.a8s configuration file. The working directory contains all resources downloaded and generated by the a9s CLI.

To print the working directory execute:

a9s cluster pwd

a8s PostgreSQL

A selected subset of the a8s PostgreSQL features are available through the a9s CLI.

Creating a PostgreSQL Service Instance

Creating a service instance with the name sample-pg-cluster:

a9s create pg instance --name sample-pg-cluster

The generated YAML specification will be stored in the usermanifests.

Creating PostgreSQL Service Instance YAML Without Applying it

a9s create pg instance --name sample-pg-cluster --no-apply

The generated YAML specification will be stored in the usermanifests but kubectl apply won't be executed.

Creating a Custom PostgreSQL Service Instance

The command:

a9s create pg instance --api-version v1beta3 --name sample-pg-cluster --namespace default --replicas 3 --requests-cpu 200m --limits-memory 200Mi --service-version 14 --volume-size 2Gi

Will generate a YAML spec called usermanifests/my-pg-instance.yaml with the following content:

apiVersion: postgresql.anynines.com/v1beta3
kind: Postgresql
metadata:
  name: my-pg
spec:
  replicas: 3
  resources:
    limits:
      memory: 200m
    requests:
      cpu: 200m
  version: 14
  volumeSize: 2Gi

Deleting a PostgreSQL Service Instance

Deleting a service instance with the name sample-pg-cluster:

a9s delete pg instance --name sample-pg-cluster

Or by providing an explicit namespace:

a9s delete pg instance --name sample-pg-cluster -n default

Note: If the service instance doesn't exist, a warning is printed and the command exists with the return code 0 as the desired state of the service instance being delete is reached.

Applying a SQL File to a PostgreSQL Service Instance

Uploading a SQL file, executing it using psql and deleting the file can be done with:

a9s pg apply --file /path/to/sql/file --service-instance sample-pg-cluster

The file is uploaded to the current primary pod of the service instance.

Note: Ensure that, during the execution of the command, there is no change of the primary node for a given clustered service instance as otherwise the file upload may fail or target the wrong pod.

Use --yes to skip the confirmation prompt.

a9s pg apply --file /path/to/sql/file --service-instance sample-pg-cluster --yes

Use --no-delete to leave the file in the pod:

a9s pg apply --file /path/to/sql/file --service-instance sample-pg-cluster --no-delete

Applying a SQL Statement to a PostgreSQL Service Instance

Applying a SQL statement on the primary pod of a PostgreSQL service instance can be accomplished with:

a9s pg apply -i sample-pg-cluster --sql "select count(*) from posts" --yes

Creating a Backup of a PostgreSQL Service Instance

a9s create pg backup --name sample-pg-cluster-backup-1 -i sample-pg-cluster

Restoring a Backup of PostgreSQL Service Instance

a9s create pg restore --name sample-pg-cluster-restore-1 -b sample-pg-cluster-backup-1 -i sample-pg-cluster

Creating a PostgreSQL Service Binding

A Service Binding is an entity facilitating the secure consumption of a service instance. By creating a service instance, a Postgres user is created along with a corresponding Kubernetes Secret.

a9s create pg servicebinding --name sb-clustered-1 -i sample-pg-cluster

Will therefore create a Kubernetes Secret named sb-clustered-1-service-binding and provide the following keys containing everything an application needs to connect to the PostgreSQL service instance:

• database
• instance_service
• password
• username

Cleaning Up

In order to delete the cluster run:

a9s delete cluster a8s

Note: This will not delete config files.

Config files are stored in the cluster working directory.

They can be removed with:

rm -rf $( a9s cluster pwd )