Kubernetes

This page provides instructions on how to configure the Helm chart to install Hoop in any cloud provider.

Quick Start

Standard Installation
Secure Installation (TLS)

This is the standard installation to evaluate Hoop. We recommend it for Proof of Concepts or testing environments.

On this installation, clients establishes connections without TLS, which is subject to interception. Make sure to deploy it over a secure network and use it only with non production resources.

Deploy the Gateway

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade hoop --install oci://ghcr.io/hoophq/helm-charts/hoop-chart --version $VERSION \
  --namespace hoopdev --create-namespace \
  --set postgres.enabled=true \
  --set defaultAgent.enabled=true \
  --set dataMasking.enabled=true \
  --set dataMasking.analyzer.replicas=2 \
  --set 'config.POSTGRES_DB_URI=postgres://root:default-pwd@hoopgateway-pg/postgres?sslmode=disable' \
  --set config.API_URL=http://localhost:8009

Access it

Forward the hoopgateway service ports to your local machine to access the WebApp

kubectl port-forward service/hoopgateway 8009:8009 8010:8010 -n hoopdev

Visit the Webapp at http://127.0.0.1:8009/login

The default installation method install a Postgres database with Host mounted storage. In case the node is decommissioned, all data will be lost.For more durable setups, use a Persistent Volume by providing the option below:

--set postgres.storageClassName=<your-storage-class>

This is production is recommended for production, it terminate the TLS directly on the gateway for all existent protocols.

For the purpose of this quick start, we’re going to generate certificate signed by a CA unstruted party with openssl. However, the process of installing and configuring should be the same when issuing certificates from trusted party organizations.Ensure you have all required certificate files from Step 1 if you’ve already issued them through your PKI provider.

Obtain a certificate for your domain

Expose the domain name of the Hoop Gateway instance

export DOMAIN_HOSTNAME=<your-hoop-gateway-domain-name-goes-here>

Generate and sign your certificates with openssl

mkdir ./tls && cd ./tls
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 1826 -out ca.crt -subj '/CN=MyOrg CA/C=AT/ST=Vienna/L=Vienna/O=MyOrg'
openssl req -new -nodes -out server.csr -newkey rsa:4096 -keyout server.key -subj '/CN=Gateway/C=AT/ST=Vienna/L=Vienna/O=MyOrg'
# create a v3 ext file for SAN properties
cat > server.v3.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = $DOMAIN_HOSTNAME
IP.1 = 127.0.0.1
EOF

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 730 -sha256 -extfile server.v3.ext

Join the Root Certificate Authority with your certificate

cat server.crt ca.crt > server-full.crt

When issuing certificates from a trusted party, make sure to include the Root and Intermediate certificates if they are provided.

(optional) Add the Root CA to your system keychain

This process is needed only when creating certificates from an unstrusted third party (openssl). It will make your system to trust the certificated issued by the Root Certificate Authority.Make sure to have the following files in your local filesystem before proceeding to the next step:

server.crt - File containing the server certificate
ca.crt - File containing the Root with Intermediate CA’s if it’s available
server.key - File containing the private key of your certificate

Generate the values.yaml file

After having the certificates in your working directory, encode the following files in base64 to generate the values.yaml file. The certificates will be used to serve the ports exposed in the gateway securely with TLS

Make sure that the DNS name of your domain match with the certificate. In this example we’ll be exposing all ports with a load balancer from AWS. Make sure to adapt this recipe to deploy a network load balancer in your own infra-structure with the proper annontations.

Export the domain hostname and the certificate files

export DOMAIN_HOSTNAME=<your-hoop-gateway-domain-name-goes-here>
export TLS_KEY_ENC=$(cat server.key | base64)
export TLS_CERT_ENC=$(cat server-full.crt | base64)

Generate the values.yaml file

cat - > values.yaml <<EOF
# gateway base configuration
config:
  POSTGRES_DB_URI: 'postgres://root:default-pwd@hoopgateway-pg/postgres?sslmode=disable'
  API_URL: "https://$DOMAIN_HOSTNAME"
  TLS_KEY: "base64://$TLS_KEY_ENC"
  TLS_CERT: "base64://$TLS_CERT_ENC"

# uses a local Postgres database with Host mounted stored
# use a distinct storage class name for more durable setups
postgres:
  enabled: true
  storageClassName: null

