Skip to main content
Skip table of contents

Installing with x-install Tool (Kubernetes)

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.

AWS Authentication and Credentials Setup Methods

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

    BASH 
    aws configure sso
    BASH 
    aws s3 ls --profile profile1

  • Environment Variables

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

  • Assume role

    CODE 
    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

    BASH 
    aws configure

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

BASH 
aws configure set default.region us-east-2

Ensure the account has the following IAM permissions:

IAM Permissions for the AWS Account - Standalone Flow

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.

JSON 
{
	"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": "*"
		}
	]
}
IAM Permissions for the AWS Account - Using an Existing Cluster

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

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

JSON 
{
	"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": "*"
		}
	]
}
SSH Key Creation

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

BASH 
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:

BASH 
chmod 400 my-dev-key.pem

  • x-install tool: Version 0.0.21 +

x-install Download Options

Platform

Architecture

File

Release Date

macOS

ARM64

x-install-darwin-arm64-.0.0.21.tar.gz

macOS

x86_64

x-install-darwin-x86_64-.0.0.21.tar.gz

Linux

ARM64

x-install-linux-arm64-.0.0.21.tar.gz

Linux

i386

x-install-linux-i386-.0.0.21.tar.gz

Linux

x86_64

x-install-linux-x86_64-.0.0.21.tar.gz

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.

  • If using an existing cluster for installation, note that it has:

    • Strictly enabled API. Since the aws-auth configMap approach is deprecated as mentioned here, starting x-install 0.0.21, only API access mode is accepted.

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:

BASH 
x-install create-standalone \
    --cluster "xio-standalone" \
    --region "us-east-2" \
    --vpc-cidr "10.0.0.0/16" \
    --ssh-key-pair-name "my-dev-key" \
    --apply-timeout "1h"

The flag --ssh-key-pair-name takes the name of the SSH key-pair that already exists in AWS.

  • The new VPC and EKS cluster will inherit the cluster 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 flag:

CODE 
x-install create-standalone \
    --cluster "xio-standalone" \
    --region "us-east-2" \
    --vpc-cidr "10.0.0.0/16" \
    --ssh-key-pair-name "my-dev-key" \
    --apply-timeout "1h"
    --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:

BASH 
x-install post-install \
    --cluster "xio-standalone" \
    --ssh-username "rocky" \
    --ssh-private-key-file "/path/to/my-dev-key.pem"

The flag --ssh-private-key-file takes the name or full path to the SSH private key of the key-pair specified with create-standalone.

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

3. Update EKS Token

By default, the EKS token expires in 60 minutes. All attempts to access the cluster will fail with Unauthorized errors. To refresh the token, run:

BASH 
x-install update-kubeconfig \
    --cluster "xio-standalone"

x-install update-kubeconfig calls the aws eks update-kubeconfig under the hood, which refreshes the EKS token, alters current-context (if set to something else than xio-standalone), etc. For full info on this, check the doc on update-kubeconfig.

Deploying the Exostellar Management Server (EMS) into an Existing EKS Cluster

1. Add Necessary IAM Permissions

Ensure all required IAM resources are present by running:

BASH 
x-install apply-iam \
    --cluster "xio-integrated" \
    --region "us-east-2" \
    --apply-timeout "1h"

2. Check the Target Environment

Verify the existing EKS cluster meets installation prerequisites:

BASH 
x-install precheck \
    --cluster "xio-integrated" \
    --region "us-east-2" \
    --ssh-key-pair-name "my-dev-key"

Note: All precheck conditions must be satisfied before proceeding to the next steps. There should be no warnings or failures with precheck.

Recommendation:

It is highly recommended to check the generated Terraform config file at $HOME/.xio/xio-standalone/xio.state/main.tf. This file contains all parameters that will be used during installation. Please pay close attention to:

  • Subnet IDs

  • Security Groups

  • IAM Roles

Please refer to this for the IAM roles required for the cluster’s node group.

3. Install the Exostellar Management Server (EMS)

Deploy the Management Server into the existing EKS Cluster:

BASH 
x-install apply \
    --cluster "xio-integrated"

4. Configure the existing EKS cluster to integrate the Exostellar Management Server (EMS) with it

Run the following command to complete the integration:

BASH 
x-install eksconfig \
    --cluster "xio-integrated"

5. Verify Post-Installation Readiness

After the successful integration with the existing cluster, use the following command to check if the setup is ready:

BASH 
x-install post-install \
    --cluster "xio-integrated" \
    --ssh-username "rocky" \
    --ssh-private-key-file "/path/to/my-dev-key.pem"

The flag --ssh-private-key-file takes the name or full path to the SSH private key of the key-pair specified with create-standalone.

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

6. Update EKS Token

By default, the EKS token expires in 60 minutes. All attempts to access the cluster will fail with Unauthorized errors. Since the cluster is not managed by x-install in this flow, to refresh the token, run:

BASH 
aws eks update-kubeconfig \
    --name "xio-integrated" \
    --region "us-east-2"

The aws eks update-kubeconfig refreshes the EKS token, alters current-context (if set to something else than xio-integrated), etc. For full info on this, check the doc on update-kubeconfig.

Adding X-Compute Nodes to the EKS Cluster via eks-node-cli

1. Access the Management Server

SSH into the Exostellar Management Server using:

BASH 
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:

BASH 
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:

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

The output should display the new nodes as ready:

CODE 
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.

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

Reference deployment example:

BASH 
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

To clean up the whole standalone stack, or to remove the Exostellar Management Server (EMS) and other components integrated with the existing cluster, run the destroy command with the appropriate cluster name (eg, xio-integrated for the existing cluster, and xio-standalone for the standalone examples above):

BASH 
x-install destroy \
    --cluster "<cluster-name>"

x-install attempts to remove the whole standalone stack or just the integrated components, as per the installation method used, based on the Terraform state files under the hood.

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

For a full list of subcommands and flags:

CODE 
x-install --help

For exploring a subcommand, for eg., precheck

CODE 
x-install precheck --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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close