builder

package
v1.10.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package builder provides functions for constructing Kubernetes resources for Valkey operator managed instances.

Index

Constants

View Source 
const (
	// TLSVolumeName is the name of the volume for TLS certificates.
	TLSVolumeName = "tls"

	// TLSMountPath is the mount path for TLS certificates inside containers.
	TLSMountPath = "/tls"

	// TLSPort is the TLS-enabled Valkey port.
	TLSPort = 16379

	// SentinelTLSPort is the TLS-enabled Sentinel port (SentinelPort + 10000).
	SentinelTLSPort = 36379

	// CertManagerAPIVersion is the API version for cert-manager Certificate resources.
	CertManagerAPIVersion = "cert-manager.io/v1"

	// CertManagerCertificateKind is the kind for cert-manager Certificate resources.
	CertManagerCertificateKind = "Certificate"
)
View Source 
const (
	// ValkeyPort is the default Valkey server port.
	ValkeyPort = 6379

	// ValkeyConfigKey is the key used in the ConfigMap for the valkey configuration.
	ValkeyConfigKey = "valkey.conf"

	// DataDir is the directory where Valkey stores its data.
	DataDir = "/data"
)
View Source 
const (
	// ComponentObserver is the component value for observer instances.
	ComponentObserver = "observer"

	// ObserverHealthPort is the port on which the observer health endpoint listens.
	ObserverHealthPort = 8084
)
View Source 
const (
	// SentinelPort is the default Sentinel port.
	SentinelPort = 26379

	// SentinelConfigKey is the key used in the ConfigMap for sentinel configuration.
	SentinelConfigKey = "sentinel.conf"

	// AnnotationKnownMaster is the annotation key used to persist the post-failover
	// master address on the Valkey CR. When present, GenerateSentinelConf uses this
	// address instead of the default pod-0 address. This ensures that if a sentinel
	// pod restarts after a failover, it reads the correct master from the ConfigMap
	// rather than falling back to the stale pod-0 default.
	AnnotationKnownMaster = "vko.gtrfc.com/known-master"

	// SentinelContainerName is the name of the Sentinel container.
	SentinelContainerName = "sentinel"

	// SentinelConfigVolumeName is the name of the writable sentinel config volume.
	SentinelConfigVolumeName = "sentinel-config"

	// SentinelConfigMountPath is the mount path for the sentinel configuration.
	SentinelConfigMountPath = "/etc/sentinel"

	// SentinelDataDir is the working directory for Sentinel.
	SentinelDataDir = "/data"

	// SentinelQuorum is the default number of Sentinels that need to agree for failover.
	SentinelQuorum = 2

	// SentinelDownAfterMilliseconds is the default time before a master is considered down.
	SentinelDownAfterMilliseconds = 5000

	// SentinelFailoverTimeout is the default failover timeout.
	SentinelFailoverTimeout = 60000

	// SentinelParallelSyncs is the number of replicas that can sync simultaneously after failover.
	SentinelParallelSyncs = 1
)
View Source 
const (
	// ValkeyContainerName is the name of the main Valkey container.
	ValkeyContainerName = "valkey"

	// SidecarContainerName is the name of the sidecar container that manages role labels.
	SidecarContainerName = "sidecar"

	// SidecarHealthPort is the port on which the sidecar readiness endpoint listens.
	SidecarHealthPort = 8082

	// ConfigVolumeName is the name of the volume for the master Valkey configuration (readonly).
	ConfigVolumeName = "config"

	// ReplicaConfigVolumeName is the name of the volume for the replica configuration (readonly, HA mode).
	ReplicaConfigVolumeName = "replica-config"

	// WritableConfigVolumeName is the name of the writable config volume (HA mode, populated by init container).
	WritableConfigVolumeName = "writable-config"

	// DataVolumeName is the name of the volume for persistent data.
	DataVolumeName = "data"

	// ConfigMountPath is the mount path for the master Valkey configuration (readonly).
	ConfigMountPath = "/etc/valkey"

	// ReplicaConfigMountPath is the mount path for the replica configuration (readonly, HA mode).
	ReplicaConfigMountPath = "/etc/valkey-replica"

	// WritableConfigMountPath is the mount path for the writable config (HA mode).
	WritableConfigMountPath = "/etc/valkey-active"

	// AuthSecretEnvName is the environment variable name used to inject the Valkey password.
	AuthSecretEnvName = "VALKEY_PASSWORD"

	// ValkeyPlainContainerName is the name of the secondary plaintext Valkey container.
	ValkeyPlainContainerName = "valkey-plain"

	// ValkeyCLIBinary is the path/name of the valkey-cli command.
	ValkeyCLIBinary = "valkey-cli"

	// ValkeyTLSFlag enables TLS for valkey-cli.
	ValkeyTLSFlag = "--tls"

	// ValkeyCACertFlag selects the CA certificate for valkey-cli.
	ValkeyCACertFlag = "--cacert"

	// ValkeyPingCommand is the ping command name used in probes.
	ValkeyPingCommand = "ping"

	// ManagerBinary is the path of the operator manager binary inside the container image.
	ManagerBinary = "./manager"

	// PodNamespaceEnvName is the env var name used to inject the pod namespace.
	PodNamespaceEnvName = "POD_NAMESPACE"

	// DefaultServiceAccountName is the Kubernetes "default" service account name.
	DefaultServiceAccountName = "default"

	// IssuerRefNameKey is the unstructured map key for an issuer reference name.
	IssuerRefNameKey = "name"

	// IssuerRefKindKey is the unstructured map key for an issuer reference kind.
	IssuerRefKindKey = "kind"
)
View Source 
const AnnotationConfigHash = "vko.gtrfc.com/config-hash"

AnnotationConfigHash is the annotation key used to store a hash of the generated Valkey / Sentinel configuration content. It is embedded in the StatefulSet pod template so that config changes (e.g. toggling allowUnencrypted) are propagated as a pod template annotation change, which the operator's rolling update logic then detects and acts upon.

View Source 
const AnnotationOperatorVersion = "vko.gtrfc.com/operator-version"

AnnotationOperatorVersion is the annotation key used to track which operator version last reconciled a managed resource. It is applied to all resources created or updated by the operator to provide an audit trail and enable detection of resources not yet reconciled by the current version.

View Source 
const AnnotationPodSpecHash = "vko.gtrfc.com/pod-spec-hash"

AnnotationPodSpecHash is the annotation key used to store a hash of the generated pod spec (containers, resources, probes, volumes, etc.). It is embedded in the StatefulSet pod template so that pod-spec-level changes (e.g. resource requests/limits) are detected by the rolling update logic, even though the StatefulSet uses OnDelete strategy.

Variables

This section is empty.

Functions

func AllServiceName added in v1.1.0 

func AllServiceName(v *vkov1.Valkey) string

AllServiceName returns the name for the all-pods Service (<name>-all). This service load-balances across all Valkey pods regardless of role.

func ApplyOperatorVersion added in v1.2.0 

func ApplyOperatorVersion(obj metav1.Object, version string)

ApplyOperatorVersion sets the operator-version annotation on a Kubernetes object. If version is empty the annotation is left unchanged.

func BuildAllService added in v1.1.0 

func BuildAllService(v *vkov1.Valkey) *corev1.Service

BuildAllService builds the all-pods Service that load-balances across all Valkey pods. Useful for read-heavy workloads where reads from replicas are acceptable. Port rules follow the same TLS / allowUnencrypted logic as BuildRWService.

func BuildConfigMap 

func BuildConfigMap(v *vkov1.Valkey) *corev1.ConfigMap

BuildConfigMap builds the ConfigMap for Valkey configuration. In standalone mode or for the master in HA mode, isReplica should be false.

func BuildHeadlessService 

func BuildHeadlessService(v *vkov1.Valkey) *corev1.Service

BuildHeadlessService builds the headless Service for StatefulSet DNS resolution. The headless service is internal infrastructure only; it always exposes the primary Valkey port for DNS record generation and does not expose a plain port.

func BuildObserverDeployment added in v1.5.0 

func BuildObserverDeployment(v *vkov1.Valkey, operatorImage string) *appsv1.Deployment

BuildObserverDeployment builds the Deployment for the observer.

func BuildObserverNetworkPolicy added in v1.5.0 

func BuildObserverNetworkPolicy(v *vkov1.Valkey) *networkingv1.NetworkPolicy

BuildObserverNetworkPolicy builds the NetworkPolicy for the observer pod. It only allows ingress on the health port (8084) from all sources for kubelet probes.

func BuildRWService added in v1.1.0 

func BuildRWService(v *vkov1.Valkey) *corev1.Service

BuildRWService builds the read-write Service that routes only to the master pod. The selector requires instanceRole=master, which is managed by the sidecar container. When TLS is enabled the primary port is 16379; when allowUnencrypted is also set, port 6379 is added as "valkey-plain".

func BuildReadOnlyService added in v1.1.0 

func BuildReadOnlyService(v *vkov1.Valkey) *corev1.Service

