LogoLogo
StackState.comDownloadSupportExplore playground
StackState v6.0
StackState v6.0
  • StackState docs!
  • Docs for all StackState products
  • 🚀Get started
    • Quick start guide
    • StackState walk-through
    • SUSE Rancher Prime
      • Air-gapped
      • Agent Air-gapped
  • 🦮Guided troubleshooting
    • What is guided troubleshooting?
    • YAML Configuration
    • Changes
    • Logs
  • 🚨Monitors and alerts
    • Monitors
    • Out of the box monitors for Kubernetes
    • Notifications
      • Configure notifications
      • Notification channels
        • Slack
        • Teams
        • Webhook
        • Opsgenie
      • Troubleshooting
    • Customize
      • Add a monitor using the CLI
      • Override monitor arguments
      • Write a remediation guide
  • 📈Metrics
    • Explore Metrics
    • Custom charts
      • Adding custom charts to components
      • Writing PromQL queries for representative charts
      • Troubleshooting custom charts
    • Advanced Metrics
      • Grafana Datasource
      • Prometheus remote_write
      • OpenMetrics
  • 📑Logs
    • Explore Logs
    • Log Shipping
  • 🔭Traces
    • Explore Traces
  • 📖Health
    • Health synchronization
    • Send health data over HTTP
      • Send health data
      • Repeat Snapshots JSON
      • Repeat States JSON
      • Transactional Increments JSON
    • Debug health synchronization
  • 🔍Views
    • Kubernetes views
    • Custom views
    • Component views
    • Explore views
    • View structure
      • Filters
      • Overview perspective
      • Highlights perspective
      • Topology perspective
      • Events perspective
      • Metrics perspective
      • Traces perspective
    • Timeline and time travel
  • 🕵️Agent
    • Network configuration
      • Proxy Configuration
    • Using a custom registry
    • Custom Secret Management
    • Request tracing
      • Certificates for sidecar injection
  • 🔭Open Telemetry
    • Getting started
    • Open telemetry collector
    • Languages
      • Generic Exporter configuration
      • Java
      • Node.js
      • .NET
      • Verify the results
    • Troubleshooting
  • CLI
    • StackState CLI
  • 🚀Self-hosted setup
    • Install StackState
      • Requirements
      • Kubernetes / OpenShift
        • Kubernetes install
        • OpenShift install
        • Required Permissions
        • Non-high availability setup
        • Small profile setup
        • Override default configuration
        • Configure storage
        • Exposing StackState outside of the cluster
      • Initial run guide
      • Troubleshooting
        • Logs
    • Configure StackState
      • Slack notifications
      • Stackpacks
    • Release Notes
      • v1.11.0 - 18/07/2024
      • v1.11.3 - 15/08/2024
      • v1.11.4 - 29/08/2024
      • v1.12.0 - 24/10/2024
      • v1.12.1 - 08/11/2024
    • Upgrade StackState
      • Steps to upgrade
      • Version-specific upgrade instructions
    • Uninstall StackState
    • Air-gapped
      • StackState air-gapped
      • StackState Kubernetes Agent air-gapped
    • Data management
      • Backup and Restore
        • Kubernetes backup
        • Configuration backup
      • Data retention
      • Clear stored data
    • Security
      • Authentication
        • Authentication options
        • File-based
        • LDAP
        • Open ID Connect (OIDC)
        • KeyCloak
        • Service tokens
      • RBAC
        • Role-based Access Control
        • Permissions
        • Roles
        • Scopes
      • Self-signed certificates
  • 🔐Security
    • Service Tokens
    • Ingestion API Keys
  • ☁️SaaS
    • User Management
  • Reference
    • StackState Query Language (STQL)
    • Chart units
Powered by GitBook
LogoLogo

Legal notices

  • Privacy
  • Cookies
  • Responsible disclosure
  • SOC 2/SOC 3
On this page
  • Before you start
  • Install StackState
  • Create project
  • Generate values.yaml
  • Create openshift-values.yaml
  • Deploy StackState with Helm
  • Access the StackState UI
  • Manually create SecurityContextConfiguration objects
  • See also
  1. Self-hosted setup
  2. Install StackState
  3. Kubernetes / OpenShift

OpenShift install

StackState Self-hosted

PreviousKubernetes installNextRequired Permissions

Last updated 11 months ago

Before you start

Extra notes for installing on:

  • OpenShift clusters with limited permissions: Read the .

  • Kubernetes: Refer to the .

Before you start the installation of StackState:

  • Check that your OpenShift environment meets the

  • Request access credentials to pull the StackState Docker images from .

  • Ensure you have the OpenShift command line tools installed (oc)

  • Add the StackState helm repository to the local helm client:

helm repo add stackstate https://helm.stackstate.io
helm repo update

Install StackState

For environments without internet access, also known as air-gapped environments, first follow .

Also make sure to follow the air-gapped instalaltion instructions whenever those are present for a step.

Create project

Start by creating the project where you want to install StackState. In our walkthrough we will use the namespace stackstate:

oc new-project stackstate

The project name is used in helm and kubectl commands as the namespace name in the --namespace flag

Generate values.yaml

The values.yaml file is required to deploy StackState with Helm. It contains your StackState license key, StackState Receiver API key and other important information.

Before you continue: Make sure you have the latest version of the Helm charts with helm repo update.

The StackState values.yaml file can be generated by running a separate Helm Chart, the stackstate/stackstate-values chart. A sample command line is:

> helm template \
  --set license='<your license>' \
  --set baseUrl='<stackstate-base-url>' \
  --set pullSecret.username='<your-registry-username>' \
  --set pullSecret.password='<your-registry-password>' \
  sts-values \
  stackstate/stackstate-values > values.yaml

This command will generate a values.yaml file which contains the necessary configuration for installing the StackState Helm Chart.

The StackState administrator passwords will be autogenerated by the above command and are output as comments in the generated values.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 values that can be passed to this chart are:

Configuration
Value
Description

Receiver API Key

receiverApiKey

The API key used by StackState to receive data from agents. This is a secret key that should be kept private. If you omit this, a random key will be generated for you.

Base URL

baseUrl

The <STACKSTATE_BASE_URL>. The external URL for StackState that users and agents will use to connect. For example https://stackstate.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 StackState to pull images from quay.io/stackstate repositories. For air-gapped environments these need to be the username and password for the local docker registry.

License key

license

The StackState 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 StackState 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 StackState'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 StackState 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 StackState images are hosted.

Pull Secret Password

pullSecret.password

The password used to pull images from the Docker registry where the StackState images are hosted.

Store the generated values.yaml file somewhere safe. You can reuse this file for upgrades, which will save time and (more importantly) will ensure that StackState continues to use the same API key. This is desirable as it means Agents and other data providers for StackState won't need to be updated.

Create openshift-values.yaml

Because OpenShift has stricter security model than plain Kubernetes, all of the standard security contexts in the deployment need to be disabled.

Create a Helm values file openshift-values.yaml with the following content and store it next to the generated values.yaml file. This contains the values that are needed for an OpenShift deployment.

elasticsearch:
  prometheus-elasticsearch-exporter:
    podSecurityContext: ""
  sysctlInitContainer:
    enabled: false
scc:
  enabled: true

Deploy StackState with Helm

The recommended deployment of StackState is a production ready, high availability setup with many services running redundantly. If required, it's also possible to run StackState in a non-redundant setup, where each service has only a single replica. This setup is only recommended for a test environment.

For air-gapped environments follow the instructions for the air-gapped installations.

To deploy StackState in a high availability setup on OpenShift:

  1. Before you deploy:

  2. Deploy the latest StackState version to the stackstate namespace with the following command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values values.yaml \
  --values openshift-values.yaml \
stackstate \
stackstate/stackstate-k8s

To deploy StackState in a non-high availability setup on OpenShift:

  1. Before you deploy:

  2. Deploy the latest StackState version to the stackstate namespace with the following command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values local-docker-registry.yaml \
  --values values.yaml \
  --values nonha_values.yaml \
  --values openshift-values.yaml \
stackstate \
stackstate/stackstate-k8s

To deploy StackState in a high availability setup on OpenShift:

  1. Before you deploy:

  2. Deploy the latest StackState version to the stackstate namespace with the following command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values local-docker-registry.yaml \
  --values values.yaml \
  --values openshift-values.yaml \
stackstate \
stackstate/stackstate-k8s

To deploy StackState in a non-high availability setup on OpenShift:

  1. Before you deploy:

  2. Deploy the latest StackState version to the stackstate namespace with the following command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values values.yaml \
  --values nonha_values.yaml \
  --values openshift-values.yaml \
stackstate \
stackstate/stackstate-k8s

After the install, the StackState release should be listed in the StackState namespace and all pods should be running:

# Check the release is listed
helm list --namespace stackstate

# Check pods are running
# It may take some time for all pods to be installed or available
kubectl get pods --namespace stackstate

Access the StackState UI

After StackState has been deployed, you can check if all pods are up and running:

kubectl get pods --namespace stackstate

When all pods are up, you can enable a port-forward:

kubectl port-forward service/stackstate-router 8080:8080 --namespace stackstate

StackState will now be available in your browser at https://localhost:8080. Log in with the username admin and the default password provided in the values.yaml file.

Next steps are

Manually create SecurityContextConfiguration objects

If you can't use an administrator account to install StackState on OpenShift, ask your administrator to apply the below SecurityContextConfiguration objects.

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: {{ template "common.fullname.short" . }}-{{ .Release.Namespace }}
  labels:
    {{- include "common.labels.standard" . | nindent 4 }}
  annotations:
    helm.sh/hook: pre-install
    stackstate.io/note: "Ignored by helm uninstall, has to be deleted manually"
fsGroup:
  type: RunAsAny
groups:
- system:serviceaccounts:{{ .Release.Namespace }}
runAsUser:
  type: RunAsAny
seLinuxContext:
  type: MustRunAs
supplementalGroups:
  type: RunAsAny
volumes:
- configMap
- downwardAPI
- emptyDir
- ephemeral
- persistentVolumeClaim
- projected
- secret
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegeEscalation: true
allowPrivilegedContainer: false
readOnlyRootFilesystem: false

See also

(Optionally) if you want to deploy a small profile setup. Add the --values small_values.yaml flag to the command below.

(Optionally) if you want to deploy a small profile setup. Add the --values small_values.yaml flag to the command below.

Give your .

For other configuration and management options, refer to the Kubernetes documentation -

🚀
Create a small_values.yaml
Create nonha_values.yaml
Create a small_values.yaml
Create nonha_values.yaml
Expose StackState outside of the cluster
Start monitoring your Kubernetes clusters
co-workers access
Create a nonha_values.yaml file
Create a small_values.yaml file
manage a StackState Kubernetes installation
required permissions
Kubernetes installation instructions
requirements
StackState support
these extra instructions
Create the project where StackState will be installed
Generate the values.yaml file
Create the openshift-values.yaml file
Deploy StackState with Helm
Access the StackState UI
Manually create SecurityContextConfiguration objects
Create the project where StackState will be installed
Generate values.yaml
Create openshift-values.yaml
Create the project where StackState will be installed
Generate values.yaml
Create openshift-values.yaml
Create the project where StackState will be installed
Generate values.yaml
Create openshift-values.yaml
Create the project where StackState will be installed
Generate values.yaml
Create openshift-values.yaml