---
title: Integrate Kubernetes with Tiger Cloud | Tiger Data Docs
description: Automate deployment, scaling, and management of your containerized workloads
---

[Kubernetes](https://kubernetes.io/) is an open-source container orchestration system that automates the deployment, scaling, and management of containerized applications. You can connect Kubernetes to Tiger Cloud, and deploy TimescaleDB within your Kubernetes clusters.

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

## Prerequisites

To follow the steps on this page:

- **[Self-managed Kubernetes](https://kubernetes.io/docs/setup/) or a Kubernetes [Turnkey Cloud Solution](https://kubernetes.io/docs/setup/production-environment/turnkey-solutions/)**.
- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** for command-line interaction with your cluster.

## Integrate TimescaleDB in a Kubernetes cluster

- [Tiger Cloud](#tab-panel-612)
- [Self-hosted TimescaleDB](#tab-panel-613)

To connect your Kubernetes cluster to your Tiger Cloud service:

1. **Create a default namespace for your Tiger Cloud components**

   1. Create a namespace:

      Terminal window

      ```
      kubectl create namespace timescale
      ```

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

      Terminal window

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

   For more information, see [Kubernetes Namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).

2. **Create a Kubernetes secret that stores your Tiger Cloud service credentials**

   Update the following command with your [connection details](/docs/integrate/find-connection-details/index.md), then run it:

   Terminal window

   ```
   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 Tiger Cloud**

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

   - **Self-hosted Kubernetes**: If your cluster is behind a firewall or running on-premise, you may need to allow egress traffic to Tiger Cloud. Test connectivity using your [connection details](/docs/integrate/find-connection-details/index.md):

     Terminal window

     ```
     nc -zv <host> <port>
     ```

     If the connection fails, check your firewall rules.

4. **Create a Kubernetes deployment that can access your Tiger Cloud**

   Run the following command to apply the deployment:

   Terminal window

   ```
   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](/docs/integrate/find-connection-details/index.md) you added to `timescale-secret` in the `timescale` namespace:

      Terminal window

      ```
      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:

      Terminal window

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

   You start a `psql` session connected to your Tiger Cloud service.

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

To connect your Kubernetes cluster to self-hosted TimescaleDB running in the cluster:

1. **Create a default namespace for Tiger Data components**

   1. Create the Tiger Data namespace:

      Terminal window

      ```
      kubectl create namespace tigerdata
      ```

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

      Terminal window

      ```
      kubectl config set-context --current --namespace=tigerdata
      ```

   For more information, see [Kubernetes Namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/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: tigerdata-pvc
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   EOF
   ```

3. **Deploy TimescaleDB as a StatefulSet**

   By default, the [TimescaleDB HA Docker image](https://hub.docker.com/r/timescale/timescaledb-ha/tags) you are installing on Kubernetes uses the default PostgreSQL database, user and password. This image includes TimescaleDB and TimescaleDB Toolkit. To deploy TimescaleDB 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: tigerdata-storage
         volumes:
           - name: tigerdata-storage
             persistentVolumeClaim:
               claimName: tigerdata-pvc
   EOF
   ```

4. **Allow applications to connect by exposing TimescaleDB 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**

   Terminal window

   ```
   kubectl create secret generic tigerdata-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 TimescaleDB**

   Terminal window

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

7. **Test the database connection**

   1. Create and run a pod to verify database connectivity using your [connection details](/docs/integrate/find-connection-details/index.md) saved in `tigerdata-secret`:

      Terminal window

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

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

      Terminal window

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

   You see the PostgreSQL interactive terminal.

You have successfully integrated Kubernetes with Tiger Cloud.