Introduction

L'interface d'Oracle Cloud Infrastructure permet d'accéder à l'ensemble des services du Cloud Oracle (Instances, Governance, Object Storage, Autonomous Database, Block Storage, ...). Cependant, pour contrôler efficacement les ressources de ces services, une solution d'automatisation, via des clients pour OCI, est parfois nécessaire afin de s'affranchir des limitations de l'interface graphique.  

Quels sont les choix possibles de clients pour mettre en place cette automatisation ?

Il existe trois clients, proposés nativement par Oracle, pouvant offrir une telle solution :

• OCI CLI : C'est une interface en lignes de commandes, basée sur python, qui permet d'administrer les services OCI. L'utilisation d'OCI CLI nécessite d'effectuer une installation du client depuis le github d'Oracle.
• OCI SDK : C'est un kit de développement (disponible pour Java, Python, Ruby) permettant de développer des outils ou des applications pour s'intégrer aux services OCIs.
• REST API : Les services OCI sont accessibles en utilisant une URL HTTPS à destination d'un REST Endpoint qui représente le serveur REST à contacter dans votre domaine OCI. REST API se base sur l'envoi de demandes vers ces URL HTTPS. Aucune installation particulière n'est nécessaire pour faire fonctionner les REST API.

Tous ces clients se basent sur une authentification sur OCI par une clef RSA et les identifiants OCI (OCID) des tenants, compartments, users et services. C'est le client REST API que je vous propose de découvrir aujourd'hui.  

Présentation REST API

 

Les URL REST API

Les commandes REST API vont donc contacter les services OCIs via  une URL d'accès :

https://rest-server/endpoint

rest-server : il s'agit du serveur REST à contacter pour vos services OCI. Ce nom de serveur se compose généralement du nom du service OCI (database, objectstorage, ...) suivi du nom de la région. Voici quelques exemples :

objectstorage.eu-frankfurt-1.oraclecloud.com
database.us-ashburn-1.oraclecloud.com

endpoint : C'est une adresse relative définissant le endpoint (le type de service) à atteindre. Elle est généralement composée de la version de l'API suivant du chemin de la ressource cible. Voici quelques exemples :

# Pour les accès VCN
20160918/vcns

# Pour les accès aux bases Autonomous
20160918/autonomousDatabases

Les méthodes REST API

Il existe quatre méthodes différentes pour envoyer des commandes aux services OCI :

• DELETE : Pour supprimer une ressource ou un objet dans OCI.
• GET : Pour récupérer des informations sur une ressource spécifique dans OCI.
• POST : Pour manager (créer, démarrer, arrêter) une ressource spécifique dans OCI.
• PUT : Pour configurer une ressource spécifique dans OCI.

L'authentification REST API

L'accès aux services OCI se fait de manière sécurisée via le protocole HTTPS. L'authentification se fait via un compte OCI disposant des droits nécessaires pour effectuer les opérations. La partie sécurité de cet accès s'effectue via les API Keys (déclaration de clef RSA). Passons maintenant aux travaux pratiques !  

Configuration REST API

Je dispose d'un tenant OCI sur la région de Frankfort et d'un compte d'accès. Je vais utiliser un serveur Linux qui me servira de client pour accéder aux différents services OCI via les REST API.  

Génération d'une clef privée RSA

La première opération est de créer une clef RSA sur le serveur Linux. Cette clef servira à l'authentification vers OCI. Nous allons créer un répertoire qui hébergera notre clef RSA privée ainsi que nos scripts REST API :

# mkdir ~/.oci

Ensuite, il nous faut créer une clef RSA 2018 bits au format PEM. Le nom de la clef générée sera oci_api_key.pem :

# openssl genpkey -out ~/.oci/oci_api_key.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
...........................................+++
.+++
# ls -l ~/.oci/oci_api_key.pem
-rw-r--r--. 1 oracle oinstall 1704 Feb 7 11:42 /home/oracle/.oci/oci_api_key.pem
# cat ~/.oci/oci_api_key.pem
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCbEyCceLoI7WdE
beYc69A03g8ifq64WRwORDRIeQ8PTYdR9r2x1wZIyxwDBO+b7iJAtThoOkVap8QK
LAF4bdUt83e0ijeG+dKatV5q+Wyl4MazkSmu/h4ehm2q5TCOAorXzvpnhY8opzxL
3Xk2+Cq7gTCz2lLv4tpk/sDj1a9p1jM4ayHcC6PzA0rVWXc7rvYm3QYn6PSBEhz+
IJBL2WEsORP+rrGm0wbzCohonip9Fb41UzT/Vo/NMEa3Ypl7bpIAHknW6QiuL9YJ
2gZ20h1YwTsj0C0ombMtPXoTL0rR+GL//gk/l+z1cxwwM1t4ApJc2JSLL0Ep1Yq0
ve+8ju//o32Y7E1si2uSvfWCErzGxSHQqe3wyKI3f5+wzhbKOoOnv/OXo6ysVGEq
a7rKVhtiib0CgYBntlciaqYHYvFHr0hiXhpVjXawTpweH3pK/0pgRVaU2lJnuPwr
MPJ2GcVTpGtUV/S5I5X9a3pnFPc3z1Vj7wd0+2zfViieCW4vfgthd3IAvzRt+xBA
x1J4Yz+OcDNTe15m9yQSJuUxlPWWdWk4K9KUW6k4LZnKCpZersDsI0FPJZOpzP1X
ZwFiuJD9m4xUfHf9EY5qrHtD2tYQOhM0OroLrSBLkAECgYEA9ZEdaJceu1t7hN1h
aKmu/TwEWKjXXP56SaW0Df+wwn+If7k4WvjfrAr9TZ4J940rioKqRrHehjvoy2ZH
/iDpSyYEPnG2ck3iDdJL45d4++ECgYEA65RzD8r7yVZbiS4Yj1/fwf+rYNT4Zy9H
OZheikVMENRB4qqZcmSlsbzdItN2vGf8b39DSl008dPivFQz7f/u7GvdgAkh5Yi6
Z3PZVjFlfnboNzRVxH+uD9ZY3yyy1TKrjvsCvk4sBwvobt+yBMx+6eCEeS5sC4e8
6Jubdwuk9hU2t/WCxTIzsm0rg0CyOrB2UBGbtf7euJ+n3J2VcBLkaHvi7kbBGS6v
Y79Do9AYWDwnX2nRgx5F9riONMkCgYEAwnXBqkbfXABXaDAIvzLaPridvhvtkWK+
2fvC5DmF24cPkEYJumMcigRUjngHKwUe7VDjlBD7ugtslRh/7fKqE+EVWuDFgPFT
XehOOw2bldjhOwTi13IRLCB27ktQDG2VOlIfihCOFNDeGntDNBQ1N4q0srXK5von
AR4dq/z1/3ivivkXMwRusF7caVb+bJDt4s+SJNpDIffQcOtkXuKgjJGEdoOVCTyx
5KAkTzy6snFGxM+8Rfy/j+BziIJk1rDHjc1BFWCowraF5G5JnEGS26Ny8QKBgHmP
9Z5FqdGwoPOPu5gS6R32eR3kBZIyQY6xdPcJAqXme5M8RU6QMMISzO03GXwKOngu
nI7JpJhcrcuuLKe8zjvHaQii3pGf5c7RuTU071edAoGBAIwWO8PVX5FsT1lJ5Hfu
hwWDB3RYXRh3wvK/TEG2UJ14yRvf5rk5hzii7nQ8xxsbhnSQ97fuDtyoy+JT60s6
j2TTvhEPfARSjyta+9pF00wE0zqqNzoLLmeXpK+4vTSS4hUSYuqbIWwt/N/4unPx
FdVHqgXYxn1qaIcGQE6X06yY
-----END PRIVATE KEY-----

 

Génération de la clef publique RSA

L'étape suivante consiste à créer la clef publique (oci_api_key.pem) associée à notre clef privée. C'est cette clef qui sera à uploader dans la console OCI :

# openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
writing RSA key
# cat ~/.oci/oci_api_key_public.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmxMgnHi6CO1nRCwBeG3V
im+JsFpQSLuuvitzkjqRI2DJ5pnxHGql0GVADHkD4ZtC7dKyOfFlncAGDw1Go4lK
BM1jpJxi27jsznJuYrbX5MvYk+6PkyimmKlVLtvx+kKiMQhVRYzbgocGA6naX+Uq
LDkT/q6xptMG8wqIaJ4qfRW+NVM0/1aPzTBGt2KZe26SAB5J1ukIri/WCdoGdtId
WME7I9AtKJmzLT16Ey9K0fhi//4JP5fs9XMcMDNbeAKSXNiUiy9BKdWKtL3vvI7v
/6N9mOxNbItrkr31ghK8xsUh0Knt8MiiN3+fsM4WyjqDp7/zl6OsrFRhKqtxwy6J
ZQIDAQAB
-----END PUBLIC KEY-----

 

Configuration d'une API Key

Voici la procédure à suivre pour configurer, grâce à la clef publique, l'authentification sur OCI. Cette clef est à configurer au niveau de notre compte OCI dans la partie API key. Voici comment procéder. Connectons nous à la console Identity Management via la lien suivant (ici pour la région de Frankfort) :

https://console.eu-frankfurt-1.oraclecloud.com/a/identity/users

Nous arrivons à la fenêtre de configuration des comptes OCI : Choisissons ensuite le compte utilisateur où nous souhaitons créer notre API Key : Cliquez sur le bouton "Add Public Key" et copiez le contenu de la clef publique générée dans la fenêtre :

  La configuration de l'API Key est terminée.  

Récupération des OCIDs

Pour l'accès aux services OCI, nous avons besoin de récupérer les différents OCIDs de nos ressources. Nous devons récupérer le fingerprint de l'API Keys que nous avons créée. Cette information est visible dans la fenêtre de détail de notre compte : Nous devons récupérer notre user OCID (visible dans les informations principales de notre compte). Vous pouvez utiliser le lien "Copy" pour le copier directement : En dernier, il reste le plus important, le tenant OCID. Pour le trouver, il faut naviguer dans le menu principal dans "Administration > Tenancy Details". L'OCID du tenant est disponible dans les informations du tenancy :  

Installation d'OCI-CURL

Pour faciliter l'utilisation des REST API, Oracle propose un petit script bash à récupérer sur le lien suivant : https://docs.cloud.oracle.com/en-us/iaas/Content/Resources/Assets/signing_sample_bash.txt Le principe est simple : Ce script contient une fonction oci-curl qui pourra être appelée en bash afin d'accéder aux services OCI en simplifiant la gestion des authentifications, notamment le renouvellement de tokens (pour plus d'informations, voir le lien : https://docs.cloud.oracle.com/fr-fr/iaas/Content/API/Concepts/signingrequests.htm) Nous allons créer un nouveau répertoire nommé oci-curl et y télécharger ce fichier via l'outil curl. Atttention, le fichier étant en UTF-8 , il est nécessaire d'y enlever le BOM (Byte Order Mark) :

# mkdir ~/oci-curl
# curl -L https://docs.cloud.oracle.com/iaas/Content/Resources/Assets/signing_sample_bash.txt  | sed -e '1s/^.*#/#/' > ~/oci-curl/oci-curl.sh
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100   162  100   162    0     0     26      0  0:00:06  0:00:06 --:--:--    46
100  4764  100  4764    0     0    780      0  0:00:06  0:00:06 --:--:--   780

Une fois le téléchargement terminé, nous devons éditer ce bash (nommé oci-curl.sh) pour y inclure les différents OCIDs récupérés au chapitre précédent : On donne ensuite les droits d'exécution à ce script puis nous le lançons afin de charger la fonction oci-curl sur notre session :

# chmod 700 ~/oci-curl/oci-curl.sh
# . ~/oci-curl/oci-curl.sh

  Passons maintenant à quelques cas d'utilisations.  

Exemples d'utilisations

 

Exemple n°1 : Informations sur les bases Autonomous de notre compartiment

Pour récupérer ces informations, il nous faut préciser, en paramètres,  l'OCID de notre compartiment et le nom du endpoint correspondant au service Database de notre région. Ensuite, il suffit de lancer la fonction oci-curl avec ces éléments en utilisant la méthode GET :

# compartmentId="ocid1.compartment.oc1..aaaaaaaa7oeoutrnkcn5esfvnz6kuxr7ijqn7s3iz4q2ylp7ms23f5gvlckq"
# endpoint=database.eu-frankfurt-1.oraclecloud.com
# apiVersion=20160918
# oci-curl $endpoint get "/$apiVersion/autonomousDatabases?compartmentId=$compartmentId"

Les informations sur les bases autonomous du compartiment s'affichent (format JSON de sortie). Ce résultat n'est pas forcément bien visible :

[{"additionalDatabaseStatus":null,"autonomousContainerDatabaseId":null,"compartmentId":"ocid1.compartment.oc1..aaaaaaaa7oeoutrnkcn5esfvnz6kuxr7ijqn7s3iz4q2ylp7ms23f5gvlckq","connectionStrings":{"allConnectionStrings":{"HIGH":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_high.atp.oraclecloud.com","MEDIUM":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_medium.atp.oraclecloud.com","LOW":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_low.atp.oraclecloud.com","TPURGENT":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_tpurgent.atp.oraclecloud.com","TP":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_tp.atp.oraclecloud.com"},"dedicated":null,"high":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_high.atp.oraclecloud.com","low":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_low.atp.oraclecloud.com","medium":"adb.eu-frankfurt-1.oraclecloud.com:1522/icnmbjgz4momkrh_db201911051736_medium.atp.oraclecloud.com"},"connectionUrls":{"apexUrl":"https://ICNMBJGZ4MOMKRH-DB201911051736.adb.eu-frankfurt-1.oraclecloudapps.com/ords/apex","machineLearningUserManagementUrl":"https://adb.eu-frankfurt-1.oraclecloud.com/omlusers/tenants/OCID1.TENANCY.OC1..AAAAAAAAISZ6B4N6MV7JTHDIQG5OMUE2VWWXRJJUYDRE5QDVW2UKDBD22C6A/databases/DB201911051736/index.html","sqlDevWebUrl":"https://ICNMBJGZ4MOMKRH-DB201911051736.adb.eu-frankfurt-1.oraclecloudapps.com/ords/admin/_sdw/?nav=worksheet"},"cpuCoreCount":1,"currentLagTimeInSeconds":null,"dataSafeStatus":"NOT_REGISTERED","dataStorageSizeInTBs":1,"dbAvailabilityType":"HIGH_AVAILABILITY","dbName":"DB201911051736","dbVersion":"18c","dbWorkload":"OLTP","definedTags":{},"displayName":"DB_TEST01","freeformTags":{},"id":"ocid1.autonomousdatabase.oc1.eu-frankfurt-1.abtheljr5iyn6ia4rcjiwzv7mwrirwanxofw753zx4kqeftl4l72rbpgldta","isAutoScalingEnabled":false,"isDedicated":false,"isFailedOver":null,"isFreeTier":true,"isPreview":false,"isRefreshableClone":null,"lagTimeInSeconds":null,"licenseModel":"LICENSE_INCLUDED","lifecycleDetails":null,"lifecycleState":"AVAILABLE","nsgIds":null,"openMode":"READ_WRITE","privateEndpoint":null,"privateEndpointLabel":null,"serviceConsoleUrl":"https://adb.eu-frankfurt-1.oraclecloud.com/console/index.html?tenant_name=OCID1.TENANCY.OC1..AAAAAAAAISZ6B4N6MV7JTHDIQG5OMUE2VWWXRJJUYDRE5QDVW2UKDBD22C6A&database_name=DB201911051736&service_type=ATP","sqlWebDeveloperUrl":null,"standbyDb":null,"subnetId":null,"systemTags":{"orcl-cloud":{"free-tier-retained":"true"}},"timeCreated":"2019-11-05T16:40:00.055Z","timeDeletionOfFreeAutonomousDatabase":null,"timeMaintenanceBegin":"2020-02-08T07:00:00.000Z","timeMaintenanceEnd":"2020-02-08T12:00:00.000Z","timeReclamationOfFreeAutonomousDatabase":"2020-02-14T11:12:03.451Z","usedDataStorageSizeInTBs":1,"whitelistedIps":null}]

 

Exemple n°2 : Informations sur les bases Autonomous de notre compartiment avec intégration de l'outil jq

jq est un outil permettant de manipuler du JSON. Il est très utilisé pour ses fonctions de formatage, de filtrage et de manipulation de données JSON. Afin de faciliter l'utilisation des REST API, je vous propose de l'installer et de l'intégrer à nos exemples. jq est téléchargeable sur le lien suivant : https://stedolan.github.io/jq/download/ Installons le :

# sudo wget https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 -O /usr/bin/jq

# sudo chmod +x /usr/bin/jq

Testons ensuite notre première commande oci-curl en y ajoutant la gestion du JSON avec jq :

# oci-curl $endpoint get "/$apiVersion/autonomousDatabases?compartmentId=$compartmentId" | jq

 

Exemple n°3 : Informations sur l'état de la base de données

Ajustons le filtre jq pour afficher uniquement l'état de la base de données :

# oci-curl $endpoint get "/$apiVersion/autonomousDatabases?compartmentId=$compartmentId" | jq '.[].displayName.lifecycleState'
"AVAILABLE"

Nous pouvons également modifier le filtre jq pour afficher le nom de la base avec l'état associé :

# oci-curl $endpoint get "/$apiVersion/autonomousDatabases?compartmentId=$compartmentId" | jq '.[] | .displayName,.lifecycleState'
"DB_PRODUCTION"
"AVAILABLE"

 

Pour conclure

L'utilisation des REST API est assez simple à mettre en place et à utiliser au quotiden. Toutes les actions de l'interface graphique OCI (et voir plus) sont disponibles via ces REST API. Il est très facile d'intégrer différents types de commandes (arrêt/ démarrage / provisonning / modification de configuration) dans des scripts afin d'automatiser vos différents process.   Pour avancer plus sur le sujet, la documentaion de réfrence des syntaxes REST API est disponible sur ce lien : https://docs.cloud.oracle.com/fr-fr/iaas/Content/API/Concepts/apiref.htm