---
title: "VoC AWS Preflight Checker Walkthrough"
slug: "voc-aws-preflight-checker-walkthrough"
description: "Validate your cloud environment for VAST on Cloud deployment with the vastcloud preflight checker tool. Ensure all prerequisites are met efficiently."
updated: 2026-10-28T02:14:35Z
published: 2026-10-28T02:14:35Z
canonical: "docs.vastdata.com/voc-aws-preflight-checker-walkthrough"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VoC AWS Preflight Checker Walkthrough

> [!NOTE]
> ℹ️ 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:

```plaintext
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 \` ` &nbsp;--run-checker \` ` &nbsp;--provider aws \` ` &nbsp;--region us-east-1 \` ` &nbsp;--subnet subnet-abc \` ` &nbsp;--aws-security-groups sg-ab`

> [!TIP]
> ✅ 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

```plaintext
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:

```plaintext
vastcloud login
```

Expected output:

```plaintext
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:

```plaintext
aws sso login --profile <AWS_PROFILE>
```

Example:

```plaintext
aws sso login --profile AWS-Polaris-Test
```

Example output:

```plaintext
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.

```plaintext
vastcloud cluster preflight --provider aws
```

When prompted, please choose `Yes`

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

### **Expected Result**

```plaintext
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`:

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

Expected output:

```plaintext
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.

| Field | Expected Value |
| --- | --- |
| Provider | `aws` |
| Region | `us-east-1` |
| Zone | `us-east-1a` |
| Instance type | `i3en.24xlarge` |
| Node count | `1` |
| Storage usable TB | `44.44` |
| State | `pending` |

## IAM Permissions Check

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

```plaintext
┃ Run permission checks?                                                                                                                                                                                                                            
┃                                                                                                                                                                                                                                                   
┃     Yes!     No.      
```

Expected output:

```plaintext
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:

```plaintext
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:

```plaintext
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`:

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

Expected results:

```plaintext
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:

```plaintext
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:

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

Validated selections:

| Resource | Selected Value |
| --- | --- |
| AWS region | `us-east-1` |
| Availability Zone | `us-east-1a` |
| Subnet | `subnet-087df6d7c877a44c6` |
| Security Group | `sg-0bdb7e6ea502e3cb6` |

## Pre-checker Network Connectivity Test

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

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

Example output:

```plaintext
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:

```plaintext
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:

```plaintext
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:

```plaintext
Connectivity check completed successfully
```

### Checker Results Log File

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

Example log path:

```plaintext
/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`:

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

Expected output:

```plaintext
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:

```plaintext
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:

```plaintext
Preflight Summary

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

Full example:

```plaintext
╭─────────────────────┬────────┬────────╮
│ 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.

| **Variable** | **Example Value** | **Description** |
| --- | --- | --- |
| `&lt;CLUSTER_NAME&gt;` | `voc-aws-test` | Name of the VAST on Cloud cluster in Polaris |
| `&lt;AWS_PROFILE&gt;` | `AWS-Polaris-Test` | AWS SSO profile used for authentication |
| `&lt;AWS_ACCOUNT_ID&gt;` | `XXXXXXXXXXXX` | Masked AWS account ID |
| `&lt;AWS_REGION&gt;` | `us-east-1` | AWS region used by the preflight checker |
| `&lt;AWS_AZ&gt;` | `us-east-1a` | AWS Availability Zone |
| `&lt;SUBNET_ID&gt;` | `subnet-087df6d7c877a44c6` | AWS subnet selected for the deployment |
| `&lt;SECURITY_GROUP_ID&gt;` | `sg-0bdb7e6ea502e3cb6` | AWS security group selected for the deployment |

For copy/paste convenience:

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

### Verify the Active vastcloud Context

Run:

```plaintext
vastcloud config get-contexts
```

Example output:

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

In this example, the active context is:

```plaintext
production-aws-XXXXXXXXXXXX-ctx → production-aws-XXXXXXXXXXXX
```

The Polaris endpoint used by this context is:

```plaintext
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

```plaintext
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:

```plaintext
vastcloud cluster preflight --provider aws <CLUSTER_NAME>
```

Example:

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

## Validate Configuration Files

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

```plaintext
~/.vast/config.yaml
~/.aws/config
```

### Example VAST Cloud Configuration

Run:

```plaintext
cat ~/.vast/config.yaml
```

Example output:

```plaintext
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:

```plaintext
cat ~/.aws/config
```

Example output:

```plaintext
[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:

```plaintext
aws credentials invalid/expired
```

Resolution:

```plaintext
aws sso login --profile <AWS_PROFILE>
```

Example:

```plaintext
aws sso login --profile AWS-Polaris-Test
```

Then rerun:

```plaintext
vastcloud cluster preflight --provider aws <CLUSTER_NAME>
```

Example:

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

### Wrong vastcloud Context Selected

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

```plaintext
vastcloud config get-contexts
```

Then switch to the correct context if needed:

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

Validate again:

```plaintext
vastcloud config get-contexts
```

Expected active context:

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

### Optional `ec2:CreateSecurityGroup` Permission Is Missing

Example warning:

```plaintext
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:

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

Possible causes:

| **Cause** | **Explanation** |
| --- | --- |
| IMDS access restricted | The environment may require IMDSv2 or block metadata access |
| Instance metadata disabled | Metadata service may be disabled in the instance configuration |
| Hardened launch policy | AWS security policy may restrict access to metadata |
| Custom networking rules | Local instance routing or firewall rules may block metadata access |

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:

| **Connectivity Area** | **Purpose** |
| --- | --- |
| AWS metadata service | Instance metadata access |
| AWS CloudFormation | Deployment orchestration |
| AWS EC2 API | Instance and networking operations |
| AWS S3 regional endpoint | Object storage access |
| External internet connectivity | Outbound communication validation |
| Internal cluster connectivity | Node-to-node communication |
| Internal TCP/UDP service ports | VAST cluster service communication |

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

```plaintext
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

```plaintext
# 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

| Check | Expected Result |
| --- | --- |
| `vastcloud login` completed successfully | Yes |
| Active context points to `production-aws-XXXXXXXXXXXX` | Yes |
| Polaris endpoint is `https://api.aws.polaris.vastdata.com` | Yes |
| AWS SSO login completed successfully | Yes |
| AWS account is masked as `XXXXXXXXXXXX` | Yes |
| Region is `us-east-1` | Yes |
| AZ is `us-east-1a` | Yes |
| Subnet is `subnet-087df6d7c877a44c6` | Yes |
| Security group is `sg-0bdb7e6ea502e3cb6` | Yes |
| Terraform is installed | Yes |
| AWS CLI is installed | Yes |
| IAM permission checks pass | Yes |
| Network connectivity check passes | Yes |
| No resource conflicts found | Yes |
| Final preflight summary shows all stages as `OK` | Yes |

## Final Success Criteria

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

```plaintext
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.