Skip to content

galactic.md

Latest commit

 

History

History
1082 lines (623 loc) · 50 KB

galactic.md

File metadata and controls

1082 lines (623 loc) · 50 KB
Raw

Generated from api/v1alpha1. Edit the API comments or .crd-ref-docs.yaml, then run task generate:api-docs. See the API index for resource ownership.

API Reference

Packages

galactic.datumapis.com/v1alpha1

Package v1alpha1 contains Galactic's own API, galactic.datumapis.com/v1alpha1: TrafficPolicy and TrafficPolicyBinding, the per-interface ingress and egress policy the CNI datapath enforces (see docs/enhancements/networking/interface-traffic-policy), and EdgeProvider, EdgeProviderApproval and EdgeService, the Galactic Edge provider registration, its operator approval and a tenant grant, EdgeInstance and EdgeAttachment, a provider pod and its connection to a granted VPC, and EdgeRoute and EdgeRouteIndex, a prefix's forwarding claim and the record of every claim accepted in a VPC (see docs/enhancements/networking/galactic-edge).

Resource Types

AppliedPolicy

AppliedPolicy is what one node has installed for one direction.

Appears in:

Field Description Default Validation
policy PolicyIdentity Policy is the installed policy's identity, absent when nothing is
installed and the direction denies as policy_unavailable.
state AppliedState State is Applied when Policy is installed and matches the desired
policy, Pending while it is not yet, and Failed when installation
failed. A Failed direction keeps enforcing Policy, its last good
snapshot, or denies when there is none.		 Enum: [Applied Pending Failed]
observedGeneration integer ObservedGeneration is the binding generation this entry reflects.
message string Message explains a Pending or Failed state. MaxLength: 1024
lastTransitionTime Time LastTransitionTime is when Policy last changed.

AppliedState

Underlying type: string

AppliedState is how far one node's installation of a direction has got.

Validation:

  • Enum: [Applied Pending Failed]

Appears in:

Field Description
Applied StateApplied means the desired policy is installed.
Pending StatePending means the desired policy is not installed yet.
Failed StateFailed means installing the desired policy failed.

ConfigurationKind

ConfigurationKind names the provider-owned resource its services' own configuration is written in.

Appears in:

Field Description Default Validation
group string Group is the resource's API group. MaxLength: 253
MinLength: 1
kind string Kind is the resource's kind. MaxLength: 63
MinLength: 1

DirectionStatus

DirectionStatus reports what one direction's reference resolved to.

Appears in:

Field Description Default Validation
policy PolicyIdentity Policy is the resolved policy, absent while the reference is
unresolved.
conditions Condition array Conditions include Resolved. MaxItems: 8

EdgeAllocation

EdgeAllocation is one client pool address and the attachment holding it.

Appears in:

Field Description Default Validation
address string Address is the allocated IPv6 address. MaxLength: 39
attachment string Attachment is the holding EdgeAttachment's namespace and name. MaxLength: 317
attachmentUID string AttachmentUID is the holding EdgeAttachment's metadata.uid. MaxLength: 36

EdgeAttachment

EdgeAttachment is one provider instance's isolated connection to the VPC its EdgeService grants: an address from the service's client pool, a link from the pod into the VPC's host VRF on the pod's node and, with PacketAccess, a TUN device. It lives in the provider's namespace. Its name is ea- followed by the pod UID, a hyphen and the service UID, so a retried create lands on the same object and no pod can take another pod's name.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeAttachment
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeAttachmentSpec
status EdgeAttachmentStatus

EdgeAttachmentSpec

EdgeAttachmentSpec is an instance's request for one isolated connection to its service's VPC. The instance writes it at create; a ValidatingAdmissionPolicy requires podUID to be the pod its token was issued for.

Appears in:

Field Description Default Validation
providerRef EdgeProviderReference ProviderRef is the provider the requesting instance runs. It must be
the service's and the instance's provider. The provider's admission
binding checks the writer against it.
serviceRef EdgeServiceReference ServiceRef is the EdgeService granting the VPC.
instanceRef EdgeInstanceReference InstanceRef is the requesting EdgeInstance.
podUID string PodUID is the requesting pod's metadata.uid. It must equal the
instance's.		 MaxLength: 36
MinLength: 1
contractVersion string ContractVersion is the provider contract version the request is
written to.		 MaxLength: 16
MinLength: 1
capabilities EdgeCapability array Capabilities are the capability versions the attachment uses:
SocketAccess, PacketAccess or both.		 MaxItems: 2
MinItems: 1
packetDevice EdgePacketDevice PacketDevice owns the TUN device. Required with PacketAccess.

