PersesPerses

Perses Helm Chart Upgrade Guide

Overview#

This guide provides instructions for upgrading Perses Helm chart releases, particularly when dealing with breaking changes between versions.

We try as much as possible to avoid breaking changes, but sometimes it's necessary to introduce them. If you are upgrading from a version to another that contains breaking changes, you will need to follow the version-specific steps outlined below.

Upgrade Types#

Patch Upgrades#

For patch version upgrades (e.g., 0.8.0 → 0.8.1), you can typically perform a standard Helm upgrade without special considerations:

helm upgrade my-release perses/perses

Major/Minor Upgrades with Breaking Changes#

For upgrades that introduce breaking changes, follow the version-specific migration guides below.

Breaking Changes by Version#

Upgrading to 0.24.0#

This version targets Perses v0.55.0, which contains several breaking changes, mostly security fixes. Read the Perses v0.55.0 upgrade guide before upgrading. The changes most relevant to the chart are listed below.

Encryption key is required when authentication is enabled#

When config.security.enable_auth is true, Perses no longer starts without an encryption key. Provide exactly one of the following:

  • config.security.encryption_key_file: path to a file containing the key, e.g. mounted from a Kubernetes Secret (recommended).
  • PERSES_SECURITY_ENCRYPTION_KEY set through envVars or the secret block.
  • config.security.encryption_key: inline key. It is stored in plain text in the ConfigMap, so avoid it in production.

The key must be exactly 32 bytes, without a trailing newline.

config:
  security:
    enable_auth: true
    encryption_key_file: /etc/perses/encryption/key
volumes:
  - name: encryption-key
    secret:
      secretName: perses-encryption-key
volumeMounts:
  - name: encryption-key
    mountPath: /etc/perses/encryption
    readOnly: true

Datasource proxy destinations are restricted#

The datasource proxy now refuses loopback, link-local, cloud metadata and Kubernetes API destinations. If a datasource runs on the same host as Perses (e.g. http://localhost:9090), allow it explicitly:

config:
  datasource:
    proxy:
      allowed_networks:
        - "127.0.0.0/8"
        - "::1/128"

Files referenced in secrets must be in an allowed directory#

File references in Perses Secrets and GlobalSecrets (e.g. tlsConfig.caFile, basicAuth.passwordFile) are now rejected by default. List the directories where these files are mounted:

config:
  security:
    secret_file_allowed_directories:
      - /etc/perses/secrets

Important dashboards are grouped#

config.frontend.important_dashboards is now a list of groups. The flat list is deprecated and will be removed in Perses v0.57.0. When set through environment variables, the old format is no longer accepted.

config:
  frontend:
    important_dashboards:
      - title: "Quick links" # optional
        dashboards:
          - project: "perses"
            dashboard: "Demo"

Sidecar security context defaults#

sidecar.securityContext now defaults to a hardened security context (non-root, read-only root filesystem, all capabilities dropped). If your sidecar setup needs to write to the container filesystem, set sidecar.securityContext.readOnlyRootFilesystem: false.

Upgrading to 0.20.0#

This version targets Perses v0.53.0 and includes breaking changes for SQL TLS configuration.

SQL TLS Configuration Field Changes#

Perses v0.53.0 only supports camelCase keys in config.database.sql.tls_config. Legacy snake_case keys now fail during Helm template rendering.

Migration mapping:

  • ca_file -> caFile
  • cert_file -> certFile
  • key_file -> keyFile
  • server_name -> serverName
  • insecure_skip_verify -> insecureSkipVerify
  • min_version -> minVersion (values: TLS10, TLS11, TLS12, TLS13)
  • max_version -> maxVersion (values: TLS10, TLS11, TLS12, TLS13)

Before:

config:
  database:
    sql:
      tls_config:
        ca_file: /etc/perses/tls/ca.crt
        cert_file: /etc/perses/tls/tls.crt
        key_file: /etc/perses/tls/tls.key
        server_name: mysql.internal
        insecure_skip_verify: false
        min_version: TLS12
        max_version: TLS13

After:

config:
  database:
    sql:
      tls_config:
        caFile: /etc/perses/tls/ca.crt
        certFile: /etc/perses/tls/tls.crt
        keyFile: /etc/perses/tls/tls.key
        serverName: mysql.internal
        insecureSkipVerify: false
        minVersion: TLS12
        maxVersion: TLS13

Container User Change in Perses v0.53.0#

Perses switched its container default user from nobody to nonroot. If you use file-based DB storage or existing PVC data, make sure mounted directories are writable by the effective runtime user/group. The chart defaults include persistence.securityContext.fsGroup=2000, but custom security contexts or pre-existing volume permissions may still require manual adjustment.

Upgrading to 0.19.0#

This version introduces a breaking change to the sidecar image configuration.

Configuration Field Changes#

  • The sidecar now uses its own registry field: sidecar.image.registry. Previously, the sidecar image always inherited image.registry.

Before (sidecar registry implicitly inherited from image.registry):

image:
  registry: custom.registry.local
  name: "persesdev/perses"
sidecar:
  enabled: true
  image:
    repository: kiwigrid/k8s-sidecar
    tag: 2.1.2

After (set sidecar.image.registry explicitly to keep the same registry):

image:
  registry: custom.registry.local
  name: "persesdev/perses"
sidecar:
  enabled: true
  image:
    registry: custom.registry.local
    repository: kiwigrid/k8s-sidecar
    tag: 2.1.2

If you rely on image.registry to point the sidecar to a custom registry, add sidecar.image.registry with the same value during upgrade.

Upgrading to 0.18.0#

This version introduces breaking changes to the image section. A field has been added.

Configuration Field Changes#

  • Added image.registry to support CRI-O 1.34

Before:

image:
  name: "persesdev/perses"

After:

image:
  registry: docker.io
  name: "persesdev/perses"

Upgrading to 0.8.0#

This version introduces breaking changes to the config section. Some fields have been renamed and reorganized.

Configuration Field Changes#

Update security Fields:

  • Change readOnly to readonly
  • Change enableAuth to enable_auth

Before:

security:
  readOnly: false
  enableAuth: false

After:

security:
  readonly: false
  enable_auth: false

Move important_dashboards to frontend section:

Before:

important_dashboards:
- name: "My Dashboard"
    url: "https://my-dashboard.com"

After:

frontend:
  important_dashboards:
  - name: "My Dashboard"
    url: "https://my-dashboard.com"

Additional Changes#

  • SQL field is not defined by default anymore
  • File system storage is now the default storage mode

Migration Steps#

  1. Backup your current values:

    helm get values my-release > backup-values.yaml

  2. Update your values file according to the field changes above

  3. Test the upgrade in a non-production environment first

  4. Perform the upgrade:

    helm upgrade my-release perses/perses -f updated-values.yaml

  5. Verify the deployment is working correctly after upgrade

General Upgrade Best Practices#

  1. Always backup your current Helm values and any persistent data before upgrading
  2. Review the changelog for the target version to understand all changes
  3. Test upgrades in a development or staging environment first
  4. Monitor the application after upgrade to ensure everything is functioning correctly
  5. Have a rollback plan ready in case issues arise

Rollback Procedure#

If you encounter issues after upgrading, you can rollback to the previous version:

# List release history
helm history my-release

# Rollback to previous revision
helm rollback my-release

# Or rollback to specific revision
helm rollback my-release <revision-number>
Edit this page