Skip to content

api.md

Latest commit

 

History

History
786 lines (588 loc) · 68.9 KB

api.md

File metadata and controls

786 lines (588 loc) · 68.9 KB
Raw

API Reference

Packages

k8s.bindplane.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the bindplane v1alpha1 API group.

Resource Types

AgentVersionsConfig

AgentVersionsConfig configures how Bindplane syncs agent versions.

Appears in:

Field Description Default Validation
syncInterval string SyncInterval is the interval at which to sync agent versions (e.g. "2h").
Must be at least 1h. Defaults to 1h.		 1h Optional: {}

AgentsAuthConfig

AgentsAuthConfig configures authentication for agent connections.

Appears in:

Field Description Default Validation
type string Type specifies the authentication method(s) for agent connections.
Can be a single method or a comma-separated list (e.g. "oauth,secretKey").
Valid values: secretKey, oauth. Defaults to secretKey.		 secretKey Optional: {}
secretKey AgentsAuthSecretKeyConfig SecretKey configures the secret key authentication method. Optional: {}

AgentsAuthSecretKeyConfig

AgentsAuthSecretKeyConfig configures secret key authentication for agent connections.

Appears in:

Field Description Default Validation
headers string array Headers is the list of HTTP headers to read the secret key from.
Defaults to ["X-Bindplane-Authorization", "Authorization"].		 Optional: {}

AgentsConfig

AgentsConfig configures how Bindplane communicates with agents.

Appears in:

Field Description Default Validation
auth AgentsAuthConfig Auth configures authentication for agent connections. Optional: {}
heartbeatInterval string HeartbeatInterval is the interval on which to perform a heartbeat over agent connections (e.g. "30s").
Defaults to 30s.		 30s Optional: {}
heartbeatTTL string HeartbeatTTL is the amount of time between agent-initiated heartbeat messages before an agent
connection expires (e.g. "1m"). Must be greater than HeartbeatInterval. Defaults to 1m.		 1m Optional: {}
heartbeatExpiryInterval string HeartbeatExpiryInterval is the interval between reaping expired agents (e.g. "30s").
Defaults to 30s.		 30s Optional: {}
rebalanceInterval string RebalanceInterval is the interval between rebalancing agents (e.g. "1h").
Defaults to 1h.		 1h Optional: {}
rebalancePercentage integer RebalancePercentage is the percentage of agents to rebalance (0–100).
0 disables percentage-based rebalancing. Defaults to 0 (disabled).		 Maximum: 100
Minimum: 0
Optional: {}
rebalanceJitter integer RebalanceJitter is the maximum percentage jitter to add to the rebalance interval (0–100).
Defaults to 0 (no jitter).		 Maximum: 100
Minimum: 0
Optional: {}
maxSimultaneousConnections integer MaxSimultaneousConnections is the maximum number of goroutines that will service
OpAMP connections concurrently. Generally set to the same value as
spec.config.maxConcurrency. Do not modify unless directed by Bindplane support.		 10 Optional: {}

ArgoRolloutSpec

ArgoRolloutSpec configures BlueGreen Argo Rollouts management for the primary Bindplane component. Only BlueGreen is supported in this release.

Appears in:

Field Description Default Validation
enabled boolean Enabled toggles Argo Rollout management for the primary Bindplane component. false Optional: {}
autoPromotionEnabled boolean AutoPromotionEnabled controls whether the new ReplicaSet is automatically
promoted to active once it becomes available. Defaults to true.		 Optional: {}
scaleDownDelaySeconds integer ScaleDownDelaySeconds is how long the previous ReplicaSet remains running
after promotion. When omitted, Argo Rollouts applies its own default (30s).		 Minimum: 0
Optional: {}

AuditTrailConfig

AuditTrailConfig defines audit trail configuration

Appears in:

Field Description Default Validation
retentionDays integer RetentionDays is the number of days to retain audit trail events. 365 Optional: {}

AuthConfig

AuthConfig defines authentication configuration

Appears in:

Field Description Default Validation
type string Type specifies the authentication type. Enum: [system ldap active-directory oidc]
Optional: {}
username string Username for authentication Optional: {}
usernameSecretRef SecretKeySelector UsernameSecretRef references a Kubernetes Secret containing the auth username.
Takes precedence over Username if both are set.		 Optional: {}
password string Password for authentication Optional: {}
passwordSecretRef SecretKeySelector PasswordSecretRef references a Kubernetes Secret containing the auth password.
Takes precedence over Password if both are set.		 Optional: {}
sessionSecret string SessionSecret is a plain-text secret used to sign session cookies. Optional: {}
sessionSecretSecretRef SecretKeySelector SessionSecretSecretRef references a Secret containing the session secret.
Takes precedence over SessionSecret when both are set.		 Optional: {}
apiKey string APIKey is a plain-text API key for programmatic access. Optional: {}
apiKeySecretRef SecretKeySelector APIKeySecretRef references a Secret containing the API key.
Takes precedence over APIKey when both are set.		 Optional: {}
sessionsStrictMode boolean SessionsStrictMode enables strict mode for session cookies. Optional: {}
ldap LDAPConfig LDAP is the configuration for ldap or active-directory auth types. Optional: {}
oidc OIDCConfig OIDC is the configuration for the oidc auth type. Optional: {}

Bindplane

Bindplane is the Schema for the bindplanes API.

Field Description Default Validation
apiVersion string k8s.bindplane.com/v1alpha1
kind string Bindplane
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BindplaneSpec

BindplaneComponentSpec

BindplaneComponentSpec defines the Bindplane component pod specification

Appears in:

Field Description Default Validation
replicas integer Replicas specifies the number of replicas for Bindplane Node deployment 3 Optional: {}
resources ResourceRequirements Resources defines compute resource requests and limits for the Bindplane Node primary container.
If podTemplate.spec.containers[server].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for Bindplane Node Type: object
Optional: {}
disablePodDisruptionBudget boolean DisablePodDisruptionBudget disables the operator-managed PodDisruptionBudget for this component.
When false (default), the operator creates a PDB with minAvailable: 1.		 false Optional: {}
minReadySeconds integer MinReadySeconds is the minimum number of seconds a newly created Node pod must be
ready (passing its readiness probe) before it is considered available. During a
rolling update the next pod is not replaced until this window elapses. When omitted,
the operator defaults this to the pod's termination grace period, giving agents
that were connected to the outgoing pod enough time to reconnect to healthy nodes
(including the new pod) before another pod is taken out of service.		 Minimum: 0
Optional: {}
strategy DeploymentStrategy Strategy defines the rollout strategy for the Bindplane Node Deployment.
When omitted, defaults to RollingUpdate with maxSurge=1 and maxUnavailable=0,
ensuring a replacement pod is running before the old pod is removed.
Mutually exclusive with ArgoRollout.Enabled.		 Optional: {}
argoRollout ArgoRolloutSpec ArgoRollout, when set with Enabled=true, manages the primary Bindplane component
as an Argo Rollouts Rollout (BlueGreen strategy) instead of a standard Deployment.
The argoproj.io/v1alpha1 Rollout CRD and the Argo Rollouts controller must be
installed in the cluster.
When enabled, BindplaneComponentSpec.Strategy is rejected by validation
(mutually exclusive — Rollout strategy is BlueGreen-only here).
RECOMMENDED: also set spec.opamp.enabled=true. BlueGreen promotions cut over
active traffic atomically; routing OpAMP/agent traffic to a dedicated Deployment
prevents agent reconnect storms during promotion.		 Optional: {}
autoscaling NodeAutoscalingSpec Autoscaling configures optional horizontal pod autoscaling for Bindplane Node.
When autoscaling is enabled, spec.bindplane.replicas is ignored and the
HorizontalPodAutoscaler controls the replica count.		 Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for Bindplane Node. When set, the value is used
verbatim as a full OCI reference (e.g. "myregistry.example.com/bindplane-ee:1.99.1" or
"ghcr.io/observiq/bindplane-ee@sha256:..."). When empty, the image is derived from spec.version.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

BindplaneComponents

BindplaneComponents groups the per-component status for all Bindplane components.

Appears in:

Field Description Default Validation
bindplane ComponentStatus Bindplane reports the image and ready replica count for the Bindplane Node deployment. Optional: {}
opamp ComponentStatus OpAMP reports the image and ready replica count for the OpAMP deployment.
Empty when OpAMP is not enabled.		 Optional: {}
jobs ComponentStatus Jobs reports the image and ready replica count for the Bindplane Jobs deployment. Optional: {}
jobsMigrate ComponentStatus JobsMigrate reports the image for which a successful database migration has completed.
The controller uses this to determine whether migration must run before applying
an image change to NATS, Jobs, and Node workloads. ReadyReplicas is not set because
the migration Job is transient.		 Optional: {}
nats ComponentStatus Nats reports the image and ready replica count for the NATS StatefulSet. Optional: {}
transformAgent ComponentStatus TransformAgent reports the image and ready replica count for the Transform Agent deployment. Optional: {}
tsdb ComponentStatus TSDB reports the image and ready replica count for the TSDB (Prometheus) StatefulSet.
Empty when remote TSDB is enabled.		 Optional: {}

BindplaneConfigSpec

BindplaneConfigSpec defines Bindplane's configuration

Appears in:

Field Description Default Validation
license string License is the Bindplane license key MinLength: 1
Optional: {}
licenseSecretRef SecretKeySelector LicenseSecretRef references a Kubernetes Secret containing the Bindplane license key.
Takes precedence over License if both are set.		 Optional: {}
auth AuthConfig Auth configuration for Bindplane Optional: {}
network NetworkConfig Network configuration for Bindplane Optional: {}
store StoreConfig Store configuration for Bindplane
tracing TracingConfig Tracing configuration for Bindplane. When omitted or type empty, tracing is disabled. Optional: {}
metrics MetricsConfig Metrics configuration for Bindplane. When omitted, defaults to prometheus type with interval 60s and endpoint /metrics. Optional: {}
maxConcurrency integer MaxConcurrency is the maximum number of concurrent OpAMP operations.
Generally set to the same value as spec.config.agents.maxSimultaneousConnections.
Do not modify unless directed by Bindplane support.		 Optional: {}
auditTrail AuditTrailConfig AuditTrail configures audit trail retention. When omitted, retentionDays defaults to 365. Optional: {}
tsdb TSDBConfig TSDB configures TLS and remote settings for Bindplane's TSDB integration. Optional: {}
nats NatsConfig Nats configures TLS for the NATS event bus (client and server). Cert-manager only. Optional: {}
eventBus EventBusConfig EventBus configures the event bus (NATS) integration, including health checks. Optional: {}
logging LoggingConfig Logging configures Bindplane log behavior. Optional: {}
agents AgentsConfig Agents configures Bindplane agent connection, heartbeat, rebalance, and authentication options. Optional: {}
agentVersions AgentVersionsConfig AgentVersions configures agent version sync behavior. Optional: {}

BindplaneJobsComponentSpec

BindplaneJobsComponentSpec defines the Bindplane Jobs component pod specification

Appears in:

Field Description Default Validation
resources ResourceRequirements Resources defines compute resource requests and limits for the Bindplane Jobs primary container.
If podTemplate.spec.containers[server].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for Bindplane Jobs
Note: Jobs are restricted to 1 replica and cannot be scaled		 Type: object
Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for Bindplane Jobs. When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

BindplaneJobsMigrateComponentSpec

BindplaneJobsMigrateComponentSpec defines the Bindplane Jobs Migrate component pod specification. Jobs Migrate runs as a Kubernetes batch/v1 Job that performs database migrations at install time and whenever the Bindplane image version changes.

Appears in:

Field Description Default Validation
resources ResourceRequirements Resources defines compute resource requests and limits for the Bindplane Jobs Migrate primary container.
If podTemplate.spec.containers[server].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for the Bindplane Jobs Migrate batch/v1 Job Type: object
Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for Bindplane Jobs Migrate. When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version.
Setting this decouples jobs-migrate from spec.version — ensure the image is compatible with
the bindplane-ee image used by node, jobs, and nats; the operator does not enforce this.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

BindplaneSpec

BindplaneSpec defines the desired state of Bindplane.

Appears in:

Field Description Default Validation
version string Version specifies the default Bindplane release version used to derive container images
for all components. Individual components can override their image via their own image
field (e.g. spec.bindplane.image); those overrides take precedence over this value.
Changing this value triggers a rolling update of every component that does not have an
explicit image override, plus a new database migration Job before downstream workloads
are updated.		 1.99.1 Optional: {}
config BindplaneConfigSpec Config contains Bindplane's configuration (license, auth, network, store, eventBus)
This config is shared by Node, Jobs, and Jobs Migrate
bindplane BindplaneComponentSpec Bindplane configuration and pod specification { } Optional: {}
bindplaneJobs BindplaneJobsComponentSpec Bindplane Jobs pod specification Optional: {}
bindplaneJobsMigrate BindplaneJobsMigrateComponentSpec Bindplane Jobs Migrate pod specification Optional: {}
transformAgent TransformAgentComponentSpec Transform Agent pod specification { } Optional: {}
tsdb TSDBComponentSpec TSDB pod specification Optional: {}
nats NatsComponentSpec NATS pod specification { } Optional: {}
opamp OpAMPComponentSpec OpAMP, when enabled, runs a dedicated Deployment for OpAMP/agent traffic
alongside the primary Node deployment. When nil or disabled (the default),
the primary Node deployment serves both frontend and OpAMP traffic.		 Optional: {}

CertManagerTLSIssuerRef

CertManagerTLSIssuerRef references a cert-manager Issuer or ClusterIssuer. See https://cert-manager.io/docs/concepts/issuer/

Appears in:

Field Description Default Validation
name string Name is the name of the Issuer or ClusterIssuer resource.
kind string Kind is the type of issuer. Either "Issuer" (namespaced) or "ClusterIssuer" (cluster-scoped). Issuer Enum: [Issuer ClusterIssuer]
Optional: {}
group string Group is the API group of the issuer. Defaults to cert-manager.io. cert-manager.io Optional: {}

ComponentStatus

ComponentStatus reports the resolved image and runtime health of a single Bindplane component.

Appears in:

Field Description Default Validation
image string Image is the fully-resolved container image in use by this component. Optional: {}
readyReplicas integer ReadyReplicas is the number of pods currently ready for this component. Optional: {}

EventBusConfig

EventBusConfig configures the Bindplane event bus (NATS) integration.

Appears in:

Field Description Default Validation
health EventBusHealthConfig Health configures the event bus health check endpoints. Optional: {}

EventBusHealthConfig

EventBusHealthConfig configures the Bindplane event bus health check. The health check sends an event over NATS and waits for responses from other pods. Health check failures affect only the status page in the Bindplane web interface; they do not cause pod shutdown or failure.

Appears in:

Field Description Default Validation
requiredHosts integer RequiredHosts is the minimum number of pods that must respond to the health check
event for the event bus to be considered healthy. When omitted, defaults to
floor(total / 2) + 1, where total is the sum of node, NATS, and jobs replicas.
Jobs Migrate is a batch/v1 Job (not a long-running pod) and is excluded from this total.		 Minimum: 1
Optional: {}
interval string Interval is how often the event bus health check is performed (e.g. 15s, 1m).
When omitted, the Bindplane server default is used.		 Optional: {}

LDAPConfig

LDAPConfig defines LDAP and Active Directory authentication configuration

Appears in:

Field Description Default Validation
protocol string Protocol to use when connecting to the LDAP server. One of: ldap|ldaps Optional: {}
server string Server is the LDAP server hostname Optional: {}
port string Port is the LDAP server port Optional: {}
baseDN string BaseDN is the base distinguished name for user searches Optional: {}
bindUser string BindUser is the username used to bind to the LDAP server Optional: {}
bindUserSecretRef SecretKeySelector BindUserSecretRef references a Kubernetes Secret containing the LDAP bind username.
Takes precedence over BindUser if both are set.		 Optional: {}
bindPassword string BindPassword is the password used to bind to the LDAP server Optional: {}
bindPasswordSecretRef SecretKeySelector BindPasswordSecretRef references a Kubernetes Secret containing the LDAP bind password.
Takes precedence over BindPassword if both are set.		 Optional: {}
searchFilter string SearchFilter is the LDAP search filter used to locate users Optional: {}
tls LDAPTLSConfig TLS configures TLS for LDAP using a Secret. The operator mounts the Secret and sets
BINDPLANE_LDAP_TLS_CERT, BINDPLANE_LDAP_TLS_KEY, and BINDPLANE_LDAP_TLS_CA to the
mounted file paths. Omit TLS to disable mutual TLS / custom CA.		 Optional: {}
tlsSkipVerify boolean TLSSkipVerify disables TLS certificate verification Optional: {}

LDAPTLSConfig

LDAPTLSConfig defines TLS for LDAP by referencing a Secret. The Secret is mounted at a fixed path; the operator sets the TLS env vars to the mounted file paths. Users specify only the secret name and key names, not mount paths.

Appears in:

Field Description Default Validation
secretName string SecretName is the name of the Secret containing the TLS certificate, key, and optionally CA.
certKey string CertKey is the key in the Secret for the TLS certificate (for mutual TLS). Optional: {}
keyKey string KeyKey is the key in the Secret for the TLS private key (for mutual TLS). Optional: {}
caKey string CAKey is the key in the Secret for the CA certificate. Omit to use system CAs. Optional: {}

LoggingConfig

LoggingConfig defines user-configurable logging options. The logging output destination is always stdout and is not user-configurable.

Appears in:

Field Description Default Validation
level string Level specifies the log level. One of: debug, info, warn, error. info Enum: [debug info warn error]
Optional: {}

MetricsConfig

MetricsConfig defines metrics configuration

Appears in:

Field Description Default Validation
type string Type specifies the metrics type. One of: otlp, prometheus. prometheus Enum: [otlp prometheus]
Optional: {}
interval string Interval is the interval at which to export metrics (e.g. 60s). Used when Type is otlp. 60s Optional: {}
prometheus MetricsPrometheusConfig Prometheus configures Prometheus metrics when Type is prometheus. Optional: {}
otlp MetricsOTLPConfig OTLP configures OTLP metrics when Type is otlp. Optional: {}

MetricsOTLPConfig

MetricsOTLPConfig defines OTLP metrics configuration

Appears in:

Field Description Default Validation
endpoint string Endpoint is the gRPC endpoint to send metrics to (e.g. localhost:4317). Optional: {}
insecure boolean Insecure disables TLS verification for the OTLP connection. Optional: {}

MetricsPrometheusConfig

MetricsPrometheusConfig defines Prometheus metrics configuration

Appears in:

Field Description Default Validation
endpoint string Endpoint is the HTTP path to serve metrics on (e.g. /metrics). /metrics Optional: {}
username string Username is the basic auth username for the metrics endpoint, if any. Optional: {}
password string Password is the basic auth password for the metrics endpoint. Optional: {}
passwordSecretRef SecretKeySelector PasswordSecretRef references a Kubernetes Secret containing the metrics endpoint password.
Takes precedence over Password if both are set.		 Optional: {}

NatsComponentSpec

NatsComponentSpec defines the NATS component pod specification

Appears in:

Field Description Default Validation
replicas integer Replicas specifies the number of replicas for NATS StatefulSet 2 Optional: {}
resources ResourceRequirements Resources defines compute resource requests and limits for the NATS primary container.
If podTemplate.spec.containers[server].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for NATS Type: object
Optional: {}
disablePodDisruptionBudget boolean DisablePodDisruptionBudget disables the operator-managed PodDisruptionBudget for this component.
When false (default), the operator creates a PDB with minAvailable: 1.		 Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for NATS. When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

