names

package
v1.1.2 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	FinalizerController     = "cybericebox.com/controller"
	FinalizerVPN            = "cybericebox.com/vpn"
	FinalizerGateway        = "cybericebox.com/gateway"
	FinalizerLab            = "cybericebox.com/lab"
	FinalizerLabGroup       = "cybericebox.com/labgroup"
	FinalizerLabGroupClient = "cybericebox.com/labgroupclient"
	FinalizerNodeAgent      = "cybericebox.com/node-agent"
	FinalizerOVSCleanup     = "cybericebox.com/ovs-cleanup"
)

Finalizer strings set by each controller/binary component. Every controller that adds or checks a finalizer must use these constants.

View Source
const (
	// MaxIDLen is the longest client-supplied object id (LabGroup, Lab, LabGroupClient,
	// deploy group).
	MaxIDLen = 64
	// MaxLabDevices is the hard ceiling of the devices of one lab, every type counted (container, switch, hub); the CRD carries the same
	// number. The chart's limits.lab.maxDevices (default 32) can only lower it, and the chart refuses a larger value.
	MaxLabDevices = 64
	// MaxContainerInterfaces is the most interfaces of a container device (a switch or hub has its fixed 48 ports): one device cannot open
	// thousands of direct connections.
	MaxContainerInterfaces = 16
	MaxSwitchPorts         = 48
	// MaxDeployAfter is the most deploy_after keys of one object.
	MaxDeployAfter = 32

	// AnnotationID holds the id a client gave an object: the CR name is derived from
	// it (EncodeName) and every answer returns the original.
	AnnotationID = LabelPrefix + "id"
	// AnnotationDeployGroup holds the original deploy group (the label holds DeployKey of it).
	AnnotationDeployGroup = LabelPrefix + "deploy-group"
	// AnnotationIDMap is JSON {encoded: original} of the object names a policy refers to
	// whose CR name differs from the id.
	AnnotationIDMap = LabelPrefix + "id-map"
)
View Source
const (
	LabelLab    = "laboratory.cybericebox.com/lab"
	LabelDevice = "laboratory.cybericebox.com/device"
	LabelGroup  = "laboratory.cybericebox.com/group"
	// LabelDeployGroup is the scheduler group of a Lab or LabGroup (a key of at
	// most 63 characters). Objects with the same key are dispatched together.
	// Operator-internal: the scheduler reads it and no user label.
	LabelDeployGroup = LabelPrefix + "deploy-group"

	// LabelNodeAgentReady is set to "true" on a node by the node-agent running there once it can serve pods, and removed when it stops.
	// Every lab pod requires it (through the lab node selector of the chart), so no lab pod lands on a node without a working
	// node-agent (a pod there would have no cni-gate and no OVS wiring).
	LabelNodeAgentReady = LabelPrefix + "node-agent-ready"

	// TopologyKeyHostname is the well-known node label used as the topology key
	// for per-node scheduling constraints (device co-location).
	TopologyKeyHostname = "kubernetes.io/hostname"
)

Kubernetes label keys.

View Source
const (
	// AnnotationDeployAfter lists, comma separated, the deploy groups that must be
	// complete (every pod Ready or failed) before the group of this object starts.
	AnnotationDeployAfter = LabelPrefix + "deploy-after"

	// AnnotationDeployPriority is an explicit dispatch priority of a Lab or LabGroup (an integer, 0 when absent or not a
	// number): within the same deploy group (or among independent objects) a higher one is dispatched first, whatever the
	// size; at equal priority the larger lab goes first.
	AnnotationDeployPriority = LabelPrefix + "deploy-priority"

	// AnnotationSpecHash is written by the management agent on the objects it
	// creates; the operator ignores it.
	AnnotationSpecHash = LabelPrefix + "spec-hash"

	// AnnotationUserLabels lists the user labels copied onto an object from its
	// Lab or LabGroup, so a label removed there is removed here too.
	AnnotationUserLabels = LabelPrefix + "user-labels"

	// AnnotationNetworks is the pod annotation listing the OVS network attachments of a DEVICE pod. The VPN and gateway pods of a group have none:
	// the node-agent derives their lab interfaces from the group's LabVPN and LabGateway objects.
	// Format: comma-separated "iface@name[|MAC]" entries.
	AnnotationNetworks = "network.cybericebox.com/networks"

	// AnnotationDefaultNetwork controls how cni-gate handles the default k8s network.
	// Missing: regular pod — delegate eth0 to k8s CNI as normal.
	// Empty "": no default network — cni-gate returns stub eth0 only.
	// Non-empty: interface name to wire via k8s CNI (e.g. "accessport").
	AnnotationDefaultNetwork = "network.cybericebox.com/default-network"

	// AnnotationConntrackAccounting on a pod asks the node-agent to switch on conntrack byte accounting and flow
	// timestamps in the pod's network namespace when the pod is wired (CNI ADD). The pod cannot do it itself without
	// being privileged (/proc/sys is read-only for an unprivileged container).
	AnnotationConntrackAccounting = "network.cybericebox.com/conntrack-accounting"

	// AnnotationDevice tags a pod/resource with its logical device name.
	AnnotationDevice = "cybericebox.com/device"

	// DefaultEth0 is the standard container ethernet interface name.
	DefaultEth0 = "eth0"

	// AccessPortIface is the reserved in-pod interface name that carries the
	// delegated Kubernetes network for web-exposed device pods. Lab interface
	// names must not collide with it: SetupNetworks would delete/replace the
	// delegated interface on a kubelet CNI retry.
	AccessPortIface = "accessport"

	// AccessPortRouteTable is the routing table that holds every route of the access port inside the pod. The rule
	// "from <access port address> lookup <table>" sends the replies back out of the port; the main table, where the lab
	// interfaces and their default gateway live, never holds a route through it (see package accessroute).
	AccessPortRouteTable = 100
	// AccessPortRulePriority is the priority of that rule: above the main table (32766), so the replies never reach
	// the lab's default route.
	AccessPortRulePriority = 1000
)

Kubernetes annotation keys.

View Source
const (
	ComponentGateway = "gateway"
	ComponentVPN     = "vpn"
)

Component names used for Deployment names, Service names, and app label values.

View Source
const (
	RoleVPNName     = "laboratory-vpn-role"
	RoleGatewayName = "laboratory-gateway-role"
	RoleAgentName   = "laboratory-agent-role"
	// RoleOperatorNamespacedName is the ClusterRole with the operator's working permissions INSIDE a namespace;
	// OperatorRoleBindingName is the RoleBinding that grants it in each LabGroup namespace.
	RoleOperatorNamespacedName = "laboratory-operator-namespaced"
	OperatorRoleBindingName    = "laboratory-operator-binding"

	// RoleProxyReportsName is the ClusterRole with the one thing the L7 proxy writes in a LabGroup namespace (its LabTrafficReports);
	// ProxyReportsBindingName is the RoleBinding that grants it there. The proxy has no such right cluster-wide.
	RoleProxyReportsName    = "laboratory-proxy-reports"
	ProxyReportsBindingName = "laboratory-proxy-reports-binding"

	// AgentRoleBindingName is the RoleBinding created in each LabGroup namespace
	// that grants the management-agent ServiceAccount access via RoleAgentName,
	// gated by LabGroupReconciler.AgentEnabled.
	AgentRoleBindingName = "laboratory-agent-binding"
)

RBAC resource names created per LabGroup namespace.

View Source
const (
	SecretVPNKeypair   = "vpn-server-keypair"
	SecretClientPrefix = "client-"
)

Secret name patterns.

View Source
const (
	AgentNamespace      = "laboratory-agent"
	AgentServiceAccount = "laboratory-agent"
)

AgentNamespace is the Kubernetes namespace where the management agent runs; AgentServiceAccount is its ServiceAccount (the operator binds it in every LabGroup namespace). They are the defaults of the chart (agent.namespace); the operator and the agent take other values from AGENT_SERVICE_NAMESPACE, AGENT_SERVICE_ACCOUNT, OPERATOR_NAMESPACE, OPERATOR_SERVICE_ACCOUNT.

View Source
const (
	VNIPoolPrefix = "vni"
	VNIPoolSize   = uint(65000)

	PoolLabSubnets = "lab-subnets"
	PoolVPNClients = "vpn-clients"
)

Pool names and parameters used by the allocation subsystem.