# enable data masking
dataMasking:
  enabled: true
  mode: best-effort

  analyzer:
    replicas: 2

# an agent will be deployed along with the gateway
defaultAgent:
  enabled: true
  grpcScheme: grpcs
  grpcHost: 127.0.0.1:8010
  grpcSkipVerify: true
  imageTag: latest

# exposes a network load balancer for all services
proxyService:
  enabled: true
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
  ports:
  - name: api
    port: 443
    targetPort: 8009
  - name: grpcs
    port: 8443
    targetPort: 8010
  - name: pgproxy
    port: 15432
    targetPort: 15432
  - name: sshproxy
    port: 12222
    targetPort: 12222
  - name: rdpproxy
    port: 13389
    targetPort: 13389
EOF

Deploy it

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade hoop \
  --install oci://ghcr.io/hoophq/helm-charts/hoop-chart --version $VERSION \
  --namespace hoopdev \
  --create-namespace \
  --values values.yaml

Access it

Via Public URL
Via Port Forward

Obtain the address of your load balancer by issuing the command below

kubectl get svc -n hoopdev hoopgateway-proxy \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Create a CNAME record for your $DOMAIN_HOSTNAME in your DNS pointing to this address.
Visit the Webapp at https://$DOMAIN_NAME/login

If you want to validate the installation without exposing the gateway to the public internet, use the kubectl to port forward the ports into your local machine.

kubectl port-forward service/hoopgateway 8009:8009 8010:8010 -n hoopdev

Then Visit the Webapp at http://127.0.0.1:8009/login

To test the native protocols directly on the gateway, make sure to export the ports below:

ssh/12222
postgres/15432
rdp/13389

Helm Install

To install the latest version in a new namespace (example: hoopdev). Issue the command below:

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoop \
  oci://ghcr.io/hoophq/helm-charts/hoop-chart --version $VERSION \
  -f values.yaml \
  --namespace hoopdev

Overwriting or passing new attributes

It is possible to add new attributes or overwrite an attribute from a base values.yaml file. In the example below a default agent is deployed as a sidecar container and with a using a specific version of the gateway.

helm upgrade --install hoop \
  oci://ghcr.io/hoophq/helm-charts/hoop-chart --version $VERSION \
  -f values.yaml \
  --set defaultAgent.enabled=true \
  --set image.gw.tag=1.45.0

Database Configuration

Hoop uses Postgres as the backend storage of all data in the system. It uses the schema private to create the tables of the system. The command below creates a database and a user with privileges to access the database and the required schema.

CREATE DATABASE hoopdb;
CREATE USER hoopuser WITH ENCRYPTED PASSWORD 'my-secure-password';
-- switch to the created database
\c hoopdb
CREATE SCHEMA IF NOT EXISTS private;
GRANT ALL PRIVILEGES ON DATABASE hoopdb TO hoopuser;
GRANT ALL PRIVILEGES ON SCHEMA public to hoopuser;
GRANT ALL PRIVILEGES ON SCHEMA private to hoopuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO hoopuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA private TO hoopuser;

In case of using a password with special characters, make sure to url encode it properly when setting the connection string.

Use these values to assemble the configuration for POSTGRES_DB_URI:

POSTGRES_DB_URI=postgres://hoopuser:<passwd>@<db-host>:5432/hoopdb

Make sure to include ?sslmode=disable option in the Postgres connection string in case your database setup doesn’t support TLS.

Agent Deployment

values.yaml (minimal)

  config:
    HOOP_KEY: '<agent-key-dsn>'

values.yaml (full)

# base configuration
config:
  HOOP_KEY: '<agent-key-dsn>'
  LOG_ENCODING: 'json' # json|console
  LOG_LEVEL: 'info' # debug|info|warn|error
  LOG_GRPC: '0' # 0|1|2

  # Override Presidio configuration propagated from the gateway (optional)
  # MSPRESIDIO_ANALYZER_URL: 'http://user:pass@presidio-analyzer:5001'
  # MSPRESIDIO_ANONYMIZER_URL: 'http://user:pass@presidio-anonymizer:5002'
  # DLP_MODE: 'best-effort' # best-effort|strict

# image default configuration
image:
  repository: hoophq/hoopdev
  pullPolicy: Always
  tag: latest

# define extra secret configuration to load as environment variables
extraSecret: {}

# -- Deployment strategy
deploymentStrategy:
  type: Recreate

# -- CPU/Memory resource requests/limits
resources: {}
#   limits:
#     cpu: 1024m
#     memory: 1Gi
#   requests:
#     cpu: 1024m
#     memory: 1Gi

# -- Node labels for pod assignment
nodeSelector: {}

# -- Toleration labels for pod assignment
tolerations: []

# -- Affinity settings for pod assignment
affinity: {}

Helm

Make sure you have helm installed in your machine. Check Helm installation page

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoopagent \
	oci://ghcr.io/hoophq/helm-charts/hoopagent-chart --version $VERSION \
	--set "config.HOOP_KEY=<AUTH-KEY>"

Using Helm Manifests

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm template hoopagent \
  oci://ghcr.io/hoophq/helm-charts/hoopagent-chart --version $VERSION \
  --set 'config.HOOP_KEY=<AUTH-KEY>' \
  --set 'image.tag=1.36.16' \
  --set 'extraSecret=AWS_REGION=us-east-1'

Starting from version 1.21.9, there is only one way to configure the agent key, which is by using the config.HOOP_KEY configuration. This requires creating a key in a DSN format in the API. To use legacy options, use the Helm chart version 1.21.4.

Need short-lived agent credentials instead of a static HOOP_KEY? The same hoopagent-chart also supports SPIFFE JWT-SVID authentication with a spiffe-helper sidecar — see SPIFFE Agent Identity → Deploying with the official Helm chart for the step-by-step guide.

Standalone Deployment

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hoopagent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hoopagent
  template:
    metadata:
      labels:
        app: hoopagent
    spec:
      containers:
      - name: hoopagent
        image: hoophq/hoopdev
        env:
        - name: HOOP_KEY
          value: '<AUTH-KEY>'

Sidecar Container

deployment.yaml

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: myapp
  spec:
    replicas: 1
    selector:
      matchLabels:
        app: myapp
    template:
      metadata:
        labels:
          app: myapp
      spec:
        containers:
        - name: myapp
          image: myapp
          ports:
          - containerPort: 8000
            name: http
            protocol: TCP
        - name: hoopagent
          image: hoophq/hoopdev
          env:
          - name: HOOP_KEY
            value: '<AUTH-KEY>'

Gateway Chart Configuration

Check the environment variables section for more information about the configuration of the section config. Example:

config:
  POSTGRES_DB_URI: 'postgres://user:pwd@host:port/db'
  (...)

TLS Configuration

Starting with version 1.45+,we are transitioning to expose native protocols directly on the Gateway, eliminating the need to forward ports locally through the Hoop Command Line. This new approach requires the Gateway to terminate TLS connections, ensuring secure protocol negotiation and protecting data in transit.

To deploy the gateway with a valid certificate, make to define the environment variables TLS_KEY and TLS_CERT.

The certificate file may contain the Root and Intermediate CA’s as well. Make sure to include them in the proper order, the example below show how the certificates must be generated:

<SERVER-CERT>
<INTERMEDIATE-CA>
<ROOT_CA>

Base64 Encoded Configuration
Path Based Configuration

config:
  TLS_KEY: 'base64://<pem-encoded-private-key>'
  TLS_CERT: 'base64://<pem-encoded-full-certificate>'

Example of how to encode the files:

Use the output of each value to configure the attributes above.

echo "base64://$(cat /tmp/tls/server.key |base64)
echo "base64://$(cat /tmp/tls/server.crt |base64)

config:
  TLS_KEY: 'file:///path/to/server.key'
  TLS_CERT: 'file:///path/to/server.crt'

Authentication

Local Authentication
Oauth2/OIDC Authentication

Local Authentication manages users and passwords locally and sign JWT access tokens to users.

config:
  POSTGRES_DB_URI: 'postgres://<user>:<pwd>@<db-host>:<port>/<dbname>'
  API_URL: 'https://hoopdev.yourdomain.tld'

The Oauth2/OIDC authentication integrates with any identity provider that support these protocols. The users are managed on the identity provider.

