Skip to main content

Aiven Operator for Kubernetes®

Aiven Operator for Kubernetes® allows users to manage Aiven services through the Kubernetes® API by using Custom Resource Definitions (CRD).

Supported services

Aiven Operator for Kubernetes® supports:

  • Aiven for Apache Kafka®
  • Aiven for Caching
  • Aiven for ClickHouse®
  • Aiven for OpenSearch®
  • Aiven for PostgreSQL®

Get started

Take your first steps by configuring the Aiven Operator and deploying a PostgreSQL® database.

Requirements

Install the Kubernetes® operator

  1. Optional: To manage the webhook TLS certificates used by our operator, install the cert-manager:

    kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
    tip

    You can also use the operator without cert-manager and the admission webhooks. To do so, skip this step and go to step 3 to install Helm.

    note
    • For GKE version >= 1.21 VPC users, add a firewall rule to explicitly allow ingress to port 9443 for admission webhook. See the Google Cloud docs.

    • If you are running a GKE Autopilot cluster in Google Cloud Platform, use GKE version >=1.21 and install cert-manager into the cert-manager namespace, as per this GitHub issue comment

  2. Verify the cert-manager installation by checking if the pods are up and running:

    kubectl get pod -n cert-manager

    Ensure the pod's status is Running.

  3. Add the Aiven Helm chart repository and update your local Helm information:

    helm repo add aiven https://aiven.github.io/aiven-charts
    helm repo update
  4. Install the CRD and the operator itself:

    helm install aiven-operator-crds aiven/aiven-operator-crds
    helm install aiven-operator aiven/aiven-operator
    tip

    To disable the admission webhooks, run:

    helm install aiven-operator aiven/aiven-operator --set webhooks.enabled=false
  5. Verify the installation by making sure the operator pod is running:

    kubectl get pod -l app.kubernetes.io/name=aiven-operator

Your pod's status should be Running.

Authenticating

Before creating a service, authenticate the operator with Aiven's API:

  1. Create an Aiven token.

  2. Create the Kubernetes secret in the namespace which is going to be used to create your Aiven services:

    kubectl create secret generic aiven-token --from-literal=token="<your-token>"

Deploy Aiven for PostgreSQL®

Create an Aiven for PostgreSQL service using the Custom Resource provided by the operator:

  1. Create a file named pg-sample.yaml with the content below, substituting the <your-project-name> with your Aiven project name:

    apiVersion: aiven.io/v1alpha1
    kind: PostgreSQL
    metadata:
    name: pg-sample
    spec:

    # gets the token from the `aiven-token` secret
    authSecretRef:
    name: aiven-token
    key: token

    # outputs the PostgreSQL connection on the `pg-connection` secret
    connInfoSecretTarget:
    name: pg-connection

    # add your Project name here
    project: <your-project-name>

    # cloud provider and plan of your choice
    # you can check all of the possibilities here https://aiven.io/pricing
    cloudName: google-europe-west1
    plan: startup-4

    # general Aiven configuration
    maintenanceWindowDow: friday
    maintenanceWindowTime: 23:00:00

    # specific PostgreSQL configuration
    userConfig:
    pg_version: '11'
  2. Apply the resource:

    kubectl apply -f pg-sample.yaml
  3. Verify the status of your service:

    kubectl get postgresqls.aiven.io pg-sample

    Once the STATE field has the value RUNNING, your service is ready for use.

Use the service

Once the service is up and running, you can deploy a pod to test the connection to PostgreSQL from Kubernetes.

  1. Create a file named pod-psql.yaml with the content below:

    apiVersion: v1
    kind: Pod
    metadata:
    name: psql-test-connection
    spec:
    restartPolicy: Never
    containers:
    - image: postgres:11-alpine
    name: postgres
    command: ['psql', '$(DATABASE_URI)', '-c', 'SELECT version();']

    # the pg-connection secret becomes environment variables
    envFrom:
    - secretRef:
    name: pg-connection

    The connection information in this case, the PostgreSQL service URI, is automatically created by the operator within a Kubernetes secret named after the value from the connInfoSecretTarget.name field.

  2. Apply the resource to create the pod and test the connection:

    kubectl apply -f pod-psql.yaml
  3. Check the logs with:

    kubectl logs psql-test-connection

An Aiven for PostgreSQL service deployed through Kubernetes.

Clean up

To destroy the resources created:

kubectl delete pod psql-test-connection
kubectl delete postgresqls.aiven.io pg-sample

To remove the operator and cert-manager:

helm uninstall aiven-operator
helm uninstall aiven-operator-crds
kubectl delete -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml