refactor(keycloak): embedded defaults + in-cluster Secret per #154 rewrite

Aligns Phase 1a with the agreed design in PR #154's rewrite (commit
669458a on design/declarative-keycloak-config). Previous structure put
the kcc realm input in a ConfigMap rendered into the gitops repo. The
rewrite's "Why no ConfigMap in the gitops repo" section explicitly
rejects that pattern:

- The gitops repo is treated as untrusted. Placeholder-only contracts
  ("file in repo only contains $(env:...), never literals") create a
  footgun where one operator mistake leaks a secret into git history.
- Realm content beyond raw secrets is still sensitive (IdP names,
  redirect URI patterns, credential hashes from kc.sh export).

New structure:

- pkg/argocd/keycloak_defaults.yaml (new) — kcc realm input in native
  format, embedded into the NIC binary via //go:embed. Same content
  as the previous gitops ConfigMap data field, no ConfigMap wrapping.
- pkg/argocd/keycloak_defaults.go (new) — RenderKeycloakDefaults()
  helper renders the template with TemplateData (Domain substitutes
  into the argocd redirect URI).
- pkg/argocd/foundational.go — InstallFoundationalServices now renders
  the embedded defaults with cfg.Domain and writes the result to a
  new in-cluster Secret keycloak-config-import (keycloak namespace).
  createKeycloakImportSecret added as a sibling of the existing
  Secret creators; uses createSecret's no-op-if-exists semantics so
  re-deploys preserve any value already present in the cluster.
- templates/manifests/keycloak/realm-setup-job.yaml — volume changed
  from a ConfigMap reference (keycloak-realm-config, deleted) to a
  Secret reference (keycloak-config-import). Everything else stays:
  same kcc image, same env-var sourcing, same hook annotations.
- templates/manifests/keycloak/realm-config-cm.yaml (deleted) — the
  gitops repo no longer carries realm content. Only the Job manifest
  remains there.

Phase 1a scope is unchanged. Phase 1b will introduce a user-supplied
keycloak.yaml file path that overrides these embedded defaults; the
Secret-vs-ConfigMap structural decision now makes that path direct.

Test:

- keycloak_defaults_test.go (new) asserts the load-bearing fields of
  the rendered kcc input — realm settings, scope lists, groups,
  argocd client, the oidc-group-membership-mapper, the full
  defaultDefaultClientScopes list, and that no unresolved Go-template
  markers leak into the output.
- writer_test.go TestKeycloakRealmConfigCM removed (it tested the
  deleted ConfigMap template).

Author: viniciusdc

pkg/argocd/foundational.go

@@ -140,6 +140,23 @@ func InstallFoundationalServices(ctx context.Context, cfg *config.NebariConfig,
 			return fmt.Errorf("failed to create Keycloak secrets: %w", err)
 		}
 
