Environments

Resource containers within a region where your resources, including virtual machines, volumes, and SSH keys, are deployed.

Environments are resource containers located within a physical data center, known as a region, where your resources, such as virtual machines, Kubernetes clusters, volumes, and SSH key pairs, are deployed. You can create multiple environments within the same region or across different regions. This arrangement ensures the logical organization of your resources, allowing for easy management and accessibility. Each environment also holds a private subnet shared by the virtual machines inside it, so the environment you choose determines both where a resource runs and how it reaches your other resources.

Overview

Virtual machines, Kubernetes clusters, volumes, firewalls, and SSH key pairs each belong to exactly one environment, and every environment belongs to exactly one region. The environment you pick decides which data center runs the resource, which private subnet its virtual machines join, and which SSH key pairs and firewalls are available to it.

Environment names must be unique within your organization, even across different regions. A region is fixed when the environment is created and cannot be changed afterwards.

This article covers managing environments in the Hyperstack console. You can also create, rename, and delete environments programmatically with the Environment API.

Resources in an environment

Each resource below is created inside an environment and follows its own scoping rule.

Resource	Scoping rule
Virtual machines	Belong to one environment and receive a private IP address from that environment's subnet.
Volumes	Belong to one environment at a time. A detached volume can be moved to another environment in the same region.
SSH key pairs	Created in one environment. A virtual machine can only use a key pair from its own environment, so import the same public key into each environment where you need it.
Firewalls	Created in one environment, which you select when you add the firewall.
Kubernetes clusters	Deployed into one environment and inherit its region.

Environment features

Environments display badges in the Hyperstack console for the optional capabilities their region supports. The List environments API returns the same information in the features object on each environment.

Badge	Feature	Meaning
	network_optimised	The environment supports high-speed networking, available in the CANADA-1 and US-1 regions for compatible flavors.
	green_status	The environment sits in a sustainably powered region running on 100% sustainable energy.

Create an environment

Create an environment before you deploy any resource into a region, since virtual machines, Kubernetes clusters, volumes, and key pairs all require one.

1. Navigate to the My Environments page, and click Create New Environment to open the modal window.

2. Complete the fields in the modal:

   a. Name: Enter a name for the environment. Names must be unique within your organization, even across different regions, and are limited to 50 characters.

   b. Select Region: Choose the region where the environment is created, such as CANADA-1.

   

3. Click Create Environment. The new environment appears in the table immediately.

Manage an environment

Rename and delete actions sit behind the ⋮ menu on each row of the My Environments page.

Rename an environment

Renaming an environment changes only its name. Its region, its subnet, and every resource inside it are unaffected.

1. Navigate to the My Environments page and click the ⋮ menu on the environment's row.

2. Click Rename to open the Change Environment Name modal.

3. Enter the new name and click Confirm.

Delete an environment

An environment must be empty before you can delete it. Delete or move every virtual machine, volume, firewall, SSH key pair, snapshot, and any other resource inside it first, otherwise the deletion is rejected and the environment is left unchanged.

Deleting a virtual machine does not delete its snapshots, so an environment that looks empty can still be blocked by a snapshot left behind. The rejection message lists how many of each resource remain.

1. Navigate to the My Environments page and click the ⋮ menu on the environment's row.

2. Click Delete.

3. In the Delete Environment? dialog, click Delete Environment. The row is removed from the table.

Environment networking

Each environment is allocated its own private subnet, expressed as a /24 CIDR block such as 10.0.5.0/24. Every virtual machine you deploy into the environment receives a private IP address from that subnet. All virtual machines in an environment therefore share the same network space, meaning they are part of the same subnet, so traffic between them takes no router hop.

That subnet size is what caps an environment at 250 virtual machines. A /24 block holds a fixed pool of addresses, and some of them are reserved for the environment's gateway and network services.

Check an environment's subnet and capacity

The My Environments page does not display an environment's subnet. Call the Get environment VM quota API to retrieve an environment's CIDR block, the number of virtual machines currently provisioned in it, and how many more its subnet can hold.

Traffic between virtual machines

Firewall rules determine which virtual machines can reach each other. A new virtual machine is secure by default and accepts no incoming traffic, not even from a virtual machine in its own environment, until you add a rule.

Once a firewall rule permits the traffic, what a virtual machine can reach depends on where the destination sits.

Destination	Network path	Reachable over the private network
A virtual machine in the same environment	Both share the environment's subnet and connect directly.	Yes, when a firewall rule allows it.
A virtual machine in a different environment in the same region	Traffic is routed between the two subnets through the environment's gateway.	Yes, when a firewall rule allows it.
A virtual machine in a different region	No private route exists between regions.	No. Use a public IP address instead.

Firewall rules control access between environments

Your virtual machines cannot reach each other by default, because a new virtual machine has no firewall rules permitting incoming traffic. The subnets of your environments in the same region are routed to one another, so a rule that permits a broad source range, such as 0.0.0.0/0, also admits traffic from your other environments. Scope each rule to the source addresses it needs.

Limits and restrictions

Limit	Value
Environments per region, per organization	1,000
Virtual machines per environment	250
Environment name length	50 characters
Environment name uniqueness	Unique within your organization, across all regions
Region	Fixed at creation, cannot be changed
Deletion	Permitted only once the environment is empty