Run it · Run on Kubernetes

Run on Kubernetes

Deploy Polign with Helm on EKS, GKE, AKS, or your own cluster. You need Kubernetes 1.30+, Helm 3.22+, and kubectl configured for the cluster.

What runs where

The chart creates a single-server Deployment, an internal Service, and a ServiceAccount. With bucket storage, records persist in your bucket and the pod keeps a disposable cache. You configure cloud resources and permissions separately.

Try it without a bucket

For a trial, use a persistent volume. Create an API key in a Kubernetes Secret, then install the chart:

# namespace, key, install
kubectl create namespace polign

kubectl -n polign create secret generic polign-key \
  --from-literal=api-key="plgn_$(openssl rand -hex 8)_$(openssl rand -hex 32)"

helm install polign oci://ghcr.io/polign/charts/polign --version 0.2.0 \
  --namespace polign \
  --set store.claim.create=true \
  --set auth.existingSecret=polign-key --wait

API-key authentication is enabled. The server registers the Secret's key at startup.

Evaluation storage

Helm retains the volume on uninstall, but durability depends on your storage provider. Use a bucket for production.

Try it out

Forward the database Service to your machine, then choose an example:

# leave this running; use a second terminal below
kubectl -n polign port-forward service/polign 23100:23000

Use Recall to save a preference, change it, and read its history. You need Python 3.10+, Git, and the Polign CLI v0.6.4+.

In a second terminal, install the Recall client and set its connection:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/Polign/recall.git#subdirectory=python"

export POLIGN_URL=http://127.0.0.1:23100
export POLIGN_COLLECTION=agent_memory
export POLIGN_API_KEY=$(kubectl -n polign get secret polign-key -o jsonpath='{.data.api-key}' | base64 -d)

Run this in Python:

from polign_recall import Client

with Client() as memory:
    memory.remember("user", "prefers_response_style", "detailed")
    memory.remember("user", "prefers_response_style", "concise")
    print(memory.recall("user", "prefers_response_style")[0].value)  # concise
    print(memory.history("user", "prefers_response_style"))  # both statements

Another agent using the same connection and collection can read the updated preference. The earlier statement stays in its history.

In a second terminal, store a vector and find similar records with the HTTP API. The first write creates the collection.

KEY=$(kubectl -n polign get secret polign-key -o jsonpath='{.data.api-key}' | base64 -d)

curl -X PUT localhost:23100/v1/collections/docs/vectors/cats \
  -H "Authorization: Bearer $KEY" \
  -d '{"values":[1,0,0],"metadata":{"title":"Cats"}}'

curl -X POST localhost:23100/v1/collections/docs/query \
  -H "Authorization: Bearer $KEY" \
  -d '{"values":[0.9,0.1,0],"k":5}'

Point it at your bucket

Use a dedicated bucket prefix and a workload identity with read, write, list, and delete access. Do not share the prefix with another running deployment.

Backendstore.uriIdentity
Amazon S3s3://bucket/polignIAM role for service accounts, or Pod Identity
Google Cloud Storagegcs://bucket/polignGKE Workload Identity
Azure Blob Storageaz://account/container/polignAzure Workload Identity

For EKS with an IAM role for service accounts, save polign-values.yaml:

# polign-values.yaml
store:
  uri: s3://your-bucket/polign
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/polign
env:
  - name: AWS_REGION
    value: us-east-1

Create the namespace and Secret as above, then install a new release with these values. This does not migrate data from a trial volume.

helm install polign oci://ghcr.io/polign/charts/polign --version 0.2.0 \
  --namespace polign -f polign-values.yaml \
  --set auth.existingSecret=polign-key \
  --wait --timeout 10m

The IAM role's trust policy must allow the polign/polign namespace and service account pair.

For an S3-compatible endpoint, set AWS_ENDPOINT_URL_S3 and AWS_S3_FORCE_PATH_STYLE=true through env. Store static credentials in a Secret referenced through envFrom or env[].valueFrom.secretKeyRef.

Connect your applications

Applications in the cluster use the Service address and the key from the Secret. HTTP uses port 23000; gRPC uses 23001.

POLIGN_URL=http://polign.polign.svc:23000
POLIGN_COLLECTION=agent_memory

Set POLIGN_API_KEY from polign-key using env[].valueFrom.secretKeyRef.

Upgrades and recovery

Verifying the chart

Verify the chart's Sigstore signature to check that it came from Polign's release workflow:

cosign verify ghcr.io/polign/charts/polign:0.2.0 \
  --certificate-identity-regexp '^https://github\.com/Polign/polign/\.github/workflows/chart-release\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Next