+		// Render the embedded keycloak-config-cli defaults and write them
+		// to the in-cluster Secret the realm-setup Job will mount. The
+		// gitops repo never holds realm content under this design.
+		domain := cfg.Domain
+		if domain == "" {
+			domain = "nebari.local"
+		}
+		importContent, err := RenderKeycloakDefaults(TemplateData{Domain: domain})
+		if err != nil {
+			span.RecordError(err)
+			return fmt.Errorf("failed to render keycloak-config-cli defaults: %w", err)
+		}
+		if err := createKeycloakImportSecret(ctx, k8sClient, importContent); err != nil {
+			span.RecordError(err)
+			return fmt.Errorf("failed to create %s secret: %w", KeycloakImportSecretName, err)
+		}
+
 		// Create namespace for Nebari system services
 		if err := createNamespace(ctx, k8sClient, NebariSystemNamespace); err != nil {
 			span.RecordError(err)
@@ -324,6 +341,33 @@ func createKeycloakSecrets(ctx context.Context, client kubernetes.Interface, key
 	return nil
 }
 
+// createKeycloakImportSecret writes the keycloak-config-cli input to an
+// in-cluster Secret named `keycloak-config-import` in the `keycloak`
+// namespace. The realm-setup Job mounts this Secret read-only and applies
+// the file against Keycloak.
+//
+// The Secret carrier (rather than a gitops-repo ConfigMap) keeps realm
+// structure and any inline credentials out of git: only the Job manifest
+// lives in the gitops repo. Phase 1a writes only the embedded defaults;
+// Phase 1b will overwrite or replace this content with the user's
+// keycloak.yaml.
+func createKeycloakImportSecret(ctx context.Context, client kubernetes.Interface, importContent []byte) error {
+	return createSecret(ctx, client, &corev1.Secret{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      KeycloakImportSecretName,
+			Namespace: KeycloakDefaultNamespace,
+			Labels: map[string]string{
+				"app.kubernetes.io/part-of":    NebariFoundationalPartOf,
+				"app.kubernetes.io/managed-by": "nebari-infrastructure-core",
+			},
+		},
+		Type: corev1.SecretTypeOpaque,
+		Data: map[string][]byte{
+			KeycloakImportSecretKey: importContent,
+		},
+	})
+}
+
 // createLandingPageSecrets creates the required secrets for the nebari-landing service
 func createLandingPageSecrets(ctx context.Context, client kubernetes.Interface, landingCfg LandingPageConfig) error {
 	namespace := NebariSystemNamespace

pkg/argocd/keycloak_defaults.go

@@ -0,0 +1,43 @@
+package argocd
+
+import (
+	"bytes"
+	_ "embed"
+	"fmt"
+	"text/template"
+)
+
+// keycloakDefaultsRaw is the default keycloak-config-cli input for the nebari
+// realm. It is embedded as a Go template and rendered with TemplateData at
+// deploy time before being written to the in-cluster Secret.
+//
+//go:embed keycloak_defaults.yaml
+var keycloakDefaultsRaw []byte
+
+const (
+	// KeycloakImportSecretName is the in-cluster Secret carrying the kcc
+	// input that the realm-setup Job applies. The content lives only inside
+	// the cluster's Secret store; the gitops repo never holds realm
+	// structure or inline credentials.
+	KeycloakImportSecretName = "keycloak-config-import" //nolint:gosec // secret name reference
+
+	// KeycloakImportSecretKey is the key inside KeycloakImportSecretName
+	// under which the rendered kcc input lives.
+	KeycloakImportSecretKey = "realm.yaml"
+)
+
+// RenderKeycloakDefaults renders the embedded default kcc input with the
+// supplied TemplateData. Only the Domain field is substituted today (used
+// to build the argocd client's redirect URI); future fields can be wired
+// in as the schema grows.
+func RenderKeycloakDefaults(data TemplateData) ([]byte, error) {
+	tmpl, err := template.New("keycloak_defaults.yaml").Parse(string(keycloakDefaultsRaw))
+	if err != nil {
+		return nil, fmt.Errorf("parse keycloak defaults template: %w", err)
+	}
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return nil, fmt.Errorf("render keycloak defaults: %w", err)
+	}
+	return buf.Bytes(), nil
+}

pkg/argocd/keycloak_defaults.yaml

@@ -0,0 +1,111 @@
+# Default keycloak-config-cli input for the nebari realm.
+#
+# Phase 1a of the declarative Keycloak configuration approach (see
+# docs/superpowers/specs/2026-03-12-declarative-keycloak-config-design.md).
+# This file is embedded into the NIC binary via go:embed (see
+# keycloak_defaults.go), rendered with TemplateData at deploy time, and
+# written verbatim to the in-cluster Secret `keycloak-config-import`. The
+# kcc Job mounts that Secret read-only and applies the file against
+# Keycloak.
+#
+# The gitops repo never sees this content. Realm structure and any
+# inline credentials (none currently — we use $(env:VAR) placeholders)
+# stay inside the cluster's Secret store.
+#
+# `$(env:VAR)` placeholders are substituted by kcc at apply time from env
+# vars set on the Job (see templates/manifests/keycloak/realm-setup-job.yaml).
+# `{{ .Domain }}` is rendered by Go's text/template at NIC deploy time.
+realm: nebari
+enabled: true
+displayName: Nebari
+sslRequired: external
+registrationAllowed: false
+loginWithEmailAllowed: true
+resetPasswordAllowed: true
+bruteForceProtected: true
+
+# kcc applies list fields as a full replace, not a merge. We must
+# include the built-in default scopes (Keycloak auto-creates these on
+# realm creation) here so they survive the import — otherwise tokens
+# would be missing email/profile/roles/etc. claims.
+defaultDefaultClientScopes:
+  - basic
+  - profile
+  - email
+  - roles
+  - web-origins
+  - acr
+  - groups
+
+roles:
+  realm:
+    - name: admin
+      description: Administrator role
+    - name: user
+      description: Regular user role
+
+groups:
+  - name: argocd-admins
+  - name: argocd-viewers
+
+users:
+  - username: admin
+    enabled: true
+    emailVerified: true
+    firstName: Admin
+    lastName: User
+    email: admin@nebari.local
+    realmRoles:
+      - admin
+      - user
+    credentials:
+      - type: password
+        value: $(env:REALM_ADMIN_PASSWORD)
+    groups:
+      - /argocd-admins
+
+clientScopes:
+  - name: groups
+    protocol: openid-connect
+    attributes:
+      include.in.token.scope: "true"
+      display.on.consent.screen: "true"
+    protocolMappers:
+      - name: group-membership
+        protocol: openid-connect
+        protocolMapper: oidc-group-membership-mapper
+        config:
+          full.path: "false"
+          introspection.token.claim: "true"
+          userinfo.token.claim: "true"
+          multivalued: "true"
+          id.token.claim: "true"
+          access.token.claim: "true"
+          claim.name: groups
+
+clients:
+  - clientId: argocd
+    enabled: true
+    protocol: openid-connect
+    publicClient: false
+    secret: $(env:ARGOCD_CLIENT_SECRET)
+    redirectUris:
+      - https://argocd.{{ .Domain }}/auth/callback
+    webOrigins:
+      - https://argocd.{{ .Domain }}
+    directAccessGrantsEnabled: false
+    standardFlowEnabled: true
+    # The realm's defaultDefaultClientScopes auto-apply only at client
+    # CREATION time, not on subsequent updates. So we must explicitly
+    # list the full set of default scopes here — otherwise kcc's
+    # replace semantics on this field would leave older clients with
+    # whatever they had at creation. Same content as the realm
+    # default-defaults above so kcc converges to the expected state.
+    defaultClientScopes:
+      - basic
+      - profile
+      - email
+      - roles
+      - web-origins
+      - acr
+      - groups

