Skip to main content

Deploy a Kubernetes Cluster

AstroPulse supports two paths:

  • Provision a new cluster — AstroPulse creates and manages the cluster in your cloud account (EKS, GKE, or AKS).
  • Register an existing cluster — works with any cluster (EKS, GKE, AKS, on-prem, kind, minikube).
Developer plan

Free accounts can provision 1 cluster and register 3 existing clusters. See pricing.

Before You Start​

  • Complete Set Up AstroPulse and confirm astroctl whoami shows the right org.
  • Have access to your cloud account (AWS, GCP, or Azure).

Option A: Provision a New Cluster​

Choose your provider:

Step 1 — Find your AWS credentials​

You need your 12-digit AWS account ID. If you don't know it:

aws sts get-caller-identity --query Account --output text

Example output: 123456789012

Make sure the AWS CLI is configured for the account you want to deploy into. If not, run aws configure or set AWS_PROFILE.

Step 2 — Connect your AWS account​

Run this once per cluster. Replace the values with your own:

astroctl cloud aws connect \
  --account-id <YOUR_AWS_ACCOUNT_ID> \
  --region <YOUR_REGION> \
  --cluster-name <YOUR_CLUSTER_NAME>

Example:

astroctl cloud aws connect \
  --account-id 123456789012 \
  --region us-east-1 \
  --cluster-name eks-dev

The CLI opens a pre-filled AWS CloudFormation link in your browser. Make sure you are logged into AWS account <YOUR_AWS_ACCOUNT_ID> in that browser tab, then click Create stack. The CLI waits and confirms when the IAM role is ready.

Find available regions
astroctl cloud aws regions list

Step 3 — Create cluster YAML​

Save this as cluster.yaml and fill in your values:

cluster.yaml
apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: <YOUR_CLUSTER_NAME>   # same name you used in Step 2
  provider: aws
  region: <YOUR_REGION>              # same region you used in Step 2 (e.g. us-east-1)
  provisioner:
    type: eks
    eks:
      accountId: "<YOUR_AWS_ACCOUNT_ID>"   # 12-digit account ID from Step 1
      credentials:
        type: dynamic
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-pool
          minNode: 1
          maxNode: 3
          instanceType: ondemand
          machineTypes:
            - t3.medium
          labels:
            environment: dev

Use the same clusterName and region you used in Step 2.

Find available machine types
# List all types in your region
astroctl cloud aws machines list -r <YOUR_REGION>

# Filter by CPU and memory (MiB)
astroctl cloud aws machines list -r <YOUR_REGION> --cpuMin 2 --memMax 4096

Step 4 — Validate and apply​

astroctl infra k8s apply -f cluster.yaml --dry-run
astroctl infra k8s apply -f cluster.yaml

Step 5 — Watch progress​

astroctl infra k8s progress stream eks-dev

Step 6 — Verify​

astroctl infra k8s get
astroctl infra k8s set-context eks-dev
kubectl get nodes

Full AWS EKS guide →

Option B: Register an Existing Cluster​

If you already have a Kubernetes cluster, register it with AstroPulse. This works with any cluster — EKS, GKE, AKS, on-premises, or local (kind, minikube).

astroctl infra k8s register --cluster-name <YOUR_CLUSTER_NAME>

The CLI installs a lightweight agent that opens a secure reverse tunnel (mTLS) back to the platform. Your cluster's kubectl context must be active.

Dry-run (print the agent manifest without deploying):

astroctl infra k8s register --cluster-name <YOUR_CLUSTER_NAME> --dry-run

Check registration status:

astroctl infra k8s register status --cluster-name <YOUR_CLUSTER_NAME>

For split-team workflows and advanced options, see Bring Your Own Kubernetes Cluster.

Generate YAML from scratch

Not sure about all the fields? Run the template command to get a fully annotated YAML with every option:

astroctl infra k8s template

Add --schema to see field types, required/optional status, and valid values.

Prefer a web UI?

You can provision and manage clusters from the AstroPulse Console without writing any YAML.

Useful References​

Next Step​

Continue with Deploy an Application.