API Reference
Packages#
perses.dev/v1alpha2#
Package v1alpha2 contains API Schema definitions for the v1alpha2 API group
Resource Types#
BasicAuth#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type SecretSourceType | type specifies the source type for secret data (secret, configmap, or file) | Enum: [secret configmap file] Required: {} | |
name string | name is the name of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
namespace string | namespace is the namespace of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
username string | username is the username credential for basic authentication | MinLength: 1 Required: {} | |
passwordPath string | passwordPath specifies the key name within the secret/configmap or filesystem path (depending on SecretSource.Type) where the password is stored | MinLength: 1 Required: {} |
Certificate#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type SecretSourceType | type specifies the source type for secret data (secret, configmap, or file) | Enum: [secret configmap file] Required: {} | |
name string | name is the name of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
namespace string | namespace is the namespace of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
certPath string | certPath specifies the key name within the secret/configmap or filesystem path (depending on SecretSource.Type) where the certificate is stored | MinLength: 1 Required: {} | |
privateKeyPath string | privateKeyPath specifies the key name within the secret/configmap or filesystem path (depending on SecretSource.Type) where the private key is stored Required for client certificates (UserCert), optional for CA certificates (CaCert) | Optional: {} |
Client#
Client defines how the client should authenticate
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
basicAuth BasicAuth | basicAuth provides username/password authentication configuration for the Perses client | Optional: {} | |
oauth OAuth | oauth provides OAuth 2.0 authentication configuration for the Perses client | Optional: {} | |
tls TLS | tls provides TLS/SSL configuration for secure connections to Perses | Optional: {} | |
kubernetesAuth KubernetesAuth | kubernetesAuth enables Kubernetes native authentication for the Perses client | Optional: {} |
Dashboard#
Dashboard represents the Perses dashboard configuration including display settings, datasources, variables, panels, layouts, and time ranges.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
display Display | |||
datasources object (keys:string, values:Spec) | Datasources is an optional list of datasource definition. | ||
variables Variable array | |||
annotations AnnotationSpec array | |||
panels object (keys:string, values:Panel) | |||
layouts Layout array | |||
duration DurationString | Duration is the default time range to use when getting data to fill the dashboard | ||
refreshInterval DurationString | RefreshInterval is the default refresh interval to use when landing on the dashboard | ||
timezone string | Timezone is the dashboard level timezone | ||
links Link array | Links is an optional list of links to display at the dashboard level |
Datasource#
Datasource represents the Perses datasource configuration including display metadata, default flag, and plugin-specific settings.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
display Display | |||
default boolean | |||
plugin Plugin | Plugin will contain the datasource configuration. The data typed is available in Cue. |
DatasourceSpec#
DatasourceSpec defines the desired state of a Perses datasource
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
config Datasource | config specifies the Perses datasource configuration | Required: {} | |
client Client | client specifies authentication and TLS configuration for the datasource | Optional: {} | |
instanceSelector LabelSelector | instanceSelector selects Perses instances where this datasource will be created | Optional: {} |
KubernetesAuth#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enable boolean | enable determines whether Kubernetes authentication is enabled for the Perses client | Optional: {} |
Metadata#
Metadata to add to deployed pods
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
labels object (keys:string, values:string) | labels are key/value pairs attached to pods | Optional: {} | |
annotations object (keys:string, values:string) | annotations are key/value pairs attached to pods for non-identifying metadata | Optional: {} |
OAuth#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type SecretSourceType | type specifies the source type for secret data (secret, configmap, or file) | Enum: [secret configmap file] Required: {} | |
name string | name is the name of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
namespace string | namespace is the namespace of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
clientIDPath string | clientIDPath specifies the key name within the secret/configmap or filesystem path (depending on SecretSource.Type) where the OAuth client ID is stored | Optional: {} | |
clientSecretPath string | clientSecretPath specifies the key name within the secret/configmap or filesystem path (depending on SecretSource.Type) where the OAuth client secret is stored | Optional: {} | |
tokenURL string | tokenURL is the OAuth 2.0 provider's token endpoint URL This is a constant specific to each OAuth provider | MinLength: 1 Required: {} | |
scopes string array | scopes specifies optional requested permissions for the OAuth token | Optional: {} | |
endpointParams object (keys:string, values:string array) | endpointParams specifies additional parameters to include in requests to the token endpoint | Optional: {} | |
authStyle integer | authStyle specifies how the endpoint wants the client ID and client secret sent The zero value means to auto-detect | Optional: {} |
Perses#
Perses is the Schema for the perses API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | perses.dev/v1alpha2 | ||
kind string | Perses | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec PersesSpec | spec is the desired state of the Perses resource | Optional: {} | |
status PersesStatus | status is the observed state of the Perses resource | Optional: {} |
PersesConfig#
PersesConfig represents the Perses server configuration including API, security, database, provisioning, and plugin settings.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
api_prefix string | Use it in case you want to prefix the API path. This can be useful if you are running Perses behind a reverse proxy. By default, the API is served with the path /api. With this config, it will be served with the path <api_prefix>/api Example: "/perses" | ||
security Security | Security contains any configuration that changes the API behavior like the endpoints exposed or if the permissions are activated. | ||
database Database | Database contains the different configuration depending on the database you want to use | ||
schemas Schemas | Schemas contain the configuration to get access to the CUE schemas DEPRECATED. Please remove it from your config. | ||
dashboard DashboardConfig | Dashboard contains the configuration for the dashboard feature. | ||
provisioning ProvisioningConfig | Provisioning contains the provisioning config that can be used if you want to provide default resources. | ||
datasource DatasourceConfig | Datasource contains the configuration for the datasource. | ||
variable VariableConfig | Variable contains the configuration for the variable. | ||
ephemeral_dashboards_cleanup_interval Duration | EphemeralDashboardsCleanupInterval is the interval at which the ephemeral dashboards are cleaned up DEPRECATED. Please use the config EphemeralDashboard instead. | Format: duration Pattern: ^(([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?$ Type: string | |
ephemeral_dashboard EphemeralDashboard | EphemeralDashboard contains the config about the ephemeral dashboard feature | ||
frontend Frontend | Frontend contains any config that will be used by the frontend itself. | ||
plugin Plugin | Plugin contains the config for runtime plugins. | ||
search Search | Search contains the config for the search engine and the index in memory. |
PersesDashboard#
PersesDashboard is the Schema for the persesdashboards API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | perses.dev/v1alpha2 | ||
kind string | PersesDashboard | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec PersesDashboardSpec | spec is the desired state of the PersesDashboard resource | Required: {} | |
status PersesDashboardStatus | status is the observed state of the PersesDashboard resource | Optional: {} |
PersesDashboardSpec#
PersesDashboardSpec defines the desired state of PersesDashboard
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
config Dashboard | config specifies the Perses dashboard configuration | Required: {} | |
instanceSelector LabelSelector | instanceSelector selects Perses instances where this dashboard will be created | Optional: {} |
PersesDashboardStatus#
PersesDashboardStatus defines the observed state of PersesDashboard
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | conditions represent the latest observations of the PersesDashboard resource state | Optional: {} |
PersesDatasource#
PersesDatasource is the Schema for the PersesDatasources API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | perses.dev/v1alpha2 | ||
kind string | PersesDatasource | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec DatasourceSpec | spec is the desired state of the PersesDatasource resource | Required: {} | |
status PersesDatasourceStatus | status is the observed state of the PersesDatasource resource | Optional: {} |
PersesDatasourceStatus#
PersesDatasourceStatus defines the observed state of PersesDatasource
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | conditions represent the latest observations of the PersesDatasource resource state | Optional: {} |
PersesGlobalDatasource#
PersesGlobalDatasource is the Schema for the PersesGlobalDatasources API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | perses.dev/v1alpha2 | ||
kind string | PersesGlobalDatasource | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec DatasourceSpec | spec is the desired state of the PersesGlobalDatasource resource | Required: {} | |
status PersesGlobalDatasourceStatus | status is the observed state of the PersesGlobalDatasource resource | Optional: {} |
PersesGlobalDatasourceStatus#
PersesGlobalDatasourceStatus defines the observed state of PersesGlobalDatasource
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | conditions represent the latest observations of the PersesGlobalDatasource resource state | Optional: {} |
PersesService#
PersesService defines service configuration for Perses
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | name is the name of the Kubernetes Service resource If not specified, a default name will be generated | Optional: {} | |
annotations object (keys:string, values:string) | annotations are key/value pairs attached to the Service for non-identifying metadata | Optional: {} |
PersesSpec#
PersesSpec defines the desired state of Perses
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata Metadata | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
client Client | client specifies the Perses client configuration | Optional: {} | |
config PersesConfig | config specifies the Perses server configuration | Optional: {} | |
args string array | args are extra command-line arguments to pass to the Perses server | Optional: {} | |
containerPort integer | containerPort is the port on which the Perses server listens for HTTP requests | Maximum: 65535 Minimum: 1 Optional: {} | |
replicas integer | replicas is the number of desired pod replicas for the Perses deployment | Optional: {} | |
resources ResourceRequirements | resources defines the compute resources configured for the container | Optional: {} | |
nodeSelector object (keys:string, values:string) | nodeSelector constrains pods to nodes with matching labels | Optional: {} | |
tolerations Toleration array | tolerations allow pods to schedule onto nodes with matching taints | Optional: {} | |
affinity Affinity | affinity specifies the pod's scheduling constraints | Optional: {} | |
priorityClassName string | priorityClassName assigns the pods to a PriorityClass, influencing scheduling and preemption | MinLength: 1 Optional: {} | |
image string | image specifies the container image that should be used for the Perses deployment | Optional: {} | |
service PersesService | service specifies the service configuration for the Perses instance | Optional: {} | |
livenessProbe Probe | livenessProbe specifies the liveness probe configuration for the Perses container | Optional: {} | |
readinessProbe Probe | readinessProbe specifies the readiness probe configuration for the Perses container | Optional: {} | |
tls TLS | tls specifies the TLS configuration for the Perses instance | Optional: {} | |
storage StorageConfiguration | storage configuration used by the StatefulSet | Optional: {} | |
serviceAccountName string | serviceAccountName is the name of the ServiceAccount to use for the Perses deployment or statefulset | Optional: {} | |
podSecurityContext PodSecurityContext | podSecurityContext holds pod-level security attributes and common container settings If not specified, defaults to fsGroup: 65534 to ensure proper volume permissions for the nobody user | Optional: {} | |
containerSecurityContext SecurityContext | containerSecurityContext holds security attributes for the Perses container If not specified, defaults to runAsUser: 65534 (nobody) and drops all capabilities | Optional: {} | |
logLevel string | logLevel defines the log level for Perses | Enum: [panic fatal error warning info debug trace] Optional: {} | |
logMethodTrace boolean | logMethodTrace when true, includes the calling method as a field in the log It can be useful to see immediately where the log comes from | Optional: {} | |
provisioning Provisioning | provisioning configuration for provisioning secrets | Optional: {} | |
volumes Volume array | volumes allows configuration of additional volumes on the Deployment or StatefulSet definitions. Volumes specified here will be appended to other operator-managed volumes. | MaxItems: 20 Optional: {} | |
volumeMounts VolumeMount array | volumeMounts allows configuration of additional VolumeMounts on the Deployment or StatefulSet definitions. VolumeMounts specified here will be appended to other operator-managed volume mounts. | MaxItems: 20 Optional: {} | |
env EnvVar array | env allows setting environment variables on the Perses container using the standard Kubernetes EnvVar shape: each entry has a name plus either a literal value or a valueFrom source (secretKeyRef, configMapKeyRef, fieldRef, resourceFieldRef). Variables are merged on top of the operator-generated config file at startup using the PERSES_ env prefix (e.g. PERSES_SECURITY_AUTHENTICATION_PROVIDERS_OIDC_0_CLIENT_ID). Environment variables always override values from the config file. corev1.EnvVar is the canonical Kubernetes env-var type | MaxItems: 50 Optional: {} | |
envFrom EnvFromSource array | envFrom allows bulk-populating environment variables from Kubernetes Secrets or ConfigMaps. All keys in the referenced object become environment variable names. Combined with the PERSES_ prefix convention, this allows overriding multiple config values from a single Secret. corev1.EnvFromSource is the canonical Kubernetes envFrom type | MaxItems: 50 Optional: {} |
PersesStatus#
PersesStatus defines the observed state of Perses
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | conditions represent the latest observations of the Perses resource state | Optional: {} | |
provisioning SecretVersion array | provisioning contains the versions of provisioning secrets currently in use | Optional: {} |
Provisioning#
Provisioning configuration for provisioning secrets
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
secretRefs ProvisioningSecret array | secretRefs is a list of references to Kubernetes secrets used for provisioning sensitive data. | Optional: {} |
ProvisioningSecret#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
LocalObjectReference LocalObjectReference | The name of the secret in the pod's namespace to select from. | ||
key string | The key of the secret to select from. Must be a valid secret key. | ||
optional boolean | Specify whether the Secret or its key must be defined | Optional: {} |
SecretSource#
SecretSource configuration for a perses secret source
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type SecretSourceType | type specifies the source type for secret data (secret, configmap, or file) | Enum: [secret configmap file] Required: {} | |
name string | name is the name of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} | |
namespace string | namespace is the namespace of the Kubernetes Secret or ConfigMap resource Required when Type is "secret" or "configmap", ignored when Type is "file" | MinLength: 1 Optional: {} |
SecretSourceType#
Underlying type: string
SecretSourceType types of secret sources in k8s
Appears in:
| Field | Description |
|---|---|
secret | |
configmap | |
file |
SecretVersion#
SecretVersion represents a secret version
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | name is the name of the provisioning secret | MinLength: 1 Required: {} | |
version string | version is the resource version of the provisioning secret | MinLength: 1 Required: {} |
StorageConfiguration#
StorageConfiguration is the configuration used to create and reconcile PVCs
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
emptyDir EmptyDirVolumeSource | emptyDir to use for ephemeral storage. When set, data will be lost when the pod is deleted or restarted. Mutually exclusive with PersistentVolumeClaimTemplate. | Optional: {} | |
pvcTemplate PersistentVolumeClaimSpec | pvcTemplate is the template for PVCs that will be created. Mutually exclusive with EmptyDir. | Optional: {} |
TLS#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enable boolean | enable determines whether TLS is enabled for connections to Perses | Optional: {} | |
caCert Certificate | caCert specifies the CA certificate to verify the Perses server's certificate | Optional: {} | |
userCert Certificate | userCert specifies the client certificate and key for mutual TLS (mTLS) authentication | Optional: {} | |
insecureSkipVerify boolean | insecureSkipVerify determines whether to skip verification of the Perses server's certificate Setting this to true is insecure and should only be used for testing | Optional: {} |

