Skip to content

Commit 733954d

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #312864 from msftadam/patch-1929
Revise configuration guide best practices and examples
2 parents 8b7f07f + 15dd6cb commit 733954d

1 file changed

Lines changed: 83 additions & 75 deletions

File tree

‎articles/operator-service-manager/configuration-guide.md‎

Lines changed: 83 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,94 @@ title: Configuration Group Best Practices for Azure Operator Service Manager
33
description: Learn about best practices for configuration groups when you're using Azure Operator Service Manager.
44
author: msftadam
55
ms.author: adamdor
6-
ms.date: 06/24/2025
6+
ms.date: 03/09/2026
77
ms.topic: best-practice
88
ms.service: azure-operator-service-manager
99
---
1010

11-
# Azure Operator Service Manager best practices for configuration groups
11+
# Best practices for configuration groups
1212

1313
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.
1414

15+
## Configuring group resource approach
16+
17+
Consider the following meta-schema guidelines when you're designing configuration resources:
18+
19+
* First, choose which parameters to expose to the operator.
20+
* A rule of thumb is to expose parameters backed by direct operation, such as a helm value.
21+
* Suppress parameters backed by another agent, such as `cloudinit` `userdata`.
22+
* Sort the parameters into site-specific, instance-specific, and security-specific sets.
23+
* Ensure that parameters don't overlap between CGS resources.
24+
* Define required versus optional parameters.
25+
* For optional parameters, define a reasonable default value.
26+
27+
## One-CGS approach
28+
29+
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 resources. This approach avoided multiple resource sets, except for rare cases where a service had multiple components. Many partners successfully onboarded services using this approach, and it remains supported. However, this approach doesn't obscure secrets. All configuration values are stored in resources as plain-text.
30+
31+
## Three-CGS approach
32+
33+
We now recommend that you use at least three CGSs for the entire NF, by organizing parameters into these sets of configuration resource groups:
34+
35+
* Site-specific parameters
36+
* Examples include IP addresses and unique names.
37+
* Uses CGS without secrets.
38+
* Stores values in plain-text during deployments.
39+
40+
* Instance-specific parameters
41+
* Examples include timeouts and debug levels.
42+
* Uses CGS without secrets.
43+
* Stores values in plain-text during deployment.
44+
45+
* Security-specific parameters
46+
* Examples include passwords and certificates.
47+
* Uses CGS with secrets.
48+
* Store values in Azure Key Vault to obscure during deployments.
49+
50+
## CGS without secrets
51+
52+
This example shows a sample CGS payload defining `abc`, `xyz`, and `qwe` as exposed parameters. Two of the parameters have default values and one is required.
53+
54+
```json
55+
{
56+
"type": "object",
57+
"properties": {
58+
"abc": {
59+
"type": "integer",
60+
"default": 30
61+
},
62+
"xyz": {
63+
"type": "integer",
64+
"default": 40
65+
},
66+
"qwe": {
67+
"type": "integer"
68+
}
69+
}
70+
"required": "qwe"
71+
}
72+
```
73+
74+
## CGV without secrets
75+
76+
This example shows a corresponding CGV input that an operator uses with the prior CGS:
77+
78+
```json
79+
{
80+
"qwe": 20
81+
}
82+
```
83+
84+
This example shows the resulting CGV resource that Azure Operator Service Manager generates:
85+
86+
```json
87+
{
88+
"abc": 30,
89+
"xyz": 40,
90+
"qwe": 20
91+
}
92+
```
93+
1594
## Overview of JSON Schema
1695

1796
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.
@@ -82,76 +161,5 @@ The following rules are applied when you're validating a default value. Consider
82161
* A default value shouldn't be applied to a required property.
83162
* A default value is evaluated in top-down order from where the keyword first appears.
84163
* Where a property value exists in the input CGV, only children of those properties are evaluated for defaults.
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 the `object` type, and neither it nor its key exists in the input CGV, no defaults for the object are evaluated.
87-
88-
## CGS considerations
89-
90-
Over time, the recommended approach to best design CGSs changed.
91-
92-
### One-CGS approach
93-
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-
96-
### Three-CGS approach
97-
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.
103-
104-
### Designing three-CGS object sets
105-
106-
Consider the following meta-schema guidelines when you're designing three-CGS objects:
107-
108-
* Choose which parameters to expose.
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` user data.
111-
* Sort the parameters into site-specific, instance-specific, and security-specific sets.
112-
* Define required versus optional parameters. For optional parameters, define a reasonable default value.
113-
* Ensure that parameters don't overlap between CGS objects.
114-
115-
This example shows a sample CGS payload:
116-
117-
```json
118-
{
119-
"type": "object",
120-
"properties": {
121-
"abc": {
122-
"type": "integer",
123-
"default": 30
124-
},
125-
"xyz": {
126-
"type": "integer",
127-
"default": 40
128-
},
129-
"qwe": {
130-
"type": "integer"
131-
}
132-
}
133-
"required": "qwe"
134-
}
135-
```
136-
137-
This example shows a corresponding CGV payload that the operator passes:
138-
139-
```json
140-
{
141-
"qwe": 20
142-
}
143-
```
144-
145-
This example shows the resulting CGV payload that Azure Operator Service Manager generates:
146-
147-
```json
148-
{
149-
"abc": 30,
150-
"xyz": 40,
151-
"qwe": 20
152-
}
153-
```
154-
155-
## CGV considerations
156-
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.
164+
* Where a property value doesn't exist in the input CGV, a default is evaluated, along with any children.
165+
* Where a property value is the `object` type, and its key doesn't exist in the input CGV, no defaults for the object are evaluated.

0 commit comments

Comments
 (0)