From fabe34bd6bd814f1156fe53305bbb30b846422c2 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Mon, 15 Jun 2020 18:07:20 +0300 Subject: [PATCH 01/38] [doc] SONiC Application Extention HLD Signed-off-by: Stepan Blyschak --- .../img/docker-infra-concepts.svg | 268 +++++ .../img/feature-start.svg | 494 +++++++++ .../img/feature-stop.svg | 469 +++++++++ .../img/install-flow.svg | 681 ++++++++++++ .../img/packages-json.svg | 390 +++++++ .../img/sonic-package-integration.svg | 319 ++++++ .../img/sonic-pkg-basic-concepts.svg | 3 + .../img/uninstall-flow.svg | 576 +++++++++++ .../img/upgrade-flow.svg | 712 +++++++++++++ .../sonic-application-extention-hld.md | 974 ++++++++++++++++++ 10 files changed, 4886 insertions(+) create mode 100644 doc/sonic-application-extention/img/docker-infra-concepts.svg create mode 100644 doc/sonic-application-extention/img/feature-start.svg create mode 100644 doc/sonic-application-extention/img/feature-stop.svg create mode 100644 doc/sonic-application-extention/img/install-flow.svg create mode 100644 doc/sonic-application-extention/img/packages-json.svg create mode 100644 doc/sonic-application-extention/img/sonic-package-integration.svg create mode 100644 doc/sonic-application-extention/img/sonic-pkg-basic-concepts.svg create mode 100644 doc/sonic-application-extention/img/uninstall-flow.svg create mode 100644 doc/sonic-application-extention/img/upgrade-flow.svg create mode 100644 doc/sonic-application-extention/sonic-application-extention-hld.md 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 0000000000..2f6c3af628 --- /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 0000000000..e049f245e8 --- /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 0000000000..d14439ec11 --- /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 100644 index 0000000000..05d1bff819 --- /dev/null +++ b/doc/sonic-application-extention/img/install-flow.svg @@ -0,0 +1,681 @@ + + + + + + + + + + + + + + + + + + + + + + + + Сторінка 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 + + + + + + + + + + Повідомлення.55 + docker cp /var/lib/sonic-package + + + + + + + + + + + docker cp /var/lib/sonic-package + + Повідомлення.56 + copy package metadata folder + + + + + + + + + + + copy package metadata folder + + Повернуто повідомлення.57 + return + + + + + + + + + + + return + + Повернуто повідомлення.58 + return + + + + + + + + + + + return + + Повідомлення.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 + + + + + + + Активація.70 + + + + + + + Активація.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/version in DB + + + + + + + + + + + Update installation status/version 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 + + + 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 0000000000..73fdbd3a5a --- /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 0000000000..23c96ba575 --- /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 0000000000..f02e0a2afc --- /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 0000000000..e97589fc01 --- /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 100644 index 0000000000..fa52ef1955 --- /dev/null +++ b/doc/sonic-application-extention/img/upgrade-flow.svg @@ -0,0 +1,712 @@ + + + + + + + + + + + + + + + + + + + + + + + + Сторінка 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 + + + + + + + + + + Повідомлення.55 + docker cp /var/lib/sonic-package + + + + + + + + + + + docker cp /var/lib/sonic-package + + Повідомлення.56 + copy package metadata folder to /tmp/<feature>_upgrade/ + + + + + + + + + + + copy package metadata folder to /tmp/<feature>_upgrade/ + + Повернуто повідомлення.57 + return + + + + + + + + + + + return + + Повернуто повідомлення.58 + return + + + + + + + + + + + return + + Повідомлення.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 + + + + + + + Активація.70 + + + + + + + Активація.71 + + + + + + + Активація.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 + + + + + + + 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 0000000000..a7e8d5bf2f --- /dev/null +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -0,0 +1,974 @@ + +# 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) +- [Essential SONiC Packages](#essential-sonic-packages) +- [SONiC Package Management](#sonic-package-management) +- [SONiC Package Database](#sonic-package-database) +- [SONiC Base Image and Packages Versioning](#sonic-base-image-and-packages-versioning) +- [Configuration and management](#configuration-and-management) +- [SONiC Package Installation Flow](#sonic-package-installation-flow) +- [SONiC Package Uninstallation Flow](#sonic-package-uninstallation-flow) +- [SONiC Package Upgrade Flow](#sonic-package-upgrade-flow) +- [Manifest File](#manifest-file) +- [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) +- [Monit Configuration](#monit-configuration) +- [Feature Concept Integration](#feature-concept-integration) +- [Multi-DB support](#multi-db-support) +- [Configuration Reload](#configuration-reload) +- [System Dump](#system-dump) +- [SONiC-2-SONiC upgrade](#sonic-2-sonic-upgrade) +- [Multi-ASIC](#multi-asic) +- [Kubernetes & SONiC Application Extension](#kubernetes--sonic-application-extension) +- [SONiC Build System](#sonic-build-system) +- [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 Infrastrcuture: +- SONiC OS must provide a CLI to manage SONiC repositories and packages. + This includes package installation, uninstallation, + 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 "feaute" + 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 tagged using a version number. + +### SONiC Package + +SONiC Packages must meet few requirements in order to be a SONiC compatible Docker image. +- Package must provide a *manifest* file that is used to tell SONiC Application Extension Infrastructure how to integrate +the package with the rest of the SONiC. +- Applications running inside container have to support *CONTAINER_FEATURE* CONFIG DB configuration as well as container +auto-restart functionality on critical process death. As this feature is implemented as part of the Docker container and not +the host OS the infrastructure does not enforce such functionality. However, this is not a hard requirement for a package. +The feature will correctly work if such functionality is missing, rather it is advised in order to be align with the behaviour +of other containers. +- Any other requirement for the Docker container demanded by SONiC must be met. + (e.g. container state recording + [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)) + +Manifest file must exists in a stardart location so that the manifest is easially discoverable by the infrastructure. +The path chosen for the manifest file is */var/lib/sonic-package/manifest.json* placed in Docker image. +Arbitrary Docker images require a modification or a layer on top which adds a manifest file. + + +###### 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.json* file provided by SONiC Package. + +The scope of this document is limited to SONiC compatible Docker images only. + +### Essential SONiC Packages + +Every SONiC Docker image can be converted to be a SONiC Package, although it is naturally to expect that SONiC OS comes with a set of Docker images +pre-installed. Those Docker images are considered to be essential. Like a debian essential package, SONiC essential package cannot be removed from the +system. Besides, this will allow for a smooth transition of SONiC Docker images into SONiC packages by marking all of the existing Docker images as +essential and then removing essential flag for images that became a SONiC packages. + +The following list enumerates essential Docker containers: +- database +- syncd +- swss +- pmon + +Those containers do not provide an individual feature, monitoring service or networking protocol implementation but rather are required +to run other features. + +### 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 are *packages.json* file as well as a directory per each SONiC package with a package metadata. A database will have the following structure: + +``` +/ + var/ + lib/ + sonic-packages/ + packages.json + snmp/ + lldp/ + dhcp-relay/ +``` + +###### Example directory strcuture 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 or a local image reference. +/name/description | string | Application description field. +/name/default-version | string | A tag which points to a package that will be a default installation candidate if not specified. +/name/essential | boolean | A flag if a SONiC package is an essential 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. + + +A sample of the content in JSON format: + +```json +{ + "database": { + "repository": "docker-database", + "description": "SONiC database service", + "essential": true, + "default-version": "1.0.0", + "status": "installed", + "installed-version": "1.0.0" + }, + "swss": { + "repository": "docker-orchagent", + "description": "SONiC switch state service", + "essential": true, + "default-version": "1.0.0", + "status": "installed", + "installed-version": "2.0.1" + }, + "cpu-report": { + "repository": "Azure/sonic-dhcp-relay", + "description": "DHCP relay feature", + "default-version": "1.0.0", + "status": "not-installed" + }, + "featureXXX": { + "repository": "Azure/sonic-snmp", + "description": "Simple Network Monitoring Protocol", + "default-version": "1.0.0", + "status": "installed", + "installed-version": "1.0.0" + } +} +``` + +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. + +Once a Docker becomes a SONiC package, user will have two options: + +- SONiC build system will be extended with a build parameter "INCLUDE_$PACKAGE=y|n". If this parameter is set to "y", a package will be +installed in SONiC image filesystem during build time. +- If the "INCLUDE_$PACKAGE" is set to "n", the target is not installed, but compiled into Docker Image and published to Docker Hub by CI for +users to install the package on a running switch. For that, the reference to the package will be added into *packages.json*. + +### 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 base OS has also have a version number that follows the same rules of semantic versioning so that a package can define a dependency on +base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "sonic_compatibility_version" that follows semantic +versioning schema. This version is in addition to SONiC version we have today. + +This version number does not replace the current SONiC version string that is generated during the build so both SONiC version string and +SONiC compatibility version coexist. SONiC compatibility version can be updated independently from SONiC version. + +The updated output of "show version" command is given below: + +``` +admin@sonic:~$ show version + +SONiC Software Version: SONiC.master.0-7580c846 +SONiC Compatibility Version: 1.0.0 +Distribution: Debian 9.13 +Kernel: 4.9.0-11-2-amd64 +Build commit: 7580c846 +Build date: Sat Sep 26 04:17:56 UTC 2020 +Built by: johnar@jenkins-worker-8 +... +``` + +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. + +### Configuration and management + +N/A (TODO) + + +#### CLI Enhancements + +The SONiC Package Manager is another executable utility available in base SONiC OS called *sonic-package-manager-manager* or abbreviated to *spm*. +The command line interfaces are given bellow: + + +#### CLI + +``` +admin@sonic:~$ sonic-package-manager-manager +Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... + + CLI to manage SONiC application packages + +Options: + --help Show this message and exit + +Commands: + add Add a new package to package database. + remove Remove a package from package database. + list List packages available in SONiC. + show Show SONiC package Info. + install Install SONiC package from repository. + upgrade Upgrade SONiC package. + uninstall Uninstall SONiC package. +``` + +``` +admin@sonic:~$ sonic-package-manager-manager show +Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... + + Show SONiC package Info. + +Options: + --help Show this message and exit + +Commands: + manifest Print package manifest + changelog Print package changelog. +``` + + +#### List of packages available +``` +admin@sonic:~$ sonic-package-manager list +Name Repository Description Version Status +----------- --------------------- ------------------------ ------------ -------------- +database docker-database SONiC database 1.0.0 Essential +swss docker-orchagent Switch state service 1.0.0 Essential +syncd docker-syncd-vs SONiC ASIC sync service 1.0.0 Essential +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] --description=[STRING] --default-version=[STRING] +admin@sonic:~$ sudo sonic-package-manager remove [NAME] +``` + + +#### Package Installation + +``` +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. + +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 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 name. + +An option to skip all dependency checks and force the installation: + +``` +admin@sonic:~$ sudo sonic-package-manager install --force feature +``` + +*show version* command can be used to display feature docker image version. + + +#### Package Upgrade + +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. + + +### SONiC Package Installation Flow + +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. The behavior might be changed if the need to have different installed versions and +choose which one to run will arise. + + +###### 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 File + +Every SONiC Package that is not an essential package must provide a *manifest.json* file in image filesystem under */var/lib/sonic-package/manifest.json*. +The following table describes schema for version 1.0.0: + +Path | Type | Mandatory | Description +--------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- +/version | string | yes | Version of manifest file definition. +/package | object | no | Package related metadata information. +/package/depends | list of strings | no | List of SONiC packages the service depends on in the format \:[>\|>=\|==\|<\|<=]\. E.g. "swss:\>1.4.1". +/package/breaks | list of strings | no | List of SONiC package the service breaks in the format \:[>\|>=\|==\|<\|<=]\. E.g. "featureX:\<=1.1.0". +/package/sonic-version | string | no | SONiC base image version dependency in the format [>\|>=\|==\|<\|<=]\. E.g. "\>=1.1.0". +/package/changelog | string | no | A path to a file relatively to manifest file that contains a human readably changelog file that will be displayed to the user. +/package/init-config | string | no | Path to SONiC Application Extension Package initial configuration JSON file relatively to manifest file.

This configuration will be appendend to running and boot configuration during installation. +/package/debug-dump | string | no | A command to be executed during system dump.

This field tells the system what to do if user requests "show techsupport" information. +/service/ | object | yes | Service management related properties. +/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 "breaks". +/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/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/peer | strnigs | no | The service that is defined as a peer for this package service.

Specifying in this option a service X, will regenerate the /usr/local/bin/X.sh script and set the "PEER" variable. The peer is started, stopped, restarted togather with the current service.

Example:

"syncd" is set as a peer for "swss". +/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/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. +/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-stop-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. +/service/host-namespace | boolean | yes | Multi-ASIC field. Wether a service should run in host namespace. Mandatory field. +/service/asic-namespace | boolean | yes | Multi-ASIC field. Wether a service should run per ASIC namespace. Mandatory field. +/container/ | object | no | Container related properties. +/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. +/container/volumes | list of strings | no | List of mounts for a container. The same syntax used for '-v' parameter for "docker run".

Example: "\:\:\". +/processes/ | list | no | A list defining processes running inside the container. +/processes/name | string | yes | Process name. +/processes/name/critical | boolean | no | Wether the process is a critical process. Defaults to False. +/processes/name/autorestart | boolean | no | Autorestart by controlled by supervisord. Defaults to False. +/processes/name/command | string | yes | Command to run the process. +/processes/name/start-depends | string | no | Format of "\:\". +/processes/name/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. +/cli | object | no | CLI plugin infromation. *NOTE*: Later will deprecated and replaced with a YANG module file path. +/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. + +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 Docker Container Lifetime + +Container lifetime in SONiC is currently controled 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 autogenerated during SONiC Package installation. The information needed for them to be +autogenerated is defined in the manifest file 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 file. + + +##### /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. + +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. + + +##### /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 file. 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}} +``` + +### 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 file path + +Path | Type | Description +--------------------------- | --------------------- | ---------------------------------------------------------------------------------------- +/package/init-cfg | string | Path to SONiC Extension Initial Configuration JSON file relatively to manifest file + +### 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 file path + +Path | Type | Description +-------------------------------- | --------------------- | ---------------------------------------------------------------------------------------- +/cli/show-cli-plugin | string | A path to a plugin for sonic-utilities show CLI command +/cli/config-cli-plugin | string | A path to a plugin for sonic-utilities config CLI command +/cli/clear-cli-plugin | string | 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. + +### Monit Configuration + +Processes information is also used to generate monit configuration file based on the *critical* flag. An installation is triggering +monit configuration reload by issueing *systemctl reload monit.service*. + +### 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 +is not marked as essential 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 + +SONiC Packages should restart on initiated *config reload* commands. Service management and services dependencies management in SONiC is complex. +*config reload* command has a 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. This list becomes dynamic with introduction of packages. + +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 file. 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 file path + +Path | Value | Description +-------------------------------|-------------------|--------------------------------------------------------------------------------- +/package/debug-dump | string | A command to be executed during system dump + +### 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 +-------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- +Essential package | Installed version in new SONiC image is greater then in current running SONiC image | No actions required, the desired package is already installed in the system +Essential package | Installed version in new SONiC image is less then in current running SONiC image | An image upgrade is required to be done in new SONiC image. If a package is compatible witg new SONiC image version the currently running essential package will migrate to new SONiC image +Non-essential package | Default version defined in *packages.json* in new SONiC image is greater then in current running SONiC image | Perform a package installation in new SONiC image +Non-essential package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation in new SONiC image of currently running package version. If a package is compatible witg new SONiC image version the currently running essential package will migrate to new SONiC image + +The old *packages.json* and new *packages.json* are merged togather 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 +``` + +### 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 file, +corresponding service files are created per each namespace. *systemd-sonic-generator* is invoked to create and install service units per each namespace. + + +###### Manifest file path + +Path | Value | Description +---------------------------------|-----------------------|--------------------------------------------------------------------------------- +/service/host-namespace | boolean | Multi-ASIC field. Wether a service should run in host namespace. +/service/asic-namespace | boolean | Multi-ASIC field. Wether a service should run per ASIC namespace. + +### 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 file 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 neccessary 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 beteen "pending" and "ready" 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. + + +### 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. + +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 %} +... +``` + + +###### Manifest file path + +Path | Value | Description +----------------------------------|-----------------------|--------------------------------------------------------------------------------- +/service/warm-shutdown/ | object | Warm reboot related properties. Used to generate the warm-reboot script. +/service/warm-shutdown/after | lits of strings | 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 | 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 | Fast reboot related properties. Used to generate the fast-reboot script. +/service/fast-shutdown/after | lits of strings | Same as for warm-shutdown. +/service/fast-shutdown/before | lits of strings | Same as for warm-shutdown. + +### SONiC Build System + +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-buildenv* will have common SONiC packages required to build SONiC application extension and will be a minimal version of sonic-slave container: + +- build-essential +- libhiredis-dev +- libnl*-dev +- libswsscommon-dev +- libsairedis-dev +- libsaimeta-dev +- libsaimetadata-dev +- tools, etc. + +*sonic-sdk* will be based on *docker-config-engine* with addition of packages needed at run time: + +- libhiredis +- libnl* +- libswsscommon +- 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 application extension it should not be added to this list. + +### SAI API + +No SAI API changes required for this feature. + +### Restrictions/Limitations + +(TODO) + +### Testing Requirements/Design + +(TODO) + + +#### Unit Test cases + +(TODO) + + +#### System Test cases + +(TODO) + +### Open/Action items From a844e0555f67f811e37e07e77b9ecab2f1f6e0e7 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 9 Oct 2020 14:29:20 +0300 Subject: [PATCH 02/38] Remove a statement in requirements for a SONiC package. Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index a7e8d5bf2f..ce980f22e9 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -155,12 +155,8 @@ In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are reposito SONiC Packages must meet few requirements in order to be a SONiC compatible Docker image. - Package must provide a *manifest* file that is used to tell SONiC Application Extension Infrastructure how to integrate -the package with the rest of the SONiC. -- Applications running inside container have to support *CONTAINER_FEATURE* CONFIG DB configuration as well as container -auto-restart functionality on critical process death. As this feature is implemented as part of the Docker container and not -the host OS the infrastructure does not enforce such functionality. However, this is not a hard requirement for a package. -The feature will correctly work if such functionality is missing, rather it is advised in order to be align with the behaviour -of other containers. +the package with the rest of the SONiC. If Package does not provide a *manifest* file then a default is used which integrates +the package as a service that does not depend on any other SONiC service. - Any other requirement for the Docker container demanded by SONiC must be met. (e.g. container state recording [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)) From ee366f558be72fdcab0d971c6acba892315f3970 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 15 Oct 2020 15:59:37 +0300 Subject: [PATCH 03/38] Review comments handled Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 382 +++++++++++++----- 1 file changed, 277 insertions(+), 105 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index ce980f22e9..95473f1093 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -18,11 +18,13 @@ - [SONiC Package Management](#sonic-package-management) - [SONiC Package Database](#sonic-package-database) - [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 Installation Flow](#sonic-package-installation-flow) - [SONiC Package Uninstallation Flow](#sonic-package-uninstallation-flow) - [SONiC Package Upgrade Flow](#sonic-package-upgrade-flow) - [Manifest File](#manifest-file) +- [SONiC Package Installation](#sonic-package-installation) +- [SONiC Package Changelog](#sonic-package-changelog) - [SONiC Package Docker Container Lifetime](#sonic-package-docker-container-lifetime) - [Initial Extension Configuration](#initial-extension-configuration) - [CLI extension](#cli-extension) @@ -110,13 +112,13 @@ into SONiC codebase but maintain them separately. This follows all the popular L 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 Infrastrcuture: +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, uninstallation, + 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 "feaute" +- 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. @@ -154,16 +156,12 @@ In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are reposito ### SONiC Package SONiC Packages must meet few requirements in order to be a SONiC compatible Docker image. -- Package must provide a *manifest* file that is used to tell SONiC Application Extension Infrastructure how to integrate -the package with the rest of the SONiC. If Package does not provide a *manifest* file then a default is used which integrates -the package as a service that does not depend on any other SONiC service. -- Any other requirement for the Docker container demanded by SONiC must be met. - (e.g. container state recording - [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)) -Manifest file must exists in a stardart location so that the manifest is easially discoverable by the infrastructure. -The path chosen for the manifest file is */var/lib/sonic-package/manifest.json* placed in Docker image. -Arbitrary Docker images require a modification or a layer on top which adds a manifest file. +- Manifest file must exists in a standard location so that the manifest is easily discoverable by the infrastructure. + The path chosen for the manifest file is */var/lib/sonic-package/manifest.json* placed in Docker image. +- An application inside container should subscribe for CONTAINER_FEATURE table for auto-restart configuration + [Auto-Restart HLD](https://github.com/Azure/SONiC/blob/8a908c2d84f7d58cdaaea2825df13bfda9b73296/doc/monitoring_containers/monitoring_containers.md#223-auto-restart-docker-container). +- 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 @@ -180,7 +178,9 @@ The scope of this document is limited to SONiC compatible Docker images only. Every SONiC Docker image can be converted to be a SONiC Package, although it is naturally to expect that SONiC OS comes with a set of Docker images pre-installed. Those Docker images are considered to be essential. Like a debian essential package, SONiC essential package cannot be removed from the -system. Besides, this will allow for a smooth transition of SONiC Docker images into SONiC packages by marking all of the existing Docker images as +system, but also, it cannot be upgraded without an image upgrade. + +This will allow for a smooth transition of SONiC Docker images into SONiC packages by marking all of the existing Docker images as essential and then removing essential flag for images that became a SONiC packages. The following list enumerates essential Docker containers: @@ -189,6 +189,10 @@ The following list enumerates essential Docker containers: - 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. + Those containers do not provide an individual feature, monitoring service or networking protocol implementation but rather are required to run other features. @@ -209,7 +213,7 @@ There are *packages.json* file as well as a directory per each SONiC package wit dhcp-relay/ ``` -###### Example directory strcuture of SONiC Package Manager library +###### 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 @@ -292,11 +296,11 @@ identifiers and build id, like *1.0.0-dev+153*, that can be used for master bran 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 base OS has also have a version number that follows the same rules of semantic versioning so that a package can define a dependency on -base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "sonic_compatibility_version" that follows semantic +base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "base_os_compatibility_version" that follows semantic versioning schema. This version is in addition to SONiC version we have today. This version number does not replace the current SONiC version string that is generated during the build so both SONiC version string and -SONiC compatibility version coexist. SONiC compatibility version can be updated independently from SONiC version. +base OS compatibility version coexist. Base OS compatibility version can be updated independently from SONiC version. The updated output of "show version" command is given below: @@ -304,7 +308,7 @@ The updated output of "show version" command is given below: admin@sonic:~$ show version SONiC Software Version: SONiC.master.0-7580c846 -SONiC Compatibility Version: 1.0.0 +Base OS Compatibility Version: 1.0.0 Distribution: Debian 9.13 Kernel: 4.9.0-11-2-amd64 Build commit: 7580c846 @@ -325,6 +329,19 @@ This version is used to tag a Docker image when installing SONiC package in SONi 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. +### SONiC Application Extension Security Considerations + +There are a lots of aspects about security when it comes to running arbitrary 3rd party Dockers 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. +- Follows the Debian approach which does not have any security guard or restrictions about packages the user is installing. + ### Configuration and management N/A (TODO) @@ -332,14 +349,14 @@ N/A (TODO) #### CLI Enhancements -The SONiC Package Manager is another executable utility available in base SONiC OS called *sonic-package-manager-manager* or abbreviated to *spm*. +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-manager +admin@sonic:~$ sonic-package-manager Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... CLI to manage SONiC application packages @@ -358,7 +375,7 @@ Commands: ``` ``` -admin@sonic:~$ sonic-package-manager-manager show +admin@sonic:~$ sonic-package-manager show Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... Show SONiC package Info. @@ -415,12 +432,25 @@ admin@sonic:~$ sudo sonic-package-manager install 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 name. +Package Database is updated with a "repository" field set to local image name. The image is tagged to 1.0.0. +In the above example the following entry is added to *packages.json*: + +```json +{ + "featureA": { + "repository": "featureA", + "default-version": "1.0.0", + "installed-version": "1.0.0", + "status": "installed" + } +} +``` 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. @@ -449,21 +479,6 @@ This command will be deprecated and replaced by "sonic-package-manager" function No CONFIG DB changes required for this feature. - -### SONiC Package Installation Flow - -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. The behavior might be changed if the need to have different installed versions and -choose which one to run will arise. - ###### Figure 3. SONiC Package Installation Flow @@ -498,61 +513,142 @@ new one and start the service. The sequence is shown on the figure below: ### Manifest File Every SONiC Package that is not an essential package must provide a *manifest.json* file in image filesystem under */var/lib/sonic-package/manifest.json*. -The following table describes schema for version 1.0.0: +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 | yes | Version of manifest file definition. +/version | string | no | Version of manifest file definition. Defaults to 1.0.0. /package | object | no | Package related metadata information. -/package/depends | list of strings | no | List of SONiC packages the service depends on in the format \:[>\|>=\|==\|<\|<=]\. E.g. "swss:\>1.4.1". -/package/breaks | list of strings | no | List of SONiC package the service breaks in the format \:[>\|>=\|==\|<\|<=]\. E.g. "featureX:\<=1.1.0". -/package/sonic-version | string | no | SONiC base image version dependency in the format [>\|>=\|==\|<\|<=]\. E.g. "\>=1.1.0". -/package/changelog | string | no | A path to a file relatively to manifest file that contains a human readably changelog file that will be displayed to the user. -/package/init-config | string | no | Path to SONiC Application Extension Package initial configuration JSON file relatively to manifest file.

This configuration will be appendend to running and boot configuration during installation. -/package/debug-dump | string | no | A command to be executed during system dump.

This field tells the system what to do if user requests "show techsupport" information. /service/ | object | yes | Service management related properties. -/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 "breaks". -/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/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/peer | strnigs | no | The service that is defined as a peer for this package service.

Specifying in this option a service X, will regenerate the /usr/local/bin/X.sh script and set the "PEER" variable. The peer is started, stopped, restarted togather with the current service.

Example:

"syncd" is set as a peer for "swss". -/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/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. -/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-stop-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. -/service/host-namespace | boolean | yes | Multi-ASIC field. Wether a service should run in host namespace. Mandatory field. -/service/asic-namespace | boolean | yes | Multi-ASIC field. Wether a service should run per ASIC namespace. Mandatory field. /container/ | object | no | Container related properties. -/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. -/container/volumes | list of strings | no | List of mounts for a container. The same syntax used for '-v' parameter for "docker run".

Example: "\:\:\". /processes/ | list | no | A list defining processes running inside the container. -/processes/name | string | yes | Process name. -/processes/name/critical | boolean | no | Wether the process is a critical process. Defaults to False. -/processes/name/autorestart | boolean | no | Autorestart by controlled by supervisord. Defaults to False. -/processes/name/command | string | yes | Command to run the process. -/processes/name/start-depends | string | no | Format of "\:\". -/processes/name/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. -/cli | object | no | CLI plugin infromation. *NOTE*: Later will deprecated and replaced with a YANG module file path. -/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. +/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 file path + +Path | Type | Mandatory | Description +--------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- +/package/depends | list of strings | no | List of SONiC packages the service depends on. Defaults to []. +/package/breaks | list of strings | no | List of SONiC package the service breaks. Defaults to []. +/package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. + + +*base-os-constraint* should have the following format: + +``` +[>|>=|==|<|<=|^|!|!=] +``` + +Example: + +```json +{ + "package": { + "base-os-constraint": ">1.0.0" + } +} +``` + + +*depends*, *breaks* fields are defined to be in the following format: + +``` +[>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... +``` + +Examples: + +```json +{ + "package": { + "depends": "swss>=1.0.0,!=1.2.2,<=3.0.0" + } +} +``` + +or + +```json +{ + "package": { + "conflicts": "syncd^1.0.0" + } +} +``` + +### SONiC Package Changelog + + +###### Manifest file path + +Path | Type | Mandatory | Description +--------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- +/package/changelog | dict | no | Changelog dictionary. +/package/changelog/\ | list of strings | no | Changelog messages for a given version. + +Example: + +```json +{ + "package": { + "changelog": { + "1.0.0": [ + "Initial release" + ], + "1.1.0": [ + "Added functionality", + "Bug fixes" + ] + } + } +} +``` + +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 + +- 1.1.0 + + * Added functionality + * Buf fixes + +``` + + ### SONiC Package Docker Container Lifetime -Container lifetime in SONiC is currently controled by systemd. The current SONiC design for container management consists of a +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 autogenerated during SONiC Package installation. The information needed for them to be -autogenerated is defined in the manifest file of a package. +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 file of a package. The relation between those scripts is shown in the below two figures in high level: @@ -624,6 +720,20 @@ Every service that the starting service requires should be started as well and s 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 file 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 "breaks". +/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/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/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/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-stop-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 @@ -650,6 +760,15 @@ docker create {{ docker_run_options }} --name={{docker_container_name}}$DEV {{docker_image_name}} ``` + +###### Manifest file 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 []. + + ### Initial Extension Configuration SONiC Package can provide an the initial configuration it would like to start with after installation. @@ -658,9 +777,25 @@ The JSON file will be loaded into running CONFIG DB and boot CONFIG DB file duri ###### Manifest file path -Path | Type | Description ---------------------------- | --------------------- | ---------------------------------------------------------------------------------------- -/package/init-cfg | string | Path to SONiC Extension Initial Configuration JSON file relatively to manifest file +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 @@ -740,11 +875,11 @@ ave to be also auto-generated from YANG in the future. ###### Manifest file path -Path | Type | Description --------------------------------- | --------------------- | ---------------------------------------------------------------------------------------- -/cli/show-cli-plugin | string | A path to a plugin for sonic-utilities show CLI command -/cli/config-cli-plugin | string | A path to a plugin for sonic-utilities config CLI command -/cli/clear-cli-plugin | string | A path to a plugin for sonic-utilities sonic-clear CLI command +Path | Type | Mandatory | Description +-------------------------------- | --------------------- | ----------|------------------------------------------------------------------------------ +/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 @@ -757,6 +892,42 @@ This feature should be supported by SONiC Application Extension without any chan Processes information is also used to generate monit configuration file based on the *critical* flag. An installation is triggering monit configuration reload by issueing *systemctl reload monit.service*. + +###### Manifest file path + +Path | Type | Mandatory | Description +-------------------------------- | --------------------- | -------------|-------------------------------------------------------------------------- +/processes/ | list | no | A list defining processes running inside the container. +/processes/name | string | yes | Process name. +/processes/name/critical | boolean | no | Wether the process is a critical process. Defaults to False. +/processes/name/command | string | yes | Command to run the process. + +Given the following processes list: + +```json +{ + "processes": { + "cpu-reportd": { + "critical": true, + "command": "/usr/bin/cpu-reportd" + } + } +} +``` + +Will generate the following monit configuration: + +``` +############################################################################### +## Monit configuration for cpu-report container +## process list: +## cpu-reportd +############################################################################### +check program cpu-report|cpu-reportd with path "/usr/bin/process_checker cpu-report cpu-reportd:" + if status != 0 for 5 times within 5 cycles then alert +``` + + ### 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 @@ -795,9 +966,9 @@ during *show techsupport* execution. This file will be included in techsupport u ###### Manifest file path -Path | Value | Description --------------------------------|-------------------|--------------------------------------------------------------------------------- -/package/debug-dump | string | A command to be executed during system dump +Path | Value | Mandatory | Description +-------------------------------|-------------------|-----------|---------------------------------------------------------------------- +/package/debug-dump | string | No | A command to be executed during system dump ### SONiC-2-SONiC upgrade @@ -807,14 +978,12 @@ and do a comparison between currently running and new SONiC image. ###### Package migration scenarios -Package | Version | Action --------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- -Essential package | Installed version in new SONiC image is greater then in current running SONiC image | No actions required, the desired package is already installed in the system -Essential package | Installed version in new SONiC image is less then in current running SONiC image | An image upgrade is required to be done in new SONiC image. If a package is compatible witg new SONiC image version the currently running essential package will migrate to new SONiC image +Package | Version | Action +-------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- Non-essential package | Default version defined in *packages.json* in new SONiC image is greater then in current running SONiC image | Perform a package installation in new SONiC image Non-essential package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation in new SONiC image of currently running package version. If a package is compatible witg new SONiC image version the currently running essential package will migrate to new SONiC image -The old *packages.json* and new *packages.json* are merged togather and updated in new SONiC image. +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*. @@ -838,10 +1007,10 @@ corresponding service files are created per each namespace. *systemd-sonic-gener ###### Manifest file path -Path | Value | Description ----------------------------------|-----------------------|--------------------------------------------------------------------------------- -/service/host-namespace | boolean | Multi-ASIC field. Wether a service should run in host namespace. -/service/asic-namespace | boolean | Multi-ASIC field. Wether a service should run per ASIC namespace. +Path | Value | Mandatory | Description +---------------------------------|---------------------|------------|--------------------------------------------------------------------------------- +/service/host-namespace | boolean | no | Multi-ASIC field. Wether a service should run in host namespace. Default is True. +/service/asic-namespace | boolean | no | Multi-ASIC field. Wether a service should run per ASIC namespace. Default is False. ### Kubernetes & SONiC Application Extension @@ -905,17 +1074,20 @@ systemctl stop {{ service }} ... ``` +*warmboot-finalizer.sh* script must also be templatized and updated based on process *reconciles* flag. + ###### Manifest file path -Path | Value | Description -----------------------------------|-----------------------|--------------------------------------------------------------------------------- -/service/warm-shutdown/ | object | Warm reboot related properties. Used to generate the warm-reboot script. -/service/warm-shutdown/after | lits of strings | 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 | 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 | Fast reboot related properties. Used to generate the fast-reboot script. -/service/fast-shutdown/after | lits of strings | Same as for warm-shutdown. -/service/fast-shutdown/before | lits of strings | Same as for warm-shutdown. +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/\/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. ### SONiC Build System From d07a1e009b1c1a03d8eaf287241584d27972ee7f Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 16 Oct 2020 16:14:03 +0300 Subject: [PATCH 04/38] Update doc about 3rd party images Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 96 ++++++++++++++++--- 1 file changed, 82 insertions(+), 14 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 95473f1093..5596bdbe52 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -37,6 +37,9 @@ - [SONiC-2-SONiC upgrade](#sonic-2-sonic-upgrade) - [Multi-ASIC](#multi-asic) - [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) - [SAI API](#sai-api) - [Restrictions/Limitations](#restrictionslimitations) @@ -686,12 +689,13 @@ manifest file. ##### /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. +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 @@ -702,9 +706,26 @@ The *pre-shutdown-action* might be usefull to execute a specific action to prepa 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 +* 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. +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 @@ -923,7 +944,7 @@ Will generate the following monit configuration: ## process list: ## cpu-reportd ############################################################################### -check program cpu-report|cpu-reportd with path "/usr/bin/process_checker cpu-report cpu-reportd:" +check program cpu-report|cpu-reportd with path "/usr/bin/process_checker cpu-report /usr/bin/cpu-reportd" if status != 0 for 5 times within 5 cycles then alert ``` @@ -981,7 +1002,7 @@ and do a comparison between currently running and new SONiC image. Package | Version | Action -------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- Non-essential package | Default version defined in *packages.json* in new SONiC image is greater then in current running SONiC image | Perform a package installation in new SONiC image -Non-essential package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation in new SONiC image of currently running package version. If a package is compatible witg new SONiC image version the currently running essential package will migrate to new SONiC image +Non-essential package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation 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. @@ -1026,7 +1047,7 @@ Besides of the manifest on the master, the SONiC switch has to have service file 1. Package installed through SONiC package manager. -During package installation these neccessary components will be auto-generated and installed on the switch. The auto-generation must honor new requirements +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. @@ -1043,8 +1064,8 @@ where the container_action script set the container state to "ready" and the con 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 beteen "pending" and "ready" 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. +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. ### Warmboot and Fastboot Design Impact @@ -1089,6 +1110,51 @@ Path | Value | Mandatory | Descrip /service/fast-shutdown/before | lits of strings | no | Same as for warm-shutdown. /processes/\/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. +### 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. 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: +- no controlled container auto-restart feature. According to current design, container is always auto-restarted on container exit. + (Could be changed if we change the container auto-restart design) +- 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. + +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 ./collectd-manifest.json +``` + + + +### 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 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*. @@ -1123,7 +1189,9 @@ No SAI API changes required for this feature. ### Restrictions/Limitations -(TODO) +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 From 386322a53b8c2771d3524d085a7ed4bfa058c094 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 16 Oct 2020 16:23:26 +0300 Subject: [PATCH 05/38] Update security section Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 5596bdbe52..fdcf25123f 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -334,8 +334,8 @@ branching, publishing new images is out of the scope of this document. ### SONiC Application Extension Security Considerations -There are a lots of aspects about security when it comes to running arbitrary 3rd party Dockers on SONiC, -making sure the container is restricted to do only what it is supposed to is a complex functionality peace here. +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. From 51a14a04ae08e63da39edb184ef271e7a7956375 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 16 Oct 2020 16:31:20 +0300 Subject: [PATCH 06/38] move manifest fields for service to service section Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index fdcf25123f..a21a687060 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -686,6 +686,18 @@ The template for creating service files will be placed at */usr/share/sonic/temp through this template outputs a systemd service file with all the unit properties set according to the package's manifest file. + +###### Manifest file 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 "breaks". +/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/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 + + ##### /usr/local/bin/*feature*.sh @@ -746,12 +758,7 @@ after installation all the service scripts under */usr/local/bin/* are re-genera 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 "breaks". -/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/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/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/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-stop-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. From a408f7bc7e42d63195dd248248b123d963e6a968 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 22 Oct 2020 18:39:11 +0300 Subject: [PATCH 07/38] add a NOTE about CONTAINER_FEATURE Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index a21a687060..70cc4274d6 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -162,7 +162,8 @@ SONiC Packages must meet few requirements in order to be a SONiC compatible Dock - Manifest file must exists in a standard location so that the manifest is easily discoverable by the infrastructure. The path chosen for the manifest file is */var/lib/sonic-package/manifest.json* placed in Docker image. -- An application inside container should subscribe for CONTAINER_FEATURE table for auto-restart configuration +- (**NOTE**: This requirement is under discussion and can be removed later) + An application inside container should subscribe for CONTAINER_FEATURE table for auto-restart configuration [Auto-Restart HLD](https://github.com/Azure/SONiC/blob/8a908c2d84f7d58cdaaea2825df13bfda9b73296/doc/monitoring_containers/monitoring_containers.md#223-auto-restart-docker-container). - Requirement on the container state recording by [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)). From 976a04c8295e1f9de15f62891c57fe82c90e1958 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 22 Oct 2020 19:05:19 +0300 Subject: [PATCH 08/38] use digest instead of unsafe tag as an image ref Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 66 ++++++++++++++++--- 1 file changed, 58 insertions(+), 8 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 70cc4274d6..ff80770125 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -154,7 +154,7 @@ Basic definitions: 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 tagged using a version number. +In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are repositories with a set of images. ### SONiC Package @@ -233,7 +233,7 @@ Path | Type | Description /name | string | Name of the package. /name/repository | string | Repository in Docker registry or a local image reference. /name/description | string | Application description field. -/name/default-version | string | A tag which points to a package that will be a default installation candidate if not specified. +/name/default-reference | string | A tag or digest of Docker image that will be a default installation candidate. /name/essential | boolean | A flag if a SONiC package is an essential 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. @@ -247,7 +247,7 @@ A sample of the content in JSON format: "repository": "docker-database", "description": "SONiC database service", "essential": true, - "default-version": "1.0.0", + "default-reference": "1.0.0", "status": "installed", "installed-version": "1.0.0" }, @@ -255,20 +255,20 @@ A sample of the content in JSON format: "repository": "docker-orchagent", "description": "SONiC switch state service", "essential": true, - "default-version": "1.0.0", + "default-reference": "1.0.0", "status": "installed", "installed-version": "2.0.1" }, "cpu-report": { "repository": "Azure/sonic-dhcp-relay", "description": "DHCP relay feature", - "default-version": "1.0.0", + "default-reference": "sha256:5d41c289942008211c2964bca72800f5c9d5ea5aa4057528da617fb36463d4ab", "status": "not-installed" }, "featureXXX": { "repository": "Azure/sonic-snmp", "description": "Simple Network Monitoring Protocol", - "default-version": "1.0.0", + "default-reference": "1.0.0", "status": "installed", "installed-version": "1.0.0" } @@ -281,6 +281,9 @@ OS at built time the *packages.json* also includes the repositories that are ava 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. + Once a Docker becomes a SONiC package, user will have two options: - SONiC build system will be extended with a build parameter "INCLUDE_$PACKAGE=y|n". If this parameter is set to "y", a package will be @@ -299,6 +302,9 @@ The schema for version is in the format of *\${MAJOR}.\${MINOR}.\${PATCH}* versi 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. + The base OS has also have a version number that follows the same rules of semantic versioning so that a package can define a dependency on base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "base_os_compatibility_version" that follows semantic versioning schema. This version is in addition to SONiC version we have today. @@ -409,13 +415,29 @@ dhcp-relay Azure/dhcp-relay DHCP relay service N/A Not #### Repository management ``` -admin@sonic:~$ sudo sonic-package-manager add [NAME] [REPOSITORY] --description=[STRING] --default-version=[STRING] +admin@sonic:~$ sudo sonic-package-manager add [NAME] [REPOSITORY] --description=[STRING] --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] [REFERENCE] + + Install SONiC package. + +Options: + -y, --yes Answer yes for any prompt. + -f, --force Force installation. + --help Show this message and exit +``` + + +###### Examples + ``` admin@sonic:~$ sudo sonic-package-manager install cpu-report ``` @@ -427,6 +449,17 @@ 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. ``` @@ -443,7 +476,7 @@ In the above example the following entry is added to *packages.json*: { "featureA": { "repository": "featureA", - "default-version": "1.0.0", + "default-reference": "1.0.0", "installed-version": "1.0.0", "status": "installed" } @@ -462,6 +495,22 @@ WARN: feature depends on syncd^1.1.1 while installed version is 1.0.5. Ignoring. #### Package Upgrade +``` +admin@sonic:~$ sudo sonic-package-manager upgrade --help + +Usage: sonic-package-manager upgrade [OPTIONS] [REFERENCE] + + Upgrade SONiC package. + +Options: + -y, --yes Answer yes for any prompt. + -f, --force Force upgrade. + --help Show this message and exit +``` + + +###### Examples + The command line example for package upgrade: ``` admin@sonic:~$ sudo sonic-package-manager upgrade ==1.5.1 @@ -554,6 +603,7 @@ can be installed at any given time. Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- +/package/version | string | yes | Version of the package. /package/depends | list of strings | no | List of SONiC packages the service depends on. Defaults to []. /package/breaks | list of strings | no | List of SONiC package the service breaks. Defaults to []. /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. From 5531fc24499cdf68a706583b2a4bcb5b9b3b8ecd Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 22 Oct 2020 21:12:17 +0300 Subject: [PATCH 09/38] update on config reload Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 40 +++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index ff80770125..6ffd8a6dc4 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -1028,9 +1028,43 @@ Application should be using swss-common library or swsssdk which take care of di ### Configuration Reload -SONiC Packages should restart on initiated *config reload* commands. Service management and services dependencies management in SONiC is complex. -*config reload* command has a 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. This list becomes dynamic with introduction of packages. +*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 From 534e542ec928a619a99a220f720eb81753ba8dd9 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 23 Oct 2020 12:42:04 +0300 Subject: [PATCH 10/38] extend changelog with more fields. Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 42 +++++++++++++------ 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 6ffd8a6dc4..aa7464382a 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -657,10 +657,14 @@ or ###### Manifest file path -Path | Type | Mandatory | Description ---------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- -/package/changelog | dict | no | Changelog dictionary. -/package/changelog/\ | list of strings | no | Changelog messages for a given version. +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: @@ -668,13 +672,21 @@ Example: { "package": { "changelog": { - "1.0.0": [ - "Initial release" - ], - "1.1.0": [ - "Added functionality", - "Bug fixes" - ] + "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" + } } } } @@ -685,15 +697,19 @@ This information will be useful for user, so a command to show changelog for a p ``` admin@sonic:~$ sonic-package-manager show package changelog -- 1.0.0: +1.0.0: * Initial release -- 1.1.0 +-- 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 + ``` From ba72a43e578311d3787dcedfd79fb4a9dce86324 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 23 Oct 2020 12:55:20 +0300 Subject: [PATCH 11/38] add section about container restrictions Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index aa7464382a..4b0cb80794 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -25,6 +25,7 @@ - [Manifest File](#manifest-file) - [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) @@ -712,6 +713,13 @@ admin@sonic:~$ sonic-package-manager show package changelog ``` +### 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 From 1175fdac962f1d8d8269313a39786dad1fd64e1c Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 23 Oct 2020 12:56:14 +0300 Subject: [PATCH 12/38] Version of manifest file definition -> Version of manifest schema definition Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 4b0cb80794..ce10c88553 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -571,7 +571,7 @@ The following table shows the top-level objects in the manifest. In the next sec Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- -/version | string | no | Version of manifest file definition. Defaults to 1.0.0. +/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. From 0d6b681bb3b455bbb03608f7e1ae3deafe5fe91c Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 23 Oct 2020 15:34:47 +0300 Subject: [PATCH 13/38] reorganize sections order Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 121 +++++++++--------- 1 file changed, 61 insertions(+), 60 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index ce10c88553..f04338dc40 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -35,8 +35,9 @@ - [Multi-DB support](#multi-db-support) - [Configuration Reload](#configuration-reload) - [System Dump](#system-dump) -- [SONiC-2-SONiC upgrade](#sonic-2-sonic-upgrade) - [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) @@ -355,8 +356,6 @@ are secured and trusted. ### Configuration and management -N/A (TODO) - #### CLI Enhancements @@ -1107,6 +1106,63 @@ 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 file, +corresponding service files are created per each namespace. *systemd-sonic-generator* is invoked to create and install service units per each namespace. + + +###### Manifest file path + +Path | Value | Mandatory | Description +---------------------------------|---------------------|------------|--------------------------------------------------------------------------------- +/service/host-namespace | boolean | no | Multi-ASIC field. Wether a service should run in host namespace. Default is True. +/service/asic-namespace | 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. + +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 file 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/\/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 @@ -1117,8 +1173,8 @@ and do a comparison between currently running and new SONiC image. Package | Version | Action -------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- -Non-essential package | Default version defined in *packages.json* in new SONiC image is greater then in current running SONiC image | Perform a package installation in new SONiC image -Non-essential package | Default version defined in *packages.json* in new SONiC image is less then in current running SONiC image | Perform a package installation in new SONiC image of currently running package version. +Non-essential 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-essential 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. @@ -1135,19 +1191,6 @@ An option to skip migrating packages will be added for users that want to have a admin@sonic:~$ sudo sonic-installer install -y sonic.bin --no-package-migration ``` -### 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 file, -corresponding service files are created per each namespace. *systemd-sonic-generator* is invoked to create and install service units per each namespace. - - -###### Manifest file path - -Path | Value | Mandatory | Description ----------------------------------|---------------------|------------|--------------------------------------------------------------------------------- -/service/host-namespace | boolean | no | Multi-ASIC field. Wether a service should run in host namespace. Default is True. -/service/asic-namespace | boolean | no | Multi-ASIC field. Wether a service should run per ASIC namespace. Default is False. ### Kubernetes & SONiC Application Extension @@ -1183,48 +1226,6 @@ The case describe the scenario when the user is setting a label via "config kube 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. - -### 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. - -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 file 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/\/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. ### 3rd party Docker images From 51bcc45b88074b608e70c8e64672beb3048b59c7 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 30 Oct 2020 11:03:40 +0200 Subject: [PATCH 14/38] Change 'essential' -> 'built-in' to indicate the purpose of this flag more clearly. Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 42 +++++++++---------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index f04338dc40..1eb664d05f 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -14,7 +14,7 @@ - [Architecture Design](#architecture-design) - [High-Level Design](#high-level-design) - [SONiC Package](#sonic-package) -- [Essential SONiC Packages](#essential-sonic-packages) +- [Built-In SONiC Packages](#built-in-sonic-packages) - [SONiC Package Management](#sonic-package-management) - [SONiC Package Database](#sonic-package-database) - [SONiC Base Image and Packages Versioning](#sonic-base-image-and-packages-versioning) @@ -180,16 +180,16 @@ The idea is to auto-generate most of the components on the host OS based on *man The scope of this document is limited to SONiC compatible Docker images only. -### Essential SONiC Packages +### Built-In SONiC Packages -Every SONiC Docker image can be converted to be a SONiC Package, although it is naturally to expect that SONiC OS comes with a set of Docker images -pre-installed. Those Docker images are considered to be essential. Like a debian essential package, SONiC essential package cannot be removed from the -system, but also, it cannot be upgraded without an image upgrade. +Every SONiC Docker image can be converted to be a SONiC Package, although a subset of SONiC Dockers will be converted to be a SONiC Package at first phase. +These are Dockers for which it might be comlicated to separate the OS part from the Docker image itself. Those Docker images are considered to be built-in. +Built-in packages cannot be removed and upgraded as SONiC Packages and the infrastructure will mark with a 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 -essential and then removing essential flag for images that became a SONiC packages. +build-in and then removing this flag for images that become a SONiC packages. -The following list enumerates essential Docker containers: +The following list enumerates built-in Docker containers, that cannot be converted to SONiC Package as part of phase 1: - database - syncd - swss @@ -197,10 +197,8 @@ The following list enumerates essential Docker containers: 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. - -Those containers do not provide an individual feature, monitoring service or networking protocol implementation but rather are required -to run other features. +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. ### SONiC Package Management @@ -236,7 +234,7 @@ Path | Type | Description /name/repository | string | Repository in Docker registry or a local image reference. /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/essential | boolean | A flag if a SONiC package is an essential package. +/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. @@ -248,7 +246,7 @@ A sample of the content in JSON format: "database": { "repository": "docker-database", "description": "SONiC database service", - "essential": true, + "built-in": true, "default-reference": "1.0.0", "status": "installed", "installed-version": "1.0.0" @@ -256,7 +254,7 @@ A sample of the content in JSON format: "swss": { "repository": "docker-orchagent", "description": "SONiC switch state service", - "essential": true, + "built-in": true, "default-reference": "1.0.0", "status": "installed", "installed-version": "2.0.1" @@ -404,9 +402,9 @@ Commands: admin@sonic:~$ sonic-package-manager list Name Repository Description Version Status ----------- --------------------- ------------------------ ------------ -------------- -database docker-database SONiC database 1.0.0 Essential -swss docker-orchagent Switch state service 1.0.0 Essential -syncd docker-syncd-vs SONiC ASIC sync service 1.0.0 Essential +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 ``` @@ -565,7 +563,7 @@ new one and start the service. The sequence is shown on the figure below: ### Manifest File -Every SONiC Package that is not an essential package must provide a *manifest.json* file in image filesystem under */var/lib/sonic-package/manifest.json*. +Every SONiC Package that is not an built-in package must provide a *manifest.json* file in image filesystem under */var/lib/sonic-package/manifest.json*. 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 @@ -1032,8 +1030,8 @@ check program cpu-report|cpu-reportd with path "/usr/bin/process_checker cpu-rep ### 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 -is not marked as essential it must be treated in the same way as any optional SONiC feature. +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) @@ -1173,8 +1171,8 @@ and do a comparison between currently running and new SONiC image. Package | Version | Action -------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------- -Non-essential 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-essential 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. +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. From 9493bf434d78150e9c0bc24a3d1fd104cb01a325 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 30 Oct 2020 13:09:42 +0200 Subject: [PATCH 15/38] save manifest json in a docker image label Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 56 +++++++++++-------- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 1eb664d05f..c71bec08cf 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -22,7 +22,7 @@ - [Configuration and management](#configuration-and-management) - [SONiC Package Uninstallation Flow](#sonic-package-uninstallation-flow) - [SONiC Package Upgrade Flow](#sonic-package-upgrade-flow) -- [Manifest File](#manifest-file) +- [Manifest](#manifest) - [SONiC Package Installation](#sonic-package-installation) - [SONiC Package Changelog](#sonic-package-changelog) - [SONiC Docker Container Resource restrictions](#sonic-docker-container-resource-restrictions) @@ -162,8 +162,7 @@ In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are reposito SONiC Packages must meet few requirements in order to be a SONiC compatible Docker image. -- Manifest file must exists in a standard location so that the manifest is easily discoverable by the infrastructure. - The path chosen for the manifest file is */var/lib/sonic-package/manifest.json* placed in Docker image. +- A package must provide a manifest as part of the Docker image. - (**NOTE**: This requirement is under discussion and can be removed later) An application inside container should subscribe for CONTAINER_FEATURE table for auto-restart configuration [Auto-Restart HLD](https://github.com/Azure/SONiC/blob/8a908c2d84f7d58cdaaea2825df13bfda9b73296/doc/monitoring_containers/monitoring_containers.md#223-auto-restart-docker-container). @@ -176,7 +175,7 @@ SONiC Packages must meet few requirements in order to be a SONiC compatible Dock 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.json* file provided by SONiC Package. +The idea is to auto-generate most of the components on the host OS based on *manifest* provided by SONiC Package. The scope of this document is limited to SONiC compatible Docker images only. @@ -392,7 +391,7 @@ Options: --help Show this message and exit Commands: - manifest Print package manifest + manifest Print package manifest. changelog Print package changelog. ``` @@ -561,9 +560,22 @@ new one and start the service. The sequence is shown on the figure below: Figure 5. SONiC Package Upgrade Flow

