Skip to content

Allow discovering non-running Docker containers #10645

Merged
traefiker merged 4 commits into
traefik:masterfrom
acouvreur:master
Oct 24, 2025
Merged

Allow discovering non-running Docker containers #10645
traefiker merged 4 commits into
traefik:masterfrom
acouvreur:master

Conversation

@acouvreur

@acouvreur acouvreur commented Apr 21, 2024

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR implements the allowEmptyServices capabilities to the Docker provider by allowing non running containers to be discovered.

Motivation

Non-running containers not returning 404, but 503 instead and having the full middleware chain built and executed on requests.

Fixes #9907

Fixes #7842

More

  • Added/updated tests
  • Added/updated documentation

Additional Notes

Test it yourself:

services:
  traefik:
    image: traefik:local
    command:
      - --entryPoints.http.address=:80
      - --providers.docker=true
      - --providers.docker.allowEmptyServices=true
      - --log.level=DEBUG
    ports:
      - "8080:80"
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'

  whoami:
    image: containous/whoami:v1.5.0
    labels:
      - traefik.enable=true
      - traefik.http.routers.whoami.rule=PathPrefix(`/whoami`)
  1. Pull this PR
  2. make
  3. docker build -t traefik:test .
  4. docker compose up
  5. docker compose down whoami
  6. curl http://localhost:8080/whoami -> 503

You can add any middleware, and they will get exectued, which is the most important part.

@rtribotte

Copy link
Copy Markdown
Member

Hello @acouvreur,

Thank you for this contribution!

The extension of the Docker provider allowEmptyServices option to include stopped containers could have a side effect that does not exist with other providers, or at least not the same meaning.

As the service definition with a docker container isn't a really "thing" (at most a docker-compose service), that Traefik can read and rely on, multiple stopped containers providing different dynamic configurations for the same resources (routers, middleware, etc...) can co-exist, which will result as being in error and dropped because of conflicting configurations found.

With docker-compose, this is mitigated if the service name never changes, as the stopped containers for the service are cleared.

With other providers, the service definition is what Traefik uses to create the configuration, and because this is not possible with Docker, I am wondering if this behavior should be controlled with the same allowEmptyServices option, WDYT?

@mrbreil

mrbreil commented May 27, 2024

Copy link
Copy Markdown

I'm interested in it too. I would like to have a custom error page for a stopped container. and it only works if the container is running or unhealthy. If the container is stopped, I just get a simple 404.

@acouvreur acouvreur changed the base branch from v3.0 to v3.3 January 31, 2025 04:00
@acouvreur acouvreur changed the base branch from v3.3 to master January 31, 2025 05:17
@acouvreur acouvreur marked this pull request as ready for review January 31, 2025 05:17
@acouvreur

acouvreur commented Jan 31, 2025

Copy link
Copy Markdown
Contributor Author

It's been a while!

I've reworked this all from scratch.

Basically all it does now is that the container status is now reported in the structure dockerData, which is then used to return a nil server if AllowEmptyServices is set to true.

We can talk about having a dedicated field for that feature specifically, but in my opinion this is what the feature is supposed to be.

AllowEmptyServices is about allowing services that are empty to be registered by Traefik, which is shown like that in the UI:

image

It returns a 503 no available server as expected, and you can have a middleware in front catching the request and do whatever you want with it.

@acouvreur acouvreur changed the title first draft that allows non-running containers to be retrieved using allowEmptyServices feat(provider): add allowEmptyServices for docker provider to scan non-running containers Feb 2, 2025
@rtribotte rtribotte added the kind/enhancement a new or improved feature. label Feb 5, 2025
@acouvreur

Copy link
Copy Markdown
Contributor Author

Any news @rtribotte ?

@rtribotte

Copy link
Copy Markdown
Member

Hi @acouvreur, sorry for the late reply.

We have given some more thought to changing the behaviour of the allowEmptyServices option and have come to the conclusion that we cannot introduce a breaking change.
In fact, exposing stopped containers from now on could lead to conflicting exposed routers, where the empty service router can take precedence over one with active service, and thus breaking some setups.

Also, as mentioned above, the lack of service definition in Docker is the a blocker to considering a stopped container as defining a service.

So we do not think that using this option in your use case is the best option.

However, we think the ability to discover a stopped container could be an opt-in feature per container by introducing a new label, WDYT?

@Kitof

Kitof commented Mar 14, 2025

Copy link
Copy Markdown

@rtribotte Thanks for your answer. Just to be sure to understand correclty, your proposition is to keep the PR of @acouvreur but with an additionnal config or label parameter like "visibleWhenStopped" with default value to false ?

@sdelicata sdelicata left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @acouvreur for this contribution!
I just made a few suggestions. Other than that LGTM

Comment thread pkg/provider/docker/config.go Outdated
Comment thread pkg/provider/docker/config.go Outdated
acouvreur and others added 4 commits October 24, 2025 11:43
…lowEmptyServices

This will allow  middleware to be used on containers that are currently not running.
@rtribotte rtribotte changed the title feat(provider): add allowEmptyServices for docker provider to scan non-running containers Add traefik.docker.allowNonRunning to discover non-running containers Oct 24, 2025
@rtribotte rtribotte changed the title Add traefik.docker.allowNonRunning to discover non-running containers Add traefik.docker.allowNonRunning to discover non-running containers Oct 24, 2025
@rtribotte rtribotte changed the title Add traefik.docker.allowNonRunning to discover non-running containers Add traefik.docker.allowNonRunning option to discover non-running containers Oct 24, 2025

@rtribotte rtribotte left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @acouvreur,

We pushed a review commit.
We limited the impact of the option only to the Docker provider, since we identified that the allowEmptyService Swarm provider option should be enough to support the Sablier use case.
However, currently the allowEmptyService option is not working as expected (and as you mentioned it, using the LBSwarm option is the current workaround). We opened an issue for that: #12196

Thank you!

@kevinpollet kevinpollet changed the title Add traefik.docker.allowNonRunning option to discover non-running containers Allow discovering non-running Docker containers Oct 24, 2025
@rtribotte rtribotte dismissed sdelicata’s stale review October 24, 2025 12:06

Comments have been addressed.

@traefiker traefiker merged commit 10be359 into traefik:master Oct 24, 2025
62 of 65 checks passed
@vordenken

Copy link
Copy Markdown

Can't believe it finally happend... Thank you all. I'm excited to test it out when it's available

@nickshanks347

Copy link
Copy Markdown

Can't believe it finally happend... Thank you all. I'm excited to test it out when it's available

Crazy right? A year and a half in the making

@Timo-1979

Copy link
Copy Markdown

I've just tested to start a single container.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add option to get all containers despite running state Do not filter "unhealthy" or "starting" Docker containers