feat: Name the upstream a request was proxied to in edge logs

api/v1alpha/networkinterface_types.go

@@ -260,6 +260,38 @@ type NetworkInterfaceAttachmentRef struct {
 	Name string `json:"name"`
 }
 
+// AttachedToRef names the consumer resource an interface is attached to, such
+// as a compute Instance. It is authored by whoever creates the claim, carried
+// onto the bound interface, and never interpreted here: the networking operator
+// has no idea what an Instance is, and the reference is opaque to it.
+//
+// It is distinct from NetworkInterfaceAttachmentRef, which the provider writes
+// to record the data-plane resource realizing the interface. This one names the
+// consumer-side thing the interface belongs to, so an operator reading an access
+// log can tell which backend served a request.
+type AttachedToRef struct {
+	// apiGroup is the API group of the referent, such as compute.datumapis.com.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	APIGroup string `json:"apiGroup"`
+
+	// kind is the kind of the referent, such as Instance.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=63
+	Kind string `json:"kind"`
+
+	// name is the name of the referent.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	Name string `json:"name"`
+}
+
 // NetworkInterfaceSpec defines the desired state of NetworkInterface. It is
 // written by the operator when a claim is fulfilled, and it carries everything
 // a provider needs to configure a NIC without reading any other resource.
@@ -336,6 +368,17 @@ type NetworkInterfaceSpec struct {
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:default="Delete"
 	ReclaimPolicy NetworkInterfaceReclaimPolicy `json:"reclaimPolicy,omitempty"`
+
+	// attachedTo names the consumer resource this interface is attached to, such
+	// as a compute Instance. It comes from the claim, and the operator carries it
+	// without interpreting it, the same way the held-by label and the
+	// HolderAvailable condition name the holder without knowing what a holder is.
+	// The holder surface says a holder exists and whether it serves; this says
+	// what the holder is, so a reader tracing traffic to a member can name the
+	// backend behind it.
+	//
+	// +kubebuilder:validation:Optional
+	AttachedTo *AttachedToRef `json:"attachedTo,omitempty"`
 }
 
 // NetworkInterfaceStatus defines the observed state of NetworkInterface: which

api/v1alpha/networkinterfaceclaim_types.go

