From c6529ede7a1e85b723157bf2161901cea3ec26c5 Mon Sep 17 00:00:00 2001 From: Kfir Toledo Date: Mon, 26 Feb 2024 14:24:36 +0200 Subject: [PATCH 1/3] tests/e2e: Add wait condition to operator test (#352) Add a wait condition to check component creation in the operator test. Signed-off-by: Kfir Toledo Signed-off-by: Etai Lev Ran --- website/content/en/docs/concepts/fabric.md | 36 +++++++++++++++++-- .../en/docs/concepts/{site.md => sites.md} | 0 2 files changed, 34 insertions(+), 2 deletions(-) rename website/content/en/docs/concepts/{site.md => sites.md} (100%) diff --git a/website/content/en/docs/concepts/fabric.md b/website/content/en/docs/concepts/fabric.md index accdfb21..f6762fa5 100644 --- a/website/content/en/docs/concepts/fabric.md +++ b/website/content/en/docs/concepts/fabric.md @@ -13,8 +13,40 @@ Each task should give the user * If appropriate, links to related concept, tutorial, or example pages. --> -## What is it +The concept of a `Fabric` encapsulates a set of cooperating [sites](./sites.md). + All sites in a fabric and communicate and may share [services](./services.md) + between them, with access governed by [policies](./policies.md). + The `Fabric` acts as a root of trust for site to site communications (i.e., + it functions as the certificate authority enabling mutual authentication between + sites). -## Detailed instructions +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. + +## Initializing a new fabric + +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](TBD). + +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](./sites.md). For a complete end to end use case, refer to + [iperf toturial](TBD). diff --git a/website/content/en/docs/concepts/site.md b/website/content/en/docs/concepts/sites.md similarity index 100% rename from website/content/en/docs/concepts/site.md rename to website/content/en/docs/concepts/sites.md From 9ff883d7cce083fdcd95fb61eb091ce6ac796664 Mon Sep 17 00:00:00 2001 From: Etai Lev Ran Date: Mon, 26 Feb 2024 17:43:17 +0200 Subject: [PATCH 2/3] add iperf tutorial skeleton Signed-off-by: Etai Lev Ran --- website/content/en/docs/concepts/fabric.md | 15 +++++---------- website/content/en/docs/tutorials/iperf.md | 12 ++++++++++++ 2 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 website/content/en/docs/tutorials/iperf.md diff --git a/website/content/en/docs/concepts/fabric.md b/website/content/en/docs/concepts/fabric.md index f6762fa5..2c7cc8bc 100644 --- a/website/content/en/docs/concepts/fabric.md +++ b/website/content/en/docs/concepts/fabric.md @@ -4,15 +4,6 @@ description: Defining a ClusterLink fabric weight: 32 --- - - The concept of a `Fabric` encapsulates a set of cooperating [sites](./sites.md). All sites in a fabric and communicate and may share [services](./services.md) between them, with access governed by [policies](./policies.md). @@ -31,10 +22,14 @@ Currently, the concept of a `Fabric` is just that - a concept. It is not represe ## Initializing a new fabric +### 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](TBD). +### Create a new Fabric CA + To create a new Fabric certificate authority (CA), execute the following CLI command: ```sh @@ -49,4 +44,4 @@ This command will create the CA files `.cert` and `.ke Once a `Fabric` has been created and initialized, you can proceed with configuring [sites](./sites.md). For a complete end to end use case, refer to - [iperf toturial](TBD). + [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 From 88aa3680d2d4cc5206fca3a697566eefa7fa3f0b Mon Sep 17 00:00:00 2001 From: Etai Lev Ran Date: Tue, 27 Feb 2024 19:26:02 +0200 Subject: [PATCH 3/3] expanded site.md, fixed URLs Signed-off-by: Etai Lev Ran --- website/content/en/docs/concepts/fabric.md | 12 +-- website/content/en/docs/concepts/sites.md | 101 +++++++++++++++++++-- 2 files changed, 97 insertions(+), 16 deletions(-) diff --git a/website/content/en/docs/concepts/fabric.md b/website/content/en/docs/concepts/fabric.md index 2c7cc8bc..54a6a5b8 100644 --- a/website/content/en/docs/concepts/fabric.md +++ b/website/content/en/docs/concepts/fabric.md @@ -4,9 +4,9 @@ description: Defining a ClusterLink fabric weight: 32 --- -The concept of a `Fabric` encapsulates a set of cooperating [sites](./sites.md). - All sites in a fabric and communicate and may share [services](./services.md) - between them, with access governed by [policies](./policies.md). +The concept of a `Fabric` encapsulates a set of cooperating [sites](/docs/concepts/sites/). + All sites in a fabric can communicate and may share [services](/docs/concepts/services) + between them, with access governed by [policies](/docs/concepts/policies/). The `Fabric` acts as a root of trust for site to site communications (i.e., it functions as the certificate authority enabling mutual authentication between sites). @@ -26,7 +26,7 @@ Currently, the concept of a `Fabric` is just that - a concept. It is not represe 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](TBD). + from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest). ### Create a new Fabric CA @@ -43,5 +43,5 @@ This command will create the CA files `.cert` and `.ke ## Related tasks Once a `Fabric` has been created and initialized, you can proceed with configuring - [sites](./sites.md). For a complete end to end use case, refer to - [iperf toturial](/docs/tutorials/iperf). + [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/sites.md b/website/content/en/docs/concepts/sites.md index 4003aa40..8399b9e1 100644 --- a/website/content/en/docs/concepts/sites.md +++ b/website/content/en/docs/concepts/sites.md @@ -1,20 +1,101 @@ --- -title: Site +title: Sites description: Defining ClusterLink Sites as part of Fabric weight: 34 --- - +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). -## What is it +## Initializing a new Site -## 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). + 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/).