feat: ESK guide

Signed-off-by: Piotr Zaniewski <[email protected]>

docs/_partials/kubeconfig_update.mdx

@@ -0,0 +1,4 @@
+:::tip kubeconfig update
+This command automatically updates your `kubeconfig` file with the new
+cluster configuration.
+:::

vcluster/deploy/environment/eks.mdx

@@ -0,0 +1,210 @@
+---
+title: Deploy on EKS
+sidebar_label: EKS
+sidebar_position: 8
+id: eks
+description: Learn how to deploy vCluster on Amazon EKS, including storage provisioning with EBS CSI driver and IAM role configuration.
+---
+
+import BasePrerequisites from '../../../platform/_partials/install/base-prerequisites.mdx';
+
+import Mark from "@site/src/components/Mark";
+
+import ProAdmonition from '../../_partials/admonitions/pro-admonition.mdx';
+
+import InstallCli from '../../_partials/deploy/install-cli.mdx';
+
+import KubeconfigUpdate from '../../../docs/_partials/kubeconfig_update.mdx';
+
+<!-- vale off -->
+# Deploy vCluster on EKS
+<!-- vale on -->
+
+This guide provides step-by-step instructions for deploying vCluster `vCluster` on [Amazon EKS](https://aws.amazon.com/.), including:
+
+- Setting up required AWS tools and permissions
+- Creating and configuring an EKS cluster
+- Installing the EBS CSI driver for storage
+- Configuring IAM roles and service accounts
+- Deploying and verifying your vCluster installation
+
+## Prerequisites
+
+Before staring, ensure you have the following tools installed:
+
+- `kubectl` installed: Kubernetes command-line tool for interacting with the cluster. See [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for installation instructions.
+- `vCluster CLI` <InstallCli />
+- [AWS CLI](https://aws.amazon.com/cli/) version <Mark color="lightgreen">1.16.156</Mark> or greater
+  :::note
+  AWS IAM permissions to create roles and policies
+  :::
+- [eksctl](https://eksctl.io/) installed for cluster management
+  :::note
+  [Upgrade](https://github.com/eksctl-io/eksctl?tab=readme-ov-file#installation) `eksctl` to the latest version to ensure latest Kubernetes version is
+  deployed.
+  :::
+
+## Create EKS cluster
+
+Start by creating EKS cluster using `eksctl`. This command creates a file named
+`cluster.yaml` with the required settings. Adjust the cluster name, region, and instance type as needed.
+
+```bash title="Cluster configuration file"
+CLUSTER_NAME=vcluster-demo
+REGION=eu-central-1
+INSTANCE_TYPE=t3.medium
+
+cat << EOF > cluster.yaml
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+metadata:
+ name: ${CLUSTER_NAME}
+ region: ${REGION}
+iam:
+  withOIDC: true
+nodeGroups:
+ - name: ng-1
+   instanceType: ${INSTANCE_TYPE}
+   desiredCapacity: 2
+   volumeSize: 80
+
+addons:
+- name: aws-ebs-csi-driver
+  wellKnownPolicies:      # this setting adds IAM and service account
+    ebsCSIController: true
+EOF
+```
+
+The file defines a cluster with two `t3.medium` instances in the `eu-central-1`
+region. The `aws-ebs-csi-driver` add-on is enabled to ensure EBS storage
+provisioning which is required by `vCluster` to store about virtual clusters.
+
+Create the cluster by running:
+
+```bash title="Create EKS cluster"
+eksctl create cluster -f cluster.yaml
+```
+
+<KubeconfigUpdate />
+
+This process typically takes about 15-20 minutes.
+
+### Verify the cluster creation
+
+Verify the installation by checking if the CSI driver pods are running:
+
+```bash title="Verify CSI driver installation"
+kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-ebs-csi-driver
+```
+
+Expected output should look similar to:
+```
+NAME                                 READY   STATUS    RESTARTS   AGE
+ebs-csi-controller-794b4448b-fhjxr   6/6     Running   0          2m14s
+ebs-csi-controller-794b4448b-j94g5   6/6     Running   0          2m14s
+ebs-csi-node-crz7p                   3/3     Running   0          2m14s
+ebs-csi-node-jg8n8                   3/3     Running   0          2m14s
+```
+
+### Configure storage class
+
+`vCluster` requires a default StorageClass for its persistent volumes. EKS provides the `gp2` StorageClass by default, but `gp3` is recommended for better performance and cost efficiency. Create a new StorageClass:
+
+```bash title="gp3 StorageClass configuration"
+cat <<EOF | kubectl apply -f -
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: gp3
+  annotations:
+    storageclass.kubernetes.io/is-default-class: "true"
+provisioner: ebs.csi.aws.com
+parameters:
+  type: gp3
+  encrypted: "true"
+volumeBindingMode: WaitForFirstConsumer
+allowVolumeExpansion: true
+EOF
+```
+
+Remove the default status from the `gp2` StorageClass:
+
+```bash title="Remove default status from gp2 StorageClass"
+kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'
+```
+
+### Configure workload identity
+
+Now create a service account in your `vCluster` that uses Workload Identity:
+
+```yaml title="vCluster workload service account"
+cat << 'EOF' | kubectl apply -f -
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: vcluster-workload-sa
+  namespace: default
+  annotations:
+    eks.amazonaws.com/role-arn: arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/vcluster-pod-role
+EOF
+```
+
+### Verify the Installation
+
+Check if `vCluster` pods are running:
+
+```bash title="Check vCluster pods"
+kubectl get pods -n team-x
+```
+
+You should see output similar to:
+```
+NAME                                                   READY   STATUS    RESTARTS   AGE
+coredns-666d64755b-k5njg-x-kube-system-x-my-vcluster   1/1     Running   0          3m11s
+my-vcluster-0                                          1/1     Running   0          6m33s
+```
+
+This configuration ensures that:
+- Service accounts are properly synced between virtual and host clusters
+- Persistent volume claims are handled correctly
+- The `gp3` storage class created earlier is used
+
+
+## Create virtual cluster
+
+Now that all the prerequisites are configured, create a virtual cluster
+using the CLI.
+
+```yaml title="vCluster values configuration"
+cat << 'EOF' | vcluster create my-vcluster --namespace team-x --values -
+sync:
+  toHost:
+    serviceAccounts:
+      enabled: true
+EOF
+```
+
+<KubeconfigUpdate />
+
+## Next steps
+
+Now that you have `vCluster` running on EKS, consider exploring:
+
+### Platform UI
+
+Setting up the [platform UI](/platform/install/quick-start-guide) for `vCluster`
+
+### Pod identity
+
+<ProAdmonition />
+
+For `vCluster` Pro users, you can enable [Pod
+Identity](/vcluster/integrations/pod-identity/eks-pod-identity)) to allow pods to assume IAM roles. This feature is useful for accessing AWS services securely from your pods.
+
+## Cleanup
+
+Remember to clean up resources when you're done experimenting:
+
+```bash title="Clean up resources"
+eksctl delete cluster -f cluster.yaml --disable-nodegroup-eviction
+```