feat(monitoring): support externally managed Keycloak

Signed-off-by: Guilherme Steinmuller <gsteinmuller@vexxhost.com>

Author: guilhermesteinmuller

doc/source/admin/monitoring.rst

@@ -206,6 +206,76 @@ Prometheus as the data source. You can find more examples of how to do
 this in the Grafana Helm chart `Import Dashboards <https://github.com/grafana/helm-charts/tree/main/charts/grafana#import-dashboards>`_
 documentation.
 
+Externally managed Keycloak
+===========================
+
+By default, Atmosphere manages the Keycloak resources needed by monitoring: the
+realm, client scope mapper, clients, client roles, and generated client
+secrets.
+
+For multi-region environments where Keycloak is shared and owned outside of the
+regional monitoring deployment, disable Keycloak management:
+
+.. code-block:: yaml
+
+  kube_prometheus_stack_keycloak_manage: false
+
+This does not disable Keycloak authentication for Grafana, Prometheus, or
+Alertmanager. It only stops the monitoring role from calling the Keycloak admin
+API. The role still waits for ``kube_prometheus_stack_keycloak_server_url`` and
+expects the referenced clients and Kubernetes secrets to exist before it deploys
+the monitoring resources.
+
+When using a shared Keycloak, override the Keycloak endpoint to point at the
+region that owns authentication. You can either set ``keycloak_host`` or override
+the full URL:
+
+.. code-block:: yaml
+
+  keycloak_host: auth.primary.example.com
+  # or:
+  kube_prometheus_stack_keycloak_server_url: https://auth.primary.example.com
+
+You must also set the local monitoring endpoints for the region being deployed:
+
+.. code-block:: yaml
+
+  kube_prometheus_stack_alertmanager_host: alertmanager.region.example.com
+  kube_prometheus_stack_grafana_host: grafana.region.example.com
+  kube_prometheus_stack_prometheus_host: prometheus.region.example.com
+
+Use region-specific client IDs when the shared Keycloak serves more than one
+monitoring deployment:
+
+.. code-block:: yaml
+
+  kube_prometheus_stack_alertmanager_client_id: alertmanager-region
+  kube_prometheus_stack_grafana_client_id: grafana-region
+  kube_prometheus_stack_prometheus_client_id: prometheus-region
+
+Each client must have a Kubernetes ``Secret`` in
+``kube_prometheus_stack_helm_release_namespace`` containing a ``password`` key.
+The namespace defaults to ``monitoring``. Override the secret names when they do
+not match the role defaults:
+
+.. code-block:: yaml
+
+  kube_prometheus_stack_alertmanager_client_secret_name: alertmanager-region-client-secret
+  kube_prometheus_stack_grafana_client_secret_name: grafana-region-client-secret
+  kube_prometheus_stack_prometheus_client_secret_name: prometheus-region-client-secret
+
+The shared Keycloak must already contain matching clients, client roles, client
+secrets, and redirect URIs. Alertmanager and Prometheus require a ``member``
+client role. Grafana requires ``admin``, ``editor``, and ``viewer`` client
+roles. The role mapper that exposes client roles in the token must also exist.
+
+The required redirect URIs are based on the endpoint variables:
+
+- ``https://{{ kube_prometheus_stack_alertmanager_host }}/oauth2/callback``
+- ``https://{{ kube_prometheus_stack_grafana_host }}/login``
+- ``https://{{ kube_prometheus_stack_grafana_host }}/login/generic_oauth``
+- ``https://{{ kube_prometheus_stack_prometheus_host }}/oauth2/callback``
+
 ************
 Viewing data
 ************

releasenotes/notes/kube-prometheus-stack-external-keycloak-7cf8c5bcb1fb0f1d.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    The ``kube_prometheus_stack`` role can now consume externally managed
+    Keycloak clients by setting ``kube_prometheus_stack_keycloak_manage`` to
+    ``false``. In this mode the role waits for the configured Keycloak API but
+    does not create or update Keycloak realms, clients, or roles, and instead
+    validates that the expected Kubernetes client secret objects already exist.

roles/kube_prometheus_stack/README.md

@@ -1 +1,6 @@
 # `kube_prometheus_stack`
+
+See the
+[monitoring documentation](../../doc/source/admin/monitoring.rst)
+for operator-facing configuration, including externally managed Keycloak
+clients.

roles/kube_prometheus_stack/defaults/main.yml

@@ -53,6 +53,7 @@ kube_prometheus_stack_prometheus_ingress_annotations:
   cert-manager.io/common-name: "{{ kube_prometheus_stack_prometheus_host }}"
 kube_prometheus_stack_prometheus_tls_template: "{{ _kube_prometheus_stack_tls_template }}"
 
+kube_prometheus_stack_keycloak_manage: true
 kube_prometheus_stack_keycloak_server_url: "https://{{ keycloak_host }}"
 kube_prometheus_stack_keycloak_admin_realm_name: master
 kube_prometheus_stack_keycloak_admin_client_id: admin-cli
