Figure out ownership of learn materials or delete

[Skarlso]

Following the tutorial here: https://www.envoyproxy.io/learn/ssl

I've got this error:

front-envoy_1  | [2020-01-12 07:54:22.719][6][critical][main] [source/server/server.cc:94] error initializing configuration '/etc/front-envoy.yaml': Protobuf message (type envoy.config.bootstrap.v3alpha.Bootstrap reason INVALID_ARGUMENT:(static_resources.listeners[0].filter_chains[1]) tls_context: Cannot find field.) has unknown fields
front-envoy_1  | [2020-01-12 07:54:22.719][6][info][main] [source/server/server.cc:595] exiting
front-envoy_1  | Protobuf message (type envoy.config.bootstrap.v3alpha.Bootstrap reason INVALID_ARGUMENT:(static_resources.listeners[0].filter_chains[1]) tls_context: Cannot find field.) has unknown fields

With this settings on the envoy front-end:

    - tls_context:
      common_tls_context:
        tls_certificates:
          - certificate_chain:
              filename: "/etc/listener.crt"
            private_key:
              filename: "/etc/listener.key"

[htuch]

@Skarlso what is the full bootstrap you are using? Looks like Envoy is viewing this as a v3 YAML, where tls_context is deprecated in favor of TLS transport extension configuration.

[htuch]

@caniszczyk @mattklein123 who is responsible for keeping https://www.envoyproxy.io/learn/ssl etc. up-to-date going forward given that Turbine Labs are no longer around?

[Skarlso]

Hi @htuch! Thank you for jumping in. It turns out that I didn't indent it correctly. :( It was under filter_chains instead of filters. I switched to the new form of doing this:

      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.api.v2.auth.DownstreamTlsContext
          common_tls_context:
            tls_certificates:
            - certificate_chain:
                filename: "/etc/example-com.crt"
              private_key:
                filename: "/etc/example-com.key"

Since it say tls_context is deprecated anyways. :)

But I'll keep an eye out for things. Also, thank you for your help and sorry, I didn't close this issue before hand. I think I can consider it resolved. :)

[htuch]

Yeah, so just to fully explain what happened here:

1. We had a v2 bootstrap which used a deprecated feature. This config had a whitespace error leading to it being invalid.
2. Envoy tried to parse as v2, it probably failed due to this error.
3. Envoy tried to reparse as v3. I think it failed again, but due to the removed field, rather than the whitespace error. Hard to tell without the precise bootstrap.

The reason I'm listing the steps above is that v3 is relatively new, and I want to make sure we understand the UX around failing config load.

[Skarlso]

Thanks! :)

[mattklein123]

@caniszczyk @mattklein123 who is responsible for keeping https://www.envoyproxy.io/learn/ssl etc. up-to-date going forward given that Turbine Labs are no longer around?

The content is unowned. cc @lucperkins as it would be really nice if we could get some help with this.

[lucperkins]

@mattklein123 What specifically are you requesting? New ownership for those docs?

[mattklein123]

@mattklein123 What specifically are you requesting? New ownership for those docs?

I'm suggesting what I have suggested for a long time: we need some part-time tech writing resources to help fix these type of issues and keep things up to date.

[svet-b]

This is not strictly speaking the same issue, but it's in line with the direction of the current discussion, so I figured I'd comment rather than opening a new issue: while the example currently at https://www.envoyproxy.io/learn/ssl works with Envoy 1.14.1, the logs are peppered with deprecation warnings, as I guess the config in the tutorial is showing its age. I had a go at updating the example config based what I found in the reference docs (e.g. https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/ssl as well as the docs for some of the other parameters that are now deprecated), but ultimately managed to create something non-functional. Needless to say, I'm pretty new to Envoy - though not to setting up reverse proxies in general.

I appreciate that the velocity of Envoy's codebase evolution is quite rapid, and some aspects of the documentation are bound to be outdated. That said, since TLS termination of an HTTP connection is such a common use case for a reverse proxy, it would be great to have a reliable minimal example for how to set this up. I'm happy to share what I came up, and/or contribute to this in any other suitable way.

Thank you for developing a great product and sharing it with the open source community!

