Kubernetes

Kubernetes overview

The Enterprise Server runs on Kubernetes the way it runs on a machine: one process, knwlge-enterprise start, in one pod. These guides take a cluster in Azure, AWS or Google Cloud to an enrolled server that developers can use, with the cloud's own database, storage and load balancer.

How it runs in a cluster

• One Deployment, one replica. The pod runs api-mcp, the worker and the scheduled jobs (the licence heartbeat, usage export, retention and memory hygiene) together. A second replica would run every job twice, so it is replaced, never scaled.
• A persistent volume for its home. /var/lib/knwlge-enterprise holds config.json, which the setup wizard writes and which carries the database password and generated secrets, state.json, and logs. A few gigabytes are plenty, unless artifacts are kept there too.
• Managed PostgreSQL 18 with pgvector outside the cluster: Azure Database for PostgreSQL, RDS or Cloud SQL. The setup wizard's database role runs the migrations, which create the limited role the server runs as.
• Somewhere for artifacts: Azure Blob, an S3 bucket, or a directory on the volume.
• The cloud's load balancer in front, terminating HTTPS for your host and sending traffic to the server's port 3000 through a Service.

Before you start

• A cluster, or the right to create one, and kubectl pointed at it. x64 nodes are the default; arm64 nodes take the arm64 build.
• A hostname you control DNS for, such as knwlge.acme.example. It must be reachable from the internet over HTTPS: developers' machines call it, and Knwlge Global pushes token revocations to it.
• Outbound HTTPS from the cluster to api.knwlge.com, to your database and storage, and to GitHub or Azure DevOps for the repositories you index.
• A project in the Knwlge app whose Enterprise Server URL is https:// and your host, and an enrollment key for it. Create the project from My Projects → New project, in your organization: you become its admin, and its first key is shown once.
• The release for your nodes from the Downloads page. The cluster never downloads anything itself: you build an image and push it to your own registry.

The steps

Every guide follows the same order; only the cloud's services and commands differ.

1. Build the image

   From the release tarball and the Dockerfile, pushed to the cloud's registry.

2. Create the database and storage

   PostgreSQL 18 with pgvector that the cluster can reach, and a bucket or container for artifacts.

3. Run the setup wizard in a pod

   A pod mounting the server's volume runs knwlge-enterprise setup, which enrolls nothing yet but writes config.json and runs the migrations.

4. Start the server

   The Deployment and its Service. The first start enrolls with Knwlge Global.

5. Put HTTPS in front

   The cloud's load balancer with a certificate for your host, and a DNS record pointing at it.

The setup wizard in a pod

kubectl exec -it gives the wizard the terminal it needs. It asks what it asks on any machine (Local Private Server) and checks each answer from inside the cluster, so a database or bucket the cluster cannot reach is caught before the server ever starts. Answer No when it offers to start the server: the Deployment does that.

To change an answer later, run it again in the running pod and restart the server:

kubectl -n knwlge exec -it deploy/knwlge-enterprise -- knwlge-enterprise setup
kubectl -n knwlge rollout restart deploy/knwlge-enterprise

A rerun keeps the generated secrets: they protect keys already stored in the database. Never delete the volume of a server you want to keep.

Upgrading

In a container the server never replaces its own files: Settings → Updates in the console shows each new release with what is new in it, and tells you to roll out a new image. To upgrade:

# Build and push the new version's image as you did the first (Container image), then:
kubectl -n knwlge set image deploy/knwlge-enterprise server=<registry>/knwlge-enterprise:<new-version>
kubectl -n knwlge rollout status deploy/knwlge-enterprise --timeout=10m

The old pod stops, the new one runs the migrations under the data guard — a migration that would lose data rolls back and the pod fails to start, leaving the database as it was — and then serves. Take a database snapshot before a major version all the same. To go back, restore the snapshot and set the previous tag.

Day to day

• Backups. The database holds everything that matters: keep the provider's automated backups and point-in-time recovery on. Snapshot the volume too, for config.json — without its secrets a restored database cannot be read back. Artifacts in a bucket follow the bucket's own versioning.
• Size. The pod asks for half a CPU and 1 GiB and may use 2 GiB; it idles well below that. Give it more memory if indexing very large repositories hits the limit.
• No Redis needed. A single server keeps its counters in memory and its queue in PostgreSQL.

Troubleshooting