metadata.yaml · cryptotaxi247/netdata-1

Code Commits Issues Pulls Sessions CI/CD

master

yaml 163 lines 8.17 KB

Raw

1	# yamllint disable rule:line-length
2	---
3	id: 'secretstore-aws-sm'
4	meta:
5	kind: 'aws-sm'
6	name: 'AWS Secrets Manager'
7	link: 'https://aws.amazon.com/secrets-manager/'
8	icon_filename: 'aws.svg'
9	keywords:
10	- 'secretstore'
11	- 'secrets'
12	- 'aws'
13	- 'aws-sm'
14	- 'aws secrets manager'
15	overview:
16	description: \|
17	Netdata can pull collector credentials directly from AWS Secrets Manager at runtime, so you never store passwords or tokens in plain-text configuration files.
18
19	This page covers AWS Secrets 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 AWS Secrets Manager. It does not create, rotate, or manage those secrets. If you use `secret-name#key`, the secret value must be stored as a JSON `SecretString`.
22	setup:
23	prerequisites:
24	list:
25	- title: 'Provide AWS credentials'
26	description: \|
27	Choose one supported authentication mode and make sure the Netdata Agent can obtain credentials for it:
28
29	- `env`: set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for the Netdata service. Set `AWS_SESSION_TOKEN` too if you use temporary credentials.
30	- `ecs`: run Netdata in ECS with a task role so `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is available.
31	- `imds`: run Netdata on EC2 with an instance profile and access to IMDSv2.
32
33	For production on AWS, prefer `ecs` or `imds` over `env` so credentials are supplied by the platform instead of being stored in the Netdata service environment.
34	- title: 'Allow access to Secrets Manager'
35	description: \|
36	The AWS identity used by this secretstore must have the `secretsmanager:GetSecretValue` permission on the secrets you reference in collector configs. Scope the IAM policy to only the secret ARNs Netdata needs.
37	- title: 'Plan for file-based changes'
38	description: \|
39	If you edit `/etc/netdata/go.d/ss/aws-sm.conf`, restart the Netdata Agent to load the updated secretstore definition.
40	configuration:
41	file:
42	name: 'go.d/ss/aws-sm.conf'
43	options:
44	description: 'The following options can be defined for this secretstore backend.'
45	folding:
46	title: 'Config options'
47	enabled: true
48	list:
49	- name: 'auth_mode'
50	description: 'How Netdata obtains AWS credentials.'
51	default_value: 'env'
52	required: true
53	detailed_description: \|
54	Supported values:
55
56	- `env`: read credentials from the Netdata process environment.
57	- `ecs`: read credentials from the ECS task credentials endpoint.
58	- `imds`: read credentials from the EC2 Instance Metadata Service.
59
60	For production on AWS, prefer `ecs` or `imds` when Netdata runs on ECS or EC2. Use `env` when you intentionally manage credentials in the Netdata service environment.
61	- name: 'region'
62	description: 'AWS region used for Secrets Manager requests. There is no automatic region detection — you must always set this explicitly.'
63	default_value: ''
64	required: true
65	- name: 'timeout'
66	description: 'Timeout in seconds for HTTP requests made by this secretstore backend.'
67	default_value: 3
68	required: false
69	examples:
70	folding:
71	title: 'Example configuration'
72	enabled: true
73	list:
74	- name: 'Environment credentials'
75	description: 'Use environment-provided AWS credentials for the Netdata service.'
76	config: \|
77	jobs:
78	- name: aws_prod
79	auth_mode: env
80	region: us-east-1
81	- name: 'ECS task role'
82	description: 'Use credentials provided to a Netdata task running in ECS.'
83	config: \|
84	jobs:
85	- name: aws_ecs
86	auth_mode: ecs
87	region: us-east-1
88	- name: 'EC2 instance profile'
89	description: 'Use the instance profile attached to the EC2 instance running Netdata.'
90	config: \|
91	jobs:
92	- name: aws_imds
93	auth_mode: imds
94	region: us-east-1
95	collector_configs:
96	description: \|
97	Use the `${store:aws-sm:...}` syntax to reference AWS Secrets Manager secrets in any string field of a collector configuration file.
98	summary:
99	operand_format: 'secret-name[#key]'
100	example_operand: 'netdata/mysql#password'
101	format:
102	description: \|
103	The operand is `secret-name` or `secret-name#key`.
104
105	- Use `secret-name` to return the whole `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql/password}`.
106	- Use `secret-name#key` to read one top-level field from a JSON `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql#password}`.
107	- If you use `#key`, Netdata parses the secret value as JSON. Secret resolution fails if the value is not valid JSON or if the key does not exist.
108	- Nested paths such as `parent.child` are not interpreted as nested JSON lookups.
109	syntax: '${store:aws-sm:<store-name>:<secret-name[#key]>}'
110	parts:
111	list:
112	- name: 'aws-sm'
113	description: 'The secretstore backend kind.'
114	- name: '<store-name>'
115	description: 'The name of the configured secretstore, for example `aws_prod`.'
116	- name: '<secret-name[#key]>'
117	description: 'The AWS Secrets Manager secret name, optionally followed by `#key` to read one field from a JSON `SecretString`.'
118	examples:
119	list:
120	- name: 'MySQL collector with password from AWS Secrets Manager'
121	description: \|
122	This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.
123	The password in the DSN connection string is not stored in plain text. Instead,
124	`${store:aws-sm:aws_prod:netdata/mysql#password}` tells Netdata to fetch the secret
125	named `netdata/mysql` from the `aws_prod` store, extract the `password` field from
126	its JSON value, and substitute it into the DSN at runtime.
127	content: \|
128	# /etc/netdata/go.d/mysql.conf
129	jobs:
130	- name: mysql_prod
131	dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"
132	- name: 'Elasticsearch collector with HTTP basic auth'
133	description: \|
134	This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.
135	The `password` field uses a secret reference instead of a plain-text password. Netdata fetches
136	the secret named `netdata/elasticsearch/password` from the `aws_prod` store and substitutes
137	its full value into the `password` field at runtime.
138	content: \|
139	# /etc/netdata/go.d/elasticsearch.conf
140	jobs:
141	- name: es_prod
142	url: https://elasticsearch.example.com:9200
143	username: netdata
144	password: "${store:aws-sm:aws_prod:netdata/elasticsearch/password}"
145	troubleshooting:
146	problems:
147	list:
148	- name: 'Find the exact error'
149	description: \|
150	Check the Netdata Agent logs when the collector starts or restarts. AWS resolver errors include messages such as `AWS_ACCESS_KEY_ID is not set`, `parsing SecretString as JSON`, or `key 'password' not found in SecretString JSON`.
151	- name: 'AWS credentials are not found'
152	description: \|
153	Check the selected `auth_mode`.
154
155	- For `env`, make sure the Netdata service has `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
156	- For `ecs`, make sure Netdata runs in ECS and `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is available.
157	- For `imds`, make sure the EC2 instance profile is attached and IMDSv2 is reachable.
158	- name: 'Access denied or wrong region'
159	description: \|
160	Confirm the configured `region` and make sure the AWS identity used by Netdata can read the referenced secret in that region.
161	- name: 'JSON key lookup fails'
162	description: \|
163	If you use `secret-name#key`, the secret must be stored as a JSON `SecretString`, and the requested key must exist as a top-level field in that JSON object.