feat: Carry internet egress to the node that serves it

api/v1alpha1/vpcattachment_types.go

@@ -114,6 +114,85 @@ type VPCAttachmentInterface struct {
 	Addresses []IPAddress `json:"addresses,omitempty"`
 }
 
+// InternetEgressAddressFamily is the address family of an egress source
+// address.
+//
+// Only IPv6 is reported. Reaching an IPv4 destination needs a resolver and a
+// translator sharing a prefix, which the platform pairs neither of, so the
+// value is withheld rather than reported and not delivered. An address written
+// today records IPv6, so accepting IPv4 later changes no attachment.
+//
+// +kubebuilder:validation:Enum=IPv6
+type InternetEgressAddressFamily string
+
+// InternetEgressAddressFamilyIPv6 is an IPv6 egress source address.
+const InternetEgressAddressFamilyIPv6 InternetEgressAddressFamily = "IPv6"
+
+// InternetEgressAddressStability is how far a consumer may rely on an egress
+// source address. It is the consumer-side projection of the serving class's
+// sharing, derived here so a consumer never reads a class.
+//
+// +kubebuilder:validation:Enum=None;Network
+type InternetEgressAddressStability string
+
+const (
+	// InternetEgressAddressStabilityNone means the address may change and
+	// other networks share it. Allow-listing it admits traffic from other
+	// networks and loses access when the address changes.
+	InternetEgressAddressStabilityNone InternetEgressAddressStability = "None"
+
+	// InternetEgressAddressStabilityNetwork means the address belongs to this
+	// network and persists. Allow-listing it is safe.
+	InternetEgressAddressStabilityNetwork InternetEgressAddressStability = "Network"
+)
+
+// InternetEgressSourceAddress is one address outbound traffic leaves on.
+//
+// +kubebuilder:validation:XValidation:rule="self.family != 'IPv6' || (isIP(self.address) && ip(self.address).family() == 6)",message="an IPv6 source address must be a valid IPv6 address"
+type InternetEgressSourceAddress struct {
+	// Family is the address family of this source address.
+	// +required
+	Family InternetEgressAddressFamily `json:"family"`
+
+	// Address is the source address translation writes, without a prefix
+	// length.
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=39
+	// +required
+	Address string `json:"address"`
+
+	// Stability states how far a consumer may rely on this address before
+	// they act on it.
+	// +required
+	Stability InternetEgressAddressStability `json:"stability"`
+}
+
+// VPCAttachmentInternetEgressStatus reports the outbound path this attachment
+// leaves the platform on.
+type VPCAttachmentInternetEgressStatus struct {
+	// SourceAddresses are the addresses translation writes for this
+	// attachment, one per family reached.
+	//
+	// Absent means this attachment reaches nothing outside the platform, or
+	// that no address has been reported for a path that does. An absent list
+	// is never a placeholder: a consumer that allow-listed a guessed address
+	// would admit the wrong traffic and believe otherwise.
+	//
+	// +listType=map
+	// +listMapKey=family
+	// +kubebuilder:validation:MaxItems=2
+	// +optional
+	SourceAddresses []InternetEgressSourceAddress `json:"sourceAddresses,omitempty"`
+}
+
+// VPCAttachmentEgressStatus reports what this attachment reaches outside the
+// platform.
+type VPCAttachmentEgressStatus struct {
+	// Internet is the internet egress realized for this attachment.
+	// +optional
+	Internet *VPCAttachmentInternetEgressStatus `json:"internet,omitempty"`
+}
+
 // VPCAttachmentStatus defines the observed state of VPCAttachment.
 //
 // Every field but Conditions is optional: an identifier is recorded before a pod
@@ -181,6 +260,15 @@ type VPCAttachmentStatus struct {
 	// +kubebuilder:validation:MinLength=1
 	// +optional
 	NetworkAttachmentDefinition string `json:"networkAttachmentDefinition,omitempty"`
+
+	// Egress reports what this attachment reaches outside the platform.
+	//
+	// It is reported per attachment rather than on the network, because the
+	// interface is what a workload holds and what a consumer reads back
+	// through. This controller is the only component that resolved which shard
+	// the network bound to, so it is the only one that can report the answer.
+	// +optional
+	Egress *VPCAttachmentEgressStatus `json:"egress,omitempty"`
 }
 
 // +kubebuilder:object:root=true

