perses-operator

Perses Operator

Overview

The Perses Operator provides Kubernetes native deployment and management of Perses and related resources. The purpose of this project is to simplify and automate the deployment and management of Perses observability dashboards on Kubernetes clusters.

The Perses Operator includes, but is not limited to, the following features:

• Kubernetes Custom Resources: Use Kubernetes custom resources to deploy and manage Perses instances, dashboards, and datasources.

• Dashboard-as-Code: Declaratively manage dashboards and datasources as Kubernetes resources, with automatic synchronization to Perses instances.

• Flexible Storage: Configure SQL database (Deployment) or file-based storage with PVC (StatefulSet) or emptyDir from a native Kubernetes resource.

• TLS and Authentication: Configure server TLS, client mTLS, and datasource proxy TLS. Support for BasicAuth, OAuth, and native Kubernetes authentication.

• Multi-Instance Sync: Use instanceSelector on dashboards and datasources to target specific Perses instances, with namespace-to-project mapping for isolation.

• Observability: Built-in Prometheus metrics and alerting rules compatible with Prometheus Operator.

For an introduction to the Perses Operator, see the getting started guide. For detailed usage documentation, see the user guide and the API Reference.

Project Status

The operator is under active development. Please refer to the Custom Resource Definition (CRD) version for the current API status:

• perses.dev/v1alpha2: unstable CRDs and API, changes can happen frequently. We encourage usage for testing and development, but suggest caution in mission-critical environments.

Custom Resource Definitions (CRDs)

A core feature of the Perses Operator is to watch the Kubernetes API server for changes to specific objects and ensure that the desired Perses deployments and configurations match. The Operator acts on the following Custom Resource Definitions (CRDs):

• Perses, which defines a desired Perses server deployment. The operator manages the underlying Deployment or StatefulSet, Service, and ConfigMap based on the spec.

• PersesDashboard, which declaratively specifies a dashboard to be synced to Perses instances. Kubernetes namespaces map to Perses projects.

• PersesDatasource, which declaratively specifies a project-scoped datasource to be synced to matching Perses instances. The datasource's namespace maps to a Perses project.

• PersesGlobalDatasource, which declaratively specifies a cluster-scoped datasource shared across all Perses projects.

The Perses Operator automatically detects changes in the Kubernetes API server to any of the above objects, and ensures that the desired state is reconciled.

Getting Started

Prerequisites

You’ll need:

• a Kubernetes cluster to run against. You can use kind or minikube to get a local cluster for testing, or run against a remote cluster. Note: Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).
• kubectl installed and configured to use your cluster.

Running on the cluster

Option 1: Helm Chart

The Perses Operator can be installed using the Helm chart from the Perses Helm repository.

[!NOTE] The Perses Operator requires cert-manager to be installed in the cluster for webhook certificate management.

1. Add the Perses Helm repository:

helm repo add perses https://perses.github.io/helm-charts
helm repo update

1. Install the Perses Operator:

helm install perses-operator perses/perses-operator

For detailed configuration options, see the Perses Operator chart documentation.

[!IMPORTANT] The Perses Operator Helm chart is newly released. If you encounter any issues, please report them in the perses/helm-charts repository.

Option 2: Kustomize

1. Install custom resource definitions:

make install-crds

1. Deploy the operator:

Option A: Using cert-manager:

make install-cert-manager
make deploy

[!IMPORTANT] This will deploy the controller with the default image docker.io/persesdev/perses-operator:v<VERSION>, where VERSION is read from the VERSION file. To use a different image, set the IMG variable:

IMG=<your-image> make deploy

Option B: Using self-signed certificates (for development/testing):

make deploy-local

1. Create a namespace for the resources:

kubectl create namespace perses-dev

1. Install custom resources:

kubectl apply -k config/samples

1. Check the Perses UI:

kubectl -n perses-dev port-forward svc/perses-sample 8080:8080

Uninstall CRDs

To delete the CRDs from the cluster:

make uninstall-crds

Undeploy controller

Undeploy the controller from the cluster:

make undeploy

Documentation

Guides

• User Guide
• Developer Guide
• Testing Guide

Reference

• API Reference
• Metrics

Helm Chart

• Perses Operator Helm Chart

Example Configs

• Kubernetes
• OpenShift
• Using TLS

Maintainers

See MAINTAINERS.

Contributing

We welcome contributions! Please see CONTRIBUTING for guidelines. If you are unsure about what to do and eager to contribute, reach out on the #perses-dev channel on CNCF Slack.

License

Apache License 2.0, see LICENSE.