Provisioning

The hostnames this service answers on: the free platform host it always has, and every domain the customer has attached. Each attachment carries a status of pending, active or failed; pending is the ordinary state between accepting a name and cert-manager completing its HTTP-01 challenge, which cannot finish until the customer's own DNS points here, so a client should render it as waiting on DNS rather than as an error. platformHost is null for a service that publishes no HTTP ingress, and also when its cluster could not be resolved: the attached names are correct either way, and a placement fault does not fail this read. platformUrl is https://{platformHost} and is set exactly when platformHost is -- the shared wildcard certificate covers every platform host, so unlike an attached domain's own url it is never waiting on a certificate to issue. 404 for a service whose product does not offer this capability, which is the same answer a service belonging to somebody else gives, and the same answer an id that was never issued gives.

Points a hostname the customer owns at this service: a Traefik ingress route and a managed HTTP-01 TLS certificate, in front of the same backend the service's platform host already serves. The hostname is validated for shape and then authorized against the caller's organization before anything is persisted, so a refusal leaves nothing to clean up. Three kinds of name get three answers: a name inside the platform's own DNS zone is refused permanently and no proof can unlock it; a single label under a parent domain staff registered is allowed if no other organization holds that label; anything else must have proven domain control first, through POST /organizations/{id}/domains/{domain}/check. A host another organization has already claimed is refused with exactly the same message an unproven domain gets, deliberately, so this route cannot be used to discover which names are in use here. Idempotent for a name already attached to this service: the existing attachment is re-applied and returned rather than duplicated. Refused with a business-rule error when the service publishes no HTTP ingress to attach to, and when it already holds the maximum number of domains the listing reports as limit. Answering 200 means the ingress and the certificate request were accepted, not that the certificate has been issued; poll the listing's status for that. A service belonging to somebody else answers 404, the same as one that does not exist.

Whether hostname could be attached to this service right now, without attaching it. status is available; taken when another service already holds the name (only ever said for a name the caller's organization may use, so it is not a way to list what other organizations hold); invalid for a malformed name; platform_zone for a name inside the platform's own DNS zone; not_verified when the organization has not proven control of the domain, which is also the answer for a name another organization holds. Gated like the attach it precedes, on the permission to change the service.

Removes one attached hostname: its ingress route, its managed TLS certificate, and its claim on the name, so the customer can attach the same domain again later -- leaving the claim behind would make their own domain permanently unusable to them after removing it once. The service's free platform host is not an attachment and cannot be removed through this route: a routeId naming it answers 404, the same as one naming another tenant's row and the same as one that never existed, because a distinguishable refusal would say which resource ids exist on this platform.

The Domain Connect links of this service: customer-owned domains connected through the customer's own DNS provider. supported is false when the service's product does not offer Domain Connect (only products that declare an SRV record and a template do), and a client should then hide the section. Each link carries the applyUrl the browser is sent to, which is signed when a signing key is configured.

Discovers a customer-owned domain's Domain Connect support (its _domainconnect TXT record and the provider's settings) and creates a pending link for this service. Never writes DNS itself: the response carries the applyUrl the browser must be sent to, where the customer approves the records at their own DNS provider. An empty host points the apex at the server. Refused when the product does not offer Domain Connect, the domain belongs to the platform, the pair is already linked, the service already holds 20 links, or the provider has no synchronous flow.

Releases one Domain Connect link. Kernel never wrote DNS for it, so nothing is cleaned up at the DNS provider; the customer removes the records there. A link of another service answers 404, the same as one that never existed.

Re-checks live DNS for one link: whether the SRV record the template creates is published and points at the expected host and port. active once it matches, failed when a different record is found, and pending while nothing has propagated yet.

This service's game subdomain (<subdomain>.<zone> pointing at its public address, with an SRV record carrying the port for games that read one) and the platform zones a new one may be taken under. A service holds at most limit (one). pending is the ordinary state until the records are created; failed is retried automatically. 404 for a service without external access, a suspended or ended one, somebody else's, or an id that was never issued.

Takes a game subdomain for this service and creates its DNS records right away when possible (the answer is then active; otherwise pending or failed, retried automatically). Refused with 422 and details zone_unavailable, invalid_subdomain, subdomain_taken or already_has_subdomain. Requires the permission to change the service's external access.

Whether a subdomain may be taken under a zone: available, taken, invalid (with the reason) or zone_unavailable. A name stays taken while a previous holder's records are being removed.

Releases this service's game subdomain and removes its DNS records (right away when possible, otherwise automatically shortly after).

