Installation

Pre-Installation

As presented in the “Getting Started” section, Liqo can be used with different topologies and scenarios. Clusters can be used for incoming or outgoing peering and construct different topologies (e.g. virtual cluster, cloud bursting, etc).

Before installing Liqo, you should:

  • Provision the clusters you would like to use with Liqo.
  • Have a look to the pre-install section, that presents some common patterns used to expose and interconnect clusters when using Liqo.

liqoctl

Liqoctl is the swiss-knife CLI tool to install and manage Liqo clusters. We strongly recommend installing Liqo using Liqoctl because it automatically handles the required customizations for each supported providers (e.g., AWS, EKS, etc.).

Under the hood, liqoctl uses Helm 3 to configure and install the Liqo chart available on the official repository. If you prefer to customize the installation configuration, you can use liqoctl as a provider-specific values file generator and then install Liqo with Helm as usual.

To install liqoctl, first, you have to set the architecture and OS of your host:

OS=linux # possible values: linux,windows,darwin
ARCH=amd64 # possible values: amd64,arm64 

Then, you can install the latest version of liqoctl:

curl --fail -LSO "https://get.liqo.io/liqoctl-${OS}-${ARCH}" && \
chmod +x "liqoctl-${OS}-${ARCH}" && \
sudo mv "liqoctl-${OS}-${ARCH}" /usr/local/bin/liqoctl

Alternatively, you can directly download liqoctl from the Liqo releases page on GitHub. For more information and options about Liqoctl, you can check out the related section

Command Completion (Optional)

To load completions in the current session, execute once:

source <(liqoctl completion bash)

To load completions for each session, execute once the following command:

source <(liqoctl completion bash) >> ~/.bashrc

If ZSH completion is not already enabled, you have first to execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions for each session, execute once:

liqoctl completion zsh > "${fpath[1]}/_liqoctl"
source ~/.zshrc

To load completions for the current session, execute once:

liqoctl completion fish | source

To load completions for each session, execute once:

liqoctl completion fish > ~/.config/fish/completions/liqoctl.fish

To load completions for the current session, execute once:

liqoctl completion powershell | Out-String | Invoke-Expression

To load completions for each session, execute once:

liqoctl completion powershell > liqoctl.ps1

and source this file from your PowerShell profile.

Pre-Requirements

Liqo only supports Kubernetes >= 1.19.0.

According to your cluster provider, you may have to perform simple steps before triggering the installation process:

Configuration

You only have to export the KUBECONFIG environment variable. Otherwise, liqoctl will use the kubeconfig in kubectl default path (i.e. ${HOME}/.kube/config )

kind get kubeconfig --name ${CLUSTER_NAME} > kind_kubeconfig
export KUBECONFIG=kind_kubeconfig
Supported CNIs

Liqo supports Kubernetes clusters using the following CNIs:

If you are installing Liqo on a cluster with Calico, you MUST read the dedicated configuration page to avoid unwanted misconfigurations.

Configuration

You only have to export the KUBECONFIG environment variable. Otherwise, liqoctl will use the kubeconfig in kubectl default path (i.e. ${HOME}/.kube/config )

export KUBECONFIG=/your/kubeconfig/path
Supported CNIs

Liqo supports EKS clusters using the default CNI:

Configuration

Liqo leverages AWS credentials to authenticate peered clusters. Specifically, in addition to the read-only permissions used to configure the cluster installation (i.e., retrieve the appropriate parameters), Liqo uses AWS users to map peering access to EKS clusters.

To install Liqo on EKS, you should log in using the AWS cli (if you already did that, you can skip this step). This is widely documented on the official CLI documentation.

In a nutshell, after having installed the CLI, you have to set up your identity:

aws configure

Before continuing, you should first export few variables about your cluster:

export EKS_CLUSTER_NAME=liqo-cluster # the name of the target cluster 
export EKS_CLUSTER_REGION=my-cluster # the AWS region where the cluster is deployed

Second, you should export the cluster’s KUBECONFIG if you have not already. You may use the following CLI command:

aws eks --region ${EKS_CLUSTER_REGION} update-kubeconfig --name ${EKS_CLUSTER_NAME}
Supported CNIs

Liqo supports AKS clusters using the following CNIs:

Configuration

First, you should have the AZ cli installed and your AKS cluster deployed. If you haven’t, you can follow the official guide.

Second, you should log-in:

az login

First, let’s start exporting required variables:

export AKS_RESOURCE_GROUP=myResourceGroup # the resourceGroup where the cluster is created
export AKS_RESOURCE_NAME=myCluster # the name of AKS cluster resource on Azure
export AKS_SUBSCRIPTION_ID=subscriptionId # the subscription id associated to the AKS cluster's resource group 

You also need read-only permissions on AKS cluster and on the Virtual Networks, if your cluster has an Azure CNI.

Supported CNIs

Liqo supports GKE clusters using the default CNI:

Liqo does not support GKE Autopilot Clusters

Configuration

To install Liqo on GKE, you should at first create a service account for liqoctl, granting the read rights for the GKE clusters (you may reduce the scope to a specific cluster if you prefer).

First, let’s start exporting required variables:

export GKE_SERVICE_ACCOUNT_ID=liqoctl-sa #the name of the service account used to interact by liqoctl with GCP
export GKE_PROJECT_ID=XYZ # the id of the GCP project where your cluster was created
export GKE_SERVICE_ACCOUNT_PATH=~/.liqo/gcp_service_account # the path where the google service account is stored
export GKE_CLUSTER_ZONE=europe-west-1b # the GCP zone where your GKE cluster is executed
export GKE_CLUSTER_ID=liqo-cluster # the name of the GKE resource on GCP

Second, you should create a GCP Service account. This will provide you an identity used by Liqoctl to query all the information needed to properly configure Liqo on your cluster.

The ServiceAccount can be created using:

gcloud iam service-accounts create ${GKE_SERVICE_ACCOUNT_ID} \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME" \
    --project="${GKE_PROJECT_ID}"

Third, you should provide the ServiceAccount just created with the rights to inspect the cluster and virtual networks parameters:

gcloud projects add-iam-policy-binding ${GKE_PROJECT_ID} \
    --member="serviceAccount:${GKE_SERVICE_ACCOUNT_ID}@${GKE_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/container.clusterViewer"
gcloud projects add-iam-policy-binding ${GKE_PROJECT_ID} \
    --member="serviceAccount:${GKE_SERVICE_ACCOUNT_ID}@${GKE_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/compute.networkViewer"

Fourth, you should create and download valid service accounts keys, as presented by the official documentation.

The keys will be used by liqoctl to authenticate to GCP as the service account we just created.

gcloud iam service-accounts keys create ${GKE_SERVICE_ACCOUNT_PATH} \
    --iam-account=${GKE_SERVICE_ACCOUNT_ID}@${GKE_PROJECT_ID}.iam.gserviceaccount.com

Now, you can obtain the cluster kubeconfig with the following command:

gcloud container clusters get-credentials ${GKE_CLUSTER_ID} --zone ${GKE_CLUSTER_ZONE} --project ${GKE_PROJECT_ID}

The kubeconfig will be added to the current selected file (KUBECONFIG environment variable or the default path ~/.kube/config) or created otherwise.

You are ready to start the installation.

Supported CNIs

Liqo supports K3s clusters using the following CNIs:

Configuration

You only have to export the KUBECONFIG environment variable. Otherwise, liqoctl will use the kubeconfig in kubectl default path (i.e. ${HOME}/.kube/config )

export KUBECONFIG=/your/kubeconfig/path

Liqo was tested running on OpenShift Container Platform (OCP) 4.8.

Configuration

You only have to export the KUBECONFIG environment variable. Otherwise, liqoctl will use the kubeconfig in kubectl default path (i.e. ${HOME}/.kube/config )

export KUBECONFIG=/your/kubeconfig/path

Quick Installation

Now, you can perform the proper Liqo installation on your cluster.

liqoctl install kind
liqoctl install kubeadm
liqoctl install eks --region=${EKS_CLUSTER_REGION} --eks-cluster-name=${EKS_CLUSTER_NAME} 
liqoctl install aks --resource-group-name "${AKS_RESOURCE_GROUP}" \ 
         --resource-name "${AKS_RESOURCE_NAME}" \
         --subscription-id "${AKS_SUBSCRIPTION_ID}"

liqoctl install gke --project-id ${GKE_PROJECT_ID} \
    --cluster-id ${GKE_CLUSTER_ID} \
    --zone ${GKE_CLUSTER_ZONE} \
    --credentials-path ${GKE_SERVICE_ACCOUNT_PATH}
liqoctl install k3s
liqoctl install openshift

Next Steps

After you have successfully installed Liqo, you may:

  • Configure: configure the Liqo security, the automatic discovery of new clusters and other system parameters.
  • Use Liqo: orchestrate your applications across multiple clusters.