↓Skip to main content

Cloudflared in Docker Compose (or Kubernetes)

·6 mins
Table of Contents

I like serving websites through cloudflare tunnel because I can skip getting a public IP, opening ports, setting up a load balancer, and dealing with certificates. In general, cloudflare tunnels have been very reliable for me once set up. However, every time I set up a new site, I forget the ideas and the steps.

Here’s a walkthrough for how to get cloudflared working in a docker-compose setup.

Note: this works for me, I might be missing knowledge and there might be better ways.

The Concepts #

Cloudflare Tunnel #

A tunnel is a connection between the cloudflared daemon and the Cloudflare network. It has a name and an ID. With a tunnel, you can route traffic from Cloudflare to your server.

Ingress rules #

Each tunnel can have multiple ingress rules. Each ingress rule has a hostname and a service: so you can route traffic to multiple backend services with the same tunnel.

Credentials and Account Certificate #

  • A certificate cert.pem authorizes cloudflared against your Cloudflare account. This is required to create and manage tunnels, as well as create dns records. It’s not required to run a tunnel.
  • A credentials file allows a user to run a specific tunnel and nothing else. This is all that’s needed to run the tunnel in production.

Unfortunately, it seems like if you fail to give cloudflared the credentials file (like through misconfiguration), it often gives an error message about a missing cert.pem file instead of a missing credentials file. cloudflared has arguments that make it look like you can pass the credentials as an environment variable, it seems like this doesn’t work with a config.yml file. These two things together cost me several hours. I might be missing something, YMMV.

Quick Tunnel, Locally Managed Tunnel, Remotely Managed Tunnel #

Cloudflare seems to have these concepts. I think:

  • Quick Tunnel is created from the CLI without a config file. You can’t have multiple ingress rules.
  • Locally Managed Tunnel is one you set up on the CLI and a config file.
  • Remotely Managed Tunnel is created in the Cloudflare dashboard.

We’re setting up a locally managed tunnel.

The Steps #

On the dev machine #

This works on MacOS, for me, as of 2025-02-17.

You can use cloudflare/cloudflared:latest, but I’d recommend getting the most recent version and using it for these commands and pinning the version in your docker-compose file. cloudflare/cloudflared:2025.2.0 is the version used in this example.

Authorize cloudflared with your Cloudflare account: #

docker run --rm -v ~/cloudflared:/home/nonroot/.cloudflared cloudflare/cloudflared:2025.2.0 tunnel login

This will open a browser window and ask you to log in to your Cloudflare account. It will write out a cert.pem file to ~/cloudflared.

Create a tunnel: #

docker run --rm -v ~/cloudflared:/home/nonroot/.cloudflared cloudflare/cloudflared:2025.2.0 tunnel create <tunnel-name>

This requires the cert from the previous step. It will output a tunnel ID and write a credentials file to ~/cloudflared/

Add DNS records mapping hostnames to the tunnel: #

docker run --rm -v ~/cloudflared:/home/nonroot/.cloudflared cloudflare/cloudflared:2025.2.0 tunnel route dns <tunnel-name> <hostname>

Where <hostname> is something like home.example.com.

This requires the cert, but it’s also just a convenience method to add a DNS entry pointing to the tunnel. Instead of this command, you can create these DNS records in the Cloudflare dashboard by adding a CNAME record pointing to: <tunnel-id>.cfargotunnel.com

Clean up #

Copy the credentials file, ~/cloudflared/<tunnel-id>.json, to the server. Once you copy the credentials file to the server, you can delete ~/cloudflared (the credentials file and the cert).

On the server #

This has always been Linux for me, but it’s all in Docker, so it should work on any platform.

docker-compose.yml:

services:
  server1:
    image: testcontainers/helloworld
  
  server2:
    image: testcontainers/helloworld

  cloudflared:
    image: cloudflare/cloudflared:2025.2.0
    restart: unless-stopped
    volumes:
      - ./cloudflared-config.yml:/cloudflared-config.yml
      - ./cloudflared-credentials.json:/cloudflared-credentials.json
    command: tunnel --no-autoupdate --config=/cloudflared-config.yml run

cloudflared-config.yml:

