Envoy: docs: getting started with lua config is not easy

[buchanae]

I started with Envoy today and my first goal is to get a simple Lua filter working. I hit some hurdles, so I wanted to capture some feedback:

• At first, I was looking in v2, but I learned I need v1 API config.
• I now understand where an HTTP filter goes, but it took me probably 15-20 minutes to understand how to navigate the docs to figure out where a Lua filter goes.
• The "Download" page uses "lyft/envoy:latest" which (I think) doesn't support Lua yet, so I got errors about an unrecognized filter. I switched to "envoyproxy/envoy".
• While trying to debug the version issue in the previous point, I was surprised to find that both docker hub and ./envoy --version report commit hashes, but the release notes report version names 1.5.

Ideas for improvement:

• Examples of config starting at the root for each type of entity (e.g. lua filter) would have given me a good picture of the config in one place.
• Don't use lyft:envoy
• Tag versions by name (e.g. v1.5) in addition to commit hashes
• Report both version name and commit hash in ./envoy --version

I won't be offended if this issue is closed without action. In my projects, I find it hard to know if people find my docs confusing and really appreciate any feedback on them, so I wanted to capture my experience here.

Really stoked to use Envoy! Thanks!

[mattklein123]

Thank you @buchanae! I will fix the docker image link on the website. Once we tag 1.5.0 next week we will be redoing the website to also point to docs/images of specific versions.

re: Lua itself, we will try to get some better docs on that specifically but doc PRs appreciated. Thanks!

[bndw]

@buchanae version 1.5.0 has been released and is tagged in Dockerhub at envoyproxy/envoy:v1.5.0

[buchanae]

Nice work! Thanks.

Unless you have a different idea, I think the best contribution I could make would be to add a Lua example to https://github.com/envoyproxy/envoy/tree/master/examples. I'll work on that

[mattklein123]

@buchanae that would be much appreciated (and link to from docs).

[nov1n]

@buchanae Any update on the example? I am going through the process myself, and it would be very helpful!

[buchanae]

I'm the worst. This fell off my radar. I'll take a pass at it this weekend!

[nov1n]

There's always so much to do :-) I'm looking forward to it!

[buchanae]

This is what I have so far: https://github.com/buchanae/envoy/tree/lua-proxy-example/examples/lua-proxy

It doesn't load for some reason:

docker-compose up
Starting luaproxy_web_service_1
Starting luaproxy_proxy_1
Attaching to luaproxy_web_service_1, luaproxy_proxy_1
proxy_1        | [2018-02-05 03:21:15.682][7][info][main] source/server/server.cc:157] initializing epoch 0 (hot restart version=9.200.16384.127)
proxy_1        | [2018-02-05 03:21:15.691][7][critical][main] source/server/server.cc:71] error initializing configuration '/etc/envoy.yaml': JSON at lines 0-0 does not conform to schema.
proxy_1        |  Invalid schema: #
proxy_1        |  Schema violation: additionalProperties
proxy_1        |  Offending document key: #/static_resources
luaproxy_proxy_1 exited with code 1

I have quite a bit of trouble getting Envoy config right.

[dio]

@buchanae I think the lua filter, in a .yaml (v2) config, should be something like:

          http_filters:
          - name: envoy.lua
            config:
              inline_code: |
                function envoy_on_response(response_handle)
                  response_handle:headers():add("foo", "bar")
                end
          - name: envoy.router

[nov1n]

@buchanae That really helped me out! I made some slight adjustments to your example to get it to work:: https://github.com/nov1n/envoy/tree/lua-proxy-example/examples/lua-proxy . Let me know what you think.

[argeualcantara]

Is this the same config when passing it to envoy through istio, I'm having issues, it's like istio does not recognize it as a valid file.

[mbanikazemi]

@nov1n @buchanae Thanks. Are you guys planning to push this example upstream?

[mbanikazemi]

@argeualcantara This own't work with Istio where the configuration is done dynamically. There is work in progress to add support for providing lua scripts in Istio.

[buchanae]

Are you guys planning to push this example upstream?

Sure, I'll make a PR with what I have this weekend. Haven't had much time to go further with Envoy, but I'll share what I have.

[mbanikazemi]

@buchanae Do you mind if I cleanup and submit this example? I will have you and @nov1n mentioned as co-authors in the commit message.

[buchanae]

@mbanikazemi works for me. Sorry I'm procrastinating on this, have been out of town on the weekends.

[nov1n]

@mbanikazemi Sure thing!

[buchanae]

@mbanikazemi Thanks very much for wrapping this up!