diff --git a/SUMMARY.md b/SUMMARY.md index c2995b269..223ceca9f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -123,10 +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/20240911112250.md) - * [v2.0.1 - 18/09/2024](setup/release-notes/20240918082712.md) - * [v2.0.2 - 01/10/2024](setup/release-notes/20241001154902.md) - * [v2.1.0 - 29/10/2024](setup/release-notes/20241023133226.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) * [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) @@ -144,6 +146,7 @@ * [Security](setup/security/README.md) * [Authentication](setup/security/authentication/README.md) * [Authentication options](setup/security/authentication/authentication_options.md) + * [Single password](/setup/security/authentication/single_password.md) * [File-based](setup/security/authentication/file.md) * [LDAP](setup/security/authentication/ldap.md) * [Open ID Connect \(OIDC\)](setup/security/authentication/oidc.md) @@ -155,6 +158,7 @@ * [Roles](setup/security/rbac/rbac_roles.md) * [Scopes](setup/security/rbac/rbac_scopes.md) * [Self-signed certificates](setup/security/self-signed-certificates.md) + * [External secrets](setup/security/external-secrets.md) ## 🔐 Security diff --git a/k8s-suse-rancher-prime.md b/k8s-suse-rancher-prime.md index 9b77eaf22..de045e081 100644 --- a/k8s-suse-rancher-prime.md +++ b/k8s-suse-rancher-prime.md @@ -158,7 +158,12 @@ The `sizing.profile` should be one of trial, 10-nonha, 20-nonha, 50-nonha, 100-n This command will generate a `$VALUES_DIR/suse-observability-values/templates/baseConfig_values.yaml` and a `$VALUES_DIR/suse-observability-values/templates/sizing_values.yaml` file which contains the necessary configuration for installing the SUSE Observability Helm Chart. {% hint style="info" %} -The SUSE Observability administrator passwords will be autogenerated by the above command and are output as comments in the generated `basicConfig.yaml` file. The actual values contain the `bcrypt` hashes of those passwords so that they're securely stored in the Helm release in the cluster. +The SUSE Observability administrator password will be autogenerated by the above command and are output as comments in the generated `basicConfig.yaml` file. For more info, see [single password](/setup/security/authentication/single_password.md). +The actual values contain the `bcrypt` hashes of those passwords so that they're securely stored in the Helm release in the cluster. +{% endhint %} + +{% hint style="warn" %} +Using a single default password is great to get started with SUSE Observability, but for a production setup [more secure authentication options](/setup/security/authentication/authentication_options.md) are available. {% endhint %} {% hint style="info" %} diff --git a/setup/configure-stackstate/email-notifications.md b/setup/configure-stackstate/email-notifications.md index 68f919fa2..cee9fb1ac 100644 --- a/setup/configure-stackstate/email-notifications.md +++ b/setup/configure-stackstate/email-notifications.md @@ -16,21 +16,30 @@ SUSE Observability needs to be configured with credentials to connect to the SMT ```yaml stackstate: - components: - all: - extraEnv: - open: - CONFIG_FORCE_stackstate_email_sender: "" - CONFIG_FORCE_stackstate_email_server_host: "" - CONFIG_FORCE_stackstate_email_server_username: "" - secret: - CONFIG_FORCE_stackstate_email_server_password: "" + email: + enabled: true + sender: "" + server: + host: "" + auth: + username: "" + password: "" ``` -This will use port `587` on the SMTP server and uses the `STARTTLS` command to establish a secure connection. -To use a different port, it can be specified explicitly: +This will use port `587` on the SMTP server and uses the `STARTTLS` command to establish a secure connection. These are all the other options that can be customized: ```yaml -stackstate.components.all.extraEnv.open: - CONFIG_FORCE_stackstate_email_server_port: 465 +stackstate: + email: + additionalProperties: + # Add needed Java email properties for your mail server (use string values), defaults are: + "mail.smtp.auth": "true" + "mail.smtp.starttls.enable": "true" + server: + protocol: smtp + port: 587 ``` + +### Using an external secret + +When the username and password cannot be provided in the values but should come from an external secret, follow [these steps](/setup/security/external-secrets.md#getting-username-and-password-for-email-sending-from-an-external-secret) \ No newline at end of file diff --git a/setup/data-management/data_retention.md b/setup/data-management/data_retention.md index 76e9945fd..b0911956a 100644 --- a/setup/data-management/data_retention.md +++ b/setup/data-management/data_retention.md @@ -10,37 +10,21 @@ SUSE Observability imposes data retention limits to save storage space and impro ## Retention of topology graph data -By default, topology graph data will be retained for 30 days. This works in a way that the latest state of topology graph will always be retained; only history older than 30 days will be removed. You can check and alter the configured retention period this using the SUSE Observability CLI. +By default, topology graph data will be retained for 30 days. This works in a way that the latest state of topology graph will always be retained; only history older than 30 days will be removed. +In some cases, it may be useful to keep historical data for more than 30 days or to reduce it to less than 30 days to save on disk space. Topology retention can be configured through the helm chart: -```shell -$ sts graph retention -``` - -In some cases, it may be useful to keep historical data for more than 30 days or to reduce it to less than 30 days to save on disk space. - -```shell -$ sts graph retention --set 10d -``` - -\(note that the duration can be specified as a duration string\) - -Note that by adding more time to the data retention period, the amount of data stored is also going to grow and need more storage space. This may also affect the performance of the Views. - -After changing the retention period to a smaller window, you may end up with some data that's already expired and will wait there until the next scheduled cleanup. To schedule a cleanup soon after the new retention window is applied use this command: - -```shell -$ sts graph retention --set 10d --schedule-removal +```yaml +stackstate: + topology: + # Retention set to 1 week + retentionHours: 144 ``` -In some cases, for example a disk running full, it can be needed to force removal of data immediately. This will have an impact on performance and current activity on SUSE Observability so is better avoided. +Note that by adding more time to the data retention period, the amount of data stored is also going to grow and requires more storage space. This may also affect the performance of the Views. -Note that this may take some time to have an effect. +When lowering the retention period, it can take some time until disk space is freed up (at least 15 minutes). -```shell -$ sts graph delete-expired-data --immediately -``` - -## Retention of events, traces and logs +## Retention of events and logs ### SUSE Observability data store @@ -48,7 +32,7 @@ If you are using the event/logs store provided with SUSE Observability, your dat #### Configure disk space for Elasticsearch -In some circumstances it may be necessary to adjust the disk space available to Elasticsearch and how it's allocated to logs, events and traces, for example if you anticipate a lot of data to arrive for a specific data type. +In some circumstances it may be necessary to adjust the disk space available to Elasticsearch and how it's allocated to logs and events, for example if you anticipate a lot of data to arrive for a specific data type. Here is a snippet with the complete disk space and retention config for Elasticsearch, including the default values. @@ -68,11 +52,6 @@ stackstate: esDiskSpaceShare: 30 # Number of days to keep the events data on Es retention: 30 - trace2es: - esDiskSpaceShare: 0 - # Number of days to keep the traces data on Es - retention: 7 - enabled: false ``` The disk space available for Elasticsearch is configured via the `elasticsearch.volumeClaimTemplate.resources.requests.storage` key. To change this value after the initial installation some [extra steps are required](data_retention.md#resizing-storage). diff --git a/setup/install-stackstate/kubernetes_openshift/ingress.md b/setup/install-stackstate/kubernetes_openshift/ingress.md index ba28499f1..d15edfbb6 100644 --- a/setup/install-stackstate/kubernetes_openshift/ingress.md +++ b/setup/install-stackstate/kubernetes_openshift/ingress.md @@ -72,6 +72,20 @@ opentelemetry-collector: - hosts: - otlp-stackstate.MY_DOMAIN secretName: otlp-tls-secret + additionalIngresses: + - name: otlp-http + annotations: + nginx.ingress.kubernetes.io/proxy-body-size: "50m" + hosts: + - host: otlp-http-stackstate.MY_DOMAIN + paths: + - path: / + pathType: Prefix + port: 4318 + tls: + - hosts: + - otlp-http-stackstate.MY_DOMAIN + secretName: otlp-http-tls-secret ``` The thing that stands out in this file is the Nginx annotation to increase the allowed `proxy-body-size` to `50m` \(larger than any expected request\). By default, Nginx allows body sizes of maximum `1m`. SUSE Observability Agents and other data providers can sometimes send much larger requests. For this reason, you should make sure that the allowed body size is large enough, regardless of whether you are using Nginx or another ingress controller. Make sure to update the `baseUrl` in the values file generated during initial installation, it will be used by SUSE Observability to generate convenient installation instructions for the agent. diff --git a/setup/install-stackstate/kubernetes_openshift/kubernetes_install.md b/setup/install-stackstate/kubernetes_openshift/kubernetes_install.md index 591ee4f9d..15a8193df 100644 --- a/setup/install-stackstate/kubernetes_openshift/kubernetes_install.md +++ b/setup/install-stackstate/kubernetes_openshift/kubernetes_install.md @@ -81,7 +81,6 @@ The values that can be passed to this chart are: | Base URL | `baseUrl` | The ``. The external URL for SUSE Observability that users and agents will use to connect. For example `https://suse-observability.internal`. If you haven't decided on an Ingress configuration yet, use `http://localhost:8080`. This can be updated later in the generated file. | | Username and password\*\* | `-u` `-p` | The username and password used by SUSE Observability to pull images. For air-gapped environments these need to be the username and password for the local contaier registry. | | License key | `license` | The SUSE Observability license key. | -| Admin API password | `adminApiPassword` | The password for the admin API. Note that this API contains system maintenance functionality and should only be accessible by the maintainers of the SUSE Observability installation. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you. | | Default password | `adminPassword` | The password for the default user \(`admin`\) to access SUSE Observability's UI. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you.| | Image Registry | `imageRegistry` | The registry where the SUSE Observability images are hosted. If not provided, the default value will be 'quay.io' | | Pull Secret Username | `pullSecret.username` | The username used to pull images from the Docker registry where the SUSE Observability images are hosted. Only needed for custom registries. | diff --git a/setup/install-stackstate/kubernetes_openshift/openshift_install.md b/setup/install-stackstate/kubernetes_openshift/openshift_install.md index ee1182095..2f4a3dd83 100644 --- a/setup/install-stackstate/kubernetes_openshift/openshift_install.md +++ b/setup/install-stackstate/kubernetes_openshift/openshift_install.md @@ -87,7 +87,6 @@ The values that can be passed to this chart are: | Base URL | `baseUrl` | The ``. The external URL for SUSE Observability that users and agents will use to connect. For example `https://suse-observability.internal`. If you haven't decided on an Ingress configuration yet, use `http://localhost:8080`. This can be updated later in the generated file. | | Username and password\*\* | `-u` `-p` | The username and password used by SUSE Observability to pull images. For air-gapped environments these need to be the username and password for the local docker registry. | | License key | `license` | The SUSE Observability license key. | -| Admin API password | `adminApiPassword` | The password for the admin API. Note that this API contains system maintenance functionality and should only be accessible by the maintainers of the SUSE Observability installation. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you. | | Default password | `adminPassword` | The password for the default user \(`admin`\) to access SUSE Observability's UI. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you.| | Image Registry | `imageRegistry` | The registry where the SUSE Observability images are hosted. If not provided, the default value will be 'quay.io' | | Pull Secret Username | `pullSecret.username` | The username used to pull images from the Docker registry where the SUSE Observability images are hosted. | diff --git a/setup/install-stackstate/kubernetes_openshift/storage.md b/setup/install-stackstate/kubernetes_openshift/storage.md index 946d23e51..9eb3b335f 100644 --- a/setup/install-stackstate/kubernetes_openshift/storage.md +++ b/setup/install-stackstate/kubernetes_openshift/storage.md @@ -21,21 +21,8 @@ For the `size` we provide the sameple for both `HA` and `NonHa` depending on the {% tab title="Changing storage class" %} ```yaml global: - # The storage class for most of the persistent volumes + # The storage class for all of the persistent volumes storageClass: "standard" - -elasticsearch: - volumeClaimTemplate: - storageClassName: "standard" - -victoria-metrics-0: - server: - persistentVolume: - storageClass: "standard" -victoria-metrics-1: - server: - persistentVolume: - storageClass: "standard" ``` {% endtab %} diff --git a/setup/otel/collector.md b/setup/otel/collector.md index 4ca1339ef..ee2495c1b 100644 --- a/setup/otel/collector.md +++ b/setup/otel/collector.md @@ -34,7 +34,7 @@ To install and configure the collector for usage with SUSE Observability we'll u ### Configure the collector Here is the full values file needed, continue reading below the file for an explanation of the different parts. Or skip ahead to the next step, but make sure to replace: -* `` with the OTLP endpoint of your SUSE Observability. If, for example, you access SUSE Observability on `play.stackstate.com` the OTLP endpoint is `otlp-play.stackstate.com`. So simply prefixing `otlp-` to the normal SUSE Observability url will do. +* `` with the OTLP endpoint of your SUSE Observability. If, for example, you access SUSE Observability on `play.stackstate.com` the OTLP endpoint is `otlp-play.stackstate.com` for GRPC and `otlp-http-play.stackstate.com` for HTTP traffic. So simply prefixing `otlp-` or `otlp-http-` to the normal SUSE Observability url will do. * `` with the cluster name you configured in SUSE Observability. **This must be the same cluster name used when installing the SUSE Observability agent**. Using a differnt cluster name will result in an empty traces perspective for Kubernetes components. {% hint style="warning" %} @@ -68,6 +68,10 @@ config: auth: authenticator: bearertokenauth endpoint: :443 + otlphttp/stackstate: + auth: + authenticator: bearertokenauth + endpoint: https:// processors: tail_sampling: decision_wait: 10s @@ -161,7 +165,7 @@ The `service` section determines what components of the collector are enabled. T The `pipelines` section defines pipelines for the traces and metrics. The metrics pipeline defines: * `receivers`, to receive metrics from instrumented applications (via the OTLP protocol, `otlp`), from spans (the `spanmetrics` connector) and by scraping Prometheus endpoints (the `prometheus` receiver). The latter is configured by default in the collector Helm chart to scrape the collectors own metrics * `processors`: The `memory_limiter` helps to prevent out-of-memory errors. The `batch` processor helps better compress the data and reduce the number of outgoing connections required to transmit the data. The `resource` processor adds additional resource attributes (discussed separately) -* `exporters`: The `debug` exporter simply logs to stdout which helps when troubleshooting. The `otlp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol. It is configured to use the bearertokenauth extension for authentication to send data to the SUSE Observability OTLP endpoint. +* `exporters`: The `debug` exporter simply logs to stdout which helps when troubleshooting. The `otlp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via GRPC (Default). The `otlphttp/stackstate` exporter sends telemetry data to SUSE Observability using the OTLP protocol via HTTP and is meant to be used where there area some impediments to use the GRPC one (needs to be activated in the pipelines). Both OTLP exporters are configured to use the bearertokenauth extension for authentication to send data to the SUSE Observability OTLP endpoint. For traces, there are 3 pipelines that are connected: * `traces`: The pipeline that receives traces from SDKs (via the `otlp` receiver) and does the initial processing using the same processors as for metrics. It exports into a router which routes all spans to both other traces pipelines. This setup makes it possible to calculate span metrics for all spans while applying sampling to the traces that are exported. diff --git a/setup/otel/troubleshooting.md b/setup/otel/troubleshooting.md index 5b02d1583..97214d7f7 100644 --- a/setup/otel/troubleshooting.md +++ b/setup/otel/troubleshooting.md @@ -36,14 +36,8 @@ To ensure the api key is configured correctly check that: ### Some proxies and firewalls don't work well with gRPC -If the collector needs to send data through a proxy or a firewall it can be that they either block the traffic completely or possibly drop some parts of the gRPC messages or unexpectedly drop the long-lived gRPC connection completely. The easiest fix is to switch from gRPC to use HTTP instead, by replacing the `otlp/stackstate` exporter configuration and all its references with the `otlp-http/stackstate` exporter with this configuration. +If the collector needs to send data through a proxy or a firewall it can be that they either block the traffic completely or possibly drop some parts of the gRPC messages or unexpectedly drop the long-lived gRPC connection completely. The easiest fix is to switch from gRPC to use HTTP instead, by replacing the `otlp/stackstate` exporter configuration and all its references with the `otlphttp/stackstate` exporter which is already configured and ready. -```yaml - otlp-http/stackstate: - auth: - authenticator: bearertokenauth - endpoint: :4318 -``` Here `` is similar to the ``, but instead of a `otlp-` prefix it has `otlp-http-` prefix, for example, `otlp-http-play.stackstate.com`. diff --git a/setup/release-notes/20240911112250.md b/setup/release-notes/v2.0.0.md similarity index 100% rename from setup/release-notes/20240911112250.md rename to setup/release-notes/v2.0.0.md diff --git a/setup/release-notes/20240918082712.md b/setup/release-notes/v2.0.1.md similarity index 100% rename from setup/release-notes/20240918082712.md rename to setup/release-notes/v2.0.1.md diff --git a/setup/release-notes/20241001154902.md b/setup/release-notes/v2.0.2.md similarity index 100% rename from setup/release-notes/20241001154902.md rename to setup/release-notes/v2.0.2.md diff --git a/setup/release-notes/20241023133226.md b/setup/release-notes/v2.1.0.md similarity index 100% rename from setup/release-notes/20241023133226.md rename to setup/release-notes/v2.1.0.md diff --git a/setup/release-notes/v2.2.0.md b/setup/release-notes/v2.2.0.md new file mode 100644 index 000000000..ec251cc3d --- /dev/null +++ b/setup/release-notes/v2.2.0.md @@ -0,0 +1,32 @@ +--- +description: SUSE Observability Self-hosted +--- + +# v2.2.0 -09/12/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. +{% endhint %} + +## Release Notes StackState version 7.0.0-snapshot.20241204151219-master-db9515b Helm Chart version 2.2.0 + +### New Features & Enhancements +* Support OpenTelemetry over HTTP +* Added related health violations to external monitors. +* Added option to the helm chart to get the license key, api key and authentication secrets from an external kubernetes secret. +* Removed the admin api and accompanying platform admin user +* Added support for highlighting of Spans which match the search criteria in the Trace perspective and Trace explorer. +* Simplify email server configuration on self-hosted installations. +* Upgrade to HDFS 3.4.1 +* Use a default namespace for Opentelemetry services, so they all show up as components in the topology + +### Bug Fixes +* Fixed issue with nonHA deployments where custom StackPacks were not persisted. +* Fix to respect `global.storageClassName` on all requested PVCs +* A removed `ServiceAccount`, for the backup cronjob, was still referenced when upgrading from an older Helm chart version +* Fixed issue where outgoing and incoming layers were reversed in the topology visualizer. +* Make sure the 'available service endpoints' fires when there are pods which are not in ready state." +* Only load related resources per type to avoid an error condition in the related resources drawer. + +### Breaking changes +* The allowed usernames when using [file based authenticated](/setup/security/authentication/file.md) is restricted to alphanumeric characters and `_`. diff --git a/setup/release-notes/v2.2.1.md b/setup/release-notes/v2.2.1.md new file mode 100644 index 000000000..429111c1b --- /dev/null +++ b/setup/release-notes/v2.2.1.md @@ -0,0 +1,10 @@ +--- +description: SUSE Observability Self-hosted +--- + +# v2.2.1 -10/12/2024 + +## Release Notes StackState version 7.0.0-snapshot.20241204151219-master-db9515b Helm Chart version 2.2.1 + +### Bug Fixes +* Fix the Helm chart which was referencing images with an invalid URL for some of the pods. \ No newline at end of file diff --git a/setup/security/authentication/authentication_options.md b/setup/security/authentication/authentication_options.md index 4f7960436..125ea7259 100644 --- a/setup/security/authentication/authentication_options.md +++ b/setup/security/authentication/authentication_options.md @@ -4,10 +4,11 @@ description: SUSE Observability Self-hosted # Authentication options -Out of the box, SUSE Observability is configured with [file-based authentication](file.md) with a username and password [configured during installation](../../../setup/install-stackstate/initial_run_guide.md#default-username-and-password). This authenticates users with a file on the server. However, this isn't a production-ready setup. +Out of the box, SUSE Observability is configured with [single password authentication](file.md) with admin user and random password [configured during installation](../../../setup/install-stackstate/initial_run_guide.md#default-username-and-password). This authenticates users with a simple secret on the server. However, this isn't a production-ready setup. For better security SUSE Observability can be configured to use exactly one of the following authentication mechanisms \(replacing the standard admin user\): +* [Single password](single_password.md) * [File based](file.md) * [LDAP](ldap.md) * [Open ID Connect \(OIDC\)](oidc.md) @@ -25,7 +26,6 @@ When a user has been authenticated permissions for that user are usually assigne * **Kubernetes Troubleshooter** - able to see all information and see and change monitors and metric configuration. * **Power User** - able to see and change all configuration and install StackPacks. * **Administrator** - able to see and change content of SUSE Observability. For example, see all configuration, install StackPacks, grant and revoke user permissions and upload \(new versions of\) StackPacks. -* **Platform Administrator** - able to perform management of the SUSE Observability platform. For example, change data retention, clear the database, view logs and cache management. When deciding on the roles to assign your users, it's strongly advised to have only a small group of Platform Administrators and Administrators. For example, only the engineers responsible for installing SUSE Observability and doing the initial configuration. Administrator users can manage access to SUSE Observability and decide which StackPacks can be used. You can delegate installation of StackPacks and other fine-tuning of the configuration to a larger number of users with the Power User role. Platform Administrator users can clear the database, change data retention settings, view logs and perform other platform management tasks. diff --git a/setup/security/authentication/file.md b/setup/security/authentication/file.md index 5bedc72e2..7768f3d02 100644 --- a/setup/security/authentication/file.md +++ b/setup/security/authentication/file.md @@ -27,13 +27,10 @@ stackstate: - username: admin passwordHash: 5f4dcc3b5aa765d61d8327deb882cf99 roles: [ stackstate-admin ] - - username: platformadmin - passwordHash: 5f4dcc3b5aa765d61d8327deb882cf99 - roles: [ stackstate-platform-admin ] - username: guest passwordHash: 5f4dcc3b5aa765d61d8327deb882cf99 roles: [ stackstate-guest ] - - username: power-user + - username: poweruser passwordHash: 5f4dcc3b5aa765d61d8327deb882cf99 roles: [ stackstate-power-user ] - username: troubleshooter @@ -46,9 +43,9 @@ stackstate: Follow the steps below to configure users and apply changes: 1. In `authentication.yaml` - add users. The following configuration should be added for each user \(see the example above\): - * **username** - the username used to log into SUSE Observability. + * **username** - the username used to log into SUSE Observability. Only alphanumeric and _ characters are allowed. * **passwordHash** - the password used to log into SUSE Observability. Passwords are stored as a bcrypt hash. - * **roles** - the list of roles that the user is a member of. The [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) are `stackstate-admin`,`stackstate-platform-admin`, `stackstate-power-user` and `stackstate-guest`, for details on how to create other roles, see [RBAC roles](../rbac/rbac_roles.md). + * **roles** - the list of roles that the user is a member of. The [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) are `stackstate-admin`, `stackstate-power-user` and `stackstate-guest`, for details on how to create other roles, see [RBAC roles](../rbac/rbac_roles.md). 2. Store the file `authentication.yaml` together with the file `values.yaml` from the SUSE Observability installation instructions. 3. Run a Helm upgrade to apply the changes: @@ -75,9 +72,9 @@ Follow the steps below to configure users and apply changes: Follow the steps below to configure users and apply changes: 1. In `authentication.yaml` - add users. The following configuration should be added for each user \(see the example above\): - * **username** - the username used to log into SUSE Observability. + * **username** - the username used to log into SUSE Observability. Only alphanumeric and _ characters are allowed. * **password** - the password used to log into SUSE Observability. Passwords are stored as either an MD5 hash or a bcrypt hash. - * **roles** - the list of roles that the user is a member of. The [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) are `stackstate-admin`, `stackstate-platform-admin`, `stackstate-power-user`, `stackstate-k8s-troubleshooter` and `stackstate-guest`, for details on how to create other roles, see [RBAC roles](../rbac/rbac_roles.md). + * **roles** - the list of roles that the user is a member of. The [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) are `stackstate-admin`, `stackstate-power-user`, `stackstate-k8s-troubleshooter` and `stackstate-guest`, for details on how to create other roles, see [RBAC roles](../rbac/rbac_roles.md). 2. Restart SUSE Observability to apply the changes. {% hint style="info" %} @@ -87,9 +84,44 @@ Follow the steps below to configure users and apply changes: * A bcrypt password hash can be generated using the following command line `htpasswd -bnBC 10 "" | tr -d ':\n'` or using an online tool. {% endhint %} +### Using an external secret + +When the user passwords 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: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + file__password: + file__password: +``` + +For every user in the logins section, a record should be added to the secret, filling in the template. For example: + +```yaml + +stackstate: + authentication: + file: + logins: + - username: admin_user + roles: [ stackstate-admin ] + + +kind: Secret +metadata: + name: "" +type: Opaque +data: + file_admin_user_password: "base64EncryptedPass" +``` + ## See also * [Authentication options](authentication_options.md) * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) * [Create RBAC roles](../rbac/rbac_roles.md) +* [External Secrets](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) diff --git a/setup/security/authentication/keycloak.md b/setup/security/authentication/keycloak.md index 00d308506..23ddec4c4 100644 --- a/setup/security/authentication/keycloak.md +++ b/setup/security/authentication/keycloak.md @@ -50,12 +50,11 @@ stackstate: # groupsField: roles # map the roles from Keycloak to the - # 4 standard subjects in SUSE Observability (guest, powerUser, admin and platformAdmin) + # 3 standard subjects in SUSE Observability (guest, powerUser and admin) roles: guest: ["keycloak-guest-role-for-stackstate"] powerUser: ["keycloak-power-user-role-for-stackstate"] admin: ["keycloak-admin-role-for-stackstate"] - platformAdmin: ["keycloak-platformadmin-role-for-stackstate"] ``` {% hint style="info" %} @@ -76,7 +75,7 @@ Follow the steps below to configure SUSE Observability to authenticate using Key * **jwtClaims** - Optional: The roles or username can be retrieved from a different attribute than the Keycloak default behavior * **usernameField** - Optional: The field in the OIDC user profile that should be used as the username. By default, this will be the `preferred_username`. * **groupsField** - Optional: SUSE Observability will always, and by default only, use the `roles` Keycloak provides. But it can also add roles from the field specified here. This is mainly useful when Keycloak is mapping roles/groups from a third-party system. -2. In `authentication.yaml` - map user roles from KeyCloak to the correct SUSE Observability subjects using the `roles.guest`, `roles.powerUser`, `roles.platformAdmin` or `roles.admin` settings \(see the example above\). For details, see the [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles). More SUSE Observability roles can also be created, see the [RBAC documentation](../rbac/). +2. In `authentication.yaml` - map user roles from KeyCloak to the correct SUSE Observability subjects using the `roles.guest`, `roles.powerUser` or `roles.admin` settings \(see the example above\). For details, see the [default SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles). More SUSE Observability roles can also be created, see the [RBAC documentation](../rbac/). 3. Store the file `authentication.yaml` together with the `values.yaml` file from the SUSE Observability installation instructions. 4. Run a Helm upgrade to apply the changes: @@ -98,9 +97,24 @@ Follow the steps below to configure SUSE Observability to authenticate using Key * The authentication configuration is stored as a Kubernetes secret. {% endhint %} +### Using an external secret + +When the keycloak 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: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + keycloak_client_id: + keycloak_secret: +``` + ## See also * [Authentication options](authentication_options.md) * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) * [Create RBAC roles](../rbac/rbac_roles.md) +* [External Secrets](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) diff --git a/setup/security/authentication/ldap.md b/setup/security/authentication/ldap.md index a382cc05b..391346ef5 100644 --- a/setup/security/authentication/ldap.md +++ b/setup/security/authentication/ldap.md @@ -49,12 +49,11 @@ stackstate: # groupMemberKey: "member:1.2.840.113556.1.4.1941:" # map the groups from LDAP to the - # standard subjects in SUSE Observability (guest, powerUser, admin and platformAdmin) + # standard subjects in SUSE Observability (guest, powerUser and admin) roles: guest: ["ldap-guest-role-for-stackstate"] powerUser: ["ldap-power-user-role-for-stackstate"] admin: ["ldap-admin-role-for-stackstate"] - platformAdmin: ["ldap-platform-admin-role-for-stackstate"] ``` {% endtab %} {% endtabs %} @@ -122,9 +121,22 @@ suse-observability/suse-observability * The authentication configuration is stored as a Kubernetes secret. {% endhint %} +### Using an external secret + +When the ldap password 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: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + ldap_password: +``` + ## See also * [Authentication options](authentication_options.md) * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) * [Create RBAC roles](../rbac/rbac_roles.md) - +* [External Secrets](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) diff --git a/setup/security/authentication/oidc.md b/setup/security/authentication/oidc.md index e96030ef9..e3921a85c 100644 --- a/setup/security/authentication/oidc.md +++ b/setup/security/authentication/oidc.md @@ -41,12 +41,12 @@ stackstate: access_type: offline # map the groups from OIDC provider - # to the 4 standard roles in SUSE Observability (guest, powerUser, admin and platformAdmin) + # 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"] - platformAdmin: ["oidc-platform-admin-role-for-stackstate"] + k8sTroubleshooter: ["oidc-troubleshooter-role-for-stackstate"] ``` Follow the steps below to configure SUSE Observability to authenticate using OIDC: @@ -106,9 +106,23 @@ jwsAlgorithm: RS256 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 + +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: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + oidc_client_id: + oidc_secret: +``` + ## See also * [Authentication options](authentication_options.md) * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) * [Create RBAC roles](../rbac/rbac_roles.md) - +* [External Secrets](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) diff --git a/setup/security/authentication/service_tokens.md b/setup/security/authentication/service_tokens.md index f3b7fcb00..da8722318 100644 --- a/setup/security/authentication/service_tokens.md +++ b/setup/security/authentication/service_tokens.md @@ -100,6 +100,21 @@ Follow the steps below to configure SUSE Observability to create a bootstrap ser * The authentication configuration is stored as a Kubernetes secret. {% endhint %} +#### Setup the bootstrap service token from an external secret + +When the bootstrap token should come from an external secret, follow [these steps](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) and add the following data: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + bootstrap_token: +``` + +This token can be added to the secret next to the data that is already there. + ### List service tokens The ID, name, expiration date and roles of all created service tokens can be seen using the new `sts` CLI. For example: @@ -131,7 +146,7 @@ A service token can be used for authentication with the `sts` CLI. For details, ### SUSE Observability APIs -To use a service token to talk directly to the SUSE Observability Base API or the SUSE Observability Admin API, add it to the header of the request in one of the following ways: +To use a service token to talk directly to the SUSE Observability Base API, add it to the header of the request in one of the following ways: * In the `Authorization` header: ```bash diff --git a/setup/security/authentication/single_password.md b/setup/security/authentication/single_password.md new file mode 100644 index 000000000..16bcf5ea4 --- /dev/null +++ b/setup/security/authentication/single_password.md @@ -0,0 +1,62 @@ +--- +description: SUSE Observability Self-hosted +--- + +# Single password + +Out of the box, SUSE Observability is configured with a single password configuration, [configured during installation](/k8s-suse-rancher-prime.md#installation). This authenticates users with a single, randomly generated password created by the `suse-observability-values` chart. +The password value can be found as comment in the generated `suse-observability-values/templates/baseConfig_values.yaml`. + +This setup provisions an admin user with the generated password + +This method for providing a password is suited to get started out-of-the-box, but for production one of the other [authentication options](/setup/security/authentication/authentication_options.md) is recommended. + +## Setting the single password through the values chart + +To set an alternative password [during installation](/k8s-suse-rancher-prime.md#installation), add the following line to the values generation command during installation: + +```bash +helm template \ + ... + --set adminPassword='' \ + ... + suse-observability-values \ + suse-observability/suse-observability-values --output-dir $VALUES_DIR +``` + +## Setting the single password in the helm chart + +It is also possible to set the single password directly in the helm install invocation. This is done by creating a bcrypted string of the required password, using `htpasswd -bnBC 10 "" | tr -d ':\n'` or using an online tool. +The fill it into the helm invocation or separate values.yaml. + +```bash +helm install \ + ... + --set stackstate.authentication.adminPassword='' \ + ... + suse-observability \ + suse-observability/suse-observability --output-dir $VALUES_DIR +``` + +### Using an external secret + +When the single password 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: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + default_password: +``` + +Creating a bcrypted version of a password can be done using `htpasswd -bnBC 10 "" | tr -d ':\n'`. + +## See also + +* [Authentication options](authentication_options.md) +* [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles) +* [Create RBAC roles](../rbac/rbac_roles.md) +* [External Secrets](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) + diff --git a/setup/security/external-secrets.md b/setup/security/external-secrets.md new file mode 100644 index 000000000..f287ed512 --- /dev/null +++ b/setup/security/external-secrets.md @@ -0,0 +1,90 @@ +--- +description: SUSE Observability External Secrets +--- + +# External Secrets + +## Overview + +SUSE Observability can take secrets like license key, api key and authentication keys through the helm install, but can also take those from already provisioned secrets. + +Here is described how to configure this. + +## Getting the license key from an external secret + +Create a secret in the namespace SUSE Observability is installed in, of the following form, filling in the blanks: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + LICENSE_KEY: "" +``` + +Add the following to your helm install command to use the secret: + +```bash + --set 'stackstate.license.fromExternalSecret'='' +``` + +## Getting username and password for email notifications from an external secret + +Create a secret in the namespace SUSE Observability is installed in, of the following form, filling in the blanks: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + SMTP_USER_NAME: "" + SMTP_PASSWORD: "" +``` + +Add the following to your helm install command to use the secret: + +```bash + --set 'stackstate.email.server.auth.fromExternalSecret'='' +``` + +## Getting the api key from an external secret + +Create a secret in the namespace SUSE Observability is installed in, of the following form, filling in the blanks: + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + API_KEY: "" +``` + +Add the following to your helm install command to use the secret: + +```bash + --set 'stackstate.apiKey.fromExternalSecret'='' +``` + +## Getting authentication data from an external secret + +Create a secret in the namespace SUSE Observability is installed in, of the following form. + +```yaml +kind: Secret +metadata: + name: "" +type: Opaque +data: + default_password: +``` + +Depending on the authentication method chosen, the `default_password` field gets replaced with different data. See the [authentication options](/setup/security/authentication/authentication_options.md) for more info. In this example the [Single password](/setup/security/authentication/single_password.md) setup is used. + +Add the following to your helm install command to use the secret: + +```bash + --set 'stackstate.authentication.fromExternalSecret'='' +``` diff --git a/setup/security/rbac/rbac_permissions.md b/setup/security/rbac/rbac_permissions.md index a431016c7..0511e835e 100644 --- a/setup/security/rbac/rbac_permissions.md +++ b/setup/security/rbac/rbac_permissions.md @@ -21,7 +21,6 @@ There are two types of permission in SUSE Observability. **System permissions** The following permissions are available in SUSE Observability: -* `access-admin-api` -Access the administrator API. * `access-analytics` - Access the Analytics page in the SUSE Observability UI. * `access-cli` - Access the CLI page. This provides the API key to use for authentication with the SUSE Observability CLI. * `access-explore` - Access the Explore page in the SUSE Observability UI. diff --git a/setup/security/rbac/rbac_roles.md b/setup/security/rbac/rbac_roles.md index 913c8d727..7dbd317b3 100644 --- a/setup/security/rbac/rbac_roles.md +++ b/setup/security/rbac/rbac_roles.md @@ -12,8 +12,7 @@ Every user in SUSE Observability needs to have a subject and a set of [permissio There are four roles predefined in SUSE Observability: -* **Administrator** - has full access to all views and has all permissions, except for platform management. -* **Platform Administrator** - has platform management permissions and access to all views. +* **Administrator** - has full access to all views and has all permissions. * **Power User** - typically granted to a user that needs to configure SUSE Observability for a team\(s\), but won't manage the entire SUSE Observability installation. * **Kubernetes Troubleshooter** - has all permissions required to use SUSE Observability for troubleshooting, including the ability to enable/disable monitors, create custom views and use the Cli. * **Guest** - has read-only access to SUSE Observability. @@ -23,7 +22,7 @@ The permissions assigned to each predefined SUSE Observability role can be found {% tabs %} {% tab title="Administrator" %} -The Administrator role \(`stackstate-admin`\): has all permissions assigned, except for `access-admin-api`, which is assigned only to the Platform Administrator predefined role. +The Administrator role \(`stackstate-admin`\): has all permissions assigned. Permissions assigned to the predefined Administrator role (`stackstate-admin`) are listed below, these were retrieved using the `sts` CLI. For details of the different permissions and how to manage them using the `sts` CLI, see [RBAC permissions](/setup/security/rbac/rbac_permissions.md). @@ -55,11 +54,13 @@ manage-stackpacks | system manage-star-view | system manage-telemetry-streams | system manage-topology-elements | system -perform-custom-query | system -read-metrics | system +perform-custom-query | system +read-agents | system +read-metrics | system read-permissions | system read-settings | system -read-stackpacks | system +read-stackpacks | system +read-system-notifications | system read-telemetry-streams | system run-monitors | system update-permissions | system @@ -67,22 +68,7 @@ update-settings | system update-visualization | system upload-stackpacks | system view-monitors | system -``` -{% endtab %} -{% tab title="Platform Administrator" %} -Platform Administrator \(`stackstate-platform-admin`\) is the only predefined role assigned the permission `access-admin-api`. - -Permissions assigned to the predefined Platform Administrator role (`stackstate-platform-admin`) are listed below, these were retrieved using the `sts` CLI. For details of the different permissions and how to manage them using the `sts` CLI, see [RBAC permissions](/setup/security/rbac/rbac_permissions.md). - -```text -❯ ./sts rbac describe-permissions --subject stackstate-platform-admin -access-view | everything -access-admin-api | system -access-cli | system -access-log-data | system -manage-star-view | system -unlock-node | system ``` {% endtab %} {% tab title="Power User" %} @@ -120,11 +106,13 @@ manage-stackpacks | system manage-star-view | system manage-telemetry-streams | system manage-topology-elements | system -perform-custom-query | system +perform-custom-query | system +read-agents | system read-metrics | system read-permissions | system read-settings | system -read-stackpacks | system +read-stackpacks | system +read-system-notifications | system read-telemetry-streams | system run-monitors | system update-settings | system @@ -164,11 +152,13 @@ manage-stackpacks | system manage-star-view | system manage-telemetry-streams | system manage-topology-elements | system -perform-custom-query | system +perform-custom-query | system +read-agents | system read-metrics | system read-permissions | system read-settings | system -read-stackpacks | system +read-stackpacks | system +read-system-notifications | system read-telemetry-streams | system run-monitors | system update-settings | system @@ -193,7 +183,8 @@ manage-star-view | system perform-custom-query | system read-metrics | system read-permissions | system -read-settings | system +read-settings | system +read-system-notifications | system read-telemetry-streams | system update-visualization | system view-monitors | system @@ -203,7 +194,7 @@ view-monitors | system ## Custom roles -In addition to the predefined roles \(`stackstate-admin`, `stackstate-platform-admin`, `stackstate-power-user`, `stackstate-k8s-troubleshooter`, `stackstate-guest`\), which are always available, custom roles can be added. There are multiple ways to add custom roles: +In addition to the predefined roles \(`stackstate-admin`, `stackstate-power-user`, `stackstate-k8s-troubleshooter`, `stackstate-guest`\), which are always available, custom roles can be added. There are multiple ways to add custom roles: 1. via the configuration file, with the same permission as the predefined roles 2. via the configuration file, with a custom scope and custom system and view permissions @@ -222,8 +213,7 @@ stackstate: guest: ["ldap-guest-role"] powerUser: ["ldap-power-user-role"] admin: ["ldap-admin-role"] - k8sTroubleshooter: ["ldap-troubleshooter-role"] - platformAdmin: ["ldap-platform-admin-role"] + k8sTroubleshooter: ["ldap-troubleshooter-role"] ``` To use it in for your SUSE Observability installation \(or already running instance, note that it will restart the API\): diff --git a/use/security/k8s-ingestion-api-keys.md b/use/security/k8s-ingestion-api-keys.md index e1a8f1738..132caabfe 100644 --- a/use/security/k8s-ingestion-api-keys.md +++ b/use/security/k8s-ingestion-api-keys.md @@ -104,4 +104,8 @@ The following code snippet provides an example configuration: auth: authenticator: bearertokenauth endpoint: :443 + otlphttp/stackstate: + auth: + authenticator: bearertokenauth + endpoint: https:// ``` \ No newline at end of file