StackGres

https://stackgres.io/doc/
Admin
StackGres is an enterprise-grade full-stack PostgreSQL distribution and operator for Kubernetes that...
Tokens:576,589
Snippets:5,126
Trust Score:8.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example InstallPlan Output

Source: https://stackgres.io/doc/latest/install/operatorhub

Shows the expected output after successfully patching and installing the operator.

```text
installplan.operators.coreos.com/install-66964 patched
installplan.operators.coreos.com/install-66964 condition met
```

--------------------------------

### Install ZFS Utilities

Source: https://stackgres.io/doc/latest/runbooks/backup-large-databases

Install the ZFS utilities on the host machine.

```bash
apt install zfsutils-linux
```

--------------------------------

### StackGres Resources Output Example

Source: https://stackgres.io/doc/latest/administration/uninstall

Example output showing various StackGres resources.

```text
NAME                                                      AGE
sgobjectstorage.stackgres.io/backup-config-minio-backend   162m

NAME                                                     AGE
sginstanceprofile.stackgres.io/instance-profile-medium   148m
sginstanceprofile.stackgres.io/instance-profile-nano     162m
```

--------------------------------

### Install Minikube binary

Source: https://stackgres.io/doc/latest/runbooks/metis-stackgres

Installs the downloaded Minikube binary to /usr/local/bin/minikube using sudo.

```bash
sudo install minikube-linux-amd64 /usr/local/bin/minikube

```

--------------------------------

### Install blockio.yaml on node

Source: https://stackgres.io/doc/latest/runbooks/io-isolation

Install the blockio configuration file on each database node.

```bash
install -m 0644 blockio.yaml /etc/containerd/blockio.yaml
```

--------------------------------

### Approve InstallPlan and Wait for Installation

Source: https://stackgres.io/doc/latest/install/operatorhub

Retrieves the InstallPlan, approves it, and waits for the installation to complete.

```bash
INSTALL_PLAN="$(kubectl get -n openshift-operators installplan -o name)"
kubectl patch -n openshift-operators "$INSTALL_PLAN" --type merge -p 'spec: { approved: true }'
kubectl wait -n openshift-operators "$INSTALL_PLAN" --for condition=Installed
```

--------------------------------

### SGShardedCluster Pods Output Example

Source: https://stackgres.io/doc/latest/administration/uninstall

Example output showing running pods for an SGShardedCluster.

```text
NAME                    READY   STATUS    RESTARTS   AGE
my-db-cluster-coord-0   5/5     Running   1          2m29s
my-db-cluster-worker0-0  5/5     Running   1          99s
my-db-cluster-worker1-1  5/5     Running   0          74s
```

--------------------------------

### Keycloak Integration Example

Source: https://stackgres.io/doc/latest/administration/security/oidc-authentication

Example configuration for integrating StackGres with a Keycloak identity provider.

```yaml
apiVersion: stackgres.io/v1
kind: SGConfig
metadata:
  name: stackgres-config
  namespace: stackgres
spec:
  authentication:
    oidc:
      authServerUrl: https://keycloak.example.com/realms/stackgres
      clientId: stackgres-console
      credentialsSecret: keycloak-client-secret
      tlsVerification: required
```

--------------------------------

### SGCluster Pods Output Example

Source: https://stackgres.io/doc/latest/administration/uninstall

Example output showing running pods for an SGCluster.

```text
NAME              READY   STATUS    RESTARTS   AGE
my-db-cluster-0   5/5     Running   1          2m29s
my-db-cluster-1   5/5     Running   1          99s
my-db-cluster-2   5/5     Running   0          74s
```

--------------------------------

### PendingRestart output example

Source: https://stackgres.io/doc/latest/administration/rollout/manual-restart

Example output showing a cluster in the default namespace with a pending restart.

```text
default.my-cluster PendingRestart=True
```

--------------------------------

### SGDistributedLogs Pods Output Example

Source: https://stackgres.io/doc/latest/administration/uninstall

Example output showing running pods for an SGDistributedLogs cluster.

```text
NAME              READY   STATUS    RESTARTS   AGE
my-dl-cluster-0   5/5     Running   1          2m59s
```

--------------------------------

