docs: connect-service-upstreams annotation fixes

[boruszak]

Description

Several issues in the description for using the consul.hashicorp.com/connect-service-upstreams annotation were creating confusion. These issues included broken links, unexplained terms, and incorectly formatted nested lists.

These edits add clarity to the description, and are especially invested in making it easier to locate syntax for formatting services when using cluster peering.

Links

Direct link to content in deployment preview

PR Checklist

• updated test coverage
• external facing docs updated
• appropriate backport labels added
• not a security concern

[trujillo-adam]

I left a few minor suggestions that you can take or leave. BTW, I think this is OK for now, but we will probably want to replace this information with links to the appropriate DNS section for when we finish reorganizing that content so that we aren't embedding usage information into the reference.

[jkirschner-hashicorp]

Hi @boruszak,

Thanks for cleaning this up! It's much easier to follow now. I have a few suggestions to enhance accuracy and steer people towards the labeled format.

[jkirschner-hashicorp]

Move this above the Unlabeled section

[jkirschner-hashicorp]

but we will probably want to replace this information with links to the appropriate DNS section

My understanding is that upstream annotations have nothing to do with Consul DNS, though there are similarities in the syntax between labeled annotations and Consul DNS lookup suffixes. So I don't think there's a need to revisit this content after the DNS docs updates are made.

[boruszak]

@jkirschner-hashicorp: your comment was in a conversation that I resolved, but I wanted to address it explicitly as well:

Adam and I just discussed how we treat versions with versioned docs, and whether we want to change references as we find them or wait until we can address the pages as a whole. There's still some questions to resolve around how we reference versions, so for the sake of tracking work and technical accuracy, we're going to leave references to previous versions (esp. reference to versions older than v1.8, which aren't selectable for versioned docs) and address them at a later point.