hosterra/scaleway-instances

Scaleway Instances SDK.

Maintainers

Details

hosterra.dev/Hosterra/scaleway-instance.git

Homepage

Installs: 2

Dependents: 0

Suggesters: 0

Security: 0

1.0.1 2025-03-26 10:06 UTC

Requires

Requires (Dev)

unlicense ca95b6c4c746d34540333f78882b2411357aeac1

phprestapisdkinstancesscaleway

This package is not auto-updated.

Last update: 2025-04-09 10:35:30 UTC

README

Scaleway Instances are virtual machines in the cloud. Different Instance types offer different technical specifications in terms of vCPU, RAM, bandwidth and storage. Once you have created your Instance and installed your image of choice (e.g. an operating system), you can connect to your Instance via SSH to use it as you wish. When you are done using the Instance, you can delete it from your account.

(switchcolumn) To retrieve information about the different images available to install on Scaleway Instances, check out our Marketplace API. (switchcolumn)

Concepts

Refer to our dedicated concepts page to find definitions of all concepts and terminology related to Instances.

(switchcolumn) (switchcolumn)

Quickstart

  1. Configure your environment variables

    This is an optional step that seeks to simplify your usage of the Instances API. See Availability Zones below for help choosing an Availability Zone. You can find your Project ID in the Scaleway console. 

     export SCW_SECRET_KEY=\"<API secret key>\"
 export SCW_DEFAULT_ZONE=\"<Scaleway Availability Zone>\"
 export SCW_PROJECT_ID=\"<Scaleway Project ID>\"

  2. Create an Instance: Run the following command to create an Instance. You can customize the details in the payload (name, description, type, tags etc) to your needs: use the information below to adjust the payload as necessary.

     curl -X POST \\
   -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\
   -H \"Content-Type: application/json\" \\
   \"https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers\" \\
     -d '{
       \"name\": \"my-new-instance\", 
       \"project\": \"'\"$SCW_PROJECT_ID\"'\",
       \"commercial_type\": \"GP1-S\", 
       \"image\": \"ubuntu_noble\",
       \"enable_ipv6\": true,
       \"volumes\": {
         \"0\":{
           \"size\": 300000000000,
           \"volume_type\": \"l_ssd\"
         }
       }
     }'
    ParameterDescriptionValid values
    nameA name of your choice for the Instance (string)Any string containing only alphanumeric characters, dots, spaces and dashes, e.g. \"my-new-instance\".
    projectThe Project in which the Instance should be created (string)Any valid Scaleway Project ID (see above), e.g. \"b4bd99e0-b389-11ed-afa1-0242ac120002\"
    commercial-typeThe 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.
    imageThe image to install on the Instance, e.g. a particular OS (string)Any Scaleway image label, e.g. \"ubuntu_noble\", or any valid Scaleway image ID, e.g. \"6fc0ade6-d6a3-4fb9-87ab-2444ac71e5c0\" which is the ID for the Ubuntu 24.04 Noble Numbat image. Use the List Instance Images endpoint to get a list of all available images with their IDs and labels, or check out the Scaleway Marketplace API.
    enable_ipv6Whether to enable IPv6 on the Instance (boolean)true or false
    volumesAn object that specifies the storage volumes to attach to the Instance. For more information, see Creating an Instance: the volumes object in the Technical information section of this quickstart.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\" or \"b_ssd\"). 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.

  3. List your Instances: run the following command to get a list of all the Instances in your account, with their details:

     curl -X GET \\
   -H \"Content-Type: application/json\" \\
   -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\
   \"https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers/\"

  4. Delete an Instance: run the following command to delete an Instance, specified by its Instance ID:

     curl -X DELETE \\
   -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\
   -H \"Content-Type: application/json\" \\
   \"https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_ZONE/servers/<Instance-ID>\"

    The expected successful response is empty.

(switchcolumn)

Technical information

Availability Zones

Instances can be deployed in the following Availability Zones:

NameAPI ID
Parisfr-par-1 fr-par-2 fr-par-3
Amsterdamnl-ams-1 nl-ams-2
Warsawpl-waw-1 pl-waw-2

