Administrator guide

In the examples, cluster A invites cluster B to a peering.

Preparation

Before establishing a peering, check on both clusters that:

• the global.modules.https.mode parameter is CertManager or CustomCertificate;
• the peering and peering-gateway domains are reachable from the other cluster: with the public domain template %s.example.com, these are peering.example.com and peering-gateway.example.com;
• load balancers and proxies between the clusters pass connections to these domains without TLS decryption.

Enabling the module

Enable the module on both clusters. The user-authn module must be enabled.

Create a ModuleConfig:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: peering
spec:
  enabled: true

The module is ready when PHASE in the command output is Ready:

d8 k get module peering

Creating an invitation

On cluster A, create a ClusterPeer of the Invite type. The object name becomes the name of the peering in this cluster:

apiVersion: peering.deckhouse.io/v1alpha1
kind: ClusterPeer
metadata:
  name: cluster-b
spec:
  type: Invite
  invite:
    tokenTTL: 1h

spec.invite.tokenTTL is the validity period of the connection string: from 10m to 24h, 24h by default.

Get the connection string:

d8 k get clusterpeer cluster-b -o jsonpath='{.status.invite.connectionString}'

Pass the string to the administrator of cluster B over a secure channel: whoever has it can connect to your cluster. The string is valid for one connection. If it expires before it is used, get the string again: the module issues a new one.

Connecting to the inviting cluster

On cluster B, create a ClusterPeer of the Join type with the connection string:

apiVersion: peering.deckhouse.io/v1alpha1
kind: ClusterPeer
metadata:
  name: cluster-a
spec:
  type: Join
  join:
    connectionString: <connection string of cluster A>

Check the peering state on both clusters:

d8 k get clusterpeers

The peering is established when PHASE is Active and READY is True. Otherwise, the reason is in status.conditions of the ClusterPeer.

Opening capabilities

The capabilities declared by the modules of the cluster are listed by the command:

d8 k get peeringcapabilities

A capability can be opened if its ACCEPTED is True. List it in spec.capabilities of the ClusterPeer on both clusters:

spec:
  capabilities:
  - <capability name>

A capability works once both clusters have opened it. The EFFECTIVE column in the d8 k get clusterpeers output shows the capabilities open in the peering.

Paired projects

Same-named projects of connected clusters are paired automatically. The pairs of a project are listed by the command:

d8 k -n <project> get projectpeers

STATE is Paired when the pair works and PeerUnreachable when the other cluster is unavailable.

Revoking a peering

To revoke a peering, delete the ClusterPeer in your cluster:

d8 k delete clusterpeer cluster-b

After the deletion, the other cluster loses access to your cluster. The other cluster is not notified of the revocation: delete the ClusterPeer on it separately. Temporary unavailability of the other cluster does not revoke the peering.

Disabling the module

When the module is disabled, all peerings of the cluster stop working, and other clusters are not notified. After the module is enabled again, establish each peering anew on both clusters. Disabling the user-authn module disables the peering module too.

To disable the module, add the modules.deckhouse.io/allow-disabling=true annotation to its ModuleConfig and set enabled: false.