Updated documentation and example configs to v3 API

[dmitri-d]

Resolves #9735

[dmitri-d]

• merged in latest changes from master

[htuch]

This is totally epic, thanks so much for taking this on, generated docs look good. I notice that version history still has v2 refs, which is what we want (no need to rewrite history); are there other files that were deliberately skipped?

Re: correctness of example fragments. I don't think it's reasonable to expect a human to manually verify the entire YAML parse of every example, but we should do a few representative ones to smoke test.

Would also like a review from @mattklein123 on the generated docs, since he generally looks at these major doc changes.

[htuch]

Did you build a list of all deprecated fields to grep for? Just curious how your script works. Can you share it in a branch or gist? It's fine if it's super-hacky, just want to get a better idea of what I should be trying to validate.

[dmitri-d]

Deprecated fields in examples were updated by hand (I did build a list of deprecated fields via grep first). I can share the script I used for updating v2 messages/fields/types/enums to v3 ones though.

[dmitri-d]

Gist with the script (pretty hacky!): https://gist.github.com/dmitri-d/e5957de963d7e51004f4fce2ba82a383

[mattklein123]

See my other comment about how this can be less manual in the future, but if there is anything we should commit for future use let's definitely do that.

[htuch]

@dmitri-d is there some place you grepped out a list of all the deprecated field names and then checked to see if any still exist in docs? I realize there could be many false positives, but this would give me confidence that we haven't missed any (dot-the-Is, cross-the-Ts).

[htuch]

For the new fragments that you wrote, did you verify they worked in some kind of test harness, e.g. that this load assignment would parse? It looks reasonable, but, would be reassuring to have some kind of machine check.

Long term we want #8837, but that's outside the scope of this PR; I'd be reassured if at least they were known to parse as valid at least once.

[dmitri-d]

I did not, agree it would be a good idea.

[htuch]

Ping on this one. I think it would be good to at least verify one example of each kind of change you've made to ensure there isn't typo/subtle failure. What you could do is take https://github.com/envoyproxy/envoy/blob/master/configs/google_com_proxy.v2.yaml and copy+paste in fragments with some surrounding context, verify it can be loaded with envoy -c. I don't think we need anything beyond that.

Is this a tractable amount of work or is it going to be too crazy?

[htuch]

https://338053-65214191-gh.circle-artifacts.com/0/generated/docs/intro/arch_overview/advanced/data_sharing_between_filters.html?highlight=per_filter_config#http-per-route-filter-configuration is an example of where per_filter_config still has untyped references. These are in text rather than code, but I think they can be spotted by grep.

[htuch]

Example configs at https://338053-65214191-gh.circle-artifacts.com/0/generated/docs/intro/arch_overview/security/ssl.html?highlight=verify_subject_alt_name still have verify_subject_alt_name and v2 references in type URLs.

[dmitri-d]

• fixed issues in the two files that @htuch found, and a bunch more.

Turns out I managed to miss a bunch of directories during the first pass.

[mattklein123]

Thanks I skimmed through and agreed this is epic. I mainly have some comments on some issues we might want to open to figure out how to make this less manual from your experience. I'm pretty fearful about doc bugs from manual editing, but without doing some of the already opened issues around config checking I think it's going to be pretty difficult. :(

Thank you so much for helping with this!

[mattklein123]

See my other comment about how this can be less manual in the future, but if there is anything we should commit for future use let's definitely do that.

[dmitri-d]

• merged in latest master

[htuch]

Thanks again for this epic PR. Modulo the typo comment and the question on how we can validate some representative sample in a bounded and small amount of time, this LGTM and is ready to go. Odds are we've missed one or two things, but we can launch-and-iterate.
/wait

[dmitri-d]

• updated with the latest master

[dmitri-d]

• verified example configurations, fixed several of them

[htuch]

LGTM, thanks! Needs master merge.

[dmitri-d]

• merged in latest master

[htuch]

LGTM, will leave this for @mattklein123 to merge in case he has any more comments.

[mattklein123]

Thank you! Let's ship and iterate.