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
  • Overview
  • Create a custom trust store
  • Using an installed JVM
  • Using a Docker JVM
  • Use a custom trust store
  • Retrieve certificate via the browser
  1. Self-hosted setup
  2. Security

Self-signed certificates

StackState Self-hosted

PreviousScopesNextService Tokens

Last updated 10 months ago

Overview

StackState has several points of interaction with external systems. For example, event handlers can call out to webhooks in other systems. With the default configuration, StackState won't be able to communicate with these systems if they're secured with TLS using a self-signed certificate, or a certificate that isn't by default trusted by the JVM.

To mitigate this, StackState allows configuration of a custom trust store.

Create a custom trust store

You need to have the custom TLS certificate available. If you don't have that, you will need to .

Use the keytool tool and the cacerts file included in the JVM (Java Virtual Machine) installation to convert an existing TLS certificate file to the format needed by StackState. You can run this on any machine, regardless of the type of operating system.

If you don't have the JVM installed on your computer, you can also instead.

Using an installed JVM

With the JVM installed on your computer and the certificate saved as a file site.cert, you can create a new trust store by taking the JVM's trust store and adding the extra certificate.

  1. Create a working directory workdir and copy the certificate file site.cert to this directory.

  2. Change directory to the workdir and make a copy of the cacerts file from your Java installation. $JAVA_HOME is an environment variable that contains the location of your Java installation. This is normally set when installing Java.

    cd workdir
    cp $JAVA_HOME/lib/security/cacerts ./custom_cacerts
  3. Run the following keytool command to add the certificate. The required password is changeit. The alias needs to be a unique alias for the certificate, for example the domain name itself without any dots.

    keytool -import -keystore custom_cacerts -alias <a-name-for-the-certificate>  -file site.cert
  4. The custom_cacerts store file will now include the site.cert certificate. You can verify that by searching for the alias in the output of

    keytool -list -keystore custom_cacerts

Using a Docker JVM

If you don't have JVM installed on your computer, you can use a JVM Docker image. The certificate should be retrieved and saved as a file site.cert.

  1. Create a working directory workdir and copy the certificate file site.cert to this directory.

  2. Start the Java Docker container with the workdir mounted as a volume so it can be accessed:

    docker run -it -v `pwd`/workdir:/workdir  adoptopenjdk:11 bash
  3. Change directory to the workdir and make a copy of the cacerts file:

    cd /workdir
    cp $JAVA_HOME/lib/security/cacerts ./custom_cacerts
  4. Run the following keytool command to add the certificate. The required password is changeit. The alias needs to be a unique alias for the certificate, for example the domain name itself without any dots.

    keytool -import -keystore custom_cacerts -alias <a-name-for-the-certificate>  -file site.cert
  5. The custom_cacerts store file will now include the site.cert certificate. You can verify that by searching for the alias in the output of

     keytool -list -keystore custom_cacerts

Use a custom trust store

The trust store and the password can be specified as values. The trust store can only be specified from the helm command line as it's a file. The password value is specified in the same way in the example, but it can also be provided via a values.yaml file.

helm upgrade \
  --install \
  --namespace stackstate \
  --values values.yaml \
  --set-file 'stackstate.java.trustStore'=custom_cacerts \
  --set 'stackstate.java.trustStorePassword'=changeit \
stackstate \
stackstate/stackstate-k8s

Note:

  • The first run of the helm upgrade command will result in pods restarting, which may cause a short interruption of availability.

  • Include these arguments on every helm upgrade run.

  • The password and trust store are stored as a Kubernetes secret.

Base64 encoded trust stores

If needed, the Java trust store can also be configured by passing Base64 encoded strings into Helm values.

To use a base64 encoded trust store, run the following helm upgrade command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values values.yaml \
  --set 'stackstate.java.trustStoreBase64Encoded'=$(cat custom_cacerts | base64 -w0) \
  --set 'stackstate.java.trustStorePassword'=changeit \
stackstate \
stackstate/stackstate-k8s

To use a base64 encoded trust store, run the following helm upgrade command:

helm upgrade \
  --install \
  --namespace stackstate \
  --values values.yaml \
  --set 'stackstate.java.trustStoreBase64Encoded'=$(cat custom_cacerts | base64) \
  --set 'stackstate.java.trustStorePassword'=changeit \
stackstate \
stackstate/stackstate-k8s

Retrieve certificate via the browser

The certificate can be directly downloaded from the Chrome browser. The steps involved may vary slightly depending on the version you are using:

  1. Navigate to the URL you need the certificate from.

  2. Click the padlock icon in the location bar.

  3. Click on Certificate.

  4. Select Details.

  5. Select Export.

  6. Save using the default export file type (Base64 ASCII encoded).

🚀
retrieve it via the browser
use a JVM Docker image