config:
  POSTGRES_DB_URI: 'postgres://<user>:<pwd>@<db-host>:<port>/<dbname>'
  API_URL: 'https://hoopdev.yourdomain.tld'
  IDP_ISSUER: 'https://idp-issuer-url'
  IDP_CLIENT_ID: 'client-id'
  IDP_CLIENT_SECRET: 'client-secret'
  IDP_AUDIENCE: ''
  IDP_CUSTOM_SCOPES: ''
  IDP_GROUPS_CLAIM: ''

The authentication configuration is now handled via Webapp or defined via API directly, the environment variable with the prefix IDP_ are deprecated and will be removed in upcoming releases.

Default Database

The chart allows deploying a Postgres database as part of the installation.

# -- Enable PostgreSQL
postgres:
  # it default to host mount when enabled
  enabled: false

  # set a storage class name to use a Persistent Volume Claim
  storageClassName: null

  # -- Size of PVC
  size: 10Gi
  # annotations: {}

It creates a default Service resource named hoopgateway-pg. This service name could be used in the POSTGRES_DB_URI configuration.

Persistence

We recommend using SSD for large deployments, it will help speed the I/O when handling many concurrent requests. The following example shows how to enable a 50GB persistent volume when using AWS/EKS.

persistence:
  # -- Use persistent volume for write ahead log sessions
  enabled: true
  storageClassName: gp2

  # -- Size of persistent volume claim
  size: 50Gi

Ingress Configuration

This section covers the ingress configuration. The gateway requires exposing the ports HTTP/8009 and HTTP2/8010. The ingress configuration establishes these two differing configurations based on the ingress controller in use.

AWS ALB
Nginx Ingress Controller
GCP Classic ALB

AWS Load Balancer Controller is a controller to help manage Elastic Load Balancers for a Kubernetes cluster.

Deploy the AWS Load Balancer Controller

https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/deploy/installation/

Ingress Configuration

# HTTP/8009 - API / WebApp
ingressApi:
  enabled: true
  # the public DNS name
  host: 'hoopgateway.yourdomain.tld'
  # the ingress class, in this case alb
  ingressClassName: 'alb'
  annotations:
    # uses the ACM service to use a valid public certificate issued by AWS
    alb.ingress.kubernetes.io/certificate-arn: 'arn:aws:acm:...'
    # the group name allows resuing the same lb for both protocols (HTTP/gRPC)
    alb.ingress.kubernetes.io/group.name: 'hoopdev'
    alb.ingress.kubernetes.io/healthcheck-path: '/'
    alb.ingress.kubernetes.io/healthcheck-protocol: 'HTTP'
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 443}]'
    alb.ingress.kubernetes.io/scheme: 'internet-facing'
    alb.ingress.kubernetes.io/ssl-redirect: '443'
    alb.ingress.kubernetes.io/target-type: 'ip'

# HTTP/8010 - gRPC Service
ingressGrpc:
  enabled: true
  # the public DNS name
  host: 'hoopdev.yourdomain.tld'
  # the ingress class, in this case alb
  ingressClassName: 'alb'
  annotations:
    # configures the type of the protocol
    alb.ingress.kubernetes.io/backend-protocol-version: 'GRPC'
    # the certificate could be reused for the same protocol
    alb.ingress.kubernetes.io/certificate-arn: 'arn:aws:acm:...'
    # the group name allows resuing the same lb for both protocols (HTTP/gRPC)
    alb.ingress.kubernetes.io/group.name: 'hoopdev'
    alb.ingress.kubernetes.io/healthcheck-path: '/'
    alb.ingress.kubernetes.io/healthcheck-protocol: 'HTTP'
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 8443}]'
    alb.ingress.kubernetes.io/scheme: 'internet-facing'
    alb.ingress.kubernetes.io/target-type: 'ip'

The Nginx Ingress Controller is an Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.

Deploy Nginx Ingress Controller

https://kubernetes.github.io/ingress-nginx/deploy/

Ingress Configuration

TLS Termination on Nginx

ingressApi:
  enabled: true
  host: hoopgateway.yourdomain.tld
  ingressClassName: 'nginx'
  tls:
  - hosts:
      - hoopgateway.yourdomain.tld
    secretName: hoopserver-tls

