Add Proxy Upstreams to Service Definition

[banks]

This PR adds Proxy Upstream definitions to be first-class within service registrations in two separate places.

The motivation is that as we integrate Envoy and other proxies, they all need ways to express and centrally manage this configuration (i.e. in catalog not just local agent state) so it needs to become a first class part of the service definitions.

The upstreams for managed proxies can now be specified directly in the connect.proxy.upstreams stanza rather than being further nested inside the opaque map connect.proxy.config as part of the application service registration.

In addition, "unmanaged" proxies can now register themselves with Kind = "connect-proxy" and with an explicit set of Upstreams as well as some other common proxy configuration.

The full details of this are documented in the doc changes inline here.

Deprecations

This PR deprecates two things:

1. Specifying upstreams for managed proxies in the service definitions opaque config map
2. Specifying an unmanaged proxy target in the ProxyDestination field

In both cases we gracefully accept the old value for now and translate it to the new setup. We should document these as deprecated though and remove them later after 1.3 release.

Testing

It turns out this apparently simple change was a huge pain given our current baggage around chancing config structs and supporting multiple formats and legacy key translations from snake to camel case etc.

I methodically considered and added tests for all of the following cases:

• Agent Services endpoint response
• Agent Service endpoint response
• Agent Register endpoint
  • Unmanaged deprecated field
  • Unmanaged new fields
  • Managed deprecated upstreams
  • Managed new
• Agent Proxy config endpoint response
• Catalog Register
  • Unmanaged deprecated field
  • Unmanaged new fields
  • Managed deprecated upstreams
  • Managed new
• Catalog Services endpoint response
• Catalog Node endpoint response
• Catalog Service endpoint response
• API package methods for ALL of the above endpoints/cases
• Config file parsing for service/services in JSON/HCL
• Config file translations from deprecated to new fields

Even with all those tests, I still wasn't confident so I wrote an external sanity check script: https://github.com/banks/consul-upstream-config-e2e

This found a whole bunch of additional issues! For now I've left it out of our actual test suite because for each issue it did find I was able to add additional cases to the actual tests we have that covered them before fixing so I don't think it adds any benefit to include this script in the repo as it is. We will look at incorporating more cases like this though into our existing functional/e2e test suite though as I think this showed there is value for significant config changes (especially in service definitions which touch so many parts of the API and config code) to validate all the options.

Documentation

This is still TODO (!!). I will add it to this PR as a separate commit so it can be read in isolation more easily.

TODO

• Update documentation for API and service definition

[banks]

TODO:

• Responses still contain "ProxyDestination": "" for all service types but don't actually set it. Should add tests that assert we still set it at least for Kind = connect-proxy. We should probably also add omit-empty as it shows for typical services too currently.

[banks]

Documentation added along with fixes for some additional issues with API responses discovered while preparing the docs.

NOTES

• This PR depends on Rename agent/proxy package to reflect that it is limited to managed proxy processes. #4550 and Support Agent Caching for Service Discovery Results #4541
• The documentation added assumes that this will all land in 1.2.3. We'll need to review that at merge time and grep out 1.2.3 references to update.
• It's not clear if we should hold this in another branch so that we can release 1.2.3 without it. It doesn't hurt to do it earlier but it's a lot of changes to add to that point release without any immediately useful outcome until we also build the Envoy integration which will likely not land until 1.2.4 @pearkes any thoughts?

[banks]

Docs changes alone are: 26e1a6e and may be a good place to start. @pearkes any input on that welcome too. It at least explains (hopefully!) what the changes are and what the new UX will look like which might be good context for reviewing any of the code.

I know this is kinda big but I couldn't really see a way of breaking it up much more without being in an inconsistent and untestable state in the interim.