Skip to content

Commit d70f5c7

Browse files
committed
feat: add platform setup on aws
1 parent 41e0b61 commit d70f5c7

File tree

1 file changed

+324
-0
lines changed
  • platform/install/environments

1 file changed

+324
-0
lines changed

platform/install/environments/aws.mdx

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
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

Comments
 (0)