-### Manifest File +### 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. -Every SONiC Package that is not an built-in package must provide a *manifest.json* file in image filesystem under */var/lib/sonic-package/manifest.json*. 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 @@ -597,7 +609,7 @@ can be installed at any given time. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- @@ -653,7 +665,7 @@ or ### SONiC Package Changelog -###### Manifest file path +###### Manifest path Path | Type | Mandatory | Description --------------------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- @@ -756,10 +768,10 @@ The relation between those scripts is shown in the below two figures in high lev 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 file. +manifest. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- @@ -826,7 +838,7 @@ is doing a cold start. This means when a new package is installed it might affec after installation all the service scripts under */usr/local/bin/* are re-generated. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- @@ -841,7 +853,7 @@ The script under /usr/bin/ starts, stops or waits for container exit. This scrip [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 file. Besides of options +*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: @@ -861,7 +873,7 @@ docker create {{ docker_run_options }} ``` -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- @@ -875,7 +887,7 @@ SONiC Package can provide an the initial configuration it would like to start wi The JSON file will be loaded into running CONFIG DB and boot CONFIG DB file during installation. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description --------------------------- | --------------------- | ----------|----------------------------------------------------------------------------- @@ -973,7 +985,7 @@ e.g. DHCP Helper Address may or may not be present in CLI depending on installed ave to be also auto-generated from YANG in the future. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description -------------------------------- | --------------------- | ----------|------------------------------------------------------------------------------ @@ -993,7 +1005,7 @@ Processes information is also used to generate monit configuration file based on monit configuration reload by issueing *systemctl reload monit.service*. -###### Manifest file path +###### manifest path Path | Type | Mandatory | Description -------------------------------- | --------------------- | -------------|-------------------------------------------------------------------------- @@ -1094,11 +1106,11 @@ 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 file. A command should write its debug dump to stdout which will be gzip-ed into a 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 file path +###### manifest path Path | Value | Mandatory | Description -------------------------------|-------------------|-----------|---------------------------------------------------------------------- @@ -1107,11 +1119,11 @@ Path | Value | Mandatory | Description ### 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 file, +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 file path +###### manifest path Path | Value | Mandatory | Description ---------------------------------|---------------------|------------|--------------------------------------------------------------------------------- @@ -1148,7 +1160,7 @@ systemctl stop {{ service }} *warmboot-finalizer.sh* script must also be templatized and updated based on process *reconciles* flag. -###### Manifest file path +###### manifest path Path | Value | Mandatory | Description ----------------------------------|-----------------------|------------|-------------------------------------------------------------------- From d19e3c816bae8ec0d865cb78a88c532e1fd5e2ab Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Mon, 2 Nov 2020 13:43:29 +0200 Subject: [PATCH 16/38] updates hld Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index c71bec08cf..19fc7299e7 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -163,10 +163,8 @@ In the above figure *Azure/sonic-dhcp-relay* and *Azure/sonic-snmp* are reposito 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. -- (**NOTE**: This requirement is under discussion and can be removed later) - An application inside container should subscribe for CONTAINER_FEATURE table for auto-restart configuration - [Auto-Restart HLD](https://github.com/Azure/SONiC/blob/8a908c2d84f7d58cdaaea2825df13bfda9b73296/doc/monitoring_containers/monitoring_containers.md#223-auto-restart-docker-container). - Requirement on the container state recording by [Kubernetes HLD](https://github.com/Azure/SONiC/blob/698e8d7991c0ca3d21b4488cf336efcfe891ef9a/doc/kubernetes/Kuberenetes-support.md)). +- The DockerHub or a private registry containing SONiC images is always accessible from the SONiC switch. ###### Figure 2. High Level Overview of SONiC Package integration @@ -203,7 +201,7 @@ into base OS. 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 are *packages.json* file as well as a directory per each SONiC package with a package metadata. A database will have the following structure: +There is a *packages.json* file representing local database of packages. ``` / @@ -211,9 +209,6 @@ There are *packages.json* file as well as a directory per each SONiC package wit lib/ sonic-packages/ packages.json - snmp/ - lldp/ - dhcp-relay/ ``` ###### Example directory structure of SONiC Package Manager library @@ -349,7 +344,13 @@ are secured and trusted. 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. -- Follows the Debian approach which does not have any security guard or restrictions about packages the user is installing. + +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 @@ -735,7 +736,7 @@ container with existing infrastructure. Every SONiC Package will automatically s 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 file of a package. +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: @@ -1208,7 +1209,7 @@ admin@sonic:~$ sudo sonic-installer install -y sonic.bin --no-package-migration 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 file as it cat provide all the info about +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. @@ -1257,7 +1258,8 @@ Default manifest: ``` 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. This settings have to be present in *container* properties in manifest. +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: @@ -1266,14 +1268,16 @@ 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. +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 ./collectd-manifest.json +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 From fb5cf40d2bc7c02eca8b14d88ffcfab588bc6fae Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Tue, 3 Nov 2020 15:33:02 +0200 Subject: [PATCH 17/38] updated figures Signed-off-by: Stepan Blyshchak --- .../img/install-flow.svg | 265 ++++++++---------- .../img/upgrade-flow.svg | 237 +++++++--------- .../sonic-application-extention-hld.md | 2 +- 3 files changed, 220 insertions(+), 284 deletions(-) mode change 100644 => 100755 doc/sonic-application-extention/img/install-flow.svg mode change 100644 => 100755 doc/sonic-application-extention/img/upgrade-flow.svg diff --git a/doc/sonic-application-extention/img/install-flow.svg b/doc/sonic-application-extention/img/install-flow.svg old mode 100644 new mode 100755 index 05d1bff819..bab72c398f --- a/doc/sonic-application-extention/img/install-flow.svg +++ b/doc/sonic-application-extention/img/install-flow.svg @@ -3,7 +3,7 @@ + viewBox="0 0 717.665 473.535" xml:space="preserve" color-interpolation-filters="sRGB" class="st16"> @@ -240,7 +239,7 @@ install <package> - + Повідомлення.44 docker pull <repo>:<tag> @@ -252,9 +251,9 @@ - + docker pull <repo>:<tag> - + Повідомлення.45 pull @@ -266,9 +265,9 @@ - + pull - + Повернуто повідомлення return @@ -279,10 +278,10 @@ - - + + return - + Повернуто повідомлення.48 return @@ -293,10 +292,10 @@ - - + + return - + Повідомлення.50 docker tag <repo>:<tag>\ <repo>:latest @@ -308,10 +307,10 @@ - + docker tag <repo>:<tag>\ <repo>:latest - + Повернуто повідомлення.52 @@ -319,9 +318,9 @@ - + - + Повідомлення.53 docker run <repo>:latest sleep @@ -335,7 +334,7 @@ docker run <repo>:latest sleep - + Повернуто повідомлення.54 @@ -343,65 +342,9 @@ - + - - Повідомлення.55 - docker cp /var/lib/sonic-package - - - - - - - - - - - docker cp /var/lib/sonic-package - - Повідомлення.56 - copy package metadata folder - - - - - - - - - - - copy package metadata folder - - Повернуто повідомлення.57 - return - - - - - - - - - - - return - - Повернуто повідомлення.58 - return - - - - - - - - - - - return - + Повідомлення.59 render host scripts/files to host FS reload host services con... @@ -413,10 +356,10 @@ - + render host scripts/files to host FSreload host services configuration - + Повернуто повідомлення.60 return @@ -427,10 +370,10 @@ - - + + return - + Повідомлення.61 Load feature initial configuration to running DB @@ -442,9 +385,9 @@ - + Load feature initial configuration to running DB - + Повернуто повідомлення.62 return @@ -455,10 +398,10 @@ - + return - + Повернуто повідомлення.63 return @@ -469,80 +412,73 @@ - + return - + Активація - + - + Активація.65 - + - + Активація.66 - + - + Активація.67 - + - + Активація.68 - + - + Активація.69 - + - - Активація.70 - - - - - - + Активація.71 - + - + Активація.72 - + - + Активація.73 - + - + Повідомлення.74 Register new feature in FEATURE table (runnig & persistent) @@ -556,7 +492,7 @@ Register new feature in FEATURE table (runnig & persistent) - + Повернуто повідомлення.75 return @@ -567,17 +503,17 @@ - + return - + Активація.76 - + - + Повідомлення на себе Check package dependencies/conflicts @@ -587,13 +523,13 @@ - - - - Check package dependencies/conflicts - + + + + Check package dependencies/conflicts + Повідомлення на себе.78 - Update installation status/version in DB + Update installation status in DB @@ -601,11 +537,11 @@ - + - - Update installation status/version in DB - + + Update installation status in DB + Повідомлення.79 Load feature initial configuration to persistent DB (/etc/son... @@ -617,9 +553,9 @@ - + Load feature initial configuration to persistent DB (/etc/sonic/config_db.json & /etc/sonic/init_cfg.json) - + Повернуто повідомлення.80 return @@ -630,25 +566,25 @@ - + return - + Активація.82 - + - + Інший фрагмент.152 - - + + - + Аркуш.87 alt @@ -664,9 +600,9 @@ - - alt - + + alt + Аркуш.88 requirements are met @@ -674,8 +610,43 @@ - requirements arerequirements 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/upgrade-flow.svg b/doc/sonic-application-extention/img/upgrade-flow.svg old mode 100644 new mode 100755 index fa52ef1955..8d22f4f4fc --- a/doc/sonic-application-extention/img/upgrade-flow.svg +++ b/doc/sonic-application-extention/img/upgrade-flow.svg @@ -15,10 +15,10 @@ .st5 {fill:#feffff;font-family:Calibri;font-size:1.00001em;font-weight:bold} .st6 {marker-end:url(#mrkr4-85);stroke:#70ad47;stroke-linecap:round;stroke-linejoin:round;stroke-width:1} .st7 {fill:#70ad47;fill-opacity:1;stroke:#70ad47;stroke-opacity:1;stroke-width:0.23584905660377} - .st8 {fill:#ffffff;stroke:none;stroke-linecap:butt} + .st8 {fill:#ffffff;stroke:none;stroke-linecap:butt;stroke-width:7.2} .st9 {fill:#61973d;font-family:Calibri;font-size:0.666664em} - .st10 {fill:#ffffff;stroke:none;stroke-linecap:butt;stroke-width:7.2} - .st11 {marker-end:url(#mrkr3-107);stroke:#70ad47;stroke-dasharray:7,5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1} + .st10 {marker-end:url(#mrkr3-107);stroke:#70ad47;stroke-dasharray:7,5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1} + .st11 {fill:#ffffff;stroke:none;stroke-linecap:butt} .st12 {fill:#70ad47;stroke:#70ad47;stroke-linecap:round;stroke-linejoin:round;stroke-width:1} .st13 {fill:#ffffff;fill-opacity:0;stroke:#ebf1e8;stroke-width:0.75} .st14 {fill:#ffffff;stroke:#ebf1e8;stroke-width:0.75} @@ -226,7 +226,7 @@ User - + Повідомлення install <package> @@ -236,11 +236,11 @@ - - - - install <package> - + + + + install <package> + Повідомлення.32 docker pull <repo>:<tag> @@ -252,9 +252,9 @@ - + docker pull <repo>:<tag> - + Повідомлення.45 pull @@ -266,9 +266,9 @@ - + pull - + Повернуто повідомлення return @@ -279,10 +279,10 @@ - - + + return - + Повернуто повідомлення.35 return @@ -293,10 +293,10 @@ - + return - + Повідомлення.53 docker run <repo>:<tag> sleep @@ -308,9 +308,9 @@ - + docker run <repo>:<tag> sleep - + Повернуто повідомлення.54 @@ -318,65 +318,9 @@ - + - - Повідомлення.55 - docker cp /var/lib/sonic-package - - - - - - - - - - - docker cp /var/lib/sonic-package - - Повідомлення.56 - copy package metadata folder to /tmp/<feature>_upgrade/ - - - - - - - - - - - copy package metadata folder to /tmp/<feature>_upgrade/ - - Повернуто повідомлення.57 - return - - - - - - - - - - - return - - Повернуто повідомлення.58 - return - - - - - - - - - - - return - + Повідомлення.44 render host scripts/files to host FS /tmp/<feature>_upgrade/ @@ -388,9 +332,9 @@ - + render host scripts/files to host FS /tmp/<feature>_upgrade/ - + Повернуто повідомлення.45 return @@ -401,10 +345,10 @@ - - + + return - + Повідомлення.61 systemctl stop <feature> @@ -418,7 +362,7 @@ systemctl stop <feature> - + Повернуто повідомлення.62 return @@ -429,10 +373,10 @@ - - + + return - + Повернуто повідомлення.63 return @@ -443,73 +387,59 @@ - - + + return - + Активація - + Активація.65 - + Активація.51 - + Активація.67 - + Активація.69 - - Активація.70 - - - - - - - Активація.71 - - - - - - + Активація.72 - + Активація.73 - + Повідомлення.74 systemctl start <feature> @@ -521,9 +451,9 @@ - + systemctl start <feature> - + Повернуто повідомлення.75 return @@ -534,17 +464,17 @@ - + return - + Активація.76 - + Повідомлення на себе Check package dependencies/conflicts @@ -558,7 +488,7 @@ Check package dependencies/conflicts - + Повідомлення на себе.78 Update installation status/version in DB @@ -570,9 +500,9 @@ - + Update installation status/version in DB - + Повідомлення.79 move /tmp/<feature>_upgrade/ to / reload host services config... @@ -587,7 +517,7 @@ move /tmp/<feature>_upgrade/ to /reload host services configuration - + Повернуто повідомлення.80 return @@ -598,25 +528,25 @@ - - + + return - + Активація.82 - + Інший фрагмент.152 - - + + - + Аркуш.69 alt @@ -634,7 +564,7 @@ alt - + Аркуш.70 requirements are met @@ -645,7 +575,7 @@ requirements aremet - + Повідомлення.50 docker tag <repo>:<tag>\ <repo>:latest @@ -660,7 +590,7 @@ docker tag <repo>:<tag>\ <repo>:latest - + Повернуто повідомлення.52 @@ -668,16 +598,16 @@ - + - + Активація.68 - + Повідомлення.140 docker rmi -f <repo>:<old-tag> @@ -691,7 +621,7 @@ docker rmi -f <repo>:<old-tag> - + Повернуто повідомлення.142 @@ -699,14 +629,49 @@ - + - + Активація.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 index 19fc7299e7..f9880b82ee 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -20,7 +20,6 @@ - [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 Uninstallation Flow](#sonic-package-uninstallation-flow) - [SONiC Package Upgrade Flow](#sonic-package-upgrade-flow) - [Manifest](#manifest) - [SONiC Package Installation](#sonic-package-installation) @@ -537,6 +536,7 @@ No CONFIG DB changes required for this feature. Figure 3. SONiC Package Installation Flow

+ ### SONiC Package Uninstallation Flow From 066a6e28cddcae8488b9b82f1b6b70567cd3c48b Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Tue, 3 Nov 2020 16:25:10 +0200 Subject: [PATCH 18/38] update on 3rd party dockers Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index f9880b82ee..73a4ba877c 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -174,8 +174,6 @@ SONiC Packages must meet few requirements in order to be a SONiC compatible Dock The idea is to auto-generate most of the components on the host OS based on *manifest* provided by SONiC Package. -The scope of this document is limited to SONiC compatible Docker images only. - ### Built-In SONiC Packages Every SONiC Docker image can be converted to be a SONiC Package, although a subset of SONiC Dockers will be converted to be a SONiC Package at first phase. @@ -1263,11 +1261,8 @@ 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: -- no controlled container auto-restart feature. According to current design, container is always auto-restarted on container exit. - (Could be changed if we change the container auto-restart design) - 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: From 727297d6babdbad670e621e5d62606b55abbfab3 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Tue, 10 Nov 2020 14:08:43 +0200 Subject: [PATCH 19/38] update sonic build section Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 89 ++++++++++++++++--- 1 file changed, 77 insertions(+), 12 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 73a4ba877c..b954786902 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -1283,9 +1283,33 @@ This will require to build a new image based on existing 3rd party Docker image ### SONiC Build System -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 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-buildenv* will have common SONiC packages required to build SONiC application extension and will be a minimal version of sonic-slave container: +*sonic-sdk* will be based on *docker-config-engine* with addition of packages needed at run time: + +- libhiredis +- libnl* +- libswsscommon +- 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 @@ -1296,18 +1320,59 @@ SONiC build system will provide three docker images to be used as a base to buil - libsaimetadata-dev - tools, etc. -*sonic-sdk* will be based on *docker-config-engine* with addition of packages needed at run time: + +#### SONiC SDK Build Metadata -- libhiredis -- libnl* -- libswsscommon -- libsairedis -- libsairedis -- libsaimeta -- libsaimetadata +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. +However, the packages dependencies contraints do not derive from these labels, instead a package maintainer +must test and verify the package on a set of version range. + +The following list of labels are going to be used: + +``` +LABEL com.azure.sonic.sdk.versions.base-os +LABEL com.azure.sonic.sdk.versions.config-engine +LABEL com.azure.sonic.sdk.versions.database +LABEL com.azure.sonic.sdk.versions.swss +LABEL com.azure.sonic.sdk.versions.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 -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 application extension it should not be added to this list. +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 From 0180680d68ac5fb5facb1cf31efc6c919566e9de Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 26 Nov 2020 15:48:58 +0200 Subject: [PATCH 20/38] add semver <-> docker tag conversion rules Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index b954786902..8a68e9a9d1 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -294,7 +294,7 @@ identifiers and build id, like *1.0.0-dev+153*, that can be used for master bran 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. +to follow a commonly used convention in Docker by tagging images with a version number [See next section]. The base OS has also have a version number that follows the same rules of semantic versioning so that a package can define a dependency on base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "base_os_compatibility_version" that follows semantic @@ -330,6 +330,25 @@ This version is used to tag a Docker image when installing SONiC package in SONi 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. From 5f711271ddb3b1aaed3a3ddb46257f59968a102a Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Thu, 26 Nov 2020 15:52:39 +0200 Subject: [PATCH 21/38] a note added for syncd pre-shutdown in warm-reboot section Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 8a68e9a9d1..0894ddd6d9 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -1162,6 +1162,8 @@ A services shutdown is an ordered executions of *systemctl stop {{ service }}* c 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. From 4901ce86fa1404afc3e4ad77ff3bcc0d004378be Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Mon, 14 Dec 2020 21:10:45 +0200 Subject: [PATCH 22/38] align doc to latest changes --- .../sonic-application-extention-hld.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 0894ddd6d9..936cb104bd 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -797,7 +797,9 @@ Path | Type | Mandatory | Descri /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/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 +/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. @@ -897,6 +899,11 @@ Path | Type | Mandatory | Descri --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- /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/environment | dict | no | Environment variables for Docker container (key=value). Defaults to {}. ### Initial Extension Configuration @@ -1145,8 +1152,8 @@ corresponding service files are created per each namespace. *systemd-sonic-gener Path | Value | Mandatory | Description ---------------------------------|---------------------|------------|--------------------------------------------------------------------------------- -/service/host-namespace | boolean | no | Multi-ASIC field. Wether a service should run in host namespace. Default is True. -/service/asic-namespace | boolean | no | Multi-ASIC field. Wether a service should run per ASIC namespace. Default is False. +/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 From 26dbcdd32e627d720d31881c5ff2e92c7c8a07bd Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Wed, 16 Dec 2020 13:02:39 +0200 Subject: [PATCH 23/38] align the doc --- .../sonic-application-extention-hld.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 936cb104bd..97b75f0ac1 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -675,7 +675,7 @@ or ```json { "package": { - "conflicts": "syncd^1.0.0" + "breaks": "syncd^1.0.0" } } ``` @@ -1032,12 +1032,12 @@ monit configuration reload by issueing *systemctl reload monit.service*. ###### manifest path -Path | Type | Mandatory | Description --------------------------------- | --------------------- | -------------|-------------------------------------------------------------------------- -/processes/ | list | no | A list defining processes running inside the container. -/processes/name | string | yes | Process name. -/processes/name/critical | boolean | no | Wether the process is a critical process. Defaults to False. -/processes/name/command | string | yes | Command to run the process. +Path | Type | Mandatory | Description +--------------------------------- | --------------------- | -------------|-------------------------------------------------------------------------- +/processes/ | list | no | A list defining processes running inside the container. +/processes/[index]/name | string | yes | Process name. +/processes/[index]/critical | boolean | no | Wether the process is a critical process. Defaults to False. +/processes/[index]/command | string | yes | Command to run the process. Given the following processes list: From 2fca28f983a12effe2a5fc853984bafe392ef907 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Wed, 16 Dec 2020 13:07:16 +0200 Subject: [PATCH 24/38] align doc --- .../sonic-application-extention-hld.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 97b75f0ac1..f61681d7b6 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -1044,7 +1044,8 @@ Given the following processes list: ```json { "processes": { - "cpu-reportd": { + { + "name": "cpu-report", "critical": true, "command": "/usr/bin/cpu-reportd" } @@ -1197,7 +1198,7 @@ Path | Value | Mandatory | Descrip /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/\/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. +/processes/[index]/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. ### SONiC-2-SONiC upgrade From 8a56a3e1dfd5e687956dab67cadd67dc5e156571 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Mon, 25 Jan 2021 18:43:53 +0200 Subject: [PATCH 25/38] align design Signed-off-by: Stepan Blyshchak --- .../sonic-application-extention-hld.md | 172 ++++++++++++------ 1 file changed, 112 insertions(+), 60 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 0894ddd6d9..590cefebd1 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -17,6 +17,7 @@ - [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) @@ -24,7 +25,7 @@ - [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 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) @@ -41,7 +42,7 @@ - [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) +- [SONiC Build System](#sonic-build-system-1) - [SAI API](#sai-api) - [Restrictions/Limitations](#restrictionslimitations) - [Testing Requirements/Design](#testing-requirementsdesign) @@ -163,7 +164,6 @@ SONiC Packages must meet few requirements in order to be a SONiC compatible Dock - 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)). -- The DockerHub or a private registry containing SONiC images is always accessible from the SONiC switch. ###### Figure 2. High Level Overview of SONiC Package integration @@ -176,14 +176,14 @@ The idea is to auto-generate most of the components on the host OS based on *man ### Built-In SONiC Packages -Every SONiC Docker image can be converted to be a SONiC Package, although a subset of SONiC Dockers will be converted to be a SONiC Package at first phase. -These are Dockers for which it might be comlicated to separate the OS part from the Docker image itself. Those Docker images are considered to be built-in. -Built-in packages cannot be removed and upgraded as SONiC Packages and the infrastructure will mark with a built-in flag. +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. +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 built-in Docker containers, that cannot be converted to SONiC Package as part of phase 1: +The following list enumerates some built-in Docker containers, that cannot become SONiC Package at current stage: - database - syncd - swss @@ -194,6 +194,8 @@ E.g. syncd contains vendor SDK which usually means there is a kernel driver inst 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. @@ -211,7 +213,7 @@ There is a *packages.json* file representing local database of packages. ###### 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 +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 @@ -220,14 +222,15 @@ The */var/lib/sonic-packages/packages.json* file is used as a persistent databas Schema definition for *packages.json* file is following: Path | Type | Description ------------------------- | ------------------ | ------------------------------------------- +------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------ /name | string | Name of the package. -/name/repository | string | Repository in Docker registry or a local image reference. -/name/description | string | Application description field. +/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. +/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: @@ -248,20 +251,21 @@ A sample of the content in JSON format: "built-in": true, "default-reference": "1.0.0", "status": "installed", - "installed-version": "2.0.1" + "installed-version": "1.0.0" }, - "cpu-report": { + "dhcp-relay": { "repository": "Azure/sonic-dhcp-relay", "description": "DHCP relay feature", "default-reference": "sha256:5d41c289942008211c2964bca72800f5c9d5ea5aa4057528da617fb36463d4ab", "status": "not-installed" }, - "featureXXX": { + "snmp": { "repository": "Azure/sonic-snmp", "description": "Simple Network Monitoring Protocol", "default-reference": "1.0.0", "status": "installed", - "installed-version": "1.0.0" + "installed-version": "1.0.0", + "image_id": "e269735173d5" } } ``` @@ -275,12 +279,39 @@ 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. -Once a Docker becomes a SONiC package, user will have two options: -- SONiC build system will be extended with a build parameter "INCLUDE_$PACKAGE=y|n". If this parameter is set to "y", a package will be -installed in SONiC image filesystem during build time. -- If the "INCLUDE_$PACKAGE" is set to "n", the target is not installed, but compiled into Docker Image and published to Docker Hub by CI for -users to install the package on a running switch. For that, the reference to the package will be added into *packages.json*. +### 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 @@ -383,33 +414,34 @@ The command line interfaces are given bellow: admin@sonic:~$ sonic-package-manager Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... - CLI to manage SONiC application packages + SONiC Package Manager. Options: - --help Show this message and exit + --help Show this message and exit. Commands: - add Add a new package to package database. - remove Remove a package from package database. - list List packages available in SONiC. - show Show SONiC package Info. - install Install SONiC package from repository. - upgrade Upgrade SONiC package. - uninstall Uninstall SONiC package. + 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 -Usage: sonic-package-manager [OPTIONS] COMMAND [ARGS]... +admin@sonic:~$ sonic-package-manager show package +Usage: sonic-package-manager show package [OPTIONS] COMMAND [ARGS]... - Show SONiC package Info. + Package show CLI commands. Options: - --help Show this message and exit + --help Show this message and exit. Commands: - manifest Print package manifest. - changelog Print package changelog. + changelog Print the package changelog + manifest Print the manifest content + versions Print available versions ``` @@ -429,7 +461,7 @@ dhcp-relay Azure/dhcp-relay DHCP relay service N/A Not #### Repository management ``` -admin@sonic:~$ sudo sonic-package-manager add [NAME] [REPOSITORY] --description=[STRING] --default-reference=[STRING] +admin@sonic:~$ sudo sonic-package-manager add [NAME] [REPOSITORY] --default-reference=[STRING] admin@sonic:~$ sudo sonic-package-manager remove [NAME] ``` @@ -439,14 +471,23 @@ admin@sonic:~$ sudo sonic-package-manager remove [NAME] ``` admin@sonic:~$ sudo sonic-package-manager install --help -Usage: sonic-package-manager install [OPTIONS] [REFERENCE] +Usage: sonic-package-manager install [OPTIONS] [PACKAGE_EXPR] Install SONiC package. Options: - -y, --yes Answer yes for any prompt. - -f, --force Force installation. - --help Show this message and exit + -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 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 + --help Show this message and exit ``` @@ -479,20 +520,20 @@ For developer convenience or for unpublished SONiC packages,it is possible to in ``` admin@sonic:~$ ls featureA.gz featureA.gz -admin@sonic:~$ sudo sonic-package-manager install 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 name. The image is tagged to 1.0.0. +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", - "default-reference": "1.0.0", "installed-version": "1.0.0", - "status": "installed" + "status": "installed", + "image_id": "9ab631f37d1d" } } ``` @@ -512,14 +553,21 @@ WARN: feature depends on syncd^1.1.1 while installed version is 1.0.5. Ignoring. ``` admin@sonic:~$ sudo sonic-package-manager upgrade --help -Usage: sonic-package-manager upgrade [OPTIONS] [REFERENCE] +Usage: sonic-package-manager upgrade [OPTIONS] [PACKAGE_EXPR] - Upgrade SONiC package. + Upgrade SONiC package Options: - -y, --yes Answer yes for any prompt. - -f, --force Force upgrade. - --help Show this message and exit + -y, --yes Answer yes for any prompt. + -f, --force Force upgrade. + --from 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 + --help Show this message and exit ``` @@ -600,9 +648,9 @@ Path | Type | Mandatory | Descri --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- /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. +/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. @@ -632,8 +680,10 @@ can be installed at any given time. 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 of strings | no | List of SONiC packages the service depends on. Defaults to []. -/package/breaks | list of strings | no | List of SONiC package the service breaks. Defaults to []. +/package/conflicts | list of strings | no | List of SONiC package the service conflicts with. Defaults to []. /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. @@ -654,7 +704,7 @@ Example: ``` -*depends*, *breaks* fields are defined to be in the following format: +*depends*, *conflicts* fields are defined to be in the following format: ``` [>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... @@ -740,7 +790,7 @@ admin@sonic:~$ sonic-package-manager show package changelog ``` -### SONiC Docker Container Resource restrictions +### 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 @@ -793,11 +843,13 @@ manifest. 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 "breaks". +/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 +/service/delayed | boolean | no | Whether to generate systemd boot timer for this unit. Timer value is set to 3m 30s. Default is False. @@ -862,7 +914,7 @@ Path | Type | Mandatory | Descri --------------------------------- | --------------------- | ----------- | ----------------------------------------------------------------------------- /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-stop-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. +/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 From 70d0517ebcf957a4b3528dc1dfac524bd5e264af Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Sun, 7 Feb 2021 16:58:44 +0200 Subject: [PATCH 26/38] remove monit section Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 245 ++++++++---------- 1 file changed, 102 insertions(+), 143 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 897199d427..1e1d42b37c 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -30,7 +30,6 @@ - [Initial Extension Configuration](#initial-extension-configuration) - [CLI extension](#cli-extension) - [SONiC Processes and Docker Statistics Telemetry Support](#sonic-processes-and-docker-statistics-telemetry-support) -- [Monit Configuration](#monit-configuration) - [Feature Concept Integration](#feature-concept-integration) - [Multi-DB support](#multi-db-support) - [Configuration Reload](#configuration-reload) @@ -60,9 +59,9 @@ ### Revision -| Rev | Date | Author | Change Description | -|:---:|:-----------:|:-----------------------:|--------------------------------------| -| 0.1 | 09/2020 | Stepan Blyshchak | Phase 1 Design | +| Rev | Date | Author | Change Description | +| :---: | :-----: | :--------------: | ------------------ | +| 0.1 | 09/2020 | Stepan Blyshchak | Phase 1 Design | ### Scope @@ -70,16 +69,16 @@ This document describes the high level design of SONiC Application Extension Inf ### 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 | +| **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 @@ -221,16 +220,16 @@ to guaranty that the database won't become broken if two write operations are pe 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). +| 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: @@ -644,14 +643,14 @@ 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. +| 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. @@ -677,14 +676,14 @@ 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 of strings | no | List of SONiC packages the service depends on. Defaults to []. -/package/conflicts | list of strings | no | List of SONiC package the service conflicts with. Defaults to []. -/package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. +| 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 of strings | no | List of SONiC packages the service depends on. Defaults to []. | +| /package/conflicts | list of strings | no | List of SONiC package the service conflicts with. Defaults to []. | +| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. | *base-os-constraint* should have the following format: @@ -735,14 +734,14 @@ or ###### 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. +| 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: @@ -841,16 +840,16 @@ 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. +| 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. | @@ -911,11 +910,11 @@ after installation all the service scripts under */usr/local/bin/* are re-genera ###### 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. +| 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 @@ -946,16 +945,16 @@ docker create {{ docker_run_options }} ###### 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 {}. +| 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 @@ -966,9 +965,9 @@ The JSON file will be loaded into running CONFIG DB and boot CONFIG DB file duri ###### manifest path -Path | Type | Mandatory | Description ---------------------------- | --------------------- | ----------|----------------------------------------------------------------------------- -/package/init-cfg | dict | no | Default package configuration in CONFIG DB format. Defaults to {} +| Path | Type | Mandatory | Description | +| ----------------- | ---- | --------- | ----------------------------------------------------------------- | +| /package/init-cfg | dict | no | Default package configuration in CONFIG DB format. Defaults to {} | Example: @@ -1064,11 +1063,11 @@ ave to be also auto-generated from YANG in the future. ###### manifest path -Path | Type | Mandatory | Description --------------------------------- | --------------------- | ----------|------------------------------------------------------------------------------ -/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. +| Path | Type | Mandatory | Description | +| ---------------------- | ------ | --------- | --------------------------------------------------------------- | +| /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 @@ -1076,48 +1075,6 @@ Path | Type | Mandatory | Descripti This feature should be supported by SONiC Application Extension without any changes to existing feature implementation. -### Monit Configuration - -Processes information is also used to generate monit configuration file based on the *critical* flag. An installation is triggering -monit configuration reload by issueing *systemctl reload monit.service*. - - -###### manifest path - -Path | Type | Mandatory | Description ---------------------------------- | --------------------- | -------------|-------------------------------------------------------------------------- -/processes/ | list | no | A list defining processes running inside the container. -/processes/[index]/name | string | yes | Process name. -/processes/[index]/critical | boolean | no | Wether the process is a critical process. Defaults to False. -/processes/[index]/command | string | yes | Command to run the process. - -Given the following processes list: - -```json -{ - "processes": [ - { - "name": "cpu-report", - "critical": true, - "command": "/usr/bin/cpu-reportd" - } - ] -} -``` - -Will generate the following monit configuration: - -``` -############################################################################### -## Monit configuration for cpu-report container -## process list: -## cpu-reportd -############################################################################### -check program cpu-report|cpu-reportd with path "/usr/bin/process_checker cpu-report /usr/bin/cpu-reportd" - if status != 0 for 5 times within 5 cycles then alert -``` - - ### Feature Concept Integration SONiC controls optional feature (aka services) via FEATURE table in CONFIG DB. Once SONiC Package is installed in the system and @@ -1190,9 +1147,9 @@ during *show techsupport* execution. This file will be included in techsupport u ###### manifest path -Path | Value | Mandatory | Description --------------------------------|-------------------|-----------|---------------------------------------------------------------------- -/package/debug-dump | string | No | A command to be executed during system dump +| Path | Value | Mandatory | Description | +| ------------------- | ------ | --------- | ------------------------------------------- | +| /package/debug-dump | string | No | A command to be executed during system dump | ### Multi-ASIC @@ -1203,10 +1160,10 @@ corresponding service files are created per each namespace. *systemd-sonic-gener ###### 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. +| 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 @@ -1242,15 +1199,17 @@ systemctl stop {{ service }} ###### 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/[index]/reconciles | boolean | no | Wether process performs warm-boot reconciliation, the warmboot-finalizer service has to wait for. Defaults to False. +| 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 @@ -1261,10 +1220,10 @@ 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. +| 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. From 49354485c250b439d7bf5613727204f0d9c610ea Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Sun, 7 Feb 2021 16:59:28 +0200 Subject: [PATCH 27/38] add versioning guideline Signed-off-by: Stepan Blyschak --- .../img/versioning-strategy.svg | 3 + .../sonic-versioning-strategy.md | 117 ++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 doc/sonic-application-extention/img/versioning-strategy.svg create mode 100644 doc/sonic-application-extention/sonic-versioning-strategy.md diff --git a/doc/sonic-application-extention/img/versioning-strategy.svg b/doc/sonic-application-extention/img/versioning-strategy.svg new file mode 100644 index 0000000000..7a1524066b --- /dev/null +++ b/doc/sonic-application-extention/img/versioning-strategy.svg @@ -0,0 +1,3 @@ + + +
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Versioning Strategy
Versioni...
Intermediate
release
Intermediate...
Breaking
change
Breaking...
Intermediate
release
Intermediate...
Intermediate
release
Intermediate...Viewer does not support full SVG 1.1 \ No newline at end of file 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 0000000000..7c0e313622 --- /dev/null +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -0,0 +1,117 @@ + +# 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 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 + - Redis-based IPC Communication API: libswsscommon, libsairedis + +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 (): + +e.g: + +``` +feat: Introduce new methods in ConsumerTable + +BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC +``` + +## SONiC Packages Versioning + +- Package release ***happens on SONiC release/branch-out*** or on demand for single Docker image: ***sub-release*** +- Manual version update ***is required*** when SONiC Package releases +- Within a release major and minor version ***must*** not change + - Package API backward compatibility is promised + - No new functionality is included +- On package release ***package maintainer must*** check package API compatibility with previous release +- In case API changed comparing to previous release ***package maintainer must*** must increment major version in master prior to branch-out +- In case API didn't change comparing to previous release ***package maintainer must*** must increment minor version in master prior branch-out +- Minor version in master after branch-out ***must*** be incremented by ***package maintainer*** in order to avoid version overlap between branches +- *Patch* version is updated on bug fixes and minor enhancements. Since this is a tedious work to do mannually on every change + this can be done only when the package is published to users via container registry (package release). + A package is published with a bug fix or enhancement whenever ***package maintainer decides*** to do so. +- On package release ***package maintainer must*** update package dependencies + +

+Figure 1. SONiC Docker Images Versioning Strategy +

+ +***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; Until CLI autogeneration, sonic utilities plugin system API incompatibility must be recorded by base OS major version increment + - 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. (e.g. sonic-linux-kernel update in sonic-buildimage should result in increment: 1.4.5(current) to 1.5.0) + A dependency should be defined in manifest.json: + ```json + { + "package": { + "base-os-constraint": "^1.5.0" + } + } + ``` +- SONiC host service (D-Bus based communitcation) + + +## Open Questions From b154820484fa297e4cb3a010c8f5709e891edc43 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Sun, 7 Feb 2021 21:41:41 +0200 Subject: [PATCH 28/38] update versioning svg Signed-off-by: Stepan Blyshchak --- doc/sonic-application-extention/img/versioning-strategy.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/img/versioning-strategy.svg b/doc/sonic-application-extention/img/versioning-strategy.svg index 7a1524066b..88b46d2b14 100644 --- a/doc/sonic-application-extention/img/versioning-strategy.svg +++ b/doc/sonic-application-extention/img/versioning-strategy.svg @@ -1,3 +1,3 @@ -
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Versioning Strategy
Versioni...
Intermediate
release
Intermediate...
Breaking
change
Breaking...
Intermediate
release
Intermediate...
Intermediate
release
Intermediate...Viewer does not support full SVG 1.1 \ No newline at end of file +
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Versioning Strategy
Versioni...
Sub-release
Sub-release
Breaking
change to
release
Breaking...
Sub-release
Sub-release
Sub-release
Sub-releaseViewer does not support full SVG 1.1 \ No newline at end of file From 110acea7c6a12edd2f7bdc7cb925cf8a3d6941bb Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Fri, 12 Feb 2021 17:42:05 +0200 Subject: [PATCH 29/38] add link to conv commits --- doc/sonic-application-extention/sonic-versioning-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 7c0e313622..667c82b08f 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -62,7 +62,7 @@ Types of changes: 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 (): +follow conventional commits (https://www.conventionalcommits.org/en/v1.0.0/): e.g: From 3aa5423cafa6b69b9c019f0cbdd1c3e722771602 Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak <38952541+stepanblyschak@users.noreply.github.com> Date: Fri, 19 Feb 2021 14:39:00 +0200 Subject: [PATCH 30/38] Update sonic-versioning-strategy.md --- doc/sonic-application-extention/sonic-versioning-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 667c82b08f..9cf61f4833 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -98,7 +98,7 @@ BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC ## Base OS API that a package uses -- SONiC utilities; Until CLI autogeneration, sonic utilities plugin system API incompatibility must be recorded by base OS major version increment +- 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*** From 0975ac08b69bba7df921478c872b5adf490f654c Mon Sep 17 00:00:00 2001 From: Stepan Blyshchak Date: Fri, 26 Feb 2021 16:04:57 +0200 Subject: [PATCH 31/38] update versioning Signed-off-by: Stepan Blyshchak --- .../img/versioning-strategy.svg | 2 +- .../sonic-application-extention-hld.md | 79 +++++++--- .../sonic-versioning-strategy.md | 140 +++++++++++++++--- 3 files changed, 184 insertions(+), 37 deletions(-) mode change 100644 => 100755 doc/sonic-application-extention/img/versioning-strategy.svg diff --git a/doc/sonic-application-extention/img/versioning-strategy.svg b/doc/sonic-application-extention/img/versioning-strategy.svg old mode 100644 new mode 100755 index 88b46d2b14..f7e32aca90 --- a/doc/sonic-application-extention/img/versioning-strategy.svg +++ b/doc/sonic-application-extention/img/versioning-strategy.svg @@ -1,3 +1,3 @@ -
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Versioning Strategy
Versioni...
Sub-release
Sub-release
Breaking
change to
release
Breaking...
Sub-release
Sub-release
Sub-release
Sub-releaseViewer does not support full SVG 1.1 \ No newline at end of file +
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Sub-release
Sub-release
Breaking
change to
release
Breaking...
Sub-release
Sub-release
Sub-release
Sub-releaseViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 1e1d42b37c..a4bde789c4 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -42,6 +42,7 @@ - [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) @@ -676,16 +677,24 @@ 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 of strings | no | List of SONiC packages the service depends on. Defaults to []. | -| /package/conflicts | list of strings | no | List of SONiC package the service conflicts with. Defaults to []. | -| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. | +| 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]/sdk-version | string | no | SDK version constraint expression string | +| /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]/sdk-version | string | no | SDK version constraint expression string | +| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. | +SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). + *base-os-constraint* should have the following format: ``` @@ -703,10 +712,10 @@ Example: ``` -*depends*, *conflicts* fields are defined to be in the following format: +*depends*, *conflicts* version constraint fields are defined to be in the following format: ``` -[>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... +[>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... ``` Examples: @@ -714,7 +723,13 @@ Examples: ```json { "package": { - "depends": "swss>=1.0.0,!=1.2.2,<=3.0.0" + "depends": [ + { + "name": "swss", + "version": ">=1.0.0,!=1.2.2,<=3.0.0", + "sdk-version": "^1.0.0,^2.0.0" + } + ] } } ``` @@ -724,11 +739,32 @@ or ```json { "package": { - "breaks": "syncd^1.0.0" + "breaks": [ + { + "name": "syncd", + "version": "^1.0.0" + } + ] } } ``` + +#### Automatic SDK compatibility check + +SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). + +SDK Docker image records an SDK version in a label that gets inherited by the package image. This allows to perform an +automatic compatibility check as follows: + +``` +for dependency in package.manifest["package"]["depends"]: + if is_built_based_on_sdk(dependency["name"]): + check(get_sdk_version(dependency["name"]).major == package.sdk_version.major) +``` + +This gives more guaranties to the user that if package installs it is compatible. + ### SONiC Package Changelog @@ -1323,7 +1359,6 @@ This will require to build a new image based on existing 3rd party Docker image ### 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 @@ -1369,14 +1404,20 @@ have a relation to database, swss, syncd containers they were built togather wit However, the packages dependencies contraints do not derive from these labels, instead a package maintainer must test and verify the package on a set of version range. -The following list of labels are going to be used: +The SDK version is saved into a label: + +``` +LABEL com.azure.sonic.sdk.version +``` + +The following list of additional labels are going to be used: ``` -LABEL com.azure.sonic.sdk.versions.base-os -LABEL com.azure.sonic.sdk.versions.config-engine -LABEL com.azure.sonic.sdk.versions.database -LABEL com.azure.sonic.sdk.versions.swss -LABEL com.azure.sonic.sdk.versions.syncd +LABEL com.azure.sonic.versions.base-os +LABEL com.azure.sonic.versions.config-engine +LABEL com.azure.sonic.versions.database +LABEL com.azure.sonic.versions.swss +LABEL com.azure.sonic.versions.syncd ``` diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 9cf61f4833..1387f3737e 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -9,6 +9,7 @@ - [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) @@ -34,7 +35,7 @@ With new SONiC Application Extension Infrastructure SONiC Dockers and SONiC Base 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. +version numbers correctly on releases. ## SONiC Package API @@ -42,7 +43,6 @@ 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 - - Redis-based IPC Communication API: libswsscommon, libsairedis If any other kind of API is exposed by the SONiC Package it should be accounted as package API. @@ -72,24 +72,29 @@ feat: Introduce new methods in ConsumerTable BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC ``` -## SONiC Packages Versioning +## SONiC Package Versioning Rules -- Package release ***happens on SONiC release/branch-out*** or on demand for single Docker image: ***sub-release*** +- 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 -- Within a release major and minor version ***must*** not change - - Package API backward compatibility is promised - - No new functionality is included -- On package release ***package maintainer must*** check package API compatibility with previous release -- In case API changed comparing to previous release ***package maintainer must*** must increment major version in master prior to branch-out -- In case API didn't change comparing to previous release ***package maintainer must*** must increment minor version in master prior branch-out -- Minor version in master after branch-out ***must*** be incremented by ***package maintainer*** in order to avoid version overlap between branches -- *Patch* version is updated on bug fixes and minor enhancements. Since this is a tedious work to do mannually on every change - this can be done only when the package is published to users via container registry (package release). - A package is published with a bug fix or enhancement whenever ***package maintainer decides*** to do so. -- On package release ***package maintainer must*** update package dependencies +- 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. + +## SONiC buildimage packages versioning + +Normally packages should be separated from sonic-buildimage repository. If a package is part of sonic-buildimage there are following restrictions: + +- Within a release major and minor version must not change + - Package API backward compatibility is promised + - No new functionality is included +- Minor version in master after branch-out must be incremented by package maintainer in order to avoid version overlap between branches

-Figure 1. SONiC Docker Images Versioning Strategy +Figure 1. SONiC Docker Images Versioning for sonic-buildimage dockers

***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. @@ -111,7 +116,108 @@ BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC } } ``` -- SONiC host service (D-Bus based communitcation) +- SONiC host service (D-Bus based communication) + + +# 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) +``` + +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 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", + "sdk-version": "^1.0.0,^2.0.0", + } + ] + } +} +``` ## Open Questions From 08b53060f9041b97b43a582e07bc53bcd909a3e9 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Fri, 5 Mar 2021 11:23:20 +0200 Subject: [PATCH 32/38] update versioning Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 92 ++++++++++++------- .../sonic-versioning-strategy.md | 11 ++- 2 files changed, 70 insertions(+), 33 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index a4bde789c4..6211096176 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -677,23 +677,29 @@ 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]/sdk-version | string | no | SDK version constraint expression string | -| /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]/sdk-version | string | no | SDK version constraint expression string | -| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version. | +| 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 | +| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version | +Each SONiC Package can have a list of labels representing components versions: -SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). +``` +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). *base-os-constraint* should have the following format: @@ -727,7 +733,9 @@ Examples: { "name": "swss", "version": ">=1.0.0,!=1.2.2,<=3.0.0", - "sdk-version": "^1.0.0,^2.0.0" + "components": { + "libswsscommon": "^1.0.0,^2.0.0" + } } ] } @@ -749,21 +757,43 @@ or } ``` +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 SDK compatibility check +#### Automatic compatibility check SDK refers to [SONiC SDK Docker Images](#sonic-sdk-docker-images). -SDK Docker image records an SDK version in a label that gets inherited by the package image. This allows to perform an -automatic compatibility check as follows: +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 some library constarint is not defined in the manifest but a library version exists in labels of a package the constraint will initialize for that component as "^$major.0.0". E.g: + +Package Foo is build with following labels: ``` -for dependency in package.manifest["package"]["depends"]: - if is_built_based_on_sdk(dependency["name"]): - check(get_sdk_version(dependency["name"]).major == package.sdk_version.major) +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 @@ -1369,6 +1399,7 @@ extensions - *sonic-sdk-buildenv*, *sonic-sdk* and *sonic-sdk-dbg*. - libhiredis - libnl* - libswsscommon +- python3-swsscommon - libsairedis - libsairedis - libsaimeta @@ -1401,23 +1432,22 @@ The list of packages added to *sonic-sdk-buildenv* in addition to *sonic-sdk*: 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. -However, the packages dependencies contraints do not derive from these labels, instead a package maintainer -must test and verify the package on a set of version range. -The SDK version is saved into a label: +The SDK components versions are saved into labels: ``` -LABEL com.azure.sonic.sdk.version +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.versions.base-os -LABEL com.azure.sonic.versions.config-engine -LABEL com.azure.sonic.versions.database -LABEL com.azure.sonic.versions.swss -LABEL com.azure.sonic.versions.syncd +LABEL com.azure.sonic.sdk.base-os +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 ``` diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 1387f3737e..221fb2fdb2 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -139,6 +139,11 @@ major.minor.patch => major.(minor + 1).patch 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: @@ -198,7 +203,7 @@ foo's manifest: 5. Dependencies SDK changes -An infrastructure can detect wether package foo is using SDK major version same as foo's dependencies. This automatic check does not require package maintainer additional manifest configuration. +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. @@ -213,7 +218,9 @@ For example, foo is only using swss::Table, while a breaking change appeared in { "name": "swss", "version": "^1.0.0", - "sdk-version": "^1.0.0,^2.0.0", + "components": { + "libswsscommon": "^1.0.0,^2.0.0" + } } ] } From 48208092f61222bd2f35dafd507a82bec30d42c6 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Fri, 5 Mar 2021 17:33:37 +0200 Subject: [PATCH 33/38] update versioning Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 4 ++-- doc/sonic-application-extention/sonic-versioning-strategy.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 6211096176..20f4229494 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -718,7 +718,7 @@ Example: ``` -*depends*, *conflicts* version constraint fields are defined to be in the following format: +*depends*, *breaks* version constraint fields are defined to be in the following format: ``` [>|>=|==|<|<=|^|!|!=],[>|>=|==|<|<=|^|!|!=],... @@ -765,7 +765,7 @@ For the list of supported expressions check the python library that is going to 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 some library constarint is not defined in the manifest but a library version exists in labels of a package the constraint will initialize for that component as "^$major.0.0". E.g: +automatic compatibility check. If some library constarint is 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: diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 221fb2fdb2..e5d9d8a63b 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -86,7 +86,7 @@ BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC ## SONiC buildimage packages versioning -Normally packages should be separated from sonic-buildimage repository. If a package is part of sonic-buildimage there are following restrictions: +Normally packages should be separated from sonic-buildimage repository. If a package is part of sonic-buildimage and uses a single repository for every SONiC release there are following restrictions: - Within a release major and minor version must not change - Package API backward compatibility is promised From 342ee91a3733f02ddd09ede7d48539600f37e7a4 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Fri, 12 Mar 2021 17:27:21 +0200 Subject: [PATCH 34/38] remove version image as no longer needed Signed-off-by: Stepan Blyschak --- .../img/versioning-strategy.svg | 3 --- .../sonic-versioning-strategy.md | 13 +------------ 2 files changed, 1 insertion(+), 15 deletions(-) delete mode 100755 doc/sonic-application-extention/img/versioning-strategy.svg diff --git a/doc/sonic-application-extention/img/versioning-strategy.svg b/doc/sonic-application-extention/img/versioning-strategy.svg deleted file mode 100755 index f7e32aca90..0000000000 --- a/doc/sonic-application-extention/img/versioning-strategy.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
v 1.0.0
v 1.0.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.0
v 1.1.1
v 1.1.1
v 1.2.0
v 1.2.0
v 1.3.0
v 1.3.0
v 2.0.0
v 2.0.0
v 2.0.0
v 2.0.0
v 3.0.0
v 3.0.0
v 2.0.1
v 2.0.1
master
master
202106
202106
202112
202112
v 3.0.1
v 3.0.1
On release minor
version increments
on master
On release minorversion in...
Major and minor
versions must
stay the same within
a release branch
Major and minor...
Sub-release
Sub-release
Breaking
change to
release
Breaking...
Sub-release
Sub-release
Sub-release
Sub-releaseViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index e5d9d8a63b..3ce32605c4 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -84,18 +84,7 @@ BREAKING CHANGE: this feature breaks the Consumer/Producer based IPC **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. -## SONiC buildimage packages versioning - -Normally packages should be separated from sonic-buildimage repository. If a package is part of sonic-buildimage and uses a single repository for every SONiC release there are following restrictions: - -- Within a release major and minor version must not change - - Package API backward compatibility is promised - - No new functionality is included -- Minor version in master after branch-out must be incremented by package maintainer in order to avoid version overlap between branches - -

