Aiven Operator for Kubernetes®

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


Only Aiven for PostgreSQL® and Aiven for Apache Kafka® are supported at this time.

Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications. Kubernetes Operators are software extensions to Kubernetes that make use of custom resources to manage applications and their components. Kubernetes website.

Getting started

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


Access to a Kubernetes cluster where you can run the operator. To try it out locally, we recommend using kind. You can install it by following their official documentation.

We will be installing the operator with Helm. Follow their official instructions to install it if you don’t have it already.

You’ll also need an Aiven account. If you don’t have one yet, sign up for Aiven (and enjoy a free trial for new accounts). Once you have your account set, please generate and note down the authentication token and your project name, they will be used to authenticate the Kubernetes operator with Aiven’s API.

Install the operator

Once you have a Kubernetes cluster and an Aiven authentication token, we can proceed to install the operator.

Install the cert-manager with the command below. It is used to manage the webhook TLS certificates used by our operator.


You can use the operator without cert-manager and the admission webhooks, skip this step and move on to the Helm chart section.


If you are running a GKE “Autopilot” cluster in Google Cloud Platform, you will need to be using GKE version >=1.21 and install cert-manager into the cert-manager namespace, as per this GitHub issue comment

kubectl apply -f

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

kubectl get pod -n cert-manager

When you see pods in the list with their status showing “Running”, then you are ready to proceed.

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

helm repo add aiven
helm repo update

Now let’s install the CRDs and then the operator itself:

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


You can use helm install aiven-operator aiven/aiven-operator --set webhooks.enabled=false to disable the admission webhooks.

Verify the installation by making sure the operator pod is running with the get pod command:

kubectl get pod -l

If your pod is listed with status “Running” then all is well.


Before creating a service, we need to authenticate the operator with Aiven’s API. To do so, create the Kubernetes secret with the command below, substituting the <your-token-here> with the authentication token generated in the “Requirements” section above. This needs to be created 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-here>"

Deploying Aiven for PostgreSQL

It’s showtime! Let’s create an Aiven for PostgreSQL service using the Custom Resource provided by the operator. Create a file named pg-sample.yaml with the content below, substituting the <your-project-name> with your Aiven project name. Take a look at the commented lines to understand better what each field represents.

kind: PostgreSQL
  name: pg-sample

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

  # outputs the PostgreSQL connection on the `pg-connection` secret
    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
  cloudName: google-europe-west1
  plan: startup-4

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

  # specific PostgreSQL configuration
    pg_version: '11'

Apply the resource with the command below:

kubectl apply -f pg-sample.yaml

You can verify the status of your service with the following command.

kubectl get pg-sample

Check the output of the command for your service; once the STATE field has the value RUNNING, it is ready to use.

Using the service

Once the service is up and running (you can see your database in the Aiven web console as well at this point) let’s deploy a pod to test the connection to PostgreSQL from Kubernetes.

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

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

      # the pg-connection secret becomes environment variables
      - 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 field.

Go ahead and run apply to create the pod and test the connection:

kubectl apply -f pod-psql.yaml

It will run, output the PostgreSQL version and terminate. We can see the logs with the following command:

kubectl logs psql-test-connection

Well done, you have an Aiven for PostgreSQL service deployed through Kubernetes.

Clean up

To destroy the resources created, execute the following commands:

kubectl delete pod psql-test-connection
kubectl delete pg-sample

To remove the operator and cert-manager (if installed), use the following:

helm uninstall aiven-operator
helm uninstall aiven-operator-crds
kubectl delete -f

Learn more

Check out these resources to learn more about Kubernetes and our operator:

Get involved

If you have any comments or want to contribute to the tool, please join us on the GitHub repository.