Le monde de l’automatisation a profondément changé et évolué ces dernières années. Alors qu’il fallait avoir auparavant une connaissance approfondie des modèles objets et des langages de programmation, l’émergence de nouveaux outils a simplifié aujourd’hui l’interaction avec les APIs. La maturité des API REST, les langages modernes et leurs librairies, les repositories publics et les communautés en ligne ont permis de simplifier la prise en main de l’automatisation d’infrastructure. Il est désormais possible de faire de grandes choses en quelques lignes de code.
Ce premier billet a pour but d’introduire l’API d’Intersight et son principe de fonctionnement. Les prochains billets permettront de rentrer plus en détail sur les différentes façons d’utiliser cette API via les SDK, Ansible et Terraform.
L’API REST d’Intersight
Intersight propose une API RESTful capable de piloter l’ensemble du computing Cisco (UCS et HyperFlex) connecté à Intersight. Le périmètre fonctionnel d’Intersight étant très large, l’API permet également d’interagir avec les différents modules d’Intersight : par exemple, avec les environnements de virtualisation et baies de stockage connectés, l’orchestrateur de tâches et workflows (Intersight Cloud Orchestrator), ou les clusters Kubernetes (Intersight Kubernetes Services). Ce billet décrit les différents modules d’Intersight.
L’API permet d’accéder à l’entièreté des ressources d’Intersight. En interagissant directement avec l’API, il est possible de réaliser toutes les opérations que l’on ferait à la main sur l’interface web. D’ailleurs, chaque opération faite sur l’interface est une requête à l’API REST dans le backend.
L’API d’Intersight permet de réaliser :
- Des requêtes en lecture seule (GET) permettant par exemple de générer un inventaire : liste des serveurs, liste des alarmes, etc.
- Des requêtes pour configurer (POST), modifier (PATCH) ou supprimer (DELETE) des ressources : création de policies, création de server profiles et association avec les serveurs physiques, etc.
L’API d’Intersight repose sur des standards modernes. Elle est basée sur la spécification OpenAPI qui est un format de définition permettant de décrire, consommer et visualiser les API RESTful.
Quels sont les bénéfices de l’API d’Intersight ?
L’API possède de nombreux bénéfices dont les trois principaux sont:
- L’API est une unique interface pour toute infrastructure Datacenter pilotée par Intersight et permet d’accélérer les configurations. La réutilisation des requêtes et scripts permet de minimiser le risque d’erreur en apportant une cohérence globale dans les configurations.
- Le support d’OpenAPI permet aux utilisateurs d’accéder à une API REST intuitive et facile à prendre en main : les capacités de l’API étant entièrement documentées, la construction des requêtes est simplifiée.
- La communauté DevNet est très active et propose de nombreux tutoriels, sandboxes, ou exemples de code permettant de commencer à travailler avec l’API.
Le modèle objet d’Intersight
Les ressources d’Intersight regroupent tous les objets adressables par l’API. Elles peuvent pointer vers des objets physiques : les serveurs, les fabric interconnects, leurs composants, etc. Mais elles peuvent également désigner des objets logiques : server profile, policies, alarmes, etc.
Toutes ces ressources font partie d’un modèle objet appelé Intersight Management Information Model. Chaque ressource du modèle, que l’on appelle un Managed Object, possède un identifiant unique : le Managed Object Identifier (Moid). Le Moid est assigné à l’objet lorsqu’il est créé, par exemple à la suite d’une requête POST. Chaque objet est une instance d’une classe / collection plus générale.
Prenons l’exemple des policies NTP (qui spécifient les serveurs NTP à utiliser dans les profils de serveur). Une policy NTP est une instance de la classe ntp.Policies. Lorsqu’une policy NTP est créée (via l’interface web ou une requête POST à l’API), un Moid lui est assigné. C’est une suite unique de caractères comme « 61d6c61b6275722d3188ab59 » permettant de désigner cet objet. En empruntant la terminologie des bases de données, on parle de primary key.
Alors, comment identifier facilement le Moid d’un objet dans Intersight ? Deux méthodes sont disponibles :
- En naviguant dans l’interface jusqu’à l’objet, on peut identifier le Moid dans l’URL :
- En naviguant dans le Model Browser :
Construction de requêtes à l’API
Chaque Managed Object possède une URI qui est l’adresse à laquelle on peut accéder à l’objet via l’API. Cette URI est unique car elle inclut le Moid et elle peut être utilisée pour les requêtes HTTP.
En reprenant l’exemple précédent de policy NTP, l’URI de l’objet est :
https://intersight.com/api/v1/ntp/Policies/61d6c61b6275722d3188ab59
L’URI comprend :
- Le schéma d’URL https.
- Le lien vers le service Intersight : intersight.com pour la version SaaS ou le nom de l’appliance résolvable en DNS.
- La version de l’API : /api/v1.
- Le path vers le Moid. Généralement le path vers un Managed Object inclut le lien vers la classe générale (/ntp/Policies) suivi du Moid (/61d6c61b6275722d3188ab59).
Il est également possible de faire une requête GET à la classe entière : https://intersight.com/api/v1/ntp/Policies. La réponse présenterait la liste de toutes les instances de la classe, c’est-à-dire ici, de toutes les policies NTP.
Nous reviendrons à la fin de ce billet sur des exemples de requêtes.
L’API Explorer de Intersight
Bien qu’il soit possible de communiquer directement avec l’API en utilisant votre outil favori (CLI via des requêtes CURL, Postman, etc), Intersight propose nativement un client REST API permettant d’exécuter et tester toutes les requêtes.
On y retrouve trois sections :
- Référence de toutes les requêtes disponibles
La section de gauche présente toutes les ressources accessibles via leur URI, ainsi que les requêtes et méthodes supportées. Certaines ressources supportent uniquement des requêtes GET (en lecture seule) pour générer un inventaire, alors que d’autres supportent les méthodes POST, PATCH ou DELETE pour modifier la ressource. Quelle que soit la méthode utilisée, l’URI de destination ne change pas et c’est ce qui fait la simplicité des API REST.
Par exemple, si on souhaite générer un inventaire de toutes les policies NTP : on utilise un GET à ntp/Policies. Si on souhaite créer une policy NTP, on utilise un POST à ntp/Policies avec le body adéquat.
- Paramètres et Response Model
La section du milieu de la page présente :
- Les paramètres de query qui spécifient les paramètres supportés pour le filtrage et l’organisation des réponses. Si on souhaite générer un inventaire avec des caractéristiques particulières – par exemple, pour générer un inventaire composé uniquement des serveurs de modèle B200 M6 – on ajoute les paramètres de filtrage adéquats dans la requête GET. Les paramètres de query supportés par Intersight sont nombreux : $filter, $orderby, $select, etc. Nous détaillerons un exemple dans le paragraphe suivant.
- Le request model qui détaille comment construire son body / payload (i.e. les données qu’on envoie à l’API) pour des méthodes POST ou PATCH.
- Le response model qui spécifie le format de la réponse attendue avec tous les attributs de l’objet, leur type (string, integer, etc) et leur hiérarchie.
- Client REST
La section de droite permet d’exécuter les requêtes et de voir la réponse de l’API. On peut y ajouter des paramètres de query. Le client REST permet de tester rapidement et directement les différentes requêtes afin d’avoir une idée plus précise des objets et de leurs attributs.
De la théorie à la pratique
Exemple d’inventaire avec l’API
Utilisons le client REST pour générer un inventaire des serveurs présents dans un parc. En utilisant une requête à la classe compute.PhysicalSummary et une méthode GET, l’API répond avec une liste de TOUS les serveurs connectés au compte Intersight.
L’URI de destination est :
https://intersight.com/api/v1/compute/PhysicalSummaries
Le body de la réponse détaille l’ensemble des attributs d’un objet serveur. Ces attributs sont par exemple le nom du serveur (Name), le modèle (Model) ou le nombre de cœurs par CPU du serveur (NumCpuCores).
Imaginons que nous souhaitons maintenant affiner la réponse et obtenir uniquement les serveurs qui possèdent des CPU dont le nombre de cœurs physiques est supérieur ou égal à 16. Pour cela nous pouvons ajouter des paramètres de query. Nous utilisons ici le paramètre de filtrage : $filter associé à l’opérateur « supérieur ou égal » qui s’écrit « ge » (pour Greater Than Or Equal).
L’URI de destination est maintenant :
https://intersight.com/api/v1/compute/PhysicalSummaries?$filter=NumCpuCores ge 16
Enfin, si nous souhaitons compter ce nombre de serveurs, nous pouvons utiliser directement le paramètre de query $count qui compte le nombre d’instances dans la réponse : ici 10 serveurs possèdent des CPU dont le nombre de cœurs physiques est supérieur ou égal à 16.
L’URI de destination est dans ce cas :
https://intersight.com/api/v1/compute/PhysicalSummaries?$filter=NumCpuCores ge 16&$count=True
Il est possible de créer des requêtes beaucoup plus poussées dans les opérations de filtrage, de sélection, ou de tri. Tout est très bien détaillé dans la documentation de la syntaxe des requêtes.
Exemple de création de ressource avec l’API
Revenons à notre exemple de policy NTP. Utilisons maintenant le client REST pour créer une nouvelle policy NTP.
Comme expliqué précédemment, l’URI utilisé est https://intersight.com/api/v1/ntp/Policies. Pour créer une ressource, nous pouvons utiliser une méthode POST à l’URI ci-dessus avec le body contenant les paramètres de configuration. Le body est écrit au format JSON et comprend ici le nom de la policy, sa description, une liste de serveurs NTP à utiliser, et le timezone.
Comment construire son body ? Le Request Model apporte une aide précieuse pour construire le payload des requêtes POST car il détaille tous les attributs de l’objet et leur type. Une deuxième méthode est d’utiliser le Developer Tool de votre navigateur web. Cet outil permet de regarder le contenu des requêtes lorsque l’on crée un objet à la main via l’interface graphique. On peut alors directement copier-coller ce payload et le réutiliser pour de prochaines requêtes.
Après exécution, le status code 200 confirme le succès de la requête et la création de l’objet. Nous voyons dans la réponse en première ligne le Moid de l’objet nouvellement créé.
En naviguant sur l’interface, nous pouvons confirmer que l’objet a été créé. L’URL montre bien le même Moid.
Si nous souhaitons lire l’objet, nous pourrions maintenant faire une requête GET à l’URI https://intersight.com/api/v1/ntp/Policies/{Moid} avec le Moid de l’objet en question.
Un dernier point
Puisque l’API d’Intersight est basée sur OpenAPI, celle-ci est entièrement documentée dans un format JSON ou YAML. Ces documents sont téléchargeables ici. Ils peuvent alors être directement importés dans des outils comme Postman afin d’avoir accès directement à toutes les requêtes possibles et leurs paramètres associés.
La documentation complète de l’API est accessible ici.
Dans les prochains billets de cette série, nous détaillerons les différentes façons d’utiliser cette API via les SDK, Ansible et Terraform.
Authors