config/crd/cloud.datumapis.com_vpcattachments.yaml

@@ -164,6 +164,69 @@ spec:
                 maxLength: 46
                 minLength: 46
                 type: string
+              egress:
+                description: |-
+                  Egress reports what this attachment reaches outside the platform.
+
+                  It is reported per attachment rather than on the network, because the
+                  interface is what a workload holds and what a consumer reads back
+                  through. This controller is the only component that resolved which shard
+                  the network bound to, so it is the only one that can report the answer.
+                properties:
+                  internet:
+                    description: Internet is the internet egress realized for this
+                      attachment.
+                    properties:
+                      sourceAddresses:
+                        description: |-
+                          SourceAddresses are the addresses translation writes for this
+                          attachment, one per family reached.
+
+                          Absent means this attachment reaches nothing outside the platform, or
+                          that no address has been reported for a path that does. An absent list
+                          is never a placeholder: a consumer that allow-listed a guessed address
+                          would admit the wrong traffic and believe otherwise.
+                        items:
+                          description: InternetEgressSourceAddress is one address
+                            outbound traffic leaves on.
+                          properties:
+                            address:
+                              description: |-
+                                Address is the source address translation writes, without a prefix
+                                length.
+                              maxLength: 39
+                              minLength: 1
+                              type: string
+                            family:
+                              description: Family is the address family of this source
+                                address.
+                              enum:
+                              - IPv6
+                              type: string
+                            stability:
+                              description: |-
+                                Stability states how far a consumer may rely on this address before
+                                they act on it.
+                              enum:
+                              - None
+                              - Network
+                              type: string
+                          required:
+                          - address
+                          - family
+                          - stability
+                          type: object
+                          x-kubernetes-validations:
+                          - message: an IPv6 source address must be a valid IPv6 address
+                            rule: self.family != 'IPv6' || (isIP(self.address) &&
+                              ip(self.address).family() == 6)
+                        maxItems: 2
+                        type: array
+                        x-kubernetes-list-map-keys:
+                        - family
+                        x-kubernetes-list-type: map
+                    type: object
+                type: object
               guestInterface:
                 description: Guest-side veth device name (e.g., "G000000010013G").
                 minLength: 1

config/crd/kustomization.yaml

@@ -6,3 +6,5 @@ resources:
   # Written centrally, federated to the cells that need it, so it is installed
   # both places.
   - cloud.datumapis.com_networkfabricidentities.yaml
+  # Cell-local: an operator writes one per InternetEgressClass this cell serves,
+  # and only the controller in the cell reads it.

config/rbac/role.yaml

@@ -71,6 +71,7 @@ rules:
   resources:
   - bgpadvertisements
   - bgprouters
+  - egressshards
   verbs:
   - get
   - list

docs/api/vpc.md

@@ -29,6 +29,67 @@ _Appears in:_
 
 
 
