Add full example of proper IngressRouteTCP usage

[theAkito]

Do you want to request a feature or report a bug?

Feature

What did you expect to see?

A full example of how to use Traefik's IngressRouteTCP.

Please add a full working example on how to properly use the IngressRouteTCP object.

Original Discussion

[hyacin75]

I too spent a ridiculous amount of time trying to get this to work using everything I could find online until I wound up very, very frustrated, and here.

Agree 100% that better documentation and examples are required, ASAP.

[ThaSami]

Trying to route TCP into cassandra cluster. and create a domain that is responsible to receive the traffic and route it... the documentation is not helpful at all!

[ldez]

We can understand the frustration. But, for all the users in this issue, please try to be constructive.

Traefik is free and open-source, anyone can contribute to improving documentation.

Remember the basic OSS mantra:

Ask not what the project can do for you - ask what you can do for the project.

https://github.com/containous/traefik/blob/master/CODE_OF_CONDUCT.md

[theAkito]

please try to be constructive.

Could you please point us to a single non-constructive quote?

By now, I am extremely appalled and surprised about how many times parts of the maintainer crew is chiming in with unhelpful and partially off-topic comments into this discussion, instead of taking 30 minutes of their time to help so many people sitting for hours and hours and hours on this issue.

It is especially ironic and taunting to tell us to improve the documentation, when you clearly know, that we cannot do that, because we need the documentation to even get what needs to be done, in the first place.

I simply cannot understand what the point is to put the time and effort in developing and releasing a feature, that nobody, except the Traefik crew involved in the development of this feature, is able to use.

[ldez]

@theAkito my comment is not about your issue or your issue description, it's a global remark: issues talking about improved documentation are often an aggressive place because of the frustration some feel.

Anyone can contribute: when people have an issue, some other people can answer and contribute.

[hyacin75]

We can understand the frustration. But, for all the users in this issue, please try to be constructive.

Traefik is free and open-source, anyone can contribute to improving documentation.

Remember the basic OSS mantra:

Ask not what the project can do for you - ask what you can do for the project.

https://github.com/containous/traefik/blob/master/CODE_OF_CONDUCT.md

Yeah, but, if we don't understand how it works, how could we possibly create documentation?

[ldez]

Anyone can contribute: when people have an issue, some other people can answer and contribute.

[dtomcej]

To expand on what @ldez said previously:

Opening an issue and saying that the "Documentation doesn't work for you" doesn't provide us with anything to help you with.

Here is a constructive example that hopefully shows what we mean:

I want to route traffic to my web app on kubernetes, and I want to use the CRDs to do it

I have followed the guide here: (url), and got to the point of the guide: (point)
 but I cannot seem to figure out where to go next, or how to get it working.

Here is my setup, and here what I am trying to do.

That sort of feedback gives us:

• Context for your issue
• Some basis for what you have tried
• What you are trying to accomplish

That kind of feedback is constructive, and can help the project, even if you don't provide anything more than that. Someone else who is more familiar with the project can use that information and improve the documentation, or ask for more information.

Generic "The documentation sucks" comments and "thumbs down" comments do not assist.

I hope that gives a little more insight into what we are hoping you can provide.

[theAkito]

@dtomcej

Please read up on the tons of information provided in the original thread. There have been enough examples that even follow the schematic you show here, precisely.

Generic "The documentation sucks" comments and "thumbs down" comments do not assist.

Precisely. Marking things as off-topic or hiding comments in the original thread, do not help, at all. It would be nice, if a full example would be provided, instead of just ignoring the issue for such a long time and trying to hide people's experience with this issue, instead of trying to solve the issue.

[ldez]

It's possible to find some inspiration in our e2e tests:

• https://github.com/traefik/traefik/search?q=%22kind%3A+IngressRouteTCP%22&unscoped_q=%22kind%3A+IngressRouteTCP%22

[mingdaoy]

Hi, I'd like to work on this task

[gcsfred2]

Terrible documentation. Suffering to setup Traefik and IngressRouteTCP in particular.

[tfny]

Hey, y'all. We are looking at this issue with an eye towards improving the docs.

Unfortunately, we are not sure that our improvements will fix /your/ specific issues as it is quite likely you all noticed a different weak point.

Would you mind taking a moment to tell us the top one to three areas you got lost in? It can be that the language is too confusing, or that there is an area that needs a lot more elaboration. This will help us get a fix ready as soon as we can.

[hyacin75]

iirc for me it was simply the lack of any example. Most docs I use I go straight to the example and just adapt it to what I am doing - if I have special requirements or it is in any way confusing or ambiguous, only then do I read the text around the example. But a solid working example that one can copy and paste, then just update the specifics - port number or destination service or whatever - would have had me up and running almost instantly.

[rtribotte]

Hello @hyacin75,

Thanks for your feedback!

Here is this example (look for the section "Declaring an IngressRouteTCP"). Can you please tell us what is wrong with it?

[hyacin75]

Hello @hyacin75,

Thanks for your feedback!

Here is this example (look for the section "Declaring an IngressRouteTCP"). Can you please tell us what is wrong with it?

Looks good to me! I don't think it existed back when we had this problem ... and my use case is long since solved with another product and forgotten, so no way for me to try it out I'm afraid (without rolling a whole other cluster and installing Traefik etc., etc.,, which I'm not will to do) ... but it certainly looks like if I was trying to do the same thing today and had this documentation at my disposal, I'd have no issue doing it!

[theAkito]

Greetings @tfny & @rtribotte,

I just found the time now, to chime in with my 2 cents, as well. Thank you for putting effort in improving the situation and trying to solve this issue, instead of waiving it away, as if it were a non-issue, as it was done previously.

I am kind of in pretty much the same situation as @hyacin75, right now. This happened a really long time ago. We stopped using Traefik and switched to a different product, which solved our issue in a different way.

So, I guess the tally counter starts with 2 people going away from Traefik, because the documentation was lacking...

Anyway, when I started this issue, we already had the example @rtribotte just provided at our disposal.

I can only remember bits and peaces of what was wrong with it. I cannot remember what exactly was wrong with it, except I would try to solve an issue from 2 years ago, once again. (If I will try to use this feature again, I will certainly come back to this issue and improve/extend my feedback.)

What I remember, when I open the link to the documentation:

1. Literally the first thing I remembered, was that several things in that reference sounded similar and I had no idea to find out which is which. It's like, they were almost named the same and the explanation next to it did not solve the issue, of what the heck that thing is supposed to be. Obviously, I cannot remember which option it was exactly, but there were a couple of ambiguous options, which raised too many question marks above my head.
2. The second thing, that comes to my mind: It's not a real example. It's a reference with very short explanations of what is happening. Good for you. Good for the developers at Traefik Labs. Bad for users, who don't know how it is programmed or works internally. For us, as simple users (who might not even be developers, specifically), it's hard to understand what those short sentences mean. Sure, some basic stuff can be looked up, if people don't know, but some are so specific to how Traefik names it, you cannot look it up. Traefik has to explain it in a better, more user-friendly way. We don't need a reference for Traefik Labs developers. We need documentation for users.
3. Just to test, I randomly selected one thing, I wanted explanation of:

middlewares[n].name	Defines the MiddlewareTCP name

Okay. I click on the MiddlewareTCP keyword. This is what I get:

MiddlewareTCP¶

MiddlewareTCP is the CRD implementation of a Traefik TCP middleware.

Register the MiddlewareTCP kind in the Kubernetes cluster before creating MiddlewareTCP objects or referencing TCP middlewares in the IngressRouteTCP objects.

And.... what does that mean? What is it? What does it do? How does it work? What do I need it for? Why does it exist? Is it mandatory? Is it optional?

Okay. One more chance. I click on the Traefik TCP middleware keyword.

And... Nothing. It's not even an explanation of what this generally is, not to mention what specifically the TCP middleware in case of an IngressRouteTCP is supposed to be. Like, how do you expect anyone to understand anything, when this is clearly just a barebones reference for developers at Traefik Labs. It's not documentation. Literally just a barebones reference.

4. Same with the other stuff.

tls.certResolver	Defines the reference to a CertResolver

Go through the links, just as in step 3.... and this is where we arrive. This is literally just 6 lines of YAML. and a single sentence saying something about certResolver. That's it. Again, just a barebones reference. That's not documentation. By now, I don't even know what the hell anything means, because everything is Traefik-specific and not generic or generally known. Good (enough) for Traefik Labs employees, bad the rest of us.

5. Now, I notice the thing I remember best. The immense and seemingly never-ending frustration. Just looking up these two examples already rekindled the flames of hate and disgust toward this documentation barebones reference. I do not wish to delve deeper into this hole of meaningless non-sense, from a perspective of a simple user, not working at Traefik Labs.

I am reminded of the (in)famous introduction to the game The Elder Scrolls V: Skyrim.

https://youtu.be/mpddXJJLhPY?t=337

Just reading this reference, you have what feels like 100 configuration options available, which are specific to Traefik only. It's not general. Sure, there are also some general options, like the proxy ones and the domain ones. Sure. But I need to know the Traefik stuff, to be able to use the general stuff, in the first place. I can't use one without the other, without understanding the whole picture, i.e. also understanding the Traefik specific terminology and CRDs, etc.

I guess, that's so much I can give, for now. If I will have anything to add, I will provide the feedback, as I want to contribute to going a step in the right direction.

All that said, I again thank you for the change of attitude and actually addressing the issue. It's great, that this issue is finally addressed properly and feedback is welcome. Thank you!

[gcsfred2]

@tfny I'm a beginner with Traefik and k8s, even though I'm an experienced developer. Allow me to give some other examples of problems with the documentation.

https://doc.traefik.io/traefik/observability/access-logs/ To enable the access logs (File (YAML)): accessLog: {}

I don't know in what file this goes. I don't know if this is a fragment of YAML. I have a lot of YAML files in my helm chart. Can I just put it anywhere? This same problem of "context" happens throughout the documentation in many YAML examples.

https://doc.traefik.io/traefik/https/tls/

 [](https://doc.traefik.io/traefik/https/tls/#certificates-definition)[](https://doc.traefik.io/traefik/https/tls/#automated)Certificates Definition
Automated
See the [Let's Encrypt](https://doc.traefik.io/traefik/https/acme/) page.

The sections are Overview, TLS and Let's Encrypt. The Automated paragraph within TLS, however, links to Let's Encrypt. It's confusing. The text gives the impression that these are separate but also related.

I was working to get TLS working with Traefik the past week. It was supposed to be a 'simple' case of enabling it for an existing HTTP service. It took me a very long time to get it to work. The documentation seems very detailed, but I needed something more common and simpler. What helped me more were older yaml in another repository from my colleague.

I miss a troubleshooting page.

GF

[tfny]

You guys, this is really great constructive feedback, I super appreciate it. We have already started the process of moving forward to get stop-gap information in place while we update the docs more widely.

I am also taking your feedback and parsing it so that we can apply it more broadly as well. Knowing what specifically made things difficult is a great gift.

I put together a survey for the community that we are currently running, the first half is about the features you will want going forward, the second half is about how to improve community experience and it only takes 5 min. If you are interested in sharing broader feedback, I would love it. https://www.surveymonkey.com/r/RCYP525

[mpl]

@tfny I'm a beginner with Traefik and k8s, even though I'm an experienced developer. Allow me to give some other examples of problems with the documentation.

https://doc.traefik.io/traefik/observability/access-logs/ To enable the access logs (File (YAML)): accessLog: {}

I don't know in what file this goes. I don't know if this is a fragment of YAML. I have a lot of YAML files in my helm chart. Can I just put it anywhere? This same problem of "context" happens throughout the documentation in many YAML examples.

On that specific problem, I think we've tried to be explicit about the "depth" of elements at least when needed. i.e. if an element is alone, and seems to be top-level, it is indeed implicitly top-level. If it was the child of another element, or a sub-section, we would have tried to specify as much. One little help we think we could do on that matter, is to add a little bit more of an example for each element to indicate more context. i.e. in that accesslog case, you would see a small snippet of configuration example on top of the page, where accesslog would be along other configuration elements, so you have additional hints of the depth of accesslog relative to other config elements.

[traefiker]

Hi! I'm Træfiker :robot: the bot in charge of tidying up the issues.

I have to close this one because of its lack of activity :disappointed:

Feel free to re-open it or join our Community Forum.

[pnowy]

If you are using the helm chart in the values to make it work you have to (postgres example):

Add

ports:
  pg:
    port: 5432
    expose: true
    exposedPort: 5432
    protocol: TCP
additionalArguments:
- "--entrypoints.pg.address=:5432/tcp"

And later add IngressRouteTCP:

apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: pg-ingress-route-tcp
spec:
  entryPoints:
    - pg
  routes:
    # currently Traefik v2 does not support SNI for Postgres, feature will be available from 3.X with TLS
    # PR with changes https://github.com/traefik/traefik/pull/9377
    - match: HostSNI(`*`)
      services:
        - name: my-cluster-ip-db-service
          port: 5432

[eumel8]

for me it was helpful to understand that I can use IngressRouteTCP instead of Ingress, i.e. expose KubeAPI on my vcluster:

helm -n vc1 upgrade vc1 --create-namespace --version 0.15.7 oci://mtr.devops.telekom.de/caas/charts/vcluster

configure vc1.example.com to Traefik Loadbalancer endpoint and apply the IngressRouteTCP

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRouteTCP
metadata:
  name: vc1
  namespace: vc1
spec:
  entryPoints:
  - websecure
  routes:
  - match: HostSNI(`vc1.example.com`)
    services:
    - name: vc1
      port: 443
  tls:
    passthrough: true

[cornfeedhobo]

Honestly, this was so bad, and the responses from maintainers have been so terrible, I finally ended up ditching Traefik for Cilium, and it's AMAZING! It's so nice to have a fully cohesive stack with introspection throughout all the layers.

I'm probably not going back to traefik unless something big changes. Cilium is way better.