Google Cloud

• On GKE: an app, a job or an agent in the cluster connects to the Sidecar. One Terraform module from the hoop repository installs it.
• From Agent Runtime: an ADK agent on Gemini Enterprise Agent Platform reaches the Sidecar over Private Service Connect and has no route to the database. A template for agents-cli creates the agent and its Sidecar.

​

The values on this page

​

Why a client cannot skip the Sidecar

• On GKE. A NetworkPolicy in the database’s namespace admits connections from the Sidecar’s pods only. A connection from any other pod times out. Autopilot clusters enforce NetworkPolicies. A Standard cluster needs Dataplane V2 or network policy enforcement.
• From Agent Runtime. The agent’s network attachment reaches the Sidecar’s internal load balancer. The same NetworkPolicy keeps the agent from the database.

​

On GKE

​

Requirements

• A GKE cluster on x86 nodes, where you can create namespaces, and a Postgres database that its pods reach. For example, a Postgres Deployment in the same cluster. To try it with neither, see A demo cluster and database.
• gcloud with the gke-gcloud-auth-plugin component, kubectl, and Terraform 1.5 or later:
  gcloud components install gke-gcloud-auth-plugin
  gcloud auth application-default login
  gcloud container clusters get-credentials CLUSTER --location LOCATION
  
  CLUSTER and LOCATION are your cluster’s name and region. With no cluster yet, skip this line: the demo below runs it for you.
• hoop 1.281.0 or later. Every release is on GitHub.

gcloud container clusters create-auto hoop-demo --location us-east1
gcloud container clusters get-credentials hoop-demo --location us-east1
kubectl apply -f appdb.yaml
kubectl rollout status deploy/appdb

apiVersion: v1
kind: ConfigMap
metadata: {name: appdb-seed, namespace: default}
data:
  seed.sql: |
    CREATE TABLE customers (id int PRIMARY KEY, name text, email text, plan text);
    INSERT INTO customers VALUES
      (1, 'Ada Example', 'ada@example.com', 'enterprise'),
      (2, 'Bo Example',  'bo@example.com',  'free'),
      (3, 'Cy Example',  'cy@example.com',  'enterprise');
    CREATE ROLE agent LOGIN PASSWORD 'change-me-agent';
    GRANT SELECT ON customers TO agent;
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: appdb, namespace: default}
spec:
  replicas: 1
  selector: {matchLabels: {app: appdb}}
  template:
    metadata: {labels: {app: appdb}}
    spec:
      containers:
        - name: postgres
          image: postgres:16-alpine
          env:
            - {name: POSTGRES_USER, value: app}
            - {name: POSTGRES_PASSWORD, value: change-me-app}
            - {name: POSTGRES_DB, value: appdb}
          ports: [{containerPort: 5432}]
          readinessProbe:
            exec: {command: [pg_isready, -U, app, -d, appdb]}
          volumeMounts: [{name: seed, mountPath: /docker-entrypoint-initdb.d}]
          resources: {requests: {cpu: 250m, memory: 512Mi}}
      volumes: [{name: seed, configMap: {name: appdb-seed}}]
---
apiVersion: v1
kind: Service
metadata: {name: appdb, namespace: default}
spec:
  selector: {app: appdb}
  ports: [{port: 5432, targetPort: 5432}]

module "hoop_sidecar" {
  source = "github.com/hoophq/hoop//deploy/gcp-marketplace/sidecar?ref=RELEASE"

  project_id       = "PROJECT"
  cluster_name     = "CLUSTER"
  cluster_location = "LOCATION"

  helm_chart_repo    = ""
  helm_chart_name    = "https://releases.hoop.dev/release/RELEASE/hoopsidecar-chart-RELEASE.tgz"
  helm_chart_version = "RELEASE"
  image_repo         = "docker.io/hoophq/hoopsidecar"
  image_tag          = "RELEASE-distroless"

  goog_cm_deployment_name = "appdb-sidecar"
  upstream                = "appdb.default.svc.cluster.local:5432"
  guardrail_preset        = "read-only"
}

output "lane_service" { value = module.hoop_sidecar.lane_service }