BuildReadOnlyService builds a read-only Service that routes only to replica pods. The selector requires instanceRole=replica, managed by the sidecar container. Only created in multi-replica mode. Port rules follow the same TLS / allowUnencrypted logic as BuildRWService.

func BuildReplicaConfigMap 

func BuildReplicaConfigMap(v *vkov1.Valkey) *corev1.ConfigMap

BuildReplicaConfigMap builds the ConfigMap for Valkey replica configuration (HA mode). It includes the `replicaof` directive pointing to the master.

func BuildSentinelCertificate 

func BuildSentinelCertificate(v *vkov1.Valkey) *unstructured.Unstructured

BuildSentinelCertificate builds the cert-manager Certificate resource for Sentinel pods.

func BuildSentinelConfigMap 

func BuildSentinelConfigMap(v *vkov1.Valkey) *corev1.ConfigMap

BuildSentinelConfigMap builds the ConfigMap for Sentinel configuration.

func BuildSentinelHeadlessService 

func BuildSentinelHeadlessService(v *vkov1.Valkey) *corev1.Service

BuildSentinelHeadlessService builds the headless Service for Sentinel StatefulSet DNS resolution. When TLS is enabled the primary port is 36379 (= SentinelPort + 10000); when sentinel.allowUnencrypted is also set, port 26379 is added as "sentinel-plain".

func BuildSentinelNetworkPolicy 

func BuildSentinelNetworkPolicy(v *vkov1.Valkey, operatorNamespace string) *networkingv1.NetworkPolicy

BuildSentinelNetworkPolicy builds the NetworkPolicy that allows Valkey→Sentinel and Sentinel↔Sentinel traffic. It restricts ingress to the Sentinel port from Valkey and Sentinel pods, and (when operatorNamespace is non-empty) also from all pods in the operator namespace so the operator can reach Sentinel pods for health checks.

func BuildSentinelStatefulSet 

func BuildSentinelStatefulSet(v *vkov1.Valkey) *appsv1.StatefulSet

BuildSentinelStatefulSet builds the StatefulSet for Sentinel instances.

func BuildSidecarRole added in v1.1.0 

func BuildSidecarRole(v *vkov1.Valkey) *rbacv1.Role

BuildSidecarRole builds the namespaced Role for the sidecar container. The role grants patch access to pods owned by this Valkey instance so the sidecar can update the instanceRole label on its own pod.

func BuildSidecarRoleBinding added in v1.1.0 

func BuildSidecarRoleBinding(v *vkov1.Valkey) *rbacv1.RoleBinding

BuildSidecarRoleBinding builds the RoleBinding that binds the sidecar Role to its ServiceAccount.

func BuildSidecarServiceAccount added in v1.1.0 

func BuildSidecarServiceAccount(v *vkov1.Valkey) *corev1.ServiceAccount

BuildSidecarServiceAccount builds the ServiceAccount for the sidecar container. Each Valkey instance gets its own ServiceAccount to limit blast radius.

func BuildStatefulSet 

func BuildStatefulSet(v *vkov1.Valkey, operatorImage string) *appsv1.StatefulSet

BuildStatefulSet builds the StatefulSet for Valkey instances. operatorImage is the container image of the operator, used for the sidecar container.

func BuildValkeyCertificate 

func BuildValkeyCertificate(v *vkov1.Valkey) *unstructured.Unstructured

BuildValkeyCertificate builds the cert-manager Certificate resource for Valkey pods.

func BuildValkeyNetworkPolicy 

func BuildValkeyNetworkPolicy(v *vkov1.Valkey, operatorNamespace string) *networkingv1.NetworkPolicy

BuildValkeyNetworkPolicy builds the NetworkPolicy that allows Valkey↔Valkey and Sentinel→Valkey traffic within the cluster. It restricts ingress to the Valkey port from other Valkey pods, Sentinel pods, and (when operatorNamespace is non-empty) all pods in the operator namespace so the operator can reach Valkey pods for health checks (e.g. INFO replication). It unconditionally allows ingress on the sidecar health port from all sources so that kubelet readiness/liveness probes always succeed.

func CertificateOwnerRef 

func CertificateOwnerRef(v *vkov1.Valkey) metav1.OwnerReference

CertificateOwnerRef returns an OwnerReference for setting on Certificate resources.

func ComputeConfigHash added in v1.3.0 

func ComputeConfigHash(v *vkov1.Valkey) string

ComputeConfigHash returns a short hex digest representing the generated Valkey (and Sentinel, if applicable) configuration content. It is embedded in the StatefulSet pod template annotations so that config changes — such as toggling allowUnencrypted — cause the pod template annotation to change. The operator's rolling update logic detects the annotation mismatch on running pods and triggers a controlled rolling restart.

