Documentation for Dynamic Configuration (#15643)
Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>
Timotej S committed
Oct 3, 2023 at 12:48 UTC
d28de728ce7a39341a68d01906d0069e3925fb2d
1 file changed
+167
libnetdata/dyn_conf/README.md
new
+167
@@ -0,0 +1,167 @@
1
+# Netdata Dynamic Configuration
2
+
3
+Purpose of Netdata Dynamic Configuration is to allow configuration of select Netdata plugins and options through the
4
+Netdata API and by extension by UI.
5
+
6
+## HTTP API documentation
7
+
8
+### Summary API
9
+
10
+For summary of all jobs and their statuses (for all children that stream to parent) use the following URL:
11
+
12
+| Method | Endpoint | Description |
13
+|:-------:|-------------------------------|------------------------------------------------------------|
14
+| **GET** | `api/v2/job_statuses` | list of Jobs |
15
+| **GET** | `api/v2/job_statuses?grouped` | list of Jobs (hierarchical, grouped by host/plugin/module) |
16
+
17
+### Dyncfg API
18
+
19
+### Top level
20
+
21
+| Method | Endpoint | Description |
22
+|:-------:|------------------|-----------------------------------------|
23
+| **GET** | `/api/v2/config` | registered Plugins (sent DYNCFG_ENABLE) |
24
+
25
+### Plugin level
26
+
27
+| Method | Endpoint | Description |
28
+|:-------:|-----------------------------------|------------------------------|
29
+| **GET** | `/api/v2/config/[plugin]` | Plugin config |
30
+| **PUT** | `/api/v2/config/[plugin]` | update Plugin config |
31
+| **GET** | `/api/v2/config/[plugin]/modules` | Modules registered by Plugin |
32
+| **GET** | `/api/v2/config/[plugin]/schema` | Plugin config schema |
33
+
34
+### Module level
35
+
36
+| Method | Endpoint | Description |
37
+|:-------:|-----------------------------------------------|---------------------------|
38
+| **GET** | `/api/v2/config/<plugin>/[module]` | Module config |
39
+| **PUT** | `/api/v2/config/[plugin]/[module]` | update Module config |
40
+| **GET** | `/api/v2/config/[plugin]/[module]/jobs` | Jobs registered by Module |
41
+| **GET** | `/api/v2/config/[plugin]/[module]/job_schema` | Job config schema |
42
+| **GET** | `/api/v2/config/[plugin]/[module]/schema` | Module config schema |
43
+
44
+### Job level - only for modules where `module_type == job_array`
45
+
46
+| Method | Endpoint | Description |
47
+|:----------:|------------------------------------------|--------------------------------|
48
+| **GET** | `/api/v2/config/[plugin]/[module]/[job]` | Job config |
49
+| **PUT** | `/api/v2/config/[plugin]/[module]/[job]` | update Job config |
50
+| **POST** | `/api/v2/config/[plugin]/[module]/[job]` | create Job |
51
+| **DELETE** | `/api/v2/config/[plugin]/[module]/[job]` | delete Job (created by Dyncfg) |
52
+
53
+## AGENT<->PLUGIN interface documentation
54
+
55
+### 1. DYNCFG_ENABLE
56
+
57
+Plugin signifies to agent its ability to use new dynamic config and the name it wishes to use by sending
58
+
59
+```
60
+plugin->agent:
61
+=============
62
+DYNCFG_ENABLE [plugin_url_name]
63
+```
64
+
65
+This can be sent only once per lifetime of the plugin (at startup or later) sending it multiple times is considered a
66
+protocol violation and plugin might get terminated.
67
+After this command is sent the plugin has to be ready to accept all the new commands/keywords related to dynamic
68
+configuration (this command lets agent know this plugin is dyncfg capable and wishes to use dyncfg functionality).
69
+
70
+After this command agent can call
71
+
72
+```
73
+agent->plugin:
74
+=============
75
+FUNCTION_PAYLOAD [UUID] 1 "set_plugin_config"
76
+the new configuration
77
+blah blah blah
78
+FUNCTION_PAYLOAD_END
79
+
80
+plugin->agent:
81
+=============
82
+FUNCTION_RESULT_BEGIN [UUID] [(1/0)(accept/reject)] [text/plain] 5
83
+FUNCTION_RESULT_END
84
+```
85
+
86
+to set the new config which can be accepted/rejected by plugin by sending answer for this FUNCTION as it would with any
87
+other regular function.
88
+
89
+The new `FUNCTION_PAYLOAD` command differs from regular `FUNCTION` command exclusively in its ability to send bigger
90
+payloads (configuration file contents) to the plugin (not just parameters list).
91
+
92
+Agent can also call (after `DYNCFG_ENABLE`)
93
+
94
+```
95
+Agent->plugin:
96
+=============
97
+FUNCTION [UID] 1 "get_plugin_config"
98
+
99
+Plugin->agent:
100
+=============
101
+FUNCTION_RESULT_BEGIN [UID] 1 text/plain 5
102
+{
103
+ "the currently used config from plugin" : "nice"
104
+}
105
+FUNCTION_RESULT_END
106
+```
107
+
108
+and
109
+
110
+```
111
+Agent->plugin:
112
+=============
113
+FUNCTION [UID] 1 "get_plugin_config_schema"
114
+
115
+Plugin->agent:
116
+=============
117
+FUNCTION_RESULT_BEGIN [UID] 1 text/plain 5
118
+{
119
+ "the schema of plugin configuration" : "splendid"
120
+}
121
+FUNCTION_RESULT_END
122
+```
123
+
124
+Plugin can also register zero, one or more configurable modules using:
125
+
126
+```
127
+plugin->agent:
128
+=============
129
+DYNCFG_REGISTER_MODULE [module_url_name] (job_array|single)
130
+```
131
+
132
+modules can be added any time during plugins lifetime (you are not required to add them all at startup).
133
+
134
+### 2. DYNCFG_REGISTER_MODULE
135
+
136
+Module has to choose one of following types at registration:
137
+
138
+- `single` - module itself has configuration but does not accept any jobs *(this is useful mainly for internal netdata
139
+ configurable things like webserver etc.)*
140
+- `job_array` - module itself **can** *(not must)* have configuration and it has an array of jobs which can be added,
141
+ modified and deleted. **this is what plugin developer needs in most cases**
142
+
143
+After module has been registered agent can call
144
+
145
+- `set_module_config [module]` FUNCTION_PAYLOAD
146
+- `get_module_config [module]` FUNCTION
147
+- `get_module_config_schema [module]` FUNCTION
148
+
149
+with same syntax as `set_plugin_config` and `get_plugin_config`. In case of `set` command the plugin has ability to
150
+reject the new configuration pushed to it.
151
+
152
+In a case the module was registered as `job_array` type following commands can be used to manage jobs:
153
+
154
+### 3. Job interface for job_array modules
155
+
156
+- `get_job_config_schema [module]` - FUNCTION
157
+- `get_job_config [module] [job]` - FUNCTION
158
+- `set_job_config [module] [job]` - FUNCTION_PAYLOAD
159
+- `delete_job_name [module] [job]` - FUNCTION
160
+
161
+### 4. Streaming
162
+
163
+When above commands are transferred trough streaming additionally `plugin_name` is prefixed as first parameter. This is
164
+done to allow routing to appropriate plugin @child.
165
+
166
+As a plugin developer you don't need to concern yourself with this detail as that parameter is stripped when sent to the
167
+plugin *(and added when sent trough streaming)* automagically.