If you are talking about v2, as I understand it’s still in alpha, and improvements are to come.
If you are talking about v1, not sure what “full working configuration” is. If you care to google, there are a number of tutorials over there. Of course they may not be suitable for your use case, but that’s because it’s traditionally an area with a lots of moving parts, and everyone needs and setups are different.
There are examples in the official github repo too.
As far as SSL is concerned, if you are talking about let’s encrypt, thab what’s “fully working” means also depends. For example if you use DNS challenge, my configuration could be different from yours because we are using different DNS providers. If you use http, then it’s up to you to make sure that external DNS resolves to your installation, and how it’s done is specific to your DNS hosting and network infrastructure.
You might want to familiarize yourself with certbot which is not required to use traefik and is not used by traefik (traefik internally uses lego to get comfortable with let’s encrypt. By familiarize, I mean actually issuing some certs and seeing how that is suppose to work with regards to domain validation.
As for a practical example, keeping in mind the points above, you can try the following.
make sure that you point test.domain.tld from the example below to your installation. We are going to use dns challenge so it is not important that anyone else can resolve this domain, but you should be able to. Hosts file is adequate here
make sure that you manager your dns zome (domain.tld) with digital ocean and you obtained read/write api token from them
it is not possible for me to list all other requirements, because environments are different in subtle way, for example your container will need to have network access to digital ocean for the api call, your zone need to be delegate to digital ocean to manager dns, etc. I’m assuming that your environment is similar to mine. Docker and linux are also implied. domain.tld is to be replaced by a domain you own/control.
Start up a nginx container:
docker run --name nginx -d -l traefik.frontend.rule=Host:test.domain.tld nginx
Start up traefik, make sure to supply your own digital ocean API token and email:
Give a couple of minutes for issuing the cert and then navigate to https://test.domain.tld you should be able to navigate to it and see the generated cerificate served correctly. If you have any issues make sure to also include -l debug to enable debug logging and examine logs.
I'm tagging along, because I'd be very interested if you could point to the incoherent pieces of examples. Our goal is obviously to provide an excellent user experience, so anything that can be improved is welcome.
Great to hear from you. Glad to know that there is people worried about users experience in traefik. Let me try to explain the kind of trouble I’m having with traefik’s documentation.
I can’t find a single complete working example of traefik configuration for any user case (and not for my use case also) in traefik’s documentation.
One example: to make traefik work for the first time I had to find working examples outside traefik’s documentation so I could understand all the minimum necessary pieces and concepts to have a working setup.
I started with the https://docs.traefik.io/basics/ page. I would expect to be able to have my first traefik configuration working with the info on the Basics page. Having read it I tried to create my first traefik configuration file, so I copied one version of the following configuration sections from the above page: [entryPoints], [frontends] and [backends], adapted them to my use case and obviously nothing worked as I didn’t put the [frontends] and [backends] sections inside a [file] section.
I didn’t find the info that [frontends] and [backends] sections should be inside a [file] section in the Basics page. I had to find a full working example outside traefik’s documentation to discover this rather simple and essential piece of information.
Please be aware that even if this info is mentioned somewhere in the Basics page (which I don’t think it is), there would be a much simplier solution: include at least one full working example of configuration in each section of traefik’s documentation (and certainly in the Basics page) so users can get it, adapt to their respective use cases and go on.
This pattern is repeated across all traefik’s documentation that I tried to use. Everywhere there are small pieces of configuration settings covering some specific issue but there is never a complete working example so when I try to use whatever feature of traefik I’m interested on, I only manage to get it working when I get some outside working example where I discover all the necessary details that traefik’s documentation didn’t present to me.
And by “working example” I don’t mean the big configuration files full of ellipses that we have in a few places in traefik’s documentation. They are nice to get an overall look but I mean real working examples that can be simply copy/pasted and, with a prescribed environment, would simply work. In my point of view they are essential. Starting with them, is much easier to get to a working setup on whatever use case users have to deal with.
You are right that “full working configuration example” can mean several different things. What I mean by it, is a complete set of complete configuration files that achieve a prescribed objective.
In your example, there is no traefik.toml file. I believe that for someone that will try to implement the configuration you proposed, it would be a great help to see a complete traefik.toml file example that works with the rest of the configuration you proposed.
You presented an example with [acme] generated Letsencrypt file. I agree that this is probably a very common use case.
I, personaly, would like to see a complete configuration example for SSL services that uses certificate files already available previously created by whatever means the user choose to use (and haven’t found one such example with Google yet) . Can you point me to one?
Full working example for me is using Traefik in a docker swarm with a private registry, a frontend, a backend, monitoring tools and a ci/cd flow with droneci using digital ocean. But this would be above and beyond and is really a personal goal of mine.
I believe that for someone that will try to implement the configuration you proposed, it would be a great help to see a complete traefik.toml
Can you point me to one?
Just use what I gave you earlier. Remove the acme releated lines and add modify entrypoints to be --entryPoints='Name:https Address::443 TLS:certs/traefik.crt,certs/traefik.key' map the /certs directory of the container to the directory on your host with traefik.crt and traefik.key. This is what traefik container creation looks after modifications:
Again, I have not read it from top to bottom, but it looks like it suits your use case and should help you. In particular, it looks useful that the author of that article describes what he is doing step by step, but also provides a github repo, with his end result.
Note, that it is quite likely that if you use it as is without modification, it won't work for you. This is, as explained, is because everyone's environment may have subtle differences and configurations require ajustements based on that. Good luck!
@geraldcroes I also would like to address your message above in saying, that while rsevero’s wording was harsh I can understand what he is talking about.
Traefik documentation is a treasure trove, but it has a bit high barrier to entry. With my own experience with traefik, I have no problem with it, but I can see how it can be confusing for less experienced users. rsevero gave you a few examples above, here is another one:
Yet, none of the examples given for kubernetes shows how to reference the TOML configuration file in the first place. Now if you respond, that this is explained elsewhere on the documentation site, you will be quite right, it is. When I’m reading it I understand what it means: you can put your toml in a config map, then you use volume mapping for the traefik pod to associate it with the correct path in the container. You also could argue, that this is more related to kubernetes than to traefik, and thus it does not really belong in traefik documentation. Whether you would be right here or not the jury is still out: you would have a point. However an example of that without detailed explanation of kubernetes would certainly improve the documentation and is not out of place - if you mention adding something to TOML, also mention how to add the TOML iteself in the first place.
What I just described above is not a huge issue on it’s own, but I, same as rsevero, feel that there are more issues like that on the site. It’s feels like it’s written over time like a patchwork of very usefull snippets, by people who know traefik inside-out, but those snippets often lack the context a new user would not have, and not much information, where to find it.
Finally, I’d like to preempt you saying that community is welcome to open PRs, I know that and I think it’s really awesome, but I just wanted to provide some feedback you asked for
I understand what you mean by “out of context”/“incomplete snippets” … even if I’m still unsure about what the best solution is.
My suggestion is that you include at least one full complete working example per documentation page. Elect a general case you believe is the more didactic that covers the issue covered in the page and include it. Preferably with an explanation of the environment where that example would work.
I’m sure that would be a great help for newcomers and who ever is trying a new feature.
I have a file edge.yml which holds traefik related services. Key difference between this and other stuff you may see is the use of a "daemon" service. This service exposes the Docker Daemon as a TCP server specifically for this stack only. The purpose of this is to traefik to run on worker nodes which do not normally have access to the /var/run/docker.sock with the swarm manager data.
Secondly it uses Zookeeper to manage the configuration.
I'll chime in here and share my experience approaching Traefik for the first time and trying to get things running by reading the docs.. I understand everyon'e implementation and use cases vary wildly and that Traefik has a large variety of configurations, I think this adds to the trouble...
I share Rodrigo's frustration and the desire to have a "full working example" - In such a large and fast moving space, I understand the difficulties in providing these examples.
For what it's worth, here is my experience:
I'm running java microservices in an Azure Service Fabric Cluster. Microsoft recommended we use Traefik as our Ingress Gateway/Router vs the Azure App Gateway as Service Fabric is a bit too dynamic for the App Gateway. The Azure App gateway seems to lose track of the Service Fabric services as it doesn't query the SF API directly, it relies on static routing.
Unfortunately, none of these will work for me as I'm using a LINUX service Fabric Cluster, not a Windows Cluster as most examples point out. There are quite a few differences in how Service Fabric Linux is configured vs Service Fabric Linux.
There are docs for Linux, yes.. But I'm using Visual Studio to publish to Linux... I'm not using sfctl, or docker in this case as its not recomennded.
Now, I don't need everything handed to me on a Silver platter to get something to work, but this still leaves in to where I have no working example to build on... I can't deploy the provided sample to Linux, it won't even run there..
So I spent a ton of time figuring out how to deploy/run and configure Traefik to run in Linux on Service Fabric. I was able to get it to run, but unable to get it to connect to service fabric at all.. A few days later I figured out that I needed to add a read-only localhost certificate to my service fabric cluster and use this certificate to connect. I was running Traefik as another application inside my cluster, so it connects via http://localhost, hence, thats the cert it needs.
So, I was able to get it to run and to connect and discover services.. Now to trying to figure out the routing.. This part of the documentation is tough.. If you look at the service fabric page it lists a set of "supported labels"
Problem with this is I have NO IDEA what labels I need, they are all described somewhat, but still no working examples.. IE, whats the minimum number of labels I need to get routing to work?
So, i tried the PathPrefixStrip Rules, saw how they work, tried other rules, tried multiple rules... I still cant figure out the routing:
So, i got some basic routing to work, One PathPrefix per service at least gets me going.. I can route through the gateway to some basic services.. This seems like a big challenge in the docs, some routing samples.. IE, how can I handle routing /test1 & /test1/health & /test1/info re-writing the url for health and info to /health /info, but still routing to the right service.. everything seems to break when I apply more than one rule. Actual rule samples here might help, not just describing how all the matchers and modifiers work. I can't seem to find a single sample of how to use the RegEx Matcher/Modifiers, whats the regex syntax need to look like? A working sample?
Now I need to look at SSL..
This is another can of worms.. The docs talk all about using lets encrpyt..
This is one of the most confusing websites I've ever seen, I can't find any way to "sign up" It seems all the ACME configurations use a login to Lets Encrypt. I don't want to "generate a certificate", I already have a certificate. So this makes 80% of the v1.7 samples that use LetsEncrypt worthless to me. I need some samples using my own certificates.. No, I didn't get real deep into the docs, it doesn't seem like something I want to use. -
It wants me to install Certbot ? - I don't want to isntall anything on the Linux Service fabric nodes! What is this amatuer hour? Since when do I install random software to issue certs on my cluster images ?
I already have a certificate, from a CA, I just want to use that.
So I extracted my certs, added the configuration section..
Now all my routing fails.. The cert shows up with a lock and shows its valid in the browser, but all the routing fails, rturns 404s and says "backend not found"
So, I've spent 2 weeks working on getting a sample to work, I still don't have routing working right, the SSL doesn't seem to work, my questions go un-answered, and most of the documentation is worthless as it doesnt apply.
One of the challenges of my configuration also, is the base endpoint configuration is in the TOML, but the backend configuration is dynamically discovered.. So, again most of the samples that use the [file] moniker are worthless to my use case..
I think this all comes down to the TOML configuration. I don't understand this markup language, maybe others are familiar with it, but it feels like a non-typed,
schema-less, yaml like mess.. In many of the samples I'm seen there are variations like this:
Is there a type definition or data dictionary for valid entries in the TOML file? Maybe that would help, because without this we have to try and find working samples somewhere, and they are all pretty different. I don't know what "monikers" are valid and which ones aren't.
None of this explains why my routing would fail when I start using TLS, or why I can't configure more than one routing rule without breaking the others..
Each "provider" in the documentation seems to introduce its own set of configuration metadata, so any samples you find aren't specific to your context. I find tons of samples using docker, using kubernities, etc, but most aren't relavent.
So, after 2 weeks, I'm about to give up on Traefik, I can't get everything to work the way I need it to, my questions go un-answered. -- most the samples, blog posts, etc dont apply because the space is so large. I'm not using docker, I'm not using Lets encrypt, My configuration is split between TOML and service fabric.. It's really quite complex to set this up other than a simple demo.
Most Engineers can "figure stuff out" by trial and error, but it helps to have something that works in your context, as basic as it needs to be, and build on it.. I couldn't even get a working configuration for a few weeks, thats why I understand the original post here..
I don't have "working samples" for the rotuing I need to do, and no way to trouble shoot why my SSL isnt working. There isnt any support here, we all just hope somebody knows something. (Gotta love open source) Problem is most of us use different contexts so its hard to get something that works for everybody or somebody in the forum that understands your context.