Label Format

Labelgate reads Docker container labels to determine what Cloudflare resources to manage. All labels follow a consistent naming convention.

Format

labelgate.<type>.<service_name>.<property>=<value>

Service Name Rules

The service_name is a unique identifier for each service within a container. It lets you define multiple services on the same container.

Allowed characters: lowercase letters, digits, and hyphens: [a-z0-9]([a-z0-9-]*[a-z0-9])?

Reserved words (cannot be used as service names): hostname, service, type, target, proxied, ttl, cleanup, credential, tunnel, path, origin, access, default, priority, weight, port, flags, tag, comment

Multiple Services

A single container can define multiple services:

labels:
  # Service "web" - main website
  labelgate.tunnel.web.hostname: "www.example.com"
  labelgate.tunnel.web.service: "http://app:80"
  # Service "api" - API endpoint
  labelgate.tunnel.api.hostname: "api.example.com"
  labelgate.tunnel.api.service: "http://app:3000"

Hostname Constraints

DNS and Tunnel Conflict

The same hostname cannot have both a DNS record and a Tunnel ingress rule. Cloudflare Tunnel automatically creates a CNAME record for tunnel hostnames, so adding a manual DNS record would conflict.

# WRONG - hostname conflict
labels:
  labelgate.dns.web.hostname: "app.example.com"
  labelgate.tunnel.web.hostname: "app.example.com"  # Conflict!

# CORRECT - use different hostnames
labels:
  labelgate.dns.legacy.hostname: "old.example.com"
  labelgate.tunnel.web.hostname: "app.example.com"

First Container Wins

When multiple containers claim the same hostname, the first container to register wins. Subsequent containers will log an error and skip that hostname.

Label Types

• DNS Labels - Manage Cloudflare DNS records
• Tunnel Labels - Manage Cloudflare Tunnel ingress rules
• Access Policy Labels - Manage Zero Trust Access policies