Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

feat: operator helm (#1535)

mingddea5308bff3
diff --git a/.github/workflows/operator-ci.yml b/.github/workflows/operator-ci.yml
index 612483d3f..72e40f477 100644
--- a/.github/workflows/operator-ci.yml
+++ b/.github/workflows/operator-ci.yml
@@ -4,12 +4,14 @@ on:
pull_request:
paths:
- 'kubernetes/operator/**'
+ - 'kubernetes/helm/operator/**'
- '.github/workflows/operator-ci.yml'
push:
branches:
- main
paths:
- 'kubernetes/operator/**'
+ - 'kubernetes/helm/operator/**'
jobs:
ci:
@@ -63,6 +65,34 @@ jobs:
version: v2.11.4
working-directory: kubernetes/operator
+ helm:
+ name: Helm lint and verify
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Helm
+ uses: azure/setup-helm@v4
+ with:
+ version: 'v3.14.0'
+
+ - name: Lint Helm chart
+ run: helm lint kubernetes/helm/operator
+
+ - name: Template Helm chart
+ run: |
+ helm template openrag-operator kubernetes/helm/operator \
+ --namespace openrag-control \
+ --debug
+
+ - name: Verify CRD symlink
+ run: |
+ if [ ! -L kubernetes/helm/operator/crds/openr.ag_openrags.yaml ]; then
+ echo "Error: CRD file is not a symlink"
+ exit 1
+ fi
+ echo "CRD symlink verified"
+
docker:
name: Docker build check
runs-on: ubuntu-latest
diff --git a/kubernetes/helm/operator/.helmignore b/kubernetes/helm/operator/.helmignore
new file mode 100644
index 000000000..691fa13d6
--- /dev/null
+++ b/kubernetes/helm/operator/.helmignore
@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/
\ No newline at end of file
diff --git a/kubernetes/helm/operator/Chart.yaml b/kubernetes/helm/operator/Chart.yaml
new file mode 100644
index 000000000..a0daab5af
--- /dev/null
+++ b/kubernetes/helm/operator/Chart.yaml
@@ -0,0 +1,17 @@
+apiVersion: v2
+name: openrag-operator
+description: A Helm chart for the OpenRAG Kubernetes Operator
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+keywords:
+ - openrag
+ - operator
+ - kubernetes
+home: https://github.com/langflow-ai/openrag
+sources:
+ - https://github.com/langflow-ai/openrag
+maintainers:
+ - name: OpenRAG Team
+ url: https://github.com/langflow-ai/openrag
+
diff --git a/kubernetes/helm/operator/crds/openr.ag_openrags.yaml b/kubernetes/helm/operator/crds/openr.ag_openrags.yaml
new file mode 120000
index 000000000..cc8e476b7
--- /dev/null
+++ b/kubernetes/helm/operator/crds/openr.ag_openrags.yaml
@@ -0,0 +1 @@
+../../../operator/config/crd/bases/openr.ag_openrags.yaml
\ No newline at end of file
diff --git a/kubernetes/helm/operator/templates/NOTES.txt b/kubernetes/helm/operator/templates/NOTES.txt
new file mode 100644
index 000000000..29e3f6db1
--- /dev/null
+++ b/kubernetes/helm/operator/templates/NOTES.txt
@@ -0,0 +1,45 @@
+Thank you for installing {{ .Chart.Name }}!
+
+Your release is named {{ .Release.Name }}.
+
+The OpenRAG Operator has been deployed to namespace: {{ .Release.Namespace }}
+
+To verify the installation:
+
+ kubectl get deployment -n {{ .Release.Namespace }} {{ include "openrag-operator.fullname" . }}
+ kubectl get pods -n {{ .Release.Namespace }} -l control-plane=controller-manager
+
+To check the operator logs:
+
+ kubectl logs -n {{ .Release.Namespace }} -l control-plane=controller-manager -f
+
+The operator will watch for OpenRAG custom resources. To create an OpenRAG instance:
+
+ kubectl apply -f - <<EOF
+ apiVersion: openr.ag/v1alpha1
+ kind: OpenRAG
+ metadata:
+ name: my-openrag
+ namespace: default
+ spec:
+ frontend:
+ image: langflowai/openrag-frontend:latest
+ backend:
+ image: langflowai/openrag-backend:latest
+ envSecret: my-backend-env
+ storage:
+ enabled: true
+ size: 10Gi
+ langflow:
+ image: langflowai/openrag-langflow:latest
+ envSecret: my-langflow-env
+ storage:
+ enabled: true
+ size: 10Gi
+ opensearch:
+ host: opensearch.default.svc.cluster.local
+ credentialsSecret: opensearch-credentials
+ EOF
+
+For more information, visit:
+ https://github.com/langflow-ai/openrag
\ No newline at end of file
diff --git a/kubernetes/helm/operator/templates/_helpers.tpl b/kubernetes/helm/operator/templates/_helpers.tpl
new file mode 100644
index 000000000..edd9f5a9d
--- /dev/null
+++ b/kubernetes/helm/operator/templates/_helpers.tpl
@@ -0,0 +1,71 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "openrag-operator.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "openrag-operator.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "openrag-operator.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "openrag-operator.labels" -}}
+helm.sh/chart: {{ include "openrag-operator.chart" . }}
+{{ include "openrag-operator.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "openrag-operator.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "openrag-operator.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+control-plane: controller-manager
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "openrag-operator.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "openrag-operator.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Image reference
+*/}}
+{{- define "openrag-operator.image" -}}
+{{- $tag := .Values.image.tag | default .Chart.AppVersion }}
+{{- printf "%s:%s" .Values.image.repository $tag }}
+{{- end }}
\ No newline at end of file
diff --git a/kubernetes/helm/operator/templates/deployment.yaml b/kubernetes/helm/operator/templates/deployment.yaml
new file mode 100644
index 000000000..7572c8363
--- /dev/null
+++ b/kubernetes/helm/operator/templates/deployment.yaml
@@ -0,0 +1,67 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: {{ include "openrag-operator.fullname" . }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+spec:
+ replicas: {{ .Values.replicaCount }}
+ selector:
+ matchLabels:
+ {{- include "openrag-operator.selectorLabels" . | nindent 6 }}
+ template:
+ metadata:
+ {{- with .Values.podAnnotations }}
+ annotations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ labels:
+ {{- include "openrag-operator.selectorLabels" . | nindent 8 }}
+ spec:
+ {{- with .Values.imagePullSecrets }}
+ imagePullSecrets:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ serviceAccountName: {{ include "openrag-operator.serviceAccountName" . }}
+ securityContext:
+ {{- toYaml .Values.podSecurityContext | nindent 8 }}
+ containers:
+ - name: manager
+ image: {{ include "openrag-operator.image" . }}
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ args:
+ {{- if .Values.leaderElection.enabled }}
+ - --leader-elect
+ {{- end }}
+ - --health-probe-bind-address={{ .Values.healthProbe.bindAddress }}
+ securityContext:
+ {{- toYaml .Values.securityContext | nindent 10 }}
+ livenessProbe:
+ httpGet:
+ path: /healthz
+ port: 8081
+ initialDelaySeconds: 15
+ periodSeconds: 20
+ readinessProbe:
+ httpGet:
+ path: /readyz
+ port: 8081
+ initialDelaySeconds: 5
+ periodSeconds: 10
+ resources:
+ {{- toYaml .Values.resources | nindent 10 }}
+ terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
+ {{- with .Values.nodeSelector }}
+ nodeSelector:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.affinity }}
+ affinity:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.tolerations }}
+ tolerations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+
diff --git a/kubernetes/helm/operator/templates/leader_election_role.yaml b/kubernetes/helm/operator/templates/leader_election_role.yaml
new file mode 100644
index 000000000..fb621a00d
--- /dev/null
+++ b/kubernetes/helm/operator/templates/leader_election_role.yaml
@@ -0,0 +1,20 @@
+{{- if .Values.leaderElection.enabled }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+ name: {{ include "openrag-operator.fullname" . }}-leader-election-role
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+rules:
+- apiGroups: [""]
+ resources: ["configmaps"]
+ verbs: ["get","list","watch","create","update","patch","delete"]
+- apiGroups: ["coordination.k8s.io"]
+ resources: ["leases"]
+ verbs: ["get","list","watch","create","update","patch","delete"]
+- apiGroups: [""]
+ resources: ["events"]
+ verbs: ["create","patch"]
+{{- end }}
+
diff --git a/kubernetes/helm/operator/templates/leader_election_rolebinding.yaml b/kubernetes/helm/operator/templates/leader_election_rolebinding.yaml
new file mode 100644
index 000000000..f553bfa56
--- /dev/null
+++ b/kubernetes/helm/operator/templates/leader_election_rolebinding.yaml
@@ -0,0 +1,18 @@
+{{- if .Values.leaderElection.enabled }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: {{ include "openrag-operator.fullname" . }}-leader-election-rolebinding
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: Role
+ name: {{ include "openrag-operator.fullname" . }}-leader-election-role
+subjects:
+- kind: ServiceAccount
+ name: {{ include "openrag-operator.serviceAccountName" . }}
+ namespace: {{ .Release.Namespace }}
+{{- end }}
+
diff --git a/kubernetes/helm/operator/templates/role.yaml b/kubernetes/helm/operator/templates/role.yaml
new file mode 100644
index 000000000..0edba5f34
--- /dev/null
+++ b/kubernetes/helm/operator/templates/role.yaml
@@ -0,0 +1,83 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: {{ include "openrag-operator.fullname" . }}-manager-role
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+rules:
+- apiGroups:
+ - ""
+ resources:
+ - namespaces
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - watch
+- apiGroups:
+ - ""
+ resources:
+ - persistentvolumeclaims
+ - secrets
+ - serviceaccounts
+ - services
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - patch
+ - update
+ - watch
+- apiGroups:
+ - apps
+ resources:
+ - deployments
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - patch
+ - update
+ - watch
+- apiGroups:
+ - networking.k8s.io
+ resources:
+ - networkpolicies
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - patch
+ - update
+ - watch
+- apiGroups:
+ - openr.ag
+ resources:
+ - openrags
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - patch
+ - update
+ - watch
+- apiGroups:
+ - openr.ag
+ resources:
+ - openrags/finalizers
+ verbs:
+ - update
+- apiGroups:
+ - openr.ag
+ resources:
+ - openrags/status
+ verbs:
+ - get
+ - patch
+ - update
+
diff --git a/kubernetes/helm/operator/templates/rolebinding.yaml b/kubernetes/helm/operator/templates/rolebinding.yaml
new file mode 100644
index 000000000..c73053909
--- /dev/null
+++ b/kubernetes/helm/operator/templates/rolebinding.yaml
@@ -0,0 +1,15 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: {{ include "openrag-operator.fullname" . }}-manager-rolebinding
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: {{ include "openrag-operator.fullname" . }}-manager-role
+subjects:
+- kind: ServiceAccount
+ name: {{ include "openrag-operator.serviceAccountName" . }}
+ namespace: {{ .Release.Namespace }}
+
diff --git a/kubernetes/helm/operator/templates/serviceaccount.yaml b/kubernetes/helm/operator/templates/serviceaccount.yaml
new file mode 100644
index 000000000..42e251076
--- /dev/null
+++ b/kubernetes/helm/operator/templates/serviceaccount.yaml
@@ -0,0 +1,15 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: {{ include "openrag-operator.serviceAccountName" . }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "openrag-operator.labels" . | nindent 4 }}
+ {{- with .Values.serviceAccount.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}
+
diff --git a/kubernetes/helm/operator/values.yaml b/kubernetes/helm/operator/values.yaml
new file mode 100644
index 000000000..0f0bdb907
--- /dev/null
+++ b/kubernetes/helm/operator/values.yaml
@@ -0,0 +1,74 @@
+# Default values for openrag-operator
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+# Operator image configuration
+image:
+ repository: ghcr.io/langflow-ai/openrag-operator
+ pullPolicy: IfNotPresent
+ # Overrides the image tag whose default is the chart appVersion.
+ tag: ""
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+# Number of operator replicas (typically 1 for leader election)
+replicaCount: 1
+
+# Service account configuration
+serviceAccount:
+ # Specifies whether a service account should be created
+ create: true
+ # Automatically mount a ServiceAccount's API credentials?
+ automount: true
+ # Annotations to add to the service account
+ annotations: {}
+ # The name of the service account to use.
+ # If not set and create is true, a name is generated using the fullname template
+ name: ""
+
+# Pod annotations
+podAnnotations: {}
+
+# Pod security context
+podSecurityContext:
+ runAsNonRoot: true
+ # fsGroup: 2000
+
+# Container security context
+securityContext:
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop:
+ - ALL
+ # readOnlyRootFilesystem: true
+ # runAsNonRoot: true
+ # runAsUser: 1000
+
+# Resource limits and requests
+resources:
+ limits:
+ cpu: 100m
+ memory: 128Mi
+
+# Leader election configuration
+leaderElection:
+ enabled: true
+
+# Health probe configuration
+healthProbe:
+ bindAddress: ":8081"
+
+# Node selector for pod assignment
+nodeSelector: {}
+
+# Tolerations for pod assignment
+tolerations: []
+
+# Affinity for pod assignment
+affinity: {}
+
+# Termination grace period in seconds
+terminationGracePeriodSeconds: 10
+
diff --git a/kubernetes/operator/README.md b/kubernetes/operator/README.md
index aa5c299d5..222934ee2 100644
--- a/kubernetes/operator/README.md
+++ b/kubernetes/operator/README.md
@@ -8,6 +8,52 @@ External dependencies (OpenSearch, Docling) are referenced by connection config
- Go 1.26.0 (`gvm use go1.26.0`)
- kubectl pointed at a cluster
+- Helm 3.x (for Helm chart installation)
+
+## Installation
+
+### Option 1: Using Helm (Recommended)
+
+The Helm chart deploys both the CRDs and the operator deployment.
+
+```bash
+# Install from local chart
+helm install openrag-operator ./kubernetes/helm/operator \
+ --namespace openrag-control \
+ --create-namespace
+
+# Verify installation
+kubectl get deployment -n openrag-control
+kubectl get crd openrags.openr.ag
+```
+
+**Customize installation:**
+
+```bash
+# Set custom image tag
+helm install openrag-operator ./kubernetes/helm/operator \
+ --namespace openrag-control \
+ --create-namespace \
+ --set image.tag=v0.1.0
+
+# Or use a values file
+helm install openrag-operator ./kubernetes/helm/operator \
+ --namespace openrag-control \
+ --create-namespace \
+ -f my-values.yaml
+```
+
+### Option 2: Using kubectl + kustomize
+
+```bash
+# Install CRDs
+make install
+
+# Deploy the operator
+make deploy IMG=ghcr.io/langflow-ai/openrag-operator:latest
+```
+
+### Option 3: Local development (see below)
## Local development cluster (kind + podman)
@@ -71,7 +117,7 @@ go run cmd/main.go
kind delete cluster --name openrag
```
-## Quick start
+## Quick start (development)
```bash
make deps # download controller-gen, kustomize, envtest into ./bin
@@ -89,6 +135,90 @@ kubectl apply -f config/samples/openrag_v1alpha1_openrag.yaml
kubectl get openrag
```
+## Helm Chart
+
+The operator Helm chart is located at `kubernetes/helm/operator/` with the following structure:
+
+```
+kubernetes/helm/operator/
+├── Chart.yaml # Chart metadata
+├── values.yaml # Default configuration values
+├── .helmignore # Files to ignore when packaging
+├── crds/
+│ └── openr.ag_openrags.yaml # OpenRAG CRD (auto-installed)
+└── templates/
+ ├── _helpers.tpl # Template helpers
+ ├── NOTES.txt # Post-install notes
+ ├── deployment.yaml # Operator deployment
+ ├── serviceaccount.yaml # Service account
+ ├── role.yaml # ClusterRole for operator
+ ├── rolebinding.yaml # ClusterRoleBinding
+ ├── leader_election_role.yaml # Role for leader election
+ └── leader_election_rolebinding.yaml
+```
+
+### Helm Chart Configuration
+
+Key configurable values in `values.yaml`:
+
+```yaml
+image:
+ repository: ghcr.io/langflow-ai/openrag-operator
+ tag: "" # defaults to chart appVersion
+ pullPolicy: IfNotPresent
+
+replicaCount: 1
+
+resources:
+ limits:
+ cpu: 500m
+ memory: 128Mi
+ requests:
+ cpu: 10m
+ memory: 64Mi
+
+leaderElection:
+ enabled: true
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
+```
+
+### Helm Chart Operations
+
+**Lint the chart:**
+```bash
+helm lint ./kubernetes/helm/operator
+```
+
+**Template the chart (dry-run):**
+```bash
+helm template openrag-operator ./kubernetes/helm/operator \
+ --namespace openrag-control
+```
+
+**Package the chart:**
+```bash
+helm package ./kubernetes/helm/operator
+```
+
+**Upgrade the operator:**
+```bash
+helm upgrade openrag-operator ./kubernetes/helm/operator \
+ --namespace openrag-control
+```
+
+**Uninstall:**
+```bash
+helm uninstall openrag-operator --namespace openrag-control
+```
+
+**Note:** CRDs are not automatically upgraded by Helm. If the CRD changes, manually apply it:
+```bash
+kubectl apply -f kubernetes/helm/operator/crds/openr.ag_openrags.yaml
+```
+
## CR overview
```yaml
@@ -121,3 +251,35 @@ spec:
```
See [`config/samples/openrag_v1alpha1_openrag.yaml`](config/samples/openrag_v1alpha1_openrag.yaml) for a full annotated example.
+
+## Release Process
+
+The operator uses GitHub Actions for automated releases:
+
+### Docker Image Publishing
+
+Images are automatically published to GitHub Container Registry (GHCR) when you push a tag:
+
+```bash
+# Create and push a release tag
+git tag operator/v0.1.0
+git push origin operator/v0.1.0
+```
+
+This triggers the `.github/workflows/operator-release.yml` workflow which:
+1. Builds multi-architecture images (linux/amd64, linux/arm64)
+2. Pushes to `ghcr.io/<owner>/openrag-operator:v0.1.0`
+3. Creates a multi-arch manifest with `:latest` tag
+4. Creates a GitHub release with release notes
+
+**Manual trigger:**
+You can also trigger the release workflow manually from the GitHub Actions UI with a custom tag.
+
+**Image location:**
+- Registry: `ghcr.io`
+- Repository: `ghcr.io/langflow-ai/openrag-operator`
+- Tags: `v0.1.0`, `v0.1.0-amd64`, `v0.1.0-arm64`, `latest`
+
+### Helm Chart Publishing
+
+(To be implemented) Helm charts can be published to GitHub Pages or a Helm repository using GitHub Actions.