Peers

Defining ClusterLink peers as part of a fabric

A Peer represents a location, such as a Kubernetes cluster, participating in a fabric. Each peer may host one or more services that it may wish to share with other peers. A peer is managed by a peer administrator, which is responsible for running the ClusterLink control and data planes. The administrator will typically deploy the ClusterLink components by configuring the Deployment Custom Resource (CR). They may also wish to define coarse-grained access policies, in accordance with high level corporate policies (e.g., “production peers should only communicate with other production peers”).

Once a peer has been added to a fabric, it can communicate with any other peer belonging to it. All configuration relating to service sharing (e.g., the exporting and importing of services, and the setting of fine grained application policies) can be done with lowered privileges (e.g., by users, such as application owners). Remote peers are represented by the Peer Custom Resources (CRs). Each peer CR instance defines a remote cluster and the network endpoints of its ClusterLink gateways.

Prerequisites

The following sections assume that you have access to the clusterlink CLI and one or more peers (i.e., clusters) where you’ll deploy ClusterLink. The CLI can be downloaded from the ClusterLink releases page on GitHub. It also assumes that you have access to the previously created fabric CA files.

Initializing a new peer

Warning

Creating a new peer is a fabric administrator level operation and should be appropriately protected.

Create a new peer certificate

To create a new peer certificate belonging to a fabric, confirm that the fabric Certificate Authority (CA) files are available in the current working directory, and then execute the following CLI command:

clusterlink create peer-cert --name <peer_name> --fabric <fabric_name>

Tip

The fabric CA files (certificate and private key) are expected to be in a subdirectory (i.e., ./<fabric_name>/cert.name and ./<fabric_name>/key.pem).

This will create the certificate and private key files (cert.pem and key.pem, respectively) of the new peer. By default, the files are created in a subdirectory named <peer_name> under the subdirectory of the fabric <fabric_name>. You can override the default by setting the --output <path> option.

Info

You will need the CA certificate (but not the CA private key) and the peer’s certificate and private key pair in the next step. They can be provided out of band (e.g., over email) to the peer administrator or by any other means for secure transfer of sensitive data.

Info

This operation is typically done by a local peer administrator, usually different than the fabric administrator.

Before proceeding, ensure that the following files (created in the previous step) are available in the current working directory:

  1. CA certificate;
  2. peer certificate; and
  3. peer private key.

Install the ClusterLink operator by running the following command:

clusterlink deploy peer --name <peer_name> --fabric <fabric_name>

The command assumes that kubectl is set to the correct context and credentials and that the certificates were created in respective sub-directories under the current working directory. If they were not, add the --path <path> CLI option to set the correct path.

This command will deploy the ClusterLink deployment CRDs using the current kubectl context. The operation requires cluster administrator privileges in order to install CRDs into the cluster. The ClusterLink operator is installed to the clusterlink-operator namespace. The CA, peer certificate, and private key are set as K8s secrets in the namespace where ClusterLink components are installed, which by default is clusterlink-system. You can confirm the successful completion of this step using the following commands:

kubectl get crds
kubectl get secret --namespace clusterlink-system
Example output
$ kubectl get crds
NAME                                       CREATED AT
accesspolicies.clusterlink.net             2024-04-07T12:08:24Z
exports.clusterlink.net                    2024-04-07T12:08:24Z
imports.clusterlink.net                    2024-04-07T12:08:24Z
instances.clusterlink.net                  2024-04-07T12:08:24Z
peers.clusterlink.net                      2024-04-07T12:08:24Z
privilegedaccesspolicies.clusterlink.net   2024-04-07T12:08:24Z

$ kubectl get secret --namespace clusterlink-system
NAME              TYPE     DATA   AGE
cl-controlplane   Opaque   2      19h
cl-dataplane      Opaque   2      19h
cl-ca             Opaque   1      19h
cl-peer           Opaque   1      19h

After the operator is installed, you can deploy ClusterLink by applying the ClusterLink CR. This will cause the ClusterLink operator to attempt reconciliation of the actual and intended ClusterLink deployment. By default, the operator will install the ClusterLink control and data plane components into a dedicated and privileged namespace (defaults to clusterlink-system). Configurations affecting the entire peer, such as the list of known peers, are also maintained in the same namespace.

Refer to the operator documentation for a description of the ClusterLink CR fields.

Add or remove peers

Info

This operation is typically done by a local peer administrator, usually different than the fabric administrator.

Managing peers is done by creating, deleting and updating peer CRs in the dedicated ClusterLink namespace (typically, clusterlink-system). Peers are added to the ClusterLink namespace by the peer administrator. Information regarding peer gateways and attributes is communicated out of band (e.g., provided by the fabric or remote peer administrator over email). In the future, these may be configured via a management plane.

Peer Custom Resource
type Peer struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec PeerSpec `json:"spec"`
    Status PeerStatus `json:"status,omitempty"`
}


type PeerSpec struct {
    Gateways []Endpoint `json:"gateways"`
}

type PeerStatus struct {
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type Endpoint struct {
    Host string `json:"host"`
    Port uint16 `json:"port"`
}

There are two fundamental attributes in the peer CRD: the peer name and the list of ClusterLink gateway endpoints through which the remote peer’s services are available. Peer names are unique and must align with the Subject name present in their certificate during connection establishment. The name is used by importers in referencing an export (see services for details).

Gateway endpoint would typically be implemented via a NodePort or LoadBalancer K8s service. A NodePort service would typically be used in local deployments (e.g., when running in kind clusters during development) and a LoadBalancer service would be used in cloud-based deployments. These can be automatically configured and created via the ClusterLink CR. The peer’s status section includes a Reachable condition indicating whether the peer is currently reachable, and in case it is not reachable, the last time it was.

Example YAML for kubectl apply -f <peer_file>
apiVersion: clusterlink.net/v1alpha1
kind: Peer
metadata:
  name: cluster17.us-east
  namespace: clusterlink-system
spec:
  gateways:
  - host: "192.168.0.12"
    port: 443
  - host: "192.168.0.17"
    port: 443

Once a peer has been created and initialized with the ClusterLink control and data planes as well as one or more remote peers, you can proceed with configuring services and policies. For a complete end-to-end use case, refer to the iperf tutorial.


Last modified May 22, 2024: TLS Refactoring (0d5bf00)