API Reference¶

Packages¶

clusterpulse.io/v1alpha1

clusterpulse.io/v1alpha1¶

Package v1alpha1 contains API Schema definitions for the clusterpulse v1alpha1 API group

cluster-controller/api/v1alpha1/registryconnection_types.go

Resource Types¶

ClusterConnection
MetricSource
MonitorAccessPolicy
RegistryConnection

Aggregation¶

Aggregation defines a cluster-wide computation across all collected resources

Appears in: - MetricSourceSpec

Field	Description	Validation
`name` string	Name is the identifier for this aggregation
`field` string	Field to aggregate (not required for count)	Optional: {}
`function` string	Function specifies the aggregation operation	Enum: [count sum avg min max percentile distinct]
`filter` AggregationFilter	Filter applies a condition before aggregating	Optional: {}
`groupBy` string	GroupBy produces aggregations grouped by this field's values	Optional: {}
`percentile` integer	Percentile value (only used when function is percentile)	Optional: {}

AggregationFilter¶

AggregationFilter defines a condition for filtering before aggregation

Appears in: - Aggregation

Field	Description	Validation
`field` string	Field to filter on
`operator` string	Operator for comparison	Enum: [equals notEquals contains startsWith endsWith greaterThan lessThan in matches]
`value` string	Value to compare against

AggregationVisibility¶

AggregationVisibility controls which aggregations are visible

Appears in: - ResourceFilter

Field	Description	Default	Validation
`include` string array	Include only these aggregations (takes precedence over exclude)		Optional: {}
`exclude` string array	Exclude these aggregations		Optional: {}

ClusterConnection¶

ClusterConnection is the Schema for the clusterconnections API

Field	Description	Default	Validation
`apiVersion` string	`clusterpulse.io/v1alpha1`
`kind` string	`ClusterConnection`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ClusterConnectionSpec
`status` ClusterConnectionStatus

ClusterConnectionSpec¶

ClusterConnectionSpec defines the desired state of ClusterConnection

Appears in: - ClusterConnection

Field	Description	Default	Validation
`displayName` string	DisplayName is a human-friendly name for the cluster
`endpoint` string	Endpoint is the API server endpoint of the target cluster
`credentialsRef` CredentialsReference	CredentialsRef references the secret containing cluster credentials
`labels` object (keys:string, values:string)	Labels for cluster categorization
`monitoring` MonitoringConfig	Monitoring configuration
`collectionMode` string	CollectionMode determines how metrics are collected from this cluster. "pull" (default): hub pulls metrics via remote API calls. "push": a collector agent is deployed on the managed cluster that pushes metrics.	pull	Enum: [pull push]
`ingesterAddress` string	IngesterAddress is the externally-reachable address of the hub ingester gRPC endpoint. Required when collectionMode is "push". Example: "hub.example.com:9443"		Optional: {}
`collectorVersion` string	CollectorVersion overrides the collector agent image tag for this cluster. If empty, defaults to the controller's own version.		Optional: {}

ClusterConnectionStatus¶

ClusterConnectionStatus defines the observed state of ClusterConnection

Appears in: - ClusterConnection

Field	Description	Default	Validation
`phase` string	Phase indicates the connection status
`lastSyncTime` Time	LastSyncTime is the timestamp of the last successful sync
`health` string	Health indicates the cluster health
`message` string	Message provides additional information about the status
`nodes` integer	Nodes is the number of nodes in the cluster
`namespaces` integer	Namespaces is the number of namespaces in the cluster
`collectorStatus` CollectorAgentStatus	CollectorStatus reports the state of the push-mode collector agent. Only populated when collectionMode is "push".

CollectionConfig¶

CollectionConfig defines collection behavior parameters

Appears in: - MetricSourceSpec

Field	Description	Default	Validation
`intervalSeconds` integer	IntervalSeconds between collection cycles (minimum 30)	60	Minimum: 30
`timeoutSeconds` integer	TimeoutSeconds for per-cluster collection	30	Minimum: 5
`maxResources` integer	MaxResources limits the number of resources collected per cluster	5000	Minimum: 1
`batchSize` integer	BatchSize for API pagination	500	Minimum: 10
`retryAttempts` integer	RetryAttempts on transient failures	3	Minimum: 0
`parallelism` integer	Parallelism for concurrent field extractions	3	Minimum: 1

CollectorAgentStatus¶

CollectorAgentStatus tracks the state of a collector agent on a managed cluster.

Appears in: - ClusterConnectionStatus

Field	Description	Default	Validation
`connected` boolean	Connected indicates whether the collector is currently connected to the ingester.
`lastHeartbeat` Time	LastHeartbeat is the timestamp of the last health report from the collector.
`version` string	Version is the collector agent version string.

ComputedField¶

ComputedField defines a derived value calculated from extracted fields

Appears in: - MetricSourceSpec

Field	Description	Default	Validation
`name` string	Name is the identifier for this computed field
`expression` string	Expression defines the computation using the expression language
`type` string	Type specifies the result type	float	Enum: [string integer float boolean]

CredentialsReference¶

CredentialsReference references a secret containing credentials

Appears in: - ClusterConnectionSpec - RegistryConnectionSpec

Field	Description	Default	Validation
`name` string	Name of the secret
`namespace` string	Namespace of the secret (defaults to same namespace as ClusterConnection)

FieldExtraction¶

FieldExtraction defines how to extract a single field from a resource

Appears in: - MetricSourceSpec

Field	Description	Default	Validation
`name` string	Name is the identifier for this extracted field
`path` string	Path is the JSONPath expression to extract the value
`type` string	Type specifies how to interpret the extracted value	string	Enum: [string integer float boolean quantity timestamp arrayLength]
`default` string	Default value when the path doesn't exist		Optional: {}

FieldValidationStatus¶

FieldValidationStatus reports the validation status of a single field

Appears in: - MetricSourceStatus

Field	Description	Validation
`field` string	Field name
`status` string	Status of validation	Enum: [valid invalid warning]
`message` string	Message provides details if status is not valid	Optional: {}

MetricSource¶

MetricSource defines a custom resource collection configuration

Field	Description	Default	Validation
`apiVersion` string	`clusterpulse.io/v1alpha1`
`kind` string	`MetricSource`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` MetricSourceSpec
`status` MetricSourceStatus

MetricSourceRBAC¶

MetricSourceRBAC defines how this resource integrates with access policies

Appears in: - MetricSourceSpec

Field	Description	Default	Validation
`resourceTypeName` string	ResourceTypeName is the unique identifier for policy references
`filterableFields` string array	FilterableFields lists fields that can be filtered in policies		Optional: {}
`filterAggregations` boolean	FilterAggregations controls whether aggregations respect RBAC filtering	true

MetricSourceSpec¶

MetricSourceSpec defines the desired state of MetricSource

Appears in: - MetricSource

Field	Description	Validation
`source` MetricSourceTarget	Source defines which Kubernetes resource to collect from
`fields` FieldExtraction array	Fields defines what to extract from each resource instance
`computed` ComputedField array	Computed defines derived values calculated from extracted fields	Optional: {}
`aggregations` Aggregation array	Aggregations defines cluster-wide computations across all collected resources	Optional: {}
`collection` CollectionConfig	Collection defines how and when to collect resources	Optional: {}
`rbac` MetricSourceRBAC	RBAC defines how this resource integrates with access policies	Optional: {}

MetricSourceStatus¶

MetricSourceStatus defines the observed state of MetricSource

Appears in: - MetricSource

Field	Description	Validation
`phase` string	Phase indicates the current state	Enum: [Active Error Disabled]
`lastCollectionTime` Time	LastCollectionTime is when collection last completed	Optional: {}
`lastCollectionDuration` string	LastCollectionDuration is how long the last collection took	Optional: {}
`resourcesCollected` integer	ResourcesCollected is the total count from last collection
`clustersCollected` integer	ClustersCollected is the number of clusters successfully collected from
`errorsLastRun` integer	ErrorsLastRun is the count of errors in the last collection cycle
`message` string	Message provides additional status information	Optional: {}
`fieldValidation` FieldValidationStatus array	FieldValidation reports validation status for each field	Optional: {}
`conditions` Condition array	Conditions represent the latest observations	Optional: {}

MetricSourceTarget¶

MetricSourceTarget identifies the Kubernetes resource to collect

Appears in: - MetricSourceSpec

Field	Description	Default	Validation
`apiVersion` string	APIVersion of the target resource (e.g., "v1", "apps/v1")
`kind` string	Kind of the target resource (e.g., "PersistentVolumeClaim", "Deployment")
`scope` string	Scope determines collection behavior: Namespaced or Cluster	Namespaced	Enum: [Namespaced Cluster]
`namespaces` NamespaceSelector	Namespaces defines which namespaces to collect from (only for Namespaced scope)		Optional: {}
`labelSelector` LabelSelector	LabelSelector filters resources by labels		Optional: {}

MonitorAccessPolicy¶

MonitorAccessPolicy defines an RBAC policy for cluster monitoring access

Field	Description	Default	Validation
`apiVersion` string	`clusterpulse.io/v1alpha1`
`kind` string	`MonitorAccessPolicy`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` MonitorAccessPolicySpec
`status` MonitorAccessPolicyStatus

MonitorAccessPolicySpec¶

MonitorAccessPolicySpec defines the desired state of MonitorAccessPolicy

Appears in: - MonitorAccessPolicy