pkg/argocd/keycloak_defaults_test.go

@@ -0,0 +1,65 @@
+package argocd
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestRenderKeycloakDefaults asserts the load-bearing fields of the
+// rendered kcc input that NIC writes to the keycloak-config-import
+// Secret. The rendered content is what makes the realm-setup Job
+// produce a valid Keycloak state; regressions here are silent (the YAML
+// renders fine but Keycloak gets misconfigured), so we check structure.
+func TestRenderKeycloakDefaults(t *testing.T) {
+	rendered, err := RenderKeycloakDefaults(TemplateData{Domain: "test.example.com"})
+	if err != nil {
+		t.Fatalf("RenderKeycloakDefaults error: %v", err)
+	}
+	output := string(rendered)
+
+	// kcc realm payload — load-bearing fields the realm-setup-job depends on
+	for _, want := range []string{
+		"realm: nebari",
+		"defaultDefaultClientScopes:",
+		// kcc applies list fields as full-replace, so the built-in default
+		// scopes must be present here or tokens lose email/profile/roles.
+		"- basic",
+		"- profile",
+		"- email",
+		"- roles",
+		"- web-origins",
+		"- acr",
+		"- groups",
+		"- name: argocd-admins",
+		"- name: argocd-viewers",
+		"username: admin",
+		"$(env:REALM_ADMIN_PASSWORD)",
+		"- /argocd-admins",
+		"protocolMapper: oidc-group-membership-mapper",
+		"claim.name: groups",
+		"clientId: argocd",
+		"$(env:ARGOCD_CLIENT_SECRET)",
+		"https://argocd.test.example.com/auth/callback",
+	} {
+		if !strings.Contains(output, want) {
+			t.Errorf("expected %q in rendered realm config, got:\n%s", want, output)
+		}
+	}
+
+	// The argocd client must explicitly list the full set of default
+	// scopes. Keycloak's realm default-defaults auto-apply only at client
+	// creation, not on subsequent updates — so we need this redundancy to
+	// keep kcc's replace semantics from stripping scopes on existing
+	// clients during a re-run.
+	if !strings.Contains(output, "    defaultClientScopes:\n      - basic") {
+		t.Errorf("argocd client must explicitly list defaultClientScopes starting with built-ins, got:\n%s", output)
+	}
+
+	// The rendered content must not contain any unresolved Go-template
+	// markers. If a future edit introduces a new {{ . }} reference and
+	// forgets to add the field, this catches it instead of letting it
+	// land in Keycloak as a literal.
+	if strings.Contains(output, "{{") || strings.Contains(output, "}}") {
+		t.Errorf("rendered output contains unresolved template markers, got:\n%s", output)
+	}
+}