Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: cluster peering documentation improvements #20878

Draft
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

boruszak
Copy link
Contributor

@boruszak boruszak commented Mar 19, 2024

Description

This PR was created in response to feedback from Support. They reported some difficulty determining the required steps to set up cluster peering connections. Edits have been made to streamline this information and avoid endless link loops between pages.

This PR also suggests a naming best practice for cluster peers. The <datacenter>-<partition> format creates a human-readable configuration pattern that simplifies peer management.

Deployment previews

VMs:

K8s:

PR Checklist

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

@github-actions github-actions bot added the type/docs Documentation needs to be created/updated/clarified label Mar 19, 2024
@boruszak boruszak added pr/no-changelog PR does not need a corresponding .changelog entry backport-inactive/1.17 This release series is no longer active. Use backport/ent/1.17. backport/1.18 labels Mar 19, 2024
Copy link
Contributor

@krastin krastin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to draw the attention on whether you have considered explicitly calling out the admin partition parameter; the rest is just tiny typos. The cluster peering docs are looking great!

</Tab>
<Tab heading="HTTP API" group="api">

1. Create a configuration entry and specify the `Kind` as `"exported-services"`. The following example exports services between `default` admin partitions. To export services between non-default admin partitions, you must include a `"Partition"` filed that contains the name of the local partition the configuration entry applies to.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we explicitly include the Partition parameter in here and all related sections? I believe it's better safe than sorry but i'm not sure if Consul CE will complain about the parameter.

</Tab>
<Tab heading="HTTP API" group="api">

1. Create a configuration entry and specify the `Kind` as `"exported-services"`. The following example exports services between `default` admin partitions. To export services between non-default admin partitions, you must include a `"Partition"` filed that contains the name of the local partition the configuration entry applies to.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Create a configuration entry and specify the `Kind` as `"exported-services"`. The following example exports services between `default` admin partitions. To export services between non-default admin partitions, you must include a `"Partition"` filed that contains the name of the local partition the configuration entry applies to.
1. Create a configuration entry and specify the `Kind` as `"exported-services"`. The following example exports services between `default` admin partitions. To export services between non-default admin partitions, you must include a `"Partition"` field that contains the name of the local partition the configuration entry applies to.

@@ -323,7 +276,7 @@ Before you can call services from peered clusters, you must set service intentio

</CodeBlockConfig>

1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces.
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups). The following example highlights the annotation that allows the workload to join the mesh and dial the upstream service using the correct DNS name. For more information about formatting a DNS name that includes namespaces or parrtitions, refer to [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups). The following example highlights the annotation that allows the workload to join the mesh and dial the upstream service using the correct DNS name. For more information about formatting a DNS name that includes namespaces or parrtitions, refer to [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise).
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups). The following example highlights the annotation that allows the workload to join the mesh and dial the upstream service using the correct DNS name. For more information about formatting a DNS name that includes namespaces or partitions, refer to [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise).

@boruszak boruszak removed the backport-inactive/1.17 This release series is no longer active. Use backport/ent/1.17. label May 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
pr/no-changelog PR does not need a corresponding .changelog entry type/docs Documentation needs to be created/updated/clarified
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants