The x-install tool is the newest Exostellar installer designed to simplify the setup process. It offers a variety of subcommands to provision a sandbox environment, install Exostellar products, and verify post-installation readiness.
Prerequisites
Before using the x-install tool, ensure that your environment meets the following requirements:
Terraform: Version 1.8+
kubectl: Version 1.28+
Helm: Version 3.14.2+
AWS Authentication, Credentials, and CredentialsRegion
Please properly configure AWS authentication and default region in your local environment.
| Expand | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
| Expand | ||||||||||||||||||||||
| ||||||||||||||||||||||
You can set up credentials using various methods such as command-line options, environment variables, assume role, credentials files, configuration files, etc.
|
AWS Account
Ensure the following IAM permissions are in place:
|
Ensure the account has the following IAM permissions:
| Expand | |||||
|---|---|---|---|---|---|
| |||||
When working with standalone flow i.e., deploying everything from scratch using the Please add your AWS account ID and cluster name to the policy below.
|
Valid AWS Marketplace Subscriptions for Exostellar Management Server, Exostellar Controller, Exostellar Worker AMIs
SSH Key
| Expand | ||||
|---|---|---|---|---|
| ||||
Use the following command to create a new SSH key pair:
Modify the permission to secure the key:
|
x-installtool: Version 0.0.10+
...
| title | x-install Download Options |
|---|
...
Platform
...
Architecture
...
File
...
Release Date
...
macOS
...
ARM64
...
| View file | ||
|---|---|---|
|
...
...
macOS
...
x86_64
...
| View file | ||
|---|---|---|
|
...
...
Linux
...
ARM64
...
| View file | ||
|---|---|---|
|
...
...
Linux
...
i386
...
| View file | ||
|---|---|---|
|
...
...
Linux
...
x86_64
...
| View file | ||
|---|---|---|
|
...
...
Windows
...
ARM64
...
| View file | ||
|---|---|---|
|
...
...
Windows
...
i386
...
| View file | ||
|---|---|---|
|
...
...
Windows
...
x86_64
...
| View file | ||
|---|---|---|
|
...
| Info |
|---|
For macOS users, please grant |
Installation Steps
1. Create a Standalone Stack
Use the following command to create a standalone stack:
(Please modify the stack name, VPC CIDR, SSH key pair, and region to suit your environment.)
| Code Block | ||
|---|---|---|
| ||
x-install create-standalone \
--stack-name=xio-standalone \
--vpc-cidr=10.0.0.0/16 \
--ssh-key-pair-name=my-dev-key \
--region=us-east-2 |
The new VPC and EKS cluster will inherit the stack name.
The VPC will be assigned the CIDR block
10.0.0.0/16.The EC2 SSH key pair,
my-dev-key, will be used to access the Exostellar Management Server.
2. Verify Post-Installation Readiness
After the standalone stack is successfully created, use the following command to check if the stack is ready:
| Code Block | ||
|---|---|---|
| ||
x-install post-install --stack-name=xio-standalone --ssh-private-key-file=my-dev-key.pem --ssh-username=rocky |
| Info |
|---|
It might take a few attempts for |
3. Add an X-Compute Node to the Standalone EKS Cluster
To add an X-Compute node to the newly created standalone EKS cluster, first SSH into the Exostellar Management Server:
| Code Block |
|---|
ssh -i "my-dev-key.pem" rocky@<management-server-public-ip> |
On the server, run the following command to add a new node to the EKS cluster:
| Code Block | ||
|---|---|---|
| ||
eks-node-cli add -n node-00 -c 1 -m 4096 -p pool-a -r az1 -k xio-standalone |
| Tip | ||
|---|---|---|
The new node can be verified using the
Please ensure |
The output should display the new nodes as ready:
| Code Block | |
|---|---|
NAME
|
| Expand | |||||
|---|---|---|---|---|---|
| |||||
When working with existing EKS clusters, use the following IAM policy. Please add your AWS account ID and cluster name to the policy below.
|
Valid AWS Marketplace Subscriptions for Exostellar Management Server, Exostellar Controller, Exostellar Worker AMIs for the same AWS account
SSH Key
| Expand | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Use the following command to create a new SSH key pair:
Modify the permission to secure the key:
|
x-installtool: Version 0.0.15+
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Installation Steps
Creating a Sandbox EKS Cluster and Deploying the Management Server
1. Create a Standalone Stack
Navigate to the directory where x-install is downloaded and use the following command to create a standalone stack, customizing the cluster name, VPC CIDR, SSH key pair, and region to suit your environment:
| Code Block | ||
|---|---|---|
| ||
x-install create-standalone \
--cluster=xio-standalone \
--vpc-cidr=10.0.0.0/16 \
--ssh-key-pair-name=my-dev-key \
--region=us-east-2 |
The new VPC and EKS cluster will inherit the stack name.
The VPC will be assigned the CIDR block
10.0.0.0/16.The EC2 SSH key pair,
my-dev-key, will be used to access the Exostellar Management Server.
By default, x-install auto-detects the latest Management Server AMI in the region within the AWS account. To specify a version or custom AMI ID, use --mgmt-server-ami-id:
| Code Block | ||
|---|---|---|
| ||
x-install create-standalone \
--cluster=xio-standalone \
--vpc-cidr=10.0.0.0/16 \
--ssh-key-pair-name=my-dev-key \
--region=us-east-2 \
--mgmt-server-ami-id=ami-053b51fb9abf27xxx |
2. Verify Post-Installation Readiness
After the standalone stack is successfully created, use the following command to check if the stack is ready:
| Code Block | ||
|---|---|---|
| ||
x-install post-install --cluster=xio-standalone --ssh-private-key-file=my-dev-key.pem --ssh-username=rocky |
| Info |
|---|
It might take a few attempts for |
Deploying the Management Server into an Existing EKS Cluster
1. Add Necessary IAM Permissions
Ensure all required IAM resources are present by running:
| Code Block | ||
|---|---|---|
| ||
x-install apply-iam --cluster xio-standalone --region us-east-2 |
2. Check the Target Environment
Verify the existing EKS cluster meets installation prerequisites:
| Code Block | ||
|---|---|---|
| ||
x-install precheck --cluster xio-standalone --region us-east-2 --ssh-key-pair-name=my-dev-key.pem |
| Info |
|---|
Please refer to this for the IAM roles required for the cluster’s node group. |
3. Install the Management Server
Deploy the Management Server into the existing EKS Cluster:
| Code Block | ||
|---|---|---|
| ||
x-install apply --cluster xio-standalone |
4. Integrate the Management Server with the Existing EKS Cluster
Run the following command to complete the integration:
| Code Block | ||
|---|---|---|
| ||
x-install eksconfig --cluster xio-standalone |
To update the integration configurations:
| Code Block | ||
|---|---|---|
| ||
x-install eksconfig --cluster xio-standalone --override-existing-params |
Adding X-Compute Nodes to the EKS Cluster via eks-node-cli
1. Access the Management Server
SSH into the Exostellar Management Server using:
| Code Block | ||
|---|---|---|
| ||
ssh -i "my-dev-key.pem" rocky@<management-server-public-ip> |
2. Add a New Node
Run this command on the server to add a new node to the EKS cluster:
| Code Block | ||
|---|---|---|
| ||
eks-node-cli add -n node-00 -c 1 -m 4096 -p pool-a -r az1 -k xio-standalone |
| Tip | ||||
|---|---|---|---|---|
The new node can be verified using the
The output should display the new nodes as ready:
Please ensure |
By default, the EKS token used to access the standalone EKS cluster expired after 60 minutes. Following that, all attempts to access the cluster will fail with Unauthorized errors.
To generate a new EKS token and use it with your existing kubeconfig file, run:
| Code Block | ||
|---|---|---|
| ||
x-install update-kubeconfig --cluster=xio-standalone |
Adding X-Compute Nodes to the EKS Cluster via Exostellar Karpenter
Reference deployment example:
| Code Block | ||
|---|---|---|
| ||
cat <<EOF | kubectl apply -f - apiVersion: apps/v1 kind: Deployment metadata: name: nginx spec: selector: matchLabels: app: nginx replicas: 2 template: metadata: labels: app: nginx spec: tolerations: - key: "exokarpenter.sh/x-compute" operator: "Exists" effect: "NoSchedule" affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: exokarpenter.sh/nodepool operator: In values: - pool-a containers: - name: nginx STATUSimage: nginx:1.14.2 ROLES ports: AGE VERSION ip-10-0-39-220.us-west-1.x-compute.internal Ready- containerPort: 80 resources: <none> requests: 4m17s v1.29.3-eks-ae9a62a |
By default, the EKS token used to access the standalone EKS cluster expired after 60 minutes. Following that, all attempts to access the cluster will fail with Unauthorized errors.
To generate a new EKS token and use it with your existing kubeconfig file, run:
| Code Block | ||
|---|---|---|
| ||
x-install update-kubeconfig --stack-name=xio-standalone |
4. Clean Up
...
cpu: 1
EOF |
Cleaning Up
The entire standalone stack can be deleted with the destroy command:
| Code Block | ||
|---|---|---|
| ||
x-install destroy --stack-name cluster=xio-standalone |
| Info |
|---|
In some cases, Terraform might time out during the destroy process. If this happens, simply re-run the command to allow Terraform to reconcile its final state. At this time, all controllers and workers EC2 instances need to be manually terminated. |
Additional Help and Support
To explore other subcommands, use the following command for a list of available options:
| Code Block |
|---|
x-install --help |
| Info |
|---|
If you encounter any issues, please take a screenshot of your |