(switchcolumn) (switchcolumn)

Pagination

Most listing requests receive a paginated response. Requests against paginated endpoints accept two query arguments:

  • page, a positive integer to choose which page to return.
  • per_page, an positive integer lower or equal to 100 to select the number of items to return per page. The default value is 50.

Paginated endpoints usually also accept filters to search and sort results.These filters are documented along each endpoint documentation.

The X-Total-Count header contains the total number of items returned.

(switchcolumn) (switchcolumn)

Creating an Instance: the volumes object

When creating an Instance using the Scaleway API, the volumes object is not strictly required. However, the defaults vary depending on certain conditions:

  1. If an image label is used:

    • The default will be an sbs_volume volume.
    • The size of this volume will be the OS size (typically 10GB in most cases).

  2. If an image ID from the marketplace is used (or any image based on a unified snapshot):

    • If the Instance supports local storage:
      • The default will be an l_ssd volume.
      • The size of this volume will be the instance's maximum local storage capacity.
    • If the Instance does not support local storage:
      • The default will be a b_ssd volume.
      • The size of this volume will be the OS size.

If you want to customize the storage configuration or add additional volumes, you will need to include the volumes object in your API request. This object should contain at least one (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\" (\"sbs_volume\", \"l_ssd\" or \"b_ssd\"). Additional keys for additional volumes should increment by 1 each time (the second volume would have a key of \"1\".)

Note that volume size must respect the volume constraints of the Instance's commercial_type: for each type of Instance, a minimum amount of storage is required, and there is also a maximum that cannot be exceeded. All Instance types support Block Storage (sbs_volume, b_ssd), some also support local storage (l_ssd). Read more about these constraints in the List Instance types documentation, specifically the volume_constraints parameter for each type listed in the response

You can use the volumes object in different ways. The table below shows which parameters are required for each of the following use cases:

Use caseRequired paramsOptional paramsNotes
Create a volume (l_ssd, b_ssd, sbs_volume) from a snapshot of an imagevolume_type, size, bootIf the size parameter is not set, the size of the volume will equal the size of the corresponding snapshot of the image. The image snapshot type should be compatible with the volume_type.
Create a volume (l_ssd, b_ssd) from a snapshotbase_snapshot, name, volume_typeboot
Create a volume of type sbs_volume from a snapshotbase_snapshot, name, volume_typesize, boot
Create an empty volumename, volume_type, sizeboot
Attach an existing volume (l_ssd, b_ssd)idboot
Attach an existing volume of type sbs_volumeid, volume_typeboot

(switchcolumn) This information is designed to help you correctly configure the volumes object when using the Create an Instance or Update an Instance methods. (switchcolumn)

Going further

For more help using Scaleway Instances, check out the following resources:

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: scaleway
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setApiKey('X-Auth-Token', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-Auth-Token', 'Bearer');


$apiInstance = new OpenAPI\Client\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$zone = 'zone_example'; // string | The zone you want to target
$server_id = 'server_id_example'; // string
$attach_server_volume_request = new \OpenAPI\Client\Model\AttachServerVolumeRequest(); // \OpenAPI\Client\Model\AttachServerVolumeRequest

try {
    $result = $apiInstance->attachServerVolume($zone, $server_id, $attach_server_volume_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->attachServerVolume: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://api.scaleway.com

ClassMethodHTTP requestDescription
DefaultApiattachServerVolumePOST /instance/v1/zones/{zone}/servers/{server_id}/attach-volume
DefaultApicheckBlockMigrationOrganizationQuotasPOST /instance/v1/zones/{zone}/block-migration/check-organization-quotas
DefaultApidetachServerVolumePOST /instance/v1/zones/{zone}/servers/{server_id}/detach-volume
DefaultApigetDashboardGET /instance/v1/zones/{zone}/dashboard
IPsApicreateIpPOST /instance/v1/zones/{zone}/ipsReserve a flexible IP
IPsApideleteIpDELETE /instance/v1/zones/{zone}/ips/{ip}Delete a flexible IP
IPsApigetIpGET /instance/v1/zones/{zone}/ips/{ip}Get a flexible IP
IPsApilistIpsGET /instance/v1/zones/{zone}/ipsList all flexible IPs
IPsApiupdateIpPATCH /instance/v1/zones/{zone}/ips/{ip}Update a flexible IP
ImagesApicreateImagePOST /instance/v1/zones/{zone}/imagesCreate an Instance image
ImagesApideleteImageDELETE /instance/v1/zones/{zone}/images/{image_id}Delete an Instance image
ImagesApigetImageGET /instance/v1/zones/{zone}/images/{image_id}Get an Instance image
ImagesApilistImagesGET /instance/v1/zones/{zone}/imagesList Instance images
ImagesApisetImagePUT /instance/v1/zones/{zone}/images/{id}Update image
ImagesApiupdateImagePATCH /instance/v1/zones/{zone}/images/{image_id}Update image
InstanceTypesApigetServerTypesAvailabilityGET /instance/v1/zones/{zone}/products/servers/availabilityGet availability
InstanceTypesApilistServersTypesGET /instance/v1/zones/{zone}/products/serversList Instance types
InstancesApicreateServerPOST /instance/v1/zones/{zone}/serversCreate an Instance
InstancesApideleteServerDELETE /instance/v1/zones/{zone}/servers/{server_id}Delete an Instance
InstancesApigetServerGET /instance/v1/zones/{zone}/servers/{server_id}Get an Instance
InstancesApilistServerActionsGET /instance/v1/zones/{zone}/servers/{server_id}/actionList Instance actions
InstancesApilistServersGET /instance/v1/zones/{zone}/serversList all Instances
InstancesApiserverActionPOST /instance/v1/zones/{zone}/servers/{server_id}/actionPerform action
InstancesApiupdateServerPATCH /instance/v1/zones/{zone}/servers/{server_id}Update an Instance
PlacementGroupsApicreatePlacementGroupPOST /instance/v1/zones/{zone}/placement_groupsCreate a placement group
PlacementGroupsApideletePlacementGroupDELETE /instance/v1/zones/{zone}/placement_groups/{placement_group_id}Delete the specified placement group
PlacementGroupsApigetPlacementGroupGET /instance/v1/zones/{zone}/placement_groups/{placement_group_id}Get a placement group
PlacementGroupsApigetPlacementGroupServersGET /instance/v1/zones/{zone}/placement_groups/{placement_group_id}/serversGet placement group servers
PlacementGroupsApilistPlacementGroupsGET /instance/v1/zones/{zone}/placement_groupsList placement groups
PlacementGroupsApisetPlacementGroupPUT /instance/v1/zones/{zone}/placement_groups/{placement_group_id}Set placement group
PlacementGroupsApisetPlacementGroupServersPUT /instance/v1/zones/{zone}/placement_groups/{placement_group_id}/serversSet placement group servers
PlacementGroupsApiupdatePlacementGroupPATCH /instance/v1/zones/{zone}/placement_groups/{placement_group_id}Update a placement group
PlacementGroupsApiupdatePlacementGroupServersPATCH /instance/v1/zones/{zone}/placement_groups/{placement_group_id}/serversUpdate placement group servers
PrivateNICsApicreatePrivateNICPOST /instance/v1/zones/{zone}/servers/{server_id}/private_nicsCreate a private NIC connecting an Instance to a Private Network
PrivateNICsApideletePrivateNICDELETE /instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}Delete a private NIC
PrivateNICsApigetPrivateNICGET /instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}Get a private NIC
PrivateNICsApilistPrivateNICsGET /instance/v1/zones/{zone}/servers/{server_id}/private_nicsList all private NICs
PrivateNICsApiupdatePrivateNICPATCH /instance/v1/zones/{zone}/servers/{server_id}/private_nics/{private_nic_id}Update a private NIC
SecurityGroupsApicreateSecurityGroupPOST /instance/v1/zones/{zone}/security_groupsCreate a security group
SecurityGroupsApicreateSecurityGroupRulePOST /instance/v1/zones/{zone}/security_groups/{security_group_id}/rulesCreate rule
SecurityGroupsApideleteSecurityGroupDELETE /instance/v1/zones/{zone}/security_groups/{security_group_id}Delete a security group
SecurityGroupsApideleteSecurityGroupRuleDELETE /instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}Delete rule
SecurityGroupsApigetSecurityGroupGET /instance/v1/zones/{zone}/security_groups/{security_group_id}Get a security group
SecurityGroupsApigetSecurityGroupRuleGET /instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}Get rule
SecurityGroupsApilistDefaultSecurityGroupRulesGET /instance/v1/zones/{zone}/security_groups/default/rulesGet default rules
SecurityGroupsApilistSecurityGroupRulesGET /instance/v1/zones/{zone}/security_groups/{security_group_id}/rulesList rules
SecurityGroupsApilistSecurityGroupsGET /instance/v1/zones/{zone}/security_groupsList security groups
SecurityGroupsApisetSecurityGroupPUT /instance/v1/zones/{zone}/security_groups/{id}Update a security group
SecurityGroupsApisetSecurityGroupRulePUT /instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}Set security group rule
SecurityGroupsApisetSecurityGroupRulesPUT /instance/v1/zones/{zone}/security_groups/{security_group_id}/rulesUpdate all the rules of a security group
SecurityGroupsApiupdateSecurityGroupPATCH /instance/v1/zones/{zone}/security_groups/{security_group_id}Update a security group
SecurityGroupsApiupdateSecurityGroupRulePATCH /instance/v1/zones/{zone}/security_groups/{security_group_id}/rules/{security_group_rule_id}Update security group rule
SnapshotsApicreateSnapshotPOST /instance/v1/zones/{zone}/snapshotsCreate a snapshot from a specified volume or from a QCOW2 file
SnapshotsApideleteSnapshotDELETE /instance/v1/zones/{zone}/snapshots/{snapshot_id}Delete a snapshot
SnapshotsApiexportSnapshotPOST /instance/v1/zones/{zone}/snapshots/{snapshot_id}/exportExport a snapshot
SnapshotsApigetSnapshotGET /instance/v1/zones/{zone}/snapshots/{snapshot_id}Get a snapshot
SnapshotsApilistSnapshotsGET /instance/v1/zones/{zone}/snapshotsList snapshots
SnapshotsApisetSnapshotPUT /instance/v1/zones/{zone}/snapshots/{snapshot_id}Set snapshot
SnapshotsApiupdateSnapshotPATCH /instance/v1/zones/{zone}/snapshots/{snapshot_id}Update a snapshot
UserDataApideleteServerUserDataDELETE /instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}Delete user data
UserDataApigetServerUserDataGET /instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}Get user data
UserDataApilistServerUserDataGET /instance/v1/zones/{zone}/servers/{server_id}/user_dataList user data
UserDataApisetServerUserDataPATCH /instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}Add/set user data
VolumeTypesApilistVolumesTypesGET /instance/v1/zones/{zone}/products/volumesList volume types
VolumesApiapplyBlockMigrationPOST /instance/v1/zones/{zone}/block-migration/applyMigrate a volume and/or snapshots to SBS (Scaleway Block Storage)
VolumesApicreateVolumePOST /instance/v1/zones/{zone}/volumesCreate a volume
VolumesApideleteVolumeDELETE /instance/v1/zones/{zone}/volumes/{volume_id}Delete a volume
VolumesApigetVolumeGET /instance/v1/zones/{zone}/volumes/{volume_id}Get a volume
VolumesApilistVolumesGET /instance/v1/zones/{zone}/volumesList volumes
VolumesApiplanBlockMigrationPOST /instance/v1/zones/{zone}/block-migration/planGet a volume or snapshot's migration plan
VolumesApisetVolumePUT /instance/v1/zones/{zone}/volumes/{id}Update volume
VolumesApiupdateVolumePATCH /instance/v1/zones/{zone}/volumes/{volume_id}Update a volume

Models

Authorization

Authentication schemes defined for the API:

scaleway

  • Type: API key
  • API key parameter name: X-Auth-Token
  • Location: HTTP header

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: v1
    • Generator version: 7.11.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen