Elaborate the core concepts documentation

website/content/en/docs/concepts/fabric.md

@@ -4,17 +4,44 @@ description: Defining a ClusterLink fabric
 weight: 32
 ---
 
-<!--
-Each task should give the user
+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).
 
-* The prerequisites for this task, if any (this can be specified at the top of a multi-task page if they're the same for all the page's tasks. "All these tasks assume that you understand....and that you have already....").
-* What this task accomplishes.
-* Instructions for the task. If it involves editing a file, running a command, or writing code, provide code-formatted example snippets to show the user what to do! If there are multiple steps, provide them as a numbered list.
-* If appropriate, links to related concept, tutorial, or example pages.
--->
+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 <fabric_name>
+```
+
+This command will create the CA files `<fabric_name>.cert` and `<fabric_name>.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/).

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., `./<fabric_name>.crt` and `./<fabric_name>.key`).
+
+```sh
+clusterlink create site --name <site_name> --fabric <fabric_name>
+```
+
+This will create the certificate and private key files (`<site_name>.cert` and
+ `<site_name>.key`, respectively) for the new site. By default, the files are
+ created in a subdirectory named `<site_name>` under the current working directory.
+ You can override the default by setting the `--output <path>` 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 <path>` 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/).

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