コンテンツにスキップ

v1alpha1

Metadata Value
Group juneau.loutres.me
Version
Module github.com/1outres/juneau/controller/api/v1alpha1
Property Optionality

AddressPool


AddressPool is the Schema for the addresspools API.

Used by: AddressPoolList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec AddressPoolSpec
status AddressPoolStatus

AddressPoolSpec

Property Description Type
addresses string[]
advertiseMode AddressPoolAdvertiseMode

AddressPoolStatus

AddressPoolList


AddressPoolList contains a list of AddressPool.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items AddressPool[]

AllocationClaim


AllocationClaim is the Schema for the allocationclaims API.

Used by: AllocationClaimList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec AllocationClaimSpec
status AllocationClaimStatus

AllocationClaimSpec

Property Description Type
allocationFilter AllocationFilter restricts the candidate space inside the pools. Used when a consumer wants to take from a specific subset of CIDRs. AllocationFilter
attribute Attribute identifies the target field on the owning resource, for example status.vni or status.tableID. string
poolRefs PoolRefs lists candidate pools, evaluated in order. The first pool that has a free value satisfying the claim wins. AllocationPoolReference[]
releaseAfter ReleaseAfter specifies how long the AllocationLease should outlive this claim. While the lease is alive, no other claim can take the same value, and a re-created claim with the same identity will inherit the same value. When unset, the lease is deleted immediately alongside the claim. metav1.Duration
requestedIP RequestedIP pins a specific value for ip-typed pools. Must be a valid IPv4/IPv6 string and must fall inside one of the candidate pools' CIDRs (further restricted by AllocationFilter when set). string
requestedNumber RequestedNumber pins a specific value for number-typed pools. uint64
resourceRef AllocationResourceReference

AllocationClaimStatus

Property Description Type
conditions metav1.Condition[]
observedGeneration int64
phase AllocationClaimPhase
value AllocationValue

AllocationClaimList


AllocationClaimList contains a list of AllocationClaim.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items AllocationClaim[]

AllocationLease


AllocationLease is the Schema for the allocationleases API.

Used by: AllocationLeaseList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec AllocationLeaseSpec
status AllocationLeaseStatus

AllocationLeaseSpec

Property Description Type
ownerDeletionTimestamp OwnerDeletionTimestamp records when the owning AllocationClaim was deleted. While unset, the lease is considered Active and will not be reaped. Once set, the lease is treated as Released and the controller will delete it after TTLSeconds elapses. metav1.Time
poolRef PoolRef references the AllocationPool that owns this lease via metadata.ownerReferences. The pool name is also kept here for efficient field-indexed lookups. AllocationPoolReference
reuseKey ReuseKey identifies the upstream owner so that a re-created AllocationClaim with the same identity can recover the value. AllocationResourceReference
ttlSeconds TTLSeconds is the grace period applied after OwnerDeletionTimestamp. Copied from the originating AllocationClaim.spec.releaseAfter. int32
value Value is the reserved address or number. AllocationValue

AllocationLeaseStatus

Property Description Type
conditions metav1.Condition[]
expiresAt metav1.Time
observedGeneration int64
phase AllocationLeasePhase

AllocationLeaseList


AllocationLeaseList contains a list of AllocationLease.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items AllocationLease[]

AllocationPool


AllocationPool is the Schema for the allocationpools API.

Used by: AllocationPoolList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec AllocationPoolSpec
status AllocationPoolStatus

AllocationPoolSpec

Property Description Type
ip AllocationPoolIPSpec
number AllocationPoolNumberSpec
strategy AllocationStrategy
type AllocationType

AllocationPoolStatus

Property Description Type
allocationVersion uint64
conditions metav1.Condition[]
lastAllocatedIP string
lastAllocatedNumber uint64
observedGeneration int64

AllocationPoolList


AllocationPoolList contains a list of AllocationPool.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items AllocationPool[]

BGPAdvertisement


BGPAdvertisement is the Schema for the bgpadvertisements API.

Used by: BGPAdvertisementList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec BGPAdvertisementSpec
status BGPAdvertisementStatus

BGPAdvertisementSpec

Property Description Type
addressPools string[]
nodeName NodeName, if non-empty, scopes the advertisement to a single node: only the bgp-speaker on the matching node emits the BGP route. When empty, every bgp-speaker advertises the configured prefixes. string
prefix Prefix, if non-empty, restricts the advertisement to a single CIDR prefix instead of advertising every CIDR backing the referenced AddressPool(s). The prefix must be contained in one of the referenced AddressPools' CIDRs. string

BGPAdvertisementStatus

BGPAdvertisementList


BGPAdvertisementList contains a list of BGPAdvertisement.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items BGPAdvertisement[]

BGPNodeState


BGPNodeState is the Schema for the bgpnodestates API.

Used by: BGPNodeStateList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec BGPNodeStateSpec
status BGPNodeStateStatus

BGPNodeStateSpec

BGPNodeStateStatus

Property Description Type
advertisements BGPNodeStateAdvertisement[]
bgpSessions BGPNodeStateSession[]
conditions metav1.Condition[]
errors BGPNodeStateError[]
heartbeat metav1.Time

BGPNodeStateList


BGPNodeStateList contains a list of BGPNodeState.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items BGPNodeState[]

BGPPeer


BGPPeer is the Schema for the bgppeers API.

Used by: BGPPeerList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec BGPPeerSpec
status BGPPeerStatus

BGPPeerSpec

Property Description Type
myASN int64
peerAddress string
peerASN int64
peerPort uint16

BGPPeerStatus

BGPPeerList


BGPPeerList contains a list of BGPPeer.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items BGPPeer[]

ElasticIP


ElasticIP is the Schema for the elasticips API.

Used by: ElasticIPList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ElasticIPSpec
status ElasticIPStatus

ElasticIPSpec

Property Description Type
externalNetwork string
Required
requestedIP RequestedIP optionally pins a specific address. The address must fall inside one of the AddressPools attached to the referenced ExternalNetwork. When unset (empty string) the controller picks the first available address. string

ElasticIPStatus

Property Description Type
address string
attachmentName string
conditions metav1.Condition[]
observedGeneration int64
phase ElasticIPPhase

ElasticIPAttachment


ElasticIPAttachment is the Schema for the elasticipattachments API.

Used by: ElasticIPAttachmentList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ElasticIPAttachmentSpec
status ElasticIPAttachmentStatus

ElasticIPAttachmentSpec

Property Description Type
elasticIPRef ElasticIPAttachmentElasticIPRef
targetRef ElasticIPAttachmentTargetRef

ElasticIPAttachmentStatus

Property Description Type
conditions metav1.Condition[]
elasticIP string
nodeName string
observedGeneration int64
phase ElasticIPAttachmentPhase
podIP string

ElasticIPAttachmentList


ElasticIPAttachmentList contains a list of ElasticIPAttachment.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ElasticIPAttachment[]

ElasticIPList


ElasticIPList contains a list of ElasticIP.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ElasticIP[]

ExternalNetwork


ExternalNetwork is the Schema for the externalnetworks API.

Used by: ExternalNetworkList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ExternalNetworkSpec
status ExternalNetworkStatus

ExternalNetworkSpec

Property Description Type
addressPools string[]
type ExternalNetworkType

ExternalNetworkStatus

ExternalNetworkAttachment


ExternalNetworkAttachment is the Schema for the externalnetworkattachments API.

Used by: ExternalNetworkAttachmentList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ExternalNetworkAttachmentSpec
status ExternalNetworkAttachmentStatus

ExternalNetworkAttachmentSpec

Property Description Type
externalNetwork string
nodeName string

ExternalNetworkAttachmentStatus

Property Description Type
assignedIP AssignedIP is the per-(ExternalNetwork, Node) NAPT source IP allocated for this attachment. Populated by the reconciler once the underlying AllocationClaim resolves to an address. string
conditions metav1.Condition[]
observedGeneration int64

ExternalNetworkAttachmentList


ExternalNetworkAttachmentList contains a list of ExternalNetworkAttachment.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ExternalNetworkAttachment[]

ExternalNetworkList


ExternalNetworkList contains a list of ExternalNetwork.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ExternalNetwork[]

NATGateway


NATGateway is the Schema for the natgateways API.

Used by: NATGatewayList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec NATGatewaySpec
status NATGatewayStatus

NATGatewaySpec

Property Description Type
externalNetwork string
vpc string

NATGatewayStatus

Property Description Type
conditions metav1.Condition[]
gatewayID GatewayID is the cluster-wide identifier allocated for this NATGateway. It is referenced by the data plane to look up per-(node, ExternalNetwork) NAPT source IPs. uint32
observedGeneration int64

NATGatewayList


NATGatewayList contains a list of NATGateway.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items NATGateway[]

NetworkACL


NetworkACL is the Schema for the networkacls API.

Used by: NetworkACLList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec NetworkACLSpec
status NetworkACLStatus

NetworkACLSpec

Property Description Type
egress Egress lists rules controlling traffic leaving Subnets that reference this ACL. NetworkACLRule[]
ingress Ingress lists rules controlling traffic entering Subnets that reference this ACL. Per-direction defaults follow the NetworkACLSpec nil-vs-[] convention. NetworkACLRule[]
vpc Vpc names the Vpc this NetworkACL belongs to. Immutable. string

NetworkACLStatus

Property Description Type
aclID ACLID is the cluster-wide identifier allocated for this ACL via an AllocationClaim. Daemons key acl_meta_map and acl_rule_table by this number; once assigned it never changes for the lifetime of the resource. uint32
attachedSubnets AttachedSubnets enumerates Subnets currently referencing this NetworkACL via spec.networkACL. Updated by the controller from an informer; observability only and may lag briefly. string[]
conditions metav1.Condition[]
egressRuleCount int32
hasEgressRules bool
hasIngressRules HasIngressRules / HasEgressRules report whether the spec set the direction explicitly (nil → false, [] or non-empty → true). Daemons use these to choose between default-allow (no enforcement at all) and default-deny (rule list applies, fall through to deny). bool
ingressRuleCount IngressRuleCount and EgressRuleCount report the rule count per direction (0 when the direction is nil/empty). Observability; not a hard limit. int32
observedGeneration int64
rulesetVersion RulesetVersion is bumped whenever the controller publishes a new effective ruleset summary. Daemons use this to invalidate stale CT entries when rules change. uint64

NetworkACLList


NetworkACLList contains a list of NetworkACL.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items NetworkACL[]

NetworkEndpoint


NetworkEndpoint is the Schema for the networkendpoints API.

Used by: NetworkEndpointList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec NetworkEndpointSpec
status NetworkEndpointStatus

NetworkEndpointSpec

Property Description Type
address Address is the L3 identity in CIDR form (e.g. "10.0.0.5/24"). string
attachment Attachment describes the local kernel iface that backs this endpoint on Spec.NodeName. Populated by the local daemon. NetworkEndpointAttachment
kind Kind identifies what produced this endpoint. EndpointKind
macAddress MACAddress is the L2 identity used as the destination MAC for this endpoint on the overlay. Always required for endpoints that participate in arp/fdb (i.e. all Kind=Pod and Kind=Node). string
nodeName NodeName pins the endpoint to a specific node. The daemon on this node owns the Attachment fields. string
podRef PodRef is required when Kind=Pod and otherwise omitted. NetworkEndpointPodReference
subnet Subnet is the L2 segment this endpoint participates in. string

NetworkEndpointStatus

Property Description Type
nodeIP NodeIP is the underlay IP of Spec.NodeName, populated by the controller. Used by remote daemons to populate fdb VTEP entries. string

NetworkEndpointList


NetworkEndpointList contains a list of NetworkEndpoint.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items NetworkEndpoint[]

NetworkInterface


NetworkInterface is the Schema for the networkinterfaces API.

Used by: NetworkInterfaceList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec NetworkInterfaceSpec
status NetworkInterfaceStatus

NetworkInterfaceSpec

Property Description Type
address string
nodeName string
podRef NetworkInterfacePodReference
securityGroups SecurityGroups lists SecurityGroup resources whose rules apply to this interface. Order is irrelevant; rules from all listed SGs are unioned. An empty / nil list means "no SG enforcement" unless the owning Vpc has spec.enforceSecurityGroups=true, in which case Pod admission rejects unattached Pods.
All referenced SGs must belong to the same Vpc as this NetworkInterface's Subnet. Webhook validation enforces this.
string[]
subnet string

NetworkInterfaceStatus

Property Description Type
address string
allocationClaim AllocationClaim names the cluster-scoped AllocationClaim that the reconciler maintains for this interface's IP reservation. Useful only for debugging — daemon/CNI consumers should rely on Address. string
conditions metav1.Condition[]
effectiveSecurityGroups EffectiveSecurityGroups echoes spec.securityGroups after the controller resolved them (filtered by existence + same-Vpc) and includes the assigned GroupID for each. Daemon reads this list rather than spec, so a stale/dangling spec entry never causes a blackhole. NetworkInterfaceEffectiveSG[]
observedGeneration int64
phase NetworkInterfacePhase
routes NetworkRoute[]

NetworkInterfaceList


NetworkInterfaceList contains a list of NetworkInterface.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items NetworkInterface[]

RouteTable


RouteTable is the Schema for the routetables API.

Used by: RouteTableList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec RouteTableSpec
status RouteTableStatus

RouteTableSpec

Property Description Type
routes Route[]
vpc string

RouteTableStatus

Property Description Type
conditions metav1.Condition[]
observedGeneration int64
routes Route[]
tableID uint32

RouteTableList


RouteTableList contains a list of RouteTable.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items RouteTable[]

SecurityGroup


SecurityGroup is the Schema for the securitygroups API.

Used by: SecurityGroupList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec SecurityGroupSpec
status SecurityGroupStatus

SecurityGroupSpec

Property Description Type
egress Egress lists rules permitting outbound traffic. nil (the field is omitted entirely) means "allow all egress" (AWS-compatible default). A non-nil list (even empty) flips egress to "deny-by-default, allow-by-rule". SecurityGroupEgressRule[]
ingress Ingress lists rules permitting inbound traffic. Empty/omitted means "deny all ingress". SecurityGroupIngressRule[]
vpc Vpc names the Vpc this SecurityGroup belongs to. Immutable. string

SecurityGroupStatus

Property Description Type
attachedInterfaces AttachedInterfaces enumerates NetworkInterfaces currently referencing this SecurityGroup. Updated by the controller from an informer; it is observability-only and may lag briefly. SecurityGroupAttachedInterface[]
conditions metav1.Condition[]
egressRuleCount int32
groupID GroupID is the cluster-wide identifier allocated for this SecurityGroup via an AllocationClaim. Daemon and BPF maps reference this number; once assigned it never changes for the lifetime of the resource. uint32
hasEgressRules HasEgressRules mirrors the spec choice (nil → false). Daemons use this to decide whether to apply egress allow-list semantics or default-allow. bool
ingressRuleCount IngressRuleCount and EgressRuleCount report how many flat (post-expansion) BPF rule entries the controller resolved for each direction. These are observability fields; they are not a hard cap (that lives in the data plane MAX_RULES_PER_SG). int32
observedGeneration int64
rulesetVersion RulesetVersion is bumped every time the controller resolves a new effective ruleset. Daemons can use it to detect and ack rule changes. uint64

SecurityGroupList


SecurityGroupList contains a list of SecurityGroup.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items SecurityGroup[]

ServiceLoadBalancer


ServiceLoadBalancer is the Schema for Juneau-managed Service LoadBalancer state. Each resource normalises the desired and observed state derived from a Kubernetes Service so that the controller, daemon, BGP speaker, and CLI tooling do not each re-interpret Service annotations independently.

Used by: ServiceLoadBalancerList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ServiceLoadBalancerSpec
status ServiceLoadBalancerStatus

ServiceLoadBalancerSpec

Property Description Type
externalNetwork ExternalNetwork selects the cluster-scoped ExternalNetwork from which the VIP is allocated. The referenced ExternalNetwork must exist and must declare at least one AddressPool. string
requestedIP RequestedIP optionally pins a specific IPv4 address. The address must fall inside one of the AddressPools attached to the referenced ExternalNetwork. When unset (empty string) the controller picks the first available address. string
serviceRef ServiceRef points at the Kubernetes Service that owns this resource. The Service must live in the same namespace as the ServiceLoadBalancer; cross-namespace references are rejected at admission time. ServiceLoadBalancerServiceReference

ServiceLoadBalancerStatus

Property Description Type
addressPool AddressPool records which AddressPool the VIP was drawn from. Mainly informational; downstream consumers should not assume pool membership without re-resolving against the API. string
advertisingNodes AdvertisingNodes lists Kubernetes node names that currently have at least one ready local endpoint and may therefore advertise the VIP via BGP. The list is sorted lexicographically for stability. string[]
allocationClaimName AllocationClaimName names the AllocationClaim that owns the VIP allocation. Recorded so that finalization and observability can follow the claim without having to re-derive the name. string
backendSummary BackendSummary aggregates endpoint-level fleet health for dashboards. ServiceLoadBalancerBackendSummary
conditions Conditions track fine-grained observable state. See the ServiceLoadBalancerCondition* constants for the canonical set. metav1.Condition[]
observedGeneration ObservedGeneration is the .metadata.generation the status reflects. Status consumers should ignore status fields when observedGeneration < .metadata.generation. int64
phase Phase is a coarse human-readable lifecycle indicator. See the ServiceLoadBalancerPhase constants for the full set. ServiceLoadBalancerPhase
ports Ports is the canonical list of (port, protocol, targetPort) triples derived from the parent Service. The list is sorted by (Port, Protocol) so consumers see deterministic output. ServiceLoadBalancerPort[]
vip VIP is the allocated external IP address. Empty until allocation succeeds. Once written, the controller treats VIP as immutable for the lifetime of the resource. string

ServiceLoadBalancerList


ServiceLoadBalancerList contains a list of ServiceLoadBalancer.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ServiceLoadBalancer[]

ServiceNATAttachment


ServiceNATAttachment is the Schema for the servicenatattachments API.
One ServiceNATAttachment exists per (Node, provider Vpc) pair and represents the SNAT source IP that traffic from cross-VPC callers takes when reaching shared Services in the provider Vpc. Resources are owned by the provider Vpc and fanned out by the VpcReconciler for every Vpc that sets spec.service.provider.natSourceSubnet.

Used by: ServiceNATAttachmentList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec ServiceNATAttachmentSpec
status ServiceNATAttachmentStatus

ServiceNATAttachmentSpec

Property Description Type
nodeName NodeName is the Kubernetes Node this attachment belongs to. string
vpc Vpc is the provider Vpc whose Service NAT pool the attachment allocates from. The Vpc must have spec.service.provider.natSourceSubnet set. string

ServiceNATAttachmentStatus

Property Description Type
assignedIP AssignedIP is the per-Node SNAT source IP used to forward traffic from cross-VPC callers into shared Services owned by the provider Vpc. Allocated from the provider Vpc's spec.service.provider.natSourceSubnet by the ServiceNATAttachmentReconciler. string
assignedMAC AssignedMAC is the synthetic MAC paired with AssignedIP, published through a derived NetworkEndpoint so the provider Vpc's fabric can resolve the SNAT IP via ARP/fdb back to this Node. string
conditions metav1.Condition[]
observedGeneration int64
subnet Subnet records the Subnet the SNAT IP was allocated from. It mirrors the provider Vpc's spec.service.provider.natSourceSubnet at allocation time and is used by downstream reconcilers (NetworkEndpoint, daemon-side ARP/fdb) to install the entry in the right L2 segment. string

ServiceNATAttachmentList


ServiceNATAttachmentList contains a list of ServiceNATAttachment.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items ServiceNATAttachment[]

Subnet


Subnet is the Schema for the subnets API.

Used by: SubnetList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec SubnetSpec
status SubnetStatus

SubnetSpec

Property Description Type
cidr string
networkACL NetworkACL names the NetworkACL applied at this Subnet's boundary. The referenced ACL must belong to the same Vpc as the Subnet (webhook-enforced). Empty means "no ACL" — the Subnet boundary does not enforce policy and traffic flows straight to the per-Pod SecurityGroup layer.
Mutability: the field is mutable. Switching the reference (or clearing it) re-converges the Subnet status and triggers daemon-side CT invalidation so flows pick up the new policy on their next packet.
string
routeTable RouteTable selects which RouteTable governs traffic from Pods in this Subnet. Empty means "use the owning Vpc's main RouteTable", which preserves the original behaviour. The referenced RouteTable must belong to the same Vpc. string
vpc string

SubnetStatus

Property Description Type
conditions metav1.Condition[]
dns DNS is the per-Subnet virtual DNS resolver IP (the second usable address in the prefix, conventionally .2). The juneau daemon terminates UDP/53 and TCP/53 destined for this address inside its virtual service plane and never bridges it to the underlay. Empty when the Subnet's prefix has no usable .2. string
dnsMAC DNSMAC is the locally-administered Ethernet address that ARP for the DNS VIP resolves to. Distinct from GatewayMAC so the data plane can demultiplex virtual-service traffic by destination MAC before consulting the FIB. Empty when DNS is empty. string
gateway string
gatewayMAC string
networkACL NetworkACL mirrors the resolved spec.networkACL reference. It carries the cluster-wide ACLID the daemon writes into the BPF subnet_map plus the ACL's RulesetVersion at the time the reference was resolved. Empty (nil) when spec.networkACL is unset or the named ACL does not yet exist. SubnetNetworkACLRef
observedGeneration int64
vni uint32

SubnetList


SubnetList contains a list of Subnet.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items Subnet[]

TraceSession


TraceSession is the Schema for the tracesessions API.

Used by: TraceSessionList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec TraceSessionSpec
status TraceSessionStatus

TraceSessionSpec

Property Description Type
capture Capture controls per-event detail and event-class selection. TraceCaptureConfig
destination Destination identifies the target endpoint. Same role as Source — kubectl uses it for tuple computation; daemons match by tuple. TraceEndpoint
expiresAt ExpiresAt is the wall-clock time after which daemons must stop emitting events for this session and remove their local dataplane state. Mandatory. Protects against orphan sessions when kubectl crashes mid-trace. Daemons evaluate expiry on every reconcile; kubectl typically sets ExpiresAt to now() + session timeout + a small grace window. metav1.Time
initialTuples InitialTuples is the precomputed list of tuples kubectl expects the dataplane to match. There can be more than one per session because a Service ClusterIP may resolve to multiple backend Pods (one tuple per backend), or because kubectl wants to trace both directions of a flow at session start. Additional tuples discovered post-NAT are learned by daemons and fanned out via the debug stream. TraceTuple[]
mode Mode selects ActiveProbe (probe injection) or ObserveOnly (passive observation). ObserveOnly is the safe default for production. TraceMode
source Source identifies the originating endpoint. Used by kubectl when computing initial tuples and shown in the rendered timeline; daemons themselves match by tuple, not by source. TraceEndpoint
traceID TraceID is a session-stable identifier programmed into BPF maps. Daemons use it to attach trace state to in-flight packets without re-keying by full tuple. kubectl picks a random non-zero value at session creation; uniqueness is the caller's responsibility (collisions cause cross-talk between concurrent sessions). uint32

TraceSessionStatus

Property Description Type
conditions Conditions reports detailed lifecycle signals. The defined types live in the TraceSessionCondition* constants below. metav1.Condition[]
lastObservedAt LastObservedAt is the most recent time any daemon emitted a trace event for this session. Surfaced to operators so a "no events received" run is distinguishable from a daemon outage. metav1.Time
observedNodes ObservedNodes lists the node names whose juneaud has programmed local trace maps for this session. Updated by the daemon-side reconciler. Order is not significant. string[]
phase Phase summarizes the lifecycle stage. Useful for kubectl progress display; reconciliation does not branch on it. TraceSessionPhase

TraceSessionList


TraceSessionList contains a list of TraceSession.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items TraceSession[]

Vpc


Vpc is the Schema for the vpcs API.

Used by: VpcList.items.

Property Description Type
metav1.TypeMeta
metav1.ObjectMeta
spec VpcSpec
status VpcStatus

VpcSpec

