Tembo Operator

The Tembo Operator is a Kubernetes Operator used for creating, updating, and deleting PostgreSQL (Postgres) instances.

The key differentiators of the Tembo Operator are:

• Unique extension management experience
• Concept of Stacks
• Easily integrate Apps to run alongside Postgres

Table of Contents

1. Quick start
   1. Cluster operations
2. Examples
   1. Trying out Postgres extensions
   2. Trying out Tembo Stacks
3. Observability with curl
4. Observability with OpenTelemetry and Jaeger

Quick Start

While it's fairly straightforward to get started running the Tembo Operator locally, there are prerequisites that you'll need before getting started. For an exhaustive list, please refer to the project's contributing guide.

Cluster Operations

To destroy any existing cluster and start the containers needed for a new one, simply run:

just start-kind

In addition to starting the cluster, several necessary dependencies are installed by subtasks. Check out the definition in the justfile if you're curious, it's all pretty composable.

Once the kind cluster has been started, you can start a local copy of the Tembo Operator to use it. Again, it's pretty easy:

just run

Examples

With the cluster running, you're ready to test some of the built-in features of the Tembo Operator.

1. Trying out Postgres Extensions

💡 The following steps assume you have gone through the quick start section.

Start by applying a YAML template of your choosing, hosted at ./yaml:

kubectl apply -f yaml/sample-standard.yaml

Once established, psql into the pod. This will require a password, the instructions of which are outlined in the CONTRIBUTING.md file's Connect via psql section.

psql postgres://postgres:$PGPASSWORD@sample-standard.localhost:5432

This will allow you to see the enabled extensions with:

\dx

As well as the to-be-enabled extensions that have already been installed:

SELECT * FROM pg_available_extensions;

Go ahead and exit Postgres with \q and the pod with Ctl-D.

Now try to exec into the pod via:

kubectl exec -it sample-standard-1 -- /bin/bash

As mentioned above, the Tembo Operator comes pre-packaged with added Postgres extension management. This comes in the form of the Trunk extension registry, which can be used from within the Kubernetes pod.

Try running the following:

trunk install pgmq

💡 Note that you can choose to install any extension found within the Trunk registry.

Considering that you should still be in the pod, simply run psql and you should find yourself in the Postgres instance.

As before, try running

SELECT * FROM pg_available_extensions WHERE name = 'pgmq'

You should see the extension in the results, from which you can run to enable:

CREATE EXTENSION pgmq CASCADE;

2. Trying out Tembo Stacks

In the above example, we utilize the sample-standard.yaml file, but there are others that offer distinct configurations. Check out the others in the yaml directory. Here are some select options to apply just as sample-standard.yaml was:

• Try out the Message Queue Stack with sample-message-queue.yaml.
• Try out the OLAP Stack with sample-olap.yaml.
• Try out the MongoAlternative Stack with sample-document.yaml.

Observability with curl

In either of the above scenarios, your app is listening on port 8080, and it will observe events.

The reconciler will run and write the status object on every change. You should see results in the logs of the pod, or on the .status object outputs of kubectl get coredb -o yaml.

Webapp Output

The sample web server exposes some example metrics and debug information you can inspect with curl.

$ kubectl apply -f yaml/sample-coredb.yaml
$ curl 0.0.0.0:8080/metrics
# HELP cdb_controller_reconcile_duration_seconds The duration of reconcile to complete in seconds
# TYPE cdb_controller_reconcile_duration_seconds histogram
cdb_controller_reconcile_duration_seconds_bucket{le="0.01"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="0.1"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="0.25"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="0.5"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="1"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="5"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="15"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="60"} 1
cdb_controller_reconcile_duration_seconds_bucket{le="+Inf"} 1
cdb_controller_reconcile_duration_seconds_sum 0.013
cdb_controller_reconcile_duration_seconds_count 1
# HELP cdb_controller_reconciliation_errors_total reconciliation errors
# TYPE cdb_controller_reconciliation_errors_total counter
cdb_controller_reconciliation_errors_total 0
# HELP cdb_controller_reconciliations_total reconciliations
# TYPE cdb_controller_reconciliations_total counter
cdb_controller_reconciliations_total 1
$ curl 0.0.0.0:8080/
{"last_event":"2019-07-17T22:31:37.591320068Z"}

Observability with OpenTelemetry and Jaeger

OpenTelemetry is an observability framework that focuses on generation, collection, management, and export of telemetry. Jaeger, on the other hand, is an observability platform with a companion UI that ingests the OpenTelemetry data. By integrating both into the Tembo Operator, users are able to gain more insights into their operations.

If you haven't already, you can start a local Kubernetes cluster by running the following:

just start-kind

Once complete, simply run:

just run-telemetry

From there, you're all set to visit the below URL and navigate your telemetry:

http://localhost:16686