VoC AWS Preflight Checker Walkthrough

ℹ️ Info

This document provides clear instructions for running and using the vastcloud preflight checker tool.

The tool is designed to help users validate that their cloud environment is ready for a VAST on Cloud deployment. Running the preflight checker helps confirm that all prerequisites are in place, saving time and potentially reducing deployment-related costs.

The wizard runs (in order):

1. Authentication status (Polaris + cloud credentials, read-only

2. Polaris deployment summary (only when a cluster name is given; skipped if Polaris auth failed)

3. API permission checks

4. Required tool presence

5. Terraform pre-checker (deploys a small network connectivity test)

6. Resource conflict/collision check

Command Syntax:

The preflight checks are an extension of the “vastcloud cluster” command:

vastcloud cluster preflight <cluster_name> --provider

• This is the basic usage of the preflight check; there are a number of options that allow for non-interactive use and selectively running checks rather than the whole suite.

• By default, all stages will run (each prompts unless --yes is set). Pass one or more --run-* flags to run only those stages; everything else is automatically skipped.

• Note that all tests must pass for a successful cluster deployment.

Examples:

• Fully interactive wizard (no cluster name)

vastcloud cluster preflight --provider aws

• Full wizard targeted at a specific cluster name

vastcloud cluster preflight my-cluster --provider aws

• Non-interactive: run permissions and tools only

vastcloud cluster preflight -y --run-permissions --run-tools

• Run the pre-checker non-interactively with the provided networking

vastcloud cluster preflight -y \
 --run-checker \
 --provider aws \
 --region us-east-1 \
 --subnet subnet-abc \
 --aws-security-groups sg-ab

✅ Tip

For common issues, debugging, and troubleshooting, please refer to the “Debug and Troubleshooting” section at the end of this procedure.
If you are managing multiple environments or using more then one VoC or VoC deployment base please read the context management section in the debug chapter at the end of the procedure.

Perquisites

• vastcloud CLI tool is installed

  curl https://storage.googleapis.com/polaris-vastcloud/install_vastcloud.sh | bash

• A Polaris deployment is present in the Polaris portal.

• You have valid AWS credentials.

Before you begin

Before you begin, please log on to both vastcloud and AWS using the two steps below.

Log in to vastcloud

Run:

vastcloud login

Expected output:

Opening browser for authentication...
Waiting for authentication...

✓ Logged in as vast.user
  Token valid until: 2026-05-14 11:29:32

Login with AWS credentials

Run the below command:

aws sso login --profile <AWS_PROFILE>

Example:

aws sso login --profile AWS-Polaris-Test

Example output:

Attempting to open your default browser.

Successfully logged into Start URL: https://identitycenter.amazonaws.com/ssoins-6804ca3289554bfe

Preflight Checker Detailed Walkthrough (AWS)

Authentication Check

The first stage validates authentication to both Polaris and AWS.
Run the command below to start the preflight checker.

vastcloud cluster preflight --provider aws

When prompted, please choose Yes

/.vast > vastcloud cluster preflight --provider aws
┃ Run authentication check?                                                                                                                                                                                                                         
┃                                                                                                                                                                                                                                                   
┃       Yes!     No.      

Expected Result

Authentication Status
 Polaris:   OK      production-aws-XXXXXXXXXXXX @ https://api.aws.polaris.vastdata.com
 AWS:       OK      arn:aws:sts::XXXXXXXXXXXX:assumed-role/AWSReservedSSO_AWS-Polaris-Test_aaf44d356dcb8d5b/vast.user @ us-east-1

Polaris Deployment Lookup

The preflight checker looks up the cluster definition in Polaris.- answer Yes:

┃ Run Polaris deployment lookup?                                                                                                                                                                                                                    
┃                                                                                                                                                                                                                                                   
┃         Yes!     No.        

Expected output:

Polaris deployment

  Name                  voc-aws-test
  Provider              aws
  Region                us-east-1
  Zone                  us-east-1a
  Instance type         i3en.24xlarge
  State                 pending
  Node count            1
  Storage (usable TB)   44.44

Review the deployment details and confirm that the values match the intended deployment.

IAM Permissions Check

The permissions check validates whether the authenticated AWS identity has the required permissions to perform deployment-related operations - answer Yes:

┃ Run permission checks?                                                                                                                                                                                                                            
┃                                                                                                                                                                                                                                                   
┃     Yes!     No.      

Expected output:

IAM Permissions

Permission check: AWS
Identity: arn:aws:sts::XXXXXXXXXXXX:assumed-role/AWSReservedSSO_AWS-Polaris-Test_aaf44d356dcb8d5b/vast.user
Region:   us-east-1

Expected results:

Operation        Status
config/login     OK
cluster list     OK
cluster create   OK
cluster delete   OK

You can: config/login, cluster list, cluster create, cluster delete

Note that the following optional permission was not granted:

Optional permissions not granted for "cluster create":
  - ec2:CreateSecurityGroup

This permission is only required if vastcloud is expected to automatically create a security group.

Because an existing security group was selected manually, this does not block the preflight check.

Required Tools Check

The tool checks whether the required local tools are installed - answer Yes:

┃ Run required tools check?                                                                                                                                                                                                                         
┃                                                                                                                                                                                                                                                   
┃       Yes!     No.      

Expected results:

Required Tools

terraform   Terraform v1.15.1
aws         aws-cli/2.33.20 Python/3.13.12 Darwin/25.4.0 source/arm64

AWS Infrastructure Selection

The preflight checker looks up the cluster in Polaris and uses the configured AWS region and Availability Zone.

Expected output:

Looking up cluster "voc-aws-test" in Polaris...

Pre-checker will run in AWS region=us-east-1 zone=us-east-1a

The following AWS resources were selected:

Subnet:           subnet-087df6d7c877a44c6
Security Groups:  sg-0bdb7e6ea502e3cb6

Validated selections:

Pre-checker Network Connectivity Test

The pre-checker deploys temporary Terraform-based checker infrastructure in AWS and validates the required connectivity - answer Yes:

 Run pre-checker (network connectivity)?                                                                                                                                                                                                           
┃                                                                                                                                                                                                                                                   
┃              Yes!     No.        

Example output:

Pre-Checker (network connectivity)
Initializing checker terraform v1.0.5...
Applying checker terraform v1.0.5...
Checker infrastructure deployed, waiting for connectivity tests...
Waiting for checker results from instance i-05948cbf69862d185...

The checker may take a few minutes to complete.

It creates a temporary EC2 checker instance and reads its serial console output until the connectivity tests complete.

Example serial console reference:

serial console: https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#GetSystemLog:instanceId=i-05948cbf69862d185

Note: The serial console URL is unique per run because the EC2 instance ID changes each time.

Expected Connectivity Test Results

The checker validates connectivity to AWS services, external endpoints, and internal VAST cluster ports.

Expected successful checks include:

connectivity to meta-data service (us-east-1)                                  ok
connectivity to CloudFormation service                                         ok
connectivity to EC2 service                                                    ok
connectivity to S3 gateway for region us-east-1                                ok
connectivity to Outside connectivity (8.8.8.8)                                 ok
connectivity to External IP to test outside communication (ping)               ok
connectivity to internal cluster instance (ping)                               ok

The checker also validates internal TCP and UDP ports required by the cluster.

Successful completion message:

Connectivity check completed successfully

Checker Results Log File

After the connectivity test completes, the results are saved locally.

Example log path:

/Users/vast.user/.vast/preflight/terraform/aws/checker/log/checker-results-voc-aws-test-20260514-053341.log

Use this log file for troubleshooting or for attaching evidence to a deployment validation record.

Checker Cleanup

After the test completes, the temporary checker resources are removed automatically. - answer Yes:

┃ Run resource conflict check?                                                                                                                                                                                                                      
┃                                                                                                                                                                                                                                                   
┃        Yes!     No.       

Expected output:

Cleaning up checker resources...
Checker resources cleaned up successfully

This confirms that the temporary AWS checker infrastructure was removed successfully.

Resource Conflict Check

The preflight checker validates that there are no conflicting resources that may block the deployment.

Expected result:

Resource Conflicts
No conflicting resources found.

Expected Preflight Summary

At the end of the process, the preflight checker displays a summary table.

Expected successful result:

Preflight Summary

Stage                 Status
authentication        OK
polaris deployment    OK
permissions           OK
tools                 OK
pre-checker           OK
conflicts             OK

Full example:

╭─────────────────────┬────────┬────────╮
│ Stage               │ Status │ Detail │
├─────────────────────┼────────┼────────┤
│ authentication      │ OK     │        │
│ polaris deployment  │ OK     │        │
│ permissions         │ OK     │        │
│ tools               │ OK     │        │
│ pre-checker         │ OK     │        │
│ conflicts           │ OK     │        │
╰─────────────────────┴────────┴────────╯

If all stages are marked OK, the AWS environment is ready for VAST on Cloud deployment.

Debug and Troubleshooting

Variables Used in This Guide

The examples below use the following values.

For copy/paste convenience:

export CLUSTER_NAME="voc-aws-test"
export AWS_PROFILE="AWS-Polaris-Test"
export AWS_REGION="us-east-1"

Verify the Active vastcloud Context

Run:

vastcloud config get-contexts

Example output:

CURRENT   NAME                              ACCOUNT
*         production-aws-XXXXXXXXXXXX-ctx   production-aws-XXXXXXXXXXXX

In this example, the active context is:

production-aws-XXXXXXXXXXXX-ctx → production-aws-XXXXXXXXXXXX

The Polaris endpoint used by this context is:

https://api.aws.polaris.vastdata.com

This is an important safety check to confirm that the preflight command is running against the intended Polaris environment.

Example Failed Result

Authentication Status
 Polaris:   OK      production-aws-XXXXXXXXXXXX @ https://api.aws.polaris.vastdata.com
 AWS:       FAILED  AWS credentials invalid/expired

If AWS authentication fails, run: Then rerun the preflight command:

vastcloud cluster preflight --provider aws <CLUSTER_NAME>

Example:

vastcloud cluster preflight --provider aws voc-aws-test

Validate Configuration Files

The vastcloud login and AWS SSO login rely on two local configuration files:

~/.vast/config.yaml
~/.aws/config

Example VAST Cloud Configuration

Run:

cat ~/.vast/config.yaml

Example output:

apiVersion: vastcloud/v2
kind: Config
current-context: production-aws-XXXXXXXXXXXX-ctx
contexts:
    - name: production-aws-XXXXXXXXXXXX-ctx
      account: production-aws-XXXXXXXXXXXX
      user: ""
accounts:
    - name: production-aws-XXXXXXXXXXXX
      api-endpoint: https://api.aws.polaris.vastdata.com
      default-provider: aws
      aws:
        account-id: "XXXXXXXXXXXX"
        region: us-east-1
users: []

Example AWS CLI Configuration

Run:

cat ~/.aws/config

Example output:

[default]
region = eu-west-1
sso_start_url = https://d-936770c4af.awsapps.com/start
sso_region = eu-west-1
sso_account_id = XXXXXXXXXXXX
sso_role_name = AWS-Support

[profile AWS-Support-XXXXXXXXXXXX]
sso_start_url = https://d-936770c4af.awsapps.com/start
sso_region = eu-west-1
sso_account_id = XXXXXXXXXXXX
sso_role_name = AWS-Support
region = eu-west-1

[profile AWS-Polaris-Test]
sso_start_url = https://identitycenter.amazonaws.com/ssoins-6804ca3289554bfe
sso_region = eu-west-1
sso_account_id = XXXXXXXXXXXX
sso_role_name = AWS-Polaris-Test
region = eu-west-1
output = json

Note: The AWS CLI profile may use output = json, but the vastcloud CLI formats its own output independently.

AWS Authentication Failed

Sample Error message:

aws credentials invalid/expired

Resolution:

aws sso login --profile <AWS_PROFILE>

Example:

aws sso login --profile AWS-Polaris-Test

Then rerun:

vastcloud cluster preflight --provider aws <CLUSTER_NAME>

Example:

vastcloud cluster preflight --provider aws voc-aws-test

Wrong vastcloud Context Selected

If the active context is not the intended one, list the contexts:

vastcloud config get-contexts

Then switch to the correct context if needed:

vastcloud config use-context production-aws-XXXXXXXXXXXX-ctx

Validate again:

vastcloud config get-contexts

Expected active context:

CURRENT   NAME                              ACCOUNT
*         production-aws-XXXXXXXXXXXX-ctx   production-aws-XXXXXXXXXXXX

Optional ec2:CreateSecurityGroup Permission Is Missing

Example warning:

Optional permissions not granted for "cluster create":
  - ec2:CreateSecurityGroup

This is not necessarily a blocker.

It is only required if vastcloud needs to automatically create a new security group.

If an existing security group is selected manually, the preflight can still pass.

Metadata Service Connectivity Failed

Example failure:

connectivity to meta-data service (us-east-1)                                  failed

Possible causes:

Recommended action:

Validate the AWS metadata service settings and confirm whether the environment requires IMDSv2.

Network Requirements Reference

The exact port list may vary by deployment design and product version, but the pre-checker validates connectivity categories such as:

Checker Instance Takes Time to Report Results

The network pre-checker deploys temporary AWS infrastructure and waits for the checker instance to report results through the serial console.

The instance ID and serial console URL are unique per run.

Example:

Waiting for checker results from instance i-05948cbf69862d185...

Use the instance ID from the current run when checking AWS serial console logs.

Quick Command Summary

# Optional: define common variables
export CLUSTER_NAME="voc-aws-test"
export AWS_PROFILE="AWS-Polaris-Test"
export AWS_REGION="us-east-1"

# Login to vastcloud
vastcloud login

# Verify current context
vastcloud config get-contexts

# If AWS SSO credentials are expired
aws sso login --profile "${AWS_PROFILE}"

# Run AWS preflight checker
vastcloud cluster preflight --provider aws "${CLUSTER_NAME}"

Final Validation Checklist

Final Success Criteria

The AWS environment can be considered ready for VAST on Cloud deployment when the final preflight summary shows:

authentication        OK
polaris deployment    OK
permissions           OK
tools                 OK
pre-checker           OK
conflicts             OK

Once all stages are marked OK, proceed with the VAST on Cloud cluster deployment workflow.