+#### InternetEgressAddressFamily
+
+_Underlying type:_ _string_
+
+InternetEgressAddressFamily is the address family of an egress source
+address.
+
+Only IPv6 is reported. Reaching an IPv4 destination needs a resolver and a
+translator sharing a prefix, which the platform pairs neither of, so the
+value is withheld rather than reported and not delivered. An address written
+today records IPv6, so accepting IPv4 later changes no attachment.
+
+_Validation:_
+- Enum: [IPv6]
+
+_Appears in:_
+- [InternetEgressSourceAddress](#internetegresssourceaddress)
+
+| Field | Description |
+| --- | --- |
+| `IPv6` |  |
+
+
+#### InternetEgressAddressStability
+
+_Underlying type:_ _string_
+
+InternetEgressAddressStability is how far a consumer may rely on an egress
+source address. It is the consumer-side projection of the serving class's
+sharing, derived here so a consumer never reads a class.
+
+_Validation:_
+- Enum: [None Network]
+
+_Appears in:_
+- [InternetEgressSourceAddress](#internetegresssourceaddress)
+
+| Field | Description |
+| --- | --- |
+| `None` | InternetEgressAddressStabilityNone means the address may change and<br />other networks share it. Allow-listing it admits traffic from other<br />networks and loses access when the address changes.<br /> |
+| `Network` | InternetEgressAddressStabilityNetwork means the address belongs to this<br />network and persists. Allow-listing it is safe.<br /> |
+
+
+#### InternetEgressSourceAddress
+
+
+
+InternetEgressSourceAddress is one address outbound traffic leaves on.
+
+
+
+_Appears in:_
+- [VPCAttachmentInternetEgressStatus](#vpcattachmentinternetegressstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `family` _[InternetEgressAddressFamily](#internetegressaddressfamily)_ | Family is the address family of this source address. |  | Enum: [IPv6] <br /> |
+| `address` _string_ | Address is the source address translation writes, without a prefix<br />length. |  | MaxLength: 39 <br />MinLength: 1 <br /> |
+| `stability` _[InternetEgressAddressStability](#internetegressaddressstability)_ | Stability states how far a consumer may rely on this address before<br />they act on it. |  | Enum: [None Network] <br /> |
+
+
 #### Network
 
 _Underlying type:_ _string_
@@ -172,6 +233,23 @@ VPCAttachment is the Schema for the vpcattachments API
 | `status` _[VPCAttachmentStatus](#vpcattachmentstatus)_ | status defines the observed state of VPCAttachment |  |  |
 
 
+#### VPCAttachmentEgressStatus
+
+
+
+VPCAttachmentEgressStatus reports what this attachment reaches outside the
+platform.
+
+
+
+_Appears in:_
+- [VPCAttachmentStatus](#vpcattachmentstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `internet` _[VPCAttachmentInternetEgressStatus](#vpcattachmentinternetegressstatus)_ | Internet is the internet egress realized for this attachment. |  |  |
+
+
 #### VPCAttachmentInterface
 
 
@@ -211,6 +289,23 @@ _Appears in:_
 | `HypervisorDeclared` | VPCAttachmentInterfaceModeHypervisorDeclared also hands the interface to a<br />hypervisor as a device. It differs from Hypervisor in who tells the<br />hypervisor that the device exists. Under Hypervisor the hypervisor finds<br />the device from what the node publishes. Under HypervisorDeclared the data<br />plane states the device, its addresses, and its MTU to the hypervisor<br />directly, which is what a guest whose hypervisor reads no node state<br />needs.<br /> |
 
 
+#### VPCAttachmentInternetEgressStatus
+
+
+
+VPCAttachmentInternetEgressStatus reports the outbound path this attachment
+leaves the platform on.
+
+
+
+_Appears in:_
+- [VPCAttachmentEgressStatus](#vpcattachmentegressstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `sourceAddresses` _[InternetEgressSourceAddress](#internetegresssourceaddress) array_ | SourceAddresses are the addresses translation writes for this<br />attachment, one per family reached.<br />Absent means this attachment reaches nothing outside the platform, or<br />that no address has been reported for a path that does. An absent list<br />is never a placeholder: a consumer that allow-listed a guessed address<br />would admit the wrong traffic and believe otherwise. |  | MaxItems: 2 <br /> |
+
+
 #### VPCAttachmentSpec
 
 
@@ -257,6 +352,7 @@ _Appears in:_
 | `guestInterface` _string_ | Guest-side veth device name (e.g., "G000000010013G"). |  | MinLength: 1 <br /> |
 | `podSubnet` _string_ | Allocated subnet in CIDR notation (e.g., "fd00:10:ff01:0:1::/80"). |  | MinLength: 1 <br /> |
 | `networkAttachmentDefinition` _string_ | NetworkAttachmentDefinition rendered for this attachment. |  | MinLength: 1 <br /> |
+| `egress` _[VPCAttachmentEgressStatus](#vpcattachmentegressstatus)_ | Egress reports what this attachment reaches outside the platform.<br />It is reported per attachment rather than on the network, because the<br />interface is what a workload holds and what a consumer reads back<br />through. This controller is the only component that resolved which shard<br />the network bound to, so it is the only one that can report the answer. |  |  |
 
 
 #### VPCRef