Documentation
¶
Overview ¶
Package refs contains typed cross-resource reference types for BubuStack.
This package provides a secure, multi-tenant-safe way to reference Kubernetes resources across the BubuStack ecosystem. All reference types include validation, drift detection, and multi-tenancy controls.
+kubebuilder:object:generate=true
Package refs provides typed cross-resource references for BubuStack APIs.
This package implements a secure, multi-tenant-safe reference system that enables resources to reference each other while maintaining namespace isolation and providing drift detection capabilities.
Key features: - Type-safe references with validation - Multi-tenancy safety (same-namespace by default) - Drift detection via UID tracking - Explicit cross-namespace references when needed
The reference system follows Kubernetes conventions and provides a foundation for building complex workflows while maintaining security and operational clarity.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ResolveNamespace ¶
func ResolveNamespace(referencingObject client.Object, ref *ObjectReference) string
ResolveNamespace determines the target namespace for a reference, defaulting to the namespace of the referencing object if the reference itself does not specify one. This is the standard pattern for enabling optional cross-namespace references.
Types ¶
type EngramReference ¶
type EngramReference struct {
ObjectReference `json:",inline"`
UID *types.UID `json:"uid,omitempty"`
}
EngramReference provides a structured reference to an Engram.
func (*EngramReference) DeepCopy ¶
func (in *EngramReference) DeepCopy() *EngramReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EngramReference.
func (*EngramReference) DeepCopyInto ¶
func (in *EngramReference) DeepCopyInto(out *EngramReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type EngramTemplateReference ¶
type EngramTemplateReference struct {
// Name of the referenced EngramTemplate.
// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=253
Name string `json:"name"`
// UID of the referenced EngramTemplate for drift detection.
// +kubebuilder:validation:Optional
UID *types.UID `json:"uid,omitempty"`
}
EngramTemplateReference provides a structured reference to a cluster-scoped EngramTemplate. It omits the namespace field as the referenced object is cluster-scoped.
func (*EngramTemplateReference) DeepCopy ¶
func (in *EngramTemplateReference) DeepCopy() *EngramTemplateReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EngramTemplateReference.
func (*EngramTemplateReference) DeepCopyInto ¶
func (in *EngramTemplateReference) DeepCopyInto(out *EngramTemplateReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ImpulseReference ¶
type ImpulseReference struct {
ObjectReference `json:",inline"`
UID *types.UID `json:"uid,omitempty"`
}
ImpulseReference provides a structured reference to an Impulse.
func (*ImpulseReference) DeepCopy ¶
func (in *ImpulseReference) DeepCopy() *ImpulseReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ImpulseReference.
func (*ImpulseReference) DeepCopyInto ¶
func (in *ImpulseReference) DeepCopyInto(out *ImpulseReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ImpulseTemplateReference ¶
type ImpulseTemplateReference struct {
// Name of the referenced ImpulseTemplate.
// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=253
Name string `json:"name"`
// UID of the referenced ImpulseTemplate for drift detection.
// +kubebuilder:validation:Optional
UID *types.UID `json:"uid,omitempty"`
}
ImpulseTemplateReference provides a structured reference to a cluster-scoped ImpulseTemplate. It omits the namespace field as the referenced object is cluster-scoped.
func (*ImpulseTemplateReference) DeepCopy ¶
func (in *ImpulseTemplateReference) DeepCopy() *ImpulseTemplateReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ImpulseTemplateReference.
func (*ImpulseTemplateReference) DeepCopyInto ¶
func (in *ImpulseTemplateReference) DeepCopyInto(out *ImpulseTemplateReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ObjectReference ¶
type ObjectReference struct {
// Name of the referenced object.
// Must be a valid DNS-1123 label as defined by Kubernetes naming conventions.
//
// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=253
// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Name string `json:"name"`
// Namespace of the referenced object.
// If empty, defaults to same namespace as the referencing object.
//
// Cross-namespace references should be used carefully and only when
// multi-tenancy is properly configured. Consider the security implications:
// - Ensure RBAC policies allow cross-namespace access
// - Validate that the target namespace is trusted
// - Monitor cross-namespace references for security compliance
//
// +kubebuilder:validation:MaxLength=63
// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Namespace *string `json:"namespace,omitempty"`
}
ObjectReference represents a typed reference to a Kubernetes object. This is the base type for all BubuStack cross-resource references.
Multi-tenancy is enforced by defaulting to same-namespace references. Cross-namespace references must be explicitly specified and should be carefully controlled through RBAC policies.
Example same-namespace reference:
storyRef: name: "my-story"
Example cross-namespace reference:
storyRef: name: "shared-story" namespace: "shared-workflows"
func (*ObjectReference) DeepCopy ¶
func (in *ObjectReference) DeepCopy() *ObjectReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObjectReference.
func (*ObjectReference) DeepCopyInto ¶
func (in *ObjectReference) DeepCopyInto(out *ObjectReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (*ObjectReference) ToNamespacedName ¶
func (ref *ObjectReference) ToNamespacedName(referencingObject client.Object) types.NamespacedName
ToNamespacedName converts an ObjectReference into a types.NamespacedName, using the provided object to determine the default namespace.
type StoryReference ¶
type StoryReference struct {
ObjectReference `json:",inline"`
// UID of the referenced Story for drift detection.
// This field is populated by controllers and should not be set by users.
//
// When a controller resolves this reference, it stores the target's UID.
// On subsequent reconciliations, if the UID has changed, it indicates
// the target was deleted and recreated, which may require special handling.
//
// +kubebuilder:validation:Optional
UID *types.UID `json:"uid,omitempty"`
}
StoryReference represents a reference to a Story resource. Stories are the main workflow definitions in BubuStack and are frequently referenced by Impulses (triggers) and other Stories (sub-workflows).
The UID field provides drift detection - controllers can detect when the referenced Story has been deleted and recreated, enabling appropriate error handling and user notification.
func (*StoryReference) DeepCopy ¶
func (in *StoryReference) DeepCopy() *StoryReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new StoryReference.
func (*StoryReference) DeepCopyInto ¶
func (in *StoryReference) DeepCopyInto(out *StoryReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type StoryRunReference ¶
type StoryRunReference struct {
ObjectReference `json:",inline"`
// UID of the referenced StoryRun for drift detection.
// This field is populated by controllers and should not be set by users.
//
// StoryRun drift detection helps maintain execution integrity and
// enables proper cleanup of orphaned StepRuns.
//
// +kubebuilder:validation:Optional
UID *types.UID `json:"uid,omitempty"`
}
StoryRunReference provides a structured reference to a StoryRun.
func (*StoryRunReference) DeepCopy ¶
func (in *StoryRunReference) DeepCopy() *StoryRunReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new StoryRunReference.
func (*StoryRunReference) DeepCopyInto ¶
func (in *StoryRunReference) DeepCopyInto(out *StoryRunReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type TemplateReference ¶
type TemplateReference struct {
// Name of the referenced template.
// Templates are cluster-scoped so no namespace is needed.
//
// Template names should be globally unique within the cluster and
// follow semantic versioning or other naming conventions to enable
// upgrades and compatibility management.
//
// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=253
// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Name string `json:"name"`
// UID of the referenced template for drift detection.
// This field is populated by controllers and should not be set by users.
//
// Template drift detection is particularly important because templates
// define the ABI and behavior expectations for dependent resources.
//
// +kubebuilder:validation:Optional
UID *types.UID `json:"uid,omitempty"`
}
TemplateReference represents a reference to a Template resource. Templates are cluster-scoped resources that define capabilities and schemas.
Since templates are cluster-scoped, they don't have a namespace field. Templates provide the foundation for Engrams and Impulses by defining what can be configured and how it should behave.
func (*TemplateReference) DeepCopy ¶
func (in *TemplateReference) DeepCopy() *TemplateReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TemplateReference.
func (*TemplateReference) DeepCopyInto ¶
func (in *TemplateReference) DeepCopyInto(out *TemplateReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
Source Files