EdgeAttachmentStatus

EdgeAttachmentStatus is the attachment's lifecycle. A field is written only by the writer named on it.

Appears in:

Field Description Default Validation
conditions Condition array Conditions are Admitted, Allocated, Draining, Published (core),
Programmed, Released (node) and Ready (provider).		 MaxItems: 8
nodeName string NodeName is the node that programs the attachment, from its instance.
Set by core at admission.		 MaxLength: 253
vpc string VPC is the base62 identifier of the service's VPC. Set by core at
admission.		 MaxLength: 16
address string Address is the attachment's IPv6 address in the VPC, from the
service's client pool. Set by core at allocation.		 MaxLength: 39
drainDeadline Time DrainDeadline is when core deletes an attachment it is draining.
hostLink string HostLink is the host end of the attachment's link. Set by the node. MaxLength: 15
podVRF string PodVRF is the VRF in the provider pod that the provider binds its
sockets to. Set by the node.		 MaxLength: 15
packetDevice string PacketDevice is the TUN device in the provider pod. Set by the node
for a PacketAccess attachment.		 MaxLength: 15

EdgeCapability

EdgeCapability is a capability a provider implements, at one version, such as PacketAccess v1.

Appears in:

Field Description Default Validation
name string Name is the capability's name. Enum: [SocketAccess PacketAccess PrefixReachability]
version string Version is the capability's version. Pattern: ^v[1-9][0-9]*$

EdgeInstance

EdgeInstance is one running Galactic Edge provider pod. Its attachments name it, and the foundation checks it against the pod it names before admitting them. Routes name it with its lease's incarnation and epoch, and their forwarding gates stay open only while that lease is renewed. Its name is ei- followed by the pod UID, so a retried create lands on the same object; a ValidatingAdmissionPolicy refuses a provider pod's create of an instance or lease under any other name.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeInstance
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeInstanceSpec

EdgeInstanceReference

EdgeInstanceReference names an EdgeInstance in the attachment's namespace.

Appears in:

Field Description Default Validation
name string Name is the EdgeInstance's name. MaxLength: 253
MinLength: 1

EdgeInstanceSpec

EdgeInstanceSpec identifies the provider pod an instance runs in. The pod writes it at create; a ValidatingAdmissionPolicy requires podUID to be the pod its token was issued for.

Appears in:

Field Description Default Validation
providerRef EdgeProviderReference ProviderRef is the provider the instance runs. The provider's
admission binding checks the writer against it.
podName string PodName is the provider pod's name, in the instance's namespace. MaxLength: 253
MinLength: 1
podUID string PodUID is the provider pod's metadata.uid. MaxLength: 36
MinLength: 1
nodeName string NodeName is the node the pod runs on. MaxLength: 253
MinLength: 1
bootID string BootID is the node's boot ID (/proc/sys/kernel/random/boot_id) when
the instance was created. Its lease's renew start is on that boot's
CLOCK_BOOTTIME, so galactic-edge applies no renewal of an instance
whose boot ID is not the node's current one.		 MaxLength: 36
MinLength: 1

EdgePacketDevice

EdgePacketDevice is the owner of a PacketAccess attachment's TUN device, the user and group the provider opens it as without CAP_NET_ADMIN.

Appears in:

Field Description Default Validation
owner integer Owner is the user ID allowed to open the device. Maximum: 4.294967294e+09
Minimum: 0
group integer Group is the group ID allowed to open the device. Maximum: 4.294967294e+09
Minimum: 0

EdgeProvider

EdgeProvider registers a Galactic Edge provider: the contract and capability versions it implements, the ServiceAccounts that act for it, and the kind of its own configuration.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeProvider
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeProviderSpec
status EdgeProviderStatus

EdgeProviderApproval

EdgeProviderApproval is the operator's approval of the EdgeProvider of the same name. While it exists, galactic-controller sets that provider's status.approved; deleting it withdraws the approval and every binding issued to the provider. It is a kind of its own, not a field of the EdgeProvider, so that approving a provider takes a privilege that registering one does not, and an operator can keep it in the same Git source that deploys the provider.

