diff --git a/doc/sonic-application-extention/img/docker-infra-concepts.svg b/doc/sonic-application-extention/img/docker-infra-concepts.svg new file mode 100644 index 00000000000..2f6c3af628a --- /dev/null +++ b/doc/sonic-application-extention/img/docker-infra-concepts.svg @@ -0,0 +1,268 @@ + + + + + + + + + + Page-1 + + + Sheet.14 + + Rounded Rectangle + Docker Registry + + + + + + + + + + + + + + + + + + + + + + Docker Registry + + Sheet.13 + + Rounded Rectangle.2 + Azure/sonic-dhcp-relay + + + + + + + + + + + + + + + + + + + + + + Azure/sonic-dhcp-relay + + Rounded Rectangle.3 + Azure/sonic-snmp + + + + + + + + + + + + + + + + + + + + + + Azure/sonic-snmp + + Sheet.8 + + Rounded Rectangle.5 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.6 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.7 + 1.0.0, 1.56.3, ... + + + + + + + + + + + + + + + + + + + + + + 1.0.0, 1.56.3, ... + + + Sheet.9 + + Rounded Rectangle.5 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.6 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.7 + 2.1.0, 0.9.1, ... + + + + + + + + + + + + + + + + + + + + + + 2.1.0, 0.9.1, ... + + + + + diff --git a/doc/sonic-application-extention/img/feature-start.svg b/doc/sonic-application-extention/img/feature-start.svg new file mode 100644 index 00000000000..e049f245e84 --- /dev/null +++ b/doc/sonic-application-extention/img/feature-start.svg @@ -0,0 +1,494 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + Object lifeline + systemd + + Sheet.6 + + + + Sheet.7 + + + + Sheet.8 + + + Sheet.9 + + + + + + + systemd + + + + + + + + Object lifeline.11 + /usr/local/bin/<feature>.sh + + Sheet.12 + + + + Sheet.13 + + + + Sheet.14 + + + Sheet.15 + + + + + + + /usr/local/bin/<feature>.sh + + + + + + + + Object lifeline.16 + /usr/bin/<feature>.sh + + Sheet.17 + + + + Sheet.18 + + + + Sheet.19 + + + Sheet.20 + + + + + + + /usr/bin/<feature>.sh + + + + + + + + Object lifeline.21 + dockerd + + Sheet.22 + + + + Sheet.23 + + + + Sheet.24 + + + Sheet.25 + + + + + + + dockerd + + + + + + + + Object lifeline.31 + hostcfgd + + Sheet.32 + + + + Sheet.33 + + + + Sheet.34 + + + Sheet.35 + + + + + + + hostcfgd + + + Message + systemctl start <feautre> + + + + + + + + + + + systemctl start <feautre> + + Message.37 + /usr/local/bin/<feature>.sh start + + + + + + + + + + + /usr/local/bin/<feature>.sh start + + Message.38 + /usr/bin/<feature>.sh start + + + + + + + + + + + /usr/bin/<feature>.sh start + + Message.39 + docker create + + + + + + + + + + + docker create + + Message.40 + docker start + + + + + + + + + + + docker start + + Return Message + return + + + + + + + + + + + return + + Return Message.53 + return + + + + + + + + + + + return + + Return Message.54 + return + + + + + + + + + + + return + + Return Message.88 + return + + + + + + + + + + + return + + Return Message.123 + return + + + + + + + + + + + return + + Activation + + + + + + + Activation.130 + + + + + + + Activation.131 + + + + + + + Activation.132 + + + + + + + Activation.133 + + + + + + + Activation.134 + + + + + + + Message.135 + docker exec -it <feautre> postStartAction + + + + + + + + + + + docker exec -it <feautre> postStartAction + + Return Message.137 + return + + + + + + + + + + + return + + Activation.138 + + + + + + + Message.139 + /usr/local/bin<feature>.sh wait + + + + + + + + + + + /usr/local/bin<feature>.sh wait + + Message.140 + /usr/bin<feature>.sh wait + + + + + + + + + + + /usr/bin<feature>.sh wait + + Message.141 + docker wait + + + + + + + + + + + docker wait + + + + + Optional fragment + + + + + Sheet.143 + opt + + + + + + + + + + + + + + + opt + + Sheet.144 + [docker inspect --type container <feature> ] + + + + + + [docker inspect --type container <feature> ] + + + diff --git a/doc/sonic-application-extention/img/feature-stop.svg b/doc/sonic-application-extention/img/feature-stop.svg new file mode 100644 index 00000000000..d14439ec11e --- /dev/null +++ b/doc/sonic-application-extention/img/feature-stop.svg @@ -0,0 +1,469 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + Object lifeline + systemd + + Sheet.2 + + + + Sheet.3 + + + + Sheet.4 + + + Sheet.5 + + + + + + + systemd + + + + + + + + Object lifeline.6 + /usr/local/bin/<feature>.sh + + Sheet.7 + + + + Sheet.8 + + + + Sheet.9 + + + Sheet.10 + + + + + + + /usr/local/bin/<feature>.sh + + + + + + + + Object lifeline.11 + /usr/bin/<feature>.sh + + Sheet.12 + + + + Sheet.13 + + + + Sheet.14 + + + Sheet.15 + + + + + + + /usr/bin/<feature>.sh + + + + + + + + Object lifeline.16 + dockerd + + Sheet.17 + + + + Sheet.18 + + + + Sheet.19 + + + Sheet.20 + + + + + + + dockerd + + + + + + + + Object lifeline.31 + hostcfgd + + Sheet.22 + + + + Sheet.23 + + + + Sheet.24 + + + Sheet.25 + + + + + + + hostcfgd + + + Message + systemctl stop <feautre> + + + + + + + + + + + systemctl stop <feautre> + + Message.37 + /usr/local/bin/<feature>.sh stop + + + + + + + + + + + /usr/local/bin/<feature>.sh stop + + Message.38 + /usr/bin/<feature>.sh stop + + + + + + + + + + + /usr/bin/<feature>.sh stop + + Message.39 + docker kill + + + + + + + + + + + docker kill + + Message.40 + docker stop + + + + + + + + + + + docker stop + + Return Message + return + + + + + + + + + + + return + + Return Message.53 + return + + + + + + + + + + + return + + Return Message.54 + return + + + + + + + + + + + return + + Return Message.88 + return + + + + + + + + + + + return + + Return Message.123 + return + + + + + + + + + + + return + + Activation + + + + + + + Activation.130 + + + + + + + Activation.131 + + + + + + + Activation.132 + + + + + + + Activation.133 + + + + + + + Activation.134 + + + + + + + Message.135 + docker exec -it <feautre> preStopAction + + + + + + + + + + + docker exec -it <feautre> preStopAction + + Return Message.137 + return + + + + + + + + + + + return + + Activation.138 + + + + + + + + + + Optional fragment + + + + + Sheet.49 + opt + + + + + + + + + + + + + + + opt + + Sheet.50 + [COLD_RESTART=n ] + + + + + + [COLD_RESTART=n ] + + + + + + Optional fragment.60 + + + + + Sheet.62 + [COLD_RESTART=y ] + + + + + + [COLD_RESTART=y ] + + + diff --git a/doc/sonic-application-extention/img/install-flow.svg b/doc/sonic-application-extention/img/install-flow.svg new file mode 100755 index 00000000000..bab72c398f5 --- /dev/null +++ b/doc/sonic-application-extention/img/install-flow.svg @@ -0,0 +1,652 @@ + + + + + + + + + + + + + + + + + + + + + + + + Сторінка 1 + + + + + + + + + Лінія проекту + Package Manager + + Аркуш.2 + + + + Аркуш.3 + + + + Аркуш.4 + + + Аркуш.5 + + + + + + + Package Manager + + + + + + + + Лінія проекту.12 + dockerd + + Аркуш.13 + + + + Аркуш.14 + + + + Аркуш.15 + + + Аркуш.16 + + + + + + + dockerd + + + + + + + + Лінія проекту.17 + Docker Registry + + Аркуш.18 + + + + Аркуш.19 + + + + Аркуш.20 + + + Аркуш.21 + + + + + + + Docker Registry + + + + + + + + Лінія проекту.22 + CONFIG DB + + Аркуш.23 + + + + Аркуш.24 + + + + Аркуш.25 + + + Аркуш.26 + + + + + + + CONFIG DB + + + + + + + + Лінія проекту.27 + Host OS FS + + Аркуш.28 + + + + Аркуш.29 + + + + Аркуш.30 + + + Аркуш.31 + + + + + + + Host OS FS + + + + + + + + Лінія суб’єкта + User + + Аркуш.33 + + + + Аркуш.34 + + + + Аркуш.35 + + + Аркуш.36 + + + + + + + User + + + Повідомлення + install <package> + + + + + + + + + + + install <package> + + Повідомлення.44 + docker pull <repo>:<tag> + + + + + + + + + + + docker pull <repo>:<tag> + + Повідомлення.45 + pull + + + + + + + + + + + pull + + Повернуто повідомлення + return + + + + + + + + + + + return + + Повернуто повідомлення.48 + return + + + + + + + + + + + return + + Повідомлення.50 + docker tag <repo>:<tag>\ <repo>:latest + + + + + + + + + + + docker tag <repo>:<tag>\ <repo>:latest + + Повернуто повідомлення.52 + + + + + + + + + + Повідомлення.53 + docker run <repo>:latest sleep + + + + + + + + + + + docker run <repo>:latest sleep + + Повернуто повідомлення.54 + + + + + + + + + + Повідомлення.59 + render host scripts/files to host FS reload host services con... + + + + + + + + + + + render host scripts/files to host FSreload host services configuration + + Повернуто повідомлення.60 + return + + + + + + + + + + + return + + Повідомлення.61 + Load feature initial configuration to running DB + + + + + + + + + + + Load feature initial configuration to running DB + + Повернуто повідомлення.62 + return + + + + + + + + + + + return + + Повернуто повідомлення.63 + return + + + + + + + + + + + return + + Активація + + + + + + + Активація.65 + + + + + + + Активація.66 + + + + + + + Активація.67 + + + + + + + Активація.68 + + + + + + + Активація.69 + + + + + + + Активація.71 + + + + + + + Активація.72 + + + + + + + Активація.73 + + + + + + + Повідомлення.74 + Register new feature in FEATURE table (runnig & persistent) + + + + + + + + + + + Register new feature in FEATURE table (runnig & persistent) + + Повернуто повідомлення.75 + return + + + + + + + + + + + return + + Активація.76 + + + + + + + Повідомлення на себе + Check package dependencies/conflicts + + + + + + + + + + + Check package dependencies/conflicts + + Повідомлення на себе.78 + Update installation status in DB + + + + + + + + + + + Update installation status in DB + + Повідомлення.79 + Load feature initial configuration to persistent DB (/etc/son... + + + + + + + + + + + Load feature initial configuration to persistent DB (/etc/sonic/config_db.json & /etc/sonic/init_cfg.json) + + Повернуто повідомлення.80 + return + + + + + + + + + + + return + + Активація.82 + + + + + + + + + + Інший фрагмент.152 + + + + + Аркуш.87 + alt + + + + + + + + + + + + + + + alt + + Аркуш.88 + requirements are met + + + + + + requirements aremet + + + Повідомлення.89 + get docker labels (com.azure.sonic.manifest) + + + + + + + + + + + get docker labels (com.azure.sonic.manifest) + + Повернуто повідомлення.92 + return + + + + + + + + + + + return + + Активація.94 + + + + + + + diff --git a/doc/sonic-application-extention/img/packages-json.svg b/doc/sonic-application-extention/img/packages-json.svg new file mode 100644 index 00000000000..73fdbd3a5ae --- /dev/null +++ b/doc/sonic-application-extention/img/packages-json.svg @@ -0,0 +1,390 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Sheet.22 + + Rounded Rectangle + Docker Registry + + + + + + + + + + + + + + + + + + + + + + Docker Registry + + Sheet.24 + + Rounded Rectangle.2 + Azure/sonic-dhcp-relay + + + + + + + + + + + + + + + + + + + + + + Azure/sonic-dhcp-relay + + Rounded Rectangle.3 + Azure/sonic-snmp + + + + + + + + + + + + + + + + + + + + + + Azure/sonic-snmp + + Sheet.27 + + Rounded Rectangle.5 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.6 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.7 + 1.0.0, 1.56.3, ... + + + + + + + + + + + + + + + + + + + + + + 1.0.0, 1.56.3, ... + + + Sheet.31 + + Rounded Rectangle.5 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.6 + + + + + + + + + + + + + + + + + + + + + + Rounded Rectangle.7 + 2.1.0, 0.9.1, ... + + + + + + + + + + + + + + + + + + + + + + 2.1.0, 0.9.1, ... + + + + + Sheet.35 + + Rounded Rectangle.13 + SONiC OS + + + + + + + + + + + + + + + + + + + + + + SONiC OS + + Rectangle + packages.json + + + + + + + packages.json + + Dynamic connector + + + + Dynamic connector.16 + + + + Rounded Rectangle.17 + Local Docker Storage: - docker-database - docker-orchagent etc. + + + + + + + + + + + + + + + + + + + + + + Local Docker Storage: - docker-database - docker-orchagent etc. + + Dynamic connector.18 + Essential packages are pointed to local docker image + + + + + Essential packagesare pointedto local docker image + + + diff --git a/doc/sonic-application-extention/img/sonic-package-integration.svg b/doc/sonic-application-extention/img/sonic-package-integration.svg new file mode 100644 index 00000000000..23c96ba575a --- /dev/null +++ b/doc/sonic-application-extention/img/sonic-package-integration.svg @@ -0,0 +1,319 @@ + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Sheet.34 + + Rounded Rectangle + SONiC Host OS + + + + + + + + + + + + + + + + + + + + + + SONiC Host OS + + Rounded Rectangle.3 + Docker Image + + + + + + + + + + + + + + + + + + + + + + Docker Image + + Rounded Rectangle.4 + manifest.json + + + + + + + + + + + + + + + + + + + + + + manifest.json + + Rectangle + Container mgmt. scripts + + + + + + + Container mgmt. scripts + + Rectangle.9 + monit.conf + + + + + + + monit.conf + + Rectangle.10 + CLI plugin + + + + + + + CLI plugin + + Rectangle.11 + hostcfgd + + + + + + + hostcfgd + + Rectangle.12 + Etc. + + + + + + + Etc. + + Rectangle.13 + Systemd service file + + + + + + + Systemdservice file + + Rectangle.14 + config reload + + + + + + + config reload + + Rectangle.15 + Warm reboot script + + + + + + + Warm reboot script + + Rectangle.16 + Techsupport script + + + + + + + Techsupport script + + Rounded Rectangle.22 + supervisord + + + + + + + + + + + + + + + + + + + + + + supervisord + + Rounded Rectangle.23 + Application Binaries + + + + + + + + + + + + + + + + + + + + + + Application Binaries + + Rectangle.25 + + + + + + + Dynamic connector + Autogeneration/Integration with existing script + + + + + Autogeneration/Integration with existing script + + Rectangle.27 + autogenerated + + + + + + + autogenerated + + Rectangle.28 + existing components + + + + + + + existing components + + Rectangle.31 + SONiC package + + + + + + + SONiC package + + + diff --git a/doc/sonic-application-extention/img/sonic-pkg-basic-concepts.svg b/doc/sonic-application-extention/img/sonic-pkg-basic-concepts.svg new file mode 100644 index 00000000000..f02e0a2afcb --- /dev/null +++ b/doc/sonic-application-extention/img/sonic-pkg-basic-concepts.svg @@ -0,0 +1,3 @@ + + +
Docker Registry
Docker Registry
Feature X (Repository)
Feature X (Repository)
v1, v2, 20206, latest( tags)
v1, v2, 20206, latest(...
Feature Y (Repository)
Feature Y (Repository)
v1, v2, 20206, latest( tags)
v1, v2, 20206, latest(...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/doc/sonic-application-extention/img/uninstall-flow.svg b/doc/sonic-application-extention/img/uninstall-flow.svg new file mode 100644 index 00000000000..e97589fc013 --- /dev/null +++ b/doc/sonic-application-extention/img/uninstall-flow.svg @@ -0,0 +1,576 @@ + + + + + + + + + + + + + + + + + + + + + + + + Сторінка 1 + + + + + + + + + Лінія проекту + Package Manager + + Аркуш.65 + + + + Аркуш.66 + + + + Аркуш.67 + + + Аркуш.68 + + + + + + + Package Manager + + + + + + + + Лінія проекту.12 + dockerd + + Аркуш.70 + + + + Аркуш.71 + + + + Аркуш.72 + + + Аркуш.73 + + + + + + + dockerd + + + + + + + + Лінія проекту.17 + Docker Registry + + Аркуш.75 + + + + Аркуш.76 + + + + Аркуш.77 + + + Аркуш.78 + + + + + + + Docker Registry + + + + + + + + Лінія проекту.22 + CONFIG DB + + Аркуш.80 + + + + Аркуш.81 + + + + Аркуш.82 + + + Аркуш.83 + + + + + + + CONFIG DB + + + + + + + + Лінія проекту.27 + Host OS FS + + Аркуш.85 + + + + Аркуш.86 + + + + Аркуш.87 + + + Аркуш.88 + + + + + + + Host OS FS + + + + + + + + Лінія суб’єкта + User + + Аркуш.90 + + + + Аркуш.91 + + + + Аркуш.92 + + + Аркуш.93 + + + + + + + User + + + Повідомлення + uninstall <package> + + + + + + + + + + + uninstall <package> + + Повідомлення.59 + remove rendered host scripts/files to host FS reload host ser... + + + + + + + + + + + remove rendered host scripts/files to host FSreload host services configuration + + Повернуто повідомлення.60 + return + + + + + + + + + + + return + + Повернуто повідомлення.63 + return + + + + + + + + + + + return + + Активація + + + + + + + Активація.65 + + + + + + + Активація.72 + + + + + + + Повідомлення.74 + Deregister feature in FEATURE table (runnig & persistent) + + + + + + + + + + + Deregister feature in FEATURE table (runnig & persistent) + + Повернуто повідомлення.75 + return + + + + + + + + + + + return + + Активація.76 + + + + + + + Повідомлення на себе + Check package dependencies/conflicts + + + + + + + + + + + Check package dependencies/conflicts + + Повідомлення на себе.78 + Update installation status/version in DB + + + + + + + + + + + Update installation status/version in DB + + Повідомлення.56 + remove package metadata folder + + + + + + + + + + + remove package metadata folder + + Повернуто повідомлення.57 + return + + + + + + + + + + + return + + Активація.71 + + + + + + + Повідомлення.139 + docker rmi -f <repo>:latest + + + + + + + + + + + docker rmi -f <repo>:latest + + Повідомлення.140 + docker rmi -f <repo>:<tag> + + + + + + + + + + + docker rmi -f <repo>:<tag> + + Повернуто повідомлення + + + + + + + + + + Повернуто повідомлення.142 + + + + + + + + + + Активація.143 + + + + + + + Активація.144 + + + + + + + Активація.145 + + + + + + + Повідомлення.146 + Get feature status + + + + + + + + + + + Get feature status + + Повернуто повідомлення.147 + return + + + + + + + + + + + return + + + + + Інший фрагмент + + + + + Аркуш.149 + alt + + + + + + + + + + + + + + + alt + + Аркуш.150 + status != disabled + + + + + + status != disabled + + + + + + Інший фрагмент.152 + + + + + Аркуш.153 + alt + + + + + + + + + + + + + + + alt + + Аркуш.154 + requirements are met + + + + + + requirements aremet + + + diff --git a/doc/sonic-application-extention/img/upgrade-flow.svg b/doc/sonic-application-extention/img/upgrade-flow.svg new file mode 100755 index 00000000000..8d22f4f4fc1 --- /dev/null +++ b/doc/sonic-application-extention/img/upgrade-flow.svg @@ -0,0 +1,677 @@ + + + + + + + + + + + + + + + + + + + + + + + + Сторінка 1 + + + + + + + + + Лінія проекту + Package Manager + + Аркуш.2 + + + + Аркуш.3 + + + + Аркуш.4 + + + Аркуш.5 + + + + + + + Package Manager + + + + + + + + Лінія проекту.12 + dockerd + + Аркуш.7 + + + + Аркуш.8 + + + + Аркуш.9 + + + Аркуш.10 + + + + + + + dockerd + + + + + + + + Лінія проекту.17 + Docker Registry + + Аркуш.12 + + + + Аркуш.13 + + + + Аркуш.14 + + + Аркуш.15 + + + + + + + Docker Registry + + + + + + + + Лінія проекту.22 + systemd + + Аркуш.17 + + + + Аркуш.18 + + + + Аркуш.19 + + + Аркуш.20 + + + + + + + systemd + + + + + + + + Лінія проекту.27 + Host OS FS + + Аркуш.22 + + + + Аркуш.23 + + + + Аркуш.24 + + + Аркуш.25 + + + + + + + Host OS FS + + + + + + + + Лінія суб’єкта + User + + Аркуш.27 + + + + Аркуш.28 + + + + Аркуш.29 + + + Аркуш.30 + + + + + + + User + + + Повідомлення + install <package> + + + + + + + + + + + install <package> + + Повідомлення.32 + docker pull <repo>:<tag> + + + + + + + + + + + docker pull <repo>:<tag> + + Повідомлення.45 + pull + + + + + + + + + + + pull + + Повернуто повідомлення + return + + + + + + + + + + + return + + Повернуто повідомлення.35 + return + + + + + + + + + + + return + + Повідомлення.53 + docker run <repo>:<tag> sleep + + + + + + + + + + + docker run <repo>:<tag> sleep + + Повернуто повідомлення.54 + + + + + + + + + + Повідомлення.44 + render host scripts/files to host FS /tmp/<feature>_upgrade/ + + + + + + + + + + + render host scripts/files to host FS /tmp/<feature>_upgrade/ + + Повернуто повідомлення.45 + return + + + + + + + + + + + return + + Повідомлення.61 + systemctl stop <feature> + + + + + + + + + + + systemctl stop <feature> + + Повернуто повідомлення.62 + return + + + + + + + + + + + return + + Повернуто повідомлення.63 + return + + + + + + + + + + + return + + Активація + + + + + + + Активація.65 + + + + + + + Активація.51 + + + + + + + Активація.67 + + + + + + + Активація.69 + + + + + + + Активація.72 + + + + + + + Активація.73 + + + + + + + Повідомлення.74 + systemctl start <feature> + + + + + + + + + + + systemctl start <feature> + + Повернуто повідомлення.75 + return + + + + + + + + + + + return + + Активація.76 + + + + + + + Повідомлення на себе + Check package dependencies/conflicts + + + + + + + + + + + Check package dependencies/conflicts + + Повідомлення на себе.78 + Update installation status/version in DB + + + + + + + + + + + Update installation status/version in DB + + Повідомлення.79 + move /tmp/<feature>_upgrade/ to / reload host services config... + + + + + + + + + + + move /tmp/<feature>_upgrade/ to /reload host services configuration + + Повернуто повідомлення.80 + return + + + + + + + + + + + return + + Активація.82 + + + + + + + + + + Інший фрагмент.152 + + + + + Аркуш.69 + alt + + + + + + + + + + + + + + + alt + + Аркуш.70 + requirements are met + + + + + + requirements aremet + + + Повідомлення.50 + docker tag <repo>:<tag>\ <repo>:latest + + + + + + + + + + + docker tag <repo>:<tag>\ <repo>:latest + + Повернуто повідомлення.52 + + + + + + + + + + Активація.68 + + + + + + + Повідомлення.140 + docker rmi -f <repo>:<old-tag> + + + + + + + + + + + docker rmi -f <repo>:<old-tag> + + Повернуто повідомлення.142 + + + + + + + + + + Активація.144 + + + + + + + Повідомлення.89 + get docker image labels (com.azure.sonic.manifest) + + + + + + + + + + + get docker image labels (com.azure.sonic.manifest) + + Повернуто повідомлення.92 + return + + + + + + + + + + + return + + Активація.94 + + + + + + + diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md new file mode 100644 index 00000000000..50dbfb10eb9 --- /dev/null +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -0,0 +1,1510 @@ + +# SONiC Application Extension Infrastructure + + +#### Rev 0.1 + + +## Table of Content +- [Revision](#revision) +- [Scope](#scope) +- [Definitions/Abbreviations](#definitionsabbreviations) +- [Overview](#overview) +- [Requirements](#requirements) +- [Architecture Design](#architecture-design) +- [High-Level Design](#high-level-design) +- [SONiC Package](#sonic-package) +- [Built-In SONiC Packages](#built-in-sonic-packages) +- [SONiC Package Management](#sonic-package-management) +- [SONiC Package Database](#sonic-package-database) +- [SONiC Build System](#sonic-build-system) +- [SONiC Base Image and Packages Versioning](#sonic-base-image-and-packages-versioning) +- [SONiC Application Extension Security Considerations](#sonic-application-extension-security-considerations) +- [Configuration and management](#configuration-and-management) +- [SONiC Package Upgrade Flow](#sonic-package-upgrade-flow) +- [Manifest](#manifest) +- [SONiC Package Installation](#sonic-package-installation) +- [SONiC Package Changelog](#sonic-package-changelog) +- [SONiC Docker Container Resource Restrictions](#sonic-docker-container-resource-restrictions) +- [SONiC Package Docker Container Lifetime](#sonic-package-docker-container-lifetime) +- [Initial Extension Configuration](#initial-extension-configuration) +- [CLI extension](#cli-extension) +- [SONiC Processes and Docker Statistics Telemetry Support](#sonic-processes-and-docker-statistics-telemetry-support) +- [Feature Concept Integration](#feature-concept-integration) +- [Multi-DB support](#multi-db-support) +- [Configuration Reload](#configuration-reload) +- [System Dump](#system-dump) +- [Multi-ASIC](#multi-asic) +- [Warmboot and Fastboot Design Impact](#warmboot-and-fastboot-design-impact) +- [SONiC-2-SONiC upgrade](#sonic-2-sonic-upgrade) +- [Kubernetes & SONiC Application Extension](#kubernetes--sonic-application-extension) +- [3rd party Docker images](#3rd-party-docker-images) +- [Installing 3rd party image as is.](#installing-3rd-party-image-as-is) +- [Prepare 3rd party image as to be SONiC compliant](#prepare-3rd-party-image-as-to-be-sonic-compliant) +- [SONiC Build System](#sonic-build-system-1) + - [SONiC SDK Docker Images](#sonic-sdk-docker-images) +- [SAI API](#sai-api) +- [Restrictions/Limitations](#restrictionslimitations) +- [Testing Requirements/Design](#testing-requirementsdesign) +- [Open/Action items](#openaction-items) + + +## List of Figures +- [Figure 1. Basic Concepts](#figure-1-basic-concepts) +- [Figure 2. High Level Overview of SONiC Package integration](#figure-2-high-level-overview-of-sonic-package-integration) +- [Figure 3. SONiC Package Installation Flow](#figure-3-sonic-package-installation-flow) +- [Figure 4. SONiC Package Uninstallation Flow](#figure-4-sonic-package-uninstallation-flow) +- [Figure 5. SONiC Package Upgrade Flow](#figure-5-sonic-package-upgrade-flow) +- [Figure 6. Feature Start Sequence Diagram](#figure-6-feature-start-sequence-diagram) +- [Figure 7. Feature Stop Sequence Diagram](#figure-7-feature-stop-sequence-diagram) + +### Revision + +| Rev | Date | Author | Change Description | +| :---: | :-----: | :--------------: | ------------------ | +| 0.1 | 09/2020 | Stepan Blyshchak | Phase 1 Design | + +### Scope + +This document describes the high level design of SONiC Application Extension Infrastructure. + +### Definitions/Abbreviations + +| **Abbreviation** | **Definition** | +| ---------------- | ------------------------------------- | +| SONiC | Software for Open Networking in Cloud | +| DB | Database | +| API | Application Programming Interface | +| SAI | Switch Abstraction Interface | +| YANG | Yet Another Next Generation | +| JSON | Java Script Object Notation | +| XML | eXtensible Markup Language | +| gNMI | gRPC Network Management Interface | + +### Overview + + +#### Feature Overview + +SONiC Application Extension Infrastructure is a SONiC infrastructure and framework for managing SONiC Application Packages which in this scope are +SONiC compatible Docker images distributed individually from one another and from the base SONiC image. + + +#### Motivation + +SONiC NOS was built with extendability in mind. The key role here play the fact that the main building block of SONiC is Docker. +Every SONiC functionality piece is packaged inside a Docker image which then is run on a SONiC box. As of today, SONiC comes with a set +of Docker containers that are built-in into SONiC image, limiting users to a predefined functionality that is supported by SONiC. +The end goal of this proposal is to achieve building a system which makes it possible to extend SONiC base set of features at runtime +without a need to upgrade the whole SONiC OS. + +We are going to leverage the existing Docker and Docker registry infrastructure and build SONiC Application Extension framework on top of it. +While Docker provides a tool for packaging an application and Docker registry for hosting it, it is not enough to just execute "docker pull" +to make an application "look and feel" like a native SONiC application. + +SONiC Application Extension framework aims at making the process of development and integration of 3-rd party applications with a native +integration into SONiC. For that we need to provide SONiC Application Extension Infrastructure with the API to connect every 3rd party application +with SONiC native infrastructure, like access to the database, SAI ASIC programming interface, sonic utility CLI, Klish based CLI, REST API, +gNMI, logging infrastructure, warm and fast restarts, etc. + +When SONiC Application Extension infrastructure will become a part of SONiC, application developer will not have to integrate every application +into SONiC codebase but maintain them separately. This follows all the popular Linux distributions that allow for installation of external applications. + +### Requirements + + +#### Functional requirements + +This section describes a list of requirements for both SONiC Application Extension Infrastructure. + +The following list of requirements has to be met for SONiC Application Extension Infrastructure: +- SONiC OS must provide a CLI to manage SONiC repositories and packages. + This includes package installation, un-installation, + both cold and warm upgrades as well as adding and removing repositories. +- Definition for a SONiC compatible Docker image and metadata a this Docker image must provide. +- Versioning schema and a mechanism to control package dependencies and conflicts. +- All SONiC packages are registered as an optional *feature* in SONiC, thus "feature" + CLI commands are applicable to SONiC Packages. +- Application upgrades: container level upgrade and system level upgrade - SONiC-2-SONiC upgrade. +- SONiC utilities CLI extension mechanism. +- Resource sharing with SONiC Package container: redis database, syslog, Linux resources etc. +- Build infrastructure and tools for easier package development. + +### Architecture Design + +This section covers the changes that are required in the SONiC architecture. In general, it is expected that the current architecture is not changed. +This section should explain how the new feature/enhancement (module/sub-module) fits in the existing architecture. + +### High-Level Design + + +### Basic concepts + +Basic definitions: + +*SONiC Package* - SONiC compatible Docker image providing its functionality as a service
+*SONiC Package Repository* - store of SONiC compatible Docker images that can be referenced by a tag
+*Docker Registry* - a storage and content delivery system, holding named Docker images, available in different tagged versions + + +###### Figure 1. Basic Concepts + +

+Figure 1. Basic Concepts +

+ +There are three notions: *package*, *repository* and *registry*. A repository is a Docker registry (private or open like Docker Hub) +repository with tagged images for specific package. + +In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are repositories with a set of images. + +### SONiC Package + +SONiC Packages must meet few requirements in order to be a SONiC compatible Docker image. + +- A package must provide a manifest as part of the Docker image. +- Requirement on the container state recording by [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)). + + +###### Figure 2. High Level Overview of SONiC Package integration + +

+Figure 2. High Level Overview of SONiC Package integration +

+ +The idea is to auto-generate most of the components on the host OS based on *manifest* provided by SONiC Package. + +### Built-In SONiC Packages + +Every SONiC Docker image can be a SONiC Package, although a subset of SONiC Dockers will be made with format of SONiC Package at first phase. +These are Dockers for which it might be complicated to separate the OS part from the Docker image itself. Those Docker images are considered as built-in Docker images. +Built-in packages **cannot** be *removed* and *upgraded* as SONiC Packages and the infrastructure will mark them with a special built-in flag. + +This will allow for a smooth transition of SONiC Docker images into SONiC Packages by marking all of the existing Docker images as +build-in and then removing this flag for images that become a SONiC Packages. + +The following list enumerates some built-in Docker containers, that cannot become SONiC Package at current stage: +- database +- syncd +- swss +- pmon + +For those packages it might be a challenge to support installation, un-installation and upgrade using SONiC Application Extension framework. +E.g. syncd contains vendor SDK which usually means there is a kernel driver installed on the host OS. Upgrading just the syncd may become +challenging because of a need to upgrade kernel driver on the host. Same is for the pmon Docker, swss and database - they are tightly integrated +into base OS. + +**NOTE**: For phase 1 dhcp-relay is chosen to be the first feature that will become a SONiC Package. + +### SONiC Package Management + +As any mature OS distribution SONiC will use its own package management solution and provide a utility to manage packages. +SONiC Package Manager will use a persistent storage for its purposes at */var/lib/sonic-packages/* on the host OS. +There is a *packages.json* file representing local database of packages. + +``` +/ + var/ + lib/ + sonic-packages/ + packages.json +``` + +###### Example directory structure of SONiC Package Manager library + +A locking mechanism will be used in order to make a package operation (installation, de-installation, upgrades) atomic. +For this a lock file */var/lib/sonic-packages/.lock* will be created on every operation and released once operation is completed +to guaranty that the database won't become broken if two write operations are performed at the same time. + +### SONiC Package Database + +The */var/lib/sonic-packages/packages.json* file is used as a persistent database of available SONiC packages. +Schema definition for *packages.json* file is following: + +| Path | Type | Description | +| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| /name | string | Name of the package. | +| /name/repository | string | Repository in Docker registry. Default source of image for installation/upgrade. | +| /name/description | string | Application description field. | +| /name/default-reference | string | A tag or digest of Docker image that will be a default installation candidate. | +| /name/built-in | boolean | A flag to indicate that a Docker is a built-in package. | +| /name/status | string | Status indicate the installation status of the package. It is either "installed" or "not-installed". | +| /name/installed-version | string | Installed version string. This version follows semantic versioning described in later section. | +| /name/image-id | string | Docker image ID of the installed Package, *null* if package is not installed or built-in (was not installed using sonic-package-manager). | + + +A sample of the content in JSON format: + +```json +{ + "database": { + "repository": "docker-database", + "description": "SONiC database service", + "built-in": true, + "default-reference": "1.0.0", + "status": "installed", + "installed-version": "1.0.0" + }, + "swss": { + "repository": "docker-orchagent", + "description": "SONiC switch state service", + "built-in": true, + "default-reference": "1.0.0", + "status": "installed", + "installed-version": "1.0.0" + }, + "dhcp-relay": { + "repository": "Azure/sonic-dhcp-relay", + "description": "DHCP relay feature", + "default-reference": "sha256:5d41c289942008211c2964bca72800f5c9d5ea5aa4057528da617fb36463d4ab", + "status": "not-installed" + }, + "snmp": { + "repository": "Azure/sonic-snmp", + "description": "Simple Network Monitoring Protocol", + "default-reference": "1.0.0", + "status": "installed", + "installed-version": "1.0.0", + "image_id": "e269735173d5" + } +} +``` + +The initial *packages.json* that comes with SONiC image is auto-generated at build time. The *packages.json* will include every +SONiC package installed at built time and have the installation status set. Besides of the packages that were built-in to SONiC +OS at built time the *packages.json* also includes the repositories that are available for users to install. E.g. a DHCP relay +feature may not come with SONiC by default, but the user will have a corresponding entry for DHCP relay package in *packages.json* +which user can install. + +Community can extend *packages.json* with own developed packages. The recommended way of defining a 'default-reference' is by +specifying a digest rather then a tag, so that a package entry points strictly to a specific image. + + +### SONiC Build System + +1. Install packages at built time. + +Build-system users will have an ability to specify packages they would like to add to database or add and install. + +rules/sonic-packages.mk: +```makefile +# rules to define remote packages that need to be installed +# during SONiC image build + +## Example: +PACKAGE = my-package +$(PACKAGE)_REPOSITORY = myrepo/mypackage +$(PACKAGE)_VERSION = 1.0.0 +$(PACKAGE)_INSTALL = y # whether to install or not + +# Add package to target group +SONIC_PACKAGES += $(PACKAGE) +``` + +2. SONiC Docker compilation option + +For SONiC Package within sonic-buildimage an option to include the package will be exposed to the user: + +rules/config: +```makefile +INCLUDE_$(PACKAGE)=y +``` + +If this option is set to **y** the corresponding Docker image will be built and installed from image tarball +placed under target/ folder. + +### SONiC Base Image and Packages Versioning + +Most of the SONiC Packages will depend on SONiC base OS API and on other SONiC packages API. Every mature package management solution provides +a set of agreements on how packages versioning should be done to avoid potential incompatibilities. + +This documents proposes to use [semantic versioning](https://semver.org/) which is used for many package management solutions. + +The schema for version is in the format of *\${MAJOR}.\${MINOR}.\${PATCH}* version. Semantic versioning can also include a suffix for pre-release +identifiers and build id, like *1.0.0-dev+153*, that can be used for master branch builds. Such a schema allows for a simple logic for comparison, +e.g: *1.0.0 < 1.1.0* and *1.5.1 > 1.4.20*. For more details of comparison rules follow the reference above. + +The version number is defined as part of the SONiC package manifest. Package maintainers must follow the above versioning approach and are encouraged +to follow a commonly used convention in Docker by tagging images with a version number [See next section]. + +The base OS components (libswsscommon, sonic-utilities, etc.) has also a version number that follows the same rules of semantic versioning so that a package can define a dependency on base OS component version. These versions are recorder in */etc/sonic/sonic_version.yml*. This versions are in addition to SONiC version we have today. + +For SONiC containers available in *sonic-buildimage* repository the corresponding makefile is modified to include a version string: + +rules/docker-dhcp-relay.mk +```makefile +$(DOCKER_DHCP_RELAY)_VERSION = 1.0.0 +``` + +This version is used to tag a Docker image when installing SONiC package in SONiC OS at build-time or publishing SONiC package. + +The versioning of the package is a responsibility of the package maintainer. The exact rules of how the versioning is done when +branching, publishing new images is out of the scope of this document. + + +#### Docker tag to semantic version string conversion and vice versa + + +Whenever user asks to install a version X the sonic-package-manager is converting X to a tag compliant string. +If version X does not use the *buildmetadata* there are no issues using version X string as a tag, if it does +the version string cannot be used as a tag because of tag string limitations, in particular the '+' sign used +to separate *buildmetadata* from the rest of the version string is not allowed to be present in Docker tag +string. + +The proposed conversion is suggested by this document is to replace a '+' with a '_', which is not allowed to +be used in semver: + +``` +tag_string = semver_string.replace('+', '_') +``` + +For the following version '1.0.5-rc0+152' the Docker tag would be '1.0.5-rc0_152'. + +### SONiC Application Extension Security Considerations + +There are a lots of aspects about security when it comes to running arbitrary SONiC packages on SONiC. +Making sure the container is restricted to do only what it is supposed to is a complex functionality peace here. +Security considerations of Phase 1 of Application Extension feature stand on an assumptions that 3rd party Dockers +are secured and trusted. + +- 3rd party package developer must add an entry in sonic-buildimage repository in packages.json.j2 template file. + The community tests and verifies the package and only those packages which are trusted are added to the template. +- If user manually adds an entry to *packages.json* file, it is user's responsibility to verify and check the package + that user is trying to install. + +The SONiC Application Extension Framework may leverage Docker Content Trust feature which allows to pull only signed +images. A set of trusted public keys may come as a default with SONiC image as well as user may add their own +public keys. Using those public keys and a signature in Docker image docker validates the signature of the image. +This way the user can ensure the integrity and the publisher of the image he is trying to install. + +[Docker Content Trust](https://docs.docker.com/engine/security/trust/) + +### Configuration and management + + +#### CLI Enhancements + +The SONiC Package Manager is another executable utility available in base SONiC OS called *sonic-package-manager* or abbreviated to *spm*. +The command line interfaces are given bellow: + + +#### CLI + +``` +admin@sonic:~$ sonic-package-manager +Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... + + SONiC Package Manager. + +Options: + --help Show this message and exit. + +Commands: + install Install SONiC package + list List available packages + migrate Migrate SONiC packages from database file + repository Repository management commands + show SONiC Package Manager show commands + uninstall Uninstall SONiC package + upgrade Upgrade SONiC package +``` + +``` +admin@sonic:~$ sonic-package-manager show package +Usage: sonic-package-manager show package [OPTIONS] COMMAND [ARGS]... + + Package show CLI commands. + +Options: + --help Show this message and exit. + +Commands: + changelog Print the package changelog + manifest Print the manifest content + versions Print available versions +``` + + +#### List of packages available +``` +admin@sonic:~$ sonic-package-manager list +Name Repository Description Version Status +----------- --------------------- ------------------------ ------------ -------------- +database docker-database SONiC database 1.0.0 Built-In +swss docker-orchagent Switch state service 1.0.0 Built-In +syncd docker-syncd-vs SONiC ASIC sync service 1.0.0 Built-In +cpu-report Azure/cpu-report CPU time report feature 1.0.5 Installed +dhcp-relay Azure/dhcp-relay DHCP relay service N/A Not installed +``` + + +#### Repository management + +``` +admin@sonic:~$ sudo sonic-package-manager add [NAME] [REPOSITORY] --default-reference=[STRING] +admin@sonic:~$ sudo sonic-package-manager remove [NAME] +``` + + +#### Package Installation + +``` +admin@sonic:~$ sudo sonic-package-manager install --help + +Usage: sonic-package-manager install [OPTIONS] [PACKAGE_EXPR] + + Install SONiC package. + +Options: + -y, --yes Answer yes for any prompt + -f, --force Force installation + --enable Wether to enable feature after install + --default-owner [local|kube] Default configured owner + --from-repository Install directly from repository specified + in this options. Format is the same as for + "docker pull" command: NAME[:TAG|@DIGEST]. + Mutually exclusive with PACKAGE_EXPR and + --from-tarball + --from-tarball Install from tarball. Mutually exclusive with + PACKAGE_EXPR and --from-repository + --skip-cli-plugin-installation Do not install CLI plugins provided by the + package on the host OS + Note: In case package CLI is defined as mandatory + and this option is beeing used the installation + will fail. + --help Show this message and exit +``` + + +###### Examples + +``` +admin@sonic:~$ sudo sonic-package-manager install cpu-report +``` + +Install a specific tag: +``` +admin@sonic:~$ sudo sonic-package-manager install cpu-report==1.0.0 +``` + +Optionally specifying a version after package name separated by a '==' in CLI allows user to install any version of extension. + +Installing using a tag/version is a convenient methods to install packages for users. The downside of using tag as an image reference +is the fact that a tag is mutable reference. Thus, an image tag might not point to the same image at any given time. Docker provides +a digest (content-addressable identifier) as immutable reference. In case users download from Docker Hub rather then from trusted repository +they might want to use a digest instead for their installations. + +Install using a digest: + +``` +admin@sonic:~$ sudo sonic-package-manager install cpu-report@sha256:8273733f491f362bb36710fd8a99f78c3fbaecd8d09333985c76f1064b80760f +``` + +For developer convenience or for unpublished SONiC packages,it is possible to install the extension from a Docker image tarball. + +``` +admin@sonic:~$ ls featureA.gz +featureA.gz +admin@sonic:~$ sudo sonic-package-manager install --from-tarball featureA.gz +``` + +This option should mainly be used for debugging, developing purpose, while the preferred way will be to pull the image from repository. +Package Database is updated with a "repository" field set to local image repository. +In the above example the following entry is added to *packages.json*: + +```json +{ + "featureA": { + "repository": "featureA", + "installed-version": "1.0.0", + "status": "installed", + "image_id": "9ab631f37d1d" + } +} +``` + +An option to skip all dependency checks and force the installation: + +``` +admin@sonic:~$ sudo sonic-package-manager install --force feature +WARN: feature depends on syncd^1.1.1 while installed version is 1.0.5. Ignoring. +``` + +*show version* command can be used to display feature docker image version. + + +#### Package Upgrade + +``` +admin@sonic:~$ sudo sonic-package-manager upgrade --help + +Usage: sonic-package-manager upgrade [OPTIONS] [PACKAGE_EXPR] + + Upgrade SONiC package + +Options: + -y, --yes Answer yes for any prompt. + -f, --force Force upgrade. + --from-repository Install directly from repository specified + in this options. Format is the same as for + "docker pull" command: NAME[:TAG|@DIGEST]. + Mutually exclusive with PACKAGE_EXPR and + --from-tarball + --from-tarball Install from tarball. Mutually exclusive with + PACKAGE_EXPR and --from-repository + --help Show this message and exit +``` + + +###### Examples + +The command line example for package upgrade: +``` +admin@sonic:~$ sudo sonic-package-manager upgrade ==1.5.1 +``` + +The the new package is downloaded and installed, the package service is stopped and restarted, an old Docker image is removed. + +For a feature that supports warm upgrade: +``` +admin@sonic:~$ sudo config warm-restart enable +admin@sonic:~$ sudo sonic-package-manager upgrade ===1.5.1 +``` + +*NOTE*: SONiC already supports docker containers warm upgrade to some extent by sonic-installer utility's "upgrade-docker" sub-command. +This command will be deprecated and replaced by "sonic-package-manager" functionality. + + +#### Config DB Enhancements + +No CONFIG DB changes required for this feature. + + +###### Figure 3. SONiC Package Installation Flow + +

+Figure 3. SONiC Package Installation Flow +

+ + +### SONiC Package Uninstallation Flow + + +###### Figure 4. SONiC Package Uninstallation Flow + +

+Figure 4. SONiC Package Uninstallation Flow +

+ +### SONiC Package Upgrade Flow + +The upgrade scenario is different from sequential uninstall and install operations. In order to minimize service downtime, +the image pulling and templates rendering has to be done while the old container is running. Also, it might be that the old +container auto-generated container management scripts are incompatible with the new one and vice verse. So we need to stop +the old container using old auto-generated service file and container management scripts, then replace the old scripts with +new one and start the service. The sequence is shown on the figure below: + + +###### Figure 5. SONiC Package Upgrade Flow + +

+Figure 5. SONiC Package Upgrade Flow +

+ +### Manifest + +Every SONiC Package that is not a built-in package must provide a *manifest*. *manifest* is a set of Docker image labels which describe +the package and instruct SONiC how this package integrates in the system. + +Image labeling is a standard Docker way to add metadata information to the image. Besides, a label can be queried using Docker Registry API +without the need to download the whole image. + + +###### Manifest Base +``` +com.azure.sonic.manifest +``` + +The value should contain a JSON serialized as a string. + +The following table shows the top-level objects in the manifest. In the next sections it is described all the fields that are relevant. + +| Path | Type | Mandatory | Description | +| ---------- | ------ | --------- | ------------------------------------------------------------------------------------------------ | +| /version | string | no | Version of manifest schema definition. Defaults to 1.0.0. | +| /package | object | no | Package related metadata information. | +| /service | object | yes | Service management related properties. | +| /container | object | no | Container related properties. | +| /processes | list | no | A list defining processes running inside the container. | +| /cli | object | no | CLI plugin information. *NOTE*: Later will deprecated and replaced with a YANG module file path. | + + +A required "version" field can be used in case the format of manifest.json is changed in the future. +In this case a migration script can be applied to convert format to the recent version. +This is similar to approach SONiC uses for CONFIG DB version. + + +### SONiC Package Installation + + +An installation process has to verify all requirements are met. First check to perform is a SONiC base image version match. +The package manager has to build the dependency tree and verify all dependent packages are installed version requirements +are met and the package that is about to be installed does not break any other package or any installed package does not +break the package that is going to be installed. + +The package manager currently won't try to install missing packages or resolve dependency conflicts but give the user an +appropriate error message. + +*NOTE*: SONiC package manager does not maintain two different versions at the same time. So, only single version of the package +can be installed at any given time. + + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ----------------------------------- | ------ | --------- | ------------------------------------------------------------------------------ | +| /package/version | string | yes | Version of the package. | +| /package/name | string | yes | Name of the package. | +| /package/description | string | no | Description of the package. | +| /package/depends | list | no | List of SONiC packages the service depends on. Defaults to [] | +| /package/depends[index]/name | string | yes | Name of SONiC Package | +| /package/depends[index]/version | string | no | Version constraint expression string | +| /package/depends/[index]/components | object | no | Per component version | +| /package/breaks | list | no | List of SONiC package the service breaks with. Defaults to [] | +| /package/breaks[index]/name | string | yes | Name of SONiC Package | +| /package/breaks[index]/version | string | no | Version constraint expression string | +| /package/breaks/[index]/components | object | no | Per component version | + +Base OS component version checking: + + +###### manifest path + +| Path | Type | Mandatory | Description | +| --------------------------------- | --------- | --------- | ----------------------------- | +| /package/base-os/ | object | no | Base OS versions constraints | +| /package/base-os/[index]/name | strnig | yes | Base OS component name | +| /package/base-os/[index]/version | string | yes | Base OS component version | + + +Each SONiC Package can have a list of labels representing components versions: + +``` +LABEL com.azure.sonic.versions.libswsscommon = 1.0.0 +LABEL com.azure.sonic.versions.libsairedis = 1.0.0 +``` + +Labels are inherited from the base image, so versions of common libraries are recorded in SONiC Package that uses SONiC SDK docker. SONiC SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). + +Version constraints should have the following format: + +``` +[>|>=|==|<|<=|^|!|!=] +``` + +Example: + +```json +{ + "package": { + "base-os": { + "libswsscommon": ">1.0.0" + } + } +} +``` + + +*depends*, *breaks* version constraint fields are defined to be in the following format: + +``` +[>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... +``` + +Examples: + +```json +{ + "package": { + "depends": [ + { + "name": "swss", + "version": ">=1.0.0,!=1.2.2,<=3.0.0", + "components": { + "libswsscommon": "^1.0.0,^2.0.0" + } + } + ] + } +} +``` + +or + +```json +{ + "package": { + "breaks": [ + { + "name": "syncd", + "version": "^1.0.0" + } + ] + } +} +``` + +For the list of supported expressions check the python library that is going to be used by package manager - https://github.com/python-poetry/semver. + + +#### Automatic compatibility check + +SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). + +SDK Docker image records an set of library versions in labels that gets inherited by the package image. This allows to perform an +automatic compatibility check. If libraries constarints are not defined in the manifest but a library version exists in labels of a package the constraint will initialize for that component as "^$major.$minor.0". E.g: + +Package Foo is build with following labels: + +``` +LABEL com.azure.sonic.versions.libswsscommon = 1.2.0 +LABEL com.azure.sonic.versions.libsairedis = 1.3.0 +``` + +```json +{ + "package": { + "depends": [ + { + "name": "Bar", + "version": ">=1.0.0,!=1.2.2,<=3.0.0", + "components": { + "libswsscommon": "^1.0.0,^2.0.0" + } + } + ] + } +} +``` + +libswsscommon is validated against "^1.0.0,^2.0.0", libsairedis is validated using "^1.3.0". +This gives more guaranties to the user that if package installs it is compatible. +If pacakge does not use sairedis interface, user can put "*" to match any version in Bar. + + +### SONiC Package Changelog + + +###### Manifest path + +| Path | Type | Mandatory | Description | +| -------------------------------------- | --------------- | --------- | --------------------------------------- | +| /package/changelog | dict | no | Changelog dictionary. | +| /package/changelog/\ | dict | yes | Package version. | +| /package/changelog/\/changes | list of strings | yes | Changelog messages for a given version. | +| /package/changelog/\/author | string | yes | Author name. | +| /package/changelog/\/email | string | yes | Author's email address. | +| /package/changelog/\/date | string | yes | Date and time in RFC 2822 format. | + +Example: + +```json +{ + "package": { + "changelog": { + "1.0.0": { + "changes": ["Initial release"], + "author": "Stepan Blyshchak", + "email": "stepanb@nvidia.com", + "date": "Mon, 25 May 2020 12:24:30 +0300" + }, + "1.1.0": { + "changes": [ + "Added functionality", + "Bug fixes" + ], + "author": "Stepan Blyshchak", + "email": "stepanb@nvidia.com", + "date": "Fri, 23 Oct 2020 12:26:08 +0300" + } + } + } +} +``` + +This information will be useful for user, so a command to show changelog for a package is added: + + +``` +admin@sonic:~$ sonic-package-manager show package changelog +1.0.0: + + * Initial release + +-- Stepan Blyshchak Mon, 25 May 2020 12:24:30 +0300 + +1.1.0 + + * Added functionality + * Buf fixes + +-- Stepan Blyshchak Fri, 23 Oct 2020 12:26:08 +0300 + +``` + +### SONiC Docker Container Resource Restrictions + +This feature will allow user to specify resource restrictions for a container via FEATURE table in CONFIG DB. +This feature is not related to SONiC Application Extension Design, as can be applied to any existing SONiC +container with existing infrastructure. Every SONiC Package will automatically support this feature. + +**TODO**: Put a reference to the design doc of this feature when it becomes available. + +### SONiC Package Docker Container Lifetime + +Container lifetime in SONiC is currently controlled by systemd. The current SONiC design for container management consists of a +service unit, a container management script */usr/bin/\.sh* and optionally */usr/local/bin/\.sh*.Those two +scripts and a service unit file will be auto-generated during SONiC Package installation. The information needed for them to be +auto-generated is defined in the manifest of a package. + +The relation between those scripts is shown in the below two figures in high level: + + +#### Feature Start Sequence Diagram + + + +###### Figure 6. Feature Start Sequence Diagram + +

+Figure 6. Feature Start Sequence Diagram +

+ + + +#### Feature Stop Sequence Diagram + + + +###### Figure 7. Feature Stop Sequence Diagram + +

+Figure 7. Feature Stop Sequence Diagram +

+ + +##### *feature*.service + +The service unit file defines a dependency relation between different units and start/stop ordering between them. +The template for creating service files will be placed at */usr/share/sonic/templates/service.j2*. The manifest fed +through this template outputs a systemd service file with all the unit properties set according to the package's +manifest. + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ------------------ | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| /service/name | string | yes | Name of the service. There could be two packages e.g: fpm-quagga, fpm-frr but the service name is the same "bgp". For such cases each one have to declare the other service in "conflicts". | +| /service/requires | list of strings | no | List of SONiC services the application requires.

The option maps to systemd's unit "Requires=". | +| /service/requisite | list of strings | no | List of SONiC services that are requisite for this package.

The option maps to systemd's unit "Requisite=". | +| /service/wanted-by | list of strings | no | List of SONiC services that wants for this package.

The option maps to systemd's unit "WantedBy=". | +| /service/after | list of strings | no | Boot order dependency. List of SONiC services the application is set to start after on system boot. | +| /service/before | list of strings | no | Boot order dependency. List of SONiC services the application is set to start before on system boot. | +| /service/wanted-by | list of strings | no | Services list that "wants" this service. Maps to systemd's WantedBy | +| /service/delayed | boolean | no | Wether to generate a timer to delay the service on boot. Defaults to false. | + + + +##### /usr/local/bin/*feature*.sh + +The script under */usr/local/bin/* has two feature specific use cases. + +* In case when the feature requires to execute specific container lifecycle actions the code to be executed after the container +has started and before the container is going down is executed within this script. SONiC package manifest includes two data +nodes - */service/post-start-action* and */service/pre-shutdown-action*. This node is of type string and the value is the path +to an executable to execute within Docker container. Note, *post-start-action* does not guaranty that the action will be executed +before or after a the container ENTRYPOINT is started. + +Example of container lifecycle hook can apply to a database package. A database systemd service should not reach started state +before redis process is ready otherwise other services will start but fail to connect to the database. Since, there is no control +when the redis process starts a *post-start-action* script may execute "sonic-db-cli ping" till the ping is succeessful. +This will ensure that service start is blocked till the redis service is up and running. + +The *pre-shutdown-action* might be usefull to execute a specific action to prepare for warm reboot. For example, teamd script that sends +SIGUSR1 to teamd to initiate warm shutdown. Note, the usage of the pre-shutdown action is not limited to warm restart and is invoked every +time the container is about to be stopped or killed. + +* Another use cases is to manage coldboot-only dependent services by conditionally starting and stopping dependent services based on the +warm reboot configuration flag. For example, a DHCP relay service is a coldboot-only dependent service of swss service, thus a warm restart +of swss should not restart DHCP relay, on the other hand a cold restart of swss must restart DHCP relay service. This is controlled by +a node in manifest */service/dependent-of*. The DHCP relay package will have "swss" listed on the *dependent-of* list which will instruct +auto-generation process to include the DHCP relay service in the list of dependent services in *swss*. This means *swss.sh* script has to +be auto-generated as well. To avoid re-generating *swss.sh* script we will put dependent services in a separate file what *swss.sh* can read. +The file path is chosen to be */etc/sonic/\_dependent* for single instance services and +*/etc/sonic/\_dependent_multi_inst_dependent* for multi instance services. + +Example of required code change for swss is given below [swss.sh](https://github.com/Azure/sonic-buildimage/blob/master/files/scripts/swss.sh): + +```bash +DEPENDENT="radv dhcp_relay" +MULTI_INST_DEPENDENT="teamd" +``` + +``` +DEPDENDENT=$(cat /etc/sonic/${SERVICE}_dependent) +MULTI_INST_DEPENDENT=$(cat /etc/sonic/${SERVICE}_multi_inst_dependent) +``` + +The infrastructure is not deciding whether this script is needed for a particular package or not based on warm-reboot requirements or +container lifetime hooks provided by a feature, instead this script is always generated and if no specific actions descirbed above +are needed it becomes a simple wrapper around a script under /usr/bin/. + +Examples are [swss.sh](https://github.com/Azure/sonic-buildimage/blob/master/files/scripts/swss.sh), +[syncd.sh](https://github.com/Azure/sonic-buildimage/blob/master/files/scripts/syncd.sh), +[bgp.sh](https://github.com/Azure/sonic-buildimage/blob/master/files/scripts/bgp.sh). These scripts +share a good amount of code, thus making it possible to templatize into a single script that can be parametrized +during generation according to feature needs - place lifecycle action hooks and dependent service management. + +Every service that the starting service requires should be started as well and stopped when a service is stopped but only if a service +is doing a cold start. This means when a new package is installed it might affect the other scripts. So after all dependencies are known +after installation all the service scripts under */usr/local/bin/* are re-generated. + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ---------------------------- | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| /service/dependent-of | lits of strnigs | no | List of SONiC services this application is dependent of.

Specifying in this option a service X, will regenerate the /usr/local/bin/X.sh script and upgrade the "DEPENDENT" list with this package service.

This option is warm-restart related, a warm-restart of service X will not trigger this package service restart.

On the other hand, this service package will be started, stopped, restarted togather with service X.

Example:

For "dhcp-relay", "radv", "teamd" this field will have "swss" service in the list. | +| /service/post-start-action | string | no | Path to an executable inside Docker image filesystem to be executed after container start.

A package may use this field in case a systemd service should not reach started state before some condition. E.g.: A database service should not reach started state before redis process is not ready. Since, there is no control, when the redis process will start a "post-start-action" script may execute "redis-cli ping" till the ping is succeessful. | +| /service/pre-shutdown-action | string | no | Path to an executable inside Docker image filesystem to be executed before container stops.

A uses case is to execute a warm-shutdown preparation script.

A script that sends SIGUSR1 to teamd to initiate warm shutdown is one of such examples. | + + +##### /usr/bin/*feature*.sh + +The script under /usr/bin/ starts, stops or waits for container exit. This script is auto-generated during build time from +[docker_image_ctl.j2](https://github.com/Azure/sonic-buildimage/blob/4006ce711fa6545b0870186ffa05d4df24edb8b7/files/build_templates/docker_image_ctl.j2). +To allow a runtime package installation, it is required to have this file as part of SONiC image and put it in +*/usr/share/sonic/templates/docker_image_ctl.j2*. The Jinja2 template will accept three arguments, *docker_container_name*, +*docker_image_name* and *docker_run_options*, which derive from the */container/* node from manifest. Besides of options +defined in the manifest, the following default are used to start container to allow container to access base SONiC resources, +like database and syslog: + +``` +docker create {{ docker_run_options }} + --net=$NET \ + --uts=host \ + --log-opt max-size=2M --log-opt max-file=5 \ + -v /var/run/redis$DEV:/var/run/redis:rw \ + $REDIS_MNT \ + -v /usr/share/sonic/device/$PLATFORM:/usr/share/sonic/platform:ro \ + -v /usr/share/sonic/device/$PLATFORM/$HWSKU/$DEV:/usr/share/sonic/hwsku:ro \ + --env "NAMESPACE_ID"="$DEV" \ + --env "NAMESPACE_PREFIX"="$NAMESPACE_PREFIX" \ + --env "NAMESPACE_COUNT"=$NUM_ASIC \ + --name={{docker_container_name}}$DEV {{docker_image_name}} +``` + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ----------------------------- | --------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| /container/privileged | string | no | Start the container in privileged mode. Later versions of manifest might extend container properties to include docker capabilities instead of privileged mode. Defaults to False. | +| /container/volumes | list of strings | no | List of mounts for a container. The same syntax used for '-v' parameter for "docker run".

Example: "\:\:\". Defaults to []. | +| /container/mounts | list of objects | no | List of mounts for a container. Defaults to []. | +| /container/mounts/[id]/source | string | yes | Source for mount | +| /container/mounts/[id]/target | string | yes | Target for mount | +| /container/mounts/[id]/type | string | yes | Type for mount. See docker mount types. | +| /container/tmpfs | list of strings | no | Tmpfs mounts. Defaults to [] | +| /container/environment | dict | no | Environment variables for Docker container (key=value). Defaults to {}. | + + +### Initial Extension Configuration + +SONiC Package can provide an the initial configuration it would like to start with after installation. +The JSON file will be loaded into running CONFIG DB and boot CONFIG DB file during installation. + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ----------------- | ---- | --------- | ----------------------------------------------------------------- | +| /package/init-cfg | dict | no | Default package configuration in CONFIG DB format. Defaults to {} | + + +Example: +```json +{ + "package": { + "init-cfg": { + "CPU_REPORT": { + "global": { + "report-interval": "5" + } + } + } + } +} +``` + +### CLI extension + +SONiC utilities support *show*, *config*, *sonic-clear* operations. A plugin approach is taken when extending those utilities. +A common way to introduce a plugin support for a python application is to structure a plugin as a python module that can be +discovered by the application in a well known location in the system. + +The proposed location is a package directory named *plugins* under each *show*, *config*, *sonic-clear* python package, +so that by iterating modules inside those packages utilities can load them. +This is implemented in a way defined in +[Python Packaging Guide. Creating and discovering plugins](https://packaging.python.org/guides/creating-and-discovering-plugins/#using-namespace-packages). + +A code snipped describing the approach is given: + +```python +import show.plugins + +def iter_plugins_namespace(ns_pkg): + return pkgutil.iter_modules(ns_pkg.__path__, ns_pkg.__name__ + ".") + +discovered_plugins = { + name: importlib.import_module(name) + for finder, name, ispkg + in iter_namespace(show.plugins) +} +``` + +A plugin will register it's sub-commands so that any utility will have a new sub-command group. +The SONiC package *can* provide a CLI plugin that will be installed into the right location during package +installation and then discovered and loaded by CLI. Later, once YANG CLI auto-generation tool is ready, +the plugin will be auto-generated and all command conflicts will be checked in advance during installation. + +In this approach it is easy to extend CLI with new commands, but in order to extend a command which is already +implemented in sonic-utilities the code in sonic-utilities base has to be implemented in an extendable manner. + + +###### Example + +For dhcp-relay feature, it is needed to extend the CLI with a new sub-command for vlan, which is easily implemented +by declaring a new sub-command: + +*show/plugins/dhcp_relay.py*: +```python +from show.vlan import vlan + +@vlan.command() +def dhcp_relay(): + pass +``` + +Extending an existing command like "show vlan brief" will require to rewrite it in an extandable way: + +*show/vlan.py*: +```python +class VlanBrief: + COLUMNS = [ + ("VLAN ID", get_vlan_id), + ("IP address", get_vlan_ip_address), + ("Ports", get_vlan_ports), + ("Port Tagging", get_vlan_ports_tagging) + ] +``` + +*show/plugins/dhcp_relay.py* +```python + +def get_vlan_dhcp_relays(vlan): + pass + +VlanBrief.COLUMNS.append(("DHCP Helper Address", get_vlan_dhcp_relays)) +``` + +NOTE: In this approach or in approach with auto-generated CLI an output of the command may change when a package is installed, +e.g. DHCP Helper Address may or may not be present in CLI depending on installed package. Thus all automation, testing tools +ave to be also auto-generated from YANG in the future. + + +###### manifest path + +| Path | Type | Mandatory | Description | +| ---------------------- | ------ | --------- | --------------------------------------------------------------- | +| /cli/mandatory | boolean| no | Wether CLI is a mandatory functionality for the package. Default: False. | +| /cli/show-cli-plugin | string | no | A path to a plugin for sonic-utilities show CLI command. | +| /cli/config-cli-plugin | string | no | A path to a plugin for sonic-utilities config CLI command. | +| /cli/clear-cli-plugin | string | no | A path to a plugin for sonic-utilities sonic-clear CLI command. | + +### SONiC Processes and Docker Statistics Telemetry Support + +[Processes And Docker Stats Telemetry HLD](https://github.com/Azure/SONiC/blob/master/doc/system-telemetry/process-docker-stats.md) + +This feature should be supported by SONiC Application Extension without any changes to existing feature implementation. + +### Feature Concept Integration + +SONiC controls optional feature (aka services) via FEATURE table in CONFIG DB. Once SONiC Package is installed in the system and +it must be treated in the same way as any optional SONiC feature. +The SONiC package installation process will register new feature in CONFIG DB. + +[Optional Feature HLD Reference](https://github.com/Azure/SONiC/blob/master/doc/Optional-Feature-Control.md) + +Features are configured in *FEATURE* table in *CONFIG DB* and backend - *hostcfgd* daemon - enables, disables features according +to the configuration. Default desired state for a SONiC Application Extension is "disabled". After installation, user can enable the feature: + +``` +admin@sonic:~$ sudo config feature featureA enabled +``` + +### Multi-DB support + +Application should be using swss-common library or swsssdk which take care of discovering database instances. + +### Configuration Reload + +*config reload* & *config load_minigraph* are used to clear current configuration and import new configuration from the input file +or from /etc/sonic/config_db.json. This command shall stop all services before clearing the configuration and then restarts those services. +Thus, any service that consumes CONFIG DB data has to be restarted on reload commands. + +As of today, *config reload* command implementation has a hard-coded list of services it needs to restart on reload. +A service is restarted in this case if its dependency is restarted (like swss) or it is restarted explicitly by *config reload*. +A problem arises when the switch will run a service which sonic-utilities is not aware about. Thus, a solution is proposed +in which *reload* command implementation is not aware of exact list of services and order they should be restarted: + +1. There will be a new target unit in systemd called – sonic.target that is wanted by ‘multi-user.target’ + +2. Every existing or newly installed extension service that requires restart on config reload would have the following + configuration in service file: + +``` +[Unit] +BindsTo=sonic.target +After=sonic.target + +[Install] +WantedBy=sonic.target +``` + +* "WantedBy" tells systemd to start services when target starts. +* "BindsTo" and "After" guaranty that services bound to sonic.target will be stopped + and the operation will be blocked till all services stop. Otherwise, service stop + can overlap with subsequent "restart" action. + +3. Config reload would be simplified to: + +``` +systemctl stop sonic.target +systemctl reset-failed `systemctl list-dependencies --plain sonic.target` +systemctl restart sonic.target +``` + + + +A different approach is considered to make easier config reloads. Every SONiC service that has to be restarted on config reload can be defined +as *PartOf* sonic.target. So the *systemctl restart sonic.target* will restart those services in the ordering is managed by systemd without a +need to update the list of services in CLI. + +### System Dump + +SONiC Package *can* specify a command to execute inside container to get the debug dump that should be included in system dump file. +This command should be specified in manifest. A command should write its debug dump to stdout which will be gzip-ed into a file +during *show techsupport* execution. This file will be included in techsupport under *dump/\/dump.gz*. + + +###### manifest path + +| Path | Value | Mandatory | Description | +| ------------------- | ------ | --------- | ------------------------------------------- | +| /package/debug-dump | string | No | A command to be executed during system dump | + +### Multi-ASIC + +Based on current Multi-ASIC design, a service might be a host namespace service, like telemetry, SNMP, etc., or replicated per each ASIC namespace, +like teamd, bgp, etc., or running in all host and ASICs namespaces, like lldp. Based on */host-namespace* and */per-namespace* fields in manifest, +corresponding service files are created per each namespace. *systemd-sonic-generator* is invoked to create and install service units per each namespace. + + +###### manifest path + +| Path | Value | Mandatory | Description | +| --------------------- | ------- | --------- | ----------------------------------------------------------------------------------- | +| /service/host-service | boolean | no | Multi-ASIC field. Wether a service should run in host namespace. Default is True. | +| /service/asic-service | boolean | no | Multi-ASIC field. Wether a service should run per ASIC namespace. Default is False. | + +### Warmboot and Fastboot Design Impact + +A SONiC package can specify an order of shutdown on warm-reboot for a service. A "bgp" may specify "radv" in this field in order to avoid radv +to announce departure and cause hosts to lose default gateway, while "teamd" service has to stop before "syncd", but after "swss" to be able to +send the last LACP PDU though CPU port right before CPU port becomes unavailable. + +The warm-reboot and fast-reboot service shutdown scripts have to be auto-generated from a template */usr/share/sonic/templates/fast-shutdown.sh.j2* +and */usr/share/sonic/templates/warm-shutdown..sh.j2* wich are symbolic links to the same template. The templates are derived from the fast-reboot +script from sonic-utlities. + +A services shutdown is an ordered executions of *systemctl stop {{ service }}* commands with an exception for "swss" service after which a syncd +pre-shutdown is requested and database backup is prepared for next boot. A service specific actions that are executed on warm-shutdown are hidden +inside the service stop script action. + +NOTE: the assumption here is that syncd pre-shutdown is bound to swss service stop when swss service is doing system level shutdown. + +The *\*-shutdown.sh* are imported and executed in corresponding *\*-reboot* scripts. + + +###### warm-shutdown.sh.j2 snippet + +```jinja2 +... +{% for service in shutdown_orider %} +systemctl stop {{ service }} +{% endfor %} +... +``` + +*warmboot-finalizer.sh* script must also be templatized and updated based on process *reconciles* flag. + + +###### manifest path + +| Path | Value | Mandatory | Description | +| ----------------------------- | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| /service/warm-shutdown/ | object | no | Warm reboot related properties. Used to generate the warm-reboot script. | +| /service/warm-shutdown/after | lits of strings | no | Warm shutdown order dependency. List of SONiC services the application is set to stop after on warm shutdown.

Example: a "bgp" may specify "radv" in this field in order to avoid radv to announce departure and cause hosts to lose default gateway.

*NOTE*: Putting "radv" here, does not mean the "radv" should be installed as there is no such dependency for the "bgp" package. | +| /service/warm-shutdown/before | lits of strings | no | Warm shutdown order dependency. List of SONiC services the application is set to stop before on warm shutdown.

Example: a "teamd" service has to stop before "syncd", but after "swss" to be able to send the last LACP PDU though CPU port right before CPU port becomes unavailable. | +| /service/fast-shutdown/ | object | no | Fast reboot related properties. Used to generate the fast-reboot script. | +| /service/fast-shutdown/after | lits of strings | no | Same as for warm-shutdown. | +| /service/fast-shutdown/before | lits of strings | no | Same as for warm-shutdown. | +| /processes | object | no | Processes infromation | +| /processes/[name]/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. | + + + +### SONiC-2-SONiC upgrade + +SONiC-2-SONiC upgrade shall work for SONiC packages as well. An upgrade will take the new system *packages.json* and version requirements +and do a comparison between currently running and new SONiC image. + + +###### Package migration scenarios + +| Package | Version | Action | +| -------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | +| Non built-in package | Default version defined in *packages.json* in new SONiC image is greater then in current running SONiC image | Perform a package installation/upgrade in new SONiC image | +| Non built-in package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation/upgrade in new SONiC image of currently running package version. | + +The old *packages.json* and new *packages.json* are merged together and updated in new SONiC image. + +Since the installation or upgrade of packages are required to be done on SONiC image installation time a new SONiC image filesystem +needs to be mounted and *dockerd* has to be started in the chroot environment of new image as it is a requisite of *sonic-package-manager*. + +CONFIG DB shall not updated with initial config of the package and a new feature in the FEATURE table in this scenario. A package should +keep it's configuration backward compatible with old version. After installation succeeded and reboot into new image is performed all +previously installed extensions should be available. + +An option to skip migrating packages will be added for users that want to have a clean SONiC installation: + +``` +admin@sonic:~$ sudo sonic-installer install -y sonic.bin --no-package-migration +``` + + +### Kubernetes & SONiC Application Extension + +[Kubernetes HLD](https://github.com/Azure/SONiC/blob/be12cc665c316348352b868f515714f202861f63/doc/kubernetes/Kubernetes-support.md) + +This section is WIP and describes the approach in very high level and needs more deep investigation. + +The first thing to note here is that a Kubernetes manifest file can be auto-generated from SONiC Package manifest as it cat provide all the info about +how to run the container. This manifest auto-generation is related to Kubernetes master changes while we will be focusing on SONiC OS side, so it is out of +the scope here. + +Besides of the manifest on the master, the SONiC switch has to have service files, configs, scripts installed for the feature. + +1. Package installed through SONiC package manager. + +During package installation these necessary components will be auto-generated and installed on the switch. The auto-generation must honor new requirements +to support "local" and "kube" modes when in "local" mode the container gets started on systemctl start, while in "kube" mode the appropriate feature label +is set. + +2. Docker container upgrades through Kubernetes. + +During that processes a new Docker container gets deployed and run on the switch. Kubernetes managed features introduces a state machine for a running +container that is reflected in the STATE DB. When container starts it sets its state as "pending" and waits till there is a "ready" flag set. + +A state-db-watcherd is listening to those changes. If there is a need to regenerate service file and scripts it initiates sonic-package-manager +upgrade re-generation processes. Since the image is already downloaded and running but pending, the package manifest can be read and based on manifest +it can generate the required files. Then, the state-db-watcherd can proceed to systemctl stop old container, systemctl start new container +where the container_action script set the container state to "ready" and the container resumes to run the applications. + +3. Docker container deploy through Kubernetes. + +The case describe the scenario when the user is setting a label via "config kube label add =". If labels match the manifest on the master +the docker image gets deployed. Using the same approach, between "pending" and "ready" states an auto-generation process can happen and register the +Docker as a new package. With that, a deployed image will become an installed SONiC Package, that can be managed in "local" mode as well. + + +### 3rd party Docker images + + +### Installing 3rd party image as is. + +It is possible to install 3rd party Docker images if the installer will use a default manifest. This default manifest will have only mandatory fields +and an auto-generated service will require only "docker" service to be started. The name of the service is derived from the name of the Package in *packages.json*. + +Default manifest: +```json +{ + "service": { + "name": "", + "requires": "docker", + "after": "docker" + } +} +``` + +The default container run configuration have to be skipped for 3rd party Docker images. E.g. "--net=host", "-e NAMESPACE=$DEV" are not required +for 3rd party unless. 'asic-service' field is ignored for 3rd party Docker image in this case. +This settings have to be present in *container* properties in manifest. + +3rd party Docker image, as it has no knowledge of SONiC, will not meet the requirements described in section [SONiC Package]((#sonic-package)). +Thus, for such Docker images the limitations are: +- can be locally managed only, as the requirement for kube managed features is not met. + +Another possibility is to allow users to provide a manifest file URL. + +An example of the flow for a collectd Docker image: +``` +admin@sonic:~$ sudo sonic-package-manager repository add collectd puckel/docker-collectd +admin@sonic:~$ sudo sonic-package-manager install collectd --manifest https://some-server/manifests/collectd/manifest.json +``` + +The manifest is saved under */var/lib/sonic-package-manager/collectd/manifest.json* for future access. + + + +### Prepare 3rd party image as to be SONiC compliant + +This will require to build a new image based on existing 3rd party Docker image and do the change according to requirements described in +[SONiC Package]((#sonic-package)). + + +### SONiC Build System + +#### SONiC SDK Docker Images + +SONiC build system will provide three docker images to be used as a base to build SONiC application +extensions - *sonic-sdk-buildenv*, *sonic-sdk* and *sonic-sdk-dbg*. + +*sonic-sdk* will be based on *docker-config-engine* with addition of packages needed at run time: + +- libhiredis +- libnl* +- libswsscommon +- python3-swsscommon +- libsairedis +- libsairedis +- libsaimeta +- libsaimetadata + +Corresponding *-dbg* packages will be added for *sonic-sdk-dbg* image. A list of packages will be extended on demand +when a common package is required by community. If a package is required but is specific to the SONiC package +it should not be added to this list. + +*sonic-sdk-buildenv* is based on *sonic-sdk* and has common SONiC packages required to build SONiC package. +The idea of this Docker image is a minimalistic sonic-slave container which contains only those packages which are +SONiC specific. E.g. libswsscommon is SONiC specific as cannot be downloaded pre-built from Debian repositories. +On the other hand, libteam and teamd are container specific and should be built per SONiC package which require these +packages. + +The list of packages added to *sonic-sdk-buildenv* in addition to *sonic-sdk*: + +- build-essential +- libhiredis-dev +- libnl*-dev +- libswsscommon-dev +- libsairedis-dev +- libsaimeta-dev +- libsaimetadata-dev +- tools, etc. + + +#### SONiC SDK Build Metadata + +The SDK images built should be labeled with metadata about the build to give the user an idea about base OS version +compatibility as well as some core packages version compatibility. Packages like *libswsscommon* and *libsairedis* +have a relation to database, swss, syncd containers they were built togather with. + +The SDK components versions are saved into labels: + +``` +LABEL com.azure.sonic.versions.libswsscommon +LABEL com.azure.sonic.versions.libsairedis +``` + +The following list of additional labels are going to be used: + +``` +LABEL com.azure.sonic.sdk.config-engine +LABEL com.azure.sonic.sdk.database +LABEL com.azure.sonic.sdk.swss +LABEL com.azure.sonic.sdk.syncd +``` + + +#### SONiC SDK Usage with Docker Multi-Stage Builds + +The user of those Docker images can levarage Docker Multi-Stage Builds to efficiently use both build environment image +and runtime image: + +```Dockerfile +FROM sonic-sdk-buildenv:1.0.2 as buildenv + +WORKDIR /src/application +RUN debuild -b -us -uc -j$(nproc) + +FROM sonic-sdk:1.0.2 as runenv + +COPY --from=buildenv /src/application_1.0.0_amd64.deb /tmp/ +RUN dpkg -i /tmp/application_1.0.0_amd64.deb + +ENTRYPOINT /usr/bin/application +``` + + +#### SONiC SDK Disk Space Usage Optimizations + +SONiC Packages might or might not use SONiC SDK but it is strongly advised to be based on SONiC SDK due to disk space optimizations. +Ideally, all SONiC Packages use the same version of SONiC SDK; in this case Docker maintains a single copy of SONiC SDK image. +The worst scenario will be when all SONiC Packages use different version of SONiC SDK and SONiC SDK use different versions of +base debian distribution; in this case Docker will need to have copies of all base layers. This may increase the total size of +SONiC image twice or more depending on the number of SONiC packages installed. + +Considering the fact that within a release the base debian Docker image does not change and SONiC SDK libraries change rarely +comparing to the packages this should not be a big concern. The versioning information put in a labels of SONiC SDK Docker image +may help the user to install or upgrade packages considering disk space optimization either manually or the sonic-package-manager +might be extended with an option to do disk space optimization. In any case, while only limited number of Dockers will become SONiC +packages this is not a big concern. + +### SAI API + +No SAI API changes required for this feature. + +### Restrictions/Limitations + +The current design puts the following restrictions on SONiC packages that can be managed by Application Extension Framework: +- No support to do ASIC programming from extension. +- No support for REST/Klish CLI/gNMI extensions + +### Testing Requirements/Design + +(TODO) + + +#### Unit Test cases + +(TODO) + + +#### System Test cases + +(TODO) + +### Open/Action items diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md new file mode 100644 index 00000000000..1dd60084459 --- /dev/null +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -0,0 +1,212 @@ + +# SONiC OS & SONiC Docker Images Versioning + + +#### Rev 0.1 + + +## Table of Content +- [SONiC Package API](#sonic-package-api) +- [SONiC Package Releases](#sonic-package-releases) +- [Conventional Commits](#conventional-commits) +- [SONiC Package Versioning Rules](#sonic-package-versioning-rules) +- [SONiC Packages Versioning](#sonic-packages-versioning) +- [Base OS versioning](#base-os-versioning) +- [Base OS API that a package uses](#base-os-api-that-a-package-uses) +- [Open Questions](#open-questions) + + +## List of Figures + +### Revision + +| Rev | Date | Author | Change Description | +|:---:|:-----------:|:-----------------------:|--------------------------------------| +| 0.1 | 02/2021 | Stepan Blyshchak | Initial Proposal | + +### Overview + +This document provides guidelines on how to do versioning for SONiC Docker Images using to semantic versioning strategy. + + +#### Motivation + +With new SONiC Application Extension Infrastructure SONiC Dockers and SONiC Base OS can be seperated and distributed individually. +SONiC Dockers (aka SONiC Packages) can be installed, upgraded invididually from other. This creates a new problem which needs to be +solved - compatibility between dependend Dockers and host OS. SONiC Application Extension Infrastructure provides a way to specify +the package version dependency using semantic versioning (https://semver.org). This document provides a guideline on how to increment +version numbers correctly on releases. + +## SONiC Package API + +First of all, a clear definition of what is package API needs to be provided: + +SONiC package API is Redis DB interface including: + - CONFIG DB, APPL DB, STATE DB tables schema provided by this package + +If any other kind of API is exposed by the SONiC Package it should be accounted as package API. + +## SONiC Package Releases + +As of today (202012 release), all SONiC Docker Images are released together with SONiC OS. With SONiC Application Extension +Infrastructure SONiC Dockers are released independently. On every release an increment in package version number is required. +The exact number in version that needs to be incremented depends on the type of changes comparing to previously released +package. + +Types of changes: + - Breaking change: backwards incompatible change; reflects in ***major*** version number + - New functionality: backward compatible change; reflects in ***minor*** version number + - Bug fixes or enhancement; reflects in ***patch*** version number + +## Conventional Commits + +In order to help ***package maintainers*** to understand whether a breaking change was introduced +comparing to previous release or a new functionality was included all SONiC repositories *can* +follow conventional commits (https://www.conventionalcommits.org/en/v1.0.0/): + +e.g: + +``` +feat: Introduce new methods in ConsumerTable + +BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC +``` + +## SONiC Package Versioning Rules + +- A package is published with a bug fix or enhancement whenever ***package maintainer decides*** to do so. +- Manual version update ***is required*** when SONiC Package releases +- On package release ***package maintainer must*** check package API compatibility comparing to previously released package +- In case API changed comparing to previous release ***package maintainer must*** must increment major version +- In case new backwards compatible changes were made comparing to previous release ***package maintainer must*** must increment minor version +- *Patch* version is updated on changes which do not introduce any changes to the API +- On package release ***package maintainer can*** update package dependencies + +**NOTE**: SONiC package version has no correlation to a SONiC release. While keeping API of dependencies compatible a package can work across different SONiC releases. + +Package maintainer may choose to maintain a single repository and have there packages that can work accross different releases or maintain a repository per SONiC release. + +***package maintainer can*** update *default-reference* in package.json in SONiC buildimage to point to a default version which will be used when user installs a package. + +## Base OS versioning + +## Base OS API that a package uses + +- SONiC utilities + - This is a ***sonic-utilities contributor responsibility*** +- Dependence on a new kernel functionality must be recorded in minor version + - This is a ***package maintainer responsibility*** + E.g.: a patch in kernel to support 3-tuple conntrack entries that NAT docker depends on. +- SONiC host service (D-Bus based communication) +- etc. + + +# Examples + +1. Changed the API and optionally introduced new API or other changes not related to API: + +``` +major.minor.patch => (major + 1).minor.patch +``` + +2. Introduced new API and optionally other changes: + +``` +major.minor.patch => major.(minor + 1).patch +``` + +3. Enhancements and bug fixes, SONiC SDK update, manifest update, etc.: + +``` +major.minor.patch => major.minor.(patch + 1) +``` + +*NOTE*: It is possible to maintain same version in two repositories, e.g. for two different SONiC releases: + +azure/sonic-foo-202106:1.2.3 +azure/sonic-foo-202112:1.2.3 + +4. Dependency changes + +Considering the following package foo: + +```json +{ + "package": { + "name": "foo", + "version": "1.2.3", + "depends": [ + { + "name": "swss", + "version": "^1.0.0" + } + ] + } +} +``` + +4.1 Package foo depends on swss API ^1.0.0. Now if swss upgrades to 2.0.0, but foo uses only few tables from swss APPL DB that didn't change a new package of foo has to be released, updating package dependencies: + +foo's manifest: + +```json +{ + "package": { + "name": "foo", + "version": "1.2.4", + "depends": [ + { + "name": "swss", + "version": "^1.0.0,^2.0.0" + } + ] + } +} +``` + +4.2 In case swss tables used by foo have changed, foo has to change by releasing a new package with updated dependency: + +```json +{ + "package": { + "name": "foo", + "version": "1.2.4", + "depends": [ + { + "name": "swss", + "version": "^2.0.0" + } + ] + } +} +``` + +4.3 In case swss tables used by foo have changed, foo's developer might still want to support swss 1.0.0. In that case infrastructure can pass dependencies versions in environment variables when starting the container, foo's application can read the environment "SWSS_VERSION" knowing which exactly API to choose. This case is similar to 4.1 as new foo package will support both ^1.0.0 & ^2.0.0 + +5. Dependencies SDK changes + +An infrastructure can detect wether package foo is using SDK componenet major version same as foo's dependencies. This automatic check does not require package maintainer additional manifest configuration. + +For more control foo developer can specify more exact rules. + +For example, foo is only using swss::Table, while a breaking change appeared in swss::ProducerStateTable/swss::ConsumerStateTable. foo's developer can update package to work with new SDK in swss as well: + +```json +{ + "package": { + "name": "foo", + "version": "1.2.4", + "depends": [ + { + "name": "swss", + "version": "^1.0.0", + "components": { + "libswsscommon": "^1.0.0,^2.0.0" + } + } + ] + } +} +``` + +## Open Questions