[mattklein123]

Unfortunately the learn materials on the website are unmaintained and we don't have any ability currently to run config checks on that material like we do on the primary docs site.

I think we either have to find an owner of this material or we need to delete it. cc @envoyproxy/maintainers

[moderation]

My $0.02 is that it's going to be a huge amount of work to update this content for the current API and releases. It will then be a huge amount of work to continue to update the content going forward. In the likely event that there won't be someone willing to take this on I'm in favor of deleting.

[mattklein123]

I agree that we should just delete it. I will wait for others to chime in and then just do it next week if no one comments.

[jmarantz]

deletion sgtm

On Tue, May 12, 2020 at 5:42 PM Matt Klein notifications@github.com wrote:

I agree that we should just delete it. I will wait for others to chime in and then just do it next week if no one comments.

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/envoyproxy/envoy/issues/9662#issuecomment-627614103, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAO2IPKF4JBHZ4RB6BVJZF3RRG7FXANCNFSM4KFWJ4AQ .

[htuch]

@mattklein123 deletion unless CNCF will fund development. I think this is the kind of thing that needs a dedicated tech writer to do well ( that's how we got these in the first place, Turbine Labs made some really nice contribution there), it's hard to see how to crowd source updating and maintaining these.

[mattklein123]

cc @caniszczyk ^ for FYI. I think we would be happy to have a tech writer maintain these docs but from a project maintainer perspective we can't do it. Will delete next week in the interim.

[lucperkins]

@mattklein123 If you’d like to request resources for this, I’d recommend submitting a help desk ticket.

[mattklein123]

@mattklein123 If you’d like to request resources for this, I’d recommend submitting a help desk ticket.

This is a large request for a long term tech writer. These docs will need to be continuously updated. Whenever I have made such a request in the past it has gone nowhere useful. If you believe that will be different I will file the request but I would rather not waste time if there is a very low chance of it happening.

[ggreenway]

I looked through some of those docs today, and there's some good theory content that is still accurate.

Instead of deleting, could we put a banner at the top of each page saying that the docs aren't maintained and that specific config snippets are probably outdated, but the high-level ideas may still be useful?

[mattklein123]

Instead of deleting, could we put a banner at the top of each page saying that the docs aren't maintained and that specific config snippets are probably outdated, but the high-level ideas may still be useful?

We could do this. One option would be to delete the configs and leave the concepts. My fear is that it's a pretty bad look for the project to have a banner like this that says the docs are out of date and we know it.

[ggreenway]

My fear is that it's a pretty bad look for the project to have a banner like this that says the docs are out of date and we know it.

Yeah, that's a good point. Probably not a good idea.

[mattklein123]

Before we delete I'm going to see if I can get someone to sponsor this content. I will report back.

[w00519772]

@Skarlso, are you able to post your front-envoy.yaml? I have spent a long time trying to get the code here working: https://www.envoyproxy.io/learn/ssl. I realise now that it is out of date after visiting this webpage.

I am using the project here: https://github.com/envoyproxy/envoy/tree/master/examples/front-proxy. Just need the adapted: front-envoy.yaml

[Skarlso]

Will do shortly

On Fri, 22 May 2020, 14:47 w00519772, notifications@github.com wrote:

@Skarlso https://github.com/Skarlso, are you able to post your front-envoy.yaml? I have spent a long time trying to get the code here working: https://www.envoyproxy.io/learn/ssl. I realise now that it is out of date after visiting this webpage.

I am using the project here: https://github.com/envoyproxy/envoy/tree/master/examples/front-proxy. Just need the adapted: front-envoy.yaml

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/envoyproxy/envoy/issues/9662#issuecomment-632673348, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABMUQVFZ7Q743B6RIJC6LLRSZX6NANCNFSM4KFWJ4AQ .

[zufardhiyaulhaq]

any update for this? the docs seems not working.

[mattklein123]

I haven't had any luck yet with this. I'm going to delete this content and we can bring it back when we find someone.

[mattklein123]

Opened https://github.com/envoyproxy/envoyproxy.github.io/pull/163 to delete the content for now, but will leave this open to track finding a new owner.