@@ -61,20 +62,33 @@ kube_prometheus_stack_keycloak_admin_password: "{{ keycloak_admin_password }}"
 kube_prometheus_stack_keycloak_realm: atmosphere
 kube_prometheus_stack_keycloak_realm_name: Atmosphere
 
+kube_prometheus_stack_alertmanager_client_id: alertmanager
+kube_prometheus_stack_alertmanager_client_secret_name: >-
+  {{ kube_prometheus_stack_helm_release_name }}-{{ kube_prometheus_stack_alertmanager_client_id }}-client-secret
+kube_prometheus_stack_grafana_client_id: grafana
+kube_prometheus_stack_grafana_client_secret_name: >-
+  {{ kube_prometheus_stack_helm_release_name }}-{{ kube_prometheus_stack_grafana_client_id }}-client-secret
+kube_prometheus_stack_prometheus_client_id: prometheus
+kube_prometheus_stack_prometheus_client_secret_name: >-
+  {{ kube_prometheus_stack_helm_release_name }}-{{ kube_prometheus_stack_prometheus_client_id }}-client-secret
+
 kube_prometheus_stack_keycloak_clients:
-  - id: alertmanager
+  - id: "{{ kube_prometheus_stack_alertmanager_client_id }}"
+    client_secret_name: "{{ kube_prometheus_stack_alertmanager_client_secret_name }}"
     port: 9093
     roles: ["member"]
     oauth2_proxy: true
     redirect_uris:
       - "https://{{ kube_prometheus_stack_alertmanager_host }}/oauth2/callback"
-  - id: grafana
+  - id: "{{ kube_prometheus_stack_grafana_client_id }}"
+    client_secret_name: "{{ kube_prometheus_stack_grafana_client_secret_name }}"
     roles: ["admin", "editor", "viewer"]
     oauth2_proxy: false
     redirect_uris:
       - "https://{{ kube_prometheus_stack_grafana_host }}/login"
       - "https://{{ kube_prometheus_stack_grafana_host }}/login/generic_oauth"
-  - id: prometheus
+  - id: "{{ kube_prometheus_stack_prometheus_client_id }}"
+    client_secret_name: "{{ kube_prometheus_stack_prometheus_client_secret_name }}"
     port: 9090
     roles: ["member"]
     oauth2_proxy: true

roles/kube_prometheus_stack/tasks/main.yml

@@ -39,6 +39,7 @@
     realm: "{{ kube_prometheus_stack_keycloak_realm }}"
     display_name: "{{ kube_prometheus_stack_keycloak_realm_name }}"
     enabled: true
+  when: kube_prometheus_stack_keycloak_manage | bool
 
 - name: Add client roles in "id_token"
   no_log: true
@@ -64,6 +65,7 @@
           access.token.claim: true
           id.token.claim: true
           multivalued: true
+  when: kube_prometheus_stack_keycloak_manage | bool
 
 - name: Retrieve "etcd" CA certificate
   run_once: true
@@ -111,7 +113,9 @@
       apiVersion: secretgen.k14s.io/v1alpha1
       kind: Password
       metadata:
-        name: "{{ kube_prometheus_stack_helm_release_name }}-{{ item.id }}-client-secret"
+        name: >-
+          {{ item.client_secret_name
+          | default(kube_prometheus_stack_helm_release_name ~ '-' ~ item.id ~ '-client-secret') }}
         namespace: "{{ kube_prometheus_stack_helm_release_namespace }}"
       spec:
         length: 64
@@ -124,6 +128,7 @@
   loop: "{{ kube_prometheus_stack_keycloak_clients }}"
   loop_control:
     label: "{{ item.id }}"
+  when: kube_prometheus_stack_keycloak_manage | bool
 
 - name: Collect all client secrets
   run_once: true
@@ -136,6 +141,28 @@
   loop_control:
     label: "{{ password.item.id }}"
     loop_var: password
+  when: kube_prometheus_stack_keycloak_manage | bool
+
+- name: Validate externally managed client secrets
+  run_once: true
+  kubernetes.core.k8s_info:
+    kind: Secret
+    namespace: "{{ kube_prometheus_stack_helm_release_namespace }}"
+    name: >-
+      {{ item.client_secret_name
+      | default(kube_prometheus_stack_helm_release_name ~ '-' ~ item.id ~ '-client-secret') }}
+  register: kube_prometheus_stack_external_client_secret
+  failed_when: >-
+    kube_prometheus_stack_external_client_secret.resources | length == 0 or
+    kube_prometheus_stack_external_client_secret.resources[0].data.password
+    is not defined
+  loop: "{{ kube_prometheus_stack_keycloak_clients }}"
+  loop_control:
+    label: >-
+      {{ item.id }}
+      ({{ item.client_secret_name
+      | default(kube_prometheus_stack_helm_release_name ~ '-' ~ item.id ~ '-client-secret') }})
+  when: not (kube_prometheus_stack_keycloak_manage | bool)
 
 - name: Create Keycloak clients
   no_log: true
