Documentation improvement suggestion

Traefik Traefik v2 (latest)
1

Traefik documentation is full of configuration examples but none of them is complete, only partial files. This makes it really hard to get a working configuration.

It would be really helpful to have at least one complete working example for every topic in the documentation. Please consider it.

2 Likes
2

Hello, thank you for your suggestion.

It may be not feasible to maintain a full set of complete examples for all possible use cases in the official documentation. We are considering setting a “contrib” space where users could provide working config and hints, which would be closer to real life needs, and supported by community.

What do you think ?

3

Hi Marc,

I’m sure it’s “not feasible to maintain a full set of complete examples for all possible use cases in the official documentation”. That’s not what I’m asking for.

What I’m asking is “one full complete working example per section”, or, to put in more objective terms, 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. That would be a great improvement in my point of view.

About the contrib space, I think it’s a great idea. It can eventually even compensate for the lack of working examples in traefik’s documentation but I really believe not having working examples in the official documentation is a great mistake.

1 Like
4

What I'd want is a document section that is tied to source code for integration tests to make sure that the what is documented actually runs on every build.

5

I am facing the same issue and totally agree with your proposal and last statements (We need simple working example in the documentation).
Everytime i am trying to do something in that wonderdul application my workflow is the following

  • read specific documentation part (ie concept, routers, services,middlewares) that sometime contains example
  • read the reference
  • try to find example in github, stackoverflow and there in Traefik forum of course

I loose an incredible amout of precious time...

I understand that maintaining an accurate documentation is a lot of work and that Traefik is an open source application... but that application is wonderdul and doesn’t have (yet) the documentation it deserves.

Best regards,

Alexandre from France

6

I have had a similar issue. For example, this config was a great start for me to allow me to start using Traefik for the first time: Docker swarm not redirecting to site with Traefik v2

I think having started with that I would have saved hours.

Thanks for the project!

7

After 2 days to tried to switch from v1.7 to v2.x, read all the documentations of traefik website, search a lots on forums and issues, I've finally make it working with my limited knownledges in kubernetes. So I could may be help by posting here my configuration files.

Before continue, I precise it's may be not the perfect way to do it, and I still have some strange errors in traefik logs, but all seems to works. Any suggestions are welcome !:slight_smile:

I've done a little fork of https://github.com/containous/traefik-helm-chart with some improvements ( PVC, ForwaredHeaders / ProxyProtocol options, ACME configuration ... )

Remove old traefik configuration.

$ git clone https://github.com/nox-digital/traefik-helm-chart.git
$ cp traefik-helm-chart/values.yaml my.values.yaml

Update your my.values.yaml file ( at least ACME email address, default CAServer is staging )

$ helm install --name traefik --namespace kube-system --values my.values.yaml traefik-helm-chart

Wait until the IP LoadBalancer address have been created (5 minutes for me):
$ watch kubectl -n kube-system get all

Then, for your applications, here is a sample example for ingress-routes.yaml file:

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: {{ template "my-app.fullname" . }}-route-http
  labels:
    app: {{ template "my-app.fullname" . }}-{{ .Values.http.name }}
    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
    release: {{ .Release.Name }}
    heritage: {{ .Release.Service }}
spec:
  entrypoints:
    - web
  routes:
  - match: Host(`{{ .Values.http.subdomain }}hostname.com`, `{{ .Values.http.subdomain }}hostname2.com`, `{{ .Values.http.subdomain }}hostname3.com`, `{{ .Values.http.subdomain }}hostname4.com`)
    kind: Rule
    services:
    - name: {{ template "my-app.fullname" . }}-{{ .Values.http.name }}
      port: 80

---

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: {{ template "my-app.fullname" . }}-route-https
  labels:
    app: {{ template "my-app.fullname" . }}-{{ .Values.http.name }}
    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
    release: {{ .Release.Name }}
    heritage: {{ .Release.Service }}
spec:
  entrypoints:
    - websecure
  routes:
  - match: Host(`{{ .Values.http.subdomain }}hostname.com`, `{{ .Values.http.subdomain }}hostname2.com`, `{{ .Values.http.subdomain }}hostname3.com`, `{{ .Values.http.subdomain }}hostname4.com`)
    kind: Rule
    services:
    - name: {{ template "my-app.fullname" . }}-{{ .Values.http.name }}
      port: 80
  tls:
    options:
      name: ""
    certResolver: default

On your service, I've set port: 80, targetPort: 8080 (because my application/nginx listen on port 8080)

Hope this could help.