Skip to main content
Version: main 🚧

Deploy vCluster Platform on Amazon EKS

This guide provides instructions for deploying the platform on Amazon Elastic Kubernetes Service (EKS).

Prerequisites​

Ensure you have the following:

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can verify with kubectl auth can-i create clusterrole -A

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm installed: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

  • vCluster CLI installed: 
    brew install loft-sh/tap/vcluster

    The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version
  • AWS CLI installed: Command-line tool for interacting with Amazon Web Services (AWS) resources and services. For more details on installation, see the AWS CLI user guide.
  • eksctl: Command-line utility that simplifies creating and managing Kubernetes clusters on Amazon Elastic Kubernetes Service (EKS). For more details on installation, see the eksctl documentation.
note

Ensure you have the necessary IAM permissions to create clusters and manage cloud services.

Create an AWS EKS cluster​

  1. Configure the AWS CLI.

    Run the following command and provide your AWS Access Key ID, Secret Access Key, and preferred output format when prompted:

    Configure AWS CLI
    aws configure

    This sets up local credentials in ~/.aws/credentials and stores your default region and output format in ~/.aws/config. This enables the AWS CLI and tools like eksctl to authenticate and access AWS services.

  2. Set environment variables.

    Modify the following with your specific values to generate a copyable command:
    export CLUSTER_NAME=vcluster-demo
    export REGION=eu-central-1

  3. Create an AWS EKS cluster using the eksctl CLI:

    Modify the following with your specific values to generate a copyable command:
    eksctl create cluster \
      -name=vcluster-demo \
      --enable-auto-mode \
      --region=eu-central-1
    info

    This process typically takes about 10-15 minutes.

    This command creates an AWS EKS cluster named vcluster-demo in the region eu-central-1.

    kubeconfig update

    This command automatically updates your kubeconfig file with the new cluster configuration.

  4. Verify the cluster creation.

    Verify that the AWS EKS was created successfully by getting the cluster info:

    List cluster nodes
    kubectl cluster-info

    You should see an output similar to the following:

    Example output
    Kubernetes control plane is running at https://8F3D76A1C205B94E32D18FC96E04B73D.gr7.eu-central-1.eks.amazonaws.com

Set up the platform​

After the AWS EKS cluster is running, deploy the platform.

Install the platform​

  1. Deploy the platform using the vCluster CLI:

    idempotency

    The following command is idempotent, meaning that running it again does not result it creating another cluster with the same name.

    vcluster platform start

    The command prompts you to enter the email address for the admin user:

    deployment expected output
    By providing your email, you accept our Terms of Service and Privacy Statement:
    Terms of Service: https://www.loft.sh/legal/terms
    Privacy Statement: https://www.loft.sh/legal/privacy
    ? Please specify an email address for the admin user
    tip

    If the command takes too long to execute—such as when other cluster operations are in progress—rerun the command.

  2. Connect to the platform.

    After the platform is deployed, your default browser opens with the platform UI, and you should see output similar to the following:

    platform deployment output
    ##########################   LOGIN   ############################

    Username: admin
    Password: 9758c908-b931-4edd-b3cb-3f034e50651a  # Change via UI or via: vcluster platform reset password

    Login via UI:  https://hyx4907.loft.host
    Login via CLI: vcluster platform login https://hyx4907.loft.host

    #################################################################

    vCluster Platform was successfully installed and can now be reached at: https://hyx4907.loft.host

    Thanks for using vCluster platform!
    19:34:46 done You are successfully logged into vCluster Platform!
    - Use `vcluster platform create vcluster` to create a new virtual cluster
    - Use `vcluster platform add vcluster` to add an existing virtual cluster to a vCluster platform instance

    When logging in via the UI, provide the following details:

    • First Name
    • Last Name
    • Email (pre-filled with the address you supplied earlier)
    • Organization

    To log in via the CLI, run the Login via CLI command provided above.

    This completes the basic platform deployment. For additional configuration and available features, see the Next steps section.

    You can optionally perform additional configuration steps:

Expose platform UI using the load balancer​

Optionally, you can expose the platform UI using a LoadBalancer service to make it accessible outside the cluster.

  1. Create a LoadBalancer service to expose the platform UI.

    note

    This assumes the platform is deployed in the vcluster-platform namespace which is a default deployment namespace.

    cat <<EOF | kubectl apply -f -
    apiVersion: v1
    kind: Service
    metadata:
      name: vcluster-platform-loadbalancer
      namespace: vcluster-platform
    spec:
      type: LoadBalancer
      externalTrafficPolicy: Cluster
      selector:
        app: loft
      ports:
      - name: https
        protocol: TCP
        port: 443
        targetPort: 10443
    EOF

  2. After the service is active, obtain the external IP address:

    kubectl get svc vcluster-platform-loadbalancer -n vcluster-platform

    Navigate to the IP address in your browser https://<EXTERNAL_IP>.

    tip

    The platform uses a self-signed certificate, so you must accept the warning in your browser. For production use, replace the default self-signed certificate with a valid TLS certificate.

Set up custom domain and configure DNS​

Optionally, you can set up a custom domain and configure DNS to provide a secure URL for accessing the platform.

note

This example assumes that your cluster has the AWS Load Balancer Controller installed. You must also have an SSL/TLS certificate issued by AWS Certificate Manager (ACM) that is created and verified.

  1. Configure DNS in Amazon Route 53. To use a custom domain, you must create a new Route 53 hosted zone:

    Modify the following with your specific values to generate a copyable command:
    aws route53 create-hosted-zone \
      --name=vcluster-platform.yourdomain.tld \
      --caller-reference=vcluster-demo

  2. Deploy the external-dns EKS add-on.

    This add-on automatically manages DNS records based on Kubernetes resources such as Ingress and Service. It integrates with Route 53 and eliminates the need to manually create or update DNS entries.

    Modify the following with your specific values to generate a copyable command:
    eksctl create addon \
      --name=external-dns \
      --cluster=vcluster-demo \
      --auto-apply-pod-identity-associations

  3. Create an Ingress object. Replace arn:aws:acm:region:account-id:certificate/certificate-id with the correct value of the ACM certificate Amazon Resource Name (ARN).

    Modify the following with your specific values to generate a copyable command:
    cat <<EOF | kubectl apply -f -
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
    name: vcluster-platform-ingress
    namespace: vcluster-platform
    annotations:
      kubernetes.io/ingress.class: alb
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/target-type: ip
      alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
      alb.ingress.kubernetes.io/ssl-redirect: '443'
      alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:region:account-id:certificate/certificate-id
      external-dns.alpha.kubernetes.io/hostname: vcluster-platform.yourdomain.tld
      alb.ingress.kubernetes.io/group.name: vcluster-platform
      alb.ingress.kubernetes.io/healthcheck-path: /healthz
    spec:
    rules:
    - host: vcluster-platform.yourdomain.tld
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: loft
              port:
                number: 10443
    EOF

  4. Connect the platform to the custom domain.

    After the DNS is setup, start the platform with the following command:

    vcluster platform start --host=vcluster-platform.yourdomain.tld

    info

    For more information on how to configure a custom domain, see the Configure external acess and TLS documentation.

    If you do not have a custom domain setup, follow the Set up a domain by using Cloud DNS tutorial.

Next steps​

After logging into the UI, you'll be able to start creating virtual clusters immediately. You're automatically part of a project called Default Project.

Click New Virtual Cluster and Create to spin one up to try out.

tip

Find more information about creating virtual clusters in the create virtual clusters section.

Otherwise, read more about some primary concepts:

  • Projects - How resources can be grouped together into different projects.
  • Virtual clusters - How to create and manage virtual clusters.
  • Templates - How to use templates to control what type of resources that can be made.
  • Host clusters - How to add more host clusters to the platform.
  • Sleep and wakeup - How to temporarily scale down unused virtual clusters and bring them back up.

You can also use Google as an identity provider and configure SSO to enable user authentication to the platform.

Cleanup​

If you deployed the AWS EKS cluster with this tutorial, and want to clean up the resources, run the following command:

Clean up resources
eksctl delete cluster -n $CLUSTER_NAME

Remember to clean up the ACM certificate and Route 53 hosted zone if they are no longer needed.