Cortex Self-Managed
Cortex can be deployed on-prem into your own Kubernetes cluster, if you're dealing with sensitive data and don't want information to leave your premises.
We provide the Cortex installation as a Helm chart, making it easy to get started and manage.
Requirements
You'll need a few things to get started with Cortex Self-Managed:
- A running k8s cluster with permission to talk to the public internet (our Docker images are hosted on GitHub)
- Permission to add image pull secrets to the cluster
- Helm Package Manager ready to use
- The Cortex Self-Manged Helm chart, which is provided to you by the Cortex team when beginning an evaluation. If you haven't been granted access, reach out to our team for a demo of the platform.
Installing Cortex
Basics
You'll need to configure your cluster to talk to Cortex.
kubectl create secret docker-registry cortex-docker-registry-secret \
--docker-server=ghcr.io \
--docker-username=gsdatta \
--docker-password=<Token provided to you by the Cortex team> \
--docker-email=<doesn't matter>`
Once you've created the secret, cd
into the helm chart, and run helm install
with your desired configuration.
For example helm install cortex .
The README contains some additional tips on configuring Cortex when running locally in a Minikube cluster.
Cluster installation
If you're installing Cortex into a cloud cluster, for example EKS/GKE, you'll need some additional configuration.
- Ensure that your
values.yaml
file in the Helm chart has been modified as desired. - Install any required plugins to your cluster, e.g.
kubectl apply
the nginx plugin for AWS - Make sure the Docker secret in the previous section has been added to the cluster
- Install the Helm chart normally
Once you've run the Helm install, you'll want to get the hostnames wired up. Get the accessible DNS hostnames for the backend
and frontend
services that the Helm chart exposes (instructions differ based on your cloud provider).
Modify the app.host
field in your values.yaml
file to point to these respective hostnames. If your cloud provider/LB/ingress
automatically sets up TLS, make sure to change app.protocol
to https
.
Run a helm upgrade
to apply the changes.
There are a few things to note when setting up the chart!
- The Helm chart spins up an ephemeral datastore with no persistent volumes, see Setting up a persistent DB
- Auth disabled by default. This means anyone who wants to play with Cortex will have access to the dashboard through a “demo” user.
- The chart does not ship with built in TLS/certs, but if deployed into a cluster behind your existing
load balancer with TLS, you just need to change the
protocol
value in the chart.
Productionalization
Once you have Cortex running, you may want to productionalize it by setting up a persistent DB or SSO.
Persistent Database
Cortex requires a Postgres Database (version 9+), and does not support other datastores. We recommend using your standard DB provider, for example a hosted RDS or Cloud SQL instance.
Prerequisite Setup
Note You must create (or utilize an existing) instance of Postgres and the database within!
- Create a Postgres Database (9+) with UTF8 encoding that will be accessible from your instance. Be sure to create and note:
- The database instance and database with:
instance URI
,database name
, andinstance port
- The username and password to access the database
- Set up database user permissions
- Add
ALL
on the public schema to create/modify tables - Add
INSERT
,SELECT
,UPDATE
,DELETE
on all tables in the public schema - This is tied to the default
public.schema
- Add
- The database instance and database with:
Using Kubectl
- Create a k8s secret which will hold your DB credentials
kubectl create secret generic cortex-secret \
--from-literal DB_HOST="hostname (without jdbc:postgresql:// or the port)" \
--from-literal DB_PORT=5432 \
--from-literal DB_USERNAME=postgres \
--from-literal DB_NAME=postgres \
--from-literal DB_PASSWORD=mysecretpassword - (Alternative to Step 1 – creating secret manually) Add your DB credentials to a new secret (keeping in mind k8s secrets are base64 encoded):
DB_HOST
DB_NAME
DB_USERNAME
DB_PASSWORD
DB_PORT
- Uncomment the
secret
field in values.yaml, and add the name of the secret you just created - Remove the
DB_*
fields fromtemplates/backend/configmap.yaml
in the Helm chart - Run
helm upgrade
Resources
- 2 instances of backend container, with 3.5GB memory per instance (2 cores recommended)
- 1 instance of frontend container, low memory requirement (<500mb is enough, it's a static nginx proxy)
- Postgres DB v9+ with 15GB storage and 4GB memory with max number of connections ≥100. The max number of connections should be ≥2x the backend's connection pool size, which is 50 by default (25 per instance).
Debugging
Debugging kubernetes and helm charts can be painful at times. Here's a few things that can help along the way
- Try running
helm install
with the--dry-run
flag. This prints out all the configurations without actually going installing the chart. More information on debugging the helm install command can be found here.