NatsConfig

NatsConfig configures the NATS event bus (client and server use the same TLS config).

Appears in:

Field Description Default Validation
tls NatsTLSConfig TLS configures mutual TLS for NATS via cert-manager. When set, a single certificate is used for client, cluster, and HTTP ports. Optional: {}

NatsTLSConfig

NatsTLSConfig defines TLS for NATS. Only cert-manager is supported; no secretName.

Appears in:

Field Description Default Validation
certManager CertManagerTLSIssuerRef CertManager references a cert-manager Issuer or ClusterIssuer to issue the NATS certificate (used for client, cluster, and HTTP). Optional: {}
skipVerify boolean SkipVerify disables TLS certificate verification for NATS connections.
Not recommended for production use.		 Optional: {}

NetworkConfig

NetworkConfig defines network configuration

Appears in:

Field Description Default Validation
host string Host specifies the bind address Optional: {}
port string Port specifies the port to listen on Optional: {}
remoteURL string RemoteURL specifies the remote URL for Bindplane.
Defaults to http://-node:3001 (the internal node service URL).
Override this when using ingress, e.g. https://bindplane.my-corp.net		 Optional: {}
webURL string WebURL is the URL used by the client for the web interface. Defaults to RemoteURL when not set. Only set when explicitly configuring. Optional: {}
corsAllowedOrigins string CorsAllowedOrigins is the allowed origin for CORS requests. Only set when explicitly configuring. Optional: {}
tls NetworkTLSConfig TLS configures TLS for the Bindplane server using a Secret. The operator mounts the Secret and sets
BINDPLANE_TLS_CERT, BINDPLANE_TLS_KEY, and optionally BINDPLANE_TLS_CA to the mounted file paths.
Omit or omit secretName/certKey/keyKey to disable server TLS (e.g. when using Ingress to terminate TLS).		 Optional: {}

NetworkTLSConfig

NetworkTLSConfig defines TLS for the Bindplane server by referencing a Secret. The Secret is mounted at a fixed path; the operator sets the TLS env vars to the mounted file paths. Users specify only the secret name and key names, not mount paths. Server-side TLS: set secretName, certKey, and keyKey. Mutual TLS: also set caKey.

Appears in:

Field Description Default Validation
minVersion string MinVersion is the minimum TLS version. One of: 1.2, 1.3. Omit to use server default. Enum: [1.2 1.3]
Optional: {}
secretName string SecretName is the name of the Secret containing the TLS certificate, key, and optionally CA.
certKey string CertKey is the key in the Secret for the TLS certificate (server or mutual TLS). Optional: {}
keyKey string KeyKey is the key in the Secret for the TLS private key (server or mutual TLS). Optional: {}
caKey string CAKey is the key in the Secret for the CA certificate. Set for mutual TLS (client cert verification); generally not used. Optional: {}
skipVerify boolean SkipVerify disables TLS certificate verification. Only set for testing. Optional: {}

NodeAutoscalingSpec

NodeAutoscalingSpec configures horizontal pod autoscaling for Bindplane Node. When enabled, the operator creates a HorizontalPodAutoscaler and the spec.bindplane.replicas field is ignored — the HPA controls replica count.

All fields are optional. Omitted fields use defaults tuned for Bindplane Node's stateful WebSocket (OpAMP) workload.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables the HorizontalPodAutoscaler for Bindplane Node.
When false (the default), static replica counts from spec.bindplane.replicas
are used and no HPA is created.		 false Optional: {}
minReplicas integer MinReplicas is the lower replica bound for the autoscaler. Default: 2. 2 Minimum: 1
Optional: {}
maxReplicas integer MaxReplicas is the upper replica bound for the autoscaler. Default: 10. 10 Minimum: 1
Optional: {}
metrics MetricSpec array Metrics contains the specifications for which metrics to use when calculating
the desired replica count. When omitted, defaults to CPU at 50% target utilization.		 Optional: {}
behavior HorizontalPodAutoscalerBehavior Behavior configures the scaling behavior in both Up and Down directions.
When omitted, the default scaleDown policy enforces slow scale-down
(1 pod per 5 minutes) to prevent agent reconnection storms.		 Optional: {}

OIDCConfig

OIDCConfig defines OpenID Connect authentication configuration

Appears in:

Field Description Default Validation
clientID string ClientID is the OIDC OAuth2 client ID Optional: {}
clientIDSecretRef SecretKeySelector ClientIDSecretRef references a Kubernetes Secret containing the OIDC client ID.
Takes precedence over ClientID if both are set.		 Optional: {}
clientSecret string ClientSecret is the OIDC OAuth2 client secret Optional: {}
clientSecretSecretRef SecretKeySelector ClientSecretSecretRef references a Kubernetes Secret containing the OIDC client secret.
Takes precedence over ClientSecret if both are set.		 Optional: {}
issuer string Issuer is the URL of the OIDC provider Optional: {}
scopes string array Scopes is the list of OAuth2 scopes to request Optional: {}
disableInvitations boolean DisableInvitations disables the invitation flow for OIDC-authenticated users.
When true, users cannot be invited via email and must log in via OIDC directly.		 Optional: {}