### Install StackGres operator with monitoring

Source: https://stackgres.io/doc/latest/install/helm

Installs the StackGres operator with integration of an existing Prometheus/Grafana monitoring stack. This example assumes a Kube Prometheus Stack is already installed in the 'monitoring' namespace. The installation will fail if the monitoring setup is not present.

```bash
helm install --create-namespace --namespace stackgres stackgres-operator \
 --set grafana.autoEmbed=true \
 --set-string grafana.webHost=prometheus-grafana.monitoring \
 --set-string grafana.secretNamespace=monitoring \
 --set-string grafana.secretName=prometheus-grafana \
 --set-string grafana.secretUserKey=admin-user \
 --set-string grafana.secretPasswordKey=admin-password \
 stackgres-charts/stackgres-operator
```

--------------------------------

### Example InstallPlan Output

Source: https://stackgres.io/doc/latest/install/operatorhub

Shows the expected output after the InstallPlan condition is met.

```text
installplan.operators.coreos.com/install-66964 condition met
```

--------------------------------

### Install Kube Prometheus Stack

Source: https://stackgres.io/doc/latest/install/helm

Installs the Kube Prometheus Stack Helm chart, which is required for the monitoring integration example. Run these commands before installing StackGres with monitoring.

```bash
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add stable https://charts.helm.sh/stable
helm repo update

helm install --create-namespace --namespace monitoring \
 --set grafana.enabled=true \
 prometheus prometheus-community/kube-prometheus-stack
```

--------------------------------

### Full Patroni Customization Example

Source: https://stackgres.io/doc/latest/administration/patroni/configuration

A comprehensive example showing both dynamicConfig and initialConfig defined within an SGCluster.

```yaml
apiVersion: stackgres.io/v1
kind: SGCluster
metadata:
  name: production-cluster
spec:
  instances: 3
  postgres:
    version: '16'
  configurations:
    patroni:
      dynamicConfig:
        ttl: 45
        loop_wait: 10
        retry_timeout: 10
        maximum_lag_on_failover: 1048576
        postgresql:
          pg_hba:
          - host all all 10.0.0.0/8 md5
      initialConfig:
        postgresql:
          callbacks:
            on_role_change: /bin/bash -c 'echo "Role changed"'
          pg_ctl_timeout: 120
```

--------------------------------

### Configure Collector via Helm values.yaml

Source: https://stackgres.io/doc/latest/administration/monitoring/opentelemetry-collector

Example configuration for the OpenTelemetry Collector using Helm values during operator installation.

```yaml
# values.yaml
collector:
  enabled: true
  config:
    receivers:
      prometheus:
        config:
          scrape_configs:
            - job_name: 'stackgres'
              scrape_interval: 30s
    exporters:
      prometheus:
        endpoint: "0.0.0.0:9090"
    service:
      pipelines:
        metrics:
          receivers: [prometheus]
          exporters: [prometheus]
```

--------------------------------

### Output of kubectl get pods for StackGres cluster

Source: https://stackgres.io/doc/latest/administration/patroni

Example output from listing the StackGres cluster pods, showing three running pods.

```text
NAME          READY   STATUS    RESTARTS   AGE
stackgres-0   5/5     Running   0          163m
stackgres-1   5/5     Running   0          163m
stackgres-2   5/5     Running   0          162m

```

--------------------------------

### Example blockio.yaml configuration

Source: https://stackgres.io/doc/latest/runbooks/io-isolation

A sample configuration defining three I/O performance tiers (1k, 5k, and 20k IOPS) using glob patterns for physical block devices.

```yaml
# blockio.yaml
Classes:

  local-lvm-nvme-io-1k:
    - Devices: ["/dev/sd[b-z]", "/dev/nvme[1-9]n[0-9]"]
      ThrottleReadIOPS: 1k
      ThrottleWriteIOPS: 1k
      ThrottleReadBps: 50M
      ThrottleWriteBps: 50M

  local-lvm-nvme-io-5k:
    - Devices: ["/dev/sd[b-z]", "/dev/nvme[1-9]n[0-9]"]
      ThrottleReadIOPS: 5k
      ThrottleWriteIOPS: 5k
      ThrottleReadBps: 200M
      ThrottleWriteBps: 200M

  local-lvm-nvme-io-20k:
    - Devices: ["/dev/sd[b-z]", "/dev/nvme[1-9]n[0-9]"]
      ThrottleReadIOPS: 20k
      ThrottleWriteIOPS: 20k
      ThrottleReadBps: 800M
      ThrottleWriteBps: 800M
```

