Skip to Content

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.

clusters/hetzner-fsn1.yaml
# 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: general

Domains

An app's domains list routes hostnames to it. Each entry names either a domain you own or a generated platform hostname.

projects/shop/apps/web.yaml
# 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
KeyMeaning
domainA hostname such as shop.example.com. The domain must be claimed and verified by your organization.
generatedA 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).
portThe app port to route to.
path_prefix, strip_prefixRoute only paths under a prefix, and optionally strip it before forwarding.
tlstrue (the default), false, or passthrough when the app terminates TLS itself.
wildcardWith tls: passthrough, route every name one or more labels below domain, but not domain itself.
dns_targetWhat 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_proxytrue 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

projects/shop/apps/game.yaml
# 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: 25565

HTTP settings

http sets the app's HTTP behaviour. Only the keys you write are changed; the others keep their current values.

projects/shop/apps/storefront.yaml
# 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
KeyMeaning
https_redirectRedirect plain HTTP to HTTPS.
www_redirectoff, to_www or to_apex.
hsts, hsts_max_age, hsts_include_subdomainsSend Strict-Transport-Security.
compressionCompress responses.
csp_mode, csp_preset, csp_policy, csp_report_uriContent-Security-Policy: mode off, report_only or enforce; preset basic, strict or custom (with your own csp_policy).
permissions_policy, permissions_policy_customPermissions-Policy: off, basic, strict or custom.
coopCross-Origin-Opener-Policy: off, same_origin_allow_popups or same_origin.
header_frame_options, header_nosniff, header_referrer_policyCommon security headers.
custom_headersExtra response headers. Replaces the stored list.
max_body_bytesThe largest accepted request body. null resets it to unlimited.
csrf_mode, csrf_trusted_origins, csrf_exempt_pathsCross-site request protection, see below.
content_negotiationStatic 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, HEAD or OPTIONS request, or it opens a WebSocket;
  • the browser marks it as coming from another site (Sec-Fetch-Site: same-site or cross-site), or an older browser sends an Origin header;
  • the Origin is not one of the app's own domains or csrf_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.

projects/shop/apps/checkout.yaml
# 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:
    - /webhooks
  • csrf_trusted_origins: up to 20 exact origins like https://login.example.com or https://example.com:8443. No wildcards, paths or trailing slashes. http:// origins are accepted only when the app serves plain HTTP (an http domain, or https_redirect: false).
  • csrf_exempt_paths: up to 20 path prefixes, each at most 256 characters. /webhooks exempts /webhooks and everything below it. / is refused: set the mode to off instead.

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).

projects/web/sites/docs.yaml
# 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
KeyMeaning
enabledServe twins. Default false.
typesWhich 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_tokensSend 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.

projects/shop/apps/api.yaml
# 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
projects/shop/apps/db.yaml
# 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.

projects/payments/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: payments
cluster: hetzner-fsn1

The 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 in rules.

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.

projects/shop/project.yaml
# 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/24

See 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.

On this page