OpAMPComponentSpec

OpAMPComponentSpec defines an optional dedicated Bindplane Deployment that serves OpAMP/agent traffic. When enabled, the operator provisions a second Deployment running BINDPLANE_MODE=node alongside the primary Node deployment. Both Deployments share the same Bindplane configuration (license, store, auth, event bus). They differ in resources, replicas, autoscaling, PDB, and OpAMP-specific tuning environment variables.

Use this when you want to scale agent-handling capacity independently from the frontend (UI/API), for example when you have a large fleet of agents but modest UI traffic.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables the dedicated OpAMP deployment. When false (the default),
the primary Node deployment serves both frontend and OpAMP traffic.		 false Optional: {}
replicas integer Replicas specifies the number of replicas for the OpAMP deployment.
Ignored when Autoscaling.Enabled is true.		 3 Optional: {}
resources ResourceRequirements Resources defines compute resource requests and limits for the OpAMP
primary container. If podTemplate.spec.containers[server].resources is
also set, the podTemplate value takes precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for the OpAMP deployment.
Merged on top of operator-managed defaults using the same merge rules as
other component podTemplates.		 Type: object
Optional: {}
disablePodDisruptionBudget boolean DisablePodDisruptionBudget disables the operator-managed PodDisruptionBudget
for the OpAMP deployment. When false (the default), the operator creates
a PDB with minAvailable: 1.		 false Optional: {}
minReadySeconds integer MinReadySeconds is the minimum number of seconds a newly created OpAMP pod
must be ready before it is considered available. When omitted, the operator
defaults this to the pod's termination grace period.		 Minimum: 0
Optional: {}
strategy DeploymentStrategy Strategy defines the rollout strategy for the OpAMP Deployment. When
omitted, defaults to RollingUpdate with maxSurge=1 and maxUnavailable=0.		 Optional: {}
autoscaling NodeAutoscalingSpec Autoscaling configures optional horizontal pod autoscaling for OpAMP.
When enabled, spec.bindplane.opamp.replicas is ignored.		 Optional: {}
maxSimultaneousConnections integer MaxSimultaneousConnections sets BINDPLANE_AGENTS_MAX_SIMULTANEOUS_CONNECTIONS
for the OpAMP deployment only. When unset, falls back to
spec.config.agents.maxSimultaneousConnections which is shared
across all node-mode Deployments. Useful when you want OpAMP pods to handle
a higher concurrency than the frontend pods.		 Minimum: 1
Optional: {}
shutdownGracePeriodTarget string ShutdownGracePeriodTarget sets BINDPLANE_ADVANCED_SERVER_OPAMP_SHUTDOWN_GRACE_PERIOD_TARGET
for the OpAMP deployment. This is a 0-1 fraction (e.g. "0.6") of the OpAMP
shutdown grace period after which the server stops accepting new OpAMP
connections. Only applied when set.		 Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for the OpAMP deployment. When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

PodTemplateSpec

PodTemplateSpec defines pod template specification. This embeds corev1.PodTemplateSpec to allow arbitrary pod spec fields. Note: The operator will merge this with operator-managed fields, ensuring operator-managed fields (like ServiceAccountName, containers, etc.) take precedence.

Appears in:

Field Description Default Validation
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec PodSpec Specification of the desired behavior of the pod.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status		 Optional: {}

PostgresConfig

PostgresConfig defines PostgreSQL store configuration

Appears in:

Field Description Default Validation
host string Host specifies the PostgreSQL host
port string Port specifies the PostgreSQL port Optional: {}
connectTimeout string ConnectTimeout specifies the connection timeout Optional: {}
statementTimeout string StatementTimeout specifies the statement timeout Optional: {}
database string Database specifies the database name Optional: {}
sslmode string SSLMode specifies the PostgreSQL SSL mode. One of: disable, require, verify-ca, verify-full. disable Enum: [disable require verify-ca verify-full]
Optional: {}
tls PostgresTLSConfig TLS configures TLS for PostgreSQL using a Secret. The operator mounts the Secret and sets
BINDPLANE_POSTGRES_SSL_ROOT_CERT, BINDPLANE_POSTGRES_SSL_CERT, and BINDPLANE_POSTGRES_SSL_KEY to the
mounted file paths. Server-side TLS: set secretName and caKey. Mutual TLS: also set certKey and keyKey.		 Optional: {}
username string Username specifies the PostgreSQL username Optional: {}
usernameSecretRef SecretKeySelector UsernameSecretRef references a Kubernetes Secret containing the PostgreSQL username.
Takes precedence over Username if both are set.		 Optional: {}
password string Password specifies the PostgreSQL password Optional: {}
passwordSecretRef SecretKeySelector PasswordSecretRef references a Kubernetes Secret containing the PostgreSQL password.
Takes precedence over Password if both are set.		 Optional: {}
maxConnections integer MaxConnections specifies the maximum number of connections Optional: {}
maxIdleConnections integer MaxIdleConnections specifies the maximum number of idle connections. Optional; no default. Optional: {}
maxLifetime string MaxLifetime specifies the maximum connection lifetime Optional: {}
maxIdleTime string MaxIdleTime specifies the maximum time a connection may remain idle (e.g. 20s, 1m). Optional; no default. Optional: {}
schema string Schema specifies the database schema Optional: {}

