docs: Installation Guide for ClusterLink

README.md

@@ -67,7 +67,7 @@ Here are the key steps for setting up your developer environment, making a chang
 ### How to setup and run ClusterLink
 
 ClusterLink can be set up and run on different environments: local environment (Kind),
- Bare-metal environment, or cloud environment.
+ Bare-metal environment, or cloud environment. For more details, refer to the [Installation Guide for ClusterLink](docs/Installation.md).
 
 #### Run ClusterLink in local environment (Kind)
 

demos/iperf3/kind/README.md

@@ -26,9 +26,9 @@ In this step, we build the Kind cluster with the gateway image.
 Create certificates and deployments files:
 1) Create folder for all deployments and yaml files:
 
-        export TEST_DIR=$PROJECT_DIR/bin/test/iperf3/
-        mkdir -p $TEST_DIR
-        cd $TEST_DIR
+        export DEPLOY_DIR=~/clusterlink-deployment
+        mkdir -p $DEPLOY_DIR
+        cd $DEPLOY_DIR
 
 2) Create fabric certificates (includes the Root CA certificate fo all the gateways):
 
@@ -51,7 +51,7 @@ Build the first Kind cluster with gateway, and iperf3-client:
 
 2) Deploy ClusterLink gateway deployment:
 
-        kubectl apply -f $TEST_DIR/peer1/k8s.yaml
+        kubectl apply -f $DEPLOY_DIR/peer1/k8s.yaml
 
 3) Expose ClusterLink gateway port using K8s nodeport service:
 
@@ -70,7 +70,7 @@ Build the second Kind cluster with gateway, and iperf3-client:
 
 2) Deploy Clustrelink gateway deployment:
 
-        kubectl apply -f $TEST_DIR/peer2/k8s.yaml
+        kubectl apply -f $DEPLOY_DIR/peer2/k8s.yaml
 
 3) Expose ClusterLink gateway port using K8s nodeport service:
 
@@ -83,7 +83,9 @@ Build the second Kind cluster with gateway, and iperf3-client:
 
 Check that container statuses are Running.
 
-    kubectl get pods
+        kubectl rollout status deployment cl-controlplane
+        kubectl rollout status deployment cl-dataplane
+        kubectl wait --for=condition=ready pod -l app=gwctl 
 
 ### Step 3: Start gwctl
 In this step, we set up the gwctl.
@@ -96,17 +98,17 @@ First, Initialize the Gateways IPs:
 
 Initialize gwctl CLI for peer1:
 
-    gwctl init --id "peer1" --gwIP $PEER1_IP --gwPort 30443 --certca $TEST_DIR/cert.pem --cert $TEST_DIR/peer1/gwctl/cert.pem --key $TEST_DIR/peer1/gwctl/key.pem
+    gwctl init --id "peer1" --gwIP $PEER1_IP --gwPort 30443 --certca $DEPLOY_DIR/cert.pem --cert $DEPLOY_DIR/peer1/gwctl/cert.pem --key $DEPLOY_DIR/peer1/gwctl/key.pem
 
 Initialize gwctl CLI for peer2:
 
-    gwctl init --id "peer2" --gwIP $PEER2_IP --gwPort 30443 --certca $TEST_DIR/cert.pem --cert $TEST_DIR/peer2/gwctl/cert.pem --key $TEST_DIR/peer2/gwctl/key.pem
+    gwctl init --id "peer2" --gwIP $PEER2_IP --gwPort 30443 --certca $DEPLOY_DIR/cert.pem --cert $DEPLOY_DIR/peer2/gwctl/cert.pem --key $DEPLOY_DIR/peer2/gwctl/key.pem
 
 Note : Another approach is to use the gwctl inside the kind cluster. In this case, the gwctl is already set up and deployed.
 (If you are using macOS this is the better approach). 
 In this case, you should replace the gwctl command with:
 
-    kubectl exec -i <gwctl_pod> -- gwctl <the command>
+    kubectl exec -i <gwctl_pod> -- gwctl <command>
 
     See example in the next step.
 

docs/installation.md

@@ -0,0 +1,126 @@
+# Installation guide for ClusterLink
+
+The ClusterLink gateway contains three main components: the control-plane, data-plane, and gwctl (more details can be found [here](../README.md#what-is-clusterlink)).
+
+ClusterLink can be deployed in any K8s based cluster (e.g., google GKE, amazon EKS, IBM IKS, KIND etc.).
+
+To deploy the ClusterLink gateway in a K8s cluster, follow these steps:
+
+1. Create and deploy certificates and the ClusterLink deployment YAML file.
+2. Expose the ClusterLink deployment to a public IP.
+3. Optionally, create a central gwctl component to control one or more gateways.
+
+Before you begin, please build the project according to the [instructions](../README.md#building-clustelink).
+
+## 1. ClusterLink deployment and certificates
+
+In this step, we generate the ClusterLink certificates and deployment files.
+
+1) Create a folder (eg. DEPLOY_DIR) for all deployments and yaml files:
+
+        export PROJECT_DIR=`git rev-parse --show-toplevel`
+        export DEPLOY_DIR=~/clusterlink-deployment
+        mkdir -p $DEPLOY_DIR
+        cd $DEPLOY_DIR
+
+2) Create fabric certificate, which is the root CA certificate for all the clusters:
+
+        $PROJECT_DIR/bin/cl-adm create fabric
+
+    Note: This step needs to be done only once per fabric.
+3) Create certificates and a deployment file for the cluster (e.g., peer1):
+
+        $PROJECT_DIR/bin/cl-adm create peer --name peer1
+
+    Note: By default, the images are pulled from ghcr.io/clusterlink-net. To change the container registry, you can use the ```--container-registry``` flag.  
+    This step needs to be performed for every K8s cluster.
+
+4) Apply ClusterLink deployment:
+
+        kubectl apply -f $DEPLOY_DIR/peer1/k8s.yaml
+
+5) Verify that all components (cl-controlplane, cl-dataplane, gwctl) are set up and ready.
+
+        kubectl rollout status deployment cl-controlplane
+        kubectl rollout status deployment cl-dataplane
+        kubectl wait --for=condition=ready pod -l app=gwctl 
+
+    Expected output:
+
+        deployment "cl-controlplane" successfully rolled out
+        deployment "cl-dataplane" successfully rolled out
+        pod/gwctl condition met
+
+## 2. Expose the ClusterLink deployment to a public IP
+
+Create a public IP for accessing the ClusterLink gateway.  
+* For a testing environment (e.g., KIND), create a K8s nodeport service:
+```
+echo "
+apiVersion: v1
+kind: Service
+metadata:
+  name: cl-svc
+spec:
+  type: NodePort
+  selector:
+    app: cl-dataplane
+  ports:
+  - port: 443
+    targetPort: 443
+    nodePort: 30443
+    protocol: TCP
+    name: http
+" | kubectl apply -f -
+
+export PEER1_IP=`kubectl get nodes -o "jsonpath={.items[0].status.addresses[0].address}"`
+export PEER1_PORT=30443
+```
+* For a operational K8s cluster environment (e.g., google GKE, amazon EKS, IBM IKS, etc.):
+
+1. First, create a K8s LoadBalancer service:
+
+        kubectl expose deployment cl-dataplane --name=cl-dataplane-load-balancer --port=443 --target-port=443 --type=LoadBalancer
+
+2. Retrieve the LoadBalancer IP when it is allocated:
+
+        export PEER1_IP=$(kubectl get svc -l app=cl-dataplane -o jsonpath="{.items[0].status.loadBalancer.ingress[0].ip}")
+        export PEER1_PORT=443
+
+Now, the ClusterLink gateway can be accessed through `$PEER1_IP` at port `$PEER1_PORT`.
+
+## 3. Create a central gwctl (optional)
+By default for each K8s cluster a gwctl pod is created that use REST APIs to send control messages to the
+ClusterLink gateway, using the command:
+
+    kubectl exec -i <gwctl_pod> -- gwctl <command>
+
+To create a single gwctl that controls one or more ClusterLink gateways, follow these steps:
+
+1. Install the local control (gwctl):
+
+        sudo make install
+
+2. Initialize the gwctl CLI for the cluster (e.g., peer1):
+
+        gwctl init --id peer1 --gwIP $PEER1_IP --gwPort $PEER1_PORT --certca $DEPLOY_DIR/cert.pem --cert $DEPLOY_DIR/peer1/gwctl/cert.pem --key $DEPLOY_DIR/peer1/gwctl/key.pem
+
+3. To run gwctl command:
+
+        gwctl --myid peer1 <command>
+
+## Additional setup modes
+### Debug mode
+To run ClusterLink components in debug mode, use ```--log-level``` flag when creating the ClusterLink deployment
+
+    $PROJECT_DIR/bin/cl-adm create peer --name peer1 --log-level debug
+
+### Running self-built images
+To create and run a local image, first build the project's local images:
+
+    make docker-build
+
+Change the container-registry in the peer deployment to use the local image:
+
+    $PROJECT_DIR/bin/cl-adm create peer --name peer1 --container-registry=""
+