Solved: Re: XR NOTES: Implementing TPA using appmgr in eXR

adelaluz · ‎11-19-2023

Introduction

This document describes how to install TPA (Third Party App) via appmgr for NCS540 eXR (x86-64) code versions.

The same procedure can be applied on ASR9000, NCS5000, NCS5500 running eXR. The same can be achived in XR7.

The goal by the end of this article is guiding you on buiding a container image offline and build an rpm using the container image, installing the docker container and deploying iperf on top of that docker.

Contributed by Adan De la luz, CISCO TAC Engineer.

Prerequisites

Before proceeding with the steps outlined in this article, ensure the following prerequisites are met:

If you have not installed yet, you must install: python, docker, git and import yaml.
Basic knowledge of working with Docker containers.
Access to the eXR device's command-line interface (CLI) with appropriate administrative privileges.
Familiarity with basic linux commands.
Knowledge of eXR (x86-64) devices and their configuration.
Understanding of python and yaml.

Components Used

The information in this document is based on these software and hardware versions:

NCS-540 running 7.3.1 eXR code version.
Python 3.9.6
Yaml 6.0.1
Docker 24.0.6
Git 2.39.3

The information in this document was created from the devices in a specific lab environment. All of the devices used in
this document started with a cleared (default) configuration. If your network is live, ensure that you understand the
potential impact of any command.

Related Products

With the debut of the XR AppMgr in release 7.3.1, there are now expanded capabilities to activate and manage the lifecycle of third-party docker containers directly within the XR Control Plane.
Host(Hypervisor): This is the underlying 64-bit Operating system that acts as the hypervisor on top of which the XR LXC/VM and the Admin LXC/VM are spawned. For LXC based platforms, it provides the shared kernel for the system. It also runs the container/VM daemons like libvirt and docker to spawn the XR and Calvados instances or even user spawned LXC/Docker instances (on LXC based platforms).

Background Information

Docker technology revolutionizes the world of software deployment and containerization. At its core, Docker simplifies
application management by encapsulating applications and their dependencies into lightweight, portable containers.

These containers can run consistently across diverse environments, ensuring that applications behave predictably,
regardless of the underlying infrastructure. Docker achieves this through the use of Docker images, which serve as
templates for containers. These images are not only stackable and versioned but are also easily distributable and
shareable. Github/ios-xr/xr-appmgr-build, This repository contains the source code for a docker image that can be built and run on IOS-XR to redirect the streaming of telemetry data to an active backup collector when a primary collector goes down for any reason. It will automatically reconfigure the router to send telemetry data back to the primary collector when it comes back up. It runs in the background as a docker container managed by the IOS-XR appmgr.

Configure

Step 1: Pull the RPM build tool.

/ios-xr/xr-appmgr-build

adelaluz@ADELALUZ-M-D0ZV ~ % mkdir appmgr_rpm_tool 
adelaluz@ADELALUZ-M-D0ZV appmgr_rpm_tool %  git clone https://github.com/ios-xr/xr-appmgr-build.git
Cloning into 'xr-appmgr-build'...
remote: Enumerating objects: 71, done.
remote: Counting objects: 100% (71/71), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 71 (delta 24), reused 49 (delta 13), pack-reused 0
Receiving objects: 100% (71/71), 2.62 MiB | 3.73 MiB/s, done.
Resolving deltas: 100% (24/24), done.
adelaluz@ADELALUZ-M-D0ZV appmgr_rpm_tool % ls
xr-appmgr-build
adelaluz@ADELALUZ-M-D0ZV appmgr_rpm_tool % cd xr-appmgr-build
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % ls

LICENSE		Makefile	README.md	appmgr_build	clean.sh	docker		examples
	release_configs
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build %

Step 2: Create a file "build.yaml" and add entries for your app.

adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % touch build.yaml
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % ls
LICENSE		Makefile	README.md	appmgr_build	build.yaml	clean.sh	docker		examples
	release_configs
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % cat > build.yaml
packages:
- name: "alpine"
  release: "eXR_7.3.1" # Release should correspond to a file in release_configs dir
  version: "0.1.0" # Application semantic version 
  sources:
    - name: alpine # corresponds to the source name on the router
      file: ./alpine.tar.gz # path from xr-appmgr-build root to image
  config-dir:
    - name: alpine-configs # the name of the directory for the app to mount in its docker run opts
      dir: examples/alpine/config
  copy_hostname: true # Copy router hostname into config dir (only useful for eXR platforms)
  copy_ems_cert: false # Copy router ems certificate into config dir

NOTE:

"name" any name can be used here instead of alpine. This is just a name placeholder for the app.
“copy_hostname” copies the router hostname into the app’s config dir, so that the container has access to the router hostname.
This is typically used when the application connects to some external controller and needs to identify itself by the configured hostname.
“copy_ems_cert” is required for the third party application to be able to connect to the router’s grpc server (if TLS is configured).
source the source name is not derived from the RPM name, rather it is defined in the build.yaml.
sources:
- name: alpine # corresponds to the source name on the router
file: ./alpine.tar.gz # Path from xr-appmgr-build root to image.

If you are using the example from Github, you do not need to modify "build.yaml" file, but in the script you will need to add the hostname of your device in case of running eXR.

Step 3: Create the container image .tar and package it as an rpm using the build tool.


adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % docker run alpine
Unable to find image 'alpine:latest' locally
latest: Pulling from library/alpine
96526aa774ef: Pull complete 
Digest: sha256:eece025e432126ce23f223450a0326fbebde39cdf496a85d8c016293fc851978
Status: Downloaded newer image for alpine:latest


adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % docker images
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
alpine       latest    8ca4688f4f35   5 weeks ago   7.34MB

adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % ls alpine.tar.gz
alpine.tar.gz

adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % docker save alpine | gzip > alpine.tar.gz
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % ls
LICENSE		README.md	appmgr_build	clean.sh	examples
Makefile	alpine.tar.gz	build.yaml	docker		release_configs
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % python3 ./appmgr_build -b build.yaml                                      
Build version: a400af285be39110322fa885e8d9b1b028d547e5
Starting to build package: alpine
Building docker image arhashem/xr-centos...  
docker build docker -f docker/Centos.Dockerfile -t arhashem/xr-centos   
[+] Building 44.8s (8/8)
  ...SNIP...
 /root/RPMS/noarch:
/root/RPMS/x86_64:
 
alpine-0.1.0-ThinXR_7.3.15.x86_64.rpm 
alpine-0.1.0-eXR_7.3.1.x86_64.rpm
 
Done building package alpine

You can see the RPMs for XR7 and eXR have been created as follow:

XR7: alpine-0.1.0-ThinXR_7.3.15.x86_64.rpm
eXR: alpine-0.1.0-eXR_7.3.1.x86_64.rpm

Step 4: Copy the RPM to router either via tftp or scp and install it using appmgr cli.

adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % ls RPMS/x86_64/alpine-0.1.0-eXR_7.3.1.x86_64.rpm
RPMS/x86_64/alpine-0.1.0-eXR_7.3.1.x86_64.rpm
adelaluz@ADELALUZ-M-D0ZV xr-appmgr-build % 

RP/0/RP0/CPU0:NCS-540#copy ftp://10.122.153.158/alpine-0.1.0-eXR_7.3.1.x86_64.rpm harddisk
Destination filename [/harddisk:/alpine-0.1.0-eXR_7.3.1.x86_64.rpm]?
Accessing ftp://calo:*@10.122.153.158;calo-mgmt/alpine-0.1.0-eXR_7.3.1.x86_64.rpm
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
Copy operation success

RP/0/RP0/CPU0:NCS-540#appmgr package install rpm /harddisk:/alpine-0.1.0-ThinXR_7.3.15.aarch64.rpm
RP/0/RP0/CPU0:NCS-540#show appmgr packages installed 
Package                                                    
------------------------------------------------------------
bash-0.1.0-dummy.fretta_x86  
alpine-0.1.0-eXR_7.3.1.x86_64.rpm               
RP/0/RP0/CPU0:NCS-540#

Step 5: Activate the container using appmgr config.

RP/0/RP0/CPU0:NCS-540#conf ter      
RP/0/RP0/CPU0:NCS-540(config)#appmgr   
RP/0/RP0/CPU0:NCS-540(config-appmgr)#application alpine  
RP/0/RP0/CPU0:NCS-540(config-application)#activate type docker source alpine docker-run-opts "-it" docker-run-cmd "sh"
RP/0/RP0/CPU0:NCS-540(config-application)#commit

RP/0/RP0/CPU0:NCS-540#show appmgr application name alpine info detail
Application: alpine
  Type: Docker
  Source: alpine
  Config State: Activated
  Docker Information:
    Container ID: 12312404cbdf8376d6
    Container name: alpine
    Labels: 
    Image: alpine:latest
    Command: "sh"
    Created at: 2023-10-23 11:25:01 +0000 UTC
    Running for: 58 seconds ago
    Status: Up 56 seconds
    Size: 0B (virtual 5.57MB)
    Ports: 
    Mounts: 
    Networks: bridge
    LocalVolumes: 0

Installing IPERF on top of docker container.

Here are the steps you need to follow to install iperf (do it on the iServer and iClient).

Step 1. Copy the ubuntu-iperf-image.tar to router’s harddisk.
Step 2. Once the file is in harddisk, load it on bash:

RP/0/RP0/CPU0:NCS-540#bash
[NCS-540:~]$ docker load -i /misc/disk1/ubuntu-iperf-image.tar
8ce178ff9f34: Loading layer [==================================================>]  84.03MB/84.03MB
1b9aa83ebcfe: Loading layer [==================================================>]  1.291MB/1.291MB
Loaded image: ubuntu-iperf-image:latest

Step 3. Verifying the image is loaded.

[NCS-540:~]$ docker image ls
REPOSITORY             TAG                 IMAGE ID            CREATED             SIZE
ubuntu-iperf-image   latest              f2633a30407f        15 mins ago         81.8MB     <<<< the name can change

Step 4. Once the image is loaded, run it on the server and client:

Server

[NCS-540:/]$ docker run -it --rm --net host --name iperf3-server -p 5201:5201 ubuntu-iperf-image -s

Note: If the name is not "ubuntu-iperf-image", please use the correct one on these commands.

Client

[NCS-540-B:~]$ docker run  --net host --rm -t ubuntu-iperf-image -c 10.222.252.40

Note: 10.222.252.40 would be the ip address from the server.

Adan

adelaluz

marce1000 · ‎11-20-2023

- Nice documentation (two posts) ; note that there are also parts of the community related to blogging and documentation , probably good to post in relevant related section too ; this group is by definition volatile because of added posts , then the info 'goes away' ,

M.

-- Each morning when I wake up and look into the mirror I always say ' Why am I so brilliant ? '
When the mirror will then always repond to me with ' The only thing that exceeds your brilliance is your beauty! '

View solution in original post

marce1000 · ‎11-20-2023

- Nice documentation (two posts) ; note that there are also parts of the community related to blogging and documentation , probably good to post in relevant related section too ; this group is by definition volatile because of added posts , then the info 'goes away' ,

M.

-- Each morning when I wake up and look into the mirror I always say ' Why am I so brilliant ? '
When the mirror will then always repond to me with ' The only thing that exceeds your brilliance is your beauty! '

adelaluz · ‎11-20-2023

My bad, I noticed it has to be posted in article zone, and I did so. Thank you.

adelaluz