mirror of https://github.com/status-im/consul.git
295 lines
15 KiB
Plaintext
295 lines
15 KiB
Plaintext
---
|
||
page_title: Create sameness groups
|
||
description: |-
|
||
Learn how to create sameness groups between partitions and cluster peers on Kubernetes so that Consul can identify instances of the same service across partitions and datacenters.
|
||
---
|
||
|
||
# Create sameness groups on Kubernetes
|
||
|
||
This topic describes how to create a sameness group, which designates a set of admin partitions as functionally identical in a Consul deployment running Kubernetes. Adding an admin partition to a sameness group enables Consul to recognize services registered to remote partitions with cluster peering connections as instances of the same service when they share a name and Consul namespace.
|
||
|
||
For information about configuring a failover strategy using sameness groups, refer to [Failover with sameness groups](/consul/docs/connect/manage-traffic/failover/sameness).
|
||
|
||
## Overview
|
||
|
||
Sameness groups are a user-defined set of partitions with identical configurations, includingcustom resource definitions (CRDs) for service and proxy defaults. Partitions on separate clusters should have an established cluster peering connection in order to recognize each other.
|
||
|
||
To create and use sameness groups in your network, complete the following steps:
|
||
|
||
- **Create sameness group custom resource definitions (CRDs) for each member of the group**. For each partition that you want to include in the sameness group, you must write and apply a sameness group CRD that defines the group’s members from that partition’s perspective. Refer to the [sameness group configuration entry reference](/consul/docs/connect/config-entries/sameness-group) for details on configuration hierarchy, default values, and specifications.
|
||
- **Export services to members of the sameness group**. You must write and apply an exported services CRD that makes the partition’s services available to other members of the group. Refer to [exported services configuration entry reference](/consul/docs/connect/config-entries/exported-services) for additional specification information.
|
||
- **Create service intentions for each member of the sameness group**. For each partition that you want to include in the sameness group, you must write and apply service intentions CRDs to authorize traffic to your services from all members of the group. Refer to the [service intentions configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for additional specification information.
|
||
|
||
## Requirements
|
||
|
||
- All datacenters where you want to create sameness groups must run Consul v1.16 or later. Refer to [upgrade instructions](/consul/docs/k8s/upgrade) for more information about how to upgrade your deployment.
|
||
- A [Consul Enterprise license](/consul/docs/enterprise/license/overview) is required.
|
||
|
||
### Before you begin
|
||
|
||
Before creating a sameness group, take the following actions to prepare your network:
|
||
|
||
#### Check Consul namespaces and service naming conventions
|
||
|
||
Sameness groups are defined at the partition level. Consul assumes all partitions in the group have identical configurations, including identical service names and identical Consul namespaces. This behavior occurs even when two partitions in the group contain functionally different services that share a common name and namespace. For example, if distinct services both named `api` were registered to different members of a sameness group, it could lead to errors because requests may be sent to the incorrect service.
|
||
|
||
To prevent errors, check the names of the services deployed to your network and the namespaces they are deployed in. Pay particular attention to the default namespace to confirm that services have unique names. If different services share a name, you should either change one of the service’s names or deploy one of the services to a different namespace.
|
||
|
||
#### Deploy mesh gateways for each partition
|
||
|
||
Mesh gateways are required for cluster peering connections and recommended to secure cross-partition traffic in a single datacenter. Therefore, we recommend securing your network, and especially your production environment, by deploying mesh gateways to each datacenter. Refer to [mesh gateways specifications](/consul/docs/k8s/connect/cluster-peering/tech-specs#mesh-gateway-specifications) for more information about configuring mesh gateways.
|
||
|
||
#### Establish cluster peering relationships between remote partitions
|
||
|
||
You must establish connections with cluster peers before you can create a sameness group that includes them. A cluster peering connection exists between two admin partitions in different datacenters, and each connection between two partitions must be established separately with each peer. Refer to [establish cluster peering connections](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering) for step-by-step instructions.
|
||
|
||
You can establish and manage cluster peering relationships between all of your self-managed clusters using [HCP Consul Central](/hcp/docs/consul/concepts/consul-central). For more information, refer to [cluster peering global view](/hcp/docs/consul/monitor/consul-central/global-views#cluster-peering) in the HCP documentation.
|
||
|
||
To establish cluster peering connections and define a group as part of the same workflow, follow instructions up to [Export services between clusters](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering#export-services-between-clusters). You can use the same exported services and service intention configuration entries to establish the cluster peering connection and create the sameness group.
|
||
|
||
## Create a sameness group
|
||
|
||
To create a sameness group, you must write and apply a set of three CRDs for each partition that is a member of the group:
|
||
|
||
- Sameness group CRDs: Define the sameness group from each partition’s perspective.
|
||
- Exported services CRDs: Make services available to other partitions in the group.
|
||
- Service intentions CRDs: Authorize traffic between services across partitions.
|
||
|
||
### Define the sameness group from each partition’s perspective
|
||
|
||
To define a sameness group for a partition, create a [sameness group CRD](/consul/docs/connect/config-entries/sameness-group) that describes the partitions and cluster peers that are part of the group. Typically, this order follows this pattern:
|
||
|
||
1. The local partition
|
||
1. Other partitions in the same datacenter
|
||
1. Partitions with established cluster peering relationships
|
||
|
||
If you want all services to failover to other instances in the sameness group by default, set `spec.defaultForFailover=true` and list the group members in the order you want to use in a failover scenario. Refer to [failover with sameness groups](/consul/docs/connect/manage-traffic/failover/sameness) for more information.
|
||
|
||
Be aware that the sameness group CRDs are different for each partition. The following example demonstrates how to format three different CRDs for three partitions that are part of the sameness group `product-group` when Partition 1 and Partition 2 are in DC1, and the third partition is Partition 1 in DC2:
|
||
|
||
<CodeTabs tabs={[ "dc1-partition-1", "dc1-partition-2", "dc2-partition-1" ]}>
|
||
|
||
<CodeBlockConfig filename="product-group.yaml" hideClipboard lineNumbers highlight="4,8-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: SamenessGroup
|
||
metadata:
|
||
name: product-group
|
||
spec:
|
||
defaultForFailover: true
|
||
members:
|
||
- partition: partition-1
|
||
- partition: partition-2
|
||
- peer: dc2-partition-1
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig filename="product-group.yaml" hideClipboard lineNumbers highlight="4,8-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: SamenessGroup
|
||
metadata:
|
||
name: product-group
|
||
spec:
|
||
defaultForFailover: true
|
||
members:
|
||
- partition: partition-2
|
||
- partition: partition-1
|
||
- peer: dc2-partition-1
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig filename="product-group.yaml" hideClipboard lineNumbers highlight="4,8-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: SamenessGroup
|
||
metadata:
|
||
name: product-group
|
||
spec:
|
||
defaultForFailover: true
|
||
members:
|
||
- partition: partition-1
|
||
- peer: dc1-partition-1
|
||
- peer: dc1-partition-2
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
</CodeTabs>
|
||
|
||
After you create the CRD, apply it to the Consul server with the following `kubectl` CLI command:
|
||
|
||
```shell-session
|
||
$ kubectl apply -f product-group.yaml
|
||
```
|
||
|
||
Then, repeat the process to create and apply a CRD for every partition that is a member of the sameness group.
|
||
|
||
### Export services to other partitions in the sameness group
|
||
|
||
To make services available to other members of the sameness group, you must write and apply an [exported services CRD](/consul/docs/connect/config-entries/exported-services) for each partition in the group. This CRD exports the local partition's services to the rest of the group members. In each CRD, set the sameness group as the `consumer` for the exported services. You can export multiple services in a single exported services configuration entry.
|
||
|
||
Because you are configuring the consumer to reference the sameness group instead of listing out each partition and cluster peer, you do not need to edit this configuration again when you add a partition or peer to the group.
|
||
|
||
The following example demonstrates how to format three different `ExportedServices` CRDs to make a service named `api` deployed to the `store` namespace of each partition available to all other group members:
|
||
|
||
<CodeTabs tabs={[ "dc1-partition-1", "dc1-partition-2", "dc2-partition-1" ]}>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="7-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
Kind: ExportedServices
|
||
metadata:
|
||
name: partition-1
|
||
spec:
|
||
services:
|
||
- name: api
|
||
namespace: store
|
||
consumers:
|
||
- samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="7-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
Kind: ExportedServices
|
||
metadata:
|
||
name: partition-2
|
||
spec:
|
||
services:
|
||
- name: api
|
||
namespace: store
|
||
consumers:
|
||
- samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="7-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
Kind: ExportedServices
|
||
metadata:
|
||
name: partition-1
|
||
spec:
|
||
services:
|
||
- name: api
|
||
namespace: store
|
||
consumers:
|
||
- samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
</CodeTabs>
|
||
|
||
For more information about exporting services, including examples of CRDs that export multiple services at the same time, refer to the [exported services configuration entry reference](/consul/docs/connect/config-entries/exported-services).
|
||
|
||
After you create each exported services configuration entry, apply it to the Consul server with the following CLI command:
|
||
|
||
```shell-session
|
||
$ kubectl apply -f product-group-export.yaml
|
||
```
|
||
|
||
#### Export services for cluster peers and sameness groups as part of the same workflow
|
||
|
||
Creating a cluster peering connection between two partitions and then adding the partitions to a sameness group requires that you write and apply two separate exported services CRDs. One CRD exports services to the peer, and a second CRD exports services to other members of the group.
|
||
|
||
If your goal for peering clusters is to create a sameness group, you can write and apply a single exported services configuration entry by configuring the `services[].consumers` block with the `samenessGroup` field instead of the `peer` field. Be aware that this scenario requires you to write the `SamenessGroup` CRD to Kubernetes before you apply the `ExportedServices` CRD that references the sameness group.
|
||
|
||
### Create service intentions to authorize traffic between group members
|
||
|
||
Exporting the service to other members of the sameness group makes the services visible to remote partitions, but you must also create service intentions so that local services are authorized to send and receive traffic from a member of the sameness group.
|
||
|
||
For each partition that is a member of the group, write and apply a [service intentions CRD](/consul/docs/connect/config-entries/service-intentions) that defines intentions for the services that are part of the group. In the `sources` block of the configuration entry, include the service name, its namespace, the sameness group and grant `allow` permissions.
|
||
|
||
Because you are using the sameness group in the `sources` block rather than listing out each partition and cluster peer, you do not have to make further edits to the service intentions configuration entries when members are added to or removed from the group.
|
||
|
||
The following example demonstrates how to format three different `ServiceIntentions` CRDs to make a service named `api` available to all instances of `payments` deployed in all members of the sameness group including the local partition. In this example, `api` is deployed to the `store` namespace in all three partitions.
|
||
|
||
<CodeTabs tabs={[ "dc1-partition-1", "dc1-partition-2", "dc2-partition-1" ]}>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="4,7-10">
|
||
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceIntentions
|
||
metadata:
|
||
name: api-intentions
|
||
spec:
|
||
sources:
|
||
- name: api
|
||
action: allow
|
||
namespace: store
|
||
samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="4,7-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceIntentions
|
||
metadata:
|
||
name: api-intentions
|
||
spec:
|
||
sources:
|
||
- name: api
|
||
action: allow
|
||
namespace: store
|
||
samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
<CodeBlockConfig hideClipboard lineNumbers highlight="4,7-10">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceIntentions
|
||
metadata:
|
||
name: api-intentions
|
||
spec:
|
||
sources:
|
||
- name: api
|
||
action: allow
|
||
namespace: store
|
||
samenessGroup: product-group
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
</CodeTabs>
|
||
|
||
Refer to [create and manage intentions](/consul/docs/connect/intentions/create-manage-intentions) for more information about how to create and apply service intentions in Consul.
|
||
|
||
After you create each service intentions configuration entry, apply it to the Consul server with the following CLI command:
|
||
|
||
```shell-session
|
||
$ kubectl apply -f api-intentions.yaml
|
||
```
|
||
|
||
#### Create service intentions for cluster peers and sameness groups as part of the same workflow
|
||
|
||
Creating a cluster peering connection between two partitions and then adding the partitions to a sameness group requires that you write and apply two separate service intentions CRDs. One CRD authorizes services for the peer, and a second CRD authorizes services for other members of the group.
|
||
|
||
If your goal for peering clusters is to create a sameness group, you can write and apply a single service intentions CRD by configuring the `sources` block with the `samenessGroup` field instead of the `peer` field. Be aware that this scenario requires you to write the `SamenessGroup` CRD to Kubernetes before you apply the `ServiceIntentions` CRD that references the sameness group.
|
||
|
||
## Next steps
|
||
|
||
When `defaultForFailover=true` in a sameness group CRD, additional upstream configuration is not required.
|
||
|
||
After creating a sameness group, you can also set up failover between services in a sameness group. Refer to [Failover with sameness groups](/consul/docs/connect/manage-traffic/failover/sameness) for more information.
|