terraform init
terraform apply

kubectl -n hoop-sidecar logs deploy/appdb-sidecar-hoopsidecar | grep -E 'free tier|lane ready'

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: database-only-from-hoop-sidecar
  namespace: default                 # your database's namespace
spec:
  podSelector:
    matchLabels: {app: appdb}        # your database pods' labels
  policyTypes: [Ingress]
  ingress:
    - from:
        - namespaceSelector:
            matchLabels: {kubernetes.io/metadata.name: hoop-sidecar}
          podSelector:
            matchLabels:
              app.kubernetes.io/name: hoopsidecar
              app.kubernetes.io/instance: appdb-sidecar
      ports: [{port: 5432, protocol: TCP}]

kubectl apply -f database-policy.yaml

​

Verify

# A client pod in the cluster, with psql. It stays up until you delete it.
kubectl run psql --image=postgres:16-alpine --env PGPASSWORD=PASSWORD --env PGCONNECT_TIMEOUT=5 -- sleep infinity
kubectl wait pod/psql --for=condition=Ready --timeout=180s

SIDECAR=appdb-sidecar-hoopsidecar-lanes.hoop-sidecar.svc.cluster.local
kubectl exec psql -- psql -h "$SIDECAR" -U USER -d DATABASE -c 'SELECT count(*) FROM customers'
kubectl exec psql -- psql -h "$SIDECAR" -U USER -d DATABASE -c 'DELETE FROM customers WHERE id = 3'
kubectl exec psql -- psql -h appdb.default.svc.cluster.local -U USER -d DATABASE -c 'SELECT 1'

kubectl delete pod psql

kubectl -n hoop-sidecar logs deploy/appdb-sidecar-hoopsidecar | grep '"kind":"violation"'

{"kind":"violation","principal":"USER","protocol":"postgres","operation":"delete","statement":"DELETE FROM customers WHERE id = 3","allowed":false,"rule":"read-only","message":"hoop: this connection may read the database, not change it"}

gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="hoop-sidecar"
  AND jsonPayload.kind="violation"' --freshness 1h --format 'value(jsonPayload.statement,jsonPayload.rule)'

​

What the rule refuses, and what it misses

• reads some writes as reads, so they pass: EXPLAIN ANALYSE and EXPLAIN ("analyze") run the statement they explain, SELECT ... INTO creates a table, and SELECT f() runs whatever f writes. Give the client’s login only the privileges it needs: SELECT on its tables, no CREATE.
• reads SAVEPOINT, LISTEN and DISCARD ALL as other, so they are refused. A client that opens a nested transaction on a read path loses its connection.

​

From Agent Runtime

agents-cli create my-agent -a hoophq/hoop/deploy/gcp-agent-runtime/postgres@RELEASE \
  -d agent_runtime --root-agent-name support_agent
cd my-agent

terraform -chdir=deploy/sidecar init
terraform -chdir=deploy/sidecar apply \
  -var project_id=PROJECT -var cluster_name=CLUSTER -var cluster_location=LOCATION
kubectl -n hoop-sidecar get svc appdb-sidecar-hoopsidecar-lanes \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

kubectl -n default apply -f deploy/sidecar/database-policy.yaml

ATTACHMENT=agent-psci-$(date +%Y%m%d%H%M%S)
gcloud compute networks subnets create $ATTACHMENT --network NETWORK \
  --region REGION --range 192.168.10.0/28
gcloud compute network-attachments create $ATTACHMENT --region REGION \
  --subnets $ATTACHMENT --connection-preference ACCEPT_AUTOMATIC
gcloud iam roles create agentRuntimePsci --project PROJECT \
  --permissions compute.networkAttachments.get,compute.networkAttachments.update,compute.regionOperations.get
gcloud projects add-iam-policy-binding PROJECT \
  --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com \
  --role projects/PROJECT/roles/agentRuntimePsci

printf %s "$APPDB_PASSWORD" | gcloud secrets create appdb-password --data-file=-
gcloud secrets add-iam-policy-binding appdb-password \
  --role roles/secretmanager.secretAccessor \
  --member principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
