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

# Hello-World AWS Cluster

> Creating your first Kubox cluster

## Overview

This walkthrough offers a hands-on guide to creating your first Kubox cluster. During the process, it will provision AWS cloud resources, including a Virtual Private Network (VPC), Subnets, Routing Tables, Load Balancer, Virtual Machines (using Spot Instances by default), and more. Successfully completing this guide will verify your permissions, and the final step will clean up all resources, ensuring no residual costs.

## Steps

<Steps>
  <Step title="Verify AWS CLI is configured and authenticated">
    <Note>
      If you are new to AWS cloud and need to configure the AWS CLI see [Set up an AWS account and create a User](/kb/beginner#set-up-an-aws-account-and-create-a-user)
    </Note>

    Verify the current context and identity

    ```bash theme={null}
    aws sts get-caller-identity
    ```
  </Step>

  <Step title="Create a cluster configuration file">
    The cluster configuration file defines the metadata and the type of virtual machines and their role in the Kubernetes cluster.
    The role can be one of the three `control-plane`, `worker` and `gpu`.

    <Note>
      **Region**: Please change the aws region in the `cluster.yaml` as required.
    </Note>

    <CodeGroup>
      ```bash linux {19} theme={null}
      #!/bin/bash

      # Define the name of the YAML file
      output_file="cluster.yaml"

      # Use cat <<EOF to write YAML content to the file
      cat <<EOF > "$output_file"
      metadata:
        clusterName: hello-world
        pulumi:
          orgName: kubox-ai
          projectName: koala

      tags:
        - key: "Environment"
          value: "dev"

      aws:
        region: "ap-southeast-2"
        nodes:
          - vmType: t2.medium
            count: 1
            role: control-plane
          - vmType: t2.medium
            count: 2
            role: worker
      EOF

      # Output a success message
      echo "YAML file '$output_file' created successfully."
      ```

      ```powershell windows {17} theme={null}
      # Define the name of the YAML file
      $outputFile = "cluster.yaml"

      # Write YAML content to the file
      @"
      metadata:
        clusterName: hello-world
        pulumi:
          orgName: kubox-ai
          projectName: koala

      tags:
        - key: "Environment"
          value: "dev"

      aws:
        region: "ap-southeast-2"
        nodes:
          - vmType: t2.medium
            count: 1
            role: control-plane
          - vmType: t2.medium
            count: 2
            role: worker
      "@ | Out-File -FilePath $outputFile -Encoding utf8

      # Output a success message
      Write-Host "YAML file '$outputFile' created successfully."
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialise a cluster folder">
    The command will create a folder with core helm charts and Kubernetes manifests that will be installed.

    ```bash theme={null}
    kubox init -f cluster.yaml
    ```

    After the command has completed you can inspect the folder `./cluster` in the current directory.
  </Step>

  <Step title="Create the cluster">
    <Note>**Time**: The cluster creation process take about 3-7 minutes depending depending on spot instance requests.</Note>

    This command will create the AWS resources including Virtual Machines and bootstrap `etcd` and Kubernetes.

    ```bash theme={null}
    kubox create -f cluster.yaml
    ```

    <Note>
      [Flux will be installed](https://fluxcd.io/flux/cmd/flux_install/) with default toolkit components. However, Flux is not bootstrapped and a sync with Git is not established.
    </Note>

    If you have get errors during creation, see the [troubleshooting guide](kb/troubleshooting).
  </Step>

  <Step title="Verify cluster">
    A kubeconfig file will be generated as part of the cluster creation process.

    ```bash theme={null}
    ls ./cluster/config
    ```

    Connect to the kubernetes cluster using `kubectl`

    ```bash theme={null}
    kubectl get nodes --kubeconfig ./cluster/config/kubeconfig
    ```
  </Step>

  <Step title="Delete cluster">
    ```bash theme={null}
    kubox delete -f cluster.yaml 
    ```
  </Step>
</Steps>

## Next

* [Exploratory data analysis on three billion rows](examples/nyc-taxi)
* [How to use GPU Nodes](kb/advance-config#using-gpu-instances)