openapi: 3.1.0
info:
title: Managed Database for PostgreSQL and MySQL Access Control List Pools API
description: "Managed Database for PostgreSQL and MySQL provides fully-managed relational Database Instances, with MySQL or PostgreSQL as database engines. The resource allows you to focus on development rather than administration or configuration. It comes with a high-availability mode, data replication, and automatic backups.\n\nCompared to traditional database management, which requires customers to provide their infrastructure and resources to manage their databases, Managed Database for PostgreSQL and MySQL Instance offers the user access to Database Instances without setting up the hardware or configuring the software. Scaleway handles the provisioning, manages the configuration, and provides useful features as high availability, automated backup, user management, and more.\n\n\n\n\n## Concepts\n\nRefer to our [dedicated concepts page](https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/concepts/) to find definitions of the different terms referring to Managed Database for PostgreSQL and MySQL.\n\n\n\n\n## Quickstart\n\n1. Configure your environment variables.\n <Message type=\"note\">\n This is an optional step that seeks to simplify your usage of the APIs.\n </Message>\n\n ```bash\n export SCW_ACCESS_KEY=\"<API access key>\"\n export SCW_SECRET_KEY=\"<API secret key>\"\n export SCW_REGION=\"<Scaleway region>\"\n ```\n2. Edit the POST request payload you will use to create your Database Instance. Replace the parameters in the following example:\n ```json\n '{\n \"project_id\": \"d8e65f2b-cce9-40b7-80fc-6a2902db6826\",\n \"name\": \"myDB\",\n \"engine\": \"PostgreSQL-15\",\n \"tags\": [\"donnerstag\"],\n \"is_ha_cluster\": true,\n \"node_type\": \"db-pro2-xxs\",\n \"disable_backup\": false,\n \"user_name\": \"my_initial_user\",\n \"password\": \"thiZ_is_v0ry_s3cret\",\n \"volume_type\": \"sbs_5k\",\n \"volume_size\": \"30000000000\"\n }'\n ```\n\n | Parameter | Description |\n | :--------------- |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `project_id` | The ID of the Project you want to create your Database Instance in. To find your Project ID you can **[list the projects](/api/account/project-api/#path-projects-list-all-projects-of-an-organization)** or consult the **[Scaleway console](https://console.scaleway.com/project/settings)**. |\n | `engine` | **REQUIRED** Version ID of the database engine. To check the list of available engines you can use the following endpoint: `https://api.scaleway.com/rdb/v1/regions/$SCW_REGION/database-engines` |\n | `name` | Name of the Database Instance |\n | `node_type` | **REQUIRED** The node type. To check the list of available node types you can use the following endpoint: `https://api.scaleway.com/rdb/v1/regions/$SCW_REGION/node-types` |\n | `is_ha_cluster` | **BOOLEAN** Defines whether High Availability is enabled for the Database Instance |\n | `disable_backup` | **BOOLEAN** Defines whether automated backups are disabled for the Database Instance |\n | `tags` | The list of tags `[\"tag1\", \"tag2\", ...]` that will be associated with the Database Instance. Tags can be appended to the query of the [List Database Instances](#path-database-instances-list-database-instances) call to show results for only the Database Instances using a specific tag. You can also combine tags to list Database Instances that possess all the appended tags. |\n | `user_name` | **REQUIRED** Identifier of the default user, which is created concurrently with the Database Instance |\n | `password` | **REQUIRED** Password for the default user |\n | `volume_type` | Type of volume where data is stored. You can specify either local volume (`lssd`) or block volume (`bssd`, `sbs_5k` or `sbs_15k`). The default value is `lssd` |\n | `volume_size` | Volume size when volume_type is `bssd`, `sbs_5k` or `sbs_15k`. The value should be expressed in bytes. For example 30GB is expressed as 30000000000 |\n3. Create a Database Instance by running the following command. Make sure you include the payload you edited in the previous step.\n ```bash\n curl -X POST \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n \"Content-Type: application/json\" \\\n https://api.scaleway.com/rdb/v1/regions/$SCW_REGION/instances \\\n -d '{\n \"project_id\": \"d8e65f2b-cce9-40b7-80fc-6a2902db6826\",\n \"name\": \"myDB\",\n \"engine\": \"PostgreSQL-15\",\n \"tags\": [\"donnerstag\"],\n \"is_ha_cluster\": true,\n \"node_type\": \"db-pro2-xxs\",\n \"disable_backup\": false,\n \"user_name\": \"my_initial_user\",\n \"password\": \"thiZ_is_v0ry_s3cret\",\n \"volume_type\": \"sbs_5k\",\n \"volume_size\": \"30000000000\"\n }'\n ```\n4. List your Database Instances.\n ```bash\n curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" https://api.scaleway.com/rdb/v1/regions/$SCW_REGION/instances\n ```\n\n You should get a response like the following:\n\n <Message type=\"note\">\n This is a response example, the UUIDs and IP address displayed are not real.\n </Message>\n\n ```json\n {\n \"id\": \"f5122f66-fb50-4cef-aa02-487ef4fc1af0\",\n \"name\": \"myDB\",\n \"organization_id\": \"895693aa-3915-4896-8761-c2923b008be7\",\n \"project_id\": \"d8e65f2b-cce9-40b7-80fc-6a2902db6826\",\n \"status\": \"ready\",\n \"engine\": \"PostgreSQL-15\",\n \"endpoint\": {\n \"ip\": \"198.51.100.0\",\n \"port\": 22245,\n \"name\": null\n },\n \"tags\": [\n \"donnerstag\"\n ],\n \"settings\": [],\n \"backup_schedule\": {\n \"frequency\": 24,\n \"retention\": 7,\n \"disabled\": true\n },\n \"is_ha_cluster\": true,\n \"read_replicas\": [],\n \"node_type\": \"db-pro2-xxs\",\n \"volume\": {\n \"type\": \"sbs_5k\",\n \"size\": 30000000000\n }\n \"created_at\": \"2019-04-19T16:24:52.591417Z\",\n \"region\": \"fr-par\"\n }\n ```\n5. Retrieve your Database Instance IP and port from the response.\n <Message type=\"note\">\n In the example above, the IP and port are `198.51.100.0` and `22245`, respectively.\n </Message>\n6. Connect to your Database Instance with the database client of the engine you selected.\n For MySQL, run the following command:\n ```bash\n mysql -h <ip-address> --port <port> -p -u <user_name>\n ```\n\n For PostgreSQL, run:\n ```bash\n psql -h <ip-address> -p <port> -U <username> -d rdb\n ```\n\n For the recurring example, the command would look like:\n\n ```bash\n psql -h 198.51.100.0 -p 22245 -U my_initial_user -d rdb\n ```\n7. Enter the database password that you defined upon creation.\n\nYou are now connected to your Managed Database.\n\n\n<Message type=\"requirement\">\nTo perform the following steps, you must first ensure that:\n - you have an account and are logged into the [Scaleway console](https://console.scaleway.com/organization)\n - you have created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page.\n - you have [installed `curl`](https://curl.se/download.html)\n</Message>\n\n\n## Technical Information\n\n### Regions\n\nScaleway's infrastructure is spread across different [regions and Availability Zones](https://www.scaleway.com/en/docs/account/reference-content/products-availability/).\n\nManaged Database for PostgreSQL and MySQL is available in the Paris, Amsterdam and Warsaw regions, which are represented by the following path parameters:\n\n- `fr-par`\n- `nl-ams`\n- `pl-waw`\n\n### PostgreSQL specifications\n\n#### Versions\n\nScaleway Database for PostgreSQL supports PostgreSQL versions 11, 12, 13, 14 and 15.\n\n#### System\n\nDifferent modules are available for installation, including TimescaleDB and PostGIS. Refer to the [Managed Database for PostgreSQL and MySQL FAQ page](https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/faq/#which-postgresql-extensions-are-available) for an extensive list of PostgreSQL extensions.\n\n#### Database Management\n\nYou can create logical databases through the Scaleway console, the Scaleway APIs or SQL.\n\n- databases created using the Scaleway console or the API are owned by an internal system user. These are called \"managed databases\".\n- databases created using SQL will be owned by the creator. These are called \"unmanaged databases\".\n\n### MySQL specifications\n\n#### Versions\n\nScaleway Database for MySQL supports MySQL 8.\n\n#### System\n\n- only the [InnoDB engine](https://dev.mysql.com/doc/refman/8.0/en/innodb-storage-engine.html) is supported\n- the [Global Transaction Identifier (GTID)](https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-concepts.html) is enabled.\n- [`mysql_native_password`](https://dev.mysql.com/doc/refman/8.0/en/native-pluggable-authentication.html) (default) and [`caching_sha2_password`](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html) authentication are supported.\n\n#### User Management\n\n- users with an `admin` role have access to all logical databases and can create new ones.\n- users created via the API are authenticated using the default authentication plugin, which can be changed in the settings.\n\n## Technical Limitations\n\n### PostgreSQL\n\n#### User Management\n\n- users with an `admin` role have `CREATEROLE` and `CREATEDB` privileges.\n- users do NOT have `SUPERUSER` nor `REPLICATION` privileges.\n- permission management through the Scaleway console or API is only possible for the \"managed databases\".\n\n#### Backup and restoration\n\nDatabases that have been backed up and then restored retain the user permission settings in use at the time of backup. If you delete users after backup and then restore your backup in the same database, or if you restore a backup to a different database with different or no users, the permissions configured for them continue to exist, but with no associated owner. This error will put a stop to the restoration process.\n\nTo avoid this issue, we recommend you re-create the users you deleted. In the occasion you restore the backup to a new database, you must create new users with the same names.\n\n## Going Further\n\nFor more information about Managed Database for PostgreSQL and MySQL, you can check out the following pages:\n\n* [Managed Database for PostgreSQL and MySQL Documentation](https://www.scaleway.com/en/docs/managed-databases/postgresql-and-mysql/)\n* [Managed Database for PostgreSQL and MySQL FAQ](https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/faq/)\n* [Scaleway Slack Community](https://scaleway-community.slack.com/) join the #database channel\n* [Contact our support team](https://console.scaleway.com/support/tickets)\n\n### How to migrate a database\n\nIf you wish to migrate existing databases to a Managed Database for PostgreSQL or MySQL, you can refer to the [Migrating existing databases to a Database Instance](https://www.scaleway.com/en/docs/tutorials/migrate-databases-instance/) tutorial page.\n\n### Troubleshoooting\n\n#### Disk full status\n\nIf your Database Instance uses local storage, your local volume might eventually approach full capacity and shift to `disk_full` mode. This mode grants you enough space to either [upgrade your node type](https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/how-to/upgrade-version/#how-to-change-the-node-type) or [clear out space in your volume](https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/troubleshooting/disk-full/)."
version: v1
servers:
- url: https://api.scaleway.com
tags:
- name: Pools
description: 'A pool is a set of identical nodes
A pool has a name, a size (its desired number of nodes), node number limits (min, max), and a Scaleway Instance type. Changing those limits increases/decreases the size of a pool. As a result and depending on its load, the pool will grow or shrink within those limits when autoscaling is enabled.
'
paths:
/k8s/v1/regions/{region}/clusters/{cluster_id}/pools:
get:
tags:
- Pools
operationId: ListPools
summary: List Pools in a Cluster
description: List all the existing pools for a specific Kubernetes cluster.
parameters:
- in: path
name: region
description: The region you want to target
required: true
schema:
type: string
enum:
- fr-par
- nl-ams
- pl-waw
- in: path
name: cluster_id
description: ID of the cluster whose pools will be listed.
required: true
schema:
type: string
- in: query
name: order_by
description: Sort order of returned pools.
schema:
type: string
enum:
- created_at_asc
- created_at_desc
- updated_at_asc
- updated_at_desc
- name_asc
- name_desc
- status_asc
- status_desc
- version_asc
- version_desc
default: created_at_asc
- in: query
name: page
description: Page number for the returned pools.
schema:
type: integer
format: int32
- in: query
name: page_size
description: Maximum number of pools per page.
schema:
type: integer
format: uint32
- in: query
name: name
description: Name to filter on, only pools containing this substring in their name will be returned.
schema:
type: string
- in: query
name: status
description: Status to filter on, only pools with this status will be returned.
schema:
type: string
enum:
- unknown
- ready
- deleting
- deleted
- scaling
- warning
- locked
- upgrading
x-enum-descriptions:
values:
ready: Pool has the right amount of nodes and is ready to process the workload
deleting: Pool is waiting to be processed for deletion
scaling: Pool is growing or shrinking
warning: Pool has some issues, check nodes
locked: Pool is locked because an abuse has been detected or reported
upgrading: Pool is upgrading its Kubernetes version
default: unknown
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.ListPoolsResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n \"https://api.scaleway.com/k8s/v1/regions/{region}/clusters/{cluster_id}/pools\""
- lang: HTTPie
source: "http GET \"https://api.scaleway.com/k8s/v1/regions/{region}/clusters/{cluster_id}/pools\" \\\n X-Auth-Token:$SCW_SECRET_KEY"
post:
tags:
- Pools
operationId: CreatePool
summary: Create a new Pool in a Cluster
description: Create a new pool in a specific Kubernetes cluster.
parameters:
- in: path
name: region
description: The region you want to target
required: true
schema:
type: string
enum:
- fr-par
- nl-ams
- pl-waw
- in: path
name: cluster_id
description: Cluster ID to which the pool will be attached.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.Pool'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Pool name.
node_type:
type: string
description: Node type is the type of Scaleway Instance wanted for the pool. Nodes with insufficient memory are not eligible (DEV1-S, PLAY2-PICO, STARDUST). 'external' is a special node type used to provision instances from other cloud providers in a Kosmos Cluster.
placement_group_id:
type: string
description: Placement group ID in which all the nodes of the pool will be created, placement groups are limited to 20 instances.
nullable: true
autoscaling:
type: boolean
description: Defines whether the autoscaling feature is enabled for the pool.
size:
type: integer
description: Size (number of nodes) of the pool.
format: uint32
min_size:
type: integer
description: Defines the minimum size of the pool. Note that this field is only used when autoscaling is enabled on the pool.
format: uint32
nullable: true
max_size:
type: integer
description: Defines the maximum size of the pool. Note that this field is only used when autoscaling is enabled on the pool.
format: uint32
nullable: true
container_runtime:
type: string
description: Customization of the container runtime is available for each pool.
enum:
- unknown_runtime
- docker
- containerd
- crio
x-enum-descriptions:
values:
containerd: Containerd Runtime will be configured (https://github.com/containerd/containerd)
default: unknown_runtime
autohealing:
type: boolean
description: Defines whether the autohealing feature is enabled for the pool.
tags:
type: array
description: Tags associated with the pool, see [managing tags](https://www.scaleway.com/en/docs/kubernetes/api-cli/managing-tags).
items:
type: string
kubelet_args:
type: object
description: Kubelet arguments to be used by this pool. Note that this feature is experimental.
properties:
<kubelet_argKey>:
type: string
description: Kubelet arguments to be used by this pool. Note that this feature is experimental.
additionalProperties: true
upgrade_policy:
type: object
description: Pool upgrade policy.
properties:
max_unavailable:
$ref: '#/components/schemas/google.protobuf.UInt32Value'
max_surge:
$ref: '#/components/schemas/google.protobuf.UInt32Value'
x-properties-order:
- max_unavailable
- max_surge
zone:
type: string
description: Zone in which the pool's nodes will be spawned.
root_volume_type:
type: string
description: 'Defines the system volume disk type. Several types of volume (`volume_type`) are provided:.
* `l_ssd` is a local block storage which means your system is stored locally on your node''s hypervisor. This type is not available for all node types
* `sbs_5k` is a remote block storage which means your system is stored on a centralized and resilient cluster with 5k IOPS limits
* `sbs_15k` is a faster remote block storage which means your system is stored on a centralized and resilient cluster with 15k IOPS limits
* `b_ssd` is the legacy remote block storage which means your system is stored on a centralized and resilient cluster. Not available for new pools, use `sbs_5k` or `sbs_15k` instead.'
enum:
- default_volume_type
- l_ssd
- b_ssd
- sbs_5k
- sbs_15k
x-enum-descriptions:
values:
l_ssd: 'Local Block Storage: your system is stored locally on your node hypervisor'
b_ssd: 'Remote Block Storage: your system is stored on a centralized and resilient cluster (deprecated: will use sbs_5k instead)'
sbs_5k: 'Remote Block Storage: your system is stored on a centralized and resilient cluster with up to 5k IOPS'
sbs_15k: 'Remote Block Storage: your system is stored on a centralized and resilient cluster with up to 15k IOPS'
default: default_volume_type
root_volume_size:
type: integer
description: System volume disk size. (in bytes)
format: uint64
nullable: true
public_ip_disabled:
type: boolean
description: Defines if the public IP should be removed from Nodes. To use this feature, your Cluster must have an attached Private Network set up with a Public Gateway.
security_group_id:
type: string
description: Security group ID in which all the nodes of the pool will be created. If unset, the pool will use default Kapsule security group in current zone.
labels:
type: object
description: Kubernetes labels applied and reconciled on the nodes.
properties:
<labelKey>:
type: string
description: Kubernetes labels applied and reconciled on the nodes.
additionalProperties: true
taints:
type: array
description: Kubernetes taints applied and reconciled on the nodes.
items:
$ref: '#/components/schemas/scaleway.k8s.v1.CoreV1Taint'
startup_taints:
type: array
description: Kubernetes taints applied at node creation but not reconciled afterwards.
items:
$ref: '#/components/schemas/scaleway.k8s.v1.CoreV1Taint'
required:
- name
- node_type
- size
x-properties-order:
- name
- node_type
- placement_group_id
- autoscaling
- size
- min_size
- max_size
- container_runtime
- autohealing
- tags
- kubelet_args
- upgrade_policy
- zone
- root_volume_type
- root_volume_size
- public_ip_disabled
- security_group_id
- labels
- taints
- startup_taints
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: "curl -X POST \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"autohealing\": false,\n \"autoscaling\": false,\n \"kubelet_args\": {\n \"<kubelet_argKey>\": \"string\"\n },\n \"labels\": {\n \"<labelKey>\": \"string\"\n },\n \"name\": \"string\",\n \"node_type\": \"string\",\n \"public_ip_disabled\": false,\n \"size\": 42,\n \"zone\": \"string\"\n }' \\\n \"https://api.scaleway.com/k8s/v1/regions/{region}/clusters/{cluster_id}/pools\""
- lang: HTTPie
source: "http POST \"https://api.scaleway.com/k8s/v1/regions/{region}/clusters/{cluster_id}/pools\" \\\n X-Auth-Token:$SCW_SECRET_KEY \\\n autohealing:=false \\\n autoscaling:=false \\\n kubelet_args:='{\n \"<kubelet_argKey>\": \"string\"\n }' \\\n labels:='{\n \"<labelKey>\": \"string\"\n }' \\\n name=\"string\" \\\n node_type=\"string\" \\\n public_ip_disabled:=false \\\n size:=42 \\\n zone=\"string\""
/k8s/v1/regions/{region}/pools/{pool_id}:
get:
tags:
- Pools
operationId: GetPool
summary: Get a Pool in a Cluster
description: Retrieve details about a specific pool in a Kubernetes cluster.
parameters:
- in: path
name: region
description: The region you want to target
required: true
schema:
type: string
enum:
- fr-par
- nl-ams
- pl-waw
- in: path
name: pool_id
description: ID of the requested pool.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.Pool'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n \"https://api.scaleway.com/k8s/v1/regions/{region}/pools/{pool_id}\""
- lang: HTTPie
source: "http GET \"https://api.scaleway.com/k8s/v1/regions/{region}/pools/{pool_id}\" \\\n X-Auth-Token:$SCW_SECRET_KEY"
patch:
tags:
- Pools
operationId: UpdatePool
summary: Update a Pool in a Cluster
description: Update the attributes of a specific pool, such as its desired size, autoscaling settings, and tags. To upgrade a pool, you will need to use the dedicated endpoint.
parameters:
- in: path
name: region
description: The region you want to target
required: true
schema:
type: string
enum:
- fr-par
- nl-ams
- pl-waw
- in: path
name: pool_id
description: ID of the pool to update.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.Pool'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
autoscaling:
type: boolean
description: New value for the pool autoscaling enablement.
nullable: true
size:
type: integer
description: New desired pool size.
format: uint32
nullable: true
min_size:
type: integer
description: New minimum size for the pool.
format: uint32
nullable: true
max_size:
type: integer
description: New maximum size for the pool.
format: uint32
nullable: true
autohealing:
type: boolean
description: New value for the pool autohealing enablement.
nullable: true
tags:
type: array
description: New tags associated with the pool.
nullable: true
items:
type: string
kubelet_args:
type: object
description: New Kubelet arguments to be used by this pool. Note that this feature is experimental.
properties:
<key>:
type: string
nullable: true
upgrade_policy:
type: object
description: New upgrade policy for the pool.
properties:
max_unavailable:
$ref: '#/components/schemas/google.protobuf.UInt32Value'
max_surge:
$ref: '#/components/schemas/google.protobuf.UInt32Value'
x-properties-order:
- max_unavailable
- max_surge
security_group_id:
type: string
description: Security group ID in which all the nodes of the pool will be moved.
x-properties-order:
- autoscaling
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scaleway/refs/heads/main/openapi/scaleway-pools-api-openapi.yml