tunnel: <tunnel-id> or <tunnel-name>
credentials-file: /cloudflared-credentials.json

ingress:
  - hostname: hello1.example.com
    service: http://server1:8080
  - hostname: hello2.example.com
    service: http://server2:8080
  - service: http_status:404  # Default fallback, required

cloudflared-credentials.json is the file saved to ~/cloudflared/ in the tunnel create step. Git ignore this.

The docker compose up and check the logs for cloudflared to make sure it started the tunnel.

Adding a new service #

If you add a new service, do the following:

  1. Add a new service to the docker-compose file
  2. Add a new ingress rule
  3. Add a new DNS record that matches the hostname in the ingress rule

Put a password on it #

You can use Cloudflare Access (or Zero Trust, whatever they call it now) to require users to authenticate before accessing any of these services.

Go through the Access setup for your identity provider and then add “Self Hosted Application”, specifying the hostname you want to protect.

Kubernetes #

I’ve also done this is Kubernetes.

Everything is the same except for the docker-compose, configuration, and credentials files. Instead of the docker-compose file, you have a k8s Deployment and a ConfigMap. The configuration gets mounted in as a ConfigMap and the credentials file gets mounted in as a secret.

cloudflared.yaml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloudflared
spec:
  selector:
    matchLabels:
      app: cloudflared
  replicas: 2 
  template:
    metadata:
      labels:
        app: cloudflared
    spec:
      containers:
        - name: cloudflared
          image: cloudflare/cloudflared:2022.3.0
          args:
            - tunnel
            # Points cloudflared to the config file, which configures what
            # cloudflared will actually do. This file is created by a ConfigMap
            # below.
            - --config
            - /etc/cloudflared/config/config.yaml
            - run
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
          livenessProbe:
            httpGet:
              # Cloudflared has a /ready endpoint which returns 200 if and only if
              # it has an active connection to the edge.
              path: /ready
              port: 2000
            failureThreshold: 1
            initialDelaySeconds: 10
            periodSeconds: 10
          volumeMounts:
            - name: config
              mountPath: /etc/cloudflared/config
              readOnly: true
            - name: creds
              mountPath: /etc/cloudflared/creds
              readOnly: true
      volumes:
        - name: creds
          secret:
            # Created when you run `cloudflared tunnel create`. You can move it into a secret by using:
            # ```sh
            # kubectl create secret generic tunnel-credentials \
            # --from-file=credentials.json=/Users/yourusername/.cloudflared/<tunnel ID>.json
            # ```
            secretName: tunnel-credentials
        # Create a config.yaml file from the ConfigMap below.
        - name: config
          configMap:
            name: cloudflared
            items:
              - key: config.yaml
                path: config.yaml
---
# This ConfigMap is just a way to define the cloudflared config.yaml file in k8s.
# It's useful to define it in k8s, rather than as a stand-alone .yaml file, because
# this lets you use various k8s templating solutions (e.g. Helm charts) to
# parameterize your config, instead of just using string literals.
apiVersion: v1
kind: ConfigMap
metadata:
  name: cloudflared
data:
  config.yaml: |
    # Name of the tunnel you want to run
    tunnel: <tunnel-id> or <tunnel-name>
    credentials-file: /etc/cloudflared/creds/credentials.json
    # Serves the metrics server under /metrics and the readiness server under /ready
    metrics: 0.0.0.0:2000
    # Autoupdates applied in a k8s pod will be lost when the pod is removed or restarted, so
    # autoupdate doesn't make sense in Kubernetes. However, outside of Kubernetes, we strongly
    # recommend using autoupdate.
    no-autoupdate: true
    # The `ingress` block tells cloudflared which local service to route incoming
    # requests to. For more about ingress rules, see
    # https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/configuration/ingress
    #
    # Remember, these rules route traffic from cloudflared to a local service. To route traffic
    # from the internet to cloudflared, run `cloudflared tunnel route dns <tunnel> <hostname>`.
    # E.g. `cloudflared tunnel route dns example-tunnel tunnel.example.com`.
    ingress:
      - hostname: hello1.example.com
        service: http://service:80
      # This rule matches any traffic which didn't match a previous rule, and responds with HTTP 404.
      - service: http_status:404
↑