EKS Quickstart

This guide explains how to install hoop self-hosted with helm on AWS in a EKS cluster

Requirements

AWS EKS cluster

AWS EKS Load Balancer Controller Addon

Valid DNS for gRPC & HTTP(s) services (e.g.: hoopdev.yourdomain.com)

Valid certificated issued by ACM

Auth0 Application Credentials

Hoop Command Line installed locally

Helm installed locally

Before starting provisioning the app, make sure to create a security group inbound rule to 0.0.0.0/0 that opens traffic to ports 443 (HTTPS) and 8443 (Custom TCP).

For this demo we're going to use as example the dns appdemo.hoop.dev.

Install a Postgres Instance

bash
# create the appdemo namespace
kubectl create namespace appdemo
# provision a postgres cluster
kubectl apply -n appdemo -f - <<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: hoopdemo
        image: postgres
        name: postgres
        ports:
        - containerPort: 5432
          name: pg
          protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: pg
spec:
  ports:
  - name: pg
    port: 5432
    protocol: TCP
    targetPort: 5432
  selector:
    app: postgres
EOF

Deploy the Gateway

Change the attributes config , ingressApi and ingressGrpc accordingly to your system configuration, save this file to appdemo.yaml

Helm values file: appdemo.yaml

yaml
# app deployment related configuration
config:
  API_URL: 'https://appdemo.hoop.dev'
  IDP_CLIENT_ID: '3092f3f9befc781208f5133ef8fc7464'
  IDP_CLIENT_SECRET: '7vaTWBwSAhgavyp0gWQLW+TVK6XxfcKN09Q37iX9zDY'
  IDP_ISSUER: 'https://yourorg.us.auth0.com/'
  IDP_AUDIENCE: 'https://yourorg.us.auth0.com/api/v2/'
  IDP_CUSTOM_SCOPES: ''

xtdbConfig:
  PG_HOST: 'pg.appdemo'
  PG_PORT: '5432'
  PG_USER: 'root'
  PG_PASSWORD: '1a2b3c4d'
  PG_DB: 'hoopdemo'

# app ingress configuration (webapp / api)
ingressApi:
  enabled: true
  host: appdemo.hoop.dev
  ingressClassName: alb
  annotations:
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-east-1:200013399172:certificate/ba3db1ae-027f-4949-8097-31274730e6d8
    alb.ingress.kubernetes.io/group.name: appdemo
    alb.ingress.kubernetes.io/healthcheck-path: /
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTP
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/security-groups: sg-0bdc19ae6ee7cce13
    alb.ingress.kubernetes.io/ssl-redirect: "443"
    alb.ingress.kubernetes.io/subnets: subnet-33c07b4efb9e3defdd,subnet-fa95c4fd44ff7d0d74
    alb.ingress.kubernetes.io/target-type: ip

# app ingress configuration (gRPC)
ingressGrpc:
  enabled: true
  host: appdemo.hoop.dev
  ingressClassName: alb
  annotations:
    alb.ingress.kubernetes.io/backend-protocol-version: GRPC
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-east-1:200013399172:certificate/ba3db1ae-027f-4949-8097-31274730e6d8
    alb.ingress.kubernetes.io/group.name: appdemo
    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/security-groups: sg-0bdc19ae6ee7cce13
    alb.ingress.kubernetes.io/subnets: subnet-33c07b4efb9e3defdd,subnet-fa95c4fd44ff7d0d74
    alb.ingress.kubernetes.io/target-type: ip

To deploy it, download the latest version of the helm chart and create the app with helm

bash
VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoop \
  https://releases.hoop.dev/release/$VERSION/hoop-chart-$VERSION.tgz \
  -f appdemo.yaml \
  --namespace appdemo

deploy the hoop in the appdemo namespace

Wait for the application to start and follow the provisioning of the load balancer to obtain the DNS of the load balancer, the command below should show the address of the load balancer.

bash
$ kubectl get ing -n appdemo
NAME               CLASS   HOSTS              ADDRESS                                                        PORTS   AGE
hoopgateway-grpc   alb     appdemo.hoop.dev   k8s-appdemo-8fb788e609-333220751.us-east-1.elb.amazonaws.com   80      81m
hoopgateway-web    alb     appdemo.hoop.dev   k8s-appdemo-8fb788e609-333220751.us-east-1.elb.amazonaws.com   80      81m

check the load balancer dns ADDRESS

💡

If the address doesn't appear, check if you installed the load balancer controller properly

Configuring DNS

Configure the ADDRESS as a CNAME record in your dns provider. For this demo, the following configuration is necessary.

DNS	TYPE	VALUE
appdemo.hoop.dev	CNAME	k8s-appdemo-8fb788e609-333220751.us-east-1.elb.amazonaws.com

Testing

Once the DNS has propagated, visit the address https://appdemo.hoop.dev and complete the initial signup process. If everything is configured correctly, you should be able to successfully log in with your provider.

Setting up your initial Agent

Now you can start connecting your private infrastructure with agents. Our helm-chart includes a default agent that runs in the same network as the gateway. This is useful if you need to connect to something already available in the Kubernetes cluster network.

Open your terminal and configure the command line to connect to your instance

shell
hoop config create --api-url https://appdemo.hoop.dev

shell
hoop login

Create a default agent

shell
HOOP_KEY=$(hoop admin create agents default)

Re-deploy the gateway enabling the agent container

shell
helm upgrade --install hoop \
  https://releases.hoop.dev/release/$VERSION/hoop-chart-$VERSION.tgz \
  -f appdemo.yaml \
  --set "agentConfig.enabled=true" \
  --set "agentConfig.gateway.key=$HOOP_KEY" \
  --namespace appdemo

💡

This will enable an agent running as a sidecar container alongside with the gateway deployment.

Check if the agent is ONLINE

shell
$ hoop admin get agents
UID   NAME      MODE       VERSION   HOSTNAME   PLATFORM      STATUS
...   default   standard   1.16.3    ...        linux/amd64   ONLINE

Create your first Connection

With your agent running, it is possible to create a connection to interact with a private resource. Let's try creating a connection to interact with the PostgreSQL instance.

Create a Postgres Connection

shell
hoop admin create connection pg-root -a default --type postgres \
  -e HOST=pg.appdemo \
  -e USER=root \
  -e DB=hoopdemo \
  -e PORT=5432 \
  -e PASS=1a2b3c4d

pg-root connection

This connection utilizes the root credentials from the postgres deployment. It is now possible to interact with the connection using the command line.

Native Access (Port Forward)

In this mode you can connect using your favorite IDE or any postgres client available.

bash
$ hoop connect pg-root
connection: pg-root | session: 98f0905c-e1b2-4360-8c4b-3e464730316a

--------------------postgres-credentials--------------------
      host=127.0.0.1 port=5433 user=noop password=noop
------------------------------------------------------------

open a port locally by default in 5433

Open a new terminal and try to connect it with a postgres client

bash
psql -h 127.0.0.1 --port 5433 postgres -c '\l'

list all databases

Ad-hoc Queries

If the user does not have a client installed locally, they can interact with "hoop exec". However, this connection is by default limited to the "hoopdemo" database.

bash
hoop exec pg-root -i '\d+'

list all tables from hoopdemo database