An approval names a provider, not one registration of it: it also covers a later change to the provider's spec, or a provider deleted and registered again under the same name. Deleting a provider leaves its approval in place.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeProviderApproval
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.

EdgeProviderReference

EdgeProviderReference names an EdgeProvider.

Appears in:

Field Description Default Validation
name string Name is the EdgeProvider's name. MaxLength: 253
MinLength: 1

EdgeProviderSpec

EdgeProviderSpec is what a provider implements and which identities speak for it. It grants no tenant authority.

Appears in:

Field Description Default Validation
contractVersions string array ContractVersions are the provider contract versions it speaks. MaxItems: 4
MinItems: 1
items:Pattern: ^v[0-9]+((alpha|beta)[0-9]+)?$
capabilities EdgeCapability array Capabilities are the capability versions it implements. MaxItems: 16
MinItems: 1
serviceAccounts ServiceAccountReference array ServiceAccounts are the only identities whose bound tokens act for the
provider. A request from any other identity is refused. The
foundation's own identities cannot be listed, nor any in kube-system or
kube-node-lease, which the provider policy leaves to Kubernetes.		 MaxItems: 16
MinItems: 1
configuration ConfigurationKind Configuration is the kind of the provider's own per-service
configuration.

EdgeProviderStatus

EdgeProviderStatus records the operator's approval.

Appears in:

Field Description Default Validation
approved boolean Approved is whether an EdgeProviderApproval of the same name exists.
galactic-controller sets it and reverts any other write, and no
provider identity may write it. An unapproved provider is refused
admission, and withdrawing approval revokes every authorization
issued to the provider.

EdgeRoute

EdgeRoute is one prefix's forwarding claim in one VPC: which attachment of which provider instance forwards the prefix. It lives in the provider's namespace; its name is derived from the VPC UID and the prefix. Providers write the claim; only galactic-controller accepts one, and a node opens the prefix's forwarding gate only for the accepted holder, only while that holder's instance lease is valid.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeRoute
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeRouteSpec
status EdgeRouteStatus

EdgeRouteClaim

EdgeRouteClaim is a provider pod's claim on a route: the attachment that forwards the prefix and the instance lease, at one epoch, that keeps it forwarding. The pod writes it by compare-and-swap on the route's resourceVersion. A claim grants nothing until galactic-controller accepts it into the route's status.

Appears in:

Field Description Default Validation
attachment string Attachment is the claiming EdgeAttachment's name, in the route's
namespace.		 MaxLength: 253
MinLength: 1
holderPodUID string HolderPodUID is the claiming pod's metadata.uid. The provider's
admission binding requires it to be the pod the writer's token was
issued for.		 MaxLength: 36
MinLength: 1
holderInstance string HolderInstance is the claiming EdgeInstance's name, in the route's
namespace.		 MaxLength: 253
MinLength: 1
instanceEpoch integer InstanceEpoch is the epoch of the instance's lease the claim is held
under. The claim is valid only while that lease is valid at this epoch.		 Minimum: 1
epoch integer Epoch is the claim's epoch. It advances whenever the attachment or the
instance epoch changes.		 Minimum: 1
released boolean Released reports that the holder of Epoch stopped forwarding and gave
the route up.

EdgeRouteHolder

EdgeRouteHolder is the claim galactic-controller accepted: the only one any node forwards the prefix for.

Appears in:

Field Description Default Validation
epoch integer Epoch is the accepted claim epoch. Minimum: 1
attachment string Attachment is the accepted EdgeAttachment's name, in the route's
namespace.		 MaxLength: 253
attachmentUID string AttachmentUID is the accepted EdgeAttachment's metadata.uid. MaxLength: 36
instance string Instance is the accepted EdgeInstance's name, in the route's
namespace.		 MaxLength: 253
instanceIncarnation string InstanceIncarnation is the incarnation of the instance's lease the
route was accepted under.		 MaxLength: 64
instanceEpoch integer InstanceEpoch is the epoch of the instance's lease the route was
accepted under.		 Minimum: 1
node string Node is the node of the attachment, the only node that may forward
the prefix.		 MaxLength: 253
vpcNamespace string VPCNamespace is the namespace of the VPC, where its EdgeRouteIndex
lives.		 MaxLength: 63

EdgeRouteIndex