@@ -165,6 +192,7 @@
   loop_control:
     label: "{{ secret.password.item.id }}"
     loop_var: secret
+  when: kube_prometheus_stack_keycloak_manage | bool
 
 - name: Create Keycloak roles
   no_log: true
@@ -184,6 +212,7 @@
   loop: "{{ kube_prometheus_stack_keycloak_clients | subelements('roles') }}"
   loop_control:
     label: "{{ item.0.id }}-{{ item.1 }}"
+  when: kube_prometheus_stack_keycloak_manage | bool
 
 - name: Generate cookie secrets
   run_once: true
@@ -222,7 +251,9 @@
             ref:
               apiVersion: v1
               kind: Secret
-              name: "{{ kube_prometheus_stack_helm_release_name }}-{{ item.id }}-client-secret"
+              name: >-
+                {{ item.client_secret_name
+                | default(kube_prometheus_stack_helm_release_name ~ '-' ~ item.id ~ '-client-secret') }}
           - name: cookie-secret
             ref:
               apiVersion: v1

roles/kube_prometheus_stack/tasks_test.go

@@ -42,25 +42,38 @@ func TestCreateKeycloakRealmTask(t *testing.T) {
 	require.NotNil(t, task)
 
 	assert.Equal(t, true, task["no_log"])
+	assert.Equal(t, "kube_prometheus_stack_keycloak_manage | bool",
+		task["when"])
 }
 
 func TestAddClientRolesInIdTokenTask(t *testing.T) {
 	task := getTaskByName("Add client roles in \"id_token\"")
 	require.NotNil(t, task)
 
 	assert.Equal(t, true, task["no_log"])
+	assert.Equal(t, "kube_prometheus_stack_keycloak_manage | bool",
+		task["when"])
 }
 
 func TestCreateKeycloakClientsTask(t *testing.T) {
 	task := getTaskByName("Create Keycloak clients")
 	require.NotNil(t, task)
 
 	assert.Equal(t, true, task["no_log"])
+	assert.Equal(t, "kube_prometheus_stack_keycloak_manage | bool",
+		task["when"])
 }
 
 func TestCreateKeycloakRolesTask(t *testing.T) {
 	task := getTaskByName("Create Keycloak roles")
 	require.NotNil(t, task)
 
 	assert.Equal(t, true, task["no_log"])
+	assert.Equal(t, "kube_prometheus_stack_keycloak_manage | bool",
+		task["when"])
+}
+
+func TestValidateExternallyManagedClientSecretsTask(t *testing.T) {
+	task := getTaskByName("Validate externally managed client secrets")
+	require.NotNil(t, task)
 }

roles/kube_prometheus_stack/vars/main.yml

@@ -220,7 +220,7 @@ _kube_prometheus_stack_helm_values:
     adminPassword: "{{ kube_prometheus_stack_grafana_admin_password }}"
     extraSecretMounts:
       - name: auth-generic-oauth-secret-mount
-        secretName: "{{ kube_prometheus_stack_helm_release_name }}-grafana-client-secret"
+        secretName: "{{ kube_prometheus_stack_grafana_client_secret_name }}"
         defaultMode: "0440"
         mountPath: /etc/secrets/auth_generic_oauth
         readOnly: true
@@ -236,7 +236,7 @@ _kube_prometheus_stack_helm_values:
         enabled: true
         name: Atmosphere
         allow_sign_up: true
-        client_id: grafana
+        client_id: "{{ kube_prometheus_stack_grafana_client_id }}"
         client_secret: "$__file{/etc/secrets/auth_generic_oauth/password}"
         scopes: openid email profile offline_access roles
         email_attribute_path: email
@@ -247,7 +247,7 @@ _kube_prometheus_stack_helm_values:
         api_url: "{{ kube_prometheus_stack_keycloak_server_url }}/realms/{{ kube_prometheus_stack_keycloak_realm }}/protocol/openid-connect/userinfo"
         tls_skip_verify_insecure: true
         # yamllint disable-line rule:line-length
-        role_attribute_path: "contains(resource_access.grafana.roles[*], 'admin') && 'Admin' || contains(resource_access.grafana.roles[*], 'editor') && 'Editor' || contains(resource_access.grafana.roles[*], 'viewer') && 'Viewer'"
+        role_attribute_path: "contains(resource_access.\"{{ kube_prometheus_stack_grafana_client_id }}\".roles[*], 'admin') && 'Admin' || contains(resource_access.\"{{ kube_prometheus_stack_grafana_client_id }}\".roles[*], 'editor') && 'Editor' || contains(resource_access.\"{{ kube_prometheus_stack_grafana_client_id }}\".roles[*], 'viewer') && 'Viewer'"
         role_attribute_strict: true
         skip_org_role_sync: false
     image: