|
| 1 | +--- |
| 2 | +title: Deploy vCluster Platform on Amazon EKS |
| 3 | +sidebar_label: EKS |
| 4 | +sidebar_position: 4 |
| 5 | +description: Learn how to deploy and configure vCluster Platform on AWS using EKS. |
| 6 | +--- |
| 7 | + |
| 8 | +import Image from "@site/src/components/Image"; |
| 9 | +import InstallNextSteps from "../../_partials/install/install-next-steps.mdx"; |
| 10 | +import ListHelmVersions from '../../_partials/install/list-helm-versions.mdx'; |
| 11 | +import BasePrerequisites from '../../_partials/install/base-prerequisites.mdx'; |
| 12 | +import InstallCli from '../../../vcluster/_partials/deploy/install-cli.mdx'; |
| 13 | +import KubeconfigUpdate from '../../../docs/_partials/kubeconfig_update.mdx'; |
| 14 | +import ProAdmonition from '../../../vcluster/_partials/admonitions/pro-admonition.mdx'; |
| 15 | +import InterpolatedCodeBlock from "@site/src/components/InterpolatedCodeBlock"; |
| 16 | + |
| 17 | +import Flow, { Step } from '@site/src/components/Flow'; |
| 18 | + |
| 19 | +import Label from '@site/src/components/Label'; |
| 20 | + |
| 21 | + |
| 22 | +This guide provides instructions for deploying the platform on [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | + |
| 26 | +Ensure you have the following: |
| 27 | +<BasePrerequisites /> |
| 28 | +- vCluster CLI installed: <InstallCli /> |
| 29 | +- `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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). |
| 30 | +- `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](https://eksctl.io/installation/). |
| 31 | +:::note |
| 32 | +Ensure you have the necessary IAM permissions to create clusters and manage cloud services. |
| 33 | +::: |
| 34 | + |
| 35 | +## Create an AWS EKS cluster |
| 36 | + |
| 37 | +<Flow id="create-eks-cluster"> |
| 38 | + |
| 39 | +<Step> |
| 40 | +Configure the AWS CLI. |
| 41 | + |
| 42 | +Run the following command and provide your AWS Access Key ID, Secret Access Key, and preferred output format when prompted: |
| 43 | + |
| 44 | +```bash title="Configure AWS CLI" |
| 45 | +aws configure |
| 46 | +``` |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +</Step> |
| 51 | + |
| 52 | +<Step> |
| 53 | +Set environment variables. |
| 54 | + |
| 55 | +<!-- vale off --> |
| 56 | +<InterpolatedCodeBlock |
| 57 | + code={ |
| 58 | +`export CLUSTER_NAME=[[VAR:CLUSTER_NAME:vcluster-demo]] |
| 59 | +export REGION=[[VAR:REGION:eu-central-1]]` |
| 60 | + } |
| 61 | + language="bash" |
| 62 | + title="Set environment variables" |
| 63 | +/> |
| 64 | +</Step> |
| 65 | + |
| 66 | +<Step> |
| 67 | +[Create an AWS EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html) using the `eksctl` CLI: |
| 68 | + |
| 69 | +<InterpolatedCodeBlock |
| 70 | + code={ |
| 71 | +`eksctl create cluster \\ |
| 72 | + -name=[[VAR:CLUSTER_NAME:vcluster-demo]] \\ |
| 73 | + --enable-auto-mode \\ |
| 74 | + --region=[[VAR:REGION:eu-central-1]]` |
| 75 | + } |
| 76 | + language="bash" |
| 77 | + title="Create AWS EKS cluster" |
| 78 | +/> |
| 79 | + |
| 80 | +:::info |
| 81 | +This process typically takes about 10-15 minutes. |
| 82 | +::: |
| 83 | + |
| 84 | +This command creates an AWS EKS cluster named `vcluster-demo` in the region `eu-central-1`. |
| 85 | + |
| 86 | +<KubeconfigUpdate /> |
| 87 | + |
| 88 | +</Step> |
| 89 | + |
| 90 | +<Step> |
| 91 | +Verify the cluster creation. |
| 92 | + |
| 93 | +Verify that the AWS EKS was created successfully by getting the cluster info: |
| 94 | + |
| 95 | +```bash title="List cluster nodes" |
| 96 | +kubectl cluster-info |
| 97 | +``` |
| 98 | + |
| 99 | +You should see an output similar to the following: |
| 100 | + |
| 101 | +```bash title="Example output" |
| 102 | +Kubernetes control plane is running at https://8F3D76A1C205B94E32D18FC96E04B73D.gr7.eu-central-1.eks.amazonaws.com |
| 103 | +``` |
| 104 | +</Step> |
| 105 | + |
| 106 | +</Flow> |
| 107 | + |
| 108 | +## Set up the platform |
| 109 | + |
| 110 | +After the AWS EKS cluster is running, deploy the platform. |
| 111 | + |
| 112 | +### Install the platform |
| 113 | + |
| 114 | +<Flow> |
| 115 | + |
| 116 | +<Step> |
| 117 | +[Deploy the platform](/platform/install/quick-start-guide) using the vCluster CLI: |
| 118 | + |
| 119 | +:::note idempotency |
| 120 | +The following command is _idempotent_, meaning that running it again does |
| 121 | +not result it creating another cluster with the same name. |
| 122 | +::: |
| 123 | + |
| 124 | +```bash title="Deploy the platform using the vCluster CLI |
| 125 | +vcluster platform start |
| 126 | +``` |
| 127 | +The command prompts you to enter the email address for the admin user: |
| 128 | + |
| 129 | +```bash title="deployment expected output" |
| 130 | +By providing your email, you accept our Terms of Service and Privacy Statement: |
| 131 | +Terms of Service: https://www.loft.sh/legal/terms |
| 132 | +Privacy Statement: https://www.loft.sh/legal/privacy |
| 133 | +? Please specify an email address for the admin user |
| 134 | +``` |
| 135 | + |
| 136 | +:::tip |
| 137 | +If the command takes too long to execute—such as when other cluster operations are in progress—rerun the command. |
| 138 | +::: |
| 139 | +</Step> |
| 140 | + |
| 141 | +<Step> |
| 142 | +Connect to the platform. |
| 143 | + |
| 144 | +After the platform is deployed, your default browser opens with the platform UI, and you should see output similar to the following: |
| 145 | + |
| 146 | + |
| 147 | +```bash title="platform deployment output" |
| 148 | +########################## LOGIN ############################ |
| 149 | + |
| 150 | +Username: admin |
| 151 | +Password: 9758c908-b931-4edd-b3cb-3f034e50651a # Change via UI or via: vcluster platform reset password |
| 152 | + |
| 153 | +Login via UI: https://hyx4907.loft.host |
| 154 | +Login via CLI: vcluster platform login https://hyx4907.loft.host |
| 155 | + |
| 156 | +################################################################# |
| 157 | + |
| 158 | +vCluster Platform was successfully installed and can now be reached at: https://hyx4907.loft.host |
| 159 | + |
| 160 | +Thanks for using vCluster platform! |
| 161 | +19:34:46 done You are successfully logged into vCluster Platform! |
| 162 | +- Use `vcluster platform create vcluster` to create a new virtual cluster |
| 163 | +- Use `vcluster platform add vcluster` to add an existing virtual cluster to a vCluster platform instance |
| 164 | +``` |
| 165 | + |
| 166 | +When logging in via the UI, provide the following details: |
| 167 | + |
| 168 | +- **First Name** |
| 169 | +- **Last Name** |
| 170 | +- **Email** (pre-filled with the address you supplied earlier) |
| 171 | +- **Organization** |
| 172 | + |
| 173 | +To log in via the CLI, run the `Login via CLI` command provided above. |
| 174 | + |
| 175 | +This completes the basic platform deployment. For additional configuration and available features, see the [Next steps section](#post-install-steps). |
| 176 | + |
| 177 | +You can _optionally_ perform additional configuration steps: |
| 178 | + |
| 179 | +- [Expose the platform UI using the load balancer](#load-balancer) |
| 180 | +- [Set up a custom domain and configure DNS](#setup-domain-dns) |
| 181 | +</Step> |
| 182 | +</Flow> |
| 183 | + |
| 184 | + |
| 185 | +### Expose platform UI using the load balancer {#load-balancer} |
| 186 | + |
| 187 | +Optionally, you can expose the platform UI using a LoadBalancer service to make it accessible outside the cluster. |
| 188 | + |
| 189 | +<Flow> |
| 190 | +<Step> |
| 191 | +Create a LoadBalancer service to expose the platform UI. |
| 192 | + |
| 193 | +:::note |
| 194 | +This assumes the platform is deployed in the `vcluster-platform` namespace which is a |
| 195 | +default deployment namespace. |
| 196 | +::: |
| 197 | + |
| 198 | +```bash |
| 199 | +cat <<EOF | kubectl apply -f - |
| 200 | +apiVersion: v1 |
| 201 | +kind: Service |
| 202 | +metadata: |
| 203 | + name: vcluster-platform-loadbalancer |
| 204 | + namespace: vcluster-platform |
| 205 | +spec: |
| 206 | + type: LoadBalancer |
| 207 | + externalTrafficPolicy: Cluster |
| 208 | + selector: |
| 209 | + app: loft |
| 210 | + ports: |
| 211 | + - name: https |
| 212 | + protocol: TCP |
| 213 | + port: 443 |
| 214 | + targetPort: 10443 |
| 215 | +EOF |
| 216 | +``` |
| 217 | +</Step> |
| 218 | + |
| 219 | +<Step> |
| 220 | +After the service is active, obtain the external IP address: |
| 221 | + |
| 222 | +```bash |
| 223 | +kubectl get svc vcluster-platform-loadbalancer -n vcluster-platform |
| 224 | +``` |
| 225 | + |
| 226 | +Navigate to the IP address in your browser `https://<EXTERNAL_IP>`. |
| 227 | + |
| 228 | +:::tip |
| 229 | +The platform uses a self-signed certificate, so you must |
| 230 | +accept the warning in your browser. For production use, replace the default self-signed certificate with a valid [TLS certificate](/platform/configure/domain#configure-tls). |
| 231 | +::: |
| 232 | +</Step> |
| 233 | +</Flow> |
| 234 | + |
| 235 | + |
| 236 | +### Set up custom domain and configure DNS {#setup-domain-dns} |
| 237 | + |
| 238 | +Optionally, you can set up a custom domain and configure DNS to provide a secure URL for accessing the platform. |
| 239 | + |
| 240 | +:::note |
| 241 | +This example assumes that your cluster has the [AWS Load Balancer Controller](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/) installed. |
| 242 | +You must also have an SSL/TLS certificate issued by [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) that is [created and verified](https://docs.aws.amazon.com/acm/latest/userguide/setup.html). |
| 243 | +::: |
| 244 | + |
| 245 | +<Flow> |
| 246 | +<Step> |
| 247 | +Configure DNS in Amazon Route 53. |
| 248 | +To use a custom domain, you must create a new Route 53 hosted zone: |
| 249 | + |
| 250 | +<InterpolatedCodeBlock |
| 251 | + code={ |
| 252 | +`aws route53 create-hosted-zone \\ |
| 253 | + --name=[[VAR:DOMAIN NAME:vcluster-platform.yourdomain.tld]] \\ |
| 254 | + --caller-reference=[[VAR:CALLER REFERENCE:vcluster-demo]]`} |
| 255 | + language="bash" |
| 256 | + title="Create a Route 53 Hosted Zone" |
| 257 | +/> |
| 258 | +</Step> |
| 259 | + |
| 260 | +<Step> |
| 261 | +Deploy the `external-dns` EKS add-on. |
| 262 | + |
| 263 | +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. |
| 264 | + |
| 265 | +<InterpolatedCodeBlock |
| 266 | + code={ |
| 267 | +`eksctl create addon \\ |
| 268 | + --name=external-dns \\ |
| 269 | + --cluster=[[VAR:CLUSTER_NAME:vcluster-demo]] \\ |
| 270 | + --auto-apply-pod-identity-associations`} |
| 271 | + language="bash" |
| 272 | + title="Deploy external-dns" |
| 273 | +/> |
| 274 | +</Step> |
| 275 | + |
| 276 | +<Step> |
| 277 | +Create an `Ingress` object. |
| 278 | +Replace `arn:aws:acm:region:account-id:certificate/certificate-id` with the correct value of the ACM certificate Amazon Resource Name (ARN). |
| 279 | + |
| 280 | +<InterpolatedCodeBlock |
| 281 | + code={ |
| 282 | +`cat <<EOF | kubectl apply -f - |
| 283 | +apiVersion: networking.k8s.io/v1 |
| 284 | +kind: Ingress |
| 285 | +metadata: |
| 286 | + name: [[VAR:INGRESS NAME:vcluster-platform-ingress]] |
| 287 | + namespace: [[VAR:NAMESPACE:vcluster-platform]] |
| 288 | + annotations: |
| 289 | + kubernetes.io/ingress.class: alb |
| 290 | + alb.ingress.kubernetes.io/scheme: internet-facing |
| 291 | + alb.ingress.kubernetes.io/target-type: ip |
| 292 | + alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]' |
| 293 | + alb.ingress.kubernetes.io/ssl-redirect: '443' |
| 294 | + alb.ingress.kubernetes.io/certificate-arn: [[VAR:ACM CERTIFICATE ARN:arn:aws:acm:region:account-id:certificate/certificate-id]] |
| 295 | + external-dns.alpha.kubernetes.io/hostname: [[VAR:DNS HOSTNAME:vcluster-platform.yourdomain.tld]] |
| 296 | + alb.ingress.kubernetes.io/group.name: [[VAR:ALB GROUP NAME:vcluster-platform]] |
| 297 | + alb.ingress.kubernetes.io/healthcheck-path: [[VAR:HEALTHCHECK PATH:/healthz]] |
| 298 | +spec: |
| 299 | + rules: |
| 300 | + - host: [[VAR:DNS HOSTNAME:vcluster-platform.yourdomain.tld]] |
| 301 | + http: |
| 302 | + paths: |
| 303 | + - path: / |
| 304 | + pathType: Prefix |
| 305 | + backend: |
| 306 | + service: |
| 307 | + name: [[VAR:SERVICE NAME:loft]] |
| 308 | + port: |
| 309 | + number: [[VAR:SERVICE PORT:10443]] |
| 310 | +EOF`} |
| 311 | + language="bash" |
| 312 | + title="Create Ingress for platform UI" |
| 313 | +/> |
| 314 | +</Step> |
| 315 | + |
| 316 | +<Step> |
| 317 | +Connect the platform to the custom domain. |
| 318 | + |
| 319 | +After the DNS is setup, start the platform with the following command: |
| 320 | + |
| 321 | +`vcluster platform start --host=vcluster-platform.yourdomain.tld` |
| 322 | + |
| 323 | +:::info |
| 324 | +For more information on how to configure a custom domain, see the [Configure external acess and TLS documentation](/platform/configure/domain). |
| 325 | + |
| 326 | +If you do not have a custom domain setup, follow the [Set up a domain by using Cloud DNS |
| 327 | +tutorial](https://cloud.google.com/dns/docs/tutorials/create-domain-tutorial). |
| 328 | +::: |
| 329 | + |
| 330 | +</Step> |
| 331 | + |
| 332 | +</Flow> |
| 333 | + |
| 334 | +## Next steps {#post-install-steps} |
| 335 | + |
| 336 | +<InstallNextSteps /> |
| 337 | + |
| 338 | +You can also use Google as an identity provider and [configure SSO](/platform/configure/single-sign-on/providers/google) to enable user |
| 339 | +authentication to the platform. |
| 340 | + |
| 341 | +## Cleanup |
| 342 | + |
| 343 | +If you deployed the AWS EKS cluster with this tutorial, and want to clean up the resources, run the |
| 344 | +following command: |
| 345 | + |
| 346 | +```bash title="Clean up resources" |
| 347 | +eksctl delete cluster -n $CLUSTER_NAME |
| 348 | +``` |
| 349 | +Remember to clean up the ACM certificate and Route 53 hosted zone if they are no longer needed. |
0 commit comments