ingressGrpc:
  enabled: true
  host: "hoop-grpc.yourdomain.tld"
  ingressClassName: 'nginx'
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: GRPC
    nginx.ingress.kubernetes.io/proxy-body-size: '0'
  tls:
  - hosts:
      - hoop-grpc.yourdomain.tld
    secretName: hoopserver-tls

This setup requires deploying a network load balancer (Layer 4) in your cloud provider.

The external Application Load Balancer is a proxy-based Layer 7 load balancer that enables you to run and scale your services behind a single external IP address. See the Architecture Overview.

The Classic ALB doesn’t support establishing HTTP/2 connections with the Hoop Gateway without TLS. To accommodate this requirement, TLS certificates must be configured both on the ALB and within the Hoop Gateway to establish secure communication between these components.

Deploy GKE Cluster

Deploy GKE Cluster by following the GKE Quick Start guide
Obtain access to your cluster via kubectl

Export your domain name

export DOMAIN_HOSTNAME=hoopgateway.yourdomain.tld

Setup Certificates

Generate self signed certificates

This step is not necessary if you already have certificates issued by a known entity.

Create the CA private key

mkdir -p /tmp/hoopdemo && cd /tmp/hoopdemo
openssl genrsa -aes256 -out ca.key 2048

Create the Root Certificate Authority (CA)

openssl req -x509 -new -nodes -key ca.key -sha256 -days 1826 -out ca.crt -subj '/CN=Hoop Root CA'

Creating the Certificate Signing Request (CSR)

openssl req -new -nodes -out server.csr -newkey rsa:2048 -keyout server.key -subj '/CN=HoopGateway'

Sign the Certificate

# create a v3 ext file for SAN properties
cat > server.v3.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = $DOMAIN_HOSTNAME
DNS.2 = grpc-$DOMAIN_HOSTNAME
IP.1 = 127.0.0.1
EOF

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out server.crt -days 730 -sha256 -extfile server.v3.ext

Make sure to install the Root Certificate Authority in your browser/system to be able to visit the Web App. The browser won’t allow access due to HSTS policy.This step is not necessary when using certificates issued by a known entity.

Export the certificates for setting up the helm chart

export TLS_CA="base64://$(cat ca.crt | base64)"
export TLS_KEY="base64://$(cat server.key | base64)"
export TLS_CERT="base64://$(cat server.crt | base64)"

The format base64://<inline-certificate-content> allows configuring inline TLS to Hoop Gateway.

Upload them into GCP

gcloud compute ssl-certificates create hoopserver \
  --certificate=server.crt \
  --private-key=server.key

We recommend using a valid certificates for production workloads.

Configure DNS and create static Global IP Addresses

Create the ip addresses of the load balancer

gcloud compute addresses create hoopgateway-grpc --global
gcloud compute addresses create hoopgateway-http --global

Associate the ip address to the proper domains in your DNS provider

Public DNS	IP Address
`$DOMAIN_HOSTNAME`	`<hoopgateway-http-ip-address>`
`grpc-$DOMAIN_HOSTNAME`	`<hoopgateway-grpc-ip-address>`

Deploy the Hoop Gateway

Create a namespace

kubectl create ns hoopdemo

Deploy a Postgres Server

Generate Specification

cat - > /tmp/hoopdemo/postgres-spec.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - env:
        - name: POSTGRES_USER
          value: root
        - name: POSTGRES_PASSWORD
          value: 1a2b3c4d
        - name: POSTGRES_DB
          value: hoopdb
        image: postgres
        name: postgres
        ports:
        - containerPort: 5432
          name: pg
          protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  ports:
  - name: postgres
    port: 5432
    protocol: TCP
    targetPort: 5432
  selector:
    app: postgres
EOF

Deploy it

kubectl apply -n hoopdemo -f /tmp/hoopdemo/postgres-spec.yaml

Deploy the Hoop Gateway

Generate Helm values.yaml

cat - > /tmp/hoopdemo/values.yaml <<EOF
config:
  POSTGRES_DB_URI: 'postgres://root:1a2b3c4d@postgres:5432/hoopdb?sslmode=disable'
  API_URL: "https://$DOMAIN_HOSTNAME"
  GRPC_URL: "grpcs://grpc-$DOMAIN_HOSTNAME:443"

defaultAgent:
  enabled: true
  grpcHost: grpc-$DOMAIN_HOSTNAME:443