Replaces this service's game subdomain with a new name (and zone): the old records are removed and the new ones created. The answer carries a NEW id. Same refusals as create.

Port allocations and quota info for this service instance. Answers from kernel state alone and never contacts a Warden node, so it is unaffected by relay health. Each allocation's protection_state is therefore the not-loaded sentinel (unknown for a protection-managed allocation, not_managed otherwise); read the live value from GET /service-instances/{id}/external-access/live. extra_slots is the staff grant on this service instance (0 without one); free_slots + extra_slots is the ceiling a new port request is refused at. 404 for a service whose product does not offer this capability, which is the same answer a service belonging to somebody else gives.

Opens one new external port on this service instance and consumes a quota slot. With matchPort false the caller names the internalPort their software listens on and the public port is drawn at random; with matchPort true the drawn port becomes both, and internalPort is ignored. The new port lands on the same public IP as every other allocation on this service, because it is pinned to the pool the instance's primary allocation already sits on -- a service whose ports were split across two IPs is a service whose players connect to one address and whose egress leaves from another. Refused with a business-rule error when the quota is spent (three slots; there is no service-instance quota override yet, so the total is the same one the listing reports), when the internal port and protocol are already allocated, when the pool has no free port, and, under relay exposure, when the workload's protected egress cannot be established -- opening a public port on an unprotected egress publishes the cluster's own address. A service belonging to somebody else answers 404, the same as one that does not exist.

The live protection state of this instance's protection-managed port allocations, read from the Warden nodes that serve them and only those. Best effort by design: a node that is unreachable, saturated, or slow is abandoned after a short per-node timeout, and its allocations are omitted with degraded set rather than reported as normal. Never fails because a relay is unavailable, so a client should render an absent allocation as unavailable, not as healthy. An instance with no protection-managed allocations contacts no relay and returns an empty list.

The network protection modes this service may choose from, for game port allocations and for a VPS's dedicated IP, and the default. Today every pool offers "normal" only: Warden expresses protection as policy documents and the external relay layer the other values came from is retired. The PATCH routes beside it accept exactly this list.

Releases one external port allocation and frees its quota slot. Any HTTP domain attached to the port is torn down first and that teardown is not best effort: an ingress route that outlived the port it targets is a public router pointing at nothing, so a failure to remove it fails the whole release and leaves the operation retryable. A system allocation -- the primary port provisioning created, which is how players reach the service at all -- is refused with a business-rule error rather than released. An allocationId naming an allocation that does not exist, or one belonging to a different service instance, is a 404: the same answer either way, since a distinguishable refusal would say which allocation ids exist.

Publishes an HTTP domain in front of one TCP-capable port: a Traefik ingress route and a managed HTTP-01 TLS certificate. The domain is authorized against the caller's organization before anything is persisted, so a refusal leaves nothing to clean up. Three kinds of name get three answers: a name inside the platform's own DNS zone is refused permanently and no proof can unlock it; a single label under a parent domain staff registered is allowed if no other organization holds that label; anything else must have proven domain control first. A host another organization has already claimed is refused with exactly the same message an unproven domain gets, deliberately, so this route cannot be used to discover which names are in use here. Answering 200 means the ingress and the certificate request were accepted, not that the certificate has been issued; poll the listing's http.status for that.

Removes the port's ingress route and managed TLS certificate, and releases its hostname claim so the customer can use the same name again later -- leaving the claim behind would make their own domain permanently unusable to them after removing it once. Idempotent: a port with no HTTP domain succeeds. An allocationId belonging to a different service instance is a 404, the same as one that does not exist.

Persists the network protection mode for one port allocation. "normal" is the only mode any pool accepts today: Warden expresses protection as policy documents and publishes no mode list, and the external relay layer the other values came from is retired, so anything else is refused with a business-rule error rather than silently stored. The route and the field stay because this is where a Warden policy selector will surface. An allocationId belonging to a different service instance is a 404.

Persists the network protection mode for this service instance's exclusive IPv4 address. Same single accepted mode as the per-allocation route above and for the same reason. A service instance that has not bought an exclusive IP has no assignment to change and answers 404, which is also what a service belonging to somebody else answers.

Every firewall rule on this machine, ordered the way the datapath evaluates them: ingress before egress, then ascending priority. maxRulesPerDirection is the ceiling a create or replace is refused against, published here so a panel never holds it as a literal. Rules are desired state: a change made here reaches the machine when Warden next reconciles, roughly a minute later, and this listing shows what was asked for rather than what the node is currently enforcing. A machine with no rules and a machine on a shared pool both answer with an empty list; nothing on this route reports whether a dedicated IP is assigned. 404 for a resource that is not a virtual machine, for one belonging to somebody else, and for a service whose product does not offer this capability, which are deliberately the same answer.

