Aller au contenu principal

Démarrage rapide

Prérequis pour suivre ce tutoriel​

Afin de profiter des fonctionnalités de gestion de base de données PostgreSQL depuis la plateforme NumSpot, les prérequis sont :

  • Un compte utilisateur NumSpot actif et connecté détenant le rôle Postgres Admin.
  • Ce compte doit être rattaché à un espace NumSpot.

De plus, certaines des commandes fournies à titre d'exemple dans ce document utilisent l'application psql. Il est donc nécessaire que cet outil soit disponible dans l'environnement d'exécution.

Préparer mon environnement d'exécution​

Les interactions avec l'API HTTP de NumSpot nécessitent d'être authentifié par un jeton d'accès (Access Token) dans une région et un espace donné. Il est donc nécessaire de préparer un environnement d'exécution en conséquence. Cet environnement sera utilisé par les commandes fournies dans ce document. Nous utiliserons la région cloudgouv-eu-west-1.

Générer mon access token​

Les API ont besoin d'avoir un token d'accès valide pour fonctionner. Il est de la forme bearer.

Exemple de demande de token
export REGION="myregion"
curl -X POST https://api.$REGION.numspot.cloud/iam/token \
-H 'Accept: */*' \
-u "${SA_idKey}":"${SA_KeyPass}" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=openid+offline_access'

Une fois que le token est renvoyé, il faudra l'ajouter aux autres demandes sous cette forme :

Ajout d'un token d'accès dans l'entête d'une requête Curl
curl  ... -H "Authorization: Bearer {token}"

Déclarer mon environnement​

Préparation de l'environnement d'exécution
export REGION="cloudgouv-eu-west-1"
export SPACE_ID="5ab07e66-3e16-4c6b-b8ff-82af206a603a"
export ACCESS_TOKEN="myaccesstoken"
info

L'identifiant unique de l'espace (SPACE_ID) peut être récupéré via la console à partir de mon menu latéral gauche : IAM > Espaces

Créer mon premier cluster PostgreSQL​

Pour commencer, nous allons configurer un cluster PostgreSQL basique adapté à un environnement de développement ou de prototypage.

Pour créer votre premier cluster PostgreSQL managé, requêtez le point d’accès : /postgresql/spaces/$SPACE_ID/clusters

Puis personnalisez certains champs de la requête :

  • name : le nom du cluster.
  • automaticBackup : les backups automatiques quotidiens (true/false).
  • user : le login admin.
  • allowedIpRanges : le(s) masque(s) réseau(x) autorisés à accéder à la base PostgreSQL managée.
info

Le mot de passe admin sera transmis dans la réponse à cette requête.

Exemple de requête : Création d'un cluster PostgreSQL managé
curl -X POST \
    --url https://api.$REGION.numspot.com/postgresql/spaces/$SPACE_ID/clusters \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data '{
        "name": "myfirstcluster",
        "automaticBackup": true,
        "user": "admin",
        "nodeConfiguration": {
            "vcpuCount": 2,
            "performanceLevel": "MEDIUM",
            "memorySizeGiB": 4
        },
        "volume": {
            "type": "GP2",
            "sizeGiB": 10
        },
        "tags": [
            {"key": "Key2", "value": "Value3"}
        ],
        "allowedIpRanges": ["X.X.X.X/X"]
    }'

Cette commande crée un cluster PostgreSQL nommé “myfirstcluster” dans NumSpot avec les backups quotidiens automatiques, 10 Gio de stockage, 4 Gio de RAM, 2 vCPU en performance Medium et le login admin fourni.

Exemple de réponse : Création d'un cluster PostgreSQL managé
{
    "allowedIpRanges": ["X.X.X.X/X"],
    "automaticBackup": true,
    "createdOn": "2024-10-17T08:26:32Z",
    "id": "b95f6603-96f9-4c28-89c8-42555048afde",
    "lastOperationName": "CREATE",
    "lastOperationResult": "IN_PROGRESS",
    "name": "myfirstcluster",
    "nodeConfiguration": {
        "memorySizeGiB": 4,
        "performanceLevel": "MEDIUM",
        "vcpuCount": 2
    },
    "password": "gOMsGFN~HdUuSCq9syfc.695Pao+H/}2",
    "status": "CREATING",
    "tags": [
        {"key": "Key2", "value": "Value3"}
    ],
    "user": "admin",
    "volume": {
        "sizeGiB": 10,
        "type": "GP2"
    }
}
  • Le champ status indique que l'état actuel de votre cluster est en cours de provisionnement.
  • Le champ lastOperationName indique que la dernière opération demandée est la création.
  • Le champ lastOperationResult indique que l’état actuel de la dernière opération demandée est en cours.
  • Le champ password est le mot de passe de l’utilisateur administrateur spécifié lors de la demande de création.
info

Veillez à bien enregistrer votre mot de passe administrateur, ce dernier est généré de manière automatique et sécurisée sans être stocké sur nos infrastructures.

Suivre l’état de provisionnement du cluster​

L’état d’avancement de la création du cluster et les différentes informations relatives à ce dernier sont disponibles via le point d’accès : /postgresql/spaces/$SPACE_ID/clusters/<CLUSTER_ID>

Exemple de requête : Suivre l’état de création d'un cluster PostgreSQL managé
curl -X GET \
    --url https://api.$REGION.numspot.com/postgresql/spaces/$SPACE_ID/clusters/$CLUSTER_ID \
    --header "Authorization: Bearer ${ACCESS_TOKEN}"
Exemple de réponse : Suivre l’état de création d'un cluster PostgreSQL managé
{
    "allowedIpRanges": ["X.X.X.X/X"],
    "automaticBackup": true,
    "createdOn": "2024-10-17T08:26:32Z",
    "host": "b95f6603-96f9-4c28-89c8-42555048afde.cloud-api.cloudgouv-eu-west-1.numspot.com/postgresql",
    "id": "b95f6603-96f9-4c28-89c8-42555048afde",
    "lastOperationName": "CREATE",
    "lastOperationResult": "SUCCEEDED",
    "name": "mydatabase",
    "nodeConfiguration": {
        "memorySizeGiB": 4,
        "performanceLevel": "MEDIUM",
        "vcpuCount": 2
    },
    "port": 5432,
    "status": "READY",
    "tags": [
        {"key": "Key2", "value": "Value3"}
    ],
    "user": "admin",
    "volume": {
        "sizeGiB": 10,
        "type": "GP2"
    }
}
  • Le champ host est l'adresse de connexion du cluster.
  • Lorsque le champ status passe à READY, alors votre cluster est provisionné et prêt à être utilisé.

Me connecter à mon cluster​

Avec l'application psql, tapez la commande suivante pour vous connecter à votre cluster :

Exemple de commande : se connecter à mon cluster
psql -h $CLUSTER_ID.cloud-postgresql.prod.cloudgouv-eu-west-1.numspot.com  -p 5432 -U $USER -d postgres -W
  • -h <host> : le nom d'hôte ou l'adresse IP du cluster PostgreSQL managé.
  • -p <port> : le port d'écoute du serveur PostgreSQL.
  • -U <username> : l'utilisateur admin spécifié à la création du cluster.
  • -d : la base de données cible à laquelle se connecter.
  • -W : cette option demandera d'entrer le mot de passe admin après avoir lancé la commande.

Vous avez maintenant un cluster PostgreSQL managé sur NumSpot, prêt à l'emploi. Vous pouvez l'utiliser pour stocker et gérer les données de vos applications tout en bénéficiant des fonctionnalités de la plateforme NumSpot.