Only pods that already carry the AnnotationConfigHash annotation are checked; pods created by an older operator version (without the annotation) are not forced to restart until they are replaced for another reason.

func ComputePodSpecHash added in v1.4.1 

func ComputePodSpecHash(v *vkov1.Valkey, operatorImage string) string

ComputePodSpecHash returns a short hex digest of the pod spec built for this Valkey CR. It is embedded in the StatefulSet pod template annotations so that any change to the pod specification (resources, probes, volumes, env vars, etc.) is detected by the rolling update logic — even though the StatefulSet uses the OnDelete update strategy.

func ComputeSentinelPodSpecHash added in v1.4.1 

func ComputeSentinelPodSpecHash(v *vkov1.Valkey) string

ComputeSentinelPodSpecHash returns a short hex digest of the sentinel pod spec built for this Valkey CR. Works identically to ComputePodSpecHash but for sentinel pods.

func ConfigMapName 

func ConfigMapName(v *vkov1.Valkey) string

ConfigMapName returns the name for the Valkey ConfigMap.

func DesiredServicePort 

func DesiredServicePort(v *vkov1.Valkey) corev1.ServicePort

DesiredServicePort returns the port spec for Services, accounting for TLS.

func GenerateSentinelConf 

func GenerateSentinelConf(v *vkov1.Valkey) string

GenerateSentinelConf generates the sentinel.conf content based on the CRD spec. If the Valkey CR carries the AnnotationKnownMaster annotation (set by the operator after a successful sentinel failover), that address is used as the sentinel monitor target instead of the default pod-0 DNS address. This ensures that sentinel pods which restart after a rolling-update failover immediately connect to the actual current master rather than a stale pod-0 replica.

func GenerateSentinelConfForHash added in v1.3.0 

func GenerateSentinelConfForHash(v *vkov1.Valkey) string

GenerateSentinelConfForHash generates sentinel.conf without the AnnotationKnownMaster override. Use this when computing the config hash for pod update detection. The AnnotationKnownMaster changes during rolling-update failovers (it is set by persistKnownMaster) and must NOT affect the hash — including it would cause all pods to appear outdated immediately after a failover, triggering an infinite restart loop.

func GenerateValkeyConf 

func GenerateValkeyConf(v *vkov1.Valkey, isReplica bool) string

GenerateValkeyConf generates the valkey.conf content based on the CRD spec. The isReplica parameter controls whether replicaof directives are included. When the Valkey CR carries the AnnotationKnownMaster annotation (set after a sentinel failover), the replica config's replicaof directive uses that address instead of the default pod-0 address.

func GenerateValkeyConfForHash added in v1.9.0 

func GenerateValkeyConfForHash(v *vkov1.Valkey, isReplica bool) string

GenerateValkeyConfForHash generates the valkey.conf content without using the AnnotationKnownMaster override. Use this when computing the config hash for pod update detection. The AnnotationKnownMaster changes during rolling-update failovers (set by persistKnownMaster) and must NOT affect the hash — including it would cause all pods to appear outdated immediately after a failover, triggering an infinite restart loop.

func MasterAddress 

func MasterAddress(v *vkov1.Valkey) string

MasterAddress returns the DNS address of the master pod (pod-0 of the StatefulSet). Used for `replicaof` configuration in replica pods.

func NetworkPolicyHasChanged 

func NetworkPolicyHasChanged(desired, current *networkingv1.NetworkPolicy) bool

NetworkPolicyHasChanged returns true if the desired NetworkPolicy differs from the current one. Uses reflect.DeepEqual for ingress rule comparison to correctly handle all peer types (PodSelector, NamespaceSelector, or combined peers).

func NetworkPolicyName 

func NetworkPolicyName(v *vkov1.Valkey) string

NetworkPolicyName returns the name for the Valkey NetworkPolicy.

func ObserverDeploymentHasChanged added in v1.5.0 

func ObserverDeploymentHasChanged(desired, current *appsv1.Deployment) bool

ObserverDeploymentHasChanged returns true if the desired observer Deployment differs from the current one in meaningful ways.

func ObserverDeploymentName added in v1.5.0 

func ObserverDeploymentName(v *vkov1.Valkey) string

ObserverDeploymentName returns the name for the observer Deployment.

func ObserverLabels added in v1.5.0 

func ObserverLabels(v *vkov1.Valkey) map[string]string

ObserverLabels returns the labels for observer resources.

func ObserverNetworkPolicyName added in v1.5.0 