--------------------------------

### List all streams with kubectl get sgstream

Source: https://stackgres.io/doc/latest/administration/cdc-streaming/monitoring-streams

Use this command to list all SGStream resources. The example output shows the stream name, status, and age.

```bash
# List all streams
kubectl get sgstream

# Example output:
# NAME               STATUS    AGE
# migration-stream   Running   2h
# backup-stream      Failed    1d

```

--------------------------------

### Pre-create LVs for static provisioning

Source: https://stackgres.io/doc/latest/runbooks/io-isolation

Use this loop on each database node during provisioning to create a fixed number of logical volumes for static PV binding.

```bash
# on each db node, at provisioning time:
for i in $(seq 1 16); do
  lvcreate -L 500G -n local-lvm-nvme-data-${i} myvg
done
```

--------------------------------

### Watch pod status after installation

Source: https://stackgres.io/doc/latest/runbooks/supabase-stackgres

Shows the expected output of `kubectl get pods --watch` after the Supabase resources are created, listing all running pods.

```bash
$ kubectl get pods --watch
NAME                                      READY   STATUS    RESTARTS   AGE
demo-supabase-auth-6b8c448b6b-njsh6       1/1     Running   0          2m
demo-supabase-kong-7c5bdfc9bf-cfb5q       1/1     Running   0          2m
demo-supabase-meta-54d7b47b89-sdzcb       1/1     Running   0          2m
demo-supabase-realtime-6c4dc64668-cxxfd   1/1     Running   0          2m
demo-supabase-rest-794594bb5f-tz4bh       1/1     Running   0          2m
demo-supabase-storage-6c766bb9cc-r8psb    1/1     Running   0          2m
demo-supabase-studio-59c86bd59b-k4p5w     1/1     Running   0          2m
supabase-db-0                             6/6     Running   0          3m
supabase-db-1                             6/6     Running   0          2m

```

--------------------------------

### Validation: Expected pods output

Source: https://stackgres.io/doc/latest/administration/monitoring

Output of `kubectl get pods -n monitoring` after a successful setup, showing running Grafana, Prometheus, and related components.

```bash
# kubectl get pods -n monitoring
NAME                                                      READY   STATUS    RESTARTS   AGE
alertmanager-prometheus-kube-prometheus-alertmanager-0    2/2     Running   0          20m
grafana-7575c4b7b5-2cbvw                                  1/1     Running   0          14m
prometheus-grafana-5b458bf78c-tpqrl                       2/2     Running   0          20m
prometheus-kube-prometheus-operator-576f4bf45b-w5j9m      2/2     Running   0          20m
prometheus-kube-state-metrics-c65b87574-tsx24             1/1     Running   0          20m
prometheus-prometheus-kube-prometheus-prometheus-0        3/3     Running   1          20m
prometheus-prometheus-node-exporter-jbsm2                 1/1     Running   0          20m
```

--------------------------------

### Minikube cluster creation output

Source: https://stackgres.io/doc/latest/runbooks/metis-stackgres

Example output from creating a Minikube cluster, showing the cluster startup process and configuration details.

```text
* minikube v1.32.0 on Amazon 2
* Automatically selected the docker driver. Other choices: none, ssh
* Using Docker driver with root privileges
* Starting control plane node minikube in cluster minikube
* Pulling base image ...
* Creating docker container (CPUs=2, Memory=3900MB) ...
* Preparing Kubernetes v1.28.3 on Docker 24.0.7 ...
  - Generating certificates and keys ...
  - Booting up control plane ...
  - Configuring RBAC rules ...
* Configuring bridge CNI (Container Networking Interface) ...
* Verifying Kubernetes components...
  - Using image gcr.io/k8s-minikube/storage-provisioner:v5
* Enabled addons: storage-provisioner, default-storageclass
* Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

```