EdgeRouteIndex is galactic-controller's record of every accepted EdgeRoute in one VPC. Acceptance is a compare-and-swap on it, so two controller replicas that both believe they lead cannot accept overlapping routes. It lives in the VPC's namespace, named by the VPC's UID. Only galactic-controller reads or writes it.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeRouteIndex
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeRouteIndexSpec

EdgeRouteIndexEntry

EdgeRouteIndexEntry is one route the index holds: an accepted holder, or one whose fencing has not completed since its route was removed or revoked.

Appears in:

Field Description Default Validation
prefix string Prefix is the route's prefix. MaxLength: 43
route string Route is the EdgeRoute's namespace and name. MaxLength: 317
routeUID string RouteUID is the EdgeRoute's metadata.uid. MaxLength: 36
epoch integer Epoch is the route's last accepted epoch. Minimum: 1
attachmentUID string AttachmentUID is the accepted attachment's metadata.uid. MaxLength: 36
instance string Instance is the accepted instance's namespace and name. MaxLength: 317
instanceIncarnation string InstanceIncarnation is the incarnation of the instance's lease the
route was accepted under.		 MaxLength: 64
instanceEpoch integer InstanceEpoch is the epoch of the instance's lease the route was
accepted under.		 Minimum: 1
node string Node is the accepted attachment's node. MaxLength: 253
removing string Removing, when set, is why the entry is leaving: the route is gone or
its holder revoked. The entry stays until the holder's gate is
confirmed closed or galactic-controller has waited the takeover
interval since it recorded the removal.		 MaxLength: 64

EdgeRouteIndexSpec

EdgeRouteIndexSpec is every route accepted in one VPC.

Appears in:

Field Description Default Validation
vpcUID string VPCUID is the VPC's metadata.uid, also the index's name. MaxLength: 36
MinLength: 1
routes EdgeRouteIndexEntry array Routes are the accepted routes, keyed by prefix. No two overlap. At
most 1024, so a full index stays within etcd's object size limit at
its entries' largest.		 MaxItems: 1024
rebuilt boolean Rebuilt is set when the index was rebuilt from routes' status after it
was lost. Entries of routes deleted meanwhile are gone, so no first
claim is accepted until galactic-controller has waited the takeover
interval and cleared it.

EdgeRouteSpec

EdgeRouteSpec is a provider's request to forward one prefix of a VPC through one of its attachments.

Appears in:

Field Description Default Validation
providerRef EdgeProviderReference ProviderRef is the provider of the instances that claim the route.
vpcUID string VPCUID is the metadata.uid of the VPC the prefix is in. MaxLength: 36
MinLength: 1
prefix string Prefix is the IPv6 prefix forwarded, a masked CIDR. It must be inside
the service's granted prefixes and must not overlap another route of
the VPC, a workload subnet of the VPC or another service's client
pool, or contain another attachment's address. It may lie inside its
own service's client pool, which no attachment is then allocated an
address from.		 MaxLength: 43
incarnation string Incarnation identifies this route object across its deletion and
recreation, set once at create. A recreated route has a new one, so no
acceptance of the old object applies to it.		 MaxLength: 64
MinLength: 1
claim EdgeRouteClaim Claim is the current claim on the route.

EdgeRouteStatus

EdgeRouteStatus is the route's acceptance and the fencing of its accepted holder.

Appears in:

Field Description Default Validation
conditions Condition array Conditions are Accepted, Claimed and Published, set by
galactic-controller.		 MaxItems: 8
accepted EdgeRouteHolder Accepted is the holder galactic-controller last accepted, written only
after the route is committed to its VPC's EdgeRouteIndex. It stays
after a revocation, with Accepted False, so the node can confirm the
holder's gate closed.
closedEpoch integer ClosedEpoch is the highest accepted epoch whose forwarding gate the
accepted holder's node confirmed closed. Only galactic-edge on that
node writes it, and it never decreases.		 Minimum: 0

EdgeService

EdgeService grants one Galactic Edge provider the use of one VPC: the capabilities it may use there and the prefixes it may request. It lives in the VPC's namespace and is written by the platform authority, never by the provider. Changing the spec revokes every authorization issued under the previous generation; deleting it revokes them all.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string EdgeService
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec EdgeServiceSpec
status EdgeServiceStatus

EdgeServiceReference

EdgeServiceReference names an EdgeService by namespace, name and UID. The UID pins the attachment to one grant object, so a service deleted and recreated under the same name does not inherit it.

Appears in:

Field Description Default Validation
namespace string Namespace is the EdgeService's namespace, its VPC's namespace. MaxLength: 63
MinLength: 1
name string Name is the EdgeService's name. MaxLength: 253
MinLength: 1
uid string UID is the EdgeService's metadata.uid. MaxLength: 36
MinLength: 1

EdgeServiceSpec

EdgeServiceSpec is a tenant's grant to one provider in one VPC.

Appears in:

Field Description Default Validation
providerRef EdgeProviderReference ProviderRef is the only provider the grant authorizes.
vpcRef EdgeVPCReference VPCRef is the only VPC the grant authorizes.
capabilities string array Capabilities are the capability names the provider may use in the VPC. MaxItems: 3
MinItems: 1
items:Enum: [SocketAccess PacketAccess PrefixReachability]
prefixes string array Prefixes bound the prefixes the provider may request in the VPC. Each
is a masked CIDR. Grants of services granting the same VPC must not
overlap: galactic-controller refuses the attachments and routes of the
later of two services whose prefixes overlap.		 MaxItems: 64
items:MaxLength: 43
validUntil Time ValidUntil, when set, is the wall-clock time after which the grant
authorizes nothing. Admission refuses it, and revokes what it issued,
once fewer than the cell's maximum clock skew remain.
clientPool string ClientPool is the IPv6 range, inside the VPC, that attachments take
their addresses from: a masked CIDR from /64 to /120. At most 1024 of
its addresses are allocated, whatever its size. Pools of services
granting the same VPC must not overlap; galactic-controller refuses
the attachments of the later of two overlapping services. Without a
pool, the service admits no attachment. A pool can be added to a
service that has none, and is fixed from then on.		 MaxLength: 43
drainSeconds integer DrainSeconds is how long an attachment the foundation revokes keeps
its resources before they are released. Unset means 30.		 Maximum: 300
Minimum: 0
trafficPolicy TrafficPolicyBindingSpec TrafficPolicy names the TrafficPolicy, in the service's namespace, for
each direction of every attachment the service admits. Ingress is
traffic delivered to the provider from the VPC; egress is traffic the
provider sends into the VPC. An omitted reference selects the built-in
default, which denies everything in that direction. A change applies
to active attachments.

EdgeServiceStatus

EdgeServiceStatus reports the grant's admission state.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the generation Conditions describe.
conditions Condition array Conditions include Admitted and TrafficPolicyResolved. MaxItems: 8
allocations EdgeAllocation array Allocations are the client pool addresses held by attachments. Core
writes them with a resourceVersion precondition, so two writers never
hand out one address, and removes one only after the attachment's node
has released it.		 MaxItems: 1024

EdgeVPCReference

EdgeVPCReference names a VPC in the service's own namespace. UID pins the grant to one VPC object, so a VPC deleted and recreated under the same name is not granted.

Appears in:

Field Description Default Validation
name string Name is the VPC's name. MaxLength: 253
MinLength: 1
uid string UID is the VPC's metadata.uid. MaxLength: 36
MinLength: 1

EnforcementMode

Underlying type: string

EnforcementMode is a node's effective interface traffic policy mode, as galactic-router reads it from the datapath galactic-cni configured.

Validation:

  • Enum: [Off Audit Enforce Unsupported Unknown]

Appears in:

Field Description
Off ModeOff means the node decides nothing: installed policies are inert.
Audit ModeAudit means the node decides and counts every packet but forwards
as if every decision allowed it.
Enforce ModeEnforce means the node drops what policy denies.
Unsupported ModeUnsupported means the node is configured to audit or enforce, but
its kernel failed the traffic policy preflight, so it refuses new
interfaces and protects none.
Unknown ModeUnknown means galactic-router could not read the node's mode.

ForwardingPath

Underlying type: string

ForwardingPath is the trusted forwarding context of a packet. In egress it is where the workload's packet is going; in ingress, where the delivered packet came from.

Validation:

  • Enum: [Private PublicNAT PublicService]

Appears in:

Field Description
Private PathPrivate is private VPC routing, same-node delivery and private
services.
PublicNAT PathPublicNAT is traffic sent toward, or returned from, a NAT shard.
PublicService PathPublicService is public service delivery through a gateway VIP, and
the replies sent from that VIP.