-Figure 1. SONiC Docker Images Versioning for sonic-buildimage dockers -

+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. From bbeeba40a5d59dc7835b2e2b73fa2570fff0ff22 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Fri, 19 Mar 2021 16:33:16 +0200 Subject: [PATCH 35/38] add a flag to skip installation of CLI plugins Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 20f4229494..93cf0c120a 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -487,6 +487,9 @@ Options: --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 if the CLI plugin is + not mandatory. --help Show this message and exit ``` @@ -1131,6 +1134,7 @@ ave to be also auto-generated from YANG in the future. | 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. | From f24ba4b8a6589d5d5f934304bcbee1fc3563733a Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Fri, 19 Mar 2021 16:46:37 +0200 Subject: [PATCH 36/38] base os another approach Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 93cf0c120a..5c3bb16426 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -695,6 +695,18 @@ can be installed at any given time. | /package/breaks/[index]/components | object | no | Per component version | | /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version | +Another proposal for base OS 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: ``` From 5befd81b363f9a4e9d22acb46dc1810381f47906 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Thu, 25 Mar 2021 16:26:32 +0200 Subject: [PATCH 37/38] update Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 32 ++++--------------- .../sonic-versioning-strategy.md | 11 ++----- 2 files changed, 8 insertions(+), 35 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 20f4229494..c2612be950 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -327,27 +327,7 @@ e.g: *1.0.0 < 1.1.0* and *1.5.1 > 1.4.20*. For more details of comparison rules 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 has also have a version number that follows the same rules of semantic versioning so that a package can define a dependency on -base OS version. A new variable is introduced in */etc/sonic/sonic_version.yml* called "base_os_compatibility_version" that follows semantic -versioning schema. This version is in addition to SONiC version we have today. - -This version number does not replace the current SONiC version string that is generated during the build so both SONiC version string and -base OS compatibility version coexist. Base OS compatibility version can be updated independently from SONiC version. - -The updated output of "show version" command is given below: - -``` -admin@sonic:~$ show version - -SONiC Software Version: SONiC.master.0-7580c846 -Base OS Compatibility Version: 1.0.0 -Distribution: Debian 9.13 -Kernel: 4.9.0-11-2-amd64 -Build commit: 7580c846 -Build date: Sat Sep 26 04:17:56 UTC 2020 -Built by: johnar@jenkins-worker-8 -... -``` +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: @@ -690,7 +670,6 @@ can be installed at any given time. | /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 | -| /package/base-os-constraint | string | no | Base image version dependency constraint. Defaults to '*': allows any version | Each SONiC Package can have a list of labels representing components versions: @@ -701,7 +680,7 @@ 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). -*base-os-constraint* should have the following format: +Version constraints should have the following format: ``` [>|>=|==|<|<=|^|!|!=] @@ -712,7 +691,9 @@ Example: ```json { "package": { - "base-os-constraint": ">1.0.0" + "base-os": { + "libswsscommon": ">1.0.0" + } } } ``` @@ -765,7 +746,7 @@ For the list of supported expressions check the python library that is going to 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 some library constarint is 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: +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: @@ -1443,7 +1424,6 @@ LABEL com.azure.sonic.versions.libsairedis The following list of additional labels are going to be used: ``` -LABEL com.azure.sonic.sdk.base-os LABEL com.azure.sonic.sdk.config-engine LABEL com.azure.sonic.sdk.database LABEL com.azure.sonic.sdk.swss diff --git a/doc/sonic-application-extention/sonic-versioning-strategy.md b/doc/sonic-application-extention/sonic-versioning-strategy.md index 3ce32605c4..1dd6008445 100644 --- a/doc/sonic-application-extention/sonic-versioning-strategy.md +++ b/doc/sonic-application-extention/sonic-versioning-strategy.md @@ -96,16 +96,9 @@ Package maintainer may choose to maintain a single repository and have there pac - 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. (e.g. sonic-linux-kernel update in sonic-buildimage should result in increment: 1.4.5(current) to 1.5.0) - A dependency should be defined in manifest.json: - ```json - { - "package": { - "base-os-constraint": "^1.5.0" - } - } - ``` + 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 From 8d1811f7592812bb5a2cd0b7af5023f5b6449219 Mon Sep 17 00:00:00 2001 From: Stepan Blyschak Date: Thu, 25 Mar 2021 16:28:24 +0200 Subject: [PATCH 38/38] udpate Signed-off-by: Stepan Blyschak --- .../sonic-application-extention-hld.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/sonic-application-extention/sonic-application-extention-hld.md b/doc/sonic-application-extention/sonic-application-extention-hld.md index 819a090641..50dbfb10eb 100644 --- a/doc/sonic-application-extention/sonic-application-extention-hld.md +++ b/doc/sonic-application-extention/sonic-application-extention-hld.md @@ -468,8 +468,10 @@ Options: --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 if the CLI plugin is - not mandatory. + 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 ``` @@ -674,7 +676,7 @@ can be installed at any given time. | /package/breaks[index]/version | string | no | Version constraint expression string | | /package/breaks/[index]/components | object | no | Per component version | -Another proposal for base OS version checking: +Base OS component version checking: ###### manifest path