View Source
const (
	// RegistryServiceAddr is host:port of the platform registry (zot) Service inside the cluster. The chart installs it in the release
	// namespace under this name and always installs it.
	RegistryServiceAddr = "laboratory-registry." + SystemNamespace + ".svc:5000"
	// RegistryForwardPort is the port on which the node-agent of every node relays the registry on the loopback, so that the container
	// runtime pulls from localhost:<port> (plain HTTP, no node configuration). It must be free on the node.
	RegistryForwardPort = 5035
)
View Source
const (
	// AnnotationStateEpoch is set on a snapshot-backed device pod: the reset
	// epoch it was created in. The node-agent ignores snapshots of pods whose
	// epoch is older than the device's current one.
	AnnotationStateEpoch = "state.cybericebox.com/epoch"
	// AnnotationStateRescue is "true" on a device pod started in rescue mode.
	AnnotationStateRescue = "state.cybericebox.com/rescue"
	// AnnotationStateDevice is set on a snapshot-backed device pod and holds
	// the name of the Device CR, so the node-agent finds the policy and the
	// status without parsing pod names.
	AnnotationStateDevice = "state.cybericebox.com/device"
	// AnnotationStateIncarnation is the incarnation number of a snapshot-backed
	// device pod; the node-agent records snapshots only for the current one.
	AnnotationStateIncarnation = "state.cybericebox.com/incarnation"
)
View Source
const (
	// MaxDeviceNameLen is the longest device name a lab may have. A web-exposed
	// device is served at <device>-<code>.<base domain>, and the wildcard cert
	// covers one label level, so <device>-<code> must fit one DNS label (<=63):
	// device + "-" + a code of at most WebCodeMaxLen chars. 35 is a round,
	// predictable limit with plenty of headroom. Longer names are rejected, never
	// truncated: truncation could make two devices collide.
	MaxDeviceNameLen = 35

	// WebCodeLen is the usual length of the random code of a web host label.
	WebCodeLen = 3
	// WebCodeMaxLen is the longest code ever used; it is the fallback length
	// after WebCodeAttempts collisions at WebCodeLen.
	WebCodeMaxLen = 4
	// WebCodeAttempts is how many codes of WebCodeLen are tried before the
	// operator widens the code to WebCodeMaxLen.
	WebCodeAttempts = 8
)
View Source
const AccessKeysNamespace = "laboratory-access-keys"

AccessKeysNamespace holds the access public keys of the tenants, one Secret each (AccessKeysSecret). The L7 proxy reads this namespace and no other: the tenants namespace holds enrollment tokens and registry credentials, which an internet-facing component must not be able to read.

View Source
const AnnotationLabCreation = "laboratory.cybericebox.com/creation-receipt"
View Source
const AnnotationLabVariableAdmission = "laboratory.cybericebox.com/variable-admission"

AnnotationLabVariableAdmission serializes write-only Secret updates against permanent retirement. It stores only a SHA256 retry token, never values.

View Source
const AnnotationLifecycleRetirement = "laboratory.cybericebox.com/lifecycle-retirement"

AnnotationLifecycleRetirement is a permanent fenced tombstone intent. It is separate from expiry-driven snapshot-only retention and blocks future Start.

View Source
const AnnotationRegenerateEnrollment = LabelPrefix + "regenerate-enrollment-token"

AnnotationRegenerateEnrollment on a Tenant asks the operator for a new enrollment token; the operator removes it once done.

View Source
const AnnotationSnapshotRetirement = LabelPrefix + "snapshot-retirement"

AnnotationSnapshotRetirement is an irreversible repository-retirement fence, written at the accepted deadline only after exact stopped/released observation.

View Source
const DefaultTenant = "default"

DefaultTenant is the tenant of a caller without a client certificate (TLS or mTLS off) and of objects that carry no tenant label.

View Source
const EnrollmentTokenKey = "token"

EnrollmentTokenKey is the data key of the token in the enrollment Secret.

View Source
const ImagesNamespace = "laboratory-images"

ImagesNamespace holds what the node-agents read to pull images for the scheduler: the credentials of an ImagePull request. The node-agent's role covers this namespace only.

View Source
const LabGroupAccessPolicyName = "access-policy"

LabGroupAccessPolicyName is the single complete firewall-policy object in every LabGroup namespace.

View Source
const LabelComponent = LabelPrefix + "component"

LabelComponent marks the operator's own pods of a group namespace (the VPN and the gateway). Every selector of a system pod (Services, network policies, label sync, scheduler, node-agent) uses it and never the `app` label: `app` is also set on device pods from the device name, and the platform prefix keeps a tenant from setting this one.

View Source
const LabelEnrollmentToken = LabelPrefix + "enrollment-token"

LabelEnrollmentToken is the label the operator puts on a Tenant with the start of the hash of its unused enrollment token (EnrollmentTokenLabel), so the agent finds the Tenant of a token with one selector instead of reading every Tenant.

View Source
const LabelPrefix = "laboratory.cybericebox.com/"

LabelPrefix is the prefix of every operator-internal label and annotation of this platform. Labels with it are never copied from a Lab or LabGroup onto its devices and pods: they are not user labels.

View Source
const LabelTenant = LabelPrefix + "tenant"

LabelTenant is the reserved label that stamps every object the management agent creates with the tenant of its caller (the client certificate CN). It is hidden from the API.

View Source
const OperatorServiceAccount = "laboratory-controller-manager"

OperatorServiceAccount is the operator's own ServiceAccount, in SystemNamespace: in every LabGroup namespace the operator binds it to the ClusterRole of its working permissions (it has no cluster-wide write access).

View Source
const ProxyL7App = "laboratory-proxy-l7"

ProxyL7App is the `app` label value on the L7 proxy pod that terminates external HTTPS and connects to exposed device Services. The web-exposure NetworkPolicy must admit this exact value (the proxy split renamed it away from the old "proxy").

View Source
const ProxyNamespace = "laboratory-proxy"

ProxyNamespace is the Kubernetes namespace where the proxy pod runs.

View Source
const SystemNamespace = "laboratory-system"

SystemNamespace is the Kubernetes namespace where the operator runs.

View Source
const TenantPullSecret = "tenant-registry"

TenantPullSecret is the name of the Secret, in every group namespace of a tenant whose spec has images.pullSecret, that holds the tenant's registry credentials (a copy of the Secret of TenantsNamespace). Device pods reference it; the platform's own pull secrets are never given to them.

View Source
const TenantsNamespace = "laboratory-tenants"

TenantsNamespace holds the per-tenant Secrets: the enrollment token and the registry credentials of a tenant (images.pullSecret).

View Source
const WGPrivateKeyPlaceholder = "__PRIVATE_KEY__"

WGPrivateKeyPlaceholder is the sentinel the controller writes in place of the WireGuard private key inside the client config it assembles into the LabGroupClient status. The cluster never holds the private key; the agent (or a direct caller) substitutes the real private key it generated for this sentinel before handing the config to the user. It cannot occur in a real config (WireGuard keys are base64, no underscores).

View Source
const WireGuardPort = 51820

WireGuardPort is the UDP port of every WireGuard endpoint INSIDE the cluster network: the VPN pod of a group listens on it, the wg-demux of the proxy binds it and forwards the handshakes of the groups to it, and the LoadBalancer Service forwards to it. A fixed in-network port, not a setting. The port clients connect to, outside the cluster, is another matter (chart proxy.wg.publicPort, the port of PUBLIC_VPN_ENDPOINT): it defaults to this one.

Variables

View Source
var DHCPImpliedCapabilities = []string{"NET_ADMIN", "NET_RAW"}

DHCPImpliedCapabilities are added to any device with an in-image DHCP interface (addr.type=dhcp) so its client can send raw broadcast DISCOVERs and set the lease, regardless of the chosen preset.

View Source
var RegistryNodePrefix = "localhost:" + strconv.Itoa(RegistryForwardPort)

RegistryNodePrefix is host:port of the registry as the nodes see it (the node-agent's localhost forwarder): image references of the image cache and of the snapshots start with it.

View Source
var ReservedDeviceNames = []string{"vpn", "gateway", "internet"}

ReservedDeviceNames are the names of the endpoints the platform provides in every lab (the VPN, the internet gateway) and of its pods; a device may not have them.

Functions

func AccessKeysSecret

func AccessKeysSecret(tenant string) string

AccessKeysSecret is the Secret (in AccessKeysNamespace) that holds the access public keys of a tenant, one entry per key id with the PEM public key. The proxy looks keys up by this name.

func DeployKey

func DeployKey(key string) string

DeployKey is the label value of a deploy group (or a deploy_after entry): the key itself when it is a valid label value of at most 63 characters, otherwise "h" and the base36 of its SHA-256. Empty stays empty. The operator maps deploy-after annotations with it too.

func DevicePortKey

func DevicePortKey(namespace, podName, ifaceName string) string

DevicePortKey computes a stable OVS port name (≤15 chars) for a device interface. Keyed by namespace + pod name + interface name — stable across reconciles and independent of the Connection CRD name (which may not exist yet at pod creation). 48 bits of the hash keep the veth peer name ("v" prefix, 14 chars) within IFNAMSIZ while making birthday collisions between ports negligible.

func EncodeName

func EncodeName(id string) string

EncodeName is the CR name of an object id: the id itself when it already is a valid DNS-1123 label (lowercase, at most 63 characters; every UUID is), otherwise "h" and the base36 of its SHA-256 (51 characters).

func EnrollmentSecret

func EnrollmentSecret(tenant string) string

EnrollmentSecret is the Secret (in TenantsNamespace) that shows the tenant's enrollment token (key "token") to the admin until it is used.

func EnrollmentTokenLabel

func EnrollmentTokenLabel(hash string) string

EnrollmentTokenLabel is the label value for a token hash (hex SHA-256): its first 48 characters, which is plenty to narrow the list to one Tenant. The full hash is still compared.

func GWHostPortKey

func GWHostPortKey(namespace string, n uint) string

GWHostPortKey returns the host-side OVS port name of lab N's internet (gateway) leg in a group namespace; distinct from the VPN leg of the same lab.

func IDOf

func IDOf(obj interface{ GetName() string }) string

IDOf is the id of an object: the original from the annotation, or the CR name of an object that was not made by the agent.

func IsReservedLabel

func IsReservedLabel(key string) bool

IsReservedLabel reports whether a label key belongs to the platform or the system: the platform prefix, Kubernetes' own domains (kubernetes.io, k8s.io and their subdomains), and the keys the operator sets on workloads (app, pod-template-hash). Such keys are never exposed, searched or set through the management agent.

func LabGatewayObjectName

func LabGatewayObjectName(labName string) string

LabGatewayObjectName returns the Kubernetes object name for the LabGateway belonging to lab.

func LabIfaceNameByIndex

func LabIfaceNameByIndex(n uint) string

LabIfaceNameByIndex returns the in-netns interface name for lab N inside VPN and Gateway pods (e.g. lab1 … lab254). Safe to share between the two pod types because each pod has its own network namespace. It is never a host-side name: see VPNHostPortKey / GWHostPortKey.

func LabVPNObjectName

func LabVPNObjectName(labName string) string

LabVPNObjectName returns the Kubernetes object name for the LabVPN belonging to lab.

func NewWebCode

func NewWebCode(n int) (string, error)

NewWebCode returns n random lowercase base36 characters from crypto/rand.

func PropagatedLabels

func PropagatedLabels(in map[string]string) map[string]string

PropagatedLabels are the labels a Lab or LabGroup passes on to its Devices and pods: the caller's own labels and the tenant stamp.

func TenantKey

func TenantKey(cn string) string

TenantKey is the label value of a tenant: the certificate CN when it is a valid label value of at most 63 characters, otherwise "h" + base36(sha256). An empty CN is the default tenant.

func TenantOf

func TenantOf(labels map[string]string) string

TenantOf is the tenant of an object: its tenant label, or the default tenant for an object created before tenancy.

func UserLabels

func UserLabels(in map[string]string) map[string]string

UserLabels returns the labels of an object that the management agent set on behalf of a caller: everything except the reserved keys (IsReservedLabel). Lab labels go to its Devices and from there to their pods.

func VPNHostPortKey

func VPNHostPortKey(namespace string, n uint) string

VPNHostPortKey returns the host-side OVS port name of lab N's VPN leg in a group namespace. Lab indexes are allocated per group, so every group has a lab 1: the name must include the namespace or two groups' VPN pods on one node would fight over the same port. ≤15 chars like DevicePortKey.

func ValidateDeviceName

func ValidateDeviceName(name string) error

ValidateDeviceName checks a device name against the DNS label rules that the web host label <device>-<code> imposes: at most MaxDeviceNameLen characters of lowercase a-z, 0-9 and '-', not starting or ending with '-'.

func ValidateID

func ValidateID(id string) error

ValidateID checks a client-supplied id: not empty, at most MaxIDLen bytes, no control characters.

func ValidateNewDeviceName

func ValidateNewDeviceName(name string) error

ValidateNewDeviceName is ValidateDeviceName plus the reserved names. It applies to what a caller submits; a device that already exists under a reserved name keeps working because system pods are selected by LabelComponent, not by name.

func WebHostLabel

func WebHostLabel(device, code string) string

WebHostLabel is the first DNS label of a web-exposed device, both as the name of its Service and as the host under the base domain: <device>-<code>. The code is random and kept short; uniqueness inside the group namespace is settled by Kubernetes itself, because the operator creates the Service with this name and picks another code on AlreadyExists. The device name must already satisfy ValidateDeviceName; it is not truncated here.

func WithPublicVPNPort

func WithPublicVPNPort(endpoint string) string

WithPublicVPNPort completes the public WireGuard address advertised to clients (PUBLIC_VPN_ENDPOINT) with the default port when it names none: "vpn.example.com" becomes "vpn.example.com:51820". An address with a port is returned as it is. The chart already appends proxy.wg.publicPort; this is for a deploy without the chart.

func WorkloadName

func WorkloadName(device, code, legacy string) string

WorkloadName is the name of the Deployment of a device, and the prefix of its bare pods: <device>-<code>, the same label the web Service has. The lab is never part of it; the relation goes through owner references and labels. A device without a code (created before codes existed) keeps its legacy name.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL