Create an Instance

How to create an Instance

Reviewed on 16 June 2023 • Published on 26 May 2021

This page shows how to create your first Scaleway Instance. An Instance is a virtual machine in the cloud. Just like a physical machine, it has resources - virtualized CPU, RAM, storage etc. - which vary depending on the Instance type you choose. After you have created your Instance you can connect to it and use it for a wide range of computing use cases depending on the Instance type you chose, from running small scale tests and personal projects, to hosting applications and development environments, to setting up a production server.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

you are the Owner of the Scaleway Organization in which the actions will be carried out, or
you are an IAM user of the Organization, with a policy granting you the necessary permission sets

Select a tab below for instructions on how to create an Instance via either our console, our API, or our CLI.

Requirements:

You have an account and are logged into the Scaleway console
You have created your SSH key and added it to your account

Click Instances in the Compute section of the side menu. The Instance creation wizard displays.

Note:
If you have existing Instances in your account, you will see a list of these Instances instead of the Instance creation page, and the «Plus Icon» button for creating new Instances.
Click Create Instance. The Instance creation wizard displays.
Complete the following steps in the wizard:
- Choose an Availability Zone, which is the geographical region where your Instance will be deployed.
- Choose an Instance type. Different Instance types have different prices, processing power, memory, storage options and bandwidth. See our dedicated documentation to help choose the best Instance type for your needs.
- Choose an Image to run on your Instance. This can be an operating system, an InstantApp or a custom image. A complete list of all available Linux distributions and InstantApps can be found here.
Note:
When choosing an image for an Enterprise Instance, be aware this Instance type is not compatible with bootscripts, except for rescue mode. InstantApps are also not available for this Instance type.
- Add Volumes. Volumes are storage spaces used by your Instances.
  - For GP1 Instances you can leave the default settings of a maximum local storage, or choose how much local and/or block storage you want. Your system volume is the volume on which your Instance will boot. The system volume can be either a local or a block volume.
  - PLAY2, PRO2, and Enterprise Instances boot directly on block volumes. You can add several block volumes and define how much storage you want for each.
Important:
Note that:
- a volume with an OS image should be at least 10 GB (125 GB for a GPU OS).
- if several Block Storage volumes are connected to your Instance, the first volume will contain the OS and is required to boot the Instance. You can change your boot volume after you create the Instance.
- if you have two or more volumes with identical operating systems, or a volume with no operating system, choosing one of these as your boot volume may cause unpredictable boot behavior.
- Enter a Name for your Instance, or leave the randomly-generated name in place. Optionally, you can also add tags to help you organize your Instance.
- Click Advanced options if you want to configure a flexible IP, a local bootscript or a cloud-init configuration. Otherwise, leave these options at their default values.
- Verify the SSH keys that will give you access to your Instance.
- Verify the Estimated cost of your Instance, based on the specifications you chose.
Click Create Instance to finish. The creation of your Instance begins, and you will be informed when the Instance is ready.

Your Instance is now created, and you are redirected to the Overview tab. From here, you can see information including your Instance’s Public IP, the SSH command to use to connect to it, and other information, settings, and actions for the Instance.

Requirements:

You have created a Scaleway account
You have created your SSH key and added it to your account
You have created an API key
You have installed curl on your local machine

Open a terminal and configure your environment variables with the export commands shown below.
Note:
This is an optional step that seeks to simplify your usage of the API. Ensure that you replace the variables represented by triangle brackets in the example below with your own customized values:
- The API access key and secret key that you created.
- The Project ID of the Project you want to create the Instance in. You can find your Project ID in the Settings tab of the relevant Project in the Scaleway console.
- The Availability Zone you want to create the Instance in, e.g. fr-par-1.
```
export SCW_ACCESS_KEY="<API access key>"
export SCW_SECRET_KEY="<API secret key>"
export SCW_PROJECT_ID="<Project ID>"
export SCW_DEFAULT_ZONE="<Availability Zone>"
```

Customize the payload for your API call. This payload specifies the configuration of the Instance you want to create. We provide an example payload below with all the required parameters, and a table of information to help you adapt it to your needs.

{
  "name": "my-new-instance",
  "project": "'""$SCW_PROJECT_ID""'",
  "commercial_type": "GP1-S",
  "image": "544f0add-626b-4e4f-8a96-79fa4414d99a",
  "enable_ipv6": true,
  "volumes 
      "0": {
        "name": "my-volume",
        "size": 300000000000,
        "volume_type": "l_ssd"
      }
  }
}

