# Helm Chart

The Helm chart option separates the infrastructure and permission provisioning process from the DBNL platform deployment process, allowing you to manage the infrastructure, permissions and Helm chart using your existing processes.

To get the Helm chart, see [ghcr.io/dbnlai/charts/dbnl](https://ghcr.io/dbnlai/charts/dbnl).

## Prerequisites

The following prerequisite steps are required before starting the Helm chart installation.

### Infrastructure

To successfully deploy the DBNL Helm chart, you will need the following infrastructure:

* A Kubernetes cluster (e.g. [EKS](https://aws.amazon.com/eks/), [GKE](https://cloud.google.com/kubernetes-engine)).
  * An [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) or [Gateway](https://kubernetes.io/docs/concepts/services-networking/gateway/) controller (e.g. [aws-load-balancer-controller](https://github.com/kubernetes-sigs/aws-load-balancer-controller), [ingress-gce](https://github.com/kubernetes/ingress-gce))
* A PostgreSQL database (e.g. [RDS](https://aws.amazon.com/rds/), [CloudSQL](https://cloud.google.com/sql)).
* An object store bucket (e.g. [S3](https://aws.amazon.com/s3/), [GCS](https://cloud.google.com/storage)) to store raw data.
* A Redis database (e.g. [ElasticCache](https://aws.amazon.com/elasticache/), [Memorystore](https://cloud.google.com/memorystore)) to act as a messaging queue.

### Configuration

To configure the DBNL Helm chart, you will need:

* A hostname to host the DBNL platform (e.g. dbnl.example.com).
* A set of DBNL registry credentials to pull the DBNL artifacts (e.g. Docker images, Helm chart).
* An RSA key pair to sign the [personal access tokens](https://docs.dbnl.com/v0.27.x/authentication#api-authentication).

An RSA key pair can be generated with:

```bash
openssl genrsa -out dbnl_dev_token_key.pem 2048
```

### Requirements

To install the DBNL Helm chart, you will need:

* Install [kubectl](https://kubernetes.io/docs/tasks/tools/) and set the Kubernetes cluster context.
* Install [helm](https://helm.sh/docs/intro/install/).

### Permissions

For the services deployed by the Helm chart to work as expected, they will need the following permissions and network accesses:

* api-srv
  * Network access to the database.
  * Network access to the Redis database.
  * Permission to read, write and generate pre-signed URLs on the object store bucket.
* worker-srv
  * Network access to the database.
  * Network access to the Redis database.
  * Permission to read and write to the object store bucket.

## Installation

The Helm chart can be installed directly using [helm install](https://helm.sh/docs/helm/helm_install/) or using your chart release management tool of choice such as [ArgoCD](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/) or [FluxCD](https://fluxcd.io/flux/guides/helmreleases/).

### Steps

The steps to install the Helm chart using the Helm CLI are as follows:

1. Create a minimal `values.yaml` file.

<pre class="language-yaml"><code class="lang-yaml"><strong>auth:
</strong><strong>  # For more details on OIDC options, see OIDC Authentication section.
</strong>  oidc:
    enabled:   true
    issuer:    oidc.example.com
    audience:  xxxxxxxx
    clientId:  xxxxxxxx
    scopes:    "openid email profile"

db:
  host: db.example.com
  port: 5432
  username: user
  password: password
  database: database

redis:
  host: redis.example.com
  port: 6379
  username: user
  password: password

ingress:
  enabled: true
  api:
    host: dbnl.example.com
  ui:
    host: dbnl.example.com

storage:
  s3:
    enabled: true
    region: us-east-1
    bucket: example-bucket
</code></pre>

2. Install the Helm chart.

```bash
helm upgrade \
    --install \
    -f values.yaml \
    dbnl oci://ghcr.io/dbnlai/charts/dbnl
```

### Options

For more details on all the installation options, see the Helm chart README and values.yaml files. The chart can be inspected with:

```bash
helm show all oci://ghcr.io/dbnlai/charts/dbnl --version $VERSION
```

## Troubleshooting

### Deployment Issues

**Image pull errors:**

```bash
# Check if registry secret exists
kubectl get secret dbnl-registry-secret -n dbnl

# If missing, contact Distributional for registry credentials
# Then create the secret:
kubectl create secret docker-registry dbnl-registry-secret \
  --docker-server=ghcr.io \
  --docker-username=YOUR_USERNAME \
  --docker-password=YOUR_TOKEN \
  -n dbnl
```

**Database connection failures:**

```bash
# Check database connectivity from a pod
kubectl run -it --rm debug --image=postgres:13 -n dbnl -- \
  psql -h YOUR_DB_HOST -U YOUR_DB_USER -d YOUR_DB_NAME

# Verify values.yaml has correct db.host, db.username, db.password
```

**Pods not starting:**

```bash
# Check pod status
kubectl get pods -n dbnl

# View pod logs
kubectl logs -n dbnl deployment/api-srv
kubectl logs -n dbnl deployment/worker-srv

# Describe pod for events
kubectl describe pod -n dbnl POD_NAME
```

**Ingress not created:**

```bash
# Check ingress status
kubectl get ingress -n dbnl

# Verify ingress controller is installed
kubectl get pods -n ingress-nginx  # or your ingress namespace

# Check ingress events
kubectl describe ingress -n dbnl dbnl-ingress
```

**OIDC authentication failures:**

* Verify `auth.oidc.issuer`, `auth.oidc.clientId`, and `auth.oidc.audience` match your IDP configuration
* Check that redirect URIs in your IDP include `https://YOUR_DOMAIN/auth/callback`
* Ensure OIDC scopes include at minimum: `openid email profile`

### Validation Steps

After deployment, verify the installation:

```bash
# Check all pods are running
kubectl get pods -n dbnl
# Expected: api-srv, worker-srv, ui-srv all in Running state

# Check services
kubectl get svc -n dbnl

# Test API health endpoint
kubectl port-forward -n dbnl svc/api-srv 8080:80
curl http://localhost:8080/health

# Access the UI
kubectl get ingress -n dbnl
# Note the ADDRESS and navigate to https://YOUR_DOMAIN
```

**Need more help?** Contact <support@distributional.com>