Documentation
¶
Overview ¶
Package names generates deterministic, unique names for Kubernetes objects.
Strategy:
- For dynamic, user-defined, or nested resources (e.g., Cells, TableGroups, Shards), we use JoinWithConstraints to append a safety hash. This prevents collisions when strings are truncated to fit Kubernetes length limits (e.g., 63 chars for labels).
- For singleton or static resources (e.g., GlobalTopo, MultiAdmin) that are 1:1 with the cluster and have predictable short names, we use simple string concatenation without hashing for better readability and predictability.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultConstraints are the name constraints for objects in Kubernetes // that don't have any special rules. DefaultConstraints = Constraints{ MaxLength: 253, ValidFirstChar: isLowercaseAlphanumeric, } // ServiceConstraints are name constraints for Service objects. ServiceConstraints = Constraints{ MaxLength: 63, ValidFirstChar: isLowercaseLetter, } // StatefulSetConstraints are name constraints for StatefulSet objects. // We need to account for the suffix appended to the Pod name, e.g. "-0", // as well as the controller-revision-hash label which appends a hash. // To be safe, we reserve 11 characters for the suffix/hash. // 63 - 11 = 52. StatefulSetConstraints = Constraints{ MaxLength: 52, ValidFirstChar: isLowercaseLetter, } // PodConstraints are name constraints for directly-managed Pod objects. // Pods are DNS labels (max 63 chars). We reserve 3 characters for the // "-{index}" suffix (supports indices 0-99, matching ReplicasPerCell max). // 63 - 3 = 60. PodConstraints = Constraints{ MaxLength: 60, ValidFirstChar: isLowercaseLetter, } )
Functions ¶
func JoinWithConstraints ¶
func JoinWithConstraints(cons Constraints, parts ...string) string
JoinWithConstraints builds a name by concatenating a number of parts with '-' as the separator, and then enforcing some constraints on the resulting name while maintaining uniqueness and determinism with respect to the input values.
It will append a hash at the end that depends only on the parts supplied. If the function is called again with the same parts, in the same order, the hash will also be the same. This determinism allows you to use the resulting name to ensure idempotency when creating objects.
However, the hash will differ if the parts are rearranged, or if substrings within parts are moved to adjacent parts. The resulting generated name, while deterministic, is thus guaranteed to be unique for a given list of parts, even if the parts themselves are allowed to contain the separator.
For example: JoinWithConstraints(cons, "a-b", "c") != JoinWithConstraints(cons, "a", "b-c") Although both will begin with "a-b-c-", the hash at the end will be different.
The constraints passed in should be appropriate for the kind of object (e.g. Pod, Service) whose name is being generated, to ensure the name is accepted by Kubernetes validation. Most objects in Kubernetes accept any name that conforms to the DefaultConstraints, with the notable exception of Service objects which must conform to ServiceConstraints. Custom constraints, such as for a CRD that adds its own naming requirements, can be expressed by defining a new Constraints object.
Types ¶
type Constraints ¶
type Constraints struct {
// MaxLength is the maximum length of the output, to be enforced after any
// transformations and including the hash suffix. If a name has to be
// truncated to fit within this maximum length, the hash at the end will be
// preceded by a special truncation mark: "---" rather than the usual "-".
//
// MaxLength must be at least 12 because that's the shortest possible
// truncated value (1 char + truncation mark + hash). Passing a value less
// than 12 will result in a panic.
MaxLength int
// ValidFirstChar is a function that returns whether the given rune is
// allowed as the first character in the output.
ValidFirstChar func(r rune) bool
}
Constraints specifies rules that the output of JoinWithConstraints must follow.
Source Files