198 releases (51 breaking)
new 0.51.0 | Oct 22, 2024 |
---|---|
0.50.1 | Sep 27, 2024 |
0.49.5 | Jul 16, 2024 |
0.43.2 | Mar 30, 2024 |
0.0.1 | May 22, 2023 |
#211 in Database interfaces
891 downloads per month
Used in 2 crates
1.5MB
28K
SLoC
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
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
Dependencies
~82MB
~1.5M SLoC