Buy or Renew
Buy or Renew
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
cancel
Create a new blog
4689
Views
4
Helpful
0
Comments

Best Practices in Migrating from NID to Official Containerized NSO

Pannag Desai
Cisco Employee
Cisco Employee
‎10-10-2024 03:50 AM

Co-Author: @Qi Li 

Table of Contents

 

We've seen many customers requesting support for the open-source project NSO in Docker (NID). Unfortunately, since NID is an unsupported open-source solution, we're unable to provide help when issues arise. Because of this, we strongly encourage customers to migrate to the officially supported Cisco Containerized NSO framework, which follows best practices and offers full support from Cisco.

We've heard from customers that transitioning from NID can feel like a barrier, and we've seen common issues pop up during the migration process. To make the transition as smooth as possible, we've put together this guide to help you every step of the way. For more information about NID, check out the links below.

For, Containerized NSO and “Recommended Containerized NSO Framework”:

In this guide, we will focus on one-to-one migration from one NID instance to single Containerized NSO instance.

With above foundations, same method is also applied on the “Recommended Containerized NSO Framework” with various scenario.

Prerequisites

We recommend you proceeding with cloning the single-instance-container-example repository and have the Containerized NSO image ready from https://software.cisco.com/download/home before proceed further.

Keep your NID setup ready, document all explicit tools, your native settings, configuration files before attempting the migration.

Please note that the “nso-dev” container has been renamed to “nso-build” in later versions of NSO.

File Structure Migration

The file structure of NID setup is shown as below:

 

|- NSO ROOT DIRECTORY/
  |- coredumps/
  |- etc/
    |- ncs.crypto_keys
    |- ssh/
    |- ssl/
  |- logs/
  |- run/
    |- packages/
    |- cdb/
    |- backups/
    |- rollbacks/
    |- scripts/
    |- state/
    |- streams/
    |- target/
    |- storedstate

 

We will map these directories to volumes of Contanerized NSO as part of this migration process

Our first step is to move these folder from NID to the Recommended Containerized NSO framework, to allow Containerized NSO start up with the same settings and data as NID.

NID has some tools in “docker-images/Dockerfile“ that Containerized NSO might not have. One can migrate the necessary components by copying those lines from “nso-docker/docker-images/Dockerfile“ to the “single-instance-containerized-nso/Dockerfile“ in the Containerized NSO framework.

single-instance-containerized-nso/Dockerfile:

 

ARG  type ver
FROM cisco-nso-$type:$ver
COPY requirements.txt /requirements.txt
RUN pip install --upgrade pip && \
	pip install -r requirements.txt
#Yum install
#RUN yum -y install <dependency> && \
#    rm -rf /tmpm/* && \
#    yum remove unzip -y && \
#    yum clean all && \
#    rm -rf /var/cache/yum
#Dnf install
#RUN dnf -y update
#RUN dnf install -y <dependency> && \
#    dnf clean all
RUN echo "alias ll='ls -alF'" >> ~/.bashrc
EXPOSE 22 80 443 2024 830 4334 2022

 

Inside this Dockerfile, one can add the extra dependencies with Yum or Dnf as shown above.

Container Migration

After the file migration is ready, we can start migrating the container and images from the NID towards Containerized NSO by following the steps below.

  • Stop the NID container instance(s). 
    docker container stop <NID container_id>
  • In case you are running docker-compose service, use: 
     docker-compose down [SERVICES]
  • Copy ncs.conf file if you want to apply same settings to Contanerized NSO: 
    docker cp nid-prod:/etc/ncs/ncs.conf NSO-Vol/nso-config/
  • Copy the Official Containerized NSO image into the “images“ folder above. Than build the enviorment with the command below.
    make clean build
  • When the command above is called in “Recommended Containerized NSO framwork” what is actually happend is the image in the image folder will be loaded
     
    docker load -i ./images/nso-${VER}.container-image-dev.linux.${ARCH}.tar.gz 
    docker load -i ./images/nso-${VER}.container-image-prod.linux.${ARCH}.tar.gz
  • At the same time, build the Dockerfile with extra dependency from NID with the image above. Please note that the BUILD_CONT variable should be “dev” for older versions, and “build” for later versions.

     
    docker build -t mod-nso-prod:${VER} --no-cache --network=host --build-arg type="prod" --build-arg ver=${VER} --file Dockerfile . 
    docker build -t mod-nso-build:${VER} --no-cache --network=host --build-arg type=${BUILD_CONT} --build-arg ver=${VER} --file Dockerfile .

  • This marks the build process completion. We can proceed next with spinning up containers with volume mappings and startup commands.

    An example template for one instance of the docker-compose file is constructed as below.

    services:
     PROD:
       image: mod-nso-prod:${VER}
       container_name: nso_prod
       network_mode: none
       profiles:
             - prod
       environment:
             - EXTRA_ARGS=--with-package-reload
             - ADMIN_USERNAME=admin
             - ADMIN_PASSWORD=admin
       ports:
             - "2023:2024"
             - "8889:8888"
       volumes:
             - type: bind
               source: './NSO-vol/nso/etc'
               target: '/nso/etc'
             - type: bind
               source: './NSO-vol/nso/run'
               target: '/nso/run'
             - type: bind
               source: './NSO-log'
               target: '/logs'
             - type: bind
               source: './NSO-vol/nso-config/ncs.conf'
               target: '/etc/ncs/ncs.conf'
       healthcheck:
            test: ncs_cmd -c "wait-start 2"
            interval: 5s
            retries: 5
            start_period: 10s
            timeout: 10s
     BUILD:
            image: mod-nso-dev:${VER}
            container_name: nso-build
            network_mode: none
            profiles:
                - build
            volumes:
                - type: bind
                  source: './NSO-vol/nso/run/packages'
                  target: '/packages'
                - type: bind
                  source: './NSO-log/'
                  target: '/logs'
            command: /bin/bash -c "make all -C /packages/ && sleep infinity"​

    There are two services in above docker-compose file: PROD and BUILD, each targetted at spinning up production container and build container respectively. Please note that the volume binding for ncs.conf might be optional and that line can be removed. Ensure that the file strusture is preserved and migrated one-to-one, The NSO ROOT DIRECTORY is a folder that contains directories etc and run, We must copy these directories to Host machine's NSO-vol directory. To copy them, you can use following commands:

    docker cp nid-prod:/nso/etc ./NSO-vol/etc
docker cp nid-prod:/nso/run ./NSO-vol/run
docker cp nid-prod:/nso/logs ./NSO-log


    The directories are mapped as depicted below:

    NID Host volume   Containers
    NSO ROOT DIRECTORY/etc NSO-vol/nso/etc prod-container's /nso/etc
    NSO ROOT DIRECTORY/run NSO-vol/nso/run prod-container's /nso/run
    root/etc/ncs/nsc.conf NSO-vol/nso-config/ncs.conf prod-container's /etc/ncs.conf
    NSO ROOT DIRECTORY/run/packages NSO-vol/nso/run/packages dev-container's /packages
    root/logs NSO-log/ dev and prod container's /log

    • Notice that build container only has volume mapping to packages directory, and does not take into account complete nso running directory.

    • To start above docker-compose file’s service, use:

      VER=<VERSION OF CONTAINERIZED NSO ex: 6.3> docker-compose up PROD BUILD -d
    • After compose service process concludes, you can verify by executing NSO cli from production container. You can refer below checklist, which you can even expand as per your requirements and setup:
      • Production Container is healthy.
      • All packages are up (execute show packages package oper status from NSO CLI on Prod).
      • If you had data and configurations, check if they are persistant in Prod Container.
    • Check if all packages are loaded, and CDB configurations from NID are persistant and migrated successfully.

 

Demo

Check prod NID container

 

pannag@VPannagSs-MacBook-Air nso-docker % docker ps        

CONTAINER ID   IMAGE                       COMMAND         CREATED        STATUS                   PORTS                                                  NAMES 

16e0d73fe7e8   cisco-nso-base:6.3-pannag   "/run-nso.sh"   12 hours ago   Up 6 minutes (healthy)   22/tcp, 80/tcp, 443/tcp, 830/tcp, 4334/tcp, 4570/tcp   nso-prod-nid

 


Check file-structure binded to host from NID container shell

 

pannag@VPannagSs-MacBook-Air nso-docker % docker exec -it 16e0d73fe7e8 /bin/bash 
root@16e0d73fe7e8:/# ls 
bin  boot  dev  enter-shell.sh  etc  home  lib  lib64  log  media  mnt  nid  nso  opt  proc  root  run  run-nso.sh  sbin  srv  sys  tmp  usr  var

 

As an example we have a configuration that needs to be kept persistent across migration process

 

admin@ncs# show running-config devices device netconf1  
devices device netconf1 
 address   127.0.0.1 
 port      1000 
 authgroup default 
 device-type netconf ned-id netconf 
 state admin-state unlocked 
! 
admin@ncs#

 

Load official NSO docker Images

pannag@VPannagSs-MacBook-Air nso-docker % docker load -i nso-6.3.container-image-dev.linux.x86_64.tar.gz  
87caf0e440a2: Loading layer [==================================================>]  225.7MB/225.7MB 
28ba30f86e74: Loading layer [==================================================>]  1.583GB/1.583GB 
Loaded image: cisco-nso-dev:6.3 
pannag@VPannagSs-MacBook-Air nso-docker % docker load -i nso-6.3.container-image-prod.linux.x86_64.tar.gz 
9d79babd5dc4: Loading layer [==================================================>]  1.183GB/1.183GB 
Loaded image: cisco-nso-prod:6.3 
pannag@VPannagSs-MacBook-Air nso-docker % docker images                                                                                   
REPOSITORY       TAG          IMAGE ID       CREATED        SIZE 
cisco-nso-base   6.3-pannag   639688eeca65   12 hours ago   680MB 
cisco-nso-dev    6.3-pannag   b002112240f1   12 hours ago   2.15GB 
cisco-nso-dev    6.3          3c0a44f35f1c   5 months ago   1.77GB 
cisco-nso-prod   6.3          9b1aee56eb76   5 months ago   1.37GB

Stop NID Containers (or use docker-compose-down if you created and started services through docker compose)

pannag@VPannagSs-MacBook-Air nso-docker % docker container stop 16e0d73fe7e8 
16e0d73fe7e8

Start a docker compose service

pannag@VPannagSs-MacBook-Air nso-docker % VER=6.3 docker-compose up BUILD PROD -d 
[+] Running 4/4 
 ✔ Container nso_prod                                                     Started  0.2s  
 ✔ Container nso-build                                                    Started  0.2s  
pannag@VPannagSs-MacBook-Air nso-docker % docker ps                               
CONTAINER ID   IMAGE                COMMAND                  CREATED         STATUS                   PORTS     NAMES 
887f31855e8f   cisco-nso-prod:6.3   "/run-nso.sh"            8 seconds ago   Up 7 seconds (healthy)             nso_prod 
a95076659c3d   cisco-nso-dev:6.3    "/bin/bash -c 'for i…"   8 seconds ago   Up 7 seconds                       nso-build

From production container's shell, verify if the configurations have been migrated and packages are loaded

pannag@VPannagSs-MacBook-Air nso-docker % docker exec -it b40eef21deb3 /bin/bash 
[root@887f31855e8f /]# ncs_cli -Cu admin -noaaa 
User admin last logged in 2024-10-02T19:09:33.622045+00:00, to 887f31855e8f, from 127.0.0.1 using cli-console 
admin connected from 127.0.0.1 using console on 887f31855e8f 
admin@ncs# show packages package oper-status  
packages package sample_service 
 oper-status up 
admin@ncs# show running-config devices device netconf1  
devices device netconf1 
 address   127.0.0.1 
 port      1000 
 authgroup default 
 device-type netconf ned-id netconf 
 state admin-state unlocked 
!

 

Use Containerized NSO Migration Framework

An automated way to experience migration, this project gives you an complete details on getting famaliar with the procedure.

https://github.com/NSO-developer/single-instance-container-example

Steps come in two sections, and first section for setting up simple NID is optional:

[OPTIONAL - If you do not have existing NID setup and need to simulate example from ground, include this section] Steps to create prerequisite NID setup for demo:

  • Download NSO image from Cisco Download Software center.
  • Clone NID repository and cd into nso-docker
  • Inside nso-docker, put your desired NSO version image in directory "nso-install-files"
  • Run make which will build two docker images, cisco-nso-base and cisco-nso-dev.
  • cd into single-instance-migration
  • As it is demonstration, we will only use cisco-nso-base to build our container, use following comand to build:
      docker run -itd -v $(pwd)/NSO-vol/nso:/nso --name nid-prod cisco-nso-base:<tag>
      You can get tag from docker images command corresponding to your image.
  • You should be able to see now two folders (NSO-vol and NSO-log) in current directory
  • Inside them you can see NSO file structure, and your NID setup is ready. You can also verify it by excecuting NSO CLI using container shell, next we will see how to migrate to Official image of Containerized NSO.

Steps for Migration

  • Clone repo and checkout nid_migration branch:
        git clone https://gitlab.com/nso-developer/single-instance-container-example
    cd single-instance-container-example
    git checkout nid_migration
  • Download Containerized NSO images (production as well as development) from Cisco Download Center.
  • Extract images and store tar files of images inside single-instance-container-example/images
  • Run 
    make build
    ....
    .......
    Successfully built d1cc7a6f3185
    Successfully tagged mod-nso-dev:6.3
    cp util/Makefile NSO-vol/nso/run/packages/

  • This step includes:

    • loading your contanerized NSO images
    • building mod-nso-dev and mod-nso-prod images from the loaded images, with some customizations to help us update packages/libraries on images
    • copy ncs.conf file from NID container using docker cp command (this can be skipped if parent of ncs.conf is mapped volume on host, then it can be mapped to Containerized NSO prod container in later step).
    • stop NID container(s).
    • It also copies Makefile from util which will help us build all packages when we spin up development container through docker compose.
    • After the target completes the build process, you can see loaded images:
      panndesa@PANNDESA-M-CX29 single-instance-container-example % docker images
REPOSITORY                                          TAG                    IMAGE ID       CREATED          SIZE
mod-nso-dev                                         6.3                    d1cc7a6f3185   9 minutes ago    2.69GB
mod-nso-prod                                        6.3                    4913ad823856   16 minutes ago   1.96GB

    • We will proceed with bringing up compose service using the target:

      make start_compos
panndesa@PANNDESA-M-CX29 single-instance-container-example % make start_compose
VER="6.3" docker-compose up BUILD PROD -d
[+] Running 4/4
✔ Container nso_prod Started 0.4s 
✔ Container nso-build Started 0.4s



      Once containers are up, verify their health as mentioned in manual procedure. For more details on this repository, please check Readme.

Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the NSO Developer community:

Popular Articles
Customers Also Viewed These Support Documents