Replaces this machine's entire ruleset with the one supplied, atomically: every existing rule is dropped and the new set is written in one repository operation, so there is no window in which the machine is filtered by half of each. Rule ids are not preserved -- a replacement mints new ones, because the request describes a ruleset rather than an edit to particular rows. Refused whole if any rule is invalid, including one malformed cidr: a partially applied replacement would be a ruleset the customer never wrote, on a filter whose default action is allow. An empty rules array is a legitimate request and removes every rule. The audit entry names the count and not the rules.

Adds one rule to this machine's firewall. A tcp or udp rule must carry a port range and an icmp or any rule must not, which is the domain's rule rather than this route's, so an omitted port is a validation refusal rather than a rule matching every port. cidr is IPv4 only and no broader than /8; absent, null or blank all mean any source. Refused with a quota error once a direction holds maxRulesPerDirection rules -- ingress and egress are counted separately. Takes effect when Warden next reconciles, roughly a minute later, not on the response. The audit entry names the rule, its direction and its action.

Removes one rule. On a machine whose firewall defaults to allow, deleting a block rule opens the port it was closing, roughly a minute later when Warden reconciles; a client should say so before sending this rather than treating it as an undo. Returns no body, because there is no row left to return; read the remaining set from the listing. 404 for a rule belonging to another machine and for a rule id naming nothing, deliberately the same answer, so this path cannot be used to discover which rule ids exist. The audit entry names the rule's direction and action as well as its id, since the row itself is gone.

Changes the fields named in the body and leaves the rest alone. A field sent as null is cleared rather than ignored, and that distinction matters: cidr: null widens the rule to any source, which on a block rule stops it protecting the range it was written for and on an allow rule opens the port to the internet. Moving a rule to a direction that is already full is refused with a quota error and the rule is left where it was. The result is re-validated as a whole, so a patch that removes the ports from a tcp rule is refused rather than saved as a rule matching every port. Takes effect when Warden next reconciles, roughly a minute later. 404 for a rule belonging to another machine, which is the same answer a rule id naming nothing gives.

The most recent imports into this service, newest first, finished ones included. An import that is still running is the first item with a status of preparing, running or cleaning_up.

Starts copying a remote SFTP server's files into this service's data volume. The service must already be stopped: the import does not stop it, and answers 409 if it is running. The transfer runs in the background as a job next to the volume, after the service's other workloads on that volume (the file sidecar, SFTP) are paused; they are started again when it ends, however it ends. By default files are copied over what is there; deleteExtraneous makes the data directory match the remote exactly, deleting files the remote does not have. The remote host must be a public address: private, loopback and link-local addresses are refused with 422. The password is stored encrypted until the transfer ends and is never returned. 409 while another operation or import holds the service. Follow progress with GET .../server-imports/{import_id}.

One import with its progress: bytes and files transferred against the totals rclone has reported so far, the file being copied, and a percentage. Poll it while the status is preparing, running or cleaning_up. A failed import carries error. An import of another service answers 404, the same as one that was never issued.

Asks an unfinished import to stop. The transfer is stopped within a few seconds, the job and credentials are removed and the paused workloads are started again, after which the status becomes cancelled. Files already copied stay. The response is the import as it stands, usually still running with cancelRequested set. Cancelling an import that has finished is a business-rule refusal.

Connection details for this service's SFTP account: username, its currently-resolved public host and port, and whether it is enabled. Never the password -- rotate it with POST .../sftp/rotate to see it once. host and port are null when the account's public port has not resolved yet; the rest of the read still succeeds. A business-rule refusal when SFTP has not been provisioned for this service yet (a fresh purchase still awaiting its first deployment, or a product with no data volume at all). 404 for a service whose product does not offer file access, the same answer a service belonging to somebody else gives, and the same answer an id that was never issued gives.

Enables or disables this service's SFTP account by scaling its Deployment, the same mechanism a service instance's own Start/Stop uses on its primary resource. Idempotent: setting the state it already holds still scales and still returns 200. A business-rule refusal when SFTP has not been provisioned for this service yet, and a 409 naming the operation in the way when another write is already in progress on this instance. A service belonging to somebody else answers 404, the same as one that does not exist.

Generates a new password for this service's SFTP account, writes it and rolls the account's pod so it takes effect, and returns it. The password is shown here once: neither this response nor any later GET .../sftp will carry it again. A business-rule refusal when SFTP has not been provisioned for this service yet, and a 409 naming the operation in the way when another write is already in progress on this instance.