- Introduction
- Prerequisites
- Components Used
- Related Products
- Background Information
- Configure
- Step 1: Pull the RPM build tool.
- Step 2: Create a file "build.yaml" and add entries for your app.
- Step 3: Create the container image .tar and package it as an rpm using the build tool.
- Step 4: Copy the RPM to router either via tftp or scp and install it using appmgr cli.
- Step 5: Activate the container using appmgr config.
- Installing IPERF on top of docker container.
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.
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
