diff --git a/website/content/en/docs/concepts/_index.md b/website/content/en/docs/concepts/_index.md index f6438f07..15139cbb 100644 --- a/website/content/en/docs/concepts/_index.md +++ b/website/content/en/docs/concepts/_index.md @@ -1,5 +1,5 @@ --- title: Core Concepts -description: Core Concepts and Tasks +description: Core Concepts of the ClusterLink system. weight: 30 --- diff --git a/website/content/en/docs/concepts/peers.md b/website/content/en/docs/concepts/peers.md index a4fb1b30..bda2503a 100644 --- a/website/content/en/docs/concepts/peers.md +++ b/website/content/en/docs/concepts/peers.md @@ -9,7 +9,7 @@ A *Peer* represents a location, such as a Kubernetes cluster, participating in a it wishes 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 CR]({{< ref "users#deploy-cr-instance" >}}). They may also wish to provide + the [deployment CR]({{< ref "operator#deploy-cr-instance" >}}). They may also wish to provide (often) coarse-grained access policies in accordance with high level corporate policies (e.g., "production peers should only communicate with other production peers"). diff --git a/website/content/en/docs/getting-started/users.md b/website/content/en/docs/getting-started/users.md index d760fc6d..dc78c895 100644 --- a/website/content/en/docs/getting-started/users.md +++ b/website/content/en/docs/getting-started/users.md @@ -58,7 +58,8 @@ To set up ClusterLink on a Kubernetes cluster, follow these steps: ``` This command will deploy the ClusterLink operator on the `clusterlink-operator` namespace - and convert the peer certificates to secrets in this namespace. + and convert the peer certificates to secrets in the namespace where ClusterLink components will be installed. + By default, the `clusterlink-system` namespace is used. The command assumes that `kubectl` is set to the correct peer (K8s cluster) and that the certificates were created by running the previous command on the same working directory. If they were not, use the flag `--path ` for pointing to the working directory @@ -66,56 +67,12 @@ To set up ClusterLink on a Kubernetes cluster, follow these steps: The `--fabric` option is optional, and by default, "default_fabric" will be used. The `--autostart` option will deploy the ClusterLink components in the `clusterlink-system` namespace, and enable ClusterLink in the cluster. + For more details and deployment configuration see [ClusterLink deployment operator]({{< ref "operator" >}}). {{< notice note >}} To deploy ClusterLink on another cluster, repeat steps 2-3 in a console with access to the cluster. {{< /notice >}} -### Additional configurations - -* Setting ClusterLink namespace: - - ```sh - clusterlink deploy peer --autostart --name --fabric \ - --namespace - ``` - - The `--namespace` parameter determines the namespace where the ClusterLink components are deployed. - Note that you must set `--autostart`, and the namespace should already exist. - -* Setting ClusterLink ingress type: - - ```sh - clusterlink deploy peer --autostart --name --fabric \ - --ingress - ``` - - The `--ingress` parameter controls the ClusterLink ingress type, with `LoadBalancer` being the default. - If you're using a local kind cluster, replace `` with `NodePort`. - For a cluster running on cloud, use `LoadBalancer` or leave ingress type unspecified. - Note that `--autostart` must be set when configuring ingress type. - -* {{< anchor deploy-cr-instance >}}Full configuration setting using a ClusterLink K8s custom resource object: - - ```yaml - kubectl apply -f - < - spec: - ingress: - type: - namespace: clusterlink-system - EOF - ``` - - After the operator is installed, you can deploy ClusterLink by applying a ClusterLink object as shown above. - The ClusterLink operator will create the ClusterLink gateway components in the `clusterlink-system` namespace. - For more details and information about the ClusterLink custom resource, - refer to the [operator documentation](https://github.com/clusterlink-net/clusterlink/blob/main/design-proposals/project-deployment.md#clusterlink-crd). - ## Try it out Check out the [ClusterLink Tutorials]({{< ref "tutorials" >}}) for setting up diff --git a/website/content/en/docs/tasks/_index.md b/website/content/en/docs/tasks/_index.md new file mode 100644 index 00000000..9355d1b0 --- /dev/null +++ b/website/content/en/docs/tasks/_index.md @@ -0,0 +1,5 @@ +--- +title: Tasks +description: How to do single specific targeted activities with ClusterLink. +weight: 35 +--- diff --git a/website/content/en/docs/tasks/operator.md b/website/content/en/docs/tasks/operator.md new file mode 100644 index 00000000..b4ddf8d9 --- /dev/null +++ b/website/content/en/docs/tasks/operator.md @@ -0,0 +1,109 @@ +--- +title: Deployment Operator +description: Usage and configuration of the ClusterLink deployment operator. +weight: 50 +--- +The ClusterLink deployment operator allows easy deployment of ClusterLink to a K8s cluster. +The preferred deployment approach involves utilizing the ClusterLink CLI, +which automatically deploys both the ClusterLink operator and ClusterLink components. +However, it's important to note that ClusterLink deployment necessitates peer certificates for proper functioning. +Detailed instructions for creating these peer certificates can be found in the [getting started]({{< ref "users#Setup">}}). + +## The common use-case + +The common use case for deploying ClusterLink on a cloud based K8s cluster (i.e., EKS, GKE, IKS, etc.) is using the CLI command: + +```sh +clusterlink deploy peer --autostart --name --fabric +``` + +The command assumes that `kubectl` is configured to access the correct peer (K8s cluster) +and that certificates files are placed in the current working directory. +If they are not, use the flag `--path ` to reference the directory where certificate files are stored. +The command deploys the ClusterLink operator in the `clusterlink-operator` namespace and converts +the peer certificates to secrets in the `clusterlink-system` namespace, where ClusterLink components will be installed. +By default, these components are deployed in the `clusterlink-system` namespace. +The `--autostart` option will create a ClusterLink K8s custom resource object and deploy it to the operator. +The operator will then create the ClusterLink components in the `clusterlink-system` namespace and enable ClusterLink in the cluster. +Additionally, a `LoadBalancer` service is created to allow cross-cluster connectivity using ClusterLink. + +## Deployment for Kind environment + +To deploy ClusterLink in a local environment like Kind, you can use the following command: + +```sh +clusterlink deploy peer --autostart --name --fabric --ingress=NodePort --ingress-port=30443 +``` + +The Kind environment doesn't allocate an external IP to the `LoadBalancer` service by default. +In this case, we will use a `NodePort` service to establish multi-cluster connectivity using ClusterLink. +Alternatively, you can install MetalLB to add a Load Balancer implementation to the Kind cluster. See instructions +[here](https://kind.sigs.k8s.io/docs/user/loadbalancer/). +The port flag is optional, and by default, ClusterLink will use any allocated NodePort that the Kind cluster provides. +However, it is more convenient to use a fixed setting NodePort for peer configuration, as demonstrated in the [ClusterLink Tutorials]({{< ref "tutorials">}}). + + +## Deployment of specific version + +To deploy a specific ClusterLink image version use the `tag` flag: + +```sh +clusterlink deploy peer --autostart --name --fabric --tag +``` + +The `tag` flag will change the tag version in the ClusterLink K8s custom resource object that will be deployed to the operator. + +## Deployment using manually defined ClusterLink custom resource + +The deployment process can be split into two steps: + +1. Deploy only ClusterLink operator: + + ```sh + clusterlink deploy peer ---name --fabric + ``` + + This command will deploy only the ClusterLink operator and the certificate's secrets as described in the [common use case]({{< ref "operator#the-common-use-case" >}}). + +1. {{< anchor deploy-cr-instance >}} Deploy a ClusterLink K8s custom resource object: + + ```yaml + kubectl apply -f - < + spec: + ingress: + type: + dataplane: + type: envoy + replicas: 1 + logLevel: info + namespace: clusterlink-system + EOF + ``` + +## Additional deployment configurations + +The `deploy peer` command has the following flags: + +- **namespace:** This field determines the namespace where the ClusterLink components are deployed. + By default, it uses `clusterlink-system`, which is created by the `clusterlink deploy peer` command. + If a different namespace is desired, that namespace must already exist. +- **dataplane:** This field determines the type of ClusterLink dataplane, with supported values `go` or `envoy`. By default, it uses `envoy`. +- **dataplane-replicas:** This field determines the number of ClusterLink dataplane replicas. By default, it uses 1. +- **ingress:** This field determines the type of ingress service to expose ClusterLink deployment, + with supported values: `LoadBalancer`, `NodePort`, or `None`. By default, it uses `LoadBalancer`. +- **ingress-port:** This field determines the port number of the external service. + By default, it uses port `443` for the `LoadBalancer` ingress type. + For the `NodePort` ingress type, the port number will be allocated by Kubernetes. + In case the user changes the default value, it is the user's responsibility to ensure the port number is valid and available for use. +- **log-level:** This field determines the severity log level for all the components (controlplane and dataplane). + By default, it uses `info` log level. +- **container-registry:** This field determines the container registry to pull the project images. + By default, it uses `ghcr.io/clusterlink-net`. +- **tag:** This field determines the version of project images to pull. By default, it uses the `latest` version. + +All the flags are mapped to corresponding field in the ClusterLink custom resource.