/
v2.4.1 Installing with x-install Tool (Kubernetes)
Document toolboxDocument toolbox

v2.4.1 Installing with x-install Tool (Kubernetes)

Owned by Yajing Wang
Last updated: Mar 07, 2025Version comment
6 min read

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 CLI

  • AWS Authentication, Credentials, and Region
    Please properly configure AWS authentication and default region in your local environment.

You can set up credentials using various methods such as command-line options, environment variables, assume role, credentials files, configuration files, etc.

  • Command-line Options

    aws configure sso
    aws s3 ls --profile profile1

  • Environment Variables

    export AWS_ACCESS_KEY_ID=<AccessKeyId> export AWS_SECRET_ACCESS_KEY=<SecretAccessKey> export AWS_SESSION_TOKEN=<SessionToken>

  • Assume role

    aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/xaccounts3access \ --role-session-name s3-access-example

  • Credentials and Configuration File:
    Update in ~/.aws/credentials and ~/.aws/config

    aws configure

Please ensure the default region is set for deployment. If not set above, use the following command:

aws configure set default.region us-east-2

Ensure the account has the following IAM permissions:

When working with standalone flow i.e., deploying everything from scratch using the create-standalone command, use the following IAM policy.

Please add your AWS account ID and cluster name to the policy below.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::<account-id>:role/<cluster-name>*", "arn:aws:iam::<account-id>:role/terraform-*" ] }, { "Effect": "Allow", "Action": [ "autoscaling:CompleteLifecycleAction", "autoscaling:CreateAutoScalingGroup", "autoscaling:DeleteAutoScalingGroup", "autoscaling:EnableMetricsCollection", "autoscaling:PutNotificationConfiguration", "autoscaling:UpdateAutoScalingGroup" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:AllocateAddress", "ec2:AssignPrivateIpAddresses", "ec2:AssociateRouteTable", "ec2:AttachInternetGateway", "ec2:AttachNetworkInterface", "ec2:AuthorizeSecurityGroupEgress", "ec2:AuthorizeSecurityGroupIngress", "ec2:CreateFleet", "ec2:CreateInternetGateway", "ec2:CreateLaunchTemplate", "ec2:CreateLaunchTemplateVersion", "ec2:CreateNatGateway", "ec2:CreateNetworkAclEntry", "ec2:CreateNetworkInterface", "ec2:CreateNetworkInterfacePermission", "ec2:CreateRoute", "ec2:CreateRouteTable", "ec2:CreateSecurityGroup", "ec2:CreateSubnet", "ec2:CreateTags", "ec2:CreateVpc", "ec2:DeleteInternetGateway", "ec2:DeleteLaunchTemplate", "ec2:DeleteNatGateway", "ec2:DeleteNetworkAclEntry", "ec2:DeleteNetworkInterface", "ec2:DeleteRoute", "ec2:DeleteRouteTable", "ec2:DeleteSecurityGroup", "ec2:DeleteSubnet", "ec2:DeleteTags", "ec2:DeleteVpc", "ec2:DescribeAddresses", "ec2:DescribeAddressesAttribute", "ec2:DescribeAvailabilityZones", "ec2:DescribeDhcpOptions", "ec2:DescribeImages", "ec2:DescribeInstanceAttribute", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInternetGateways", "ec2:DescribeKeyPairs", "ec2:DescribeLaunchTemplates", "ec2:DescribeLaunchTemplateVersions", "ec2:DescribeNatGateways", "ec2:DescribeNetworkAcls", "ec2:DescribeNetworkInterfaces", "ec2:DescribeRouteTables", "ec2:DescribeSecurityGroupRules", "ec2:DescribeSecurityGroups", "ec2:DescribeSnapshots", "ec2:DescribeSubnets", "ec2:DescribeTags", "ec2:DescribeVolumes", "ec2:DescribeVpcAttribute", "ec2:DescribeVpcs", "ec2:DetachInternetGateway", "ec2:DetachNetworkInterface", "ec2:DisassociateAddress", "ec2:DisassociateRouteTable", "ec2:ModifyInstanceAttribute", "ec2:ModifyLaunchTemplate", "ec2:ModifyNetworkInterfaceAttribute", "ec2:ModifySubnetAttribute", "ec2:ModifyVpcAttribute", "ec2:ReleaseAddress", "ec2:RevokeSecurityGroupEgress", "ec2:RevokeSecurityGroupIngress", "ec2:RunInstances", "ec2:TerminateInstances" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "eks:AssociateAccessPolicy", "eks:CreateAccessEntry", "eks:CreateAddon", "eks:CreateCluster", "eks:CreateNodegroup", "eks:DeleteAccessEntry", "eks:DeleteAddon", "eks:DeleteCluster", "eks:DeleteNodegroup", "eks:DescribeAccessEntry", "eks:DescribeAddon", "eks:DescribeAddonVersions", "eks:DescribeCluster", "eks:DescribeNodegroup", "eks:DisassociateAccessPolicy", "eks:ListAssociatedAccessPolicies", "eks:ListNodegroups", "eks:TagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "events:PutRule", "events:PutTargets" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreateOpenIDConnectProvider", "iam:CreatePolicy", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeleteOpenIDConnectProvider", "iam:DeletePolicy", "iam:DeleteRole", "iam:DeleteRolePolicy", "iam:DetachRolePolicy", "iam:GetInstanceProfile", "iam:GetOpenIDConnectProvider", "iam:GetPolicy", "iam:GetPolicyVersion", "iam:GetRole", "iam:GetRolePolicy", "iam:ListAttachedRolePolicies", "iam:ListInstanceProfilesForRole", "iam:ListPolicyVersions", "iam:ListRolePolicies", "iam:PutRolePolicy", "iam:RemoveRoleFromInstanceProfile", "iam:TagInstanceProfile", "iam:TagOpenIDConnectProvider", "iam:TagPolicy", "iam:TagRole" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "kms:CreateAlias", "kms:CreateGrant", "kms:CreateKey", "kms:DeleteAlias", "kms:DescribeKey", "kms:EnableKeyRotation", "kms:GetKeyPolicy", "kms:GetKeyRotationStatus", "kms:ListAliases", "kms:ListResourceTags", "kms:PutKeyPolicy", "kms:RetireGrant", "kms:ScheduleKeyDeletion", "kms:TagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DeleteLogGroup", "logs:DescribeLogGroups", "logs:ListTagsForResource", "logs:PutRetentionPolicy", "logs:TagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "aws-marketplace:ListEntities" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ssm:RegisterManagedInstance", "ssm:UpdateInstanceInformation" ], "Resource": "*" } ] }

