Integrate Kubernetes with Tiger Cloud

Automate deployment, scaling, and management of your containerized workloads

Kubernetes is an open-source container orchestration system that automates the deployment, scaling, and management of containerized applications. You can connect Kubernetes to , and deploy within your Kubernetes clusters.

This guide explains how to connect a Kubernetes cluster to , configure persistent storage, and deploy in your kubernetes cluster.

Prerequisites

To follow the steps on this page:

• Install self-managed Kubernetes or sign up for a Kubernetes Turnkey Cloud Solution.
• Install kubectl for command-line interaction with your cluster.

Integrate TimescaleDB in a Kubernetes cluster

Tab Title

To connect your Kubernetes cluster to your :

1. Create a default namespace for your components

   1. Create a namespace:

      kubectl create namespace timescale
      

   2. Set this namespace as the default for your session:

      kubectl config set-context --current --namespace=timescale
      

   For more information, see Kubernetes Namespaces.

2. Create a Kubernetes secret that stores your credentials

   Update the following command with your connection details, then run it:

   kubectl create secret generic timescale-secret \
    --from-literal=PGHOST=<host> \
    --from-literal=PGPORT=<port> \
    --from-literal=PGDATABASE=<dbname> \
    --from-literal=PGUSER=<user> \
    --from-literal=PGPASSWORD=<password>
   

3. Configure network access to

   • Managed Kubernetes: outbound connections to external databases like work by default. Make sure your cluster’s security group or firewall rules allow outbound traffic to IP.

   • Self-hosted Kubernetes: If your cluster is behind a firewall or running on-premise, you may need to allow egress traffic to . Test connectivity using your connection details:

     nc -zv <host> <port>
     

     If the connection fails, check your firewall rules.

4. Create a Kubernetes deployment that can access your

   Run the following command to apply the deployment:

   kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: timescale-app
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: timescale-app
     template:
       metadata:
         labels:
           app: timescale-app
       spec:
         containers:
         - name: timescale-container
           image: postgres:latest
           envFrom:
             - secretRef:
                 name: timescale-secret
   EOF
   

5. Test the connection

   1. Create and run a pod that uses the connection details you added to timescale-secret in the timescale namespace:

      kubectl run test-pod --image=postgres --restart=Never \
       --env="PGHOST=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGHOST}' | base64 --decode)" \
       --env="PGPORT=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPORT}' | base64 --decode)" \
       --env="PGDATABASE=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGDATABASE}' | base64 --decode)" \
       --env="PGUSER=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGUSER}' | base64 --decode)" \
       --env="PGPASSWORD=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPASSWORD}' | base64 --decode)" \
       -- sleep infinity
      

   2. Launch a psql shell in the test-pod you just created:

      kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"
      

   You start a psql session connected to your .

Tab Title

Running on Kubernetes is similar to running . This procedure outlines the steps for a non-distributed system.

To connect your Kubernetes cluster to running in the cluster:

1. Create a default namespace for components

   1. Create the namespace:

      kubectl create namespace timescale
      

   2. Set this namespace as the default for your session:

      kubectl config set-context --current --namespace=timescale
      

   For more information, see Kubernetes Namespaces.

2. Set up a persistent volume claim (PVC) storage

   To manually set up a persistent volume and claim for self-hosted Kubernetes, run the following command:

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: timescale-pvc
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   EOF
   

3. Deploy as a StatefulSet

   By default, the HA Docker image you are installing on Kubernetes uses the default database, user and password. This image includes and . To deploy on Kubernetes, run the following command:

   kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: timescaledb
   spec:
     serviceName: timescaledb
     replicas: 1
     selector:
       matchLabels:
         app: timescaledb
     template:
       metadata:
         labels:
           app: timescaledb
       spec:
         containers:
           - name: timescaledb
             image: 'timescale/timescaledb-ha:pg18'
             env:
               - name: POSTGRES_USER
                 value: postgres
               - name: POSTGRES_PASSWORD
                 value: postgres
               - name: POSTGRES_DB
                 value: postgres
               - name: PGDATA
                 value: /var/lib/postgresql/data/pgdata
             ports:
               - containerPort: 5432
             volumeMounts:
               - mountPath: /var/lib/postgresql/data
                 name: timescale-storage
         volumes:
           - name: timescale-storage
             persistentVolumeClaim:
               claimName: timescale-pvc
   EOF
   

4. Allow applications to connect by exposing within Kubernetes

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Service
   metadata:
     name: timescaledb
   spec:
     selector:
       app: timescaledb
     ports:
       - protocol: TCP
         port: 5432
         targetPort: 5432
     type: ClusterIP
   EOF
   

5. Create a Kubernetes secret to store the database credentials

   kubectl create secret generic timescale-secret \
   --from-literal=PGHOST=timescaledb \
   --from-literal=PGPORT=5432 \
   --from-literal=PGDATABASE=postgres \
   --from-literal=PGUSER=postgres \
   --from-literal=PGPASSWORD=postgres
   

6. Deploy an application that connects to

   kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: timescale-app
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: timescale-app
     template:
       metadata:
         labels:
           app: timescale-app
       spec:
         containers:
         - name: timescale-container
           image: postgres:latest
           envFrom:
             - secretRef:
                 name: timescale-secret
   EOF
   

7. Test the database connection

   1. Create and run a pod to verify database connectivity using your connection details saved in timescale-secret:

      kubectl run test-pod --image=postgres --restart=Never \
      --env="PGHOST=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGHOST}' | base64 --decode)" \
      --env="PGPORT=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPORT}' | base64 --decode)" \
      --env="PGDATABASE=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGDATABASE}' | base64 --decode)" \
      --env="PGUSER=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGUSER}' | base64 --decode)" \
      --env="PGPASSWORD=$(kubectl get secret timescale-secret -o=jsonpath='{.data.PGPASSWORD}' | base64 --decode)" \
      -- sleep infinity
      

   2. Launch the interactive shell within the created test-pod:

      kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"
      

   You see the interactive terminal.

You have successfully integrated Kubernetes with .