openapi: 3.1.0
info:
title: Managed Database for PostgreSQL and MySQL Access Control List Clusters 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: Clusters
description: 'A cluster is a fully managed Kubernetes cluster
It is composed of different pools, each pool containing the same kind of nodes.
'
paths:
/k8s/v1/regions/{region}/clusters:
get:
tags:
- Clusters
operationId: ListClusters
summary: List Clusters
description: List all existing Kubernetes clusters in a specific region.
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: query
name: organization_id
description: Organization ID on which to filter the returned clusters.
schema:
type: string
- in: query
name: project_id
description: Project ID on which to filter the returned clusters.
schema:
type: string
- in: query
name: order_by
description: Sort order of returned clusters.
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 to return for clusters, from the paginated results.
schema:
type: integer
format: int32
- in: query
name: page_size
description: Maximum number of clusters per page.
schema:
type: integer
format: uint32
- in: query
name: name
description: Name to filter on, only clusters containing this substring in their name will be returned.
schema:
type: string
- in: query
name: status
description: Status to filter on, only clusters with this status will be returned.
schema:
type: string
enum:
- unknown
- creating
- ready
- deleting
- deleted
- updating
- locked
- pool_required
x-enum-descriptions:
values:
creating: Cluster is provisioning
ready: Cluster is ready to use
deleting: Cluster is waiting to be processed for deletion
updating: Cluster is updating its own configuration, it can be a version upgrade too
locked: Cluster is locked because an abuse has been detected or reported
pool_required: Cluster has no associated pool and has been shutdown
default: unknown
- in: query
name: type
description: Type to filter on, only clusters with this type will be returned.
schema:
type: string
- in: query
name: private_network_id
description: Private Network ID to filter on, only clusters within this Private Network will be returned.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.ListClustersResponse'
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\""
- lang: HTTPie
source: "http GET \"https://api.scaleway.com/k8s/v1/regions/{region}/clusters\" \\\n X-Auth-Token:$SCW_SECRET_KEY"
post:
tags:
- Clusters
operationId: CreateCluster
summary: Create a new Cluster
description: Create a new Kubernetes cluster in a Scaleway region.
parameters:
- in: path
name: region
description: The region you want to target
required: true
schema:
type: string
enum:
- fr-par
- nl-ams
- pl-waw
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.k8s.v1.Cluster'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organization_id:
type: string
description: Organization ID in which the cluster will be created.
deprecated: true
nullable: true
x-one-of: ProjectIdentifier
project_id:
type: string
description: Project ID in which the cluster will be created.
nullable: true
x-one-of: ProjectIdentifier
type:
type: string
description: Type of the cluster. See [list available cluster types](#list-available-cluster-types-for-a-cluster) for a list of valid types.
name:
type: string
description: Cluster name.
description:
type: string
description: Cluster description.
tags:
type: array
description: Tags associated with the cluster.
items:
type: string
version:
type: string
description: Kubernetes version of the cluster.
cni:
type: string
description: Container Network Interface (CNI) plugin running in the cluster.
enum:
- unknown_cni
- cilium
- calico
- weave
- flannel
- kilo
- none
- cilium_native
x-enum-descriptions:
values:
cilium: Cilium CNI will be configured (https://github.com/cilium/cilium)
calico: Calico CNI will be configured (https://github.com/projectcalico/calico)
kilo: Kilo CNI will be configured (https://github.com/squat/kilo/). Note that this CNI is only available for Kosmos clusters
none: Does not install any CNI. This feature is only available through a ticket and is not covered by support.
cilium_native: Cilium CNI will be configured in native routing mode (https://docs.cilium.io/en/stable/network/concepts/routing/#native-routing)
default: unknown_cni
pools:
type: array
description: Pools created along with the cluster.
items:
$ref: '#/components/schemas/scaleway.k8s.v1.CreateClusterRequest.PoolConfig'
autoscaler_config:
type: object
description: Autoscaler configuration for the cluster. It allows you to set (to an extent) your preferred autoscaler configuration, which is an implementation of the cluster-autoscaler (https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/).
properties:
scale_down_disabled:
type: boolean
description: Forbid cluster autoscaler to scale down the cluster, defaults to false.
nullable: true
scale_down_delay_after_add:
type: string
description: How long after scale up the scale down evaluation resumes.
nullable: true
estimator:
type: string
description: Type of resource estimator to be used in scale up.
enum:
- unknown_estimator
- binpacking
default: unknown_estimator
expander:
type: string
description: Kubernetes autoscaler strategy to fit pods into nodes, see https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#what-are-expanders for details.
enum:
- unknown_expander
- random
- most_pods
- least_waste
- priority
- price
default: unknown_expander
ignore_daemonsets_utilization:
type: boolean
description: Ignore DaemonSet pods when calculating resource utilization for scaling down, defaults to false.
nullable: true
balance_similar_node_groups:
type: boolean
description: Detect similar node groups and balance the number of nodes between them, defaults to false.
nullable: true
expendable_pods_priority_cutoff:
type: integer
description: Pods with priority below cutoff will be expendable. They can be killed without any consideration during scale down and they won't cause scale up. Pods with null priority (PodPriority disabled) are non expendable.
format: int32
nullable: true
scale_down_unneeded_time:
type: string
description: How long a node should be unneeded before it is eligible for scale down, defaults to 10 minutes.
nullable: true
scale_down_utilization_threshold:
type: object
description: Node utilization level, defined as a sum of requested resources divided by allocatable capacity, below which a node can be considered for scale down.
properties:
value:
type: number
format: float
x-properties-order:
- value
max_graceful_termination_sec:
type: integer
description: Maximum number of seconds the cluster autoscaler waits for pod termination when trying to scale down a node, defaults to 600 (10 minutes).
format: uint32
nullable: true
skip_nodes_with_local_storage:
type: boolean
description: Cluster autoscaler will never delete nodes with pods with local storage, e.g. EmptyDir or HostPath, defaults to true.
log_level:
type: integer
description: Cluster autoscaler logging level expressed from 0 to 4 (4 being the more verbose), defaults to 2. see https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#how-can-i-increase-the-information-that-the-ca-is-logging for details.
format: int32
x-properties-order:
- scale_down_disabled
- scale_down_delay_after_add
- estimator
- expander
- ignore_daemonsets_utilization
- balance_similar_node_groups
- expendable_pods_priority_cutoff
- scale_down_unneeded_time
- scale_down_utilization_threshold
- max_graceful_termination_sec
- skip_nodes_with_local_storage
- log_level
auto_upgrade:
type: object
description: Auto upgrade configuration of the cluster. This configuration enables to set a specific 2-hour time window in which the cluster can be automatically updated to the latest patch version.
properties:
enable:
type: boolean
description: Defines whether auto upgrade is enabled for the cluster.
maintenance_window:
type: object
description: Maintenance window of the cluster auto upgrades.
properties:
start_hour:
type: integer
description: Start time of the two-hour maintenance window.
format: uint32
day:
type: string
description: Day of the week for the maintenance window.
enum:
- any
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
default: any
x-properties-order:
- start_hour
- day
x-properties-order:
- enable
- maintenance_window
feature_gates:
type: array
description: List of feature gates to enable.
items:
type: string
admission_plugins:
type: array
description: List of admission plugins to enable.
items:
type: string
open_id_connect_config:
type: object
description: OpenID Connect configuration of the cluster. This configuration enables to update the OpenID Connect configuration of the Kubernetes API server.
properties:
issuer_url:
type: string
description: URL of the provider which allows the API server to discover public signing keys. Only URLs using the `https://` scheme are accepted. This is typically the provider's discovery URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".
client_id:
type: string
description: A client ID that all tokens must be issued for.
username_claim:
type: string
description: JWT claim to use as the user name. The default is `sub`, which is expected to be the end user's unique identifier. Admins can choose other claims, such as `email` or `name`, depending on their provider. However, claims other than `email` will be prefixed with the issuer URL to prevent name collision.
nullable: true
username_prefix:
type: string
description: Prefix prepended to username claims to prevent name collision (such as `system:` users). For example, the value `oidc:` will create usernames like `oidc:jane.doe`. If this flag is not provided and `username_claim` is a value other than `email`, the prefix defaults to `( Issuer URL )#` where `( Issuer URL )` is the value of `issuer_url`. The value `-` can be used to disable all prefixing.
nullable: true
groups_claim:
type: array
description: JWT claim to use as the user's group.
nullable: true
items:
type: string
groups_prefix:
type: string
description: Prefix prepended to group claims to prevent name collision (such as `system:` groups). For example, the value `oidc:` will create group names like `oidc:engineering` and `oidc:infra`.
nullable: true
required_claim:
type: array
description: Multiple key=value pairs describing a required claim in the ID token. If set, the claims are verified to be present in the ID token with a matching value.
nullable: true
items:
type: string
x-properties-order:
- issuer_url
- client_id
- username_claim
- username_prefix
- groups_claim
- groups_prefix
- required_claim
apiserver_cert_sans:
type: array
description: Additional Subject Alternative Names for the Kubernetes API server certificate.
items:
type: string
private_network_id:
type: string
description: Private network ID for internal cluster communication (cannot be changed later).
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scaleway/refs/heads/main/openapi/scaleway-clusters-api-openapi.yml