envoyproxy / learnenvoy Goto Github PK

It fits OK under Getting Started, but it might make more sense as a call-out. It's probably helpful to link to from more places than just the homepage, too.

The section argues against storing routes as config, but doesn't argue particularly well for storing routes as dynamic state / data. An example might help explain what the difference is, as well as why it's better.

Due to the complexity of a lot of what we're talking about (or maybe just our writing style), many of the articles have asides or avenues for further explanation. It would help to move these asides out a call-out box, so they're not inline with the straight-line explanation.

We'd probably need code support for this, unless there's a Markdown feature I don't know about.

Examples:

• In On Your Laptop, we introduce the concept of clusters, listeners, and listener filters. These aren't obvious definitions, but defining them inline (which we currently do, in a clipped sort of way) feels like a distraction. It'd be great to pull that definition out.
• Routing and Service Discovery introduce the concept of a control plane. It's a whole topic with a great post covering it. Calling it out as further reading seems good.

On https://www.learnenvoy.io/articles/health-check.html
following config is incorrect:

health_checks:
  - timeout: 1s
    interval: 60s
    interval_jitter: 1s
    unhealthy_threshold: 3
    healthy_threshold: 3
    tcp_health_check:
      send: ""
      receive: []

it causes parse error INVALID_ARGUMENT:static_resources.clusters[1].health_checks[0].tcp_health_check.send: invalid value "" for type type.googleapis.com/envoy.api.v2.core.HealthCheck.Payload)

It's better to replace

    tcp_health_check:
      send: ""
      receive: []

with
tcp_health_check: {}

For instance, the On Your Laptop article shows snippets of a bunch of config, then talks through what the config does. We use this pattern in other articles, and I believe it would be useful to make it easier to tie bits of code to explanations.

There are some libraries like Cupper's annotated code blocks that could help with this.