Skip to content

Commit ab9a953

Browse files
feat: add platform setup on aws (#752)
--------- Co-authored-by: Joan E <[email protected]>
1 parent 917d80a commit ab9a953

File tree

1 file changed

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

1 file changed

+349
-0
lines changed

platform/install/environments/aws.mdx

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

Comments
 (0)