OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Typed Kubernetes Client Generation for OpenRAG
This document explains how to generate and use typed Kubernetes clients for the OpenRAG CRDs.
Overview
Instead of using unstructured.Unstructured, you can now use strongly-typed Go clients that provide:
- Compile-time type safety - Catch errors during development, not runtime
- IDE auto-completion - Better developer experience
- Cleaner code - No manual field path navigation or type assertions
Generating the Clientset
Prerequisites
# Install code-generator dependency
go get k8s.io/[email protected]
Generate Clients
# Generate clientset, listers, and informers
make generate-client
This will create the following packages:
pkg/generated/clientset/versioned- Typed clientsetpkg/generated/listers/api/v1alpha1- Listers for efficient readspkg/generated/informers/externalversions- Informers for watching resources
Usage Examples
Before (Using Unstructured)
import (
"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
"k8s.io/apimachinery/pkg/runtime/schema"
)
// Create unstructured client
dynamicClient, err := dynamic.NewForConfig(config)
gvr := schema.GroupVersionResource{
Group: "openr.ag",
Version: "v1alpha1",
Resource: "openrags",
}
// Get OpenRAG (weakly typed - runtime errors)
obj, err := dynamicClient.Resource(gvr).Namespace("default").Get(ctx, "my-openrag", metav1.GetOptions{})
if err != nil {
return err
}
// Manual field navigation (error-prone)
spec, found, err := unstructured.NestedMap(obj.Object, "spec")
backend, found, err := unstructured.NestedMap(spec, "backend")
image, found, err := unstructured.NestedString(backend, "image")
// No compile-time type checking!
After (Using Typed Client)
import (
openragv1alpha1 "github.com/langflow-ai/openrag-operator/api/v1alpha1"
clientset "github.com/langflow-ai/openrag-operator/pkg/generated/clientset/versioned"
)
// Create typed client
client, err := clientset.NewForConfig(config)
// Get OpenRAG (strongly typed - compile-time safety!)
openrag, err := client.OpenrV1alpha1().OpenRAGs("default").Get(ctx, "my-openrag", metav1.GetOptions{})
if err != nil {
return err
}
// Direct field access with type safety
image := openrag.Spec.Backend.Image // ✅ Type-safe!
replicas := openrag.Spec.Backend.Replicas // ✅ Auto-complete!
Full Example: Creating an OpenRAG Instance
package main
import (
"context"
"fmt"
corev1 "k8s.io/api/core/v1"
"k8s.io/apimachinery/pkg/api/resource"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/client-go/tools/clientcmd"
"k8s.io/utils/ptr"
openragv1alpha1 "github.com/langflow-ai/openrag-operator/api/v1alpha1"
clientset "github.com/langflow-ai/openrag-operator/pkg/generated/clientset/versioned"
)
func main() {
// Load kubeconfig
config, err := clientcmd.BuildConfigFromFlags("", "/path/to/kubeconfig")
if err != nil {
panic(err)
}
// Create OpenRAG typed client
client, err := clientset.NewForConfig(config)
if err != nil {
panic(err)
}
// Define OpenRAG instance
openrag := &openragv1alpha1.OpenRAG{
ObjectMeta: metav1.ObjectMeta{
Name: "my-openrag",
Namespace: "default",
},
Spec: openragv1alpha1.OpenRAGSpec{
TenantID: "tenant-123",
Frontend: openragv1alpha1.FrontendSpec{
ComponentSpec: openragv1alpha1.ComponentSpec{
Image: "myregistry/openrag-frontend:v1.0.0",
Replicas: ptr.To(int32(2)),
Resources: corev1.ResourceRequirements{
Requests: corev1.ResourceList{
corev1.ResourceCPU: resource.MustParse("100m"),
corev1.ResourceMemory: resource.MustParse("256Mi"),
},
},
},
},
Backend: openragv1alpha1.BackendSpec{
ComponentSpec: openragv1alpha1.ComponentSpec{
Image: "myregistry/openrag-backend:v1.0.0",
Replicas: ptr.To(int32(3)),
Env: []corev1.EnvVar{
{Name: "CUSTOM_VAR", Value: "custom_value"},
},
},
Storage: &openragv1alpha1.PersistenceSpec{
Enabled: true,
Size: resource.MustParse("10Gi"),
},
},
Langflow: openragv1alpha1.LangflowSpec{
ComponentSpec: openragv1alpha1.ComponentSpec{
Image: "myregistry/langflow:v1.0.0",
Replicas: ptr.To(int32(2)),
},
PVCReclaimPolicy: openragv1alpha1.PVCReclaimRetain,
},
},
}
// Create the resource
result, err := client.OpenrV1alpha1().OpenRAGs("default").Create(
context.Background(),
openrag,
metav1.CreateOptions{},
)
if err != nil {
panic(err)
}
fmt.Printf("Created OpenRAG: %s\n", result.Name)
// Update the resource
result.Spec.Backend.Replicas = ptr.To(int32(5))
updated, err := client.OpenrV1alpha1().OpenRAGs("default").Update(
context.Background(),
result,
metav1.UpdateOptions{},
)
if err != nil {
panic(err)
}
fmt.Printf("Updated OpenRAG backend replicas to: %d\n", *updated.Spec.Backend.Replicas)
// List all OpenRAG instances
list, err := client.OpenrV1alpha1().OpenRAGs("").List(
context.Background(),
metav1.ListOptions{},
)
if err != nil {
panic(err)
}
fmt.Printf("Found %d OpenRAG instances\n", len(list.Items))
for _, item := range list.Items {
fmt.Printf(" - %s/%s (Phase: %s)\n", item.Namespace, item.Name, item.Status.Phase)
}
}
Using Informers (Efficient Watching)
Informers provide efficient caching and watching of resources:
import (
"time"
"k8s.io/client-go/tools/cache"
informers "github.com/langflow-ai/openrag-operator/pkg/generated/informers/externalversions"
)
// Create informer factory
informerFactory := informers.NewSharedInformerFactory(client, time.Minute*10)
// Get OpenRAG informer
openragInformer := informerFactory.Openr().V1alpha1().OpenRAGs()
// Add event handlers
openragInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
AddFunc: func(obj interface{}) {
openrag := obj.(*openragv1alpha1.OpenRAG)
fmt.Printf("OpenRAG added: %s/%s\n", openrag.Namespace, openrag.Name)
},
UpdateFunc: func(old, new interface{}) {
newOpenRAG := new.(*openragv1alpha1.OpenRAG)
fmt.Printf("OpenRAG updated: %s/%s\n", newOpenRAG.Namespace, newOpenRAG.Name)
},
DeleteFunc: func(obj interface{}) {
openrag := obj.(*openragv1alpha1.OpenRAG)
fmt.Printf("OpenRAG deleted: %s/%s\n", openrag.Namespace, openrag.Name)
},
})
// Start informers
stopCh := make(chan struct{})
defer close(stopCh)
informerFactory.Start(stopCh)
// Wait for cache sync
if !cache.WaitForCacheSync(stopCh, openragInformer.Informer().HasSynced) {
panic("Failed to sync cache")
}
// Now use the lister for efficient reads
lister := openragInformer.Lister()
openrags, err := lister.OpenRAGs("default").List(labels.Everything())
Benefits
Type Safety
// ❌ Unstructured - Runtime error
image := obj.Object["spec"].(map[string]interface{})["backend"].(map[string]interface{})["image"].(string)
// ✅ Typed - Compile-time error if field doesn't exist
image := openrag.Spec.Backend.Image
IDE Support
- Auto-completion for all fields
- Jump to definition
- Inline documentation
- Refactoring support
Cleaner Code
- No type assertions
- No manual field path navigation
- Easier to read and maintain
Regenerating Clients
Run this command whenever you modify the CRD types:
make generate # Regenerate DeepCopy methods
make generate-client # Regenerate clientsets, listers, informers
Distribution
Option 1: Publish as Go Module (Recommended)
Users can import directly:
import clientset "github.com/langflow-ai/openrag-operator/pkg/generated/clientset/versioned"
Option 2: Copy Generated Code
If users don't want to depend on your entire module, they can copy the generated code to their project:
cp -r pkg/generated /path/to/their/project/
Troubleshooting
code-generator not found
If you see this error:
Error: k8s.io/code-generator not found in module cache
Run:
go mod download k8s.io/code-generator
# OR
go get k8s.io/[email protected]
go mod tidy
The dependency is already in go.mod, so go mod download should be sufficient.
Permission denied on script
chmod +x hack/update-codegen.sh
Generated code not in version control
It's recommended to commit generated code to version control so users can use it without running code generation.
CI Check Failures
If your pull request fails with:
Error: git diff --exit-code pkg/generated/
This means you modified the API types but didn't regenerate the typed client. Fix it:
make generate-client
git add pkg/generated/
git commit --amend --no-edit
git push --force-with-lease
Our CI automatically verifies that generated code is up to date to prevent inconsistencies.
Contributing
When modifying API types in api/v1alpha1/, always run:
make generate # Regenerate deepcopy code
make manifests # Regenerate CRDs and RBAC
make generate-client # Regenerate typed client
git add api/ config/ pkg/generated/
git commit -m "feat: add new field to OpenRAG spec"
See docs/CONTRIBUTING.md for more details.