API Reference

Packages#

perses.dev/v1alpha2

perses.dev/v1alpha2#

Package v1alpha2 contains API Schema definitions for the v1alpha2 API group

Resource Types#

Perses
PersesDashboard
PersesDatasource
PersesGlobalDatasource

BasicAuth#

Appears in:

Client

Field	Description	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	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#

Appears in:

DatasourceSpec
PersesSpec

Field	Description	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:

PersesDashboardSpec

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:

DatasourceSpec

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:

PersesDatasource
PersesGlobalDatasource

Field	Description	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:

Client

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:

PersesSpec

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:

Client

Field	Description	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	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:

PersesSpec

Field	Description	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.

PersesDashboard#

PersesDashboard is the Schema for the persesdashboards API

Field	Description	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:

PersesDashboard

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:

PersesDashboard

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	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:

PersesDatasource

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	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:

PersesGlobalDatasource

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:

PersesSpec

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:

Perses

Field	Description	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: {}
`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: {}
`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: {}

PersesStatus#

PersesStatus defines the observed state of Perses

Appears in:

Perses

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:

PersesSpec

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:

Provisioning

Field	Description	Validation
`name` string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names	Optional: {}
`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:

BasicAuth
Certificate
OAuth

Field	Description	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:

BasicAuth
Certificate
OAuth
SecretSource

Field	Description
`secret`
`configmap`
`file`

SecretVersion#

SecretVersion represents a secret version

Appears in:

PersesStatus

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:

PersesSpec

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:

Client
PersesSpec

Field	Description	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: {}