Skip to main content
porter clusters contains commands for provisioning and managing the clusters in the current project. Creating a cluster provisions Kubernetes infrastructure in a cloud account you have already connected to Porter. Porter picks the cloud provider from the cloud account, runs preflight checks against it, and selects a Kubernetes version and node groups for you.

​
Prerequisites

​
porter clusters create

Create a new cluster in the current project from a name, region, and cloud account. Usage:
Options:

​
Interactive prompts

Any of --name, --cloud-account-id, and --region that you omit are prompted for:
  • Name — the prompt is prefilled with a suggested name based on your project and existing clusters
  • Cloud account — chosen from the accounts connected to the project. A project with a single connected account skips this prompt
  • Region — chosen from the regions the selected cloud account supports, filtered as you type. If the region list can’t be fetched, or the account reports no regions, the prompt falls back to free-text entry
The cloud account is asked before the region because the account determines which regions are offered. Unless you pass --yes, Porter then shows the resolved choices and asks you to confirm. Where the provider’s base monthly cost can be determined, it is shown too. The prompt defaults to no.
On a non-interactive terminal there is no name prompt: omitting --name silently provisions a cluster under the suggested name. Always pass --name in CI. Omitting --cloud-account-id or --region there is not equivalent, as those prompts have no non-interactive fallback.

​
Provisioning

Provisioning is asynchronous and can take up to an hour. The command prints a dashboard link as soon as the cluster is created, before any wait, so an interrupted wait still leaves you with a link. Pass --wait to block until the cluster is ready, which is what you want in CI. The wait polls the cluster’s status and exits non-zero if provisioning fails, the timeout elapses, your Porter session expires, or it loses the connection after repeated polling failures. Interrupting the wait with Ctrl-C is the one case that exits zero: it stops watching only, and the cluster keeps provisioning in the background. Passing --wait-timeout without --wait is an error rather than a silently ignored flag, as is a --wait-timeout of zero or less.

​
Preflight checks

Porter runs preflight checks against the cloud account before provisioning, catching problems like insufficient quota. When they fail, the CLI prints each failing check and exits with code 3 without creating a cluster. Resolve the reported issues and re-run.

​
Exit codes

​
Sandbox requirements

--enable-sandboxes is validated server-side and the create fails unless all of the following hold:
  • The cloud account is an AWS account. Sandboxes are not available on GCP or Azure
  • The AWS account is not on the free tier. Sandbox nodes need local NVMe storage, which no free tier instance type offers. The create also fails if Porter cannot determine free tier eligibility at all
  • Sandboxes are enabled for your project. Contact Porter support if they are not
Sandboxes can also be enabled on an existing cluster from the dashboard. See Sandboxes Getting Started.
--cloud-account-id takes Porter’s own cloud account UUID, which is printed by porter cloud-accounts list --json as id. It is not the Provider ID column of the default table, which holds the AWS account ID, GCP project ID, or Azure subscription ID.

​
porter clusters list

List the clusters in the current project. Usage:
Options: The default output is a table with the cluster’s Name, Provider, Region, Status, and Created, ordered newest first. On a terminal that supports it, each name links to the cluster’s dashboard page. When the output is piped to another command, it is printed as tab-separated values so it stays friendly to tools like grep, cut, and awk. Name is the cluster’s vanity name when one is set, falling back to the provisioned name otherwise. The table has no ID column, so use --json when you need cluster IDs or the underlying provisioned name. In the table, status is one of Ready, Updating, Updating (Unavailable), Deleting, Deleted, Failed, Unreachable, or - when Porter does not yet know. --json reports the raw state instead, such as ready or updating_unavailable.

​
porter clusters delete

Delete a cluster from the current project. Porter tears down the infrastructure it provisioned for the cluster. Usage:
The <cluster> argument identifies the cluster by its ID, name, or vanity name. Run porter clusters list --json to see all three, since the default table shows neither the ID nor the provisioned name. If the identifier matches more than one cluster, the CLI prints the matches and asks you to re-run with the cluster ID. Options:
A cluster can only be deleted once nothing is still running on it. If resources remain, the CLI lists them by type and name and exits non-zero without deleting anything. This check runs after the confirmation prompt, so you may confirm a delete and only then learn it is blocked.
Deletion is asynchronous and can take up to an hour. The cluster moves to the deleting state while teardown proceeds. Deleting a cluster that is already being deleted is a no-op that exits zero, so a run with --wait can safely be repeated to resume watching an interrupted wait. On a non-interactive terminal there is nothing to prompt, so --yes is required.