Migration worries

Great work on v2!

Best way to get introduced is by forgetting to tag some docker server with the maroilles tag and have it fail during the nightly pull update :smiley:

On a more serious note: Just wanted to share some pain points that flared up from a docker user perspective:

  • https://docs.traefik.io/migration/v1-to-v2/ is quite the TODO collection for a GA software release and it does require to migrate all acme.json files manually via an external tool into the same name?
  • Most basic and daily stuff, like the default "entryPoints.http.redirect" directive which is the 3rd example in the 1.7 docs do not have any counterpart or is the RedirectScheme and is this per host or can the tests collide with other container labels?
  • What happend to the simple "Basics" chapter? I just find myself between a huge info dump in "Getting Started" and "Config Discovery" which is a highly folded and nested document with so many side nodes and sub-configs with unintuitive Go-Templates forked into it that it becomes pure brain noise reading through it.

I'm not the ops guy, maintaining 100 swam servers and instances and stuff, just using it for some smaller projects but this project just feels a lot more complicated right now. Mixing all the default and easier stuff with docker compose on a static machine with notes about all the swarm specifics in the same document is so irritating. Maybe split the Docker chapter into Docker and Docker Swarm specific topics?

As a side question: I have some containers that use the old "traefik.frontend.auth.basic" stuff, putting those (or forgetting to convert them) into a traefik v2 proxy will not end up unprotected and will error out on startup correct?

1 Like

I really feel you on this.

I expressed the same worries in slack and i just think Traefik does itself no favour in having such a bumpy migration. Such a great release should not get tainted grey because it's just hard to understand how to migrate over.

I think one of the hardest thing to get along with is the error message which is shown, when a configuration value is missplaced / wrong or does not exist.

E.g.

2019/09/17 16:58:67 command traefik error: field not found, node: debug

Without any context, it's hard to guess which one of theses it is

[global]
  debug: true

[api]
  debug: true

Well, it's the former, the latter is allowed.

A similar bummer is

019/09/17 16:53:13 command traefik error: field not found, node: entryPoint

Which actually tells us that api.entryPoint no longer exist, but it's hard to read and one will probably assume there is something wrong in entrypoints because .. https://docs.traefik.io/v2.0/migration/v1-to-v2/#tls-configuration-is-now-dynamic-per-router ... is not a complete migration. It let's us assume that with v2 entrypoints have been removed since the v2 example does not include them.

One might assume "check the docs" but really, if you start at https://docs.traefik.io .. in which sub-folder you expect entrypoints to be defined? Finding them under "Routing" was somewhat suprising to me, i was looking at https://docs.traefik.io/getting-started/configuration-overview/

Tracking down configuration issues will become a taks by skimming through the reference file https://docs.traefik.io/reference/static-configuration/file/ with a string search and trying to understand where specific values have been moved to, or even removed / renamed.

I think also there are some troublemakers in terms of naming, e.g. Providers are something that are introduced everywhere - great. But why is it called Configuration Discovery in the main sidemenu in the traefik docs?


I think, with v2, thinks became far more flexible and "Lego" alike. With routers and middlewares you probably you can do whatever you ever dreamed of - but this has a downside. It is far more generic and rather complicated to setup things which might have been a boolean value ( e.g. like global http to https redirect or how to expose you api .. just check the forum already).

This said - it's fair enough that we all need to RTFM - but that is the actual afair. The docs will need more attention and crafting when having such generic toolsets.

At the Traifik developers: Please do not take this as an offense, you did a great job with v2 already. I understand that docs are hard and maybe not the beloved task to finish with great detail.
But maybe think about it that way - not being able to discover all the new things and possiblities you build into v2, not being able to understand your new great concepts and ideas .. and even worth understanding them the wrong way, being even a little dissapointed about everything getting "complicated" ... does not do a great job for such a otherwise packed release.

Already way to long post, sorry ;/

1 Like

My most recent issue is the reliance on AI bots to manage their github issues

Great work on v2!

Thank you

Yes. You have to migrate acme.json manually with the tool at https://github.com/containous/traefik-migration-tool
And no, if I understand the last part of your question properly, it will not overwrite the existing file by default, see the usage at: https://github.com/containous/traefik-migration-tool/blob/master/docs/traefik-migration-tool_acme.md

  • Most basic and daily stuff, like the default "entryPoints.http.redirect" directive which is the 3rd example in the 1.7 docs do not have any counterpart or is the RedirectScheme and is this per host or can the tests collide with other container labels?

I think this is now answered by the latest iteration of the migration guide. See: https://docs.traefik.io/v2.0/migration/v1-to-v2/#http-to-https-redirection-is-now-configured-on-routers

  • What happend to the simple "Basics" chapter? I just find myself between a huge info dump in "Getting Started" and "Config Discovery" which is a highly folded and nested document with so many side nodes and sub-configs with unintuitive Go-Templates forked into it that it becomes pure brain noise reading through it.

I believe the equivalent of this chapter is now all the parts under https://docs.traefik.io/v2.0/getting-started/concepts/

The link leads to a 404