You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This article provides Azure Operator Service Manager guidelines to optimize the design of configuration group schemas (CGSs) and the operation of configuration group values (CGVs). Network function (NF) vendors, telco operators, and their partners should keep these practices in mind when onboarding and deploying NFs.
14
14
15
-
## What is JSON Schema?
15
+
## Overview of JSON Schema
16
16
17
-
JSON Schema is an Internet Engineering Task Force (IETF) standard providing a format for what JSON data is required for a given application and how to interact with it. Applying such standards for a JSON document lets you enforce consistency and data validity across JSON data.
17
+
JSON Schema is an Internet Engineering Task Force (IETF) standard that provides a format for what JSON data is required for an application and how to interact with it. Applying such standards for a JSON document helps you enforce consistency and data validity across JSON data.
18
18
19
19
### Where is JSON Schema used?
20
20
21
21
* Azure Operator Service Manager uses JSON Schema notation as a meta-schema within CGS `ConfigurationGroupSchemaPropertiesFormat` object `schemaDefinition` properties.
22
-
* Azure Operator Service Manager allows the designer and publisher to specify the JSON Schema where operator must provide data (JSON values) when instantiating an site network service (SNS) or NF.
23
-
* Azure Operator Service Manager allows the meta-schema properties be optional or required. Where a property is marked required, it must be specified in the values JSON.
22
+
* Azure Operator Service Manager allows the designer and publisher to specify the JSON Schema when the operator must provide data (JSON values) during instantiation of a site network service (SNS) or NF.
23
+
* Azure Operator Service Manager allows the meta-schema properties to be optional or required. Where a property is marked `required`, it must be specified in the JSON values.
24
24
25
25
### What JSON keywords are supported?
26
26
27
-
For the CGS meta-schema, Azure Operator Service Manager implements supports for JSON standard keywords on a type-by-type basis.
27
+
For the CGS meta-schema, Azure Operator Service Manager implements support for JSON standard keywords on a type-by-type basis:
28
28
29
-
* For object types, keyword support is limited by filter policy. See JSON Schema - [object](https://json-schema.org/understanding-json-schema/reference/object).
30
-
* For string types, keyword support isn't limited or filtered. See JSON Schema - [string](https://json-schema.org/understanding-json-schema/reference/string).
31
-
* For numeric types, keyword support isn't limited or filtered. See JSON Schema - [numeric](https://json-schema.org/understanding-json-schema/reference/numeric).
29
+
* For object types, keyword support is limited by filter policy. See [object](https://json-schema.org/understanding-json-schema/reference/object) in the JSON Schema reference.
30
+
* For string types, keyword support isn't limited or filtered. See [string](https://json-schema.org/understanding-json-schema/reference/string) in the JSON Schema reference.
31
+
* For numeric types, keyword support isn't limited or filtered. See [Numeric types](https://json-schema.org/understanding-json-schema/reference/numeric) in the JSON Schema reference.
32
32
33
33
## Optional and required fields
34
34
35
-
A property is declared optional by including a `required` keyword, which omits the optional property. If the `required` keyword isn't specified, then all properties are considered required. At least one required property type is needed to support an optional property type.
35
+
You declare a property as optional by including a `required` keyword, which omits the optional property. If you don't specify the `required` keyword, all properties are considered required. You need at least one required property type to support an optional property type.
36
36
37
37
```json
38
38
{
@@ -53,11 +53,11 @@ A property is declared optional by including a `required` keyword, which omits t
53
53
54
54
## Default values in JSON Schema
55
55
56
-
For optional properties, Azure Operator Service Manager implements a custom method of default value handling. When a default value is defined in CGS meta-schema, Azure Operator Service Manager uses that value where the property is missing or undefined in the input CGV data. Azure Operator Service Manager validator logic essentially hydrates the CGV value with the default value when no value is provided by operator.
56
+
For optional properties, Azure Operator Service Manager implements a custom method of handling default values. When a default value is defined in CGS meta-schema, Azure Operator Service Manager uses that value where the property is missing or undefined in the input CGV data. Azure Operator Service Manager validator logic essentially hydrates the CGV value with the default value when the operator doesn't provide a value.
57
57
58
58
### How to define defaults
59
59
60
-
Defaults must be specified either inside properties or inside items of array. The following example demonstrates defaults with `integer` and `string` property types:
60
+
Defaults must be specified either inside properties or inside items of an array. The following example demonstrates defaults with integer and string property types:
61
61
62
62
```json
63
63
{
@@ -77,40 +77,42 @@ Defaults must be specified either inside properties or inside items of array. Th
77
77
78
78
### Rules for defining defaults
79
79
80
-
The following rules are applied when you're validating a default value. Consider these rules when using default values to ensure expected outcomes.
80
+
The following rules are applied when you're validating a default value. Consider these rules when you're using default values to ensure expected outcomes.
81
81
82
82
* A default value shouldn't be applied to a required property.
83
-
* A default value is evaluated in top-down order, from where the keyword is first seen.
83
+
* A default value is evaluated in top-down order from where the keyword first appears.
84
84
* Where a property value exists in the input CGV, only children of those properties are evaluated for defaults.
85
85
* Where a property value doesn't exist in the input CGV, it's evaluated for a default, along with any children.
86
-
* Where a property value is type object, and neither it or it's key exist in the input CGV, then no defaults for the object are evaluated.
86
+
* Where a property value is the `object` type, and neither it nor its key exists in the input CGV, no defaults for the object are evaluated.
87
87
88
88
## CGS considerations
89
89
90
-
Over time, the recommended approach to best design CGSs changed. Although the original one-CGS approach remains supported, for all new projects, we now recommend the three-CGS approach.
90
+
Over time, the recommended approach to best design CGSs changed.
91
91
92
92
### One-CGS approach
93
93
94
-
Originally it was recommended to use only a single CGS for the entire NF. This consolidated site-specific, instance-specific, and security-specific parameters into a single set of configuration group objects. Multiple object sets were avoided, except for rare cases where a service was composed of multiple components. Many partners successfully onboarded services using this approach and it remains supported.
94
+
The original recommendation was to use only a single CGS for the entire NF. This approach consolidated site-specific, instance-specific, and security-specific parameters into a single set of configuration group objects. This approach avoided multiple object sets, except for rare cases where a service had multiple components. Many partners successfully onboarded services by using this approach, and it remains supported.
95
95
96
96
### Three-CGS approach
97
97
98
-
More recently, it's now recommended to use at least three CGS for the entire NF, organizing parameters into site-specific, instance-specific, and security-specific configuration group sets. Examples of site-specific parameters are ip addresses or unique names. Examples of instance-spccific parameters are timeouts or debug levels. Examples of security-specific parameters would be passwords or certificates. With security-specific parameters, Azure Key Vault is used to store secure values.
98
+
We now recommend that you use at least three CGSs for the entire NF, by organizing parameters into these sets of configuration groups:
99
+
100
+
***Site-specific parameters**: Examples include IP addresses and unique names.
101
+
***Instance-specific parameters**: Examples include timeouts and debug levels.
102
+
***Security-specific parameters**: Examples include passwords and certificates. With security-specific parameters, you use Azure Key Vault to store secure values.
99
103
100
104
### Designing three-CGS object sets
101
105
102
106
Consider the following meta-schema guidelines when you're designing three-CGS objects:
103
107
104
108
* Choose which parameters to expose.
105
-
* A rule of thumb is to expose those parameters set using a direct operation, such as a compute SKU or Helm value.
106
-
* As opposed to a parameter that is acted on by another agent, such as `cloudinit` user-data.
109
+
110
+
A rule of thumb is to expose those parameters by using a direct operation, such as a compute tier or Helm value. Use this approach as opposed to a parameter that another agent acts on, such as `cloudinit` userdata.
107
111
* Sort the parameters into site-specific, instance-specific, and security-specific sets.
108
112
* Define required versus optional parameters. For optional parameters, define a reasonable default value.
109
-
* Ensure no overlapping parameters between CGS objects.
110
-
111
-
The following example shows a sample CGS and corresponding CGV payloads.
113
+
* Ensure that paramters don't overlap between CGS objects.
112
114
113
-
CGS payload:
115
+
This example shows a sample CGS payload:
114
116
115
117
```json
116
118
{
@@ -132,15 +134,15 @@ CGS payload:
132
134
}
133
135
```
134
136
135
-
Corresponding CGV payload passed by the operator:
137
+
This example shows a corresponding CGV payload that the operator passes:
136
138
137
139
```json
138
140
{
139
141
"qwe": 20
140
142
}
141
143
```
142
144
143
-
Resulting CGV payload generated by Azure Operator Service Manager:
145
+
This example shows the resulting CGV payload that Azure Operator Service Manager generates:
144
146
145
147
```json
146
148
{
@@ -152,4 +154,4 @@ Resulting CGV payload generated by Azure Operator Service Manager:
152
154
153
155
## CGV considerations
154
156
155
-
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.
157
+
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 validation, one option is to use the YAML extension for Visual Studio Code.
Azure Operator Service Manager provides three distinct interfaces that cater to three roles:
14
14
15
-
- Network Function (NF) Publisher
16
-
- Service Designer
17
-
- Service Operator
15
+
- Network function (NF) publisher
16
+
- Service designer
17
+
- Service operator
18
18
19
19
In practice, the same person can perform more than one of these roles if necessary.
20
20
21
-
:::image type="content" source="media/roles-interfaces-diagram.png" alt-text="Diagram that shows three interfaces catering to three roles: Publisher, Designer, and Operator." lightbox="media/roles-interfaces-diagram.png":::
21
+
:::image type="content" source="media/roles-interfaces-diagram.png" alt-text="Diagram that shows three interfaces catering to three roles: publisher, designer, and operator." lightbox="media/roles-interfaces-diagram.png":::
22
22
23
-
## NF Publisher
23
+
## NF publisher
24
24
25
-
The NF Publisher creates and publishes network functions to Azure Operator Service Manager. NF Publisher responsibilities include:
25
+
The NF publisher creates and publishes network functions to Azure Operator Service Manager. NF publisher responsibilities include:
26
26
27
27
- Create the network function.
28
28
- Encode the network function in a network function definition (NFD).
29
-
- Determine the deployment parameters to expose to the Service Designer.
29
+
- Determine the deployment parameters to expose to the service designer.
30
30
- Onboard the NFD to Azure Operator Service Manager.
31
31
- Upload the associated artifacts.
32
32
- Validate the NFD.
33
33
34
-
The NF Publisher is responsible for creating and updating these Azure Operator Service Manager resources:
34
+
The NF publisher is responsible for creating and updating these Azure Operator Service Manager resources:
35
35
36
36
- Publisher
37
37
- Artifact store
38
38
- Artifact manifest
39
39
- Network function definition group (NFDG)
40
40
- Network function definition version (NFDV)
41
41
42
-
## Service Designer
42
+
## Service designer
43
43
44
-
The Service Designer is responsible for building a network service design (NSD). The Service Designer collects network function definitions from various NF Publishers. When collection of the network function definitions is complete, the Service Designer combines them with the Azure infrastructure to create a cohesive service.
44
+
The service designer is responsible for building a network service design (NSD). The service designer collects NFDs from various NF publishers. When collection of the NFDs is complete, the service designer combines them with the Azure infrastructure to create a cohesive service.
45
45
46
-
The Service Designer determines how to parametrize the service by defining one or more configuration group schemas (CGSs). The CGSs define the inputs that the Service Operator must supply in the configuration group values (CGVs).
46
+
The service designer determines how to parametrize the service by defining one or more configuration group schemas (CGSs). The CGSs define the inputs that the service operator must supply in the configuration group values (CGVs).
47
47
48
-
The Service Designer determines how inputs from the Service Operator map to parameters that the NF Publishers and the Azure infrastructure require.
48
+
The service designer determines how inputs from the service operator map to parameters that the NF publishers and the Azure infrastructure require.
49
49
50
-
As part of creating the network service design, the Service Designer must consider the upgrade and scaling requirements of the service.
50
+
As part of creating the network service design, the service designer must consider the upgrade and scaling requirements of the service.
51
51
52
-
The Service Designer is responsible for creating and updating the following Azure Operator Service Manager objects:
52
+
The service designer is responsible for creating and updating the following Azure Operator Service Manager objects:
53
53
54
54
- Publisher
55
55
- Artifact store
56
56
- Artifact manifest
57
57
- Network service design group (NSDG)
58
58
- Network service design version (NSDV)
59
-
-Configuration group schema
59
+
-CGS
60
60
61
-
## Service Operator
61
+
## Service operator
62
62
63
-
The Service Operator is the person who runs the service on a day-to-day basis. The Service Operator's duties include creating, modifying, and monitoring these objects:
63
+
The service operator is the person who runs the service on a day-to-day basis. The service operator's duties include creating, modifying, and monitoring these objects:
64
64
65
65
- Site
66
66
- Site network service (SNS)
@@ -69,11 +69,11 @@ The Service Operator is the person who runs the service on a day-to-day basis. T
69
69
The process to create an SNS consists of:
70
70
71
71
- Selecting an NFDV for the new service.
72
-
- Applying parameters by using inputs in the form of a site and one or more configuration group schemas.
72
+
- Applying parameters by using inputs in the form of a site and one or more CGSs.
73
73
74
-
The Service Designer determines the exact format of these inputs.
74
+
The service designer determines the exact format of these inputs.
75
75
76
-
A Service Operator is responsible for creating and updating the following Azure Operator Service Manager objects:
76
+
A service operator is responsible for creating and updating the following Azure Operator Service Manager objects:
0 commit comments