README
¶
Lynq Operator
Kubernetes-Native Database-Driven Automation
Automate node lifecycle from database to production
Overview • Features • Quick Start • Documentation • Contributing
📖 Overview
Lynq Operator is a Kubernetes operator that automates database-driven infrastructure provisioning. It reads node data from external datasources (MySQL, PostgreSQL planned for v1.2) and dynamically creates, updates, and manages Kubernetes resources using declarative templates.
One database row = One fully provisioned node stack
Why Lynq Operator?
Traditional provisioning approaches are limited:
- ❌ Helm: Manual per-node releases and values files
- ❌ GitOps: Static manifests don't scale to thousands of nodes
- ❌ Custom scripts: Fragile, hard to maintain, no drift correction
Lynq Operator provides:
- ✅ Database-driven automation: Your existing database becomes the source of truth
- ✅ Real-time sync: Changes propagate automatically (30s status reflection)
- ✅ Production-grade: SSA, webhooks, finalizers, metrics, and drift detection built-in
📚 Complete Documentation • 🏗️ Architecture Details
✨ Key Features
| Feature | Description |
|---|---|
| 🗄️ Database-Driven | MySQL support (PostgreSQL in v1.2) |
| 📝 Template Engine | Go templates + 200+ Sprig functions |
| 🔄 Server-Side Apply | Conflict-free resource management |
| 📊 Dependencies | DAG-based resource ordering |
| ⚙️ Policies | Fine-grained lifecycle control |
| 🚀 Production-Ready | Webhooks, metrics, drift detection |
Advanced capabilities: Multi-template support, cross-namespace provisioning, orphan cleanup, smart watch predicates, custom template functions (sha1sum, fromJson, toHost), and more.
📖 Full feature list: Documentation
Integrations
- ExternalDNS - Automatic DNS records (Route53, Cloudflare, etc.)
- Terraform Operator - Cloud resource provisioning (S3, RDS, CDN)
- cert-manager - Automatic TLS certificates
- Prometheus/Grafana - Complete monitoring with dashboards
🏗️ Architecture
Lynq Operator uses a three-controller design for database-to-Kubernetes synchronization:
- LynqHub Controller - Syncs database → Creates LynqNode CRs
- LynqForm Controller - Validates templates and linkage
- LynqNode Controller - Renders templates → Applies resources via SSA
Multi-template support: One registry can be referenced by multiple templates (prod, staging, etc.). Desired count = referencingTemplates × activeRows.
📊 Detailed architecture diagrams: Architecture Guide
Supported Kubernetes Versions
| Version | Status |
|---|---|
| v1.28 - v1.33 | ✅ Validated |
| Other GA releases | ⚠️ Expected |
The operator targets GA/stable Kubernetes APIs and is decoupled from specific cluster releases. Validate in staging before production rollout.
🚀 Quick Start
Get started in 5 minutes with a working example:
🎯 Quick Start Guide with Minikube - Automated setup scripts included
Installation (Helm - Recommended)
# 1. Install cert-manager (required for webhooks)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
# 2. Install Lynq Operator
helm repo add lynq-operator https://k8s-lynq.github.io/lynq
helm repo update
helm install lynq k8s-lynq/lynq \
--namespace lynq-system \
--create-namespace
📖 More installation options: Installation Guide
Configuration Example
1. Connect to your database (LynqHub):
apiVersion: operator.lynq.sh/v1
kind: LynqHub
metadata:
name: my-saas-hub
spec:
source:
type: mysql
mysql:
host: mysql.database.svc.cluster.local
database: nodes
table: node_configs
passwordRef:
name: mysql-secret
key: password
syncInterval: 1m
valueMappings:
uid: node_id
hostOrUrl: node_url
activate: is_active # Must be "1", "true", or "yes"
📖 Database setup guide: DataSource Configuration
2. Define resource template (LynqForm):
apiVersion: operator.lynq.sh/v1
kind: LynqForm
metadata:
name: saas-app-template
spec:
hubId: my-saas-hub
deployments:
- id: app
nameTemplate: "{{ .uid }}-app"
spec:
apiVersion: apps/v1
kind: Deployment
spec:
replicas: 2
template:
spec:
containers:
- name: app
image: myapp:latest
env:
- name: NODE_ID
value: "{{ .uid }}"
📖 Template syntax and functions: Template Guide
3. Verify:
kubectl get lynqnodes --watch
kubectl get lynqnode <lynqnode-name> -o yaml
Result: Each active database row automatically provisions a complete node stack!
📚 Documentation
Complete documentation is available at lynq.sh
Quick Links
| Category | Pages |
|---|---|
| Getting Started | Quick Start • Installation |
| Core Concepts | Architecture • API Reference • Templates • Policies • Dependencies |
| Operations | DataSource Setup • Monitoring • Alert Runbooks • Troubleshooting • Performance |
| Integrations | ExternalDNS • Terraform Operator • Argo CD |
| Advanced | Security • Development • Contributing |
Examples
Simple SaaS Application:
INSERT INTO nodes VALUES ('acme-corp', 'https://acme.myapp.io', 1, 'enterprise');
→ Automatically creates Deployment, Service, Ingress, ConfigMaps, and Secrets
Multi-region with custom variables:
extraValueMappings:
region: deployment_region
dbHost: database_host
Template functions:
nameTemplate: "{{ .uid | sha1sum | trunc63 }}" # Unique names
value: "{{ (.config | fromJson).apiKey }}" # Parse JSON
value: "{{ .nodeUrl | toHost }}" # Extract host
📖 More examples: Quick Start Guide
🛠️ Development
Building from Source
# Clone repository
git clone https://github.com/k8s-lynq/lynq.git
cd lynq
# Install dependencies
go mod download
# Run tests
make test
# Build binary
make build
# Build and push container
make docker-build docker-push IMG=<your-registry>/lynq:tag
Running Locally
# Install CRDs
make install
# Run controller locally (uses ~/.kube/config)
make run
# Run with debug logging
LOG_LEVEL=debug make run
Running Tests
# Unit tests
make test
# Integration tests
make test-integration
# E2E tests (requires kind)
make test-e2e
# Coverage report
make test-coverage
🤝 Contributing
We welcome contributions from anyone interested in database-driven Kubernetes automation.
Our vision: We're building this project with open governance and community-first principles. As the project grows, we aspire to join cloud-native foundations like CNCF to foster broader collaboration and adoption.
Ways to contribute:
- 🐛 Bug reports and feature requests
- 📝 Documentation improvements
- 💻 Code contributions (features, bug fixes, optimizations)
- 🌍 Translations and internationalization
- 🎨 UX/UI improvements for tooling
- 📊 Use case sharing and feedback
🌟 Want to Add a New Datasource?
Lynq Operator uses a pluggable adapter pattern that makes it easy to add support for new datasources (PostgreSQL, MongoDB, REST APIs, etc.).
Why contribute a datasource?
- ✅ Only 2 methods to implement
- ✅ MySQL reference implementation to follow
- ✅ Complete step-by-step guide provided
- ✅ Recognition in release notes
📚 Full Guide: Contributing a New Datasource
How to Contribute
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Contribution Guidelines
- Follow Conventional Commits
- Add tests for new features
- Update documentation
- Run
make lintbefore submitting - Ensure all CI checks pass
See CONTRIBUTING.md for detailed guidelines.
🗺️ Roadmap
See full roadmap for details.
📊 Status
| Component | Status | Description |
|---|---|---|
| Core Controllers | ✅ Production | LynqHub, LynqForm, and LynqNode controllers with SSA |
| MySQL Datasource | ✅ Production | Sync from MySQL with column mapping and VIEWs |
| Template Engine | ✅ Production | Go templates with 200+ Sprig functions + custom functions |
| Webhooks | ✅ Production | Validation and defaulting for all CRDs |
| Performance | ✅ Production | Event-driven reconciliation with smart watch predicates |
| Multi-Template | ✅ Production | One registry, multiple templates (prod, staging, etc.) |
| Cross-Namespace | ✅ Production | Provision resources across namespaces with label tracking |
| Orphan Cleanup | ✅ Production | Automatic detection and cleanup of removed resources |
| PostgreSQL | 🚧 Planned | PostgreSQL datasource adapter (v1.2) |
Kubernetes: v1.28-v1.33 validated • Status: Production-ready
❓ FAQ
How is this different from Helm or GitOps?
Lynq Operator is database-driven and designed for SaaS platforms where node data lives in databases, not git repositories. It automates provisioning from database rows with real-time sync, whereas Helm and GitOps require manual per-node configuration.
Can I use my existing database?
Yes! You just need read-only access and column mappings. If your schema doesn't match, create a MySQL VIEW to transform the data.
What values are valid for the `activate` column?
Must be exactly one of: "1", "true", "TRUE", "True", "yes", "YES", "Yes"
All other values (including "active", "0", empty, NULL) are considered inactive. Use a VIEW to transform your data if needed.
⚠️ What happens if I delete LynqHub or LynqForm?
Warning: Causes cascade deletion of all LynqNode CRs and their resources!
Protection: Set deletionPolicy: Retain on resources BEFORE deleting, or update in-place instead of delete/recreate.
How does it scale to thousands of nodes?
Production deployments handle 1000+ nodes with concurrent reconciliation, SSA efficiency, resource caching, and optional sharding.
How fast does it react to changes?
- Immediate: Event-driven drift correction
- 30 seconds: Periodic status reflection
- Configurable: Database sync interval (e.g., 1 minute)
Can one registry support multiple environments?
Yes! One registry can be referenced by multiple templates (prod, staging, dev). Each database row creates multiple LynqNode CRs.
How do I set up webhook certificates?
Install cert-manager first - it automatically manages TLS certificates for webhook communication. See installation guide for details.
📝 License
Copyright 2025 Lynq Operator Authors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
🌟 Acknowledgments
Built with:
- Kubebuilder - Kubernetes operator framework
- Operator SDK - Operator development toolkit
- controller-runtime - Kubernetes controller library
- Sprig - Template function library
Inspired by the cloud-native ecosystem and CNCF projects.
📬 Contact & Community
- 🐛 Issues: GitHub Issues - Report bugs or request features
- 💬 Discussions: GitHub Discussions - Ask questions or share ideas
- 📧 Email: rationlunas@gmail.com - Direct contact for partnership inquiries
We're looking for:
- Users sharing their experiences and use cases
- Contributors interested in database-driven Kubernetes
- Organizations interested in collaboration
Directories