Quickstart: Publish Nginx container as Containerized Network Function (CNF)

This quickstart describes how to use the az aosm Azure CLI extension to create and publish a basic Network Function Definition. Its purpose is to demonstrate the workflow of the Publisher Azure Operator Service Manager (AOSM) resources. The basic concepts presented here are meant to prepare users to build more exciting services.

Prerequisites

Create input file

Create an input file for publishing the Network Function Definition. Execute the following command to generate the input configuration file for the Network Function Definition (NFD).

az aosm nfd generate-config --definition-type cnf

Execution of the preceding command generates an cnf-input.jsonc file.

Note

Edit the cnf-input.jsonc file. Replace it with the values shown in the following sample. Save the file as input-cnf-nfd.jsonc.

If you are using an existing resource group, change the publisher_resource_group_name field to match it.

Tip

You can use multiple container registries as sources for your images in the AOSM CLI. The images to be copied from these registries are selected automatically based on the helm package schema. The source registries are configured in the image_sources list of the cnf-input.jsonc file.

When using ACRs, you must have the Reader and AcrPull roles on the ACR. When using non-ACR registries, you must run docker login to authenticate with each private registry before running the az aosm nfd build command. In this quickstart we use docker.io as the image source registry. This is a public registry and does not require authentication.

Here's sample input-cnf-nfd.jsonc file:

{
  // Azure location to use when creating resources e.g uksouth
  "location": "uksouth",
  // Name of the Publisher resource you want your definition published to.
  // Will be created if it does not exist.
  "publisher_name": "nginx-publisher",
  // Resource group for the Publisher resource.
  // Will be created if it does not exist.
  "publisher_resource_group_name": "nginx-publisher-rg",
  // Name of the ACR Artifact Store resource.
  // Will be created if it does not exist.
  "acr_artifact_store_name": "nginx-nsd-acr",
  // Name of NF definition.
  "nf_name": "nginx",
  // Version of the NF definition in 1.1.1 format (three integers separated by dots).
  "version": "1.0.0",
  // List of registries from which to pull the image(s).
  // For example ["sourceacr.azurecr.io/test", "myacr2.azurecr.io", "ghcr.io/path"].
  // For non Azure Container Registries, ensure you have run a docker login command before running build.
  //
  "image_sources": ["docker.io"],
  // List of Helm packages to be included in the CNF.
  "helm_packages": [
    {
      "name": "nginxdemo",
      "path_to_chart": "nginxdemo-0.3.0.tgz",
      "default_values": ""
    }
  ]
}
  • publisher_name - Name of the Publisher resource you want your definition published to. Created if it doesn't already exist.
  • publisher_resource_group_name - Resource group for the Publisher resource. Created if it doesn't already exist.
  • acr_artifact_store_name - Name of the Azure Container Registry (ACR) Artifact Store resource. Created if it doesn't already exist.
  • location - The Azure location to use when creating resources.
  • nf_name - The name of the NF definition.
  • version - The version of the NF definition in A.B.C format.
  • image_sources - list of the registries from which to pull the images.
  • helm_packages:
    • name - The name of the Helm package.
    • path_to_chart - The file path of Helm Chart on the local disk. Accepts .tgz, .tar or .tar.gz. Use Linux slash (/) file separator even if running on Windows. The path should be an absolute path or the path relative to the location of the cnf-input.jsonc file.
    • default_values - The file path (absolute or relative to cnf-input.jsonc) of the YAML values file on the local disk that is used instead of the values.yaml file present in the helm chart.
    • depends_on - Names of the Helm packages this package depends on. Leave as an empty array if there are no dependencies.

Build the Network Function Definition (NFD)

To construct the Network Function Definition (NFD), initiate the build process.

az aosm nfd build -f input-cnf-nfd.jsonc --definition-type cnf

The Az CLI AOSM extension generates a directory called cnf-cli-output. This directory contains the BICEP files defining the AOSM resources required to publish an NFDV and upload the images required to deploy it to AOSM-managed storage. Examine the generated files to gain a better understanding of the Network Function Definition (NFD) structure.

Directory/File Description
nfDefinition/deployParameters.json Defines the schema for the deployment parameters required to create a Network Function (NF) from this Network Function Definition Version (NFDV).
nfDefinition/nginxdemo-mappings.json Maps the deployment parameters for the Network Function Definition Version (NFDV) to the values required for the helm chart.
nfDefinition/deploy.bicep Bicep template for creating the Network Function Definition Version (NFDV) itself.
artifacts/artifacts.json A list of the helm packages and container images required by the NF.
artifactManifest/deploy.bicep Bicep template for creating the artifact manifest.
base/deploy.bicep Bicep template for creating the publisher, network function definition group, and artifact store resources

Publish the Network Function Definition and upload artifacts

Execute the following command to publish the Network Function Definition (NFD) and upload the associated artifacts:

Note

If you are using Windows, you must have Docker Desktop running during the publish step.

Note

Publisher names must be unique within a region. It is quite likely that the 'nginx-publisher' defined in the example config file already exists.

If you get an error saying "A private publisher resource with the name 'nginx-publisher' already exists in the provided region", edit the publisher_name field in the config file so that it is unique (e.g. add a random string suffix), re-run the build command (above), and then re-run this publish command.

If you go on to create a network service design, you will need to use this new pubilsher name in the resource_element_templates array.

az aosm nfd publish -b cnf-cli-output --definition-type cnf

When the command completes, inspect the resources within your Publisher Resource Group to review the created components and artifacts.

Next steps