When working with existing EKS clusters, use the following IAM policy.

Please add your AWS account ID and cluster name to the policy below.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::<account-id>:role/<cluster-name>*", "arn:aws:iam::<account-id>:role/terraform-*" ] }, { "Effect": "Allow", "Action": [ "aws-marketplace:ListEntities" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:AuthorizeSecurityGroupEgress", "ec2:AuthorizeSecurityGroupIngress", "ec2:CreateSecurityGroup", "ec2:CreateTags", "ec2:DeleteSecurityGroup", "ec2:DescribeDhcpOptions", "ec2:DescribeImages", "ec2:DescribeInstanceAttribute", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInternetGateways", "ec2:DescribeNatGateways", "ec2:DescribeNetworkInterfaces", "ec2:DescribeRouteTables", "ec2:DescribeSecurityGroups", "ec2:DescribeSnapshots", "ec2:DescribeSubnets", "ec2:DescribeTags", "ec2:DescribeVolumes", "ec2:DescribeVpcAttribute", "ec2:DescribeVpcs", "ec2:ModifyInstanceAttribute", "ec2:RevokeSecurityGroupEgress", "ec2:RunInstances", "ec2:TerminateInstances" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "eks:DescribeCluster", "eks:DescribeNodegroup", "eks:ListNodegroups" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeleteRole", "iam:DeleteRolePolicy", "iam:DetachRolePolicy", "iam:GetInstanceProfile", "iam:GetPolicy", "iam:GetPolicyVersion", "iam:GetRole", "iam:GetRolePolicy", "iam:ListAttachedRolePolicies", "iam:ListInstanceProfilesForRole", "iam:ListRolePolicies", "iam:PutRolePolicy", "iam:RemoveRoleFromInstanceProfile", "iam:TagInstanceProfile", "iam:TagRole" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": "*" } ] }

Use the following command to create a new SSH key pair:

aws ec2 create-key-pair --key-name 'my-dev-key' --query 'KeyMaterial' --output text --region us-east-2 > my-dev-key.pem

Modify the permission to secure the key:

chmod 400 my-dev-key.pem

  • x-install tool: Version 0.0.17+

Platform

Architecture

File

Release Date

Platform

Architecture

File

Release Date

macOS

ARM64

Feb 24, 2025

macOS

x86_64

Feb 24, 2025

Linux

ARM64

Feb 24, 2025

Linux

i386

Feb 24, 2025

Linux

x86_64

Feb 24, 2025

Windows

ARM64

Feb 24, 2025

Windows

i386

Feb 24, 2025

Windows

x86_64

Feb 24, 2025

For macOS users, please grant x-install permissions by clicking the “Allow Anyway” button in the Security settings. This button is available for about an hour after you try to open the app. You can access the Security settings by choosing Apple Menu > System Settings, then clicking Privacy & Security in the sidebar.

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:

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:

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:

x-install post-install --cluster=xio-standalone --ssh-private-key-file=my-dev-key.pem --ssh-username=rocky

It might take a few attempts for post-install to pass all system units and containers readiness checks, due to infrastructure readiness latency.

Deploying the Management Server into an Existing EKS Cluster

1. Add Necessary IAM Permissions

Ensure all required IAM resources are present by running:

x-install apply-iam --cluster xio-standalone --region us-east-2

2. Check the Target Environment

Verify the existing EKS cluster meets installation prerequisites:

x-install precheck --cluster xio-standalone --region us-east-2 --ssh-key-pair-name=my-dev-key.pem

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:

x-install apply --cluster xio-standalone

4. Integrate the Management Server with the Existing EKS Cluster

Run the following command to complete the integration:

x-install eksconfig --cluster xio-standalone

To update the integration configurations:

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:

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:

eks-node-cli add -n node-00 -c 1 -m 4096 -p pool-a -r az1 -k xio-standalone

The new node can be verified using the kubectl command:

kubectl get node -l eks.amazonaws.com/nodegroup=x-compute

The output should display the new nodes as ready:

NAME STATUS ROLES AGE VERSION ip-10-0-39-220.us-west-1.x-compute.internal Ready <none> 4m17s v1.29.3-eks-ae9a62a

Please ensure ~/.kube/config is set up properly. It takes a couple of minutes for the x-compute node to boot and show up.

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:

x-install update-kubeconfig --cluster=xio-standalone

Adding X-Compute Nodes to the EKS Cluster via Exostellar Karpenter

Reference deployment example:

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 image: nginx:1.14.2 ports: - containerPort: 80 resources: requests: cpu: 1 EOF

Cleaning Up

The entire standalone stack can be deleted with the destroy command:

x-install destroy --cluster=xio-standalone

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:

x-install --help

If you encounter any issues, please take a screenshot of your x-install output and download your ~/.xio/ folder. Then, submit both to Exostellar Customer Support for further assistance.

Related content