ICMPMatch

ICMPMatch matches an ICMP or ICMPv6 message type, and optionally its code.

Appears in:

Field Description Default Validation
type integer Type is the ICMP or ICMPv6 message type. Maximum: 255
Minimum: 0
code integer Code is the message code. Omitted, any code matches. Maximum: 255
Minimum: 0

IPFamily

Underlying type: string

IPFamily is an IP address family.

Validation:

  • Enum: [IPv4 IPv6]

Appears in:

Field Description
IPv4 IPv4 is IP version 4.
IPv6 IPv6 is IP version 6.

LocalPolicyReference

LocalPolicyReference names a TrafficPolicy in the binding's own namespace. There is no namespace field, so a binding can never refer to another tenant's policy.

Appears in:

Field Description Default Validation
name string Name is the TrafficPolicy's name. MaxLength: 253
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

NodeBindingStatus

NodeBindingStatus is what one node enforces for the interface. Each node writes only its own entry, and removes it once the interface has left the node.

Appears in:

Field Description Default Validation
node string Node is the node's name. MaxLength: 253
MinLength: 1
ingress AppliedPolicy Ingress is the node's installed ingress policy.
egress AppliedPolicy Egress is the node's installed egress policy.
mode EnforcementMode Mode is the node's effective enforcement mode when it last reported.
An Applied policy protects the interface only while Mode is Enforce.
Absent from a node that predates the field, which reads as Unknown.		 Enum: [Off Audit Enforce Unsupported Unknown]
heartbeatTime Time HeartbeatTime is when the node last confirmed this entry. The node
refreshes it at least every 10 minutes while it holds the interface,
so an older entry describes a node that stopped reporting.

PolicyIdentity

PolicyIdentity identifies the policy a direction resolved to. UID is the policy's API UID, or DefaultPolicyUID when the reference is omitted.

Appears in:

Field Description Default Validation
name string Name is the policy's name.
uid string UID is the policy's API UID, or DefaultPolicyUID for the built-in
default.
generation integer Generation is the policy's metadata.generation, 0 for the built-in
default.

PortRange

PortRange is an inclusive range of transport ports. A single port has equal endpoints. Port 0 is representable so a rule can match it.

Appears in:

Field Description Default Validation
start integer Start is the first port in the range. Maximum: 65535
Minimum: 0
end integer End is the last port in the range. Maximum: 65535
Minimum: 0

Protocol

Underlying type: string

Protocol is an IP protocol a rule can match.

Validation:

  • Enum: [TCP UDP ICMP ICMPv6]

Appears in:

Field Description
TCP ProtocolTCP is TCP.
UDP ProtocolUDP is UDP.
ICMP ProtocolICMP is ICMP for IPv4.
ICMPv6 ProtocolICMPv6 is ICMP for IPv6.

RuleAction

Underlying type: string

RuleAction is what a rule does with a packet it matches.

Validation:

  • Enum: [Allow Deny]

Appears in:

Field Description
Allow ActionAllow forwards the packet.
Deny ActionDeny drops the packet. No ICMP error is sent.

ServiceAccountReference

ServiceAccountReference names one ServiceAccount.

Appears in:

Field Description Default Validation
namespace string Namespace is the ServiceAccount's namespace. MaxLength: 63
MinLength: 1
name string Name is the ServiceAccount's name. MaxLength: 253
MinLength: 1

TrafficPolicy

TrafficPolicy is an ordered list of Allow and Deny rules that a TrafficPolicyBinding applies to one direction of one VPC interface.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string TrafficPolicy
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec TrafficPolicySpec
status TrafficPolicyStatus

TrafficPolicyBinding

TrafficPolicyBinding binds an ingress and an egress TrafficPolicy to one VPC interface. It has no attachment field: it applies to the VPCAttachment with the same namespace and name, so an interface can never have two bindings.

Field Description Default Validation
apiVersion string galactic.datumapis.com/v1alpha1
kind string TrafficPolicyBinding
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec TrafficPolicyBindingSpec
status TrafficPolicyBindingStatus

TrafficPolicyBindingSpec

TrafficPolicyBindingSpec names the policy for each direction of one interface. An omitted reference selects the built-in default, whose only rule denies everything, for that direction alone.

Appears in:

Field Description Default Validation
ingressPolicyRef LocalPolicyReference IngressPolicyRef is the policy for traffic delivered to the workload.
egressPolicyRef LocalPolicyReference EgressPolicyRef is the policy for traffic the workload sends.

TrafficPolicyBindingStatus

TrafficPolicyBindingStatus separates what the API asked for from what each node enforces. Admission success is never reported as convergence.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the generation Ingress and Egress describe.
ingress DirectionStatus Ingress is the resolved ingress reference.
egress DirectionStatus Egress is the resolved egress reference.
conditions Condition array Conditions are Installed and Enforcing, which galactic-controller
derives from Nodes.		 MaxItems: 8
nodes NodeBindingStatus array Nodes lists what each node with the interface enforces. MaxItems: 64

TrafficPolicySpec

TrafficPolicySpec is an ordered rule list. The first matching rule decides a packet, and a packet no rule matches is denied.

Appears in:

Field Description Default Validation
rules TrafficRule array Rules are evaluated in order. MaxItems: 64
MinItems: 1

TrafficPolicyStatus

TrafficPolicyStatus reports whether the policy is valid and compiles.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the generation the conditions describe.
conditions Condition array Conditions include Accepted, false when the policy fails validation or
exceeds the compiled entry limit.		 MaxItems: 8

TrafficRule

TrafficRule is one ordered rule of a TrafficPolicy.

Appears in:

Field Description Default Validation
name string Name identifies the rule in status and metrics. It is unique within the
policy. Renaming a rule starts a new counter series.		 MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
action RuleAction Action is what happens to a packet this rule matches first. Enum: [Allow Deny]
match TrafficRuleMatch Match selects packets. Omitted, the rule matches every packet.

TrafficRuleMatch

TrafficRuleMatch selects packets. Every field that is present must match, and an omitted field matches anything. Within one list the entries are alternatives.

Explicit null and empty lists are invalid: omission is the only wildcard. The fields are nullable so a null reaches admission, where the validating webhook rejects it.

Appears in:

Field Description Default Validation
path ForwardingPath Path is the forwarding path. Omitted, any path in the bound direction
matches.		 Enum: [Private PublicNAT PublicService]
ipFamily IPFamily IPFamily restricts the rule to one address family. Omitted, both match,
and a packet can only match list entries of its own family.		 Enum: [IPv4 IPv6]
protocol Protocol Protocol is the IP protocol. Omitted, any protocol matches, and the rule
cannot carry ports or ICMP fields.		 Enum: [TCP UDP ICMP ICMPv6]
sourceIPs string array SourceIPs are exact source addresses, IPv4 or IPv6. IPv4-mapped IPv6
literals and zone identifiers are rejected. Mutually exclusive with
SourceCIDRs.		 MaxItems: 64
MinItems: 1
items:MaxLength: 39
items:XValidation: {isIP(self) must be an IPv4 or IPv6 address }
destinationIPs string array DestinationIPs are exact destination addresses, IPv4 or IPv6. Mutually
exclusive with DestinationCIDRs.		 MaxItems: 64
MinItems: 1
items:MaxLength: 39
items:XValidation: {isIP(self) must be an IPv4 or IPv6 address }
sourceCIDRs string array SourceCIDRs are source prefixes. A prefix must have no host bits set.
Mutually exclusive with SourceIPs.		 MaxItems: 64
MinItems: 1
items:MaxLength: 43
items:XValidation: {isCIDR(self) && cidr(self).ip() == cidr(self).masked().ip() must be a prefix with no host bits set }
destinationCIDRs string array DestinationCIDRs are destination prefixes. A prefix must have no host
bits set. Mutually exclusive with DestinationIPs.		 MaxItems: 64
MinItems: 1
items:MaxLength: 43
items:XValidation: {isCIDR(self) && cidr(self).ip() == cidr(self).masked().ip() must be a prefix with no host bits set }
sourcePorts PortRange array SourcePorts are source port ranges. They require protocol TCP or UDP,
and ranges must not overlap.		 MaxItems: 16
MinItems: 1
destinationPorts PortRange array DestinationPorts are destination port ranges. They require protocol TCP
or UDP, and ranges must not overlap.		 MaxItems: 16
MinItems: 1
icmp ICMPMatch ICMP matches a message type and code. It requires protocol ICMP or
ICMPv6.