Arista eAPI ou EOS API

Dernière modification le 15 mars 2020

Arista EOS propose des interfaces programmables pour les applications. Ces interfaces peuvent être exploitées par des applications exécutées sur le commutateur ou externes à EOS. L’interface API EOS (eAPI) permet aux applications et aux scripts d’avoir un contrôle programmatique complet sur EOS, avec une syntaxe stable et facile à utiliser. Une fois l’API activée, le commutateur accepte les commandes utilisant la syntaxe CLI d’Arista et répond avec une sortie sérialisée en JSON et servie via HTTP.

Le client envoie une requête HTTP POST au serveur, en utilisant le protocole JSON-RPC 2.0. La requête spécifie :

• La méthode à utiliser (pour l’instant « runCmds »)
• Une liste de commande à executer, par exemple [‘show interfaces’] ou [‘configure’, ‘interface Ethernet 1’, ‘shutdown’]
• Un numéro de version, spécifiant à quelle révision du modèle de sortie le script doit s’attendre (pour l’instant, toujours « 1 »)

Le serveur traite la demande et collecte un modèle de données structuré, sérialisé en JSON, pour chaque commande. Si une commande renvoie une erreur, le champ JSON-RPC 2.0 « errors » sera correctement défini, sinon la réponse est placée dans le champ « result ».

localhost>enable
localhost#configure
localhost(config)#management api http-commands
localhost(config-mgmt-api-http-cmds)#no shutdown
localhost(config-mgmt-api-http-cmds)#end
localhost#write memory

Une fois configuré, le commutateur peut accepter les requêtes eAPI sur https (dans mon cas le port 4443 d’un cEOS-lab a été exposé) et il est possible d’accéder à l’interface explorer à l’adresse : https://127.0.0.1:4443/explorer.html. Après authentification, on peut, depuis cette interface, tester les requêtes eAPI et explorer les réponses JSON.

Une documentation supplémentaire sur les formats de réponse peut être consultée sur le commutateur à l’adresse https://127.0.0.1:4443/overview.html et https://127.0.0.1:4443/documentation.html.

Personnellement, je code en Python 3 depuis au moins deux ans, or, depuis janvier 2020, la branche 2.x de Python n’est plus supportée et les exemples eAPI off-box que l’on trouve dans certaines littératures ne sont plus utilisables du fait de l’obsolescence du module jsonrpclib qui n’est plus mis à jour depuis 5 ans et pour lequel le portage Python 3.x n’a pas été fait. J’indique, ici, une façon de contourner le problème en utilisant un fork supportant Python 3 et qui s’appelle jsonrpclib-pelix.

Même si je ne le décris pas ici, je code toujours en environnement virtuel Python.

pip install jsonrpclib-pelix

#!/usr/bin/env python
import ssl
ssl._create_default_https_context = ssl._create_unverified_context
import json
from jsonrpclib import Server

switch = Server( "https://admin:arista@127.0.0.1:4443/command-api" )
response = switch.runCmds( 1, [ "show version" ] )
print(json.dumps(response, indent=3))
print(response[0]['version'])

Il existe une librairie Python beaucoup plus populaire et supportée pour faire des requêtes HTTP, il s’agit de requests. Voici un petit exemple de code pour accéder à un switch virtuel Arista vEOS tournant dans EVE-NG. La variable data est construite à partir des informations récoltées dans la fenêtre « Request Viewer » de l’interface web « Simple eAPI request editor » du switch virtuel.

pip install requests

#!/usr/bin/env python
import requests
import json


requests.packages.urllib3.disable_warnings()

uri = 'https://192.168.1.209/command-api'
data={
  "jsonrpc": "2.0",
  "method": "runCmds",
  "params": {
    "format": "json",
    "timestamps": False,
    "autoComplete": False,
    "expandAliases": False,
    "includeErrorDetail": False,
    "cmds": [
      "show version"
    ],
    "version": 1
  },
  "id": "PythonScript-1"
}

s = requests.session()
s.auth = ('admin','arista')
s.verify = False
s.headers.update({'Content-Type' : 'application/json'})
r = s.request('post', uri, data=json.dumps(data))

print(json.dumps(r.json(), indent=3))

De façon beaucoup plus simple et pérenne, il convient plutôt d’utiliser le client eAPI pour python : pyeapi maintenu par Arista, qui supporte Python 3 et qui permet de coder plus sereinement. La librairie pyeapi fournit à la fois un client pour envoyer et recevoir des commandes via eAPI, ainsi qu’une API pour travailler directement avec les ressources EOS. L’API est conçue pour être facile et directe à utiliser tout en étant également extensible. Une version pour le langage Golang est également disponible : goeapi.

Il y a deux méthodes principales à distinguer. La méthode connect() reçoit les informations de connexions nécessaires et retourne un objet EapiConnection (il est possible de retourner un objet Node si return_node=True). La méthode connect_to() prend les informations de connexion dans un fichier de configuration et retourne un objet Node. Le fichier de configuration peut se situer dans le fichier ~/.eapi.conf ou /mnt/flash/eapi.conf, indiqué par la variable EAPI_CONF ou chargé par la méthode load_config().

pip install pyeapi

[connection:ceos1]
host: 127.0.0.1
port: 4443

[DEFAULT]
username: admin
password: arista
transport: https

#!/usr/bin/env python
import pyeapi
from pprint import pprint as pprint

pyeapi.load_config('eapi.conf')

try:
    node = pyeapi.connect_to('ceos1')
    version = node.enable('show version')
    pprint(version)
    print(version[0]['result']['version'])
except AttributeError:
    print("Host not found in eapi.conf")

Il est également facile d’entrer en configuration sur le switch cEOS-lab. Voici un exemple de manipulation de l’API vlans.

#!/usr/bin/env python
import pyeapi

pyeapi.load_config('eapi.conf')

try:
    node = pyeapi.connect_to('ceos1')
    vlans = node.api('vlans')
    vlans.autorefresh = True
    if vlans.get(10):
        print('Vlan 10 already exists, deleting it')
        vlans.delete(10)
    print('\nCreating Vlan 10')
    vlans.create(10)
    print('Setting Vlan 10 name to "test10"')
    vlans.set_name(10, 'test10')
    print('\nDisplaying all vlans on the node')
    print(('-' * 32))
    for vlan in list(vlans.values()):
        print(("   Vlan Id: {vlan_id}, Name: {name}".format(**vlan)))
except AttributeError:
    print("Host not found in eapi.conf")

Les modules pyeapi disponibles en version 0.8.3 sont les suivants :

• Client
  • Client
  • Eapilib
  • Utils
• Api
  • Abstract
  • Acl
  • Bgp
  • Interfaces
  • Ipinterfaces
  • Mlag
  • Ntp
  • Ospf
  • Routemaps
  • Spanningtree
  • Staticroute
  • Stp
  • Switchports
  • System
  • Users
  • Varp
  • Vlans
  • Vrfs
  • Vrrp

La documentation pour pyeapi est disponible en ligne.