@@ -102,6 +102,7 @@ type NetworkInterfaceAddressRequest struct {
 //
 // +kubebuilder:validation:XValidation:message="networkInterfaceName is immutable and cannot be set, changed, or cleared after creation",rule="has(self.networkInterfaceName) == has(oldSelf.networkInterfaceName) && (!has(self.networkInterfaceName) || self.networkInterfaceName == oldSelf.networkInterfaceName)"
 // +kubebuilder:validation:XValidation:message="addresses is immutable and cannot be set, changed, or cleared after creation",rule="has(self.addresses) == has(oldSelf.addresses) && (!has(self.addresses) || self.addresses == oldSelf.addresses)"
+// +kubebuilder:validation:XValidation:message="attachedTo is immutable and cannot be set, changed, or cleared after creation",rule="has(self.attachedTo) == has(oldSelf.attachedTo) && (!has(self.attachedTo) || self.attachedTo == oldSelf.attachedTo)"
 type NetworkInterfaceClaimSpec struct {
 	// network is the network the interface attaches to. The network must already
 	// exist in the same namespace as the claim.
@@ -215,6 +216,20 @@ type NetworkInterfaceClaimSpec struct {
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
 	NetworkInterfaceName string `json:"networkInterfaceName,omitempty"`
+
+	// attachedTo names the consumer resource this interface is attached to, such
+	// as a compute Instance. It is set by whoever creates the claim.
+	//
+	// It is copied to the bound interface and never interpreted here. The
+	// networking operator has no idea what an Instance is; it carries the
+	// reference so a reader tracing traffic to a member can name the backend
+	// behind it.
+	//
+	// Immutable, because a bound interface's attachment does not move to a
+	// different consumer resource.
+	//
+	// +kubebuilder:validation:Optional
+	AttachedTo *AttachedToRef `json:"attachedTo,omitempty"`
 }
 
 // NetworkInterfaceClaimStatus defines the observed state of

config/crd/bases/networking.datumapis.com_networkinterfaceclaims.yaml

@@ -108,6 +108,40 @@ spec:
                 x-kubernetes-validations:
                 - message: Each address class may be requested at most once
                   rule: self.all(a, self.exists_one(b, b.class == a.class))
+              attachedTo:
+                description: |-
+                  attachedTo names the consumer resource this interface is attached to, such
+                  as a compute Instance. It is set by whoever creates the claim.
+
+                  It is copied to the bound interface and never interpreted here. The
+                  networking operator has no idea what an Instance is; it carries the
+                  reference so a reader tracing traffic to a member can name the backend
+                  behind it.
+
+                  Immutable, because a bound interface's attachment does not move to a
+                  different consumer resource.
+                properties:
+                  apiGroup:
+                    description: apiGroup is the API group of the referent, such as
+                      compute.datumapis.com.
+                    maxLength: 253
+                    minLength: 1
+                    type: string
+                  kind:
+                    description: kind is the kind of the referent, such as Instance.
+                    maxLength: 63
+                    minLength: 1
+                    type: string
+                  name:
+                    description: name is the name of the referent.
+                    maxLength: 253
+                    minLength: 1
+                    type: string
+                required:
+                - apiGroup
+                - kind
+                - name
+                type: object
               attachmentMode:
                 default: Netns
                 description: |-
@@ -249,6 +283,10 @@ spec:
                 after creation
               rule: has(self.addresses) == has(oldSelf.addresses) && (!has(self.addresses)
                 || self.addresses == oldSelf.addresses)
+            - message: attachedTo is immutable and cannot be set, changed, or cleared
+                after creation
+              rule: has(self.attachedTo) == has(oldSelf.attachedTo) && (!has(self.attachedTo)
+                || self.attachedTo == oldSelf.attachedTo)
           status:
             default:
               conditions:

config/crd/bases/networking.datumapis.com_networkinterfaces.yaml

@@ -142,6 +142,37 @@ spec:
                     == 1
                 - message: Only one address may be held per address family
                   rule: self.all(a, self.exists_one(b, b.family == a.family))
+              attachedTo:
+                description: |-
+                  attachedTo names the consumer resource this interface is attached to, such
+                  as a compute Instance. It comes from the claim, and the operator carries it
+                  without interpreting it, the same way the held-by label and the
+                  HolderAvailable condition name the holder without knowing what a holder is.
+                  The holder surface says a holder exists and whether it serves; this says
+                  what the holder is, so a reader tracing traffic to a member can name the
+                  backend behind it.
+                properties:
+                  apiGroup:
+                    description: apiGroup is the API group of the referent, such as
+                      compute.datumapis.com.
+                    maxLength: 253
+                    minLength: 1
+                    type: string
+                  kind:
+                    description: kind is the kind of the referent, such as Instance.
+                    maxLength: 63
+                    minLength: 1
+                    type: string
+                  name:
+                    description: name is the name of the referent.
+                    maxLength: 253
+                    minLength: 1
+                    type: string
+                required:
+                - apiGroup
+                - kind
+                - name
+                type: object
               attachmentMode:
                 default: Netns
                 description: |-

docs/api/networkinterfaceclaims.md

@@ -74,7 +74,7 @@ it. To change one of those fields, delete the claim and create a new one,
 accepting that the workload gets new addresses unless the interface is
 retained.<br/>
           <br/>
-            <i>Validations</i>:<li>has(self.networkInterfaceName) == has(oldSelf.networkInterfaceName) && (!has(self.networkInterfaceName) || self.networkInterfaceName == oldSelf.networkInterfaceName): networkInterfaceName is immutable and cannot be set, changed, or cleared after creation</li><li>has(self.addresses) == has(oldSelf.addresses) && (!has(self.addresses) || self.addresses == oldSelf.addresses): addresses is immutable and cannot be set, changed, or cleared after creation</li>
+            <i>Validations</i>:<li>has(self.networkInterfaceName) == has(oldSelf.networkInterfaceName) && (!has(self.networkInterfaceName) || self.networkInterfaceName == oldSelf.networkInterfaceName): networkInterfaceName is immutable and cannot be set, changed, or cleared after creation</li><li>has(self.addresses) == has(oldSelf.addresses) && (!has(self.addresses) || self.addresses == oldSelf.addresses): addresses is immutable and cannot be set, changed, or cleared after creation</li><li>has(self.attachedTo) == has(oldSelf.attachedTo) && (!has(self.attachedTo) || self.attachedTo == oldSelf.attachedTo): attachedTo is immutable and cannot be set, changed, or cleared after creation</li>
         </td>
         <td>true</td>
       </tr><tr>
@@ -142,22 +142,40 @@ Omit this field for ordinary private addressing, which is the common case.<br/>
             <i>Validations</i>:<li>self.all(a, self.exists_one(b, b.class == a.class)): Each address class may be requested at most once</li>
         </td>
         <td>false</td>
+      </tr><tr>
+        <td><b><a href="#networkinterfaceclaimspecattachedto">attachedTo</a></b></td>
+        <td>object</td>
+        <td>
+          attachedTo names the consumer resource this interface is attached to, such
+as a compute Instance. It is set by whoever creates the claim.
+
+It is copied to the bound interface and never interpreted here. The
+networking operator has no idea what an Instance is; it carries the
+reference so a reader tracing traffic to a member can name the backend
+behind it.
+
+Immutable, because a bound interface's attachment does not move to a
+different consumer resource.<br/>
+        </td>
+        <td>false</td>
       </tr><tr>
         <td><b>attachmentMode</b></td>
         <td>enum</td>
         <td>
           attachmentMode is how the guest consumes this interface. Netns places it in
 the workload's network namespace, which is what an ordinary container
 expects. Hypervisor hands it to a hypervisor as a device, which is what a
-virtual machine or microVM guest needs.
+virtual machine or microVM guest needs. HypervisorDeclared also hands it
+to a hypervisor, and additionally has the realizer state the device to
+that hypervisor instead of letting it discover the device from the node.
 
 It is copied to the bound interface and never interpreted here. Whoever
 realizes the interface decides what each mode means on its data plane.
 
 Immutable, because the guest and the attachment are both built against it.<br/>
           <br/>
             <i>Validations</i>:<li>self == oldSelf: attachmentMode is immutable and cannot be changed after creation</li>
-            <i>Enum</i>: Netns, Hypervisor<br/>
+            <i>Enum</i>: Netns, Hypervisor, HypervisorDeclared<br/>
             <i>Default</i>: Netns<br/>
         </td>
         <td>false</td>
@@ -309,6 +327,56 @@ CIDR, so a class cannot be used to ask for a particular address.<br/>
 </table>
 
 
+### NetworkInterfaceClaim.spec.attachedTo
+<sup><sup>[↩ Parent](#networkinterfaceclaimspec)</sup></sup>
+
+
+
+attachedTo names the consumer resource this interface is attached to, such
+as a compute Instance. It is set by whoever creates the claim.
+
+It is copied to the bound interface and never interpreted here. The
+networking operator has no idea what an Instance is; it carries the
+reference so a reader tracing traffic to a member can name the backend
+behind it.
+
+Immutable, because a bound interface's attachment does not move to a
+different consumer resource.
+
+<table>
+    <thead>
+        <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Description</th>
+            <th>Required</th>
+        </tr>
+    </thead>
+    <tbody><tr>
+        <td><b>apiGroup</b></td>
+        <td>string</td>
+        <td>
+          apiGroup is the API group of the referent, such as compute.datumapis.com.<br/>
+        </td>
+        <td>true</td>
+      </tr><tr>
+        <td><b>kind</b></td>
+        <td>string</td>
+        <td>
+          kind is the kind of the referent, such as Instance.<br/>
+        </td>
+        <td>true</td>
+      </tr><tr>
+        <td><b>name</b></td>
+        <td>string</td>
+        <td>
+          name is the name of the referent.<br/>
+        </td>
+        <td>true</td>
+      </tr></tbody>
+</table>
+
+
 ### NetworkInterfaceClaim.status
 <sup><sup>[↩ Parent](#networkinterfaceclaim)</sup></sup>