func ObserverNetworkPolicyName(v *vkov1.Valkey) string

ObserverNetworkPolicyName returns the name for the observer NetworkPolicy.

func ObserverSelectorLabels added in v1.5.0 

func ObserverSelectorLabels(v *vkov1.Valkey) map[string]string

ObserverSelectorLabels returns the minimal label set for observer selectors.

func OperatorVersionChanged added in v1.2.0 

func OperatorVersionChanged(current metav1.Object, version string) bool

OperatorVersionChanged returns true when the annotation on current does not match version, indicating that the resource was last reconciled by a different operator version and should be updated.

func ProbeCommand 

func ProbeCommand(v *vkov1.Valkey) []string

ProbeCommand returns the probe command, accounting for TLS and auth. When auth is enabled, the probe uses a shell command to expand the VALKEY_PASSWORD environment variable for the -a flag.

func RWServiceName added in v1.1.0 

func RWServiceName(v *vkov1.Valkey) string

RWServiceName returns the name for the read-write Service (<name>-rw). This service routes only to the master pod.

func ReadOnlyServiceName added in v1.1.0 

func ReadOnlyServiceName(v *vkov1.Valkey) string

ReadOnlyServiceName returns the name for the read-only replica Service (<name>-r). This service routes only to replica pods.

func ReplicaConfigMapName 

func ReplicaConfigMapName(v *vkov1.Valkey) string

ReplicaConfigMapName returns the name for the replica Valkey ConfigMap (HA mode).

func SentinelCertificateName 

func SentinelCertificateName(v *vkov1.Valkey) string

SentinelCertificateName returns the name of the Certificate resource for Sentinel pods.

func SentinelConfigMapName 

func SentinelConfigMapName(v *vkov1.Valkey) string

SentinelConfigMapName returns the name for the Sentinel ConfigMap.

func SentinelMonitorName 

func SentinelMonitorName(v *vkov1.Valkey) string

SentinelMonitorName returns the name used for the `sentinel monitor` directive.

func SentinelNetworkPolicyName 

func SentinelNetworkPolicyName(v *vkov1.Valkey) string

SentinelNetworkPolicyName returns the name for the Sentinel NetworkPolicy.

func SentinelProbeCommand added in v1.1.6 

func SentinelProbeCommand(v *vkov1.Valkey) []string

SentinelProbeCommand returns the exec probe command for a Sentinel container, accounting for TLS and auth configuration.

When TLS is enabled the probe uses valkey-cli with TLS flags. The Sentinel TLS config uses tls-auth-clients optional, so no client certificate is required — only the CA cert is needed for server verification. When auth is enabled, the password is read from the VALKEY_PASSWORD env var that is injected into the Sentinel container.

func SentinelStatefulSetHasChanged 

func SentinelStatefulSetHasChanged(desired, current *appsv1.StatefulSet) bool

SentinelStatefulSetHasChanged returns true if the live Sentinel StatefulSet differs from desired. It checks replicas and the full pod template spec (containers, init containers, volumes, ServiceAccountName, TerminationGracePeriodSeconds, labels, and annotations).

func SentinelTLSSecretName 

func SentinelTLSSecretName(v *vkov1.Valkey) string

SentinelTLSSecretName returns the name of the Secret that holds TLS certs for Sentinel. When cert-manager is used in unified mode, the Valkey Secret is shared. When cert-manager is used in default mode, a separate Certificate is created for Sentinel. When a user-provided secret is used, the same secret is shared.

func ServicePort 

func ServicePort(v *vkov1.Valkey) int32

ServicePort returns the Valkey client port, accounting for TLS configuration.

func SidecarServiceAccountName added in v1.1.0 

func SidecarServiceAccountName(v *vkov1.Valkey) string

SidecarServiceAccountName returns the name of the ServiceAccount used by the sidecar container.

func StatefulSetHasChanged 

func StatefulSetHasChanged(desired, current *appsv1.StatefulSet) bool

StatefulSetHasChanged returns true if the live StatefulSet differs from the desired spec in ways that require an update (replicas, pod template spec).

func ValkeyCertificateName 

func ValkeyCertificateName(v *vkov1.Valkey) string

ValkeyCertificateName returns the name of the Certificate resource for Valkey pods.

func ValkeyTLSSecretName 

func ValkeyTLSSecretName(v *vkov1.Valkey) string

ValkeyTLSSecretName returns the name of the Secret that holds TLS certs for Valkey. When cert-manager is used, this is the Secret created by the Certificate resource. When a user-provided secret is used, this returns the user's secret name.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.