Property Description Type
enforceSecurityGroups EnforceSecurityGroups makes SecurityGroup attachment mandatory for every Pod placed in a Subnet of this Vpc. Pods without the juneau.loutres.me/security-groups annotation (or with a list that resolves to zero valid SGs) are rejected at admission. Existing Pods are not retroactively affected when this flag is toggled. bool
service Service configures Service routing for this VPC. When nil, the VPC has no Service routing — its Pods cannot reach any ClusterIP and the controller does not inject a Service-typed route into the VPC's main RouteTable.
Two cross-VPC roles are independently configurable under this field: Provider (this VPC hosts Services that other VPCs may reach) and Consume (this VPC's Pods may reach shared Services hosted in other VPCs). Setting either implicitly enables Service routing for the VPC.
VpcServiceSpec

VpcStatus

Property Description Type
conditions metav1.Condition[]
mainRouteTable string
observedGeneration int64
vpcID uint32

VpcList


VpcList contains a list of Vpc.

Property Description Type
metav1.TypeMeta
metav1.ListMeta
items Vpc[]

AddressPoolSpec

AddressPoolSpec defines the desired state of AddressPool.

Used by: AddressPool.spec.

Property Description Type
addresses string[]
advertiseMode AddressPoolAdvertiseMode

AllocationClaimSpec

AllocationClaimSpec defines the desired state of AllocationClaim.

Used by: AllocationClaim.spec.

Property Description Type
allocationFilter AllocationFilter restricts the candidate space inside the pools. Used when a consumer wants to take from a specific subset of CIDRs. AllocationFilter
attribute Attribute identifies the target field on the owning resource, for example status.vni or status.tableID. string
poolRefs PoolRefs lists candidate pools, evaluated in order. The first pool that has a free value satisfying the claim wins. AllocationPoolReference[]
releaseAfter ReleaseAfter specifies how long the AllocationLease should outlive this claim. While the lease is alive, no other claim can take the same value, and a re-created claim with the same identity will inherit the same value. When unset, the lease is deleted immediately alongside the claim. metav1.Duration
requestedIP RequestedIP pins a specific value for ip-typed pools. Must be a valid IPv4/IPv6 string and must fall inside one of the candidate pools' CIDRs (further restricted by AllocationFilter when set). string
requestedNumber RequestedNumber pins a specific value for number-typed pools. uint64
resourceRef AllocationResourceReference

AllocationClaimStatus

AllocationClaimStatus defines the observed state of AllocationClaim.

Used by: AllocationClaim.status.

Property Description Type
conditions metav1.Condition[]
observedGeneration int64
phase AllocationClaimPhase
value AllocationValue

AllocationLeaseSpec

AllocationLeaseSpec defines the desired state of AllocationLease.
AllocationLease records a single (pool, value) reservation that survives the deletion of its owning AllocationClaim. While a lease exists no other claim can take the same value, and a claim re-created with the same ReuseKey will inherit the recorded value. Leases are managed entirely by the AllocationClaim controller; consumers of the allocation framework should never create or modify AllocationLease objects directly.

Used by: AllocationLease.spec.

Property Description Type
ownerDeletionTimestamp OwnerDeletionTimestamp records when the owning AllocationClaim was deleted. While unset, the lease is considered Active and will not be reaped. Once set, the lease is treated as Released and the controller will delete it after TTLSeconds elapses. metav1.Time
poolRef PoolRef references the AllocationPool that owns this lease via metadata.ownerReferences. The pool name is also kept here for efficient field-indexed lookups. AllocationPoolReference
reuseKey ReuseKey identifies the upstream owner so that a re-created AllocationClaim with the same identity can recover the value. AllocationResourceReference
ttlSeconds TTLSeconds is the grace period applied after OwnerDeletionTimestamp. Copied from the originating AllocationClaim.spec.releaseAfter. int32
value Value is the reserved address or number. AllocationValue

AllocationLeaseStatus

AllocationLeaseStatus defines the observed state of AllocationLease.

Used by: AllocationLease.status.

Property Description Type
conditions metav1.Condition[]
expiresAt metav1.Time
observedGeneration int64
phase AllocationLeasePhase

AllocationPoolSpec

AllocationPoolSpec defines the desired state of AllocationPool.

Used by: AllocationPool.spec.

Property Description Type
ip AllocationPoolIPSpec
number AllocationPoolNumberSpec
strategy AllocationStrategy
type AllocationType

AllocationPoolStatus

AllocationPoolStatus defines the observed state of AllocationPool.

Used by: AllocationPool.status.

Property Description Type
allocationVersion uint64
conditions metav1.Condition[]
lastAllocatedIP string
lastAllocatedNumber uint64
observedGeneration int64

BGPAdvertisementSpec

BGPAdvertisementSpec defines the desired state of BGPAdvertisement.

Used by: BGPAdvertisement.spec.

Property Description Type
addressPools string[]
nodeName NodeName, if non-empty, scopes the advertisement to a single node: only the bgp-speaker on the matching node emits the BGP route. When empty, every bgp-speaker advertises the configured prefixes. string
prefix Prefix, if non-empty, restricts the advertisement to a single CIDR prefix instead of advertising every CIDR backing the referenced AddressPool(s). The prefix must be contained in one of the referenced AddressPools' CIDRs. string

BGPNodeStateStatus

BGPNodeStateStatus defines the observed state of BGPNodeState.

Used by: BGPNodeState.status.

Property Description Type
advertisements BGPNodeStateAdvertisement[]
bgpSessions BGPNodeStateSession[]
conditions metav1.Condition[]
errors BGPNodeStateError[]
heartbeat metav1.Time

BGPPeerSpec

BGPPeerSpec defines the desired state of BGPPeer.

Used by: BGPPeer.spec.

Property Description Type
myASN int64
peerAddress string
peerASN int64
peerPort uint16

ElasticIPAttachmentSpec

ElasticIPAttachmentSpec defines the desired state of ElasticIPAttachment.

Used by: ElasticIPAttachment.spec.

Property Description Type
elasticIPRef ElasticIPAttachmentElasticIPRef
targetRef ElasticIPAttachmentTargetRef

ElasticIPAttachmentStatus

ElasticIPAttachmentStatus defines the observed state of ElasticIPAttachment.

Used by: ElasticIPAttachment.status.

Property Description Type
conditions metav1.Condition[]
elasticIP string
nodeName string
observedGeneration int64
phase ElasticIPAttachmentPhase
podIP string

ElasticIPSpec

ElasticIPSpec defines the desired state of ElasticIP.

Used by: ElasticIP.spec.

Property Description Type
externalNetwork string
Required
requestedIP RequestedIP optionally pins a specific address. The address must fall inside one of the AddressPools attached to the referenced ExternalNetwork. When unset (empty string) the controller picks the first available address. string

ElasticIPStatus

ElasticIPStatus defines the observed state of ElasticIP.

Used by: ElasticIP.status.

Property Description Type
address string
attachmentName string
conditions metav1.Condition[]
observedGeneration int64
phase ElasticIPPhase

ExternalNetworkAttachmentSpec

ExternalNetworkAttachmentSpec defines the desired state of ExternalNetworkAttachment.

Used by: ExternalNetworkAttachment.spec.

Property Description Type
externalNetwork string
nodeName string

ExternalNetworkAttachmentStatus

ExternalNetworkAttachmentStatus defines the observed state of ExternalNetworkAttachment.

Used by: ExternalNetworkAttachment.status.

Property Description Type
assignedIP AssignedIP is the per-(ExternalNetwork, Node) NAPT source IP allocated for this attachment. Populated by the reconciler once the underlying AllocationClaim resolves to an address. string
conditions metav1.Condition[]
observedGeneration int64

ExternalNetworkSpec

ExternalNetworkSpec defines the desired state of ExternalNetwork.

Used by: ExternalNetwork.spec.

Property Description Type
addressPools string[]
type ExternalNetworkType

NATGatewaySpec

NATGatewaySpec defines the desired state of NATGateway.

Used by: NATGateway.spec.

Property Description Type
externalNetwork string
vpc string

NATGatewayStatus

NATGatewayStatus defines the observed state of NATGateway.

Used by: NATGateway.status.

Property Description Type
conditions metav1.Condition[]
gatewayID GatewayID is the cluster-wide identifier allocated for this NATGateway. It is referenced by the data plane to look up per-(node, ExternalNetwork) NAPT source IPs. uint32
observedGeneration int64

NetworkACLSpec

NetworkACLSpec defines the desired state of NetworkACL.
Semantics:
- A NetworkACL is scoped to exactly one Vpc. Cross-Vpc references are rejected by webhook validation. - Each direction (Ingress, Egress) is independently configured: - nil (the field is omitted entirely) → default-allow for that direction. The Subnet boundary applies no policy and packets fall through to SecurityGroup unchanged. - non-nil empty list ([]) → default-deny. With no rules to match, every packet hits the implicit terminal deny. - non-empty list → rules evaluated in priority order; the first match's Action wins. Packets that match no rule fall to the implicit terminal deny. - The nil-vs-[] convention mirrors SecurityGroup so operators can reason about both layers consistently. - A Subnet attaches at most one NetworkACL via Subnet.spec.networkACL. Use rule priorities to compose multiple intents inside a single ACL rather than chaining several ACLs onto one Subnet.

Used by: NetworkACL.spec.

Property Description Type
egress Egress lists rules controlling traffic leaving Subnets that reference this ACL. NetworkACLRule[]
ingress Ingress lists rules controlling traffic entering Subnets that reference this ACL. Per-direction defaults follow the NetworkACLSpec nil-vs-[] convention. NetworkACLRule[]
vpc Vpc names the Vpc this NetworkACL belongs to. Immutable. string

NetworkACLStatus

NetworkACLStatus reports observed state.

Used by: NetworkACL.status.

Property Description Type
aclID ACLID is the cluster-wide identifier allocated for this ACL via an AllocationClaim. Daemons key acl_meta_map and acl_rule_table by this number; once assigned it never changes for the lifetime of the resource. uint32
attachedSubnets AttachedSubnets enumerates Subnets currently referencing this NetworkACL via spec.networkACL. Updated by the controller from an informer; observability only and may lag briefly. string[]
conditions metav1.Condition[]
egressRuleCount int32
hasEgressRules bool
hasIngressRules HasIngressRules / HasEgressRules report whether the spec set the direction explicitly (nil → false, [] or non-empty → true). Daemons use these to choose between default-allow (no enforcement at all) and default-deny (rule list applies, fall through to deny). bool
ingressRuleCount IngressRuleCount and EgressRuleCount report the rule count per direction (0 when the direction is nil/empty). Observability; not a hard limit. int32
observedGeneration int64
rulesetVersion RulesetVersion is bumped whenever the controller publishes a new effective ruleset summary. Daemons use this to invalidate stale CT entries when rules change. uint64

NetworkEndpointSpec

NetworkEndpointSpec defines the desired state of NetworkEndpoint.

Used by: NetworkEndpoint.spec.

Property Description Type
address Address is the L3 identity in CIDR form (e.g. "10.0.0.5/24"). string
attachment Attachment describes the local kernel iface that backs this endpoint on Spec.NodeName. Populated by the local daemon. NetworkEndpointAttachment
kind Kind identifies what produced this endpoint. EndpointKind
macAddress MACAddress is the L2 identity used as the destination MAC for this endpoint on the overlay. Always required for endpoints that participate in arp/fdb (i.e. all Kind=Pod and Kind=Node). string
nodeName NodeName pins the endpoint to a specific node. The daemon on this node owns the Attachment fields. string
podRef PodRef is required when Kind=Pod and otherwise omitted. NetworkEndpointPodReference
subnet Subnet is the L2 segment this endpoint participates in. string

NetworkEndpointStatus

NetworkEndpointStatus defines the observed state of NetworkEndpoint.

Used by: NetworkEndpoint.status.

Property Description Type
nodeIP NodeIP is the underlay IP of Spec.NodeName, populated by the controller. Used by remote daemons to populate fdb VTEP entries. string

NetworkInterfaceSpec

NetworkInterfaceSpec defines the desired state of NetworkInterface.

Used by: NetworkInterface.spec.

Property Description Type
address string
nodeName string
podRef NetworkInterfacePodReference
securityGroups SecurityGroups lists SecurityGroup resources whose rules apply to this interface. Order is irrelevant; rules from all listed SGs are unioned. An empty / nil list means "no SG enforcement" unless the owning Vpc has spec.enforceSecurityGroups=true, in which case Pod admission rejects unattached Pods.
All referenced SGs must belong to the same Vpc as this NetworkInterface's Subnet. Webhook validation enforces this.
string[]
subnet string

NetworkInterfaceStatus

NetworkInterfaceStatus defines the observed state of NetworkInterface.

Used by: NetworkInterface.status.

Property Description Type
address string
allocationClaim AllocationClaim names the cluster-scoped AllocationClaim that the reconciler maintains for this interface's IP reservation. Useful only for debugging — daemon/CNI consumers should rely on Address. string
conditions metav1.Condition[]
effectiveSecurityGroups EffectiveSecurityGroups echoes spec.securityGroups after the controller resolved them (filtered by existence + same-Vpc) and includes the assigned GroupID for each. Daemon reads this list rather than spec, so a stale/dangling spec entry never causes a blackhole. NetworkInterfaceEffectiveSG[]
observedGeneration int64
phase NetworkInterfacePhase
routes NetworkRoute[]

RouteTableSpec

RouteTableSpec defines the desired state of RouteTable.

Used by: RouteTable.spec.

Property Description Type
routes Route[]
vpc string

RouteTableStatus

RouteTableStatus defines the observed state of RouteTable.

Used by: RouteTable.status.

Property Description Type
conditions metav1.Condition[]
observedGeneration int64
routes Route[]
tableID uint32

SecurityGroupSpec

SecurityGroupSpec defines the desired state of SecurityGroup.
Semantics:
- A SecurityGroup is scoped to exactly one Vpc. Cross-Vpc references are rejected by webhook validation. - Ingress is implicitly deny-all; rules whitelist what is admitted. - When Egress is nil (the field is omitted), egress is implicitly allow-all (AWS-compatible default). When Egress is set (even as an empty list), egress flips to deny-by-default + allow-list.

Used by: SecurityGroup.spec.

Property Description Type
egress Egress lists rules permitting outbound traffic. nil (the field is omitted entirely) means "allow all egress" (AWS-compatible default). A non-nil list (even empty) flips egress to "deny-by-default, allow-by-rule". SecurityGroupEgressRule[]
ingress Ingress lists rules permitting inbound traffic. Empty/omitted means "deny all ingress". SecurityGroupIngressRule[]
vpc Vpc names the Vpc this SecurityGroup belongs to. Immutable. string

SecurityGroupStatus

SecurityGroupStatus reports observed state.

Used by: SecurityGroup.status.

Property Description Type
attachedInterfaces AttachedInterfaces enumerates NetworkInterfaces currently referencing this SecurityGroup. Updated by the controller from an informer; it is observability-only and may lag briefly. SecurityGroupAttachedInterface[]
conditions metav1.Condition[]
egressRuleCount int32
groupID GroupID is the cluster-wide identifier allocated for this SecurityGroup via an AllocationClaim. Daemon and BPF maps reference this number; once assigned it never changes for the lifetime of the resource. uint32
hasEgressRules HasEgressRules mirrors the spec choice (nil → false). Daemons use this to decide whether to apply egress allow-list semantics or default-allow. bool
ingressRuleCount IngressRuleCount and EgressRuleCount report how many flat (post-expansion) BPF rule entries the controller resolved for each direction. These are observability fields; they are not a hard cap (that lives in the data plane MAX_RULES_PER_SG). int32
observedGeneration int64
rulesetVersion RulesetVersion is bumped every time the controller resolves a new effective ruleset. Daemons can use it to detect and ack rule changes. uint64

ServiceLoadBalancerSpec

ServiceLoadBalancerSpec describes the desired LoadBalancer state derived from a Kubernetes Service.
A ServiceLoadBalancer is owned by exactly one Service in the same namespace. The controller uses ServiceRef.Name plus the resource's own namespace to resolve the parent Service; the resource is named deterministically from the parent Service so that multiple reconcilers can converge without racing on creation.

Used by: ServiceLoadBalancer.spec.

Property Description Type
externalNetwork ExternalNetwork selects the cluster-scoped ExternalNetwork from which the VIP is allocated. The referenced ExternalNetwork must exist and must declare at least one AddressPool. string
requestedIP RequestedIP optionally pins a specific IPv4 address. The address must fall inside one of the AddressPools attached to the referenced ExternalNetwork. When unset (empty string) the controller picks the first available address. string
serviceRef ServiceRef points at the Kubernetes Service that owns this resource. The Service must live in the same namespace as the ServiceLoadBalancer; cross-namespace references are rejected at admission time. ServiceLoadBalancerServiceReference

ServiceLoadBalancerStatus

ServiceLoadBalancerStatus reports the observed state derived from the parent Service, EndpointSlices, and the allocation pipeline.

Used by: ServiceLoadBalancer.status.

Property Description Type
addressPool AddressPool records which AddressPool the VIP was drawn from. Mainly informational; downstream consumers should not assume pool membership without re-resolving against the API. string
advertisingNodes AdvertisingNodes lists Kubernetes node names that currently have at least one ready local endpoint and may therefore advertise the VIP via BGP. The list is sorted lexicographically for stability. string[]
allocationClaimName AllocationClaimName names the AllocationClaim that owns the VIP allocation. Recorded so that finalization and observability can follow the claim without having to re-derive the name. string
backendSummary BackendSummary aggregates endpoint-level fleet health for dashboards. ServiceLoadBalancerBackendSummary
conditions Conditions track fine-grained observable state. See the ServiceLoadBalancerCondition* constants for the canonical set. metav1.Condition[]
observedGeneration ObservedGeneration is the .metadata.generation the status reflects. Status consumers should ignore status fields when observedGeneration < .metadata.generation. int64
phase Phase is a coarse human-readable lifecycle indicator. See the ServiceLoadBalancerPhase constants for the full set. ServiceLoadBalancerPhase
ports Ports is the canonical list of (port, protocol, targetPort) triples derived from the parent Service. The list is sorted by (Port, Protocol) so consumers see deterministic output. ServiceLoadBalancerPort[]
vip VIP is the allocated external IP address. Empty until allocation succeeds. Once written, the controller treats VIP as immutable for the lifetime of the resource. string

ServiceNATAttachmentSpec

ServiceNATAttachmentSpec defines the desired state of ServiceNATAttachment.
One ServiceNATAttachment exists per (Node, provider Vpc) pair: each provider Vpc (a Vpc with spec.service.provider.natSourceSubnet set) allocates one SNAT source IP per Node so that cross-VPC callers reaching shared Services in that Vpc receive replies over the provider Vpc's fabric back to the originating Node.

Used by: ServiceNATAttachment.spec.

Property Description Type
nodeName NodeName is the Kubernetes Node this attachment belongs to. string
vpc Vpc is the provider Vpc whose Service NAT pool the attachment allocates from. The Vpc must have spec.service.provider.natSourceSubnet set. string

ServiceNATAttachmentStatus

ServiceNATAttachmentStatus defines the observed state of ServiceNATAttachment.

Used by: ServiceNATAttachment.status.

Property Description Type
assignedIP AssignedIP is the per-Node SNAT source IP used to forward traffic from cross-VPC callers into shared Services owned by the provider Vpc. Allocated from the provider Vpc's spec.service.provider.natSourceSubnet by the ServiceNATAttachmentReconciler. string
assignedMAC AssignedMAC is the synthetic MAC paired with AssignedIP, published through a derived NetworkEndpoint so the provider Vpc's fabric can resolve the SNAT IP via ARP/fdb back to this Node. string
conditions metav1.Condition[]
observedGeneration int64
subnet Subnet records the Subnet the SNAT IP was allocated from. It mirrors the provider Vpc's spec.service.provider.natSourceSubnet at allocation time and is used by downstream reconcilers (NetworkEndpoint, daemon-side ARP/fdb) to install the entry in the right L2 segment. string

SubnetSpec

SubnetSpec defines the desired state of Subnet.

Used by: Subnet.spec.

Property Description Type
cidr string
networkACL NetworkACL names the NetworkACL applied at this Subnet's boundary. The referenced ACL must belong to the same Vpc as the Subnet (webhook-enforced). Empty means "no ACL" — the Subnet boundary does not enforce policy and traffic flows straight to the per-Pod SecurityGroup layer.
Mutability: the field is mutable. Switching the reference (or clearing it) re-converges the Subnet status and triggers daemon-side CT invalidation so flows pick up the new policy on their next packet.
string
routeTable RouteTable selects which RouteTable governs traffic from Pods in this Subnet. Empty means "use the owning Vpc's main RouteTable", which preserves the original behaviour. The referenced RouteTable must belong to the same Vpc. string
vpc string

SubnetStatus

SubnetStatus defines the observed state of Subnet.

Used by: Subnet.status.

Property Description Type
conditions metav1.Condition[]
dns DNS is the per-Subnet virtual DNS resolver IP (the second usable address in the prefix, conventionally .2). The juneau daemon terminates UDP/53 and TCP/53 destined for this address inside its virtual service plane and never bridges it to the underlay. Empty when the Subnet's prefix has no usable .2. string
dnsMAC DNSMAC is the locally-administered Ethernet address that ARP for the DNS VIP resolves to. Distinct from GatewayMAC so the data plane can demultiplex virtual-service traffic by destination MAC before consulting the FIB. Empty when DNS is empty. string
gateway string
gatewayMAC string
networkACL NetworkACL mirrors the resolved spec.networkACL reference. It carries the cluster-wide ACLID the daemon writes into the BPF subnet_map plus the ACL's RulesetVersion at the time the reference was resolved. Empty (nil) when spec.networkACL is unset or the named ACL does not yet exist. SubnetNetworkACLRef
observedGeneration int64
vni uint32

TraceSessionSpec

TraceSessionSpec is the desired state of a trace session.

Used by: TraceSession.spec.

Property Description Type
capture Capture controls per-event detail and event-class selection. TraceCaptureConfig
destination Destination identifies the target endpoint. Same role as Source — kubectl uses it for tuple computation; daemons match by tuple. TraceEndpoint
expiresAt ExpiresAt is the wall-clock time after which daemons must stop emitting events for this session and remove their local dataplane state. Mandatory. Protects against orphan sessions when kubectl crashes mid-trace. Daemons evaluate expiry on every reconcile; kubectl typically sets ExpiresAt to now() + session timeout + a small grace window. metav1.Time
initialTuples InitialTuples is the precomputed list of tuples kubectl expects the dataplane to match. There can be more than one per session because a Service ClusterIP may resolve to multiple backend Pods (one tuple per backend), or because kubectl wants to trace both directions of a flow at session start. Additional tuples discovered post-NAT are learned by daemons and fanned out via the debug stream. TraceTuple[]
mode Mode selects ActiveProbe (probe injection) or ObserveOnly (passive observation). ObserveOnly is the safe default for production. TraceMode
source Source identifies the originating endpoint. Used by kubectl when computing initial tuples and shown in the rendered timeline; daemons themselves match by tuple, not by source. TraceEndpoint
traceID TraceID is a session-stable identifier programmed into BPF maps. Daemons use it to attach trace state to in-flight packets without re-keying by full tuple. kubectl picks a random non-zero value at session creation; uniqueness is the caller's responsibility (collisions cause cross-talk between concurrent sessions). uint32

TraceSessionStatus

TraceSessionStatus is observed state.

Used by: TraceSession.status.

Property Description Type
conditions Conditions reports detailed lifecycle signals. The defined types live in the TraceSessionCondition* constants below. metav1.Condition[]
lastObservedAt LastObservedAt is the most recent time any daemon emitted a trace event for this session. Surfaced to operators so a "no events received" run is distinguishable from a daemon outage. metav1.Time
observedNodes ObservedNodes lists the node names whose juneaud has programmed local trace maps for this session. Updated by the daemon-side reconciler. Order is not significant. string[]
phase Phase summarizes the lifecycle stage. Useful for kubectl progress display; reconciliation does not branch on it. TraceSessionPhase

VpcSpec

VpcSpec defines the desired state of Vpc.

Used by: Vpc.spec.

Property Description Type
enforceSecurityGroups EnforceSecurityGroups makes SecurityGroup attachment mandatory for every Pod placed in a Subnet of this Vpc. Pods without the juneau.loutres.me/security-groups annotation (or with a list that resolves to zero valid SGs) are rejected at admission. Existing Pods are not retroactively affected when this flag is toggled. bool
service Service configures Service routing for this VPC. When nil, the VPC has no Service routing — its Pods cannot reach any ClusterIP and the controller does not inject a Service-typed route into the VPC's main RouteTable.
Two cross-VPC roles are independently configurable under this field: Provider (this VPC hosts Services that other VPCs may reach) and Consume (this VPC's Pods may reach shared Services hosted in other VPCs). Setting either implicitly enables Service routing for the VPC.
VpcServiceSpec

VpcStatus

VpcStatus defines the observed state of Vpc.

Used by: Vpc.status.

Property Description Type
conditions metav1.Condition[]
mainRouteTable string
observedGeneration int64
vpcID uint32

AddressPoolAdvertiseMode

Used by: AddressPoolSpec.advertiseMode.

AllocationClaimPhase

Used by: AllocationClaimStatus.phase.

AllocationFilter

Used by: AllocationClaimSpec.allocationFilter.

Property Description Type
cidrs CIDRs further narrow the candidate address space inside ip-typed pools. Each entry must be a subset of one of the pool CIDRs. string[]

AllocationLeasePhase

Used by: AllocationLeaseStatus.phase.

AllocationPoolIPSpec

Used by: AllocationPoolSpec.ip.

Property Description Type
cidrs CIDR ranges that participate in this pool. The union forms the candidate address space. string[]
excluded Excluded lists individual addresses that must never be allocated. Typically populated with reserved IPs such as gateway, network or broadcast addresses. string[]

AllocationPoolNumberSpec

Used by: AllocationPoolSpec.number.

Property Description Type
max uint64
min uint64

AllocationPoolReference

Used by: AllocationClaimSpec.poolRefs, and AllocationLeaseSpec.poolRef.

Property Description Type
name string

AllocationResourceReference

Used by: AllocationClaimSpec.resourceRef, and AllocationLeaseSpec.reuseKey.

Property Description Type
apiVersion string
kind string
name string
namespace Namespace of the referenced resource. Required when the owner is a namespaced resource; omit for cluster-scoped owners. string

AllocationStrategy

Used by: AllocationPoolSpec.strategy.

AllocationType

Used by: AllocationPoolSpec.type.

AllocationValue

Used by: AllocationClaimStatus.value, and AllocationLeaseSpec.value.

Property Description Type
ip string
number uint64

BGPNodeStateAdvertisement

Used by: BGPNodeStateStatus.advertisements.

Property Description Type
addressPool AddressPool, when set, names the AddressPool the prefix list is drawn from. Empty for non-pool sources (ServiceLoadBalancer). string
lastSyncedAt metav1.Time
prefixes Prefixes is the set of CIDRs that bgp-speaker intends to advertise for this advertisement. Derived from the source resource at reconcile time, not observed on the wire (BIRD BMP does not expose adj-RIB-out). string[]
sourceKind SourceKind identifies the upstream Kubernetes resource family (e.g. BGPAdvertisement, ServiceLoadBalancer). Optional for pre-existing AddressPool entries so older controllers reading this status keep working; new entries always set it. string
sourceName SourceName is the name of the source resource. Empty when an advertisement is shared across multiple resources of the same kind (e.g. multiple BGPAdvertisements pinning the same pool). string
sourceNamespace SourceNamespace is the namespace of the source resource. Empty for cluster-scoped sources. string

BGPNodeStateError

Used by: BGPNodeStateStatus.errors.

Property Description Type
lastSeen metav1.Time
message string
resourceKind string
resourceName string

BGPNodeStateSession

Used by: BGPNodeStateStatus.bgpSessions.

Property Description Type
lastError string
peerAddress PeerAddress is the BGP peer's IP address as observed on the wire via BMP. Always set. string
peerName PeerName is the BGPPeer resource name that configured this session. Empty when the BGPPeer resource could not be resolved (e.g. deleted but session still active, or bird.conf not yet reloaded). string
state string
upSince metav1.Time

ElasticIPAttachmentElasticIPRef

Used by: ElasticIPAttachmentSpec.elasticIPRef.

Property Description Type
name string

ElasticIPAttachmentPhase

Used by: ElasticIPAttachmentStatus.phase.

ElasticIPAttachmentTargetRef

Used by: ElasticIPAttachmentSpec.targetRef.

Property Description Type
networkInterfaceName string

ElasticIPPhase

Used by: ElasticIPStatus.phase.

EndpointKind

EndpointKind enumerates the kinds of network endpoints that can join an L2 segment (Subnet) on the data plane.
The data plane reconcilers (arp/fdb/pod-iface/attacher) are kind-agnostic; Kind exists for observability, validation (kind-specific required fields), and provider-specific bookkeeping (e.g. PodRef back-pointer for Kind=Pod).

Used by: NetworkEndpointSpec.kind.

ExternalNetworkType

Used by: ExternalNetworkSpec.type.

NetworkACLRule

NetworkACLRule is a single ordered rule applied at the Subnet boundary.
Unlike SecurityGroup, NetworkACL rules carry an explicit Priority and Action: rules run in priority order (low number first) and the first match decides the verdict. Peers are CIDR-only — Subnet-level ACLs describe address-based scopes; per-Pod identity matching belongs to SecurityGroup, which sits one stage downstream.

Used by: NetworkACLSpec.egress, and NetworkACLSpec.ingress.

Property Description Type
action Action declares what to do when this rule matches. NetworkACLAction
cidr CIDR is the peer address scope this rule matches. IPv4 only. "0.0.0.0/0" matches any address. string
description Description is free-form metadata returned in API responses for operator clarity; ignored by the data plane. string
ports Ports list the L4 destination ports admitted by this rule. Empty matches every port for the chosen protocol. When Protocol is "icmp" or "all", Ports must be empty. NetworkACLPort[]
priority Priority orders rules within their direction. Lower numbers run first; the first matching rule's Action wins. Priorities must be unique within each direction (webhook-enforced). int32
protocol Protocol selects the IP protocol. Defaults to "all" when empty. NetworkACLProtocol

NetworkEndpointAttachment

NetworkEndpointAttachment describes the local kernel iface that realizes this endpoint on Spec.NodeName. Populated by the daemon running on Spec.NodeName after the veth is created. Other nodes' daemons read the rest of Spec but ignore Attachment (ifindex is meaningless across nodes).

Used by: NetworkEndpointSpec.attachment.

Property Description Type
hostMACAddress HostMACAddress is the MAC of the host-side veth peer (the side that faces the host network stack on Spec.NodeName). Used by the data plane to populate ifindex_host_mac. string
ifindex Ifindex is the BPF-attached side of the veth pair on Spec.NodeName. int

NetworkEndpointPodReference

Used by: NetworkEndpointSpec.podRef.

Property Description Type
interface string
name string
uid string

NetworkInterfaceEffectiveSG

NetworkInterfaceEffectiveSG is a single resolved SecurityGroup reference. Daemon-side maps key off GroupID, never the name.

Used by: NetworkInterfaceStatus.effectiveSecurityGroups.

Property Description Type
groupID uint32
name string

NetworkInterfacePhase

Used by: NetworkInterfaceStatus.phase.

NetworkInterfacePodReference

Used by: NetworkInterfaceSpec.podRef.

Property Description Type
interface string
name string
uid string

NetworkRoute

Used by: NetworkInterfaceStatus.routes.

Property Description Type
dst string
gw string

Route

Used by: RouteTableSpec.routes, and RouteTableStatus.routes.

Property Description Type
dst string
subnet string
via RouteVia

SecurityGroupAttachedInterface

SecurityGroupAttachedInterface identifies a NetworkInterface that references this SecurityGroup.

Used by: SecurityGroupStatus.attachedInterfaces.

Property Description Type
name string
namespace string

SecurityGroupEgressRule

SecurityGroupEgressRule mirrors SecurityGroupIngressRule but for egress. The "to" side semantics are identical to "from".

Used by: SecurityGroupSpec.egress.

Property Description Type
description Description is free-form metadata. string
ports Ports list the destination ports admitted by this rule. SecurityGroupPort[]
protocol Protocol selects the IP protocol. Defaults to "all" when empty. SecurityGroupProtocol
to To lists the peers (CIDRs or SecurityGroupRefs) admitted by this rule. At least one peer is required. SecurityGroupPeer[]

SecurityGroupIngressRule

SecurityGroupIngressRule allows ingress traffic that matches the (peer × protocol × ports) cross-product. Multiple ingress rules are ORed together.

Used by: SecurityGroupSpec.ingress.

Property Description Type
description Description is free-form metadata returned in API responses for operator clarity; ignored by the data plane. string
from From lists the peers (CIDRs or SecurityGroupRefs) whose traffic is admitted by this rule. At least one peer is required. SecurityGroupPeer[]
ports Ports list the destination ports admitted by this rule. Empty list (or unset) matches any port for the chosen protocol. When Protocol is "icmp" or "all", Ports must be empty. SecurityGroupPort[]
protocol Protocol selects the IP protocol. Defaults to "all" when empty. SecurityGroupProtocol

ServiceLoadBalancerBackendSummary

ServiceLoadBalancerBackendSummary is a small aggregate of backend endpoint state. It exists so kubectl-juneau and dashboards can surface fleet health without re-listing EndpointSlices.

Used by: ServiceLoadBalancerStatus.backendSummary.

Property Description Type
localReadyNodes LocalReadyNodes is the number of distinct nodes that have at least one ready local endpoint. It is the cardinality of the AdvertisingNodes set when externalTrafficPolicy=Local. int32
totalReady TotalReady is the number of ready, serving, non-terminating endpoints across the whole Service. int32

ServiceLoadBalancerPhase

ServiceLoadBalancerPhase summarises the high-level lifecycle state.
The phase is informational and is intended for human consumption (kubectl printer columns and dashboards). Programmatic logic should use Conditions, which carry stable reason/status semantics.

Used by: ServiceLoadBalancerStatus.phase.

ServiceLoadBalancerPort

ServiceLoadBalancerPort mirrors the Service port that this LoadBalancer exposes externally. The port list is recomputed every reconcile from the parent Service so it stays in sync.

Used by: ServiceLoadBalancerStatus.ports.

Property Description Type
name Name of the port. May be empty if the parent Service uses a single unnamed port. string
port Port is the externally-exposed port that clients connect to on the VIP. int32
protocol Protocol is the L4 protocol. Only TCP and UDP are supported in the initial release; SCTP and other values are rejected at admission time. corev1.Protocol
targetPort TargetPort is the port on the backend Pod. When the parent Service uses a string targetPort, the controller resolves it against the backend EndpointSlice and writes the integer port here so dataplane consumers do not need to re-resolve names. int32

ServiceLoadBalancerServiceReference

ServiceLoadBalancerServiceReference identifies the parent Service.
The reference is intentionally minimal: ServiceLoadBalancer is always co-located with its Service, so the API does not surface a Namespace or Group/Kind field that could drift from reality.

Used by: ServiceLoadBalancerSpec.serviceRef.

Property Description Type
name Name of the Service in the same namespace as this resource. string

SubnetNetworkACLRef

SubnetNetworkACLRef carries the resolved view of a Subnet's NetworkACL attachment that the daemon needs to program the BPF subnet_map. Distinct from spec.networkACL because it folds in fields (ACLID, RulesetVersion) that the controller resolves at reconcile time and that the daemon cannot recompute from the spec alone.

Used by: SubnetStatus.networkACL.

Property Description Type
aclID ACLID is the resolved cluster-wide identifier from the referenced NetworkACL's status.aclID. Zero means "the ACL exists in spec but has not been allocated yet"; the daemon treats zero as "no ACL programmed" and falls back to default-allow until the controller publishes a non-zero value. uint32
name Name mirrors spec.networkACL — the user-facing reference. Kept in status so daemons consume one struct without cross-checking spec. string
rulesetVersion RulesetVersion mirrors the referenced ACL's status.rulesetVersion at the moment the reference was resolved. Daemons compare this against their last-applied value to decide whether to flush CT entries. uint64

TraceCaptureConfig

TraceCaptureConfig controls what events the dataplane emits. Defaults to a low-overhead "Decision" capture suitable for live debugging. Operators can opt in to extra detail at the cost of ringbuf pressure.

Used by: TraceSessionSpec.capture.

Property Description Type
includeMapMiss IncludeMapMiss surfaces lookup misses in subnet/fdb/arp/fib/ service/backend maps. Indispensable for "why did my packet drop?" debugging; cheap to emit because misses are rare in healthy clusters. bool
includeNAT IncludeNAT emits before/after tuples for DNAT, SNAT, NAPT, shared-Service and host-network Service rewrites. Necessary for cross-node propagation: trace_id assignment on the destination node depends on a learned post-NAT tuple. bool
includePacketMeta IncludePacketMeta enriches enter events with packet metadata (TCP flags, ICMP type/code). Costs one extra event field. bool
includePolicy IncludePolicy emits NetworkACL and SecurityGroup verdicts as dedicated events so a "policy drop" never has to be inferred from a missing follow-up event. bool
level Level selects the per-event verbosity. Defaults to Decision when empty. TraceCaptureLevel

TraceEndpoint

TraceEndpoint identifies one side of a trace session.
Exactly one of PodRef, ServiceRef or IP must be set. The webhook enforces this invariant; daemons treat a missing selector as a programming error and skip the session.
Protocol and Port are interpreted relative to the destination side only; on the source side they are ignored (a source pod's ephemeral port is not known until traffic flows).

Used by: TraceSessionSpec.destination, and TraceSessionSpec.source.

Property Description Type
ip IP is a literal IPv4 address (no CIDR). Useful for tracing node-internal IPs, external destinations and bare endpoints that have no Kubernetes object. string
podRef PodRef selects a Pod by namespace + name. The Pod must have a Juneau NetworkInterface attached. TracePodReference
port Port applies to the destination side. Required when this endpoint is a session's Destination and Protocol is TCP/UDP; ignored on Source and for ICMP. int32
protocol Protocol applies to the destination side. Required when this endpoint is a session's Destination, ignored on Source. TraceProtocol
serviceRef ServiceRef selects a Kubernetes Service by namespace + name. The destination tuple is computed from the Service's ClusterIP. Use Port + Protocol to disambiguate multi-port Services. TraceServiceReference

TraceMode

TraceSession is a temporary, cluster-scoped coordination object that activates dataplane tracing across every juneaud node for a single debugging session. The object is created by kubectl juneau trace for the lifetime of the trace and deleted on exit; daemons watch TraceSession resources, program local BPF trace maps, stream events to kubectl, and remove their dataplane state on delete or expiry.
TraceSession is intentionally ephemeral. The default workflow keeps detailed events out of CRD status entirely — events flow over a dedicated debug gRPC channel directly from the daemon to kubectl. Status only carries coarse coordination state (phase, observed nodes) so reconciliation stays cheap even with many concurrent sessions.
spec.expiresAt is mandatory: it bounds dataplane state if kubectl crashes between create and delete. Daemons treat any session past its expiry time as deleted and tear down local trace state even if the CRD has not yet been garbage-collected by the API server.
TraceMode selects whether a trace session injects probe traffic or only observes existing traffic that matches the configured tuples.

Used by: TraceSessionSpec.mode.

TraceSessionPhase

TraceSessionPhase reflects the controller-perceived state of the session. Daemons do not write Phase; they only append to ObservedNodes and bump LastObservedAt.

Used by: TraceSessionStatus.phase.

TraceTuple

TraceTuple is a five-tuple plus VPC scope. kubectl pre-computes the initial tuples it expects to see and stores them on the spec so daemons can program their BPF trace_tuple_map without re-resolving CRDs.

Used by: TraceSessionSpec.initialTuples.

Property Description Type
dstIP DstIP is the destination IPv4 address. string
dstPort DstPort is the destination L4 port. 0 wildcards the destination port (e.g. ICMP sessions). int32
protocol Protocol selects the IP protocol matched by this tuple. TraceProtocol
scope Scope selects the keyspace this tuple belongs to. Determines whether the daemon installs the tuple into the host or VPC trace_tuple_map keyspace. TraceTupleScope
srcIP SrcIP is the source IPv4 address. string
srcPort SrcPort is the source L4 port. 0 wildcards the source port. int32
vpcID VPCID is required when Scope=VPC and ignored otherwise. uint32

VpcServiceSpec

VpcServiceSpec configures the Service-routing behaviour of a VPC, including its participation in cross-VPC shared Services.
Setting either Provider or Consume enables Service routing for this VPC: the controller injects a Service-typed route into every RouteTable belonging to it so that Pods can reach ClusterIPs.

Used by: VpcSpec.service.

Property Description Type
consume Consume, when true, allows Pods in this VPC to call shared Services hosted in other VPCs. The per-Service ACL annotation (juneau.loutres.me/shared-service-allowed-consumer-vpcs) may further restrict which provider Services this VPC can reach. bool
provider Provider, when set, makes Services in this VPC eligible to be marked as cross-VPC shared via the juneau.loutres.me/shared-service annotation. Per-Node SNAT IPs are allocated from the configured Subnet so that backend replies flow over this VPC's fabric back to the originating caller's Node. VpcServiceProviderSpec

NetworkACLAction

NetworkACLAction is the verdict of a matching rule.
Rules are evaluated in priority order; the first matching rule's action is final. When no rule matches, the direction's default applies (see NetworkACLSpec for the nil-vs-[] convention).

Used by: NetworkACLRule.action.

NetworkACLPort

NetworkACLPort selects an L4 destination port (or range).
Either Port or PortRange must be set, never both. Webhook validation enforces this invariant. The struct mirrors SecurityGroupPort but is kept distinct so an accidental cross-kind assignment fails to compile.

Used by: NetworkACLRule.ports.

Property Description Type
port Port matches a single L4 destination port. int32
portRange PortRange matches a contiguous L4 destination port range. NetworkACLPortRange

NetworkACLProtocol

NetworkACLProtocol selects which IP protocol a rule matches.
"all" is a wildcard that suppresses any L4 port match (ports list must be empty). icmp accepts only protocol-level matching; ICMP type/code is not expressed by NetworkACL rules in v1alpha1.
The values intentionally line up with SecurityGroupProtocol so the same BPF matching primitives (policy_match.h) handle both layers. The Go types are kept separate so mixing an SG rule with an ACL rule fails at compile time rather than at the BPF write path.

Used by: NetworkACLRule.protocol.

RouteVia

Used by: Route.via.

Property Description Type
endpointName Endpoint is required when type=endpoint. Refers to a NetworkEndpoint by name. string
natGateway NATGateway is required when type=natGateway. Refers to a NATGateway by name (cluster-scoped). string
type RouteViaType

SecurityGroupPeer

SecurityGroupPeer expresses a single source/destination scope.
Exactly one of CIDR or SecurityGroupRef must be set. Webhook validation enforces this invariant; the controller assumes it during expansion.

Used by: SecurityGroupEgressRule.to, and SecurityGroupIngressRule.from.

Property Description Type
cidr CIDR matches any address inside the given IPv4 prefix. Mutually exclusive with SecurityGroupRef. string
securityGroupRef SecurityGroupRef matches any NetworkInterface whose membership set includes the referenced SecurityGroup. The referenced SG must belong to the same Vpc as this rule's parent. Mutually exclusive with CIDR. SecurityGroupPeerRef

SecurityGroupPort

SecurityGroupPort selects an L4 destination port (or range).
Either Port or PortRange must be set, never both. Webhook validation enforces this invariant.

Used by: SecurityGroupEgressRule.ports, and SecurityGroupIngressRule.ports.

Property Description Type
port Port matches a single L4 destination port. int32
portRange PortRange matches a contiguous L4 destination port range. SecurityGroupPortRange

SecurityGroupProtocol

SecurityGroupProtocol selects which IP protocol a rule matches.
"all" is a wildcard that suppresses any L4 port match (ports list must be empty). icmp accepts only protocol-level matching; ICMP type/code is not expressed by SecurityGroup rules in v1alpha1.

Used by: SecurityGroupEgressRule.protocol, and SecurityGroupIngressRule.protocol.

TraceCaptureLevel

TraceCaptureLevel selects how much detail the dataplane emits per matched packet. Verbose levels increase ringbuf pressure and are intended for short, targeted runs.

Used by: TraceCaptureConfig.level.

TracePodReference

TracePodReference identifies a Pod by namespace + name. Pod UID is resolved at session creation by kubectl and not stored in the CRD, so a Pod restart between create and observation does not invalidate the session.

Used by: TraceEndpoint.podRef.

Property Description Type
name string
namespace string

TraceProtocol

TraceProtocol selects the IP protocol matched by the session's tuples and probe. Mirrors the values used by NetworkACL and SecurityGroup so operators can reason about both layers consistently.

Used by: TraceEndpoint.protocol, and TraceTuple.protocol.

TraceServiceReference

TraceServiceReference identifies a Kubernetes Service by namespace Service's ClusterIP at admission time.

Used by: TraceEndpoint.serviceRef.

Property Description Type
name string
namespace string

TraceTupleScope

TraceTupleScope qualifies the keyspace a tuple lives in.
- Host: tuple is meaningful only on the underlay / host network namespace (NAPT outside-side, host-network Service backends). - VPC: tuple is scoped to a Juneau VPC; vpcID must be set.

Used by: TraceTuple.scope.

VpcServiceProviderSpec

VpcServiceProviderSpec configures the cross-VPC provider role of a VPC.

Used by: VpcServiceSpec.provider.

Property Description Type
natSourceSubnet NATSourceSubnet names a Subnet in this VPC from which per-Node SNAT source IPs are allocated for cross-VPC callers reaching shared Services owned by this VPC. The Subnet must exist and belong to this VPC. Required to mark Services in this VPC as shared. string

NetworkACLPortRange

NetworkACLPortRange specifies an inclusive [From,To] port range. To must be >= From.

Used by: NetworkACLPort.portRange.

Property Description Type
from int32
to int32

RouteViaType

Used by: RouteVia.type.

SecurityGroupPeerRef

SecurityGroupPeerRef names a peer SecurityGroup. The reference is resolved at admission time and re-resolved by the controller; rules that point at deleted SGs are dropped from the effective ruleset.

Used by: SecurityGroupPeer.securityGroupRef.

Property Description Type
name string

SecurityGroupPortRange

SecurityGroupPortRange specifies an inclusive [From,To] port range. To must be >= From.

Used by: SecurityGroupPort.portRange.

Property Description Type
from int32
to int32