Training
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Microsoft has developed many proven practices for managing network functions (NFs) by using Azure Operator Service Manager. This article provides guidelines that NF vendors, telco operators, and their partners can follow to optimize the design. Keep these practices in mind when you onboard and deploy your NFs.
We recommend that you first onboard and deploy your simplest NFs (one or two charts) by using the quickstarts to familiarize yourself with the overall flow. You can add necessary configuration details in subsequent iterations. As you go through the quickstarts, consider the following points:
We recommend that you create a single publisher per NF supplier. This practice provides optimal support, maintenance, and governance experience across all suppliers and simplifies your network service design when composed of multiple NFs from multiple vendors.
After the desired set of Azure Operator Service Manager publisher resources and artifacts is tested and approved for production use, we recommend marking the entire set as immutable to prevent accidental changes and ensure a consistent deployment experience. Consider relying on immutability capabilities to distinguish between resources and artifacts used in production versus the ones used for testing and development purposes. You can query the state of the publisher resources and the artifact manifests to determine which ones are marked as immutable. For more information, see Publisher tenants, subscriptions, regions, and preview management.
Keep in mind the following logic:
Consider using agreed-upon naming conventions and governance techniques to help address any remaining gaps.
Network Function Definition Group (NFDG) represents the smallest component that you plan to reuse independently across multiple services. All parts of an NFDG are always deployed together. These parts are called networkFunctionApplications
. For example, it's natural to onboard a single NF composed of multiple Helm charts and images as a single NFDG if you always deploy those components together. In cases when multiple NFs are always deployed together, it's reasonable to have a single NFDG for all of them. Single NFDGs can have multiple NFDVs.
For Containerized Network Function Definition Versions (CNF NFDVs), the networkFunctionApplications
list can only contain helm packages. It's reasonable to include multiple helm packages if they're always deployed and deleted together.
For Virtualized Network Function Definition Versions (VNF NFDVs), the networkFunctionApplications
list must contain at least one VhdImageFile
and one ARM template. The ARM template should deploy a single virtual machine (VM). To deploy multiple VMs for a single VNF, make sure to use separate ARM templates for each VM.
The ARM template can only deploy Resource Manager resources from the following resource providers:
Note
For ARM templates containing anything beyond the preceding list, all PUT calls and Re-PUT on the VNF result in a validation error.
deployParametersMappingRuleProfile
.applicationEnablement: Disabled
.Note
Minimum number of changes required every time the payload of a given NF changes. A minor or major NF release without exposing new CGS parameters only requires updating the artifact manifest, pushing new images and charts, and bumping the NFDV version.
Network Service Design Group (NSDG) is a composite of one or more NFDGs and any infrastructure components (such as Nexus Azure Kubernetes Service [NAKS]/Azure Kubernetes Service [AKS] clusters and virtual machines) deployed at the same time. A site network service (SNS) refers to a single NSDV. Such design guarantees consistent and repeatable deployment of the network service to a given site from a single SNS PUT.
An example of an NSDG is:
These five components form a single NSDG. A single NSDG can have multiple NSDVs.
Note
Changes in NFDV shouldn't trigger an NSDV update. The NFDV value should be exposed as a parameter within the CGS, so operators can control what to deploy by using CGVs.
We recommend that you always start with a single CGS for the entire NF. If there are site-specific or instance-specific parameters, we still recommend that you keep them in a single CGS. We recommend splitting into multiple CGSs when there are multiple components (rarely NFs, more commonly, infrastructure) or configurations that are shared across multiple NFs. The number of CGSs defines the number of CGVs.
In this scenario, we recommend that you use a single global CGS to expose the common NF and third-party component configurations. You can define NF-specific CGS as needed.
CGS payload:
{ "type": "object", "properties": { "abc": { "type": "integer", "default": 30 }, "xyz": { "type": "integer", "default": 40 }, "qwe": { "type": "integer" //doesn't have defaults } } "required": "qwe" }
Corresponding CGV payload passed by the operator:
{ "qwe": 20 }
Resulting CGV payload generated by Azure Operator Service Manager:
{ "abc": 30, "xyz": 40, "qwe": 20 }
Before you submit the CGV resource creation, you can validate that the schema and values of the underlying YAML or JSON file match what the corresponding CGS expects. To accomplish that, one option is to use the YAML extension for Visual Studio Code.
The Azure Operator Service Manager CLI extension assists with the publishing of NFDs and NSDs. Use this tool as the starting point for creating new NFDs and NSDs. Consider using the CLI to create the initial files. Then edit them to incorporate infrastructure components before you publish.
We recommend that you have a single SNS for the entire site, including the infrastructure. The SNS should deploy any infrastructure required (for example, NAKS/AKS clusters and virtual machines), and then deploy the NFs required on top. Such design guarantees consistent and repeatable deployment of the network service to a given site from a single SNS PUT.
We recommend that every SNS is deployed with a user-assigned managed identity rather than a system-assigned managed identity. This user-assigned managed identity must have permissions to access the NFDV and needs to have the role of Managed Identity Operator on itself. For more information, see Create and assign a user-assigned managed identity.
The following two scenarios illustrate Azure Operator Service Manager resource mapping.
An NF with one or two application components is deployed to a NAKS cluster.
Resources breakdown:
Multiple NFs with some shared and independent components are deployed to a NAKS cluster.
Resources breakdown:
Assuming NFs support in-place/in-service upgrades, for CNFs:
For VNFs:
deployParameters
and templateParameters
need to be parametrized in such a way that you can supply the unique values by using CGVs for each.Azure Operator Service Manager is a regional service deployed across availability zones in regions that support them. For all regions where Azure Operator Service Manager is available, see Azure products by region. For the list of Azure regions that have availability zones, see Choose the right Azure region for you.
Consider the following high-availability and disaster recovery requirements:
Note
If a region becomes unavailable, you can deploy (but not upgrade) an NF by using publisher resources in another region. Assuming that artifacts and resources are identical between the publishers, you only need to change the networkServiceDesignVersionOfferingLocation
value in the SNS resource payload.
resource sns 'Microsoft.HybridNetwork/sitenetworkservices@2023-09-01’ = { name: snsName location: location identity: { type: 'SystemAssigned' } properties: { publisherName: publisherName publisherScope: 'Private' networkServiceDesignGroupName: nsdGroup networkServiceDesignVersionName: nsdvName networkServiceDesignVersionOfferingLocation: location
During installation and upgrade by default, atomic and wait options are set to true
, and the operation timeout is set to 27 minutes
. During initial onboarding, only while you are still debugging and developing artifacts, we recommend that you set the atomic flag to false.
This prevents a helm rollback upon failure and retains any logs or errors which may otherwise be lost. The optimal way to accomplish that is in the ARM template of the NF.
In the ARM template, add the following section:
"roleOverrideValues": [ "{\"name\":\"NF_component_name>\",\"deployParametersMappingRuleProfile\":{\"helmMappingRuleProfile\":{\"options\":{\"installOptions\":{\"atomic\":\"false\",\"wait\":\"true\",\"timeout\":\"100\"},\"upgradeOptions\":{\"atomic\":\"true\",\"wait\":\"true\",\"timeout\":\"4\"}}}}}" ]
The component name is defined in the NFDV:
networkFunctionTemplate: { nfviType: 'AzureArcKubernetes' networkFunctionApplications: [ { artifactType: 'HelmPackage' name: 'fed-crds' dependsOnProfile: null artifactProfile: { artifactStore: { id: acrArtifactStore.id }
Important
Make sure atomic and wait are set back to true
after initial onboarding is complete.
As the first step towards cleaning up a deployed environment, start by deleting operator resources in the following order:
Only once these operator resources are successfully deleted, should a user proceed to delete other environment resources, such as the NAKS cluster.
Important
Deleting resources out of order can result in orphaned resources left behind.
As the first step towards cleaning up an onboarded environment, start by deleting publisher resources in the following order:
Important
Make sure SNS is deleted before you delete the NFDV.
Important
Deleting resources out of order can result in orphaned resources left behind.
By default, containerized network function applications (NfApps) are installed or updated based on the sequential order in which they appear in the network function design version (NFDV). For delete, the NfApps are deleted in the reverse order specified. Where a publisher needs to define specific ordering of NfApps, different from the default, a dependsOnProfile is used to define a unique sequence for install, update and delete operations.
A publisher can use the dependsOnProfile in the NFDV to control the sequence of helm executions for NfApps. Given the following example, on install operation the NfApps will be deployed in the following order: dummyApplication1, dummyApplication2, then dummyApplication. On update operation, the NfApps will be updated in the following order: dummyApplication2, dummyApplication1, then dummyApplication. On delete operation, the NfApps will be deleted in the following order: dummyApplication2, dummyApplication1, then dummyApplication.
{
"location": "eastus",
"properties": {
"networkFunctionTemplate": {
"networkFunctionApplications": [
{
"dependsOnProfile": {
"installDependsOn": [
"dummyApplication1",
"dummyApplication2"
],
"uninstallDependsOn": [
"dummyApplication1"
],
"updateDependsOn": [
"dummyApplication1"
]
},
"name": "dummyApplication"
},
{
"dependsOnProfile": {
"installDependsOn": [
],
"uninstallDependsOn": [
"dummyApplication2"
],
"updateDependsOn": [
"dummyApplication2"
]
},
"name": "dummyApplication1"
},
{
"dependsOnProfile": null,
"name": "dummyApplication2"
}
],
"nfviType": "AzureArcKubernetes"
},
"networkFunctionType": "ContainerizedNetworkFunction"
}
}
As of today, if dependsOnProfile provided in the NFDV is invalid, the NF operation will fail with a validation error. The validation error message is shown in the operation status resource and looks similar to the following example.
{
"id": "/providers/Microsoft.HybridNetwork/locations/EASTUS2EUAP/operationStatuses/ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
"name": "ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
"resourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/xinrui-publisher/providers/Microsoft.HybridNetwork/networkfunctions/testnfDependsOn02",
"status": "Failed",
"startTime": "2023-07-17T20:48:01.4792943Z",
"endTime": "2023-07-17T20:48:10.0191285Z",
"error": {
"code": "DependenciesValidationFailed",
"message": "CyclicDependencies: Circular dependencies detected at hellotest."
}
}
In some cases, third-party helm charts may not be fully compliant with AOSM requirements for registryURL. In this case, the injectArtifactStoreDetails feature can be used to avoid making changes to helm packages.
To use injectArtifactStoreDetails, set the installOptions parameter in the NF resource roleOverrides section to true, then use whatever registryURL value is needed to keep the registry URL valid. See following example of injectArtifactStoreDetails parameter enabled.
resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = {
name: nfName
location: location
properties: {
nfviType: 'AzureArcKubernetes'
networkFunctionDefinitionVersionResourceReference: {
id: nfdvId
idType: 'Open'
}
allowSoftwareUpdate: true
nfviId: nfviId
deploymentValues: deploymentValues
configurationType: 'Open'
roleOverrideValues: [
// Use inject artifact store details feature on test app 1
'{"name":"testapp1", "deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"atomic":"false","wait":"false","timeout":"60","injectArtifactStoreDetails":"true"},"upgradeOptions": {"atomic": "false", "wait": "true", "timeout": "100", "injectArtifactStoreDetails": "true"}}}}}'
]
}
}
Training
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization