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.

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.

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.

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.

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

1. Add the Perses Helm repository:

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

2. Install the Perses Operator:

helm install perses-operator perses/perses-operator

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

1. Install custom resource definitions:

make install-crds

2. Deploy the operator:

Option A: Using cert-manager:

make install-cert-manager
make deploy

IMG=<your-image> make deploy

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

make deploy-local

3. Create a namespace for the resources:

kubectl create namespace perses-dev

4. Install custom resources:

kubectl apply -k config/samples

5. Check the Perses UI:

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

To delete the CRDs from the cluster:

make uninstall-crds

Undeploy the controller from the cluster:

make undeploy

• User Guide
• Developer Guide
• Testing Guide

• API Reference
• Metrics

• Perses Operator Helm Chart

• Kubernetes
• OpenShift
• Using TLS

See MAINTAINERS.

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.

Apache License 2.0, see LICENSE.