metadata.yaml · cryptotaxi247/netdata

Code Commits Issues Pulls Sessions CI/CD

master

yaml 154 lines 8.19 KB

Raw

1	# yamllint disable rule:line-length
2	---
3	id: 'secretstore-gcp-sm'
4	meta:
5	kind: 'gcp-sm'
6	name: 'Google Secret Manager'
7	link: 'https://cloud.google.com/secret-manager'
8	icon_filename: 'google.svg'
9	keywords:
10	- 'secretstore'
11	- 'secrets'
12	- 'gcp'
13	- 'gcp-sm'
14	- 'google secret manager'
15	overview:
16	description: \|
17	Netdata can pull collector credentials directly from Google Secret Manager at runtime, so you never store passwords or tokens in plain-text configuration files.
18
19	This page covers Google Secret Manager specific setup. For the full resolver overview and syntax reference, including simpler alternatives like `${env:...}`, `${file:...}`, and `${cmd:...}`, see [Secrets Management](/src/collectors/SECRETS.md).
20	limitations: \|
21	Netdata reads existing secrets from Google Secret Manager. It does not create, rotate, or manage those secrets. If you omit the version in the operand, Netdata reads the `latest` secret version automatically.
22	setup:
23	prerequisites:
24	list:
25	- title: 'Choose a GCP authentication mode'
26	description: \|
27	Choose one supported authentication mode and make sure the Netdata Agent can use it:
28
29	- `metadata`: run Netdata in a Google Cloud environment where the metadata server is reachable.
30	- `service_account_file`: provide a service account JSON file on the Netdata host.
31
32	Prefer `metadata` for production when Netdata runs in a supported Google Cloud environment. Use `service_account_file` when Netdata runs outside Google Cloud or when you need explicit credentials.
33	- title: 'Protect the service account file'
34	description: \|
35	If you use `service_account_file`, the JSON file contains a private key. Keep it on the Netdata host, make it readable by the `netdata` user, and restrict access as tightly as possible. A common setup is `chmod 0600` with ownership that allows the `netdata` user to read the file.
36	- title: 'Allow Secret Manager access'
37	description: \|
38	The Google identity used by this secretstore must have the `roles/secretmanager.secretAccessor` IAM role on the secrets you reference from collector configs. Do not use broader roles like `roles/secretmanager.admin`.
39	- title: 'Plan for file-based changes'
40	description: \|
41	If you edit `/etc/netdata/go.d/ss/gcp-sm.conf`, restart the Netdata Agent to load the updated secretstore definition.
42	configuration:
43	file:
44	name: 'go.d/ss/gcp-sm.conf'
45	options:
46	description: 'The following options can be defined for this secretstore backend.'
47	folding:
48	title: 'Config options'
49	enabled: true
50	list:
51	- name: 'mode'
52	description: 'GCP authentication mode.'
53	default_value: 'metadata'
54	required: true
55	detailed_description: \|
56	Supported values:
57
58	- `metadata`: get an access token from the Google metadata server. This works in GCE, GKE (with Workload Identity configured), Cloud Run, and other Google Cloud environments where the metadata server is reachable.
59	- `service_account_file`: use a local service account JSON file.
60
61	Prefer `metadata` for production when Netdata runs in a supported Google Cloud environment. Use `service_account_file` when you need explicit credentials or when the metadata server is not available.
62	- name: 'mode_service_account_file.path'
63	group: 'Service Account File'
64	description: 'Absolute path to a service account JSON file. Required when `mode` is `service_account_file`. The file contains a private key and should be readable only by the `netdata` user or another tightly scoped owner.'
65	default_value: ''
66	required: true
67	- name: 'timeout'
68	description: 'Timeout in seconds for HTTP requests made by this secretstore backend.'
69	default_value: 3
70	required: false
71	examples:
72	folding:
73	title: 'Example configuration'
74	enabled: true
75	list:
76	- name: 'Metadata server'
77	description: 'Use credentials from the Google metadata server.'
78	config: \|
79	jobs:
80	- name: gcp_metadata
81	mode: metadata
82	- name: 'Service account file'
83	description: 'Use a service account JSON file stored on the Netdata host.'
84	config: \|
85	jobs:
86	- name: gcp_service_account
87	mode: service_account_file
88	mode_service_account_file:
89	path: /etc/netdata/gcp-service-account.json
90	collector_configs:
91	description: \|
92	Use the `${store:gcp-sm:...}` syntax to reference Google Secret Manager secrets in any string field of a collector configuration file.
93	summary:
94	operand_format: 'project/secret[/version]'
95	example_operand: 'my-project/mysql-password'
96	format:
97	description: \|
98	The operand is `project/secret` or `project/secret/version`.
99
100	- Use `project/secret` to read the latest version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password}`.
101	- Use `project/secret/version` to read a specific version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password/3}`.
102
103	Project IDs may use letters, numbers, `.`, `_`, `:`, or `-`. Secret names and versions may use letters, numbers, `_`, or `-`.
104	syntax: '${store:gcp-sm:<store-name>:<project/secret[/version]>}'
105	parts:
106	list:
107	- name: 'gcp-sm'
108	description: 'The secretstore backend kind.'
109	- name: '<store-name>'
110	description: 'The name of the configured secretstore, for example `gcp_prod`.'
111	- name: '<project/secret[/version]>'
112	description: 'The Google Cloud project ID, secret name, and optional version.'
113	examples:
114	list:
115	- name: 'MySQL collector with password from Google Secret Manager'
116	description: \|
117	This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.
118	The password in the DSN connection string is not stored in plain text. Instead,
119	`${store:gcp-sm:gcp_prod:my-project/mysql-password}` tells Netdata to fetch the
120	latest version of the `mysql-password` secret from the `my-project` project using
121	the `gcp_prod` store, and substitute its value into the DSN at runtime.
122	content: \|
123	# /etc/netdata/go.d/mysql.conf
124	jobs:
125	- name: mysql_prod
126	dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"
127	- name: 'HTTP check collector with password from Google Secret Manager'
128	description: \|
129	This example configures an HTTP check collector job in `/etc/netdata/go.d/httpcheck.conf`.
130	The `password` field uses a secret reference instead of a plain-text value. Netdata fetches
131	the `api-password` secret from the `my-project` project and substitutes its value into the
132	`password` field at runtime.
133	content: \|
134	# /etc/netdata/go.d/httpcheck.conf
135	jobs:
136	- name: internal_api
137	url: https://api.example.com/health
138	username: netdata
139	password: "${store:gcp-sm:gcp_prod:my-project/api-password}"
140	troubleshooting:
141	problems:
142	list:
143	- name: 'Find the exact error'
144	description: \|
145	Check the Netdata Agent logs when the collector starts or restarts. GCP resolver errors include messages such as `metadata token request returned HTTP 404`, `invalid project ID`, `invalid version`, or `reading service account file`.
146	- name: 'Metadata mode does not work'
147	description: \|
148	`mode: metadata` requires the Google metadata server. If Netdata is not running in a supported Google Cloud environment, switch to `service_account_file`.
149	- name: 'Service account file cannot be read'
150	description: \|
151	Check the file path, the JSON contents, and that the `netdata` user can read the file. Because the file contains a private key, keep its permissions as tight as possible.
152	- name: 'Permission denied or secret not found'
153	description: \|
154	Make sure the Google identity used by Netdata can access the referenced secret, and confirm that the operand uses the correct `project/secret` or `project/secret/version` format.