mainService:
  annotations:
    beta.cloud.google.com/backend-config: '{"ports": {"http": "hoopgateway-http", "grpc": "hoopgateway-grpc"}}'
    cloud.google.com/app-protocols: '{"http":"HTTPS", "grpc":"HTTP2"}'
  httpBackendConfig:
    healthCheckType: HTTPS
  grpcBackendConfig:
    healthCheckType: HTTPS
    # it avoids clients being dropped for being idle
    timeoutSec: 259200

ingressApi:
  enabled: true
  host: "$DOMAIN_HOSTNAME"
  annotations:
    kubernetes.io/ingress.class: 'gce'
    ingress.gcp.kubernetes.io/pre-shared-cert: 'hoopserver'
    kubernetes.io/ingress.global-static-ip-name: 'hoopgateway-http'

ingressGrpc:
  enabled: true
  host: "grpc-$DOMAIN_HOSTNAME"
  annotations:
    kubernetes.io/ingress.class: 'gce'
    ingress.gcp.kubernetes.io/pre-shared-cert: 'hoopserver'
    kubernetes.io/ingress.global-static-ip-name: 'hoopgateway-grpc'
EOF

Deploy it

helm upgrade --install hoop oci://ghcr.io/hoophq/helm-charts/hoop-chart -f values.yaml --namespace hoopdemo \
  --set config.TLS_CA=$TLS_CA \
  --set config.TLS_KEY=$TLS_KEY \
  --set config.TLS_CERT=$TLS_CERT

Access It

Wait for all resources to be provisioned, the command below will show any pending operations on GCP

gcloud compute operations list |grep -v DONE

Check if the ip addresses are displayed when listing the ingresses

kubectl get ing -n hoopdemo

NAME               CLASS    HOSTS                   ADDRESS
hoopgateway-grpc   <none>   grpc-$DOMAIN_HOSTNAME   XX.X.XX.XXX
hoopgateway-web    <none>   $DOMAIN_HOSTNAME        XX.XXX.XXX.X

Navigate to the Web Application public URL at https://$DOMAIN_HOSTNAME/login

Proxy Protocol Services

Starting from version 1.45+, the protocols are served directly on the Gateway. These ports must be exposed to your network via a Network Load Balancer. Configuration Example:

proxyService:
  enabled: true
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
  ports:
  - name: api
    port: 443
    targetPort: 8009
  - name: grpcs
    port: 8443
    targetPort: 8010
  - name: pgproxy
    port: 15432
    targetPort: 15432
  - name: sshproxy
    port: 12222
    targetPort: 12222
  - name: rdpproxy
    port: 13389
    targetPort: 13389
  - name: httpproxy
    port: 18888
    targetPort: 18888

This setup requires configuring TLS directly on the gateway.

Computing Resources

The helm-chart defaults to 1vCPU and 1GB, which is suitable for evaluation purposes only. For production setups, we recommend allocating at least 8GB/4vCPU to the gateway process.

resources:
  gw:
    limits:
      cpu: 4096m
      memory: 8Gi
    requests:
      cpu: 4096m
      memory: 8Gi

Image Configuration

By default, the latest version of all images is used. If you want to use a specific image or pin the versions, use the image attribute section.

image:
  gw:
    repository: hoophq/hoop
    pullPolicy: Always
    tag: latest

Default Agent Sidecar

Adding this section will deploy a default agent as a sidecar container.

defaultAgent:
  enabled: true
  imageRepository: 'hoophq/hoopdev'
  imageTag: latest
  imagePullPolicy: Always
  grpcHost: 127.0.0.1:8009

The grpcHost allows configuring the host to connect when starting the agent. In case the gateway has TLS configured (TLS_CA env set), the host must match the certificate SAN.

Data Masking Configuration

To enable the Data Masking feature, you need to configure the dataMasking section in your values.yaml file. It will deploy the Microsoft Presidio on the same namespace as the Hoop Gateway.

dataMasking:
  enabled: true
  # https://github.com/microsoft/presidio/releases
  version: latest
  # best-effort | strict
  mode: best-effort

  analyzer:
    replicas: 2
    resources:
      requests:
        cpu: 2048m
        memory: 1024Mi
      limits:
        cpu: 2500m
        memory: 2048Mi