Field	Description	Validation
`identity` PolicyIdentity	Identity defines who this policy applies to
`access` PolicyAccess	Access defines the effect and enablement of this policy
`scope` PolicyScope	Scope defines what resources are accessible
`lifecycle` PolicyLifecycle	Lifecycle defines validity periods	Optional: {}

MonitorAccessPolicyStatus¶

MonitorAccessPolicyStatus defines the observed state of MonitorAccessPolicy

Appears in: - MonitorAccessPolicy

Field	Description	Default	Validation
`state` string	State indicates the current policy state	Pending	Enum: [Active Inactive Error Pending Expired]
`message` string	Message provides additional status information		Optional: {}
`compiledAt` string	CompiledAt is when the policy was last compiled		Optional: {}
`hash` string	Hash is the spec hash of the compiled policy		Optional: {}
`affectedUsers` integer	AffectedUsers is the count of users affected by this policy
`affectedGroups` integer	AffectedGroups is the count of groups affected by this policy
`affectedServiceAccounts` integer	AffectedServiceAccounts is the count of SAs affected by this policy
`customResourceTypes` integer	CustomResourceTypes is the count of custom resource types referenced
`customResourceWarnings` string array	CustomResourceWarnings lists warnings about custom resource references		Optional: {}
`evaluationCount` integer	EvaluationCount tracks how many times this policy has been evaluated	0
`lastEvaluated` string	LastEvaluated is when this policy was last evaluated		Optional: {}
`conditions` Condition array	Conditions represent the latest observations		Optional: {}

MonitoringConfig¶

MonitoringConfig defines monitoring settings

Appears in: - ClusterConnectionSpec

Field	Description	Default	Validation
`interval` integer	Reconciliation interval in seconds (minimum 30, default 30)
`timeout` integer	Connection timeout in seconds (minimum 5, default 10)

NamespaceSelector¶

NamespaceSelector defines namespace inclusion/exclusion patterns

Appears in: - MetricSourceTarget

Field	Description	Default	Validation
`include` string array	Include specifies namespace patterns to include (supports wildcards)		Optional: {}
`exclude` string array	Exclude specifies namespace patterns to exclude (takes precedence over include)		Optional: {}

PatternFilter¶

Underlying type: struct{Allowed []string "json:\"allowed,omitempty\""; Denied []string "json:\"denied,omitempty\""}

PatternFilter defines allowed/denied patterns

Appears in: - ResourceFilterSpec

PolicyAccess¶

PolicyAccess defines the effect and enablement

Appears in: - MonitorAccessPolicySpec

Field	Description	Default	Validation
`effect` string	Effect is Allow or Deny		Enum: [Allow Deny]
`enabled` boolean	Enabled indicates whether this policy is active	true

PolicyClusterRule¶

PolicyClusterRule defines access for a set of clusters

Appears in: - PolicyClusters

Field	Description	Validation
`selector` PolicyClusterSelector	Selector matches clusters by name, pattern, or labels
`permissions` PolicyPermissions	Permissions defines what actions are allowed	Optional: {}
`resources` ResourceFilter array	Resources defines resource-level filtering	Optional: {}

PolicyClusterSelector¶

PolicyClusterSelector identifies which clusters a rule applies to

Appears in: - PolicyClusterRule

Field	Description	Validation
`matchLabels` object (keys:string, values:string)	MatchLabels selects clusters by labels	Optional: {}
`matchNames` string array	MatchNames selects clusters by exact name or wildcard pattern	Optional: {}
`matchPattern` string	MatchPattern selects clusters by regex	MaxLength: 256 Optional: {}

PolicyClusters¶

PolicyClusters defines cluster-level access

Appears in: - PolicyScope

Field	Description	Default	Validation
`default` string	Default access for clusters not matching any rule	none	Enum: [allow deny none]
`rules` PolicyClusterRule array	Rules defines per-cluster access rules		Optional: {}

PolicyIdentity¶

PolicyIdentity defines who this policy applies to

Appears in: - MonitorAccessPolicySpec

Field	Description	Default	Validation
`subjects` PolicySubjects	Subjects specifies the users, groups, and service accounts
`priority` integer	Priority determines evaluation order (higher = first)	100	Maximum: 10000 Minimum: 1

PolicyLifecycle¶

PolicyLifecycle defines validity periods

Appears in: - MonitorAccessPolicySpec

Field	Description	Default	Validation
`validity` PolicyValidity	Validity defines time-based validity		Optional: {}

PolicyPermissions¶

PolicyPermissions defines the known permission flags for cluster access

Appears in: - PolicyClusterRule

Field	Description	Default	Validation
`view` boolean	View grants basic cluster visibility		Optional: {}
`viewMetrics` boolean	ViewMetrics grants access to cluster metrics		Optional: {}

PolicyScope¶

PolicyScope defines what resources are accessible

Appears in: - MonitorAccessPolicySpec

Field	Description	Default	Validation
`clusters` PolicyClusters	Clusters defines cluster access rules

PolicyServiceAccount¶

PolicyServiceAccount references a Kubernetes service account

Appears in: - PolicySubjects

Field	Description	Default	Validation
`name` string	Name of the service account
`namespace` string	Namespace of the service account	default

PolicySubjects¶

PolicySubjects specifies the identities this policy applies to

Appears in: - PolicyIdentity

Field	Description	Validation
`users` string array	Users is a list of usernames or email addresses	Optional: {}
`groups` string array	Groups is a list of group names	Optional: {}
`serviceAccounts` PolicyServiceAccount array	ServiceAccounts is a list of service account references	Optional: {}

PolicyValidity¶

PolicyValidity defines time bounds for the policy

Appears in: - PolicyLifecycle

Field	Description	Default	Validation
`notBefore` string	NotBefore - policy is not valid before this time		Optional: {}
`notAfter` string	NotAfter - policy expires after this time		Optional: {}

RegistryConnection¶

RegistryConnection is the Schema for the registryconnections API

Field	Description	Default	Validation
`apiVersion` string	`clusterpulse.io/v1alpha1`
`kind` string	`RegistryConnection`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` RegistryConnectionSpec
`status` RegistryConnectionStatus

RegistryConnectionSpec¶

RegistryConnectionSpec defines the desired state of RegistryConnection

Appears in: - RegistryConnection

Field	Description	Default	Validation
`displayName` string	DisplayName is a human-friendly name for the registry
`endpoint` string	Endpoint is the registry endpoint (e.g., https://registry.example.com)
`type` string	Type is optional and purely informational (all registries use Docker v2 API) Examples: "dockerhub", "harbor", "ecr", "gcr", "artifactory" Can be left empty or any string for documentation purposes
`credentialsRef` CredentialsReference	CredentialsRef references the secret containing registry credentials (optional) Secret should contain "username" and "password" fields
`insecure` boolean	Insecure allows connecting to registries with self-signed certificates
`skipTLSVerify` boolean	SkipTLSVerify skips TLS certificate verification
`monitoring` RegistryMonitoringConfig	Monitoring configuration
`labels` object (keys:string, values:string)	Labels for registry categorization
`healthCheckPaths` string array	HealthCheckPaths to verify (defaults to ["/v2/"])

RegistryConnectionStatus¶

RegistryConnectionStatus defines the observed state of RegistryConnection

Appears in: - RegistryConnection

Field	Description	Default	Validation
`phase` string	Phase indicates the connection status (Connecting, Connected, Error, Unknown)
`health` string	Health indicates registry health (healthy, degraded, unhealthy, unknown)
`available` boolean	Available indicates if the registry is reachable
`lastCheckTime` Time	LastCheckTime is the timestamp of the last health check
`responseTime` integer	ResponseTime is the last health check response time in milliseconds
`message` string	Message provides additional information about the status
`repositoryCount` integer	RepositoryCount is the number of repositories (if catalog check is enabled)
`version` string	Version is the registry version (if detectable)
`features` object (keys:string, values:boolean)	Features detected from the registry

RegistryMonitoringConfig¶

RegistryMonitoringConfig defines monitoring settings for registry

Appears in: - RegistryConnectionSpec

Field	Description	Default	Validation
`interval` integer	Interval in seconds between health checks (minimum 30, default 60)
`timeout` integer	Timeout in seconds for health check requests (minimum 5, default 10)
`checkCatalog` boolean	CheckCatalog enables checking /v2/_catalog endpoint (requires appropriate permissions)
`maxCatalogEntries` integer	MaxCatalogEntries limits the number of catalog entries to fetch (default 100)

ResourceFilter¶

ResourceFilter defines visibility and filtering for a resource type

Appears in: - PolicyClusterRule

Field	Description	Default	Validation
`type` string	Type is the resource type: "nodes", "operators", "namespaces", "pods", or a custom resource type name (e.g., "virtualmachines")		MinLength: 1
`visibility` string		all	Enum: [all none filtered]
`filters` ResourceFilterSpec	Filters defines allow/deny criteria		Optional: {}
`aggregations` AggregationVisibility	Aggregations controls aggregation visibility (custom resource types only)		Optional: {}

ResourceFilterSpec¶

ResourceFilterSpec defines allow/deny criteria for a resource type

Appears in: - ResourceFilter

Field	Description	Validation
`namespaces` PatternFilter	Namespaces filters by namespace (supports wildcards)	Optional: {}
`names` PatternFilter	Names filters by resource name (supports wildcards)	Optional: {}
`labels` object (keys:string, values:string)	Labels filters by K8s labels	Optional: {}
`fields` object (keys:string, values:PatternFilter)	Fields filters by field values (custom resource types only)	Optional: {}