--------------------------------

### ClusterRole Example: stackgres-reader

Source: https://stackgres.io/doc/latest/api/rbac

Defines a ClusterRole named stackgres-reader with read-only permissions (get, list) on core, storage, apiextensions, and StackGres resources. Required because StackGres handles resources in different namespaces.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: stackgres-reader
rules:
- apiGroups: [""]
  resources:
    - namespaces
    - pods
    - secrets
  verbs: ["get", "list"]
- apiGroups: ["storage.k8s.io"]
  resources:
    - storageclasses
  verbs: ["get", "list"]
- apiGroups: ["apiextensions.k8s.io"]
  resources:
    - customresourcedefinitions
  verbs: ["get", "list"]
- apiGroups: ["stackgres.io"]
  resources:
    - sgclusters
    - sgpgconfigs
    - sgbackupconfigs
    - sgbackups
    - sgdistributedlogs
    - sginstanceprofiles
    - sgpoolconfigs
    - sgobjectstorages
    - sgscripts
  verbs: ["get", "list"]

```

--------------------------------

### Start REST API Locally

Source: https://stackgres.io/doc/latest/developer/stackgres/outside

Build the project and start the Java process for the REST API with the required SSL and JWT configuration.

```bash
cd stackgres-k8s/src/
./mvnw clean install -DskipTests
cd restapi/
java \
 -Dquarkus.http.ssl.certificate.files=$(pwd)/../operator/src/test/resources/certs/server.crt \
 -Dquarkus.http.ssl.certificate.key-files=$(pwd)/../operator/src/test/resources/certs/server-key.pem \
 -Dmp.jwt.verify.publickey.location=$(pwd)/src/test/resources/jwt/rsa_public.pem \
 -Dsmallrye.jwt.sign.key.location=$(pwd)/src/test/resources/jwt/rsa_private.key \
 -Dquarkus.http.ssl-port=8443 \
 -jar target/quarkus-app/quarkus-run.jar
```

--------------------------------

### Install Kube Prometheus Stack with Helm

Source: https://stackgres.io/doc/latest/administration/monitoring

Installs the kube-prometheus-stack chart in the 'monitoring' namespace with Grafana enabled. Creates the namespace if it does not exist. StackGres provides advanced monitoring installation options via the Operator installation with Helm.

```bash
helm install --create-namespace --namespace monitoring \
 --set grafana.enabled=true \
 prometheus prometheus-community/kube-prometheus-stack

```

--------------------------------

### Create React app and install supabase-js

Source: https://stackgres.io/doc/latest/runbooks/supabase-stackgres

Commands to create a new React app named 'my-app' and install the '@supabase/supabase-js' dependency. Run these in a terminal.

```bash
npx create-react-app my-app
cd my-app && npm install @supabase/supabase-js

```

--------------------------------

### Install K3s

Source: https://stackgres.io/doc/latest/runbooks/k3s-stackgres

Installs a specific version of K3s.

```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.25.9+k3s1 sh -
```

--------------------------------

### Install StackGres with grafana.autoEmbed=true

Source: https://stackgres.io/doc/latest/administration/monitoring

Use this Helm command to automatically embed an existing Grafana installation into the StackGres UI. Requires Grafana username and password during installation.

```bash
helm install --create-namespace --namespace stackgres stackgres-operator \
   --set grafana.autoEmbed=true \
   https://stackgres.io/downloads/stackgres-k8s/stackgres/latest/helm/stackgres-operator.tgz
```

--------------------------------

### Set up a local kind cluster

Source: https://stackgres.io/doc/latest/developer/stackgres/outside

Runs the E2E setup script to create a local Kubernetes cluster using kind. This is a prerequisite for running StackGres outside of K8s.

```bash
sh stackgres-k8s/e2e/e2e setup_k8s

```

--------------------------------

### Install MinIO via Helm

Source: https://stackgres.io/doc/latest/runbooks/backup-large-databases

Deploy MinIO using the specified configuration file.

```bash
helm install -n minio --create-namespace minio bitnami/minio --version 12.8.7 -f /opt/ongres/minio/minio.yaml
```
Tokens:
Raw