PostgresTLSConfig

PostgresTLSConfig defines TLS for PostgreSQL by referencing a Secret. The Secret is mounted at a fixed path; the operator sets the TLS env vars (sslRootCert, sslCert, sslKey) to the mounted file paths. Users specify only the secret name and key names, not mount paths. Server-side TLS: set secretName and caKey. Mutual TLS: set secretName, caKey, certKey, and keyKey.

Appears in:

Field Description Default Validation
secretName string SecretName is the name of the Secret containing the CA and optionally client cert and key.
caKey string CAKey is the key in the Secret for the root CA (maps to sslRootCert). Required for TLS; enables server-side TLS. Optional: {}
certKey string CertKey is the key in the Secret for the client certificate (maps to sslCert). Set with KeyKey for mutual TLS. Optional: {}
keyKey string KeyKey is the key in the Secret for the client private key (maps to sslKey). Set with CertKey for mutual TLS. Optional: {}

ServiceAccountSpec

ServiceAccountSpec defines configuration for an operator-managed ServiceAccount.

Appears in:

Field Description Default Validation
annotations object (keys:string, values:string) Annotations are added to the ServiceAccount's metadata.annotations.
Use this to attach cloud workload identity annotations, e.g. AWS IRSA
(eks.amazonaws.com/role-arn) or GKE Workload Identity (iam.gke.io/gcp-service-account).		 Optional: {}

StorageSpec

StorageSpec defines persistent storage configuration

Appears in:

Field Description Default Validation
volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate defines the template for creating PersistentVolumeClaims
This follows the same structure as StatefulSet volumeClaimTemplates

StoreConfig

StoreConfig defines store configuration

Appears in:

Field Description Default Validation
postgres PostgresConfig Postgres configuration
maxEvents integer MaxEvents is the maximum number of events to merge into a single event. Defaults to 100. 100 Optional: {}
eventMergeWindow string EventMergeWindow is the window during which events are merged (e.g. "100ms"). Defaults to 100ms. 100ms Optional: {}
summaryRollupRetentionDays integer SummaryRollupRetentionDays is the number of days to retain daily rollup data.
0 means indefinite retention (rollups are never deleted). Defaults to 365.		 365 Optional: {}

TSDBComponentSpec

TSDBComponentSpec defines the TSDB component pod specification. By default, this deploys a Prometheus StatefulSet managed by the operator.

Appears in:

Field Description Default Validation
resources ResourceRequirements Resources defines compute resource requests and limits for the TSDB primary container.
If podTemplate.spec.containers[tsdb].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for the TSDB component Type: object
Optional: {}
storage StorageSpec Storage defines the persistent storage configuration for the TSDB component Optional: {}
tls TSDBTLSConfig TLS configures TLS for the TSDB server (StatefulSet). Use either secretName (user-defined Secret)
or certManager (cert-manager Issuer/ClusterIssuer), not both. When set, the TSDB serves remote write over TLS.		 Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for TSDB (Prometheus). When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version
using the ghcr.io/observiq/bindplane-prometheus registry.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

TSDBConfig

TSDBConfig configures Bindplane's TSDB component (default implementation: Prometheus).

Appears in:

Field Description Default Validation
remote TSDBRemoteConfig Remote configures Bindplane to use an externally managed TSDB-compatible backend
(for example, Prometheus, Mimir, or VictoriaMetrics) instead of the operator-managed TSDB StatefulSet.		 Optional: {}
tls TSDBTLSConfig TLS configures TLS for TSDB remote write. Optional: {}

TSDBRemoteConfig

TSDBRemoteConfig defines how Bindplane connects to an externally managed TSDB-compatible backend.

Appears in:

Field Description Default Validation
enable boolean Enable controls whether Bindplane should connect to an external TSDB-compatible backend.
When false, all other fields in this object must be omitted.		 Optional: {}
host string Host is the hostname or IP of the external TSDB-compatible backend.
Required when enable is true.		 Optional: {}
port integer Port is the TCP port of the external TSDB-compatible backend.
Required when enable is true.		 9090 Optional: {}
queryPathPrefix string QueryPathPrefix is an optional prefix path for PromQL APIs (for example, /prometheus). Optional: {}
remoteWrite TSDBRemoteWriteConfig RemoteWrite optionally overrides where Bindplane sends TSDB remote write traffic. Optional: {}

TSDBRemoteWriteConfig

TSDBRemoteWriteConfig defines optional remote write endpoint overrides.

Appears in:

Field Description Default Validation
host string Host is the remote write hostname or IP. Must be set together with port. Optional: {}
port integer Port is the remote write TCP port. Must be set together with host. Optional: {}
endpoint string Endpoint is the remote write HTTP path. /api/v1/write Optional: {}

TSDBTLSConfig

TSDBTLSConfig defines TLS for TSDB remote write. Exactly one of secretName (user-defined Secret) or certManager (cert-manager Issuer/ClusterIssuer) should be set.

Appears in:

Field Description Default Validation
secretName string SecretName is the name of the Secret containing the TLS certificate, key, and optionally CA (user-defined TLS).
Omit when using certManager.		 Optional: {}
certKey string CertKey is the key in the Secret for the TLS certificate. Optional: {}
keyKey string KeyKey is the key in the Secret for the TLS private key. Optional: {}
caKey string CAKey is the key in the Secret for the CA certificate. Optional: {}
certManager CertManagerTLSIssuerRef CertManager references a cert-manager Issuer or ClusterIssuer to issue server and client certs (mTLS).
Mutually exclusive with secretName.		 Optional: {}
skipVerify boolean SkipVerify disables TLS certificate verification for the TSDB remote write client. Only set for testing. Optional: {}

TracingConfig

TracingConfig defines tracing configuration

Appears in:

Field Description Default Validation
type string Type specifies the tracing type. One of: otlp, google. When empty, tracing is disabled. Enum: [otlp google]
Optional: {}
otlp TracingOTLPConfig OTLP configures OTLP tracing when Type is otlp. Optional: {}
samplingRate string SamplingRate is the ratio between 0 and 1 of traces to keep. Omit or 0 to disable sampling. Optional: {}

TracingOTLPConfig

TracingOTLPConfig defines OTLP tracing configuration

Appears in:

Field Description Default Validation
endpoint string Endpoint is the OTLP endpoint to send traces to (e.g. http://localhost:4317). Optional: {}
insecure boolean Insecure disables TLS verification for the OTLP connection. Optional: {}

TransformAgentComponentSpec

TransformAgentComponentSpec defines the Transform Agent component pod specification

Appears in:

Field Description Default Validation
replicas integer Replicas specifies the number of replicas for Transform Agent deployment 2 Optional: {}
resources ResourceRequirements Resources defines compute resource requests and limits for the Transform Agent primary container.
If podTemplate.spec.containers[transform-agent].resources is also set, the podTemplate value takes
precedence because it is more specific.		 Optional: {}
podTemplate PodTemplateSpec PodTemplate defines pod template specification for Transform Agent Type: object
Optional: {}
tls TransformAgentTLSConfig TLS configures mutual TLS for the Transform Agent via cert-manager. When set, a single certificate
is used for the Transform Agent server and Bindplane clients.		 Optional: {}
disablePodDisruptionBudget boolean DisablePodDisruptionBudget disables the operator-managed PodDisruptionBudget for this component.
When false (default), the operator creates a PDB with minAvailable: 1.		 Optional: {}
extraEnv EnvVar array ExtraEnv is a list of additional environment variables to inject into the
primary container of this component. These are prepended BEFORE the
operator-managed environment variables, so a duplicate Name set here will
be ignored — Kubernetes uses the LAST entry for a given Name and the
operator will not let user entries override its own values.
This is the supported way to add custom environment variables. Setting
env on podTemplate.spec.containers[] is intentionally ignored.
Environment variable names starting with BINDPLANE_ are rejected by the
validating webhook unless the operator is started with --allow-bindplane-extra-env=true.		 Optional: {}
extraVolumes Volume array ExtraVolumes is a list of additional volumes to add to this component's pod.
Volume names must be unique and must not collide with operator-managed volume names.
Allowed sources: secret, configMap, projected, csi, emptyDir, downwardAPI.
hostPath and other sources are rejected by the validating webhook.		 Optional: {}
extraVolumeMounts VolumeMount array ExtraVolumeMounts is a list of additional volume mounts for this component's primary container.
Each mount's name must reference a volume defined in extraVolumes on the same component.
mountPath must be absolute and must not collide with an operator-managed mount path.		 Optional: {}
image string Image overrides the container image for Transform Agent. When set, the value is used
verbatim as a full OCI reference. When empty, the image is derived from spec.version
using the ghcr.io/observiq/bindplane-transform-agent registry.		 MinLength: 1
Optional: {}
serviceAccount ServiceAccountSpec ServiceAccount configures the operator-managed ServiceAccount for this component. Optional: {}

TransformAgentTLSConfig

TransformAgentTLSConfig defines TLS for the Transform Agent. Only cert-manager is supported; no secretName.

Appears in:

Field Description Default Validation
certManager CertManagerTLSIssuerRef CertManager references a cert-manager Issuer or ClusterIssuer to issue the Transform Agent certificate
used by both the Transform Agent server and Bindplane clients.		 Optional: {}

VolumeClaimTemplate

VolumeClaimTemplate defines a template for creating PersistentVolumeClaims

Appears in:

Field Description Default Validation
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec PersistentVolumeClaimSpec Spec defines the PersistentVolumeClaim specification