Skip to content

Commit da5e12a

Browse files
msftadammsftadam
authored
Revise configuration guide best practices and examples
Updated the date and revised best practices for configuration groups, including recommendations for one-CGS and three-CGS approaches. Added guidelines for designing configuration resources and examples of CGS and CGV payloads.
1 parent b1572bf commit da5e12a

1 file changed

Lines changed: 73 additions & 72 deletions

File tree

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

Lines changed: 73 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,86 @@ 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+
* Surpress parameters backed by another agent, such as `cloudinit` `userdata`.
22+
* Sort the parameters into site-specific, instance-specific and decurity-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 does not obscure secrets. All configuration values will be 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+
* Instance-specific parameters**: Examples include timeouts and debug levels.
36+
* Uses CGS without secrets
37+
* Security-specific parameters**: Examples include passwords and certificates. With security-specific parameters, you use Azure Key Vault to store secure values.
38+
* Uses CGS without secrets
39+
* Site-specific parameters**: Examples include IP addresses and unique names.
40+
* Uses CGS with secrets
41+
42+
## CGS without secrets
43+
44+
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.
45+
46+
```json
47+
{
48+
"type": "object",
49+
"properties": {
50+
"abc": {
51+
"type": "integer",
52+
"default": 30
53+
},
54+
"xyz": {
55+
"type": "integer",
56+
"default": 40
57+
},
58+
"qwe": {
59+
"type": "integer"
60+
}
61+
}
62+
"required": "qwe"
63+
}
64+
```
65+
66+
## CGV without secrets
67+
68+
This example shows a corresponding CGV input which an operator uses with the prior CGS:
69+
70+
```json
71+
{
72+
"qwe": 20
73+
}
74+
```
75+
76+
This example shows the resulting CGV resource that Azure Operator Service Manager generates:
77+
78+
```json
79+
{
80+
"abc": 30,
81+
"xyz": 40,
82+
"qwe": 20
83+
}
84+
```
85+
1586
## Overview of JSON Schema
1687

1788
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.
@@ -85,73 +156,3 @@ The following rules are applied when you're validating a default value. Consider
85156
* Where a property value doesn't exist in the input CGV, it's evaluated for a default, along with any children.
86157
* 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.
87158

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.

0 commit comments

Comments
 (0)