Distribuire un'applicazione IOx utilizzando IOxClient

Introduzione

Questo documento descrive la distribuzione di un'applicazione mediante ioxclient.

Obiettivo

Questo documento è dedicato alla comprensione della distribuzione di un'applicazione utilizzando ioxclient.

L'obiettivo di questo documento è assolutamente pratico, quindi se desiderate maggiori dettagli tecnici, vi consiglio di rivedere la documentazione condivisa.

Prerequisiti

• Conoscenze base dei sistemi operativi Cisco IOS XE e Cisco IOS.
• Conoscenza approfondita del ciclo di vita del Docker e del contenitore.
• Operazioni Linux di base.

Requisiti

Se il dispositivo supporta iox, verificare la matrice di compatibilità: matrice di supporto della piattaforma

Inoltre, si prega di scaricare il client iox secondo le specifiche del PC: Download

Componenti usati

Le informazioni fornite in questo documento si basano sulle seguenti versioni software e hardware:

• ioxclient versione 1.17.0.0
• Router C800v, versione 17.12.3a
• Computer Ubuntu versione 20.04
• Installare Docker Engine versione 24.0.9 o precedente.

Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.

Panoramica

Che cos'è IOx?

IOx è l'ambiente applicativo per i dispositivi Cisco, questa funzionalità ci consente di assemblare le applicazioni in un formato compatibile con IOx, utilizzando strumenti come ioxclient.

Cos'è ioxclient?

ioxclient è uno strumento da riga di comando che fa parte di Cisco IOx SDK. Viene utilizzato per sviluppare, testare e distribuire applicazioni IOx su dispositivi Cisco IOx.

Definire l'applicazione

Questo codice di esempio crea un server HTTP di base in ascolto tramite la porta 8000; Funge da funzionalità di base dell'immagine Docker (Dockerfile).

Nota: Un Dockerfile è necessario solo per lo sviluppo di immagini personalizzate con funzionalità specifiche. È possibile estrarre un'applicazione da un repository contenitore, esportarla e utilizzarla come base per ioxclient.

Applicazione Python

import http.server
import socketserver

PORT = 8000
Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print(f"Serving at port {PORT}")
    httpd.serve_forever()

Definire il file Docker

FROM python:alpine3.20
WORKDIR /apps
COPY . .
EXPOSE 8000
ENTRYPOINT [ "python" ]
CMD [ "main.py" ]

Con questo codice si imposta un server http in ascolto attraverso la porta 8000 e si raccoglie l'applicazione in un file Docker.

Pacchetto

È necessario creare e popolare un file package.YAML con metadati e definizioni di risorse per una corretta distribuzione dell'applicazione.

Il file YAML è un formato, questo formato è attraente a causa della sintassi semplice, all'interno del file possiamo specificare aspetti dell'applicazione come variabili ambientali, porte, dipendenze e così via.

Esempio YAML dal repository dei modelli Cisco DevNet IOx

descriptor-schema-version: "2.2"

info:
  name: iox_docker_python
  description: "IOx Docker Python Sample Application"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"

app:
  cpuarch: "x86_64"
  type: docker
  resources:
    profile: c1.small

  # Specify runtime and startup
  startup:
    rootfs: rootfs.tar
    target: ["python3 main.py"]

Consultare la documentazione per consultare i valori validi nel file del pacchetto:

• Documentazione del dispositivo: descrittore pacchetto IOx
• Repository Github:  Cisco DevNet/iox-app-template

Per questo documento, il file di configurazione YAML contiene le seguenti informazioni:

descriptor-schema-version: "2.2"

info:
  name: "tac_app"
  description: "tac_app"
  version: "1.0"
  author-name: "TAC-TEST"

app:
  cpuarch: x86_64
  type: docker
  resources:
    profile: "custom"
    cpu: 100                # CPU en MHz assigned to the application.
    disk: 50               # Storage in MB for the disk
    memory: 128           # Memory en MB assigned to the application.
    network:
      -
        interface-name: eth0
        ports:
          tcp:
            - 8000
  startup:
    rootfs: "rootfs.tar"         # Container file system
    target: "python main.py"     # Command to start the application

A causa di un'incompatibilità tra Docker Engine versione 25.0 e ioxclient, si consiglia di utilizzare una distribuzione Linux che supporti Docker Engine versione 24.0.9 o precedente, poiché la versione 24.0.9 è la più recente versione supportata per la compatibilità con ioxclient.

In questo esempio, l'immagine Docker utilizzata per dimostrare la funzionalità del client IOx è stata creata su una macchina virtuale basata su Ubuntu che esegue la versione 20.04, scelta in modo specifico perché i file binari .deb di Docker Engine sono disponibili per questa distribuzione/versione.

