Developer Guide

This guide covers the development workflow for the Perses Operator. For general usage and deployment, see the README.

Prerequisites#

• A Kubernetes cluster — use kind or minikube for local development
• kubectl configured for your cluster
• Go

How It Works#

This project follows the Kubernetes Operator pattern using Controllers that reconcile resources until the desired state is reached.

Each Perses CR instance manages the following resources:

• A ConfigMap holding the Perses server configuration
• A Deployment (SQL storage) or StatefulSet (file-based storage) running the Perses server
• A Service for in-cluster API access

Dashboards and datasources (PersesDashboard, PersesDatasource, PersesGlobalDatasource) are synced to matching Perses instances via the Perses API.

More information can be found via the Kubebuilder Documentation.

Running Locally#

Run the controller on your host machine (outside the cluster). This is the fastest iteration loop for development.

1. Install CRDs into the cluster:

make install-crds

2. Run the controller:

make run

make run ARGS="--perses-default-base-image=docker.io/persesdev/perses:latest"

3. In another terminal, create a namespace and apply sample resources:

kubectl create namespace perses-dev
kubectl apply -k config/samples

4. Access the Perses UI:

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

Deploying to a Cluster#

To test with the operator running inside the cluster, build and deploy a development image. The operator requires TLS certificates for the conversion webhook — choose one of the options below. Make sure the image is pushed to a registry accessible from the cluster.

For local kind clusters, use the e2e targets which build the image and load it directly into kind without pushing to a registry:

make e2e-deploy  # Build image, load into kind, and deploy

For remote clusters, build, push to a registry, and deploy:

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

IMG=<some-registry>/perses-operator:tag make test-image-build image-push deploy-local

Using cert-manager (recommended for production-like environments):

make install-cert-manager
IMG=<some-registry>/perses-operator:tag make test-image-build image-push deploy

Undeploy#

make undeploy

Using OLM#

To install the operator via Operator Lifecycle Manager (OLM), see hack/README.md.

Modifying the API Definitions#

After editing the API types under api/, regenerate manifests and code:

make generate          # Regenerate DeepCopy methods
make bundle            # Regenerate CRDs, RBAC, webhooks, and OLM bundle manifests
make generate-api-docs # Regenerate API reference documentation

CI will fail if the generated manifests or API docs are out of date.

Modifying or Adding Metrics#

Metrics are defined in internal/metrics/. After adding or modifying metrics, regenerate the documentation:

make generate-metrics-docs

This updates docs/metrics.md automatically from the metrics code. CI will fail if the generated docs are out of date.

Modifying or Adding Alerting Rules#

Alerting rules are defined in jsonnet/mixin/alerts/alerts.libsonnet. After making changes, regenerate the YAML resources and run the alert tests:

make jsonnet-resources  # Regenerate YAML files in jsonnet/examples/
make test-alerts        # Validate alerting rules with promtool

See Testing for details.

Useful Make Targets#

Run make help to see all available targets with descriptions.

Contributing#

Please read CONTRIBUTING.md for details on the contribution process and commit message conventions.