Skip to content

ContainerLabels.md

Jump to bottom
Chris edited this page May 15, 2025 · 9 revisions

Container Labels

Docker labels are the primary mechanism for instructing DockFlare which containers to expose and how to configure their public access and Zero Trust Access policies via your Cloudflare Tunnel.

DockFlare monitors Docker events and inspects container labels. If a container has the required labels, DockFlare will automatically configure the necessary DNS records, Cloudflare Tunnel ingress rules, and potentially Cloudflare Access Applications.

Label Prefix

DockFlare looks for labels starting with a specific prefix.

  • Default Prefix: cloudflare.tunnel
  • Custom Prefix: You can change this using the LABEL_PREFIX environment variable.

In the examples below, the default prefix cloudflare.tunnel is used. If you set a custom prefix (e.g., LABEL_PREFIX=cf.ingress), replace cloudflare.tunnel with cf.ingress in your labels.

Core Ingress Labels

These labels are essential for exposing a service's network endpoint:

Label Description Required Example
{prefix}.enable Must be set to "true" for DockFlare to manage this container. Yes cloudflare.tunnel.enable="true"
{prefix}.hostname The public hostname (subdomain) you want to use. Must be within a zone managed by your Cloudflare account. Yes cloudflare.tunnel.hostname="app.example.com"
{prefix}.service The internal network address of the service. Format: protocol://hostname:port (e.g., http://my-app:80, https://my-app:443, tcp://host:port). Yes cloudflare.tunnel.service="http://my-app-container:80"

Optional Ingress Configuration Labels

These labels allow for more specific configuration of the ingress rule itself:

Label Description Required Example
{prefix}.zonename Specifies the Cloudflare zone (domain name, e.g., example.com) for the hostname. Overrides the default CF_ZONE_ID env var for this rule. No cloudflare.tunnel.zonename="mydomain.org"
{prefix}.no_tls_verify If set to "true", Cloudflare Tunnel will not verify the TLS certificate of an HTTPS internal service. Useful for self-signed certs. No cloudflare.tunnel.no_tls_verify="true"

Access Policy Labels (Zero Trust)

These labels define the initial Cloudflare Access Policy for the exposed hostname. Note: These label-defined policies can be overridden by changes made in the DockFlare Web UI. If a UI override is active, these labels will not be re-applied unless the policy is "Reverted to Labels" via the UI.

Label Description Default Example
{prefix}.access.policy Defines the type of Access Policy. Common values: bypass (public), authenticate (requires login via configured IdPs), default_tld (inherits from *.yourdomain.com policy, no app created for this specific hostname). (None) cloudflare.tunnel.access.policy="authenticate"
{prefix}.access.name Custom name for the Cloudflare Access Application. DockFlare-{hostname} cloudflare.tunnel.access.name="My Web App Access"
{prefix}.access.session_duration Session duration for the Access Application (e.g., 24h, 30m). 24h cloudflare.tunnel.access.session_duration="1h"
{prefix}.access.app_launcher_visible If "true", the application will be visible in the Cloudflare App Launcher. false cloudflare.tunnel.access.app_launcher_visible="true"
{prefix}.access.allowed_idps Comma-separated list of allowed Identity Provider (IdP) UUIDs. If access.policy="authenticate" and this is not set, it typically allows any configured IdP for the account. (Account Default) cloudflare.tunnel.access.allowed_idps="<IdP_UUID_1>,<IdP_UUID_2>"
{prefix}.access.auto_redirect_to_identity If "true", automatically redirects to the identity provider login page. false cloudflare.tunnel.access.auto_redirect_to_identity="true"
{prefix}.access.custom_rules A JSON string representing an array of Cloudflare Access Policy rules. Overrides access.policy if set to authenticate or bypass for policy decision. See Cloudflare Access Policy Docs for schema. (None) cloudflare.tunnel.access.custom_rules='[{"email":{"email":"[email protected]"},"action":"allow"}]'

Example of Access Policy Labels:

labels:
  cloudflare.tunnel.enable: "true"
  cloudflare.tunnel.hostname: "secure-app.example.com"
  cloudflare.tunnel.service: "http://my-secure-app:8080"
  cloudflare.tunnel.access.policy: "authenticate"
  cloudflare.tunnel.access.session_duration: "8h"
  cloudflare.tunnel.access.allowed_idps: "YOUR_GITHUB_IDP_UUID_HERE" 
  # This creates an Access Application named "DockFlare-secure-app.example.com"
  # that requires authentication via the specified GitHub IdP with an 8-hour session.

Labeling Approaches & Precedence

DockFlare supports applying these labels in two main ways:

  1. Basic Usage (Single Domain): Use simple, non-indexed labels ({prefix}.hostname, {prefix}.access.policy, etc.) to expose and configure one hostname per container.
  2. Using Multiple Domains (Indexed Labels): Use indexed labels ({prefix}.0.hostname, {prefix}.0.access.policy, then {prefix}.1.hostname, etc.) to expose multiple hostnames from a single container. Each indexed set can have its own full configuration, including its own Access Policy settings.
    • If an indexed configuration (e.g., {prefix}.0.access.policy) is set, it takes precedence over any default (non-indexed) {prefix}.access.policy label for that specific indexed hostname.
    • If an indexed configuration omits an access label (e.g., {prefix}.0.access.session_duration is not set), it will fall back to the value of the default non-indexed label (e.g., {prefix}.access.session_duration) if present, or finally to the hardcoded application defaults.

See the linked pages for detailed examples. Remember that Access Policies defined by any of these labels can be interactively changed and overridden via the Web UI.

Clone this wiki locally