feat: ⚠️ Important!⚠️ declarative GitOps configuration via Helm values + fsnotify watcher (Fixes #226, #360, #233)

[DioCrafts]

Declarative GitOps configuration via Helm values + fsnotify file watcher

Branch: feat/crd-declarative-config
Closes: #226, #360, #233

---

Hey maintainers! 👋

Following your feedback on PR #441 — "I don't expect Kite to maintain a CRD by itself. If this can be done using only Helm Values, then I would be very happy to accept that feature" — I've completely reworked the approach.

No CRDs. No controller-runtime. No operator. Just Helm values and a ConfigMap.

This PR adds declarative, GitOps-ready configuration for Kite using a simple pattern: Helm renders your config into a ConfigMap, Kite watches the mounted files with fsnotify, and reconciles OAuth, RBAC, and settings to the database automatically. One helm upgrade (or one ArgoCD sync) and you're done.

What does this actually solve?

Right now, configuring Kite after install is a fully imperative process. You either use the UI or call the REST API. That means:

• Configuration state lives only in the database — not in Git
• No drift detection — someone changes a role in the UI and nobody knows
• Automating the initial setup requires brittle scripts
• No way to promote config from dev → staging → production consistently

With this feature, Kite configuration becomes just another section in your Helm values — versioned in Git, synced by ArgoCD/Flux, reviewed in PRs.

How it works

values.yaml  →  Helm  →  ConfigMap  →  Volume mount  →  fsnotify  →  Reconciler  →  Database
                                       /etc/kite/config.d/

1. You declare OAuth providers, RBAC roles, and settings in values.yaml under kiteConfig:
2. Helm renders them into a ConfigMap with separate YAML files (oauth.yaml, roles.yaml, settings.yaml)
3. The ConfigMap is mounted at /etc/kite/config.d/ as a volume
4. Kite's file watcher detects changes via fsnotify and reconciles to the database
5. Hot reload — changes apply within seconds, no pod restart needed

What was done, step by step

1. Config schema types (pkg/config/types.go, 85 lines)

Clean Go structs for the declarative config — KiteConfig covers three top-level sections:

• oauth.providers[] — full OIDC provider config (issuer URL, client ID/secret, auth/token/userinfo URLs, scopes)
• roles[] — RBAC roles with cluster/namespace/resource scopes and subject assignments (users or groups)
• generalSettings — AI config, kubectl toggle, analytics, version check, node terminal image, etc.

Used pointer types (*bool, *int) for optional fields so the reconciler can distinguish "not set" from "set to zero/false".

2. File watcher with fsnotify (pkg/config/watcher.go, 308 lines)

This is where the magic happens. The watcher:

• Discovers config from KITE_CONFIG_DIR (default: /etc/kite/config.d/)
• conf.d pattern: reads all *.yaml / *.yml files, sorted alphabetically, and merges them. OAuth providers and roles are appended across files. General settings use last-write-wins per field. This lets teams split config across multiple files.
• fsnotify hot reload: picks up changes in ~2 seconds with debouncing to coalesce rapid updates
• ConfigMap symlink support: handles Kubernetes' atomic ConfigMap updates (the ..data → ..timestamp symlink swap pattern) by watching parent directories
• Content hashing: SHA-256 comparison skips no-op reconciliations when the merged config hasn't actually changed
• Polling fallback: 5-minute resync as a safety net for edge cases where fsnotify events might be lost
• Graceful degradation: if the config directory doesn't exist, NewWatcher() returns nil and Kite runs normally without the feature

3. Database reconciler (pkg/config/reconciler.go, 383 lines)

Full CRUD reconciliation against the Kite database:

• OAuth: Creates new providers, updates existing ones, deletes orphaned ones. Only touches resources tagged with managedBy: kite-declarative-config — your manually-created providers (UI/API) are never modified.
• Roles: Creates/updates role definitions with set-based assignment reconciliation (adds missing, removes extras). System roles (admin/viewer) are protected — you can manage their assignments but can't redefine them.
• General Settings: Maps spec fields to DB columns with field-level updates. Only touches fields you actually declare (nil = don't touch).
• Orphan cleanup: When you remove a provider/role from config, it gets deleted from the database. Only managed resources are affected.
• RBAC sync: Triggers rbac.SyncNow after role changes so the in-memory permission cache updates immediately.

4. Model changes (pkg/model/oauth.go, pkg/model/rbac.go)

• Added ManagedBy field to OAuthProvider, Role, and RoleAssignment structs. This is how the reconciler tracks which resources it owns vs. which were created manually.
• Added GetOAuthProviderByNameUnfiltered() to look up providers regardless of enabled status (needed for reconciliation).
• GORM auto-migration handles the schema change — no manual SQL needed.

5. Wired into main.go (+9 lines)

Minimal integration:

if w := config.NewWatcher(db); w != nil {
    configCtx, configCancel := context.WithCancel(context.Background())
    defer configCancel()
    go w.Start(configCtx)
}

The watcher only starts when KITE_CONFIG_DIR exists and contains files. Everything degrades gracefully — if the directory doesn't exist, Kite runs exactly as before.

6. Helm chart integration

• charts/kite/templates/declarative-config.yaml — ConfigMap template that renders kiteConfig values into separate YAML files
• charts/kite/templates/deployment.yaml — Added volume mount, KITE_CONFIG_DIR env var, and a checksum/declarative-config annotation for automatic rollout on config changes
• charts/kite/values.yaml — Documented kiteConfig section with sensible defaults (disabled by default), inline examples, and security guidance for OAuth secrets

A typical Helm install:

kiteConfig:
  enabled: true
  oauth:
    providers:
      - name: "microsoft-entra-id"
        issuerUrl: "https://login.microsoftonline.com/TENANT/v2.0"
        clientId: "YOUR_CLIENT_ID"
        clientSecret: "YOUR_CLIENT_SECRET"  
        scopes: "openid profile email User.Read"
  roles:
    - name: admin
      assignments:
        - subjectType: group
          subject: "aad-group-id"
  generalSettings:
    kubectlEnabled: true
    enableAnalytics: false

7. Deploy examples

• deploy/examples/kite-values-entra-id.yaml — Ready-to-use Azure Entra ID example with OAuth, group-based role assignments, and a custom project-scoped role
• deploy/examples/declarative-config-confd.yaml — Shows how to use the conf.d pattern to split config across multiple files for team-based workflows

Why this approach (vs. the previous CRD)

	CRD (PR #441)	This PR (Helm + fsnotify)
Dependencies	controller-runtime, apiextensions, CRD YAML	fsnotify (already an indirect dep)
Binary size impact	Significant (~controller-runtime)	Negligible
RBAC requirements	CRD create/update permissions	None extra
Complexity	Informer, status patching, GC, schema	File watcher + reconciler
Helm integration	CRD + CR template	ConfigMap template (native)
Works outside K8s	No	Yes (any volume mount)
Lines of code	~1,500	~776 (pkg/config/)

What this doesn't change

• The REST API and UI management paths are completely untouched
• Existing installations without kiteConfig.enabled work exactly as before
• LoadConfigFromEnv() still works
• No new container images, sidecars, or additional deployments
• No new CRDs to install

Testing

• go build ./... — compiles clean
• go vet ./... — no issues
• go test ./pkg/... — all 8 suites pass
• go mod tidy — clean
• helm lint charts/kite — passes
• helm template with kiteConfig enabled — renders correctly (ConfigMap, volume mount, env var, checksum annotation)

Files changed

12 files changed, 1101 insertions(+), 2 deletions(-)

 charts/kite/templates/declarative-config.yaml  80 +++
 charts/kite/templates/deployment.yaml           18 ++
 charts/kite/values.yaml                         78 +++
 deploy/examples/declarative-config-confd.yaml   54 +++
 deploy/examples/kite-values-entra-id.yaml       61 +++
 go.mod                                           2 ~
 main.go                                          9 +
 pkg/config/reconciler.go                       383 +++
 pkg/config/types.go                             85 +++
 pkg/config/watcher.go                          308 +++
 pkg/model/oauth.go                              17 ~
 pkg/model/rbac.go                                8 +

Happy to iterate on anything. Looking forward to feedback!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9c02471cb

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7b4c632b38

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c24f49d6d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 39f6529a38

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7655184886

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8946b27a70

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 12efcfd9e9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c86a1fb33

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[zxh326]

I have no objections to introducing declarative GitOps. However, I don’t expect Kite to maintain a CRD by itself. This would be too complicated. If this can be done using only Helm Values, then I would be very happy to accept that feature.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79faef736a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[DioCrafts]

I have no objections to introducing declarative GitOps. However, I don’t expect Kite to maintain a CRD by itself. This would be too complicated. If this can be done using only Helm Values, then I would be very happy to accept that feature.

@zxh326 I just modify with Helm chart values approach. I hope you like.

Thank you!!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a20164cc3e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3fe55b07e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8e46a18f0

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16b4b39746

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed582c1a2e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 212ba7a57f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 729c227259

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: de65b4b52c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c9f440e4e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 95c14e6ae3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a8afaec15

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6df68bef14

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 512ad6dee7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1bdd45ba24

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: abb399b782

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".