Endpoints

An endpoint makes one port of one component reachable from outside the cluster. An instance has at most 12. The Endpoints tab lists them with their address and certificate; adding, changing and removing them needs containerinstance/write — and, on an instance that uses vault secrets, the Owner role on those vaults, see Permissions — and restarts no pods.

Add an endpoint

1. On the instance's Endpoints tab, choose Add endpoint. The New endpoint sheet opens. Expose this port, in a component's edit sheet, opens the same sheet with the component and port filled in.
2. Fill in:
   • Name — lowercase letters, digits and hyphens, starting with a letter, and unique in the instance. The sheet does not change it later.
   • Component — the component that serves the endpoint.
   • Exposure — Ingress for HTTPS on a hostname, or Load balancer for an address of its own that carries raw TCP or UDP.
   • Port — one of the ports the component declares. It is chosen by name, so changing the port's number later keeps the endpoint attached. An ingress endpoint cannot use a UDP port.
   • For Ingress also the Hostname, the Paths and Require sign-in, described below.
3. Choose Save endpoint.

The endpoint starts answering once every startup wave of the instance is up. An ingress endpoint is served over HTTPS; the platform ends the TLS connection and passes the request on to the container as plain HTTP on the chosen port.

Hostnames

• Platform hostname. Leave Hostname empty and the platform gives the endpoint a hostname under apps.example.com, made from the boundary, the resource group and the instance: <boundary>-<resource group>-<instance>.apps.example.com, where <boundary> is the start of the boundary's slug. The first ingress endpoint in the instance's list gets that name; the others add their own name at the end. The name is stored with the endpoint when you save. The sheet's placeholder always shows the form with the endpoint's name at the end, also when the endpoint will be the first.
• Your own domain. Enter a full domain name such as shop.example.com, and create a DNS record that points it at the platform — your platform administrator knows the target. With the usual certificate setup, the certificate can only be issued once the name resolves to the platform.
• Several endpoints on one hostname. Give them Paths — absolute path prefixes such as /api — to split the hostname between them; an endpoint without paths serves the whole hostname. A prefix matches the start of the path text, so /admin also matches /administrator. When paths overlap, which endpoint serves a request is decided by route precedence, not by which path is more specific, and the sheet warns about overlaps within the instance.
• Changing a hostname asks you to confirm. The endpoint stops answering on the old name at once and answers on the new one when its DNS resolves and its certificate is issued.

TLS certificates

The platform requests a certificate for every hostname an ingress endpoint uses; endpoints that share a hostname share its certificate. The Certificate column shows Pending certificate until it is issued and Certificate ready after. For your own domain, a pending certificate usually means the DNS record is missing or does not point at the platform yet.

The Address column shows the endpoint's URL as soon as the endpoint is saved, whether or not it answers yet; the Certificate column is the better sign that it does.

Internal only

An instance without endpoints cannot be reached from outside the cluster; its Overview shows Internal only. Its components still answer inside the boundary on their in-cluster names — see How an instance is reached. Removing every endpoint makes an instance internal again.

Load balancer endpoints

A Load balancer endpoint gets an address of its own from the cluster, carrying exactly the one port. The Address column shows it as address:port once it is assigned, and Waiting for a load balancer address until then. It takes no hostname, paths or sign-in and gets no certificate.

Caution

A load balancer endpoint accepts connections on its port from any source, and there is no allowlist of addresses to narrow that. Besides clients outside the cluster, that includes workloads in other boundaries: every workload may open TCP 443 to any address, so on port 443 they can connect to it too. The boundary's network rules do not apply to that port, so the application itself has to decide who may use it.

Require sign-in

Turn on Require sign-in on an ingress endpoint to put the platform's sign-in in front of it:

• A browser without a session is sent to sign in with a platform account, through auth.apps.example.com.
• After signing in, the person needs containerinstance/access, held through a role assigned on the instance's resource group, its boundary or the whole platform; a role assigned on the instance itself is not recognized. The check reads only roles that hold the action as an ordinary action: Owner, Contributor, Platform Owner and Platform Contributor pass. Reader, Blueprint Reader and Blueprints Operator list it as a data action, which this check does not read, so they are refused. Anyone refused gets 403 Forbidden. A revoked role stops working within about 30 seconds.
• Requests that get through carry the headers X-Forwarded-User (the user name) and X-Forwarded-Email, so the application can tell who is calling.
• A sign-in lasts up to eight hours. Where the cluster routes through Traefik, using the endpoint does not extend it, so people sign in again eight hours after they signed in.

Important

Trust X-Forwarded-User and X-Forwarded-Email only on requests that came through an endpoint with Require sign-in. Through an endpoint without it, the headers carry whatever the client sent. And the sign-in covers only the endpoint: every workload in the boundary can connect to the component directly on its in-cluster name, without signing in and with any headers it chooses.

Use sign-in protection on hostnames under apps.example.com. The sign-in is kept in a browser cookie for that domain, which the browser does not send to a domain of your own, so an endpoint on your own domain keeps sending people back to sign in.

Important

Because the cookie belongs to the whole of apps.example.com, the browser also sends it to every other hostname under that domain — the apps and container instances of other teams included — and whoever runs the service behind such a hostname receives it with each request.

The sign-in needs the instance's managed identity. Every instance created on the platform has one; without it the switch is disabled.

Change or remove an endpoint

• The pencil icon opens the endpoint's sheet; everything but its name can be changed.
• The bin icon removes the endpoint after you confirm: its route and sign-in are taken down and it stops answering. The certificate is kept, so adding the same hostname again does not need a new one.
• Removing a port or a container that an endpoint uses, in a component's edit sheet, removes that endpoint in the same save, after you confirm.

With the CLI

Endpoints are part of the instance. Write the complete list to a file and update the instance with it; the list replaces the one the instance has:

{
  "endpoints": [
    { "name": "web", "component": "main", "port": "http", "expose": "ingress" },
    { "name": "api", "component": "main", "port": "http", "expose": "ingress",
      "hostname": "api.example.com" },
    { "name": "admin", "component": "main", "port": "admin", "expose": "ingress", "authGuard": true },
    { "name": "mqtt", "component": "broker", "port": "mqtt", "expose": "loadBalancer" }
  ]
}

stsh ci update worker -g my-resource-group --file endpoints.json

Copy the existing entries from stsh ci get worker -o json unchanged, including their hostname: an ingress entry sent without one is given the platform hostname for its place in the list, which need not be the one it had.