SONiC Application Extension Guide

Rev 0.1

Table of Content

• Revision

• Scope

• Porting an existing SONiC Docker image to be an Application Extension

• Developing a new SONiC Application Extension

• Adding 3rd party application to SONiC package database

• Building SONiC image with 3rd party application

• Manifest Reference

Revision

Scope

This document gives developers a quick guide through developing new application extensions or porting existing SONiC docker images into application extension compatible ones.

It is recommended to get acquainted with HLD document before reading this document.

Porting an existing SONiC Docker image to be an Application Extension

It is possible to port existing SONiC docker image and make it an Application Extension.

An example of porting DHCP relay - https://github.com/sonic-net/sonic-buildimage/commit/b3b6938fda9244607fb00bfd36a74bccab0c38a9.

1. Add a new build time flag to SONiC build system to control whether to include new Docker Image XXX:

Makefile.work

INCLUDE_XXX=$(INCLUDE_XXX)

1. Register this Docker image in SONIC_PACKAGES_LOCAL target group and remove from SONIC_INSTALL_DOCKER_IMAGES:

rules/docker-XXX.mk

ifeq ($(INCLUDE_XXX), y)
ifeq ($(INSTALL_DEBUG_TOOLS), y)
SONIC_PACKAGES_LOCAL += $(DOCKER_XXX_DBG)
else
SONIC_PACKAGES_LOCAL += $(DOCKER_XXX)
endif
endif

1. Remove $(DOCKER_XXX)_RUN_OPT and replace with variables used to generate manifest for the docker:

rules/docker-XXX.mk

$(DOCKER_XXX)_CONTAINER_PRIVILEGED = true
$(DOCKER_XXX)_CONTAINER_VOLUMES += /etc/sonic:/etc/sonic:ro
$(DOCKER_XXX)_CONTAINER_VOLUMES += /usr/share/sonic/scripts:/usr/share/sonic/scripts:ro
$(DOCKER_XXX)_CONTAINER_TMPFS += /tmp/

These variables are used to generate manifest for docker at build time (see generate_manifest function in https://github.com/sonic-net/sonic-buildimage/blob/master/rules/functions):

1. For extensions that provide CLI commands a CLI plugin is needed.

4.1. Remove extension CLI commands from sonic-utilities code.

4.2. Move the implementation as a separate file into sonic-buildimage under dockers/docker-xxx/cli folder.

This plugin has to implement register function needed to be loaded by sonic-utilities core:

dockers/docker-xxx/cli/show.py

import click

@click.command()
def example()
    pass

def register(cli):
    cli.add_command(example)

register may throw an exception, in this case main CLI will still work but a warning will be printed to the user.

4.3 UT for CLI:

In case CLI has unit tests, they need to be moved from sonic-utilities into sonic-buildimage repository and placed under dockers/docker-xxx/cli-plugins-tests/.

In case this folder exists tests are executed at docker image build time and test log is recorder in target/docker-xxx.gz.log.

The command line to execute tests is:

pytest-3 -v

Developing a new SONiC Application Extension

To develop a new SONiC Application Extension use the following example extension as a template: https://github.com/stepanblyschak/sonic-example-extension.

Prerequisites, build instructions and installation instructions are present in repository README.md file.

Adding 3rd party application to SONiC package database

Modify files/build_templates/packages.json.j2 to include new package. Example for the previous sonic-example-extension - cpu-report:

{
    "cpu-report": {
        "repository": "stepanblyschak/cpu-report",
        "description": "CPU report example",
        "default-reference": "1.0.0"
    }
}

Building SONiC image with 3rd party application

To build SONiC image with 3rd party application pre-installed use SONIC_PACKAGES target group. See https://github.com/sonic-net/sonic-buildimage/blob/master/rules/sonic-packages.mk.

Create a file under rules/ called rules/cpu-report.mk with the following content:

CPU_REPORT = cpu-report
$(CPU_REPORT)_REPOSITORY = stepanblyschak/cpu-report
$(CPU_REPORT)_VERSION = 1.0.0
SONIC_PACKAGES += $(CPU_REPORT)

Additional options:

$(CPU_REPORT)_DEFAULT_FEATURE_STATE_ENABLED # "y" or "n" - whether feature is enabled by default at system start. Sets enabled in the FEATURE table. Disabled by default.
$(CPU_REPORT)_DEFAULT_FEATURE_OWNER # "local" or "kube". Default is "local".

Manifest Reference

Label name the manifest content should be written to:

com.azure.sonic.manifest

The value should contain a JSON serialized as a string.

​