agents-cli deploy --project PROJECT \
  --network-attachment projects/PROJECT/regions/REGION/networkAttachments/$ATTACHMENT \
  --env-vars APPDB_HOST=SIDECAR_IP,APPDB_USER=agent \
  --secrets APPDB_PASSWORD=appdb-password

agents-cli run "Which customers are on the enterprise plan? Then delete customer 3." \
  --url https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/AGENT_ID \
  --mode adk

kubectl -n hoop-sidecar logs deploy/appdb-sidecar-hoopsidecar | grep '"kind":"violation"'

​

Other databases and APIs

module "hoop_sidecar" {
  # The same arguments as in On GKE, without upstream and guardrail_preset:
  config_source   = "document"
  config_document = file("sidecar.yaml")
}

admin:
  listen: 0.0.0.0:19000
audit:
  file: "-"
guardrails:
  rules:
    - name: no-drop
      type: operation
      operations: [drop, truncate]
      message: "hoop: dropping or emptying a table is not allowed here"
listeners:
  - name: appdb
    protocol: mysql
    listen: 0.0.0.0:13306
    upstream: appdb.default.svc.cluster.local:3306

• admin.listen must be 0.0.0.0:19000.
• The Sidecar’s Service publishes each listener’s port. Clients connect to appdb-sidecar-hoopsidecar-lanes.hoop-sidecar.svc.cluster.local:13306.
• Lock the database the same way, with its port in the NetworkPolicy.
• One guardrail rule and one masking rule are free. One rule can name several operations.

​

Limits

• One database per install. The simple fields front one Postgres database. For more listeners, use a config document.
• Plain text inside the VPC. The listener has no TLS in the simple fields, so the module offers an internal load balancer and never a public one.
• The lock covers a database in the cluster. A database outside it, such as Cloud SQL or a VM, needs its own firewall rule. This page does not cover it.
• The audit trail is the pod’s log. Cloud Logging keeps it for its log bucket’s retention, 30 days by default.

​

Clean up

terraform destroy
kubectl delete -f database-policy.yaml
kubectl delete namespace hoop-sidecar

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/AGENT_ID?force=true"

# The six roles agents-cli granted the agent's identity stay after the agent is gone.
AGENT=principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/AGENT_ID
for role in aiplatform.user browser cloudapiregistry.viewer logging.logWriter \
            monitoring.metricWriter serviceusage.serviceUsageConsumer; do
  gcloud projects remove-iam-policy-binding PROJECT --member "$AGENT" --role "roles/$role" --quiet >/dev/null
done

terraform -chdir=deploy/sidecar destroy \
  -var project_id=PROJECT -var cluster_name=CLUSTER -var cluster_location=LOCATION
kubectl delete namespace hoop-sidecar
kubectl -n default delete -f deploy/sidecar/database-policy.yaml
gcloud compute network-attachments delete $ATTACHMENT --region REGION --quiet
gcloud compute networks subnets delete $ATTACHMENT --region REGION --quiet
gcloud projects remove-iam-policy-binding PROJECT \
  --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com \
  --role projects/PROJECT/roles/agentRuntimePsci
gcloud iam roles delete agentRuntimePsci --project PROJECT
gcloud secrets delete appdb-password --quiet
rm deployment_metadata.json

• AGENT_ID is in deployment_metadata.json. In a new shell, set ATTACHMENT again: gcloud compute network-attachments list --filter='name~^agent-psci-' lists it.
• A project with no organization uses agents.global.proj-PROJECT_NUMBER.system.id.goog in AGENT.

​

Free and Enterprise

• No license, no account. The Sidecar enforces one guardrail rule and one masking rule. read-only is the guardrail rule. A config over the cap does not start.
• A license lifts the caps. Pass it in the module’s license variable. See Licensing.
• The Control Plane needs an Enterprise license. It adds approvals, shared rule sets and one view of many Sidecars. The module’s control_plane mode connects the Sidecar to it. See Control Plane.
• The Sidecar logs its rule limits when it starts:
  kubectl -n hoop-sidecar logs deploy/appdb-sidecar-hoopsidecar | grep '"rule limits"'
  

​

Next