Networking
Domains, HTTP settings, connections between apps and projects, and outbound traffic.
The examples on this page share one project, shop, on the cluster
hetzner-fsn1.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
- name: control-plane
role: control_plane
- name: generalDomains
An app's domains list routes hostnames to it. Each entry names either a
domain you own or a generated platform hostname.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/web:2.0.0
port: 3000
domains:
- generated: site
- domain: shop.example.com
dns_target: cname
behind_proxy: true
- domain: shop.example.com
path_prefix: /api
strip_prefix: true
port: 8080| Key | Meaning |
|---|---|
domain | A hostname such as shop.example.com. The domain must be claimed and verified by your organization. |
generated | A platform hostname instead of a literal one: site for the app's HTTPS host, or srv for a TCP or UDP host (with protocol and port). |
port | The app port to route to. |
path_prefix, strip_prefix | Route only paths under a prefix, and optionally strip it before forwarding. |
tls | true (the default), false, or passthrough when the app terminates TLS itself. |
wildcard | With tls: passthrough, route every name one or more labels below domain, but not domain itself. |
dns_target | What the domain's DNS records point at: a_records (A and AAAA records at the load balancer) or cname (a CNAME to the app's platform host). Leaving it out keeps the current choice. |
behind_proxy | true when the domain is served through a CDN or reverse proxy (Cloudflare, Fastly, ...). The DNS check then fetches https://<domain>/ and confirms the request reached this app, instead of matching load balancer addresses. HTTP(S) domains only. Set Cloudflare's SSL/TLS mode to Full (strict), never Flexible. It also gives the domain an ACME challenge delegation, so its certificate is issued over DNS (see Behind a CDN or proxy). Leaving it out keeps the current setting. |
Don't write a platform hostname as a literal domain: it is refused with
platform_suffix_literal. Use generated instead.
Origin lock
A domain behind_proxy can also be locked to your own CDN, so nobody can
skip its firewall or rate limits by calling the load balancer directly. Turn
on Origin lock in the domain's settings (or POST .../domains/{domain_id}/origin-lock
in the API): you get a key, shown once. Have your CDN send it on every request
in the X-Aline-Origin-Key header (on Cloudflare: Rules, Transform Rules,
Modify Request Header, Set static). Requests without a matching key get 403.
The header is removed before the request reaches your app.
Rotating the key gives you a new one and keeps the previous one working for
24 hours. Turning the lock off stops every key at once. Keys are not part of
the IaC file and an export never contains them; only their fingerprint
(the first 16 hex digits of printf %s KEY | sha256sum) is ever shown again.
While the lock is on, the client IP header you choose (CF-Connecting-IP,
True-Client-IP, Fastly-Client-IP or your own) is passed to the app with
the visitor's address; read the client IP from that header. Without the lock
it is removed like every other client-set header, because anyone could set
it. X-Real-Ip (and the last X-Forwarded-For entry) holds the address of
the CDN edge that connected, not the visitor's.
TCP and UDP
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/game-server:1.0.0
ports:
- port: 25565
name: game
domains:
- generated: srv
protocol: tcp
port: 25565HTTP settings
http sets the app's HTTP behaviour. Only the keys you write are changed;
the others keep their current values.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/storefront:3.1.0
port: 3000
http:
https_redirect: true
www_redirect: to_apex
hsts: true
hsts_max_age: 31536000
compression: true
csp_mode: enforce
csp_preset: strict
max_body_bytes: 10485760| Key | Meaning |
|---|---|
https_redirect | Redirect plain HTTP to HTTPS. |
www_redirect | off, to_www or to_apex. |
hsts, hsts_max_age, hsts_include_subdomains | Send Strict-Transport-Security. |
compression | Compress responses. |
csp_mode, csp_preset, csp_policy, csp_report_uri | Content-Security-Policy: mode off, report_only or enforce; preset basic, strict or custom (with your own csp_policy). |
permissions_policy, permissions_policy_custom | Permissions-Policy: off, basic, strict or custom. |
coop | Cross-Origin-Opener-Policy: off, same_origin_allow_popups or same_origin. |
header_frame_options, header_nosniff, header_referrer_policy | Common security headers. |
custom_headers | Extra response headers. Replaces the stored list. |
max_body_bytes | The largest accepted request body. null resets it to unlimited. |
csrf_mode, csrf_trusted_origins, csrf_exempt_paths | Cross-site request protection, see below. |
content_negotiation | Static sites only: answer pages in Markdown, JSON, YAML or text, see below. |
Cross-site request protection
With csrf_mode: enforce, the edge refuses a state-changing request that a
browser sends from another site, with a plain 403, before it reaches your
app. A request is refused when all of these hold:
- it is not a
GET,HEADorOPTIONSrequest, or it opens a WebSocket; - the browser marks it as coming from another site (
Sec-Fetch-Site: same-siteorcross-site), or an older browser sends anOriginheader; - the
Originis not one of the app's own domains orcsrf_trusted_origins; - the path is not under one of
csrf_exempt_paths.
Requests without these browser headers, such as webhooks, CLIs and calls
from other servers, always pass. report_only lets every request through but
adds X-Aline-Csrf: would-block to the ones enforce would refuse, so you
can check your logs before you switch it on. The default is off.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/checkout:1.4.0
port: 3000
http:
csrf_mode: enforce
csrf_trusted_origins:
- https://login.example.com
csrf_exempt_paths:
- /webhookscsrf_trusted_origins: up to 20 exact origins likehttps://login.example.comorhttps://example.com:8443. No wildcards, paths or trailing slashes.http://origins are accepted only when the app serves plain HTTP (anhttpdomain, orhttps_redirect: false).csrf_exempt_paths: up to 20 path prefixes, each at most 256 characters./webhooksexempts/webhooksand everything below it./is refused: set the mode tooffinstead.
Static sites only serve GET and HEAD, so they have no CSRF settings.
Content negotiation
A static site can answer a page without an extension with a twin file when
the request's Accept header prefers it over HTML. With
content_negotiation on, curl -H 'Accept: text/markdown' https://docs.example.com/about
gets about.md instead of about.html. Browsers keep getting HTML: a tie,
*/* and the usual browser Accept values all answer with the page, and a
request that matches no twin gets the page too (never 406).
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
repo: example/docs
http:
content_negotiation:
enabled: true
types: [markdown, json]
markdown_tokens: true| Key | Meaning |
|---|---|
enabled | Serve twins. Default false. |
types | Which twins: markdown (.md, text/markdown), json (.json, application/json), yaml (.yaml then .yml; application/yaml, application/x-yaml or text/yaml) and text (.txt, text/plain). Default all four. |
markdown_tokens | Send x-markdown-tokens with a Markdown twin: a token estimate (characters / 4) counted at deploy. Default true. |
The twin of / is index.<ext>; /about/ tries about.<ext>, then
about/index.<ext>; /about tries about.<ext>. A twin is sent with status
200, its own Content-Type and a Content-Location naming the file, and
your _headers rules still apply. Every answer for a page that can be
negotiated, the HTML one too, carries Vary: Accept, so caches keep the two
apart. The mapping replaces the stored choice: keys you leave out take their
defaults. A change applies with the next routing update, no redeploy. An app
file refuses the key.
Connections between apps
connections opens traffic from this app to other apps of the same project,
on the listed ports.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/api:1.4.2
port: 8080
connections:
- to: db
ports:
- port: 5432
protocol: tcp# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
template: postgres
version: "16"Connections between projects
A project's network_policies allows traffic to another project of the same
cluster. direction: both (the default) lets both projects reach each other;
ingress lets only this project reach the target. network_policies: []
removes every policy.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: payments
cluster: hetzner-fsn1The shop project below lets itself reach payments on port 443 and also
limits its outbound traffic.
Outbound traffic
egress controls where a project or an app can connect to outside the
cluster:
mode: public(a project's default): any destination.mode: isolated: only the destinations inrules.
Each rule has a kind (fqdn or cidr), a value (a domain, optionally
starting with *., or a CIDR), an optional port, an optional protocol
(tcp or udp, which needs a port) and a description. In public mode
the rules are informational. An app without egress.mode follows its
project.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
network_policies:
- target: payments
direction: ingress
ports:
- port: 443
egress:
mode: isolated
rules:
- kind: fqdn
value: api.example.net
port: 443
protocol: tcp
description: Payment provider
- kind: cidr
value: 203.0.113.0/24See NetworkPolicySpec and
EgressSpec for every key.
Blocked connection emails
In isolated mode, each blocked connection shows in the app's logs as
"blocked outbound connection to" the address. The org's owner and admins
also get an email and an in-app notification per app, with the address and
port, the domain name when known, how often it was blocked, and when it was
first and last seen. To keep the volume low:
- An app's first blocked connection is reported within about 15 minutes. After that, each app gets at most one daily digest.
- A digest lists only destinations not reported in the last 7 days, up to 10, then "+N more".
- An org gets at most 5 of these emails a day. The rest are added to a later digest.
To stop the emails for all apps, turn off Blocked outbound traffic in
Settings > Notifications (/settings/notifications); members can turn it
on there. To stop them for one
app, use the Don't email me about this app link in the email, or the
switch in the app's Network tab. Both choices only apply to you.