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