resolver

package
v0.10.2 Latest Latest
Warning

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

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

Documentation

Overview

Package resolver provides the central logic for calculating the "Effective Specification" of a MultigresCluster.

In the Multigres Operator, a cluster's configuration can come from multiple sources:

  1. Inline Configurations (defined directly in the MultigresCluster CR).
  2. Template References (pointing to CoreTemplate, CellTemplate, or ShardTemplate CRs).
  3. Hardcoded Defaults (fallback values for safety).

The Resolver is the single source of truth for determining the final configuration. It ensures that the Reconciler and the Webhook always agree on what the final configuration should be.

Logic Hierarchy

When calculating the final configuration for a component, the Resolver applies the following precedence (highest to lowest):

  1. Inline Spec (if provided, it takes precedence over the template).
  2. Template Spec (the base configuration from the referenced CR).
  3. Global Defaults (hardcoded constants like default images or replicas).

Dual Usage

This package is designed to be used in two distinct phases:

  1. Mutation (Webhook): The 'PopulateClusterDefaults' method is safe to call during admission. It applies static defaults (images) and "Smart Defaults" (injecting mandatory system databases, table groups, and shards) to the API object itself. This solves the "Invisible Defaults" problem without making external API calls.

  2. Reconciliation (Controller): The 'Resolve...' methods (e.g., ResolveGlobalTopo) are used during reconciliation. They fetch external templates from the API server and determine the effective configuration by checking for inline definitions vs. template references.

  3. Validation (Webhook): The 'Validate...' methods (e.g. ValidateClusterIntegrity) are used during admission to enforce strict referential integrity and logical consistency. They simulate the resolution process to catch configuration errors (like referencing missing templates or invalid overrides) before the cluster is persisted.

Usage: 

	// Create a resolver
	res := resolver.NewResolver(client, namespace)

	// Webhook: Apply static and smart defaults to the object
	res.PopulateClusterDefaults(cluster)

 // Webhook: Validate the cluster structure
 if err := res.ValidateClusterIntegrity(ctx, cluster); err != nil {
     return err
 }

	// Controller: Calculate final config for a specific component
	// This handles the Inline > Template > Default precedence logic
	globalTopoSpec, err := res.ResolveGlobalTopo(ctx, cluster)

Index

Constants

View Source 
const (
	// DefaultEtcdReplicas is the default number of replicas for the managed Etcd cluster if not specified.
	DefaultEtcdReplicas int32 = 3

	// DefaultAdminReplicas is the default number of replicas for the MultiAdmin deployment if not specified.
	DefaultAdminReplicas int32 = 1

	// FallbackCoreTemplate is the name of the template to look for if no specific CoreTemplate is referenced.
	FallbackCoreTemplate = "default"

	// FallbackCellTemplate is the name of the template to look for if no specific CellTemplate is referenced.
	FallbackCellTemplate = "default"

	// FallbackShardTemplate is the name of the template to look for if no specific ShardTemplate is referenced.
	FallbackShardTemplate = "default"

	// DefaultPoolName is the name used for the default pool when no pools are specified in a ShardTemplate.
	DefaultPoolName = "default"

	// DefaultTopoRootPath is the default etcd key prefix for the global topology server.
	DefaultTopoRootPath = "/multigres/global"

	// DefaultTopoImplementation is the default client implementation for external topology servers.
	DefaultTopoImplementation = "etcd"

	// DefaultSystemDatabaseName is the name of the mandatory system database.
	DefaultSystemDatabaseName = "postgres"

	// DefaultSystemTableGroupName is the name of the mandatory default table group.
	DefaultSystemTableGroupName = "default"

	// DefaultMultiAdminWebReplicas is the default number of replicas for the MultiAdminWeb deployment if not specified.
	DefaultMultiAdminWebReplicas int32 = 1

	// DefaultImagePullPolicy is the default image pull policy used for all components if not specified.
	DefaultImagePullPolicy = corev1.PullIfNotPresent

	// DefaultEtcdStorageSize is the default PVC size for the managed Etcd cluster if not specified.
	DefaultEtcdStorageSize = "1Gi"

	// DefaultBackupPath is the default filesystem path for backups.
	DefaultBackupPath = "/backups"

	// DefaultBackupStorageSize is the default PVC size for backup storage.
	DefaultBackupStorageSize = "10Gi"

	// DefaultDurabilityPolicy is the default durability policy for databases.
	// Upstream multiorch currently supports: AT_LEAST_2, MULTI_CELL_AT_LEAST_2.
	// More user-defined policies will be added in the future.
	DefaultDurabilityPolicy = "AT_LEAST_2"

	// Image defaults re-exported from the canonical source in api/v1alpha1.
	DefaultPostgresImage      = multigresv1alpha1.DefaultPostgresImage
	DefaultEtcdImage          = multigresv1alpha1.DefaultEtcdImage
	DefaultMultiAdminImage    = multigresv1alpha1.DefaultMultiAdminImage
	DefaultMultiAdminWebImage = multigresv1alpha1.DefaultMultiAdminWebImage
	DefaultMultiOrchImage     = multigresv1alpha1.DefaultMultiOrchImage
	DefaultMultiPoolerImage   = multigresv1alpha1.DefaultMultiPoolerImage
	DefaultMultiGatewayImage  = multigresv1alpha1.DefaultMultiGatewayImage

	// DefaultLogLevel is the default log level for all multigres data-plane components.
	DefaultLogLevel = multigresv1alpha1.LogLevel("info")
)

Variables

This section is empty.

Functions

func DefaultResourcesAdmin 

func DefaultResourcesAdmin() corev1.ResourceRequirements

DefaultResourcesAdmin returns the default resource requests and limits for the MultiAdmin deployment.

func DefaultResourcesAdminWeb 

func DefaultResourcesAdminWeb() corev1.ResourceRequirements

DefaultResourcesAdminWeb returns the default resource requests and limits for the MultiAdminWeb deployment.

func DefaultResourcesEtcd 

func DefaultResourcesEtcd() corev1.ResourceRequirements

DefaultResourcesEtcd returns the default resource requests and limits for the managed Etcd cluster.

func DefaultResourcesGateway 

func DefaultResourcesGateway() corev1.ResourceRequirements

DefaultResourcesGateway returns the default resource requests and limits for the MultiGateway deployment.

func DefaultResourcesOrch 

func DefaultResourcesOrch() corev1.ResourceRequirements

DefaultResourcesOrch returns the default resource requests and limits for the MultiOrch deployment.

func DefaultResourcesPooler 

func DefaultResourcesPooler() corev1.ResourceRequirements

DefaultResourcesPooler returns the default resources for the Multipooler container in a pool.

func DefaultResourcesPostgres 

func DefaultResourcesPostgres() corev1.ResourceRequirements

DefaultResourcesPostgres returns the default resources for the Postgres container in a pool.

func ValidatePoolName 

func ValidatePoolName(name multigresv1alpha1.PoolName) error

ValidatePoolName checks that a pool name is a valid DNS label within length limits. CRD structural schema does not enforce validation markers on map keys, so pool names must be validated explicitly.

Types

type Resolver 

type Resolver struct {
	Client             client.Client
	Namespace          string
	CoreTemplateCache  map[string]*multigresv1alpha1.CoreTemplate
	CellTemplateCache  map[string]*multigresv1alpha1.CellTemplate
	ShardTemplateCache map[string]*multigresv1alpha1.ShardTemplate
}

Resolver handles the logic for fetching templates and calculating defaults. It serves as the single source of truth for defaulting logic across the operator.

func NewResolver 

func NewResolver(
	c client.Client,
	namespace string,
) *Resolver

NewResolver creates a new defaults.Resolver.

func (*Resolver) CellTemplateExists 

