Resources / Ingress

Ingress

An ingress: the entry that accepts traffic and forwards it to targets at L3 (every IP packet), L4 (TCP and UDP ports) or L7 (HTTP and HTTPS with host, path and header rules and TLS termination), on nodes that run as Compute processes on a VPC. It serves once its engine is available; until then it stays Pending with reason EngineNotAvailable. https listeners wait for their certificate.

Overview

APIedge.etorm.com/v1alpha1
Resourceingresses (cluster-scoped inside its cluster)
Short namesing
Available inproject clusters only
Statuswritten by a controller through /status

Minimal example

apiVersion: edge.etorm.com/v1alpha1
kind: Ingress
metadata:
  name: example
spec:
  vpcRef:
    name: "<name>"

Spec

FieldTypeRequiredDefaultAllowedDescription
monitoringRefreference to MonitoringWorkspaceOptional MonitoringWorkspace to send L3/L4/L7 flow and latency telemetry to.
vpcRefreference to VPCyesThe VPC the nodes and the backends are on. Cannot be changed.
levelstring (one of)"l7"l3, l4, l7l3 forwards every IP packet to target; l4 forwards TCP and UDP listeners; l7 routes HTTP and HTTPS requests by host, path and headers. Cannot be changed.
targetobjectl3: where every packet goes. Exactly one of loadBalancerRef, processRef, accountRef or address.
target.loadBalancerRefobjectA load balancer of this project: traffic goes to its node addresses.
target.loadBalancerRef.namestringyeslength 1 to 63Name of the load balancer.
target.processRefobjectA Compute process: traffic goes to its first interface on the VPC.
target.processRef.namestringyeslength 1 to 63Name of the process.
target.accountRefobjectA VPC member (Account).
target.accountRef.namestringyeslength 1 to 63Name of the account.
target.addressstringup to 45 charactersAn IPv6 or IPv4 address literal. IPv4 only when the VPC has an IPv4 network.
target.portinteger1 to 65535Port to connect to. Defaults to the load balancer's first listener port; required otherwise.
target.databaseRefobjectA Database of this project: traffic goes to the node that has the role now (so it follows a failover). The port defaults to the database port.
target.databaseRef.namestringyeslength 1 to 63Name of the database.
target.databaseRef.rolestring (one of)yesprimary, replicasprimary (the node that accepts writes) or replicas (the read-only nodes, else the primary).
target.brokerRefobjectA MessageBroker of this project: traffic goes to the node(s) that serve now. The port defaults to the first protocol port the node offers.
target.brokerRef.namestringyeslength 1 to 63Name of the message broker.
target.brokerRef.rolestring (one of)yesserving, endpointsserving (the node that serves now) or endpoints (every node).
listenerslist of objectup to 8 itemsl4 and l7: the ports the ingress accepts on.
listeners[].namestringup to 63 charactersName of the listener, unique; defaults to <protocol>-<port>.
listeners[].protocolstring (one of)yestcp, udp, http, httpsProtocol the listener accepts.
listeners[].portintegeryes1 to 65535Port the listener accepts on.
listeners[].targetobjectWhere this listener's traffic goes. Exactly one of loadBalancerRef, processRef, accountRef or address.
listeners[].target.loadBalancerRefobjectA load balancer of this project: traffic goes to its node addresses.
listeners[].target.loadBalancerRef.namestringyeslength 1 to 63Name of the load balancer.
listeners[].target.processRefobjectA Compute process: traffic goes to its first interface on the VPC.
listeners[].target.processRef.namestringyeslength 1 to 63Name of the process.
listeners[].target.accountRefobjectA VPC member (Account).
listeners[].target.accountRef.namestringyeslength 1 to 63Name of the account.
listeners[].target.addressstringup to 45 charactersAn IPv6 or IPv4 address literal. IPv4 only when the VPC has an IPv4 network.
listeners[].target.portinteger1 to 65535Port to connect to. Defaults to the load balancer's first listener port; required otherwise.
listeners[].target.databaseRefobjectA Database of this project: traffic goes to the node that has the role now (so it follows a failover). The port defaults to the database port.
listeners[].target.databaseRef.namestringyeslength 1 to 63Name of the database.
listeners[].target.databaseRef.rolestring (one of)yesprimary, replicasprimary (the node that accepts writes) or replicas (the read-only nodes, else the primary).
listeners[].target.brokerRefobjectA MessageBroker of this project: traffic goes to the node(s) that serve now. The port defaults to the first protocol port the node offers.
listeners[].target.brokerRef.namestringyeslength 1 to 63Name of the message broker.
listeners[].target.brokerRef.rolestring (one of)yesserving, endpointsserving (the node that serves now) or endpoints (every node).
listeners[].tlsobjectTLS termination (https listeners).
listeners[].tls.certificateRefobjectyesThe certificate the listener presents.
listeners[].tls.certificateRef.namestringyeslength 1 to 63Name of the Certificate.
listeners[].tls.minVersionstring (one of)"1.2"1.2, 1.3Lowest TLS version accepted.
ruleslist of objectup to 32 itemsl7: the first rule that matches decides; none matches means defaultTarget, else 404.
rules[].hoststringup to 253 charactersHost name, or *.name for any subdomain. Empty matches any host.
rules[].pathstringup to 512 charactersExact path.
rules[].pathPrefixstringup to 512 charactersPath prefix on a segment boundary: /api matches /api and /api/x, not /apix.
rules[].headerslist of objectup to 8 itemsHeaders that must all be present with exactly this value.
rules[].headers[].namestringyesup to 64 charactersHeader name.
rules[].headers[].valuestringyesup to 256 charactersHeader value.
rules[].listenerstringup to 63 charactersOnly requests that arrived on this listener.
rules[].targetobjectyesWhere matching requests go.
rules[].target.loadBalancerRefobjectA load balancer of this project: traffic goes to its node addresses.
rules[].target.loadBalancerRef.namestringyeslength 1 to 63Name of the load balancer.
rules[].target.processRefobjectA Compute process: traffic goes to its first interface on the VPC.
rules[].target.processRef.namestringyeslength 1 to 63Name of the process.
rules[].target.accountRefobjectA VPC member (Account).
rules[].target.accountRef.namestringyeslength 1 to 63Name of the account.
rules[].target.addressstringup to 45 charactersAn IPv6 or IPv4 address literal. IPv4 only when the VPC has an IPv4 network.
rules[].target.portinteger1 to 65535Port to connect to. Defaults to the load balancer's first listener port; required otherwise.
rules[].target.databaseRefobjectA Database of this project: traffic goes to the node that has the role now (so it follows a failover). The port defaults to the database port.
rules[].target.databaseRef.namestringyeslength 1 to 63Name of the database.
rules[].target.databaseRef.rolestring (one of)yesprimary, replicasprimary (the node that accepts writes) or replicas (the read-only nodes, else the primary).
rules[].target.brokerRefobjectA MessageBroker of this project: traffic goes to the node(s) that serve now. The port defaults to the first protocol port the node offers.
rules[].target.brokerRef.namestringyeslength 1 to 63Name of the message broker.
rules[].target.brokerRef.rolestring (one of)yesserving, endpointsserving (the node that serves now) or endpoints (every node).
defaultTargetobjectl7: where requests go when no rule matches.
defaultTarget.loadBalancerRefobjectA load balancer of this project: traffic goes to its node addresses.
defaultTarget.loadBalancerRef.namestringyeslength 1 to 63Name of the load balancer.
defaultTarget.processRefobjectA Compute process: traffic goes to its first interface on the VPC.
defaultTarget.processRef.namestringyeslength 1 to 63Name of the process.
defaultTarget.accountRefobjectA VPC member (Account).
defaultTarget.accountRef.namestringyeslength 1 to 63Name of the account.
defaultTarget.addressstringup to 45 charactersAn IPv6 or IPv4 address literal. IPv4 only when the VPC has an IPv4 network.
defaultTarget.portinteger1 to 65535Port to connect to. Defaults to the load balancer's first listener port; required otherwise.
defaultTarget.databaseRefobjectA Database of this project: traffic goes to the node that has the role now (so it follows a failover). The port defaults to the database port.
defaultTarget.databaseRef.namestringyeslength 1 to 63Name of the database.
defaultTarget.databaseRef.rolestring (one of)yesprimary, replicasprimary (the node that accepts writes) or replicas (the read-only nodes, else the primary).
defaultTarget.brokerRefobjectA MessageBroker of this project: traffic goes to the node(s) that serve now. The port defaults to the first protocol port the node offers.
defaultTarget.brokerRef.namestringyeslength 1 to 63Name of the message broker.
defaultTarget.brokerRef.rolestring (one of)yesserving, endpointsserving (the node that serves now) or endpoints (every node).
nodesinteger11 to 5How many nodes run the data plane. Each has its own address; any node accepts any traffic and they agree on every choice.
affinityGroupstringup to 63 charactersRun the nodes on the same host as every other process of the project with this affinity group (for example the backends the balancer reaches while no path joins two hosts). Without it the nodes are spread over different hosts.
maxNodesinteger1 to 5The most nodes the platform may run by itself. When the nodes refuse connections (condition Saturated) the platform raises spec.nodes by one, with a cooldown, up to this number. Unset, it never changes spec.nodes.
resourcesobject{}What each node may use.
resources.memoryPowerinteger60 to 10Memory per node: 64 KiB times two to this power (6 is 4 MiB).
resources.cpuMillicoresinteger2501 to 1000Processor time per node on average, in thousandths of a core.
publicobjectPublishes the ingress under a public name from the internet (spec 0026, "Public names"). Only in system projects. The platform makes everything else: a PublicEndpoint (the door on the gateway host), the listener on the station, the DNS records, and shows the result in status.public. Deleting the ingress removes all of it.
public.hostnamestringyesup to 253 charactersThe public DNS name (lower case), for example code.etorm.com.
public.portinteger4431 to 65535The TCP port clients connect to (and on the station and the gateway host).
public.proxystring (one of)"fronted"fronted, directfronted: a proxy in front of the station ends the clients' TLS with a public certificate and connects over TLS without checking the ingress's own certificate (the ingress then needs a generated certificate). direct: clients connect to the relay itself, which then needs a certificate they trust; use fronted.
public.gatewayRefobjectyesThe gateway whose host relays to the ingress (it must have the ingress's VPC attached).
public.gatewayRef.namestringyeslength 1 to 63Name of the gateway.
public.stationRefobjectThe station (an ExternalNode) that publishes the port on its public addresses. Without it only the gateway host listens.
public.stationRef.projectstringyeslength 1 to 63The system project that holds the ExternalNode.
public.stationRef.namestringyeslength 1 to 63Name of the ExternalNode.
public.relayRefobjectDeprecated spelling of stationRef: still read, and used when stationRef is not set.
public.relayRef.projectstringyeslength 1 to 63The system project that holds the ExternalNode.
public.relayRef.namestringyeslength 1 to 63Name of the ExternalNode.
public.dnsobjectWhere the public name is published in DNS. Without it no record is made (the name is set outside the platform).
public.dns.zonestringyesup to 253 charactersThe DNS zone that holds the name, for example etorm.com.
public.dns.secretNamestringlength 1 to 63No longer used. The platform's DNS operator holds the zone's credential (a DNSZone names it); the records are declared as DNSRecord objects.
public.dns.takeoverstring (one of)"refuse"refuse, replaceWhat to do when the name already has records of its own that Etorm did not make. Kept for compatibility: the zone operator adopts a record with the same type, name and content and repairs one of the same type and name (the zone policy decides), so it no longer refuses; the old records are not put back when the name is removed).

Status

FieldTypeRequiredDefaultAllowedDescription
phasestringPending, Ready, Degraded (some nodes are not running, or no backend is up) or Failed.
addresseslist of stringWhere clients send traffic: every node's IPv6 address, then IPv4 addresses when present.
endpointslist of objectOne entry per node.
endpoints[].processstringThe node's process.
endpoints[].addressstringIts IPv6 address on the VPC.
endpoints[].portslist of integerPorts it accepts on.
loadobjectWhat the nodes report about refused connections (condition Saturated). Written when a node's report changes, not on every connection.
load.refusedRecentintegerConnections refused in the last minute, over all nodes.
load.refusedTotalintegerConnections refused since the nodes started.
load.backlogintegerThe most idle listening sockets per listener any node keeps (nodes raise it by themselves while they refuse).
load.atLimitbooleanA node is refusing at its own limit; only more nodes help.
planstringDigest of the plan the nodes run; changes whenever the configuration they get changes.
publicobjectThe public name's state (only with spec.public).
public.hostnamestringThe public name.
public.phasestringPending, Ready (the name resolves to the station, the station and the gateway host listen, and the ingress is serving) or Failed.
public.addresseslist of stringThe addresses the name resolves to (the station's), when the name is not proxied; with a proxy the proxy's.
public.messagestringWhat is missing or wrong.
conditionslist of objectDetailed state, one entry per aspect; Ready says whether the traffic is being served.
conditions[].typestringAspect.
conditions[].statusstringTrue or False.
conditions[].reasonstringMachine-readable reason.
conditions[].messagestringHuman-readable detail.
targetslist of objectEach target as the nodes see it.
targets[].namestringWhere it is used: listener, rule number, default or target.
targets[].addressstringResolved addresses, comma-separated.
targets[].portintegerPort.
targets[].statestringUp, Down or Unknown.
targets[].reasonstringWhy it is Down.

Columns in listings

ColumnFrom
Level.spec.level
Address.status.addresses[0]
Phase.status.phase

Related guides

All resources