Parameter	Description	Valid values
name	A name of your choice for the Instance (string)	Any string containing only alphanumeric characters, dots, spaces and dashes, e.g. `"my-new-instance"`.
project	The Project in which the Instance should be created (string)	Any valid Scaleway Project ID (see above), e.g. `"b4bd99e0-b389-11ed-afa1-0242ac120002"`
commercial-type	The commercial Instance type to create (string)	Any valid ID of a Scaleway commercial Instance type, e.g. `"GP1-S"`, `"PRO2-M"`. Use the List Instance Types endpoint to get a list of all valid Instance types and their IDs.
image	The image to install on the Instance, e.g. a particular OS (string)	Any valid Scaleway image ID, e.g. `"544f0add-626b-4e4f-8a96-79fa4414d99a"` which is the ID for the `Ubuntu 22.04 Jammy Jellyfish` image. Use the Marketplace API endpoint to find available images and their IDs.
enable_ipv6	Whether to enable IPv6 on the Instance (boolean)	`true` or `false`
volumes	An object that specifies the storage volumes to attach to the Instance. Must respect the volume constraints of the `commercial_type` (i.e. for each type of Instance, a minimum amount of storage is required, and there is also a maximum that cannot be exceeded. Some Instance types support only Block Storage (`b_ssd`), others also support local storage (`l_ssd`) ). These constraints are available at the List Instance Types endpoint, via the `volume_constraints` parameter for each type listed in the response	A (dictionary) object with a minimum of one key (`"0"`) whose value is another object containing the parameters `"name"` (a name for the volume), `"size"` (the size for the volume, in bytes), and `"volume_type"` (`"l_ssd"`, `"b_ssd"` or `"unified"`). Additional keys for additional volumes should increment by 1 each time (the second volume would have a key of `1`.) Further parameters are available, and it is possible to attach existing volumes rather than creating a new one, or create a volume from a snapshot. For full details see here.

Use the following curl command, replacing the payload with the one you specified at step 2, to create your Instance.

curl -X POST -H "Content-Type: application/json" \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/instance/v1/zones/{$ZONE}/servers" \
-d '{"name": "my-new-instance", "project": "'"$PROJECT_ID"'", "commercial_type": "GP1-S", "image":"544f0add-626b-4e4f-8a96-79fa4414d99a","enable_ipv6": true, "volumes":{"0":{"name": "my-volume","size": 300000000000,"volume_type": "l_ssd"}}}'

Valid Instance creation results in a 201 response containing a server object which confirms the attributes of your Instance.

Tip:

To make this response more readable, try adding | jq '.' to the end of the command shown in step three. This tells your shell to use the jq JSON processor to parse the response received from this call and display it in a formatted way.

Tip:

When creating an Instance via the API, it is in a powered off state by default. To power it on, call the Perform action endpoint, passing it the ID of your Instance (returned in the 201 response at step 3) and poweron as the action to perform.

See the Instance API documentation for full details on the Instance API. In particular, see the Create an Instance call for more details of configurable parameters when creating an Instance.

Requirements:

You have created a Scaleway account
You have created your SSH key and added it to your account
You have created an API key
You have installed and configured the Scaleway CLI on your local machine

Prepare your command by choosing values for the parameters below to define the Instance you want to create. Use the table to select appropriate values.

name=my-new-instance 
project-id=adcaffc9-38ef-4502-86e1-f70d3c353745
zone=fr-par-1
type=GP1-S
image=544f0add-626b-4e4f-8a96-79fa4414d99a
ip=new
root-volume=l:300GB

Parameter	Description	Valid values
name	A name of your choice for the Instance	Any string containing only alphanumeric characters, dots, spaces and dashes, e.g. `my-new-instance`.
project-id	The Project in which the Instance should be created	Any valid Scaleway Project ID, e.g. `b4bd99e0-b389-11ed-afa1-0242ac120002`
zone	The Availability Zone in which the Instance should be created. Note that some Instance types are only available in certain Availability Zones (see type`below)	Any valid Scaleway Availability Zone, e.g. `fr-par-1`, `pl-waw-2`
type	The type of Instance to create	Any valid ID of a Scaleway Instance type, e.g. `GP1-S`, `PRO2-M`. Use the server-type command to get a list of all valid Instance types and their IDs. The default value is `DEV1-S`
image	The image to install on the Instance, e.g. a particular OS	Any valid Scaleway image ID or its label, e.g. `544f0add-626b-4e4f-8a96-79fa4414d99a` or`ubutunu_jammy` for the Ubuntu 22.04 Jammy Jellyfish image. The default value is `ubuntu_jammy`. Use the marketplace command to get a list of all available images and their IDs.
ip	The IP address to use for the Instance.	`new` to create a new IP, `dynamic` to create a dynamic IP address, `none` for no public IP address, or an existing IP ID. Default is `new`
root-volume	The root volume for the Instance (type e.g. `l` (local) or `b` (block) followed by a colon and its required size e.g. `10GB`)	Any valid volume type and size that is coherent with the storage constraints of the Instance type (available via `scw instance server-type list`)

Open a terminal and run the command below, with the parameters modified according to your needs as defined in step one.

scw instance server create name=my-new-instance project-id=2ea18278-847c-4c33-8111-9c2376ed921e zone=fr-par-1 type=GP1-S image=544f0add-626b-4e4f-8a96-79fa4414d99a ip=new root-volume=l:300GB

Your Instance is created, and its details are returned to you in response.

Read the official Scaleway CLI Instance documentation for full details on how to create an Instance via the CLI, including all available parameters, and how to take your next steps.