func (r *Resolver) CellTemplateExists(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (bool, error)

CellTemplateExists checks if a CellTemplate with the given name exists in the current namespace.

func (*Resolver) CoreTemplateExists 

func (r *Resolver) CoreTemplateExists(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (bool, error)

CoreTemplateExists checks if a CoreTemplate with the given name exists in the current namespace.

func (*Resolver) PopulateClusterDefaults 

func (r *Resolver) PopulateClusterDefaults(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) ([]string, error)

PopulateClusterDefaults applies static defaults to the Cluster Spec.

func (*Resolver) ResolveCell 

func (r *Resolver) ResolveCell(
	ctx context.Context,
	cellSpec *multigresv1alpha1.CellConfig,
) (*multigresv1alpha1.StatelessSpec, *multigresv1alpha1.PodPlacementSpec, *multigresv1alpha1.LocalTopoServerSpec, error)

ResolveCell determines the final configuration for a specific Cell. It orchestrates: Template Lookup -> Fetch -> Merge -> Defaulting.

func (*Resolver) ResolveCellTemplate 

func (r *Resolver) ResolveCellTemplate(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (*multigresv1alpha1.CellTemplate, error)

ResolveCellTemplate fetches and resolves a CellTemplate by name.

func (*Resolver) ResolveCoreTemplate 

func (r *Resolver) ResolveCoreTemplate(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (*multigresv1alpha1.CoreTemplate, error)

ResolveCoreTemplate fetches and resolves a CoreTemplate by name, using the request-scoped cache.

func (*Resolver) ResolveGlobalTopo 

func (r *Resolver) ResolveGlobalTopo(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) (*multigresv1alpha1.GlobalTopoServerSpec, error)

ResolveGlobalTopo determines the final GlobalTopoServer configuration.

func (*Resolver) ResolveMultiAdmin 

func (r *Resolver) ResolveMultiAdmin(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) (*multigresv1alpha1.StatelessSpec, error)

ResolveMultiAdmin determines the final MultiAdmin configuration.

func (*Resolver) ResolveMultiAdminWeb 

func (r *Resolver) ResolveMultiAdminWeb(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) (*multigresv1alpha1.StatelessSpec, error)

ResolveMultiAdminWeb determines the final MultiAdminWeb configuration.

func (*Resolver) ResolveShard 

func (r *Resolver) ResolveShard(
	ctx context.Context,
	shardSpec *multigresv1alpha1.ShardConfig,
	allCellNames []multigresv1alpha1.CellName,
	inheritedBackup *multigresv1alpha1.BackupConfig,
) (*multigresv1alpha1.MultiOrchSpec, map[multigresv1alpha1.PoolName]multigresv1alpha1.PoolSpec, *multigresv1alpha1.PVCDeletionPolicy, *multigresv1alpha1.BackupConfig, multigresv1alpha1.InitdbArgs, *multigresv1alpha1.PostgresConfigRef, error)

ResolveShard determines the final configuration for a specific Shard.

func (*Resolver) ResolveShardTemplate 

func (r *Resolver) ResolveShardTemplate(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (*multigresv1alpha1.ShardTemplate, error)

ResolveShardTemplate fetches and resolves a ShardTemplate by name.

func (*Resolver) ShardTemplateExists 

func (r *Resolver) ShardTemplateExists(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) (bool, error)

ShardTemplateExists checks if a ShardTemplate with the given name exists in the current namespace.

func (*Resolver) ValidateCellTemplateReference 

func (r *Resolver) ValidateCellTemplateReference(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) error

ValidateCellTemplateReference checks if a CellTemplate reference is valid. See ValidateCoreTemplateReference for logic details.

func (*Resolver) ValidateClusterIntegrity 

func (r *Resolver) ValidateClusterIntegrity(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) error

ValidateClusterIntegrity checks that all templates referenced by the cluster actually exist. This corresponds to the Level 4 Referential Integrity check.

This method is primarily used by the Validating Webhook to reject clusters with broken references.

func (*Resolver) ValidateClusterLogic 

func (r *Resolver) ValidateClusterLogic(
	ctx context.Context,
	cluster *multigresv1alpha1.MultigresCluster,
) (admission.Warnings, error)

ValidateClusterLogic performs deep logic checks and strict validation on the cluster configuration. It simulates the resolution process to identify broken references, empty cells, or invalid overrides.

This method is primarily used by the Validating Webhook to enforce logical correctness.

func (*Resolver) ValidateCoreTemplateReference 

func (r *Resolver) ValidateCoreTemplateReference(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) error

ValidateCoreTemplateReference checks if a CoreTemplate reference is valid. It returns nil if: 1. The name is empty (no reference). 2. The name matches the FallbackCoreTemplate (assumed to be a system default or implicitly allowed). 3. The referenced CoreTemplate exists in the Resolver's namespace. Otherwise, it returns an error.

func (*Resolver) ValidateShardTemplateReference 

func (r *Resolver) ValidateShardTemplateReference(
	ctx context.Context,
	name multigresv1alpha1.TemplateRef,
) error

ValidateShardTemplateReference checks if a ShardTemplate reference is valid. See ValidateCoreTemplateReference for logic details.

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.