StackVista · aacevedoosorio · Jan 7, 2025 · Nov 29, 2024 · Nov 30, 2024 · Nov 30, 2024
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -123,12 +123,12 @@
   * [E-mail notifications](setup/configure-stackstate/email-notifications.md)
   * [Stackpacks](stackpacks/about-stackpacks.md)
 * [Release Notes](setup/release-notes/README.md)
-  * [v2.0.0 - 11/09/2024](setup/release-notes/v2.0.0.md)
-  * [v2.0.1 - 18/09/2024](setup/release-notes/v2.0.1.md)
-  * [v2.0.2 - 01/10/2024](setup/release-notes/v2.0.2.md)
-  * [v2.1.0 - 29/10/2024](setup/release-notes/v2.1.0.md)
-  * [v2.2.0 - 09/12/2024](setup/release-notes/v2.2.0.md)
-  * [v2.2.1 - 10/12/2024](setup/release-notes/v2.2.1.md)
+  * [v2.0.0 - 11/Sep/2024](setup/release-notes/v2.0.0.md)
+  * [v2.0.1 - 18/Sep/2024](setup/release-notes/v2.0.1.md)
+  * [v2.0.2 - 01/Oct/2024](setup/release-notes/v2.0.2.md)
+  * [v2.1.0 - 29/Oct/2024](setup/release-notes/v2.1.0.md)
+  * [v2.2.0 - 09/Dec/2024](setup/release-notes/v2.2.0.md)
+  * [v2.2.1 - 10/Dec/2024](setup/release-notes/v2.2.1.md)
 * [Upgrade SUSE Observability](setup/upgrade-stackstate/README.md)
   * [Migration from StackState](setup/upgrade-stackstate/migrate-from-6.md)
   * [Steps to upgrade](setup/upgrade-stackstate/steps-to-upgrade.md)
@@ -150,8 +150,10 @@
     * [File-based](setup/security/authentication/file.md)
     * [LDAP](setup/security/authentication/ldap.md)
     * [Open ID Connect \(OIDC\)](setup/security/authentication/oidc.md)
+      * [Microsoft Entra ID](setup/security/authentication/oidc/microsoft-entra-id.md)
     * [KeyCloak](setup/security/authentication/keycloak.md)
     * [Service tokens](setup/security/authentication/service_tokens.md)
+    * [Troubleshooting](setup/security/authentication/troubleshooting.md)
   * [RBAC](setup/security/rbac/README.md)
     * [Role-based Access Control](setup/security/rbac/role_based_access_control.md)
     * [Permissions](setup/security/rbac/rbac_permissions.md)

diff --git a/k8s-suse-rancher-prime-air-gapped.md b/k8s-suse-rancher-prime-air-gapped.md
@@ -120,52 +120,6 @@ Create a private-registry.yaml file with the following content:
 ```yaml
 global:
   imageRegistry: registry.example.com:5043
-minio:
-  image:
-    registry: registry.example.com:5043
-elasticsearch:
-  prometheus-elasticsearch-exporter:
-    image:
-      repository: registry.example.com:5043/suse-observability/elasticsearch-exporter
-victoriametrics-cluster:
-  vmstorage:
-    image:
-      repository: registry.example.com:5043/suse-observability/vmstorage
-  vminsert:
-    image:
-      repository: registry.example.com:5043/suse-observability/vminsert
-  vmselect:
-    image:
-      repository: registry.example.com:5043/suse-observability/vmselect
-victoria-metrics-0:
-  server:
-    image:
-      repository: registry.example.com:5043/suse-observability/victoria-metrics
-  backup:
-    setupCron:
-      image:
-        repository: registry.example.com:5043/suse-observability/container-tools
-    vmbackup:
-      image:
-        repository: registry.example.com:5043/suse-observability/vmbackup
-victoria-metrics-1:
-  server:
-    image:
-      repository: registry.example.com:5043/suse-observability/victoria-metrics
-  backup:
-    setupCron:
-      image:
-        repository: registry.example.com:5043/suse-observability/container-tools
-    vmbackup:
-      image:
-        repository: registry.example.com:5043/suse-observability/vmbackup
-clickhouse:
-  backup:
-    image:
-      registry: registry.example.com:5043
-opentelemetry-collector:
-  image:
-    repository: registry.example.com:5043/suse-observability/sts-opentelemetry-collector
 ```
 
 This guide follows the [Installation](https://docs.stackstate.com/get-started/k8s-suse-rancher-prime#installation) setup, but instead of using publicly available Helm and Docker repositories/registries, it uses pre-downloaded Helm archives and private Docker registries.

diff --git a/setup/data-management/backup_restore/kubernetes_backup.md b/setup/data-management/backup_restore/kubernetes_backup.md
@@ -198,7 +198,7 @@ The backup schedule can be configured using the Helm value `backup.stackGraph.sc
 
 By default, the StackGraph backups are kept for 30 days. As StackGraph backups are full backups, this can require a lot of storage.
 
-The backup retention delta can be configured using the Helm value `backup.stackGraph.scheduled.backupRetentionTimeDelta`, specified in [Python timedelta format \(python.org\)](https://docs.python.org/3/library/datetime.html#timedelta-objects).
+The backup retention delta can be configured using the Helm value `backup.stackGraph.scheduled.backupRetentionTimeDelta`, specified in the format of GNU date `--date` argument. For example, the default is `30 days ago`. See [Relative items in date strings](https://www.gnu.org/software/coreutils/manual/html_node/Relative-items-in-date-strings.html) for more examples.
 
 ## Metrics \(Victoria Metrics\)
 

diff --git a/setup/install-stackstate/kubernetes_openshift/ingress.md b/setup/install-stackstate/kubernetes_openshift/ingress.md
@@ -16,6 +16,10 @@ The SUSE Observability Helm chart exposes an `ingress` section in its values. Th
 
 To configure the ingress for SUSE Observability, create a file `ingress_values.yaml` with contents like below. Replace `MY_DOMAIN` with your own domain \(that's linked with your ingress controller\) and set the correct name for the `tls-secret`. Consult the documentation of your ingress controller for the correct annotations to set. All fields below are optional, for example, if no TLS will be used, omit that section but be aware that SUSE Observability also doesn't encrypt the traffic.
 
+{% hint style="warning" %}
+Note that setting up TLS is required for the use of the rancher UI extension.
+{% endhint %}
+
 ```text
 ingress:
   enabled: true
@@ -34,8 +38,7 @@ The thing that stands out in this file is the Nginx annotation to increase the a
 Include the `ingress_values.yaml` file when you run the `helm upgrade` command to deploy SUSE Observability:
 
 ```text
-helm upgrade \
-  --install \
+helm upgrade --install \
   --namespace "suse-observability" \
   --values "ingress_values.yaml" \
   --values $VALUES_DIR/suse-observability-values/templates/baseConfig_values.yaml \

diff --git a/setup/install-stackstate/kubernetes_openshift/storage.md b/setup/install-stackstate/kubernetes_openshift/storage.md
@@ -15,7 +15,7 @@ To remove the PVC's either remove them manually with `kubectl delete pvc` or del
 ## Customize storage
 
 You can customize the `storageClass` and `size` settings for different volumes in the Helm chart. These example values files show how to change the storage class or the volume size. These can be merged to change both at the same time.
-For the `size` we provide the sameple for both `HA` and `NonHa` depending on the sizing profile chosen during the installation process.
+For the `size` we provide the sample for both `HA` and `NonHa` depending on the sizing profile chosen during the installation process.
 
 {% tabs %}
 {% tab title="Changing storage class" %}
@@ -150,4 +150,4 @@ stackstate:
 
 {% hint style="info" %}
 The NonHa example belongs to the biggest NonHa instance meant to observe 100 nodes and retain data for 2 weeks.
-{% endhint %}
+{% endhint %}
diff --git a/setup/install-stackstate/troubleshooting.md b/setup/install-stackstate/troubleshooting.md
@@ -11,7 +11,7 @@ Here is a quick guide for troubleshooting the startup of SUSE Observability:
 1. Check that the install completed successfully and the release is listed:
 
    ```text
-   helm list --namespace stackstate
+   helm list --namespace suse-observability
    ```
 
 2. Check that all pods in the SUSE Observability namespace are running:

diff --git a/setup/release-notes/v2.0.0.md b/setup/release-notes/v2.0.0.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.0.0 - 11/09/2024
+# v2.0.0 - 11/Sep/2024
 
 ## Release Notes StackState version 7.0.0-snapshot.20240911112250-master-f9361e0 Helm Chart version 2.0.0
 

diff --git a/setup/release-notes/v2.0.1.md b/setup/release-notes/v2.0.1.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.0.1 - 18/09/2024
+# v2.0.1 - 18/Sep/2024
 
 ## Release Notes StackState version 7.0.0-snapshot.20240918082712-master-8d36ec2 Helm Chart version 2.0.1
 

diff --git a/setup/release-notes/v2.0.2.md b/setup/release-notes/v2.0.2.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.0.2 - 01/10/2024
+# v2.0.2 - 1/Oct/2024
 
 ## Release Notes StackState version 7.0.0-snapshot.20241001154902-master-e89f93c Helm Chart version 2.0.2
 

diff --git a/setup/release-notes/v2.1.0.md b/setup/release-notes/v2.1.0.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.1.0 - 29/10/2024
+# v2.1.0 - 29/Oct/2024
 
 ## Release Notes StackState version 7.0.0-snapshot.20241023133226-master-a9f30a7 Helm Chart version 2.1.0
 

diff --git a/setup/release-notes/v2.2.0.md b/setup/release-notes/v2.2.0.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.2.0 -09/12/2024
+# v2.2.0 - 09/Dec/2024
 
 {% hint style="warning" %}
 This release has a bug where the Helm chart is using invalid image URLs for some pods, instead use [version 2.2.1](./v2.2.1.md) or newer.

diff --git a/setup/release-notes/v2.2.1.md b/setup/release-notes/v2.2.1.md
@@ -2,7 +2,7 @@
 description: SUSE Observability Self-hosted
 ---
 
-# v2.2.1 -10/12/2024
+# v2.2.1 - 10/Dec/2024
 
 ## Release Notes StackState version 7.0.0-snapshot.20241204151219-master-db9515b Helm Chart version 2.2.1
 

diff --git a/setup/security/authentication/oidc.md b/setup/security/authentication/oidc.md
@@ -12,9 +12,9 @@ SUSE Observability can authenticate using an OIDC authentication provider. To en
 
 Before you can configure SUSE Observability to authenticate using OIDC, you need to create a client for SUSE Observability on your OIDC provider. Use the following settings for the client \(if needed by the OIDC provider\):
 
-* Use the OIDCAuthoirzation Flow
-* Set the **Redirect URI** to the base URL of SUSE Observability suffixed with `/loginCallback`. For example `https://stackstate.acme.com/loginCallback`. For some OIDC providers, such as Google, the Redirect URI must match exactly, including any query parameters. In that case, you should configure the URI like this `https://stackstate.acme.com/loginCallback?client_name=StsOidcClient`.
-* Give SUSE Observability access to at least the scopes `openid` and `email` or the equivalent of these for your OIDC provider.
+* Use the OIDC Authorization Flow, it is also often called the Authorization code flow. SUSE Observability does not support the Implicit grant and hybrid flows, so there is no need to enable support for them.
+* Set the **Redirect URI** to the base URL of SUSE Observability suffixed with `/loginCallback`. For example `https://stackstate.acme.com/loginCallback`. For some OIDC providers, such as Google and Azure Entra ID, the Redirect URI must match exactly, including any query parameters. In that case, you should configure the URI like this `https://stackstate.acme.com/loginCallback?client_name=StsOidcClient`.
+* Give SUSE Observability access to at least the scopes `openid` and `email` or the equivalent of these for your OIDC provider. Depending on the provider more scopes may be required, if a separate `profile` exists include it as well.
 * SUSE Observability needs OIDC offline access. For some identity providers, this requires an extra scope, usually called `offline_access`.
 
 The result of this configuration should produce a **clientId** and a **secret**. Copy those and keep them around for configuring SUSE Observability. Also write down the **discoveryUri** of the provider. Usually this is either in the same screen or can be found in the documentation.
@@ -43,10 +43,10 @@ stackstate:
     # map the groups from OIDC provider
     # to the 4 standard roles in SUSE Observability (guest, powerUser, k8sTroubleshooter and admin)
     roles:
-      guest: ["oidc-guest-role-for-stackstate"]
-      powerUser: ["oidc-power-user-role-for-stackstate"]
-      admin: ["oidc-admin-role-for-stackstate"]
-      k8sTroubleshooter: ["oidc-troubleshooter-role-for-stackstate"]
+      guest: ["guest-group-in-oidc-provider"]
+      powerUser: ["powerUser-group-in-oidc-provider"]
+      admin: ["admin-group-in-oidc-provider"]
+      k8sTroubleshooter: ["troubleshooter-group-in-oidc-provider"]
 ```
 
 Follow the steps below to configure SUSE Observability to authenticate using OIDC:
@@ -84,29 +84,11 @@ Follow the steps below to configure SUSE Observability to authenticate using OID
 * The authentication configuration is stored as a Kubernetes secret.
 {% endhint %}
 
-## Additional settings for specific OIDC providers
+## Setup guides
 
-This section includes additional settings needed for specific OIDC providers.
+* [Microsoft Entra ID](./oidc/microsoft-entra-id.md)
 
-### Microsoft Identity Platform
-
-To authenticate SUSE Observability via OIDC with the Microsoft Identity Platform, the additional scope `offline_access` needs to be granted and requested during authentication.
-
-In Microsoft Azure, approve the permission _"Maintain access to data you have given it access to"_ on the consent page of the authorization code flow.
-
-In the SUSE Observability configuration described above, add the scope `offline_access`, in addition to `openid` and `email`. For example:
-
-```yaml
-jwsAlgorithm: RS256
-      scope: ["openid", "email", "offline_access"]
-      jwtClaims:
-        usernameField: preferred_username
-        groupsField: groups
-```
-
-For further details, see [Permissions and consent in the Microsoft identity platform \(learn.microsoft.com\)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent).
-
-### Using an external secret
+## Using an external secret
 
 When the oidc secrets should come from an external secret, follow [these steps](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) but fill in the following data:
 
@@ -122,6 +104,7 @@ data:
 
 ## See also
 
+* [Troubleshooting authentication and authorization](troubleshooting.md)
 * [Authentication options](authentication_options.md)
 * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles)
 * [Create RBAC roles](../rbac/rbac_roles.md)

diff --git a/setup/security/authentication/oidc/microsoft-entra-id.md b/setup/security/authentication/oidc/microsoft-entra-id.md
@@ -0,0 +1,56 @@
+---
+description: SUSE Observability Self-hosted
+---
+
+# Microsoft Entra ID
+
+## Creating an application in Entra ID
+
+1. Register an application in Entra ID by following [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=client-secret)
+   1. As a display name you can use, for example, `SUSE Observability`
+   2. Select the `Web` platform and specify the redirect URL: `https://<your-stackstate-installation>/loginCallback?client_name=StsOidcClient`
+   3. When adding credentials use the `client secret` credentials and make sure to store the secret
+2. The other sections in the `Prepare for development` section are not required but for a production installation you should follow them to set an owner and possible pre-approve certain scopes (see the next section for the scopes SUSE Observability will request)
+3. Finally make sure SUSE Observability will receive the groups for a user (needed for authorization) by adding the groups claim to the app registration using [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui#configure-groups-optional-claims). Select which types of groups you want to expose, the rest of this document assumes you didn't customize the token properties and SUSE Observability receives the Group Id.
+
+## Configuring SUSE Observability
+
+Using the app registration information create a new `authentication.yaml` file for SUSE Observability:
+```
+stackstate:
+  authentication:
+    oidc:
+      # The client id is in the list of essentials on the overview page of the App registration
+      clientId: "<Application (client) ID>"
+      secret: "<Application (client) secret>"
+      # The Directory (Tenant) ID is in the list of essentials on the overview page of the App registration
+      discoveryUri: "https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
+      jwsAlgorithm: RS256
+      scope: ["openid", "email", "profile", "offline_access"]
+      jwtClaims:
+        usernameField: "email"
+        groupsField: groups
+    roles:
+      guest: []
+      powerUser: []
+      admin: [ "aaaaaaaa-bbbb-1111-2222-aabbccddeeff", "eeeeeeeeee-bbbb-1111-2222-aabbccddeeff" ]
+      k8sTroubleshooter: []
+```
+
+Get the values for:
+* Application (client) ID: in the Essentials section on the Overview page of the app registration
+* Application (client) secret: created in step 1 of the previous section and saved somewhere
+* Directory (tenant) ID: in the Essentials section on the Overview page of the app registration
+* The group ids for the different roles: in Entra ID admin browse to **Identity > All Groups**. The group id's are in the second column labeled `Object Id`. Decide which Entra ID groups should have which level of permissions and assign them to their respective roles in the above yaml example (removing the 2 example group ids).
+
+Now redeploy SUSE Observability with the helm command used to install but now include the new `authentication.yaml` file, `helm upgrade ... --values authentication.yaml`. Make sure to always include this file now when upgrading.
+
+### Used scopes
+
+SUSE Observability is configured to requests 4 scopes:
+* openid, to do authentication
+* email, to identify users
+* profile, to be able to request the user profile which contains the groups for the users
+* offline_access, to be able to keep a user logged in for a longer time without re-authentication and to allow the user to use SUSE Observabilities API tokens.
+
+For further details, see [Permissions and consent in the Microsoft identity platform \(learn.microsoft.com\)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent).
diff --git a/setup/security/authentication/troubleshooting.md b/setup/security/authentication/troubleshooting.md
@@ -0,0 +1,32 @@
+---
+description: SUSE Observability Self-hosted
+---
+
+# Troubleshooting authentication and authorization
+
+When authentication or authorization fails it usually is due to a mismatch in the configuration of the provider and SUSE Observability. To make troubleshooting easier it is possible to enable debug logging on SUSE Observability for authentication and authorization specifically.
+
+{% hint style="warning" %}
+Disable the debug logging again as soon as your are done with troubleshooting, because it is very likely debug logging contains secrets and/or personal information.
+{% endhint %}
+
+To enable debug logging copy/paste the following yaml snippet into a `debug-auth.yaml` file.
+
+```yaml
+stackstate:
+  components:
+    server:
+      additionalLogging: |
+        logger("org.pac4j.core.engine", DEBUG)
+        logger("org.pac4j.oidc.profile.creator", DEBUG)
+        logger("org.pac4j.oidc.credentials.authenticator", DEBUG)
+    api:
+      additionalLogging: |
+        logger("org.pac4j.core.engine", DEBUG)
+        logger("org.pac4j.oidc.profile.creator", DEBUG)
+        logger("org.pac4j.oidc.credentials.authenticator", DEBUG)
+```
+
+Now run the `helm upgrade` command you used before but include this one extra yaml file (so `helm upgrade .... --values debug-auth.yaml`) to enable debug logging. No pods will be restarting, the logging configuration changes will be loaded automatically after about 30 seconds.
+
+To disable the debug logging run the `helm upgrade ....` command again but omit the `--values debug-auth.yaml`. After 30 seconds the updated logging configuration is loaded and the debug logging stops.