Create Linux or Windows Virtual Instances in Gcore Cloud.
2. Select the region where the Virtual Instance will be deployed.
Notice that regions are labeled either Core or Edge. This represents the region's equipment specifications.
| | Core | Edge\* | | ---------------------------------------- | --------------------------- | ------------------------------- | | Equipment generation | The latest | Different | | Designed for high scalability on the fly | Yes | Not | | Available resources | 1000 cores and 30 TB of RAM | Up to 300 cores and 1 TB of RAM | | Ports for user traffic and storage | Separate | Shared | | Price | Higher | Lower | * Edge regions can be transformed into Core regions — contact [support](mailto:support@gcore.com) to request the conversion. ## Step 2. Configure the imageSelect the type of hardware architecture for the instance:
* **x86-64** : This architecture is known for its broad compatibility with Linux operating systems and Windows distributions. It is commonly used in general purpose computing applications. * **ARM** : ARM architecture is designed for energy efficiency and low power consumption, which also supports strong performance, making it ideal for high-performance computing tasks. However, ARM Virtual Machines are compatible with fewer OS distributions.
The selected hardware architecture determines the available OS options and instance flavors. Select the image source from one of the tabs:
* **Distributions** — standard OS distributions: Ubuntu, Debian, CentOS, Windows, and others. * **Marketplace** — pre-configured templates with software already installed. * **Volume** — boot from an existing volume. * **Snapshot** — boot from a previously created snapshot. * **Custom Images** — use an image uploaded to the project. ## Step 3. Select the VM typeThe available CPU generation is determined by the selected region and displayed in the **CPU generation** field. Select one of the available flavors:
* **Standard** — balanced compute, memory, and networking for a wide range of workloads. * **CPU-Optimized** — higher vCPU-to-RAM ratio, suited for CPU-intensive tasks — batch processing, video encoding, and large-scale data processing. * **Memory-Optimized** — higher RAM-to-vCPU ratio, suited for memory-intensive workloads — databases, SRM/ERP, and data warehouses.Enter a volume name, select its type, and set its size in GiB.
(Optional) Add an **Attachment Tag**.
## Step 5. Configure networking ### Configure the interfaceConfigure the network interface:
1. Select the **Network type**: **Public** or **Private**. 2. In the **IP Family** section, select the IP version: **IPv4**, **IPv6**, or **Dual (IPv4 + IPv6)**. 3. In the **Security Groups** section, select the security groups to attach. The default security group is attached automatically if no selection is made. 4. (Optional) Enable **Use reserved IP** to assign a [reserved IP address](/cloud/networking/ip-address/create-and-configure-a-reserved-ip-address) to the instance, or enable **Use floating IP** to assign a [floating IP address](/cloud/networking/ip-address/create-and-configure-a-floating-ip-address).To assign multiple public IP addresses, add additional public interfaces after the instance is created: open the **Networking** tab in the VM settings and click **Add Interface**.
For a **private** interface, configure a network and a subnet as described below.
Select an existing network from the dropdown list or create a new one by clicking **Add a new network**.
Select an existing subnet from the dropdown list or create a new one by clicking **Add a new subnet**.
When adding multiple interfaces, the order in the creation form determines how the OS names them after the instance starts. The diagram below shows how the selection order carries through to the **Networking** tab and then to the OS interface names:
```bash theme={null}
$ ip addr show enp3s0
2: enp3s0: The first interface (`enp3s0`) is the public interface; the second interface (`enp4s0`) is the private interface. The order set at creation determines routing priority: the first interface has higher priority for outbound traffic than subsequent ones. The interface order cannot be changed after the instance is created.
In addition to SSH keys, a password can also be set for the Virtual Instance, as described in step 7. A password is required to connect to a Linux instance from the [Customer Portal](/cloud/virtual-instances/connect/connect-to-your-instance-via-control-panel#connect-to-a-linux-instance).
Enable the **User data** toggle to customize the instance during the initial boot using a `cloud-init` agent.
A password for connecting to a Linux instance from the [Customer Portal](/cloud/virtual-instances/connect/connect-to-your-instance-via-control-panel) or [via SSH](/cloud/virtual-instances/connect/connect-via-ssh) can be set via **User data**. Insert the following code into the field, replacing `my-password` with the chosen password:
```yaml theme={null} #cloud-config password: my-password chpasswd: { expire: False } ssh_pwauth: True ```Enable **Add tags** to add a key-value pair as metadata for the Virtual Instance.
### PlacementEnable **Add to placement group** to determine how to place multiple instances.
Instances can be placed in one of three types of groups:
* **Affinity** groups assemble virtual machines on the same hardware. Machines launched in one affinity group will exchange data faster because they are located on the same server. * **Anti-Affinity** groups work the opposite way: all Virtual Machines in this group will be separated across different physical hardware. This increases fault tolerance of a cluster: Even if something goes wrong with one server, machines on the other servers will remain available. * **Soft Anti-Affinity** groups encourage, but don't strictly enforce, the separation of Virtual Machines. Unlike a strict anti-affinity policy, where machines may never be placed together, soft anti-affinity allows placement on the same hardware when it is necessary due to factors like resource constraints or high demand. It is suitable for users who want to use the anti-affinity policy by default while also avoiding machine creation failures if an unused host is not found.Add the instance to an existing placement group or create a new one by clicking **Add placement group**.
## Step 8. Specify the number of instancesIndicate how many instances with the same configuration are needed. No more than 10 instances can be created at a time.
Set the **Name Template** for the instances. Select one of the available options from the dropdown:
* `{ip_octets}` — the placeholder is replaced with the last two octets of the assigned IP address — `my-vm-{ip_octets}` becomes `my-vm-10-0-5`. * `{instance_role}` — the placeholder is replaced with the value of the `instance_role` metadata tag set in the **Add tags** section. ## Step 9. Create the instanceClick **Create Instance**.
The instance transitions to the **Building** status while resources are being allocated.
After that, the instance moves to the **Power on** status and is ready to use.
Creating a Linux VM via the REST API consists of three API calls: list available images, list flavors, then submit the create request. The instance is reachable via SSH within about 30 seconds of the task finishing.
Open a bash terminal and set these as environment variables before running the examples:
```bash theme={null} export GCORE_API_KEY="{YOUR_API_KEY}" export GCORE_CLOUD_PROJECT_ID="{YOUR_PROJECT_ID}" export GCORE_CLOUD_REGION_ID="{YOUR_REGION_ID}" ``` ## Add an SSH keyIf the project does not yet have an SSH key, register one before creating the instance. The create call references the key by name, not by ID.
| Parameter | Required | Description | | ------------ | -------- | --------------------------------------------------------------------- | | `name` | Yes | Identifier used as `ssh_key_name` in the create call. | | `public_key` | No | An RSA or Ed25519 public key string. Omit to generate a new key pair. |When `public_key` is omitted, the response includes a `private_key` field - save it immediately, as it is not shown again.
## QuickstartComplete scripts for the full flow. See the step-by-step section below for details on each call.
Each step below explains what the call does, which parameters matter, and what the response looks like. Use this section to understand the flow or to debug a specific step.
To list only Gcore-managed public images, add the `visibility=public` parameter.
To delete the instance and its boot volume in a single call, pass the volume ID in the `volumes` query parameter.
If a floating IP was assigned to the instance, add `delete_floatings=true` to the query string.
## Create a Basic VMBasic VMs boot from a system-managed local SSD — no volume configuration is accepted on create. Networking is references-only: the create call attaches existing ports by ID rather than creating interfaces inline. The region is specified in the request body, so a single endpoint handles all regions without encoding the region in the URL path.
Set the required environment variables. `REGION_ID` is the numeric ID of a region that supports Basic VMs — query the [regions API](/api-reference/cloud/regions/list-regions) and filter for regions where `has_basic_vm` is `true`.
```bash theme={null} export GCORE_API_KEY="{YOUR_API_KEY}" export GCORE_CLOUD_PROJECT_ID="{YOUR_PROJECT_ID}" export REGION_ID="{REGION_ID}" export PORT_ID="{YOUR_PORT_ID}" ``` ### Step 1. Select an imageOnly Linux images are accepted on Basic VM create. Query the images endpoint for the target region and save the ID of the chosen image.
```bash theme={null} curl "https://api.gcore.com/cloud/v1/images/$GCORE_CLOUD_PROJECT_ID/$REGION_ID?visibility=public" \ -H "Authorization: APIKey $GCORE_API_KEY" ``` ```bash theme={null} export IMAGE_ID="{IMAGE_ID}" ``` ### Step 2. List Basic VM flavorsBasic VM flavors use the `g1s-shared-*` or `g2s-shared-*` naming scheme. Query the standard flavors endpoint and filter by name prefix.
```bash theme={null} curl "https://api.gcore.com/cloud/v1/flavors/$GCORE_CLOUD_PROJECT_ID/$REGION_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" ``` The API returns: ```json theme={null} { "results": [ {"flavor_id": "g2s-shared-1-2-25", "vcpus": 1, "ram": 2048}, {"flavor_id": "g2s-shared-2-4-50", "vcpus": 2, "ram": 4096}, {"flavor_id": "g2s-shared-4-8-80", "vcpus": 4, "ram": 8192} ] } ```The number after the RAM value in the flavor name is the local SSD size in GiB. Set `FLAVOR_NAME` to the chosen flavor.
```bash theme={null} export FLAVOR_NAME="g2s-shared-1-2-25" ``` ### Step 3. Create the Basic VMPass `region_id` in the request body rather than the URL path. The boot disk is created automatically; no volume fields are accepted.
| Parameter | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `region_id` | Yes | Numeric ID of the target region. | | `flavor_name` | Yes | Shared-CPU flavor name from Step 1. | | `image_id` | Yes | ID of a Linux OS image. Only Linux images are accepted. | | `interfaces[].port_id` | Yes | ID of a pre-created port in the same region. Pass multiple entries to attach several NICs; the array order sets the NIC boot order. | | `name` | No | Display name. Auto-generated if omitted. | | `ssh_key_id` | No | UUID of an SSH key registered in the project. | | `user_data` | No | Base64-encoded cloud-init script. | | `tags` | No | Key-value map of labels. | ```bash theme={null} curl -X POST "https://api.gcore.com/cloud/v1/projects/$GCORE_CLOUD_PROJECT_ID/basic_vms" \ -H "Authorization: APIKey $GCORE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "region_id": '"$REGION_ID"', "flavor_name": "'"$FLAVOR_NAME"'", "image_id": "'"$IMAGE_ID"'", "name": "my-basic-vm", "interfaces": [{"port_id": "'"$PORT_ID"'"}] }' ``` The API returns: ```json theme={null} {"tasks": ["d4a4b10e-5d22-4c23-8e09-f7a3e1c1a999"]} ```Poll `GET /cloud/v1/tasks/{task_id}` every 5 seconds until `state` is `FINISHED`, then read the instance ID from `created_resources`.
```bash theme={null} curl "https://api.gcore.com/cloud/v1/tasks/$TASK_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" ``` When complete: ```json theme={null} { "state": "FINISHED", "created_resources": { "instances": ["a1b2c3d4-..."] } } ``` ```bash theme={null} export BASIC_VM_ID="{BASIC_VM_ID}" ``` ### Step 4. Get Basic VM detailsThe response includes `boot_volume_id` referencing the system-managed local disk, which is destroyed together with the VM on delete.
```bash theme={null} curl "https://api.gcore.com/cloud/v1/projects/$GCORE_CLOUD_PROJECT_ID/basic_vms/$BASIC_VM_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" ``` The API returns: ```json theme={null} { "id": "a1b2c3d4-...", "name": "my-basic-vm", "status": "ACTIVE", "region_id": 26, "flavor_name": "g2s-shared-1-2-25", "image_id": "bf221f42-...", "boot_volume_id": "e5f6a7b8-...", "addresses": { "doc-test-net": [{"addr": "10.10.10.5", "type": "fixed"}] } } ``` ### Step 5. Update the Basic VMRename the VM or replace its interface list. Updating `interfaces[]` is a full replace — the API diffs the submitted list against the current state and attaches or detaches ports accordingly. Interface order is immutable after creation.
| Field | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | New display name. | | `tags` | Merge-patch map — a `null` value removes the key. | | `interfaces[]` | Full list of port IDs. Ports in the list but not currently attached are attached; ports currently attached but not in the list are detached. | ```bash theme={null} curl -X PATCH "https://api.gcore.com/cloud/v1/projects/$GCORE_CLOUD_PROJECT_ID/basic_vms/$BASIC_VM_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "my-basic-vm-renamed"}' ``` The API returns: ```json theme={null} {"tasks": ["c7d8e9f0-..."]} ```Poll the task until `state` is `FINISHED`.
### Step 6. Delete the Basic VMDeleting a Basic VM also destroys its system-managed boot disk. Ports attached to the VM are detached but not deleted.
```bash theme={null} curl -X DELETE "https://api.gcore.com/cloud/v1/projects/$GCORE_CLOUD_PROJECT_ID/basic_vms/$BASIC_VM_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" ``` The API returns: ```json theme={null} {"tasks": ["f1a2b3c4-..."]} ```Poll the task until `state` is `FINISHED`.
Declare a Virtual Machine and its boot volume together. The [Terraform provider](/developer-tools/terraform/overview) models these as two separate resources — [`gcore_cloud_volume`](https://registry.terraform.io/providers/G-Core/gcore/latest/docs/resources/cloud_volume) and [`gcore_cloud_instance`](https://registry.terraform.io/providers/G-Core/gcore/latest/docs/resources/cloud_instance) — provisioned in order.
## Create a VMDeclares a boot volume from an Ubuntu 22.04 image and a VM with a public IPv4 interface. `ssh_key_name` takes the name of an [SSH key](#add-an-ssh-key) registered in the project.
```hcl theme={null} resource "gcore_cloud_volume" "boot" { project_id = var.project_id region_id = var.region_id name = "my-boot-volume" source = "image" image_id = var.image_id size = 20 type_name = "ssd_hiiops" } resource "gcore_cloud_instance" "example" { project_id = var.project_id region_id = var.region_id flavor = "g2-standard-2-4" name = "my-vm" ssh_key_name = "my-keypair" volumes = [{ volume_id = gcore_cloud_volume.boot.id }] interfaces = [{ type = "external" ip_family = "ipv4" }] } output "instance_id" { value = gcore_cloud_instance.example.id } output "public_ip" { value = gcore_cloud_instance.example.addresses } ```To find the image ID for the region, query the [Images API](/api-reference/cloud#tag/Images/operation/ImageListForProjectRegion.get):
```bash theme={null} curl "https://api.gcore.com/cloud/v1/images/{project_id}/{region_id}?visibility=public&os_distro=ubuntu" \ -H "Authorization: APIKey $GCORE_API_KEY" | jq '.results[] | select(.name | contains("22.04")) | {id, name}' ```If the project does not yet have an SSH key, declare it as a Terraform resource. SSH keys are project-wide and do not require `region_id`.
```hcl theme={null} resource "gcore_cloud_ssh_key" "my_key" { project_id = var.project_id name = "my-keypair" public_key = "ssh-ed25519 AAAA... user@example.com" } resource "gcore_cloud_instance" "example" { # ... ssh_key_name = gcore_cloud_ssh_key.my_key.name } ```When `public_key` is omitted, Gcore generates a key pair. The private key is returned once in the response and is not stored — save it before applying.
## Optional fields | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `user_data` | Base64-encoded cloud-init script that runs at first boot. | | `security_groups` | List of security group IDs. If omitted, the default security group is applied. | | `username` / `password_wo` | Creates a Linux user or sets the Windows Admin password at boot. | | `vm_state` | `"active"` (default) to start immediately; `"stopped"` to keep the VM off. | | `tags` | Map of key-value labels attached to the instance. | | `name_template` | Auto-generates the name from the public IP, e.g. `"my-vm-{ip_octets}"`. Use instead of `name` when dynamic naming is required. |Example with `user_data` and `tags`:
```hcl theme={null} resource "gcore_cloud_instance" "example" { # ... required fields ... user_data = base64encode(<<-EOF #cloud-config password: your-password chpasswd: { expire: false } ssh_pwauth: true EOF ) tags = { env = "production" team = "backend" } } ``` ## Delete a VMRemove both `gcore_cloud_instance.example` and `gcore_cloud_volume.boot` from the configuration, then run `terraform apply` — Terraform deletes the instance first, then the volume.
```hcl theme={null} # Remove or comment out both blocks: # resource "gcore_cloud_instance" "example" { # name = "my-vm" # flavor = "g2-standard-2-4" # ... # } # resource "gcore_cloud_volume" "boot" { # name = "my-boot-volume" # source = "image" # ... # } ``` ```bash theme={null} terraform apply ``` ## Import a VMImport the instance and its boot volume separately to bring existing infrastructure under configuration management:
```bash theme={null} terraform import gcore_cloud_instance.example 'To find the boot volume ID, look for `"is_root_volume": true` in the instance details:
```bash theme={null} curl "https://api.gcore.com/cloud/v1/instances/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID/$INSTANCE_ID" \ -H "Authorization: APIKey $GCORE_API_KEY" | jq '.volumes[] | select(.is_root_volume == true) | .id' ```