When the dataMasking attribute is enabled, it takes control over the following configurations:

DLP_MODE
DLP_PROVIDER
MSPRESIDIO_ANALYZER_URL
MSPRESIDIO_ANONYMIZER_URL
GOOGLE_APPLICATION_CREDENTIALS_JSON

If you need more control over the deployment, we recommend using a standalone helm chart of Presidio. See more details above in the Presidio Deployment section.

This attribute is available starting from version 1.37.16+ of the Helm chart.

Node Selector

This configuration describes a pod that has a node selector, disktype: ssd. This means that the pod will get scheduled on a node that has a disktype=ssd label. See this documentation for more information.

# -- Node labels for pod assignment
nodeSelector:
  disktype: ssd

Tolerations

See this article explaining how to configure tolerations

# -- Toleration labels for pod assignment
tolerations:
- effect: NoExecute
  key: spot
  value: "true"
- effect: NoSchedule
  key: spot
  value: "true"

Node Affinity

See this article explaining how to configure affinity and anti-affinity rules

# -- Affinity settings for pod assignment
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.kubernetes.io/zone
          operator: In
          values:
          - antarctica-east1
          - antarctica-west1
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 1
      preference:
        matchExpressions:
        - key: another-node-label-key
          operator: In
          values:
          - another-node-label-value

Presidio Deployment

The Data Masking feature uses Microsoft Presidio. We provide a Helm chart that gives more control over the deployment.

helm upgrade --install presidio \
  oci://ghcr.io/hoophq/helm-charts/presidio-chart --version v0.1.0 \
  -f values.yaml

We recommend starting with at least 2 replicas to handle concurrent requests more efficiently:

analyzer:
  replicas: 2

  resources:
    requests:
      cpu: 2048m
      memory: 1024Mi
    limits:
      cpu: 2500m
      memory: 2048Mi

It will guarantee at least four concurrent requests when performing model inference. If you want the workload to be burstable, decrease the CPU requests to 1024m. For maximum performance, ensure CPU requests are always set to 2 vCPUs and enable the Horizontal Pod Autoscaler.

These services must be respectively configured in the Gateway with the following environment variables:

DLP_PROVIDER=mspresidio
MSPRESIDIO_ANALYZER_URL=http://presidio-envoy-lb:3010
MSPRESIDIO_ANONYMIZER_URL=http://presidio-envoy-lb:3010

For more information about Presidio Deployment, see this section.

Generating Manifests

If you prefer using manifests over Helm, we recommend this approach. It allows you to track any modifications to the chart whenever a new version appears. You can apply a diff to your versioned files to identify what has been altered.

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm template hoop \
  oci://ghcr.io/hoophq/helm-charts/hoop-chart --version $VERSION \
  -f values.yaml

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Quick Start

Helm Install

Overwriting or passing new attributes

Database Configuration

Agent Deployment

Helm

Using Helm Manifests

Standalone Deployment

Sidecar Container

Gateway Chart Configuration

TLS Configuration

Authentication

Default Database

Persistence

Ingress Configuration

Proxy Protocol Services

Computing Resources

Image Configuration

Default Agent Sidecar

Data Masking Configuration

Node Selector

Tolerations

Node Affinity

Presidio Deployment

Generating Manifests

​Quick Start

​Helm Install

​Overwriting or passing new attributes

​Database Configuration

​Agent Deployment

​Helm

​Using Helm Manifests

​Standalone Deployment

​Sidecar Container

​Gateway Chart Configuration

​TLS Configuration

​Authentication

​Default Database

​Persistence

​Ingress Configuration

​Proxy Protocol Services

​Computing Resources

​Image Configuration

​Default Agent Sidecar

​Data Masking Configuration

​Node Selector

​Tolerations

​Node Affinity

​Presidio Deployment

​Generating Manifests

Quick Start

Helm Install

Overwriting or passing new attributes

Database Configuration

Agent Deployment

Helm

Using Helm Manifests

Standalone Deployment

Sidecar Container

Gateway Chart Configuration

TLS Configuration

Authentication

Default Database

Persistence

Ingress Configuration

Proxy Protocol Services

Computing Resources

Image Configuration

Default Agent Sidecar

Data Masking Configuration

Node Selector

Tolerations

Node Affinity

Presidio Deployment

Generating Manifests