diff --git a/website/content/en/docs/concepts/fabric.md b/website/content/en/docs/concepts/fabric.md index accdfb21..54a6a5b8 100644 --- a/website/content/en/docs/concepts/fabric.md +++ b/website/content/en/docs/concepts/fabric.md @@ -4,17 +4,44 @@ description: Defining a ClusterLink fabric weight: 32 --- - +Currently, the concept of a `Fabric` is just that - a concept. It is not represented + or backed by any managed resource in a ClusterLink deployment. Once a `Fabric` is created, + its only relevance is in providing a certificate for use by each site's gateways. + One could potentially consider a more elaborate implementation where a central + management entity explicitly deals with `Fabric` life cycle, association of sites to + a fabric, etc. The role of this central management component in ClusterLink is currently + delegated to users who are responsible for coordinating the transfer to certificates + between sites, out of band. -## What is it +## Initializing a new fabric -## Detailed instructions +### Prerequisites + +The following assume that you have access to the `clusterlink` CLI and one or more + sites (i.e., clusters) where you'll deploy ClusterLink. The CLI can be downloaded + from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest). + +### Create a new Fabric CA + +To create a new Fabric certificate authority (CA), execute the following CLI command: + +```sh +clusterlink create fabric --name +``` + +This command will create the CA files `.cert` and `.key` in the + current directory. While you will need access to these files to create the sites` gateway + certificates later, the private key file should be protected and not shared with others. ## Related tasks + +Once a `Fabric` has been created and initialized, you can proceed with configuring + [sites](/docs/concepts/sites/). For a complete, end to end, use case please refer to the + [iperf toturial](/docs/tutorials/iperf/). diff --git a/website/content/en/docs/concepts/site.md b/website/content/en/docs/concepts/site.md deleted file mode 100644 index 4003aa40..00000000 --- a/website/content/en/docs/concepts/site.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Site -description: Defining ClusterLink Sites as part of Fabric -weight: 34 ---- - - - -## What is it - -## Detailed instructions - -## Related tasks diff --git a/website/content/en/docs/concepts/sites.md b/website/content/en/docs/concepts/sites.md new file mode 100644 index 00000000..8399b9e1 --- /dev/null +++ b/website/content/en/docs/concepts/sites.md @@ -0,0 +1,101 @@ +--- +title: Sites +description: Defining ClusterLink Sites as part of Fabric +weight: 34 +--- + +A `Site` represents a location, such as a Kubernetes cluster, participating in a + [Fabric](/docs/concepts/fabric/). Each site may host one or more [Services](/docs/concepts/services/) + it wishes to share with other sites. A site is managed by a site administrator, + which is responsible for running the ClusterLink control and data planes. The + administrator will typically deploy the ClusterLink components by configuring + the [deployment CRD](/docs/getting-started/#setup). They may also wish to provide + (often) coarse-grained access policies in accordance with high level corporate + policies (e.g., "production sites should only communicate with other production sites"). + +Once a `Site` has been added to a `Fabric`, it can communicate with any other `Site` + 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). + +## Initializing a new Site + +### Prerequisites + +The following assume that you have access to the `clusterlink` CLI and one or more + sites (i.e., clusters) where you'll deploy ClusterLink. The CLI can be downloaded + from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest). + It also assumes that you have access to the [previously created](/docs/concepts/fabric/#create-a-new-fabric-ca) + Fabric CA files. + +### Create a new Site certificate + +Creating a new Site is a **Fabric** administrator level operation and should be appropriately protected. + +To create a new Site certificate belonging to a fabric, confirm that the Fabric CA files + are available in the current working directory, and then execute the following CLI command: + +> Note: The Fabric CA files (certificate and private key) are expected in the current +> working directory (i.e., `./.crt` and `./.key`). + +```sh +clusterlink create site --name --fabric +``` + +This will create the certificate and private key files (`.cert` and + `.key`, respectively) for the new site. By default, the files are + created in a subdirectory named `` under the current working directory. + You can override the default by setting the `--output ` option. + +You will need the CA certificate (but **not** the CA private key) and the site certificate + and private in the next step. They can be provided out of band (e.g., over email) to the + site administrator. + +### Deploy ClusterLink to a Site + +This operation is typically done by a local *Site administrator*, typically different + than the *Fabric administrator*. Before proceeding, ensure that the CA certificate + (the CA private key is not needed), and the site certificate and key files which were + created in the previous step are in the current working directory. + +1. Install the ClusterLink deployment operator. + + ```sh + clusterlink site init + ``` + + The command assumes that kubectl is set to the correct context and credentials + and that the certificates were created in the local folder. If they were not, + add `-f ` to set the correct path to the certificate files. + + 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 + and the CA and site certificate and key are set as Kubernetes secrets + in the namespace. You can confirm the successful completion of the step using + the following commands (TODO: describe output): + + ```sh + kubectl get crds + ``` + + and + + ```sh + kubectl get secret --namespace clusterlink-operator + ``` + +1. Deploy ClusterLink CRD instance. + + After the operator is installed, you can deploy ClusterLink by applying + the ClusterLink instance CRD. + Refer to the [getting started guide](/docs/getting-started/#setup) for a description + of the CRD instance fields. + +## Related tasks + +Once a `Site` has been created and initialized with the ClusterLink control and data + planes, you can proceed with configuring [services](/docs/concepts/services/) + and [policies](/docs/concepts/policies/). + For a complete end to end use case, refer to [iperf toturial](/docs/tutorials/iperf/). diff --git a/website/content/en/docs/tutorials/iperf.md b/website/content/en/docs/tutorials/iperf.md new file mode 100644 index 00000000..b53dc418 --- /dev/null +++ b/website/content/en/docs/tutorials/iperf.md @@ -0,0 +1,12 @@ +--- +title: iperf +description: Running iperf across multiple sites with ClusterLink +--- + +## Initialize Clusters + +## Install ClusterLink + +## Deploy iperf Clients and Servers + +## Enable Access