Documentation
¶
Index ¶
- Constants
- Variables
- func AccessKeysSecret(tenant string) string
- func DeployKey(key string) string
- func DevicePortKey(namespace, podName, ifaceName string) string
- func EncodeName(id string) string
- func EnrollmentSecret(tenant string) string
- func EnrollmentTokenLabel(hash string) string
- func GWHostPortKey(namespace string, n uint) string
- func IDOf(obj interface{ ... }) string
- func IsReservedLabel(key string) bool
- func LabGatewayObjectName(labName string) string
- func LabIfaceNameByIndex(n uint) string
- func LabRegistrySecret(lab string) string
- func LabVPNObjectName(labName string) string
- func NewWebCode(n int) (string, error)
- func PropagatedLabels(in map[string]string) map[string]string
- func TenantKey(cn string) string
- func TenantOf(labels map[string]string) string
- func UserLabels(in map[string]string) map[string]string
- func VPNHostPortKey(namespace string, n uint) string
- func ValidateDeviceName(name string) error
- func ValidateID(id string) error
- func ValidateNewDeviceName(name string) error
- func WebHostLabel(device, code string) string
- func WithPublicVPNPort(endpoint string) string
- func WorkloadName(device, code, legacy string) string
Constants ¶
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.
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" )
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.
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.
const ( ComponentGateway = "gateway" ComponentVPN = "vpn" )
Component names used for Deployment names, Service names, and app label values.
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.
const ( SecretVPNKeypair = "vpn-server-keypair" SecretClientPrefix = "client-" )
Secret name patterns.
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.
const ( VNIPoolPrefix = "vni" VNIPoolSize = uint(65000) PoolLabSubnets = "lab-subnets" PoolVPNClients = "vpn-clients" )
Pool names and parameters used by the allocation subsystem.
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 )
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" )
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 )
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.
const AnnotationLabCreation = "laboratory.cybericebox.com/creation-receipt"
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.
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.
const AnnotationRegenerateEnrollment = LabelPrefix + "regenerate-enrollment-token"
AnnotationRegenerateEnrollment on a Tenant asks the operator for a new enrollment token; the operator removes it once done.
const AnnotationSnapshotRetirement = LabelPrefix + "snapshot-retirement"
AnnotationSnapshotRetirement is an irreversible repository-retirement fence, written at the accepted deadline only after exact stopped/released observation.
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.
const EnrollmentTokenKey = "token"
EnrollmentTokenKey is the data key of the token in the enrollment Secret.
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.
const LabGroupAccessPolicyName = "access-policy"
LabGroupAccessPolicyName is the single complete firewall-policy object in every LabGroup namespace.
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.
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.
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.
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.
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).
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").
const ProxyNamespace = "laboratory-proxy"
ProxyNamespace is the Kubernetes namespace where the proxy pod runs.
const SystemNamespace = "laboratory-system"
SystemNamespace is the Kubernetes namespace where the operator runs.
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.
const TenantsNamespace = "laboratory-tenants"
TenantsNamespace holds the per-tenant Secrets: the enrollment token and the registry credentials of a tenant (images.pullSecret).
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).
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 ¶
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.
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
EnrollmentSecret is the Secret (in TenantsNamespace) that shows the tenant's enrollment token (key "token") to the admin until it is used.
func EnrollmentTokenLabel ¶
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 ¶
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 ¶
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 ¶
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 ¶
LabGatewayObjectName returns the Kubernetes object name for the LabGateway belonging to lab.
func LabIfaceNameByIndex ¶
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 LabRegistrySecret ¶ added in v1.2.0
LabRegistrySecret is the dockerconfigjson Secret, in the lab's namespace, with the pull credentials the platform sent for the lab (CR name lab): "<lab>-registry". Like the other derived names it stays a DNS label of at most 63 characters: a longer name, and the lab "tenant" (whose name would be TenantPullSecret), use the hash of the lab name instead.
func LabVPNObjectName ¶
LabVPNObjectName returns the Kubernetes object name for the LabVPN belonging to lab.
func NewWebCode ¶
NewWebCode returns n random lowercase base36 characters from crypto/rand.
func PropagatedLabels ¶
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 ¶
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 ¶
TenantOf is the tenant of an object: its tenant label, or the default tenant for an object created before tenancy.
func UserLabels ¶
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 ¶
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 ¶
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 ¶
ValidateID checks a client-supplied id: not empty, at most MaxIDLen bytes, no control characters.
func ValidateNewDeviceName ¶
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 ¶
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 ¶
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 ¶
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.