RESTCONF: Una guía práctica de uso

---

Herramientas Utilizadas

Para trabajar con RESTCONF, mis herramientas de trabajo son:

• Postman, para realizar peticiones a los equipos sin tener que escribir scripts.
• Python3.6 con la librería “requests”.
• Pyang, para explorar los modelos de YANG
• Un editor de código, Visual Studio Code por ejemplo.
• Un laboratorio con al menos un equipo con IOS-XE. Se puede utilizar los CSRv disponibles en DevNet con este fin.

---

RESTCONF

Esta guía no pretende indagar en detalle los conceptos de RESTCONF ni de los modelos de datos de YANG. Esta información está disponible en los módulos de DevNet: https://developer.cisco.com/learning/tracks/iosxe-programmability

Sin embargo, sí se quiere remarcar algunos conceptos:

• RESTCONF usa HTTPS como transporte. Esto significa que implementa los métodos GET, POST, PUT, DELETE …
• Los modelos de datos están escritos en YANG. Los datos que recibimos en las peticiones están en formato JSON.
• Existen dos tipos de modelos de datos: abiertos (IEEE, IETF) y nativos (de Cisco, o cualquier otro fabricante).

Para usar RESTCONF, una vez está habilitado en el equipo, debemos en primer lugar armar la URI en la cual se encuentra el recurso al que queremos acceder. Esta URI variará dependiendo del modelo de datos a utilizar. Siempre sigue la siguiente estructura:

https://<IP:Puerto>/<root>/data/<modulo:container>/<leaf>?<opciones>

Donde:

• <IP:Puerto> es la IP del equipo y el puerto donde atiende el servicio de RESTCONF (por defecto, el 443.
• <root> es la raíz de la URI, la misma para todos los recursos.
• <modulo:container> y <leaf> son los elementos dentro del modelo de datos a los que se está haciendo referencia.
• <opciones> son filtros opcionales.

Una vez construida la URI, se realiza una petición con alguno de los métodos disponibles dependiendo de qué se desee realizar. Los métodos implementados en IOS-XE son los siguientes:

El foco de esta guía es cómo conseguir armar la URI, y qué métodos usar, para replicar comandos de CLI ya conocidos. En particular, cómo conseguir los valores de <root>, <modulo:container> y <leaf>.

---

Construcción de la URI

Como ya se dijo brevemente en el apartado anterior la URI se arma fundamentalmente a partir del modelo de YANG a utilizar. El problema es que de ambos tipos (abiertos y nativos) se encuentran disponibles una gran cantidad, y su lectura no es precisamente amigable. Tampoco se encuentran ordenados de forma que alguien sin experiencia en el manejo de estos modelos se pueda mover con facilidad. A modo de referencia:

• Modelos abiertos: https://github.com/YangModels/yang/tree/master/standard
• Modelos nativos (de Cisco, por ejemplo, ordenados por sistema operativo y por versión): https://github.com/YangModels/yang/tree/master/vendor/cisco

Además, cuando uno piensa en automatizar cierta tarea sobre los equipos, en base a la experiencia previa y la documentación disponible, es muy probable que tenga la información para hacerlo vía CLI. Por lo tanto, una de las formas más fáciles de acercarse a estas nuevas interfaces es “convirtiendo” instrucciones de IOS en datos y peticiones vía RESTCONF.

Obtención de la raíz

La RFC 8040 define una URI especifica para obtener este dato. La misma es:

GET https://<direccion:puerto>/.well-known/host-meta

El valor que necesitamos es “restconf”, contenido en el atributo “href” de la etiqueta “Link”.

Obtención de módulo y container

La forma más fácil de explicar el proceso que se siguió es mediante un ejemplo. Lo que se va a buscar automatizar es la configuración de un spoke en una topología Hub & Spoke de FlexVPN. Si quisiéramos hacerlo vía CLI, los comandos básicos para lograr al menos que se levante el túnel podrían ser los siguientes:

Viendo la configuración vemos que hay seis bloques: keyring, IKEv2 auth policy, IKEv2 profile, IPSec profile, interfaz Loopback e interfaz Tunnel. Este es el primer primer paso para encontrar la equivalencia: dividir los elementos de la configuración deseada. Cada elemento será una transacción vía RESTCONF.
Ahora, lo primero que necesitamos para ir armando la URI es el modelo de YANG a utilizar. Cisco provee un modelo específico, llamado “native” (Cisco-IOS-XE-native.yang), con la que accedemos a prácticamente toda la configuración del equipo en cuestión. El modelo, para IOS-XE 16.9.3 por ejemplo, comienza con las siguientes líneas:

Con esto tenemos el nombre del módulo: “Cisco-IOS-XE-native”. Ahora necesitaríamos saber con qué containers dentro del mismo trabajar para realizar las configuraciones requeridas. Si analizamos el archivo con la herramienta Pyang vemos lo siguiente:

Lo que se observa es que todo el árbol depende de un container que también se llama “native”. Este es el nombre del container que necesitamos.
Recapitulando, la URI que se armó hasta ahora es la siguiente:

https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-native:native

Esta URI ya puede ser usada para traer toda la información del contenedor (equivalente a toda la configuración del equipo). En una operación de lectura podríamos luego filtrar la respuesta, pero para crear/editar configuraciones necesitamos la ruta específica al recurso. Por lo tanto, sólo nos queda encontrar la ruta hacia el recurso deseado.

Obtención del resto de la URI

Es aquí donde cambiamos la forma de trabajo con respecto a RESTCONF.
Idealmente vamos a necesitar un dispositivo con IOS-XE y una configuración de fábrica para detectar exactamente qué líneas de CLI modifican qué contenedores dentro del modelo. Para esto, un CSR1000v es la manera más cómoda de realizar las pruebas. En DevNet Sandbox, podemos reservar un laboratorio para realizar exactamente estas pruebas: “IOS XE on CSR Recommended Code”.
Con la ayuda de Postman podemos realizar las peticiones para encontrar la ruta. En la configuración que trae el CSRv de DevNet, si no hacemos ninguna modificación y se ejecuta un GET a la URI armada previamente se obtiene el siguiente resultado:

Nota: por brevedad, se filtró el resultado de la llamada a sólo el primer nivel dentro de la estructura de datos. Esto se puede hacer usando “opciones” dentro de la URI. La opción “depth” nos entrega el resultado mostrado. La URI completa sería:

GET https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-native:native?depth=1

Podemos ver todos los contenedores dentro del módulo “native”. En este caso sabemos que al ejecutar comandos por CLI van a cambiar los contenedores “interface” y “crypto”, pero en caso de no estar seguro se puede ejecutar la llamada sin ningún filtro e ir comparando los cambios en todos los contenedores.
Para ver cambios, debemos ingresar vía CLI al router e introducir un primer bloque de configuración. Comenzaremos por el Keyring. Se carga la siguiente configuración en el router:

Nota: No es necesario guardar la configuración, las llamadas en RESTCONF son sobre la running-config.

Una vez cargada la configuración volvemos a hacer la petición vía RESTCONF (GET) y vemos los siguientes cambios dentro de crypto:

https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-native:native

La respuesta refleja la configuración agregada. A partir de esta respuesta podemos completar la URI que sería necesaria para realizar esta configuración vía RESTCONF:

• El primer punto es qué método se necesita para la configuración: como se quiere crear un Keyring, el método adecuado es POST.
• Completar la URI leyendo el árbol de la respuesta: vemos que el keyring se define dentro de “crypto” -> “ikev2” (se puede omitir el nombre del módulo, antes de los “:”).
• Definir el cuerpo del mensaje: Dentro del cuerpo de la petición vamos a tener que indicar qué parámetros queremos darle al keyring a crear. Se compone de todos los datos dentro de la ruta definida. En este caso es todo el campo “keyring”.

Para resumir, a continuación se muestra la URI completa y el cuerpo del mensaje:

POST https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-native:native/crypto/ikev2

Construida la petición, se puede enviar al equipo para probar que funcione correctamente. La respuesta nos indicará el resultado mediante su “status code”. Algunos códigos comunes son:

Código	Descripción Humana
201	Creado OK, respuesta correcta frente a un POST.
204	Modificado OK, respuesta correcta frente a un PUT
400	Error en la petición, suele ocurrir frente a URIs mal armadas o con campos incorrectos en el cuerpo del mensaje.
401	Error en las credenciales.
404	No se encuentra el recurso. Posible problema en la URI
409	Conflicto en la creación. En un POST, significa que ya existe el recurso (se debería modificar con PUT).

Si la petición no devuelve un resultado correcto, entonces mediante prueba y error debemos buscar arreglar la URI o el contenido del cuerpo.

En una segunda parte, los campos restantes de la configuración.

---

Modificación de las configuraciones

Cuando lo que se desea es modificar algún parámetro de la configuración, por ejemplo una interfaz, cambia el tipo de solicitud que hay que realizar. Las modificaciones se realizan con la petición PUT, y es necesario generalmente modificar la URI para identificar el recurso específico a modificar.
¿Cómo se identifica este recurso? Podemos identificar un elemento específico dentro de una lista de la siguiente forma: tomemos como ejemplo el keyring creado en la guía, si quisiéramos ahora modificar este llavero lo identificamos mediante su key “name”, es decir “Flex_key”. La URI es la siguiente:

PUT https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-native:native/crypto/ikev2/keyring=Flex_key

Hay que tener en cuenta que el contenido de este keyring será reemplazado completamente por el del cuerpo de la petición. Esto quiere decir que los campos que no se envíen dentro del cuerpo y que existiesen previamente en la configuración van a eliminarse. Por lo tanto, siempre es recomendable realizar una petición GET a la misma URI y sobre la respuesta agregar/modificar/eliminar los campos deseados.
Si la modificación se realizó con éxito, la respuesta tendrá el código 204.