Kubernetes
This page provides instructions on how to configure the Helm chart to install Hoop in any cloud provider.
Quick Start
Setup Postgres Database
Create a new namespace and install a Postgres database in your Kubernetes cluster
Configure the values.yml
Deploy the Gateway
Access it
- Forward the hoopgateway service ports to your local machine to access the WebApp
Installing
To install the latest version in a new namespace (example: hoopdev
). Issue the command below:
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.
Database Configuration
Hoop uses Postgres as the backend storage of all data in the system. The user that connects in the database must be a superuser or have the CREATEROLE permission. The command below creates a database and a user with privileges to access the database and the default schema.
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
Helm
Make sure you have helm installed in your machine. Check Helm installation page
Using Helm Manifests
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.
Standalone Deployment
Sidecar Container
Gateway Chart Configuration
Check the environment variables section for more information about each configuration.
Authentication
Local Authentication manages users and passwords locally and sign JWT access tokens to users.
Make sure to create a strong secret key for JWT_SECRET_KEY
configuration, the command below generate a strong key as the value for this configuration:
Local Authentication manages users and passwords locally and sign JWT access tokens to users.
Make sure to create a strong secret key for JWT_SECRET_KEY
configuration, the command below generate a strong key as the value for this configuration:
The Oauth2/OIDC authentication integrates with any identity provider that support these protocols. The users are managed on the identity provider.
Persistence
We recommend using persistent volumes for session blobs to avoid losing sessions during outages or restarts. The following example shows how to enable a 100GB persistent volume when using AWS/EKS.
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 Load Balancer Controller is a controller to help manage Elastic Load Balancers for a Kubernetes cluster.
Deploy the AWS Load Balancer Controller
Ingress Configuration
AWS Load Balancer Controller is a controller to help manage Elastic Load Balancers for a Kubernetes cluster.
Deploy the AWS Load Balancer Controller
Ingress Configuration
The Nginx Ingress Controller is an Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.
Deploy Nginx Ingress Controller
Ingress Configuration
- TLS Termination on Nginx
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
Setup Certificates
- Export the certificates for setting up the helm chart
The format base64://<inline-certificate-content>
allows configuring inline TLS to Hoop Gateway.
- Upload them into GCP
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
- 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
Access It
- Wait for all resources to be provisioned, the command below will show any pending operations on GCP
- Check if the ip addresses are displayed when listing the ingresses
- Navigate to the Web Application public URL at
https://$DOMAIN_HOSTNAME/login
Service Configuration
The chart allows configuring the main service that exposes the service of the gateway.
mainService.annotations
attribute allows adding an annotation mapping. GCP for instance configure aspects of how to configure the load balancer based on this configurationmainService.httpBackendConfig
: It creates thehoopgateway-http
Backend Config resource when this attribute is set. It could be referenced using the annotationbeta.cloud.google.com/backend-config
healthCheckType
: The protocol used by probe systems for health checking. The BackendConfig only supports creating health checks using the HTTP, HTTPS, or HTTP2timeoutSec
: The amount of time in seconds that Google Cloud waits for a response to a probe.
mainService.grpcBackendConfig
: It creates thehoopgateway-grpc
Backend Config resource when this attribute is set. It could be referenced using the annotationbeta.cloud.google.com/backend-config
healthCheckType
: The protocol used by probe systems for health checking. The BackendConfig only supports creating health checks using the HTTP, HTTPS, or HTTP2timeoutSec
: The amount of time in seconds that Google Cloud waits for a response to a probe.
For more information of how to configure these resources, refer to the GCP Ingress Configuration Reference.
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.
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.
Default Agent Sidecar
Adding this section will deploy a default agent as a sidecar container.
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.
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.
Tolerations
See this article explaining how to configure tolerations
Node Affinity
See this article explaining how to configure affinity and anti-affinity rules
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.