Node
Node custom resource schema.
The Node CRD represents a single containerlab node realized as one direct device Pod. Together
with Link, Nodes are the primary c9s API. The object name is the containerlab node name; the
namespace is the topology boundary.
Node
SPEC
NodeSpec is the spec for a Node resource. It is a flat containerlab node definition -- containerlab vocabulary, no wrapper -- plus clabernetes-side per-node payload fields and an optional NodeProfile reference. The definition must be self-contained: expanding topology defaults/kinds into the node is the emitter's job (the Topology compiler does this for you). Anything that is deployment policy rather than node payload -- expose behavior, image pull defaults, generic resources, scheduling, and probes -- lives on NodeProfile objects explicitly referenced by Nodes. The containerlab vocabulary here is a curated subset (see NodeDefinition): fields the direct runtime cannot realize are absent, and unknown fields are rejected rather than silently ignored.
-
Aliases lists additional network names for the node. Each alias is realized as an extra same-namespace headless Service selecting the node's Pod, so lab members resolve the alias exactly like the node's own name. Aliases do not inherit from defaults or kinds.
-
AppProtocols holds application-protocol hints for selected expose Service destination ports. Entries replace built-in hints by canonical port and transport; an empty AppProtocol explicitly suppresses the hint. These entries do not select ports or affect device planning.
-
NodeAppProtocol holds the application-protocol intent for one expose Service destination port.
-
AppProtocol is a Kubernetes qualified name used as ServicePort.appProtocol. An empty value explicitly suppresses any built-in hint for this port. The DNS prefix is limited to 253 characters and the name to 63.
-
Port is the destination port and transport in canonical "/tcp" or "/udp" form. The port number must be between 1 and 65535.
-
-
-
Binds is a list of bind (mount) compatible strings.
-
CapAdd is a list of linux capabilities to add to the node's container.
-
Certificate holds the TLS certificate configuration for the node.
-
Issue indicates if the node should have a certificate issued -- when unset the node does not use TLS.
-
KeySize is the size of the certificate key in bits.
-
SANs is the list of subject alternative names to add to the node's certificate.
-
ValidityDuration is how long the issued certificate is valid for, as a Go duration -- i.e. 8760h for a year.
-
-
Cmd overrides the container command.
-
Components holds the hardware component (i.e. SR-OS card/mda) configuration for the node.
-
Component holds a hardware component configuration (i.e. an SR-OS card or mda).
-
SFM is the SFM (switch fabric module) of the component.
-
Slot is the slot identifier of the component.
-
Type is the type of the component.
-
XIOM holds the xiom configuration of the component.
-
XIOM holds a single xiom configuration of a hardware component.
-
Slot is the slot of the xiom.
-
Type is the type of the xiom.
-
-
-
CPU is the number of vcpus to allocate for the node's container -- it becomes the container's Kubernetes CPU limit.
range: >= 0 -
Devices is a list of host devices to map into the node's container.
-
EnforceStartupConfig makes the node boot from StartupConfig even when it already has a saved (persisted) configuration.
-
Entrypoint overrides the container entrypoint.
-
EnvFiles is a list of external files containing environment variables for the node.
-
Exec is a list of commands to run in the node's container once it is started.
-
FilesFromConfigMap holds files staged from ConfigMaps for this Node's application containers.
-
FileFromConfigMap represents a file that you would like to mount (from a configmap) in the device pod for a given node.
-
ConfigMapName is the name of the configmap to mount.
-
ConfigMapPath is the path/key in the configmap to mount, if not specified the configmap will be mounted without a sub-path.
-
FilePath is the path to mount the file.
-
Mode sets the file permissions when mounting the configmap. Since the configmap will be read only filesystem anyway, we basically just want to expose if the file should be mounted as executable or not. So, default permissions would be 0o444 (read) and execute would be 0o555.
default: "read"enum: "read", "execute"
-
-
-
FilesFromSecret holds sensitive files projected from same-namespace Secrets into this Node's direct application container.
-
FileFromSecret represents one file projected from a same-namespace Kubernetes Secret.
-
FilePath is the absolute destination path, or the destination directory when SecretPath is omitted and every Secret key is projected.
-
Mode selects read-only or read-and-execute permissions for the staged file.
default: "read"enum: "read", "execute" -
SecretName is the name of the same-namespace Secret.
-
SecretPath is the Secret data key to project. When omitted, every key is projected beneath FilePath in deterministic key order.
-
-
-
FilesFromURL holds files preparation must fetch and verify before the Node starts.
-
FileFromURL represents a file that you would like to mount from a URL in the device pod for a given node.
-
Digest is the required SHA-256 identity of the downloaded bytes in direct-runtime mode. It prevents a mutable URL from changing a device payload without changing the accepted plan.
-
FilePath is the path to mount the file.
-
URL is the url to fetch and mount at the provided FilePath. This URL must be a url that can be simply downloaded and dumped to disk -- meaning a normal file server type endpoint or if using GitHub or similar a "raw" path.
-
-
-
Group names the containerlab group a node belongs to. Group-scoped configuration from the topology's groups section participates in the imported inheritance rules, and the name itself is carried onto the compiled Node as a label.
-
Healthcheck is the containerlab process health contract for the node; it merges over the image-defined OCI healthcheck and is realized as container startup/readiness behavior.
-
Interval is the time in seconds to wait between checks.
range: >= 0 -
Retries is the number of consecutive failures needed to consider the container unhealthy.
range: >= 0 -
StartPeriod is the time in seconds to wait for the container to initialize before the retries countdown starts.
range: >= 0 -
Test is the command to run to check the health of the container -- the first element selects the containerlab test form (i.e. CMD) and the remainder is the command itself.
-
Timeout is the time in seconds to wait before considering a check to have hung.
range: >= 0
-
-
Image is the container image for the node.
-
ImagePullPolicy is the containerlab pull policy for the node's image; it maps onto the equivalent Kubernetes image pull policy and takes precedence over profile and global defaults.
enum: "always", "Always", "never", +3 more -
Kind is the containerlab kind of the node -- i.e. nokia_srlinux.
-
License is the path to the license file for the node.
-
LinkApplyMode declares the lifecycle action used when the node's links change: live (no lifecycle action), restart, or recreate. It overrides the kind's imported default.
enum: "live", "restart", "recreate" -
Memory is the memory limit for the node's container in containerlab's human-readable form -- i.e. 1Gb -- and becomes the container's Kubernetes memory limit.
-
MgmtIPv4 is the user-defined IPv4 address of the node in the management network.
-
MgmtIPv6 is the user-defined IPv6 address of the node in the management network.
-
NetworkMode declares that this node shares the network namespace -- and therefore the device pod -- of the named primary node.
container:<primary node name>is the only accepted value: clabernetes derives node "grouping" (nodes co-located in one device pod, i.e. the cards of a distributed chassis) from exactly this containerlab-native field, and the other containerlab network modes have no meaning inside a device pod. -
Ports lists additional ports to expose on this node. Each entry is a destination port between 1 and 65535 with an optional protocol -- "8080" or "5201/udp" -- meaning the port the node itself listens on. clabernetes allocates the pod side port that carries it and records both in the Node status, so docker style "host:container" bindings are rejected here. Unless auto expose is disabled, the default set of management ports is exposed in addition to these.
-
Privileged runs the node's container in privileged mode.
-
ProfileRef optionally names the same-namespace NodeProfile supplying direct workload policy. When omitted, built-in defaults and supported global Config defaults are used.
-
Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
default: ""
-
-
RestartPolicy is the container restart policy for the node. Only the values with a shared-Pod mapping are accepted -- a device container in a direct Pod always restarts with its Pod, so Docker's "no" and "on-failure" policies cannot be represented.
enum: "always", "Always", "unless-stopped", "Unless-stopped" -
SecurityOpts is a list of security options (i.e. seccomp or apparmor settings) to apply to the node's container.
-
ShmSize is the shared memory size allocated to the node's container -- i.e. 256m.
-
StartupConfig is the startup configuration for the node -- either a path or an inline (multiline string) config.
-
StartupDelay is an optional delay in seconds applied before the node's application container starts.
-
SuppressStartupConfig boots the node with its factory configuration -- containerlab generates and mounts no startup config at all.
-
Type is the type of the node -- i.e. ixrd2.
-
User is the linux user to use in the node's container.
STATUS
NodeStatus is the status for a Node resource. Everything in here is an allocation or an observation made by the controller -- user intent never lives in the status.
-
AppliedProfile identifies the NodeProfile revision successfully applied to the direct workload. It is nil when the Node uses built-in and supported global Config defaults.
-
Generation is the applied NodeProfile generation.
format: int64 -
Name is the NodeProfile name.
-
UID distinguishes replacement profiles that reuse a name.
-
-
Conditions contains the current conditions for this Node.
-
Condition contains details for one aspect of the current state of this API Resource.
-
lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
format: date-time -
message is a human readable message indicating details about the transition. This may be an empty string.
-
observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
format: int64range: >= 0 -
reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
-
status of the condition, one of True, False, Unknown.
enum: "True", "False", "Unknown" -
type of condition in CamelCase or in foo.example.com/CamelCase.
-
-
-
DirectContainers contains bounded Kubernetes observations for application containers that represent this logical Node. It contains no user intent or full plan data.
-
NodeDirectContainerStatus is one plan-addressed application-container observation.
-
ComponentID is the imported component identity when this is not the logical primary.
-
ID is the stable runtime-neutral container identity from the applied plan.
-
ImageID is the kubelet-observed immutable image identity when available.
-
Name is the deterministic Kubernetes container name used with kubectl's -c option.
-
Ready is the Kubernetes application-container readiness observation.
-
RestartCount is the kubelet-observed restart count.
format: int32 -
State is one of unknown, waiting, running, or terminated.
-
-
-
DirectManagement contains the bounded management allocation from the applied direct plan. It contains no credentials or kind-specific configuration.
-
InterfaceName is the package-selected management interface in the Pod namespace.
-
IPv4 is the allocated IPv4 address and prefix.
-
IPv4Gateway is the source-specific IPv4 gateway.
-
IPv6 is the allocated IPv6 address and prefix.
-
IPv6Gateway is the source-specific IPv6 gateway.
-
-
ExposedPorts holds expose-port allocations for this Node. The controller assigns and programs the direct Pod Service from this field.
-
LoadBalancerAddress is the address of the load balancer exposing the node's ports (if the expose service is of the LoadBalancer flavor).
-
Ports holds the individual port allocations for the node.
-
NodeExposedPort holds a single expose port allocation for a Node.
-
DestinationPort is the port on the (containerlab) node itself -- this is the port the expose service listens on.
-
ExposePort is the allocated Service port targeting the direct device Pod.
-
Protocol is the protocol of the port -- TCP or UDP.
enum: "TCP", "UDP"
-
-
-
-
PlanDigest identifies the immutable direct device plan observed by this status.
-
Readiness is the controller-observed readiness of this Node's active runtime -- one of "ready", "notready" or "unknown".
enum: "ready", "notready", "unknown"