Skip to content

Latest commit

 

History

History
564 lines (294 loc) · 24.4 KB

api.md

File metadata and controls

564 lines (294 loc) · 24.4 KB

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

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:DatasourceSpec) Datasources is an optional list of datasource definition.
variables Variable array
panels object (keys:string, values:Panel)
layouts Layout array
duration Duration Duration is the default time range to use when getting data to fill the dashboard 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
refreshInterval Duration RefreshInterval is the default refresh interval to use when landing on the dashboard 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

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.
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 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: {}
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: {}

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

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