Nota: L'unico modo per installare le versioni precedenti di Docker consiste nell'installarle tramite i file bin. Questi file binari sono versioni specifiche del software già predisposte per l'esecuzione diretta su un particolare sistema operativo.

Configurazione

Per preparare la VM con le specifiche indicate, procedere con l'installazione del file binario da una versione precedente di Docker:

wget https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/docker-ce-cli_24.0.9-1~ubuntu.20.04~focal_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/docker-ce_24.0.9-1~ubuntu.20.04~focal_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/docker-buildx-plugin_0.11.2-1~ubuntu.20.04~focal_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/docker-compose-plugin_2.21.0-1~ubuntu.20.04~focal_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/containerd.io_1.7.19-1_amd64.deb

And installed them:
sudo dpkg -i ./containerd.io_1.7.19-1_amd64.deb \
./docker-ce_24.0.9-1~ubuntu.20.04~focal_amd64.deb \
./docker-ce-cli_24.0.9-1~ubuntu.20.04~focal_amd64.deb \
./docker-buildx-plugin_0.11.2-1~ubuntu.20.04~focal_amd64.deb \
./docker-compose-plugin_2.21.0-1~ubuntu.20.04~focal_amd64.deb

Una volta installati tutti i file, il computer è pronto per creare il pacchetto dell'applicazione iox.

Procedura di imballaggio

Trasferire il codice Python e il file Docker nella macchina virtuale, verificare che entrambi i file si trovino nella stessa directory, quindi procedere con la creazione dell'immagine Docker:

sudo docker build -t tac_app .

Per elencare le immagini Docker disponibili nel repository del computer locale, eseguire il comando riportato di seguito:

ubuntu@ip-172-31-30-249:~$ sudo docker images

REPOSITORY    TAG       IMAGE ID       CREATED          SIZE
tac_app       latest    94a1c2ba4b08   19 seconds ago   1.78GB

Da qui ci sono 2 alternative 

1 - Creare il pacchetto dell'applicazione utilizzando l'immagine Docker e il file descrittore package.yaml

2 - Esportare l'immagine come file system radice e comprimerla con il file descrittore YAML

Opzione 1 - Creazione del package dell'immagine Docker e del file YAML:

Spostarsi nella directory di destinazione in cui si desidera collocare l'immagine e il file YAML.

ubuntu@ip-172-31-30-249:~/tes0$ ls
package.yaml

Creare quindi il pacchetto del file eseguendo questo comando:

ioxclient docker package tac_app package.yaml
...

Example:
ubuntu@ip-172-31-30-249:~/tese$ sudo /home/ubuntu/ioxclient_1.17.0.0_linux_amd64/ioxclient docker package tac_app package.yaml 
Currently active profile: default
Secure client authentication: no
Command Name: docker-package
Timestamp at DockerPackage start: 1748211382584
Using the package descriptor file in the project dir
Validating descriptor file package.yaml with package schema definitions
Parsing descriptor file..
Found schema version 2.7
Loading schema file for version 2.7
Validating package descriptor file..
File package.yaml is valid under schema version 2.7
Generating 10x package of type docker with layers as rootfs
Replacing symbolically linked layers in docker rootfs, if any
No symbolically linked layers found in rootfs. No changes made in rootfs 
Removing emulation layers in docker rootfs, if any
The docker image is better left in it's pristine state
Updated package metadata file :/home/ubuntu/tes0/.package.metadata
No rsa key and/or certificate files provided to sign the package
-------------------------------------------------------------------
Generating the envelope package
-------------------------------------------------------------------
Checking if package descriptor file is present..
Skipping descriptor schema validation..
Created Staging directory at : /tmp/1093485025
Copying contents to staging directory
Timestamp before CopyTree: 1748211503878
Timestamp after CopyTree: 1748211575671
Creating artifacts manifest file
Creating an inner envelope for application artifacts
Including rootfs.tar
Generated /tmp/1093485025/artifacts.tar.gz
Parsing Package Metadata file /tmp/1093485025/.package.metadata 
Updated package metadata file /tmp/1093485025/.package.metadata 
Calculating SHA256 checksum for package contents..
Timestamp before SHA256: 1748211630718
Timestamp after SHA256: 1748211630718
Path:.package.metadata
SHA256: 50c922f103ddc01a5dc7a98d6cacefb167f4a2c692dfc521231bb42f0c3dcf55 Timestamp before SHA256: 1748211630719
Timestamp after SHA256: 1748211630719
Path: artifacts.mf
SHA256: 511008aa2d1418daf1770768fb79c90f16814ff7789d03beb4f4ea1bf4fae8f2 Timestamp before SHA256: 1748211630719
Timestamp after SHA256: 1748211634941
Path: artifacts.tar.gz
SHA256: 0cc3f69af50cf0a01ec9a1400c440f60a0dff55369bd309b6dfc69715302425+ Timestamp before SHA256: 1748211634941
Timestamp after SHA256: 1748211634952
Path: envelope_package.tar.gz
SHA256: d492de09441a241f879cd268cd1b3424ee79a58a9495aa77ae5b11cab2fd55da Timestamp before SHA256: 1748211634953
Timestamp after SHA256: 1748211634963
Path: package.yaml
SHA256: d8dc7253443ff3ad080c42bc8d82db4c3ea7ae9b2d0e2f827fbaf2bc80245f62 Generated package manifest at package.mf
Generating IOx Package..
Package docker image tac_app at /home/ubuntu/tes0/package.tar
ubuntu@ip-172-31-30-249:~/tes0$ |

Questo insieme di azioni è stato responsabile della generazione del pacchetto tar. Per esaminare il contenuto del pacchetto, è possibile decomprimerlo utilizzando l'utilità tar

ubuntu@ip-172-31-30-249:~/tes0$ tar -tf package.tar
package.yaml
artifacts.mf
.package.metadata
package.mf
envelope_package.tar.gz
artifacts.tar.gz

Opzione 2 - Esportazione dell'immagine Docker come file system radice e relativo pacchetto con il file YAML descrittore.

Eseguire il comando nella directory in cui deve essere creata l'immagine:

ubuntu@ip-172-31-30-249:~/tac_app$ sudo docker save tac_app -o rootfs.tar

Questo comando esporta l'immagine Docker come un bundle contenente il file system radice che si installa su / all'interno del contenitore.

Spostare il file package.YAML nella posizione specificata. Al termine, la struttura della directory deve essere simile a quella mostrata di seguito:

ubuntu@ip-172-31-30-249:~/tac_app$ ls 
package.yaml   rootfs.tar

Il passaggio finale prevede il packaging dell'immagine Docker mediante l'esecuzione di questo comando:

ioxclient docker package tac_app package.yaml
...

ubuntu@ip-172-31-30-249:~/tac_app$ ioxclient package .
Currently active profile :  default
Secure client authentication:  no
Command Name:  package
No rsa key and/or certificate files provided to sign the package
Checking if package descriptor file is present..
Validating descriptor file /home/ubuntu/tac_app/package.yaml with package schema definitions
Parsing descriptor file..
Found schema version  2.7
Loading schema file for version  2.7
Validating package descriptor file..
File /home/ubuntu/tac_app/package.yaml is valid under schema version 2.7
Created Staging directory at :  /tmp/2119895371
Copying contents to staging directory
Timestamp before CopyTree: 1748374177879


Timestamp after CopyTree: 1748374357306
Creating artifacts manifest file
Creating an inner envelope for application artifacts

Generated  /tmp/2119895371/artifacts.tar.gz
Updated package metadata file :  /tmp/2119895371/.package.metadata
Calculating SHA256 checksum for package contents..
Timestamp before SHA256: 1748374566796
Timestamp after SHA256: 1748374566796
Path:  .package.metadata
SHA256 : 4fad07c3ac4d817db17bacc8563b4c632bc408d2a9cbdcb5e7a526c1c5c6e04e
Timestamp before SHA256: 1748374566796
Timestamp after SHA256: 1748374566809
Path:  artifacts.mf
SHA256 : d448a678ae952f9fe74dc19172aba17e283a5e268aca817fefc78b585f02b492
Timestamp before SHA256: 1748374566809
Timestamp after SHA256: 1748374575477
Path:  artifacts.tar.gz
SHA256 : 64d70f43be692e3cee61d906036efef45ba29e945437237e1870628ce64d5147
Timestamp before SHA256: 1748374575477
Timestamp after SHA256: 1748374575489
Path:  package.yaml
SHA256 : d8dc7253443ff3ad080c42bc8d82db4c3ea7ae9b2d0e2f827fbaf2bc80245f62
Generated package manifest at  package.mf
Generating IOx Package..
Package generated at /home/ubuntu/tac_app/package.tar

A seguito di queste azioni, il file package.tar viene generato e preparato per la distribuzione. Per esaminare il contenuto del pacchetto, eseguire il comando riportato di seguito:

ubuntu@ip-172-31-30-249:~/tac_app$ tar -tf  tac_app.tar
package.yaml
artifacts.mf
.package.metadata
package.mf
artifacts.tar.gz

Installazione 

Dopo aver preparato l'applicazione, il passaggio finale consiste nell'installarla sul dispositivo di destinazione eseguendo il comando in modalità di esecuzione privilegiata, come mostrato:

 app-hosting install appid tacapp package bootflash:package.tar

Attendere circa 1 minuto e verificare se l'applicazione è in esecuzione correttamente:

Router# show app-hosting list
App id                                   State
---------------------------------------------------------
  tacapp                               RUNNING