@cryptotaxi247 / netdata / commits / 8c1ced85d

Cloud Docs: updated (#20661)

Co-authored-by: ilyam8 <ilya@netdata.cloud>

Kanela committed Jul 13, 2025 at 09:31 UTC 8c1ced85dc0567119a43140ef53a3d4dcc979639

8 files changed +651 -458

docs/netdata-cloud/README.md

+102 -56

@@ -1,79 +1,123 @@

1 # Netdata Cloud

3 -Netdata Cloud is a powerful service that transforms standalone Netdata Agent installations into a unified, scalable observability solution. It achieves this without centralizing metric storage, ensuring optimal performance and cost-effectiveness even at enterprise scale.

3 +Netdata Cloud is a powerful service that transforms your standalone Netdata Agent installations into a unified, scalable observability solution. It achieves this without centralizing metric storage, ensuring optimal performance and cost-effectiveness even at enterprise scale.

5 -By serving as a lightweight control plane, Netdata Cloud provides:

5 +:::info

7 -- Seamless coordination across multiple teams and environments

8 -- Unified visibility across cloud providers and data centers

9 -- Real-time, high-fidelity monitoring at any scale

10 -- Flexible observability pipelines that grow with your infrastructure

7 +By serving as a lightweight control plane, Netdata Cloud provides you with:

8 +

9 +- **Seamless coordination** across multiple teams and environments

10 +- **Unified visibility** across cloud providers and data centers

11 +- **Real-time, high-fidelity** monitoring at any scale

12 +- **Flexible observability** pipelines that grow with your infrastructure

13 +

14 +:::

15 +

16 +<details>

17 +<summary>Click to see visual representation of the architecture</summary>

19 ```mermaid

20 flowchart TB

14 - NC("☁️ Netdata Cloud

15 - Horizontal scalability,

16 - Role based access,

17 - Access from anywhere,

18 - Central dispatch of Alert notifications

19 - Custom Dashboards,

20 - Advanced customization,

21 - ")

22 - Users[["✨ Unified Dashboards

23 - across the infrastructure,

24 - multi-cloud, hybrid-cloud"]]

25 - Notifications["🔔 Alert Notifications

26 - Slack, e-mail, Mobile App,

27 - PagerDuty, and more"]

28 - Users <--> NC

29 - NC -->|deduplicated| Notifications

30 - subgraph On-Prem Infrastructure

31 - direction TB

32 - Agents("🌎 Netdata Agents

33 - Standalone,

34 - Children, Parents

35 - (possibly overlapping)")

36 - TimeSeries[("Time-Series

37 - metric samples

38 - database")]

39 - PrivateAgents("🔒 Private

40 - Netdata Agents")

41 - Agents <--> TimeSeries

42 - Agents ---|stream| PrivateAgents

43 - end

44 - NC <-->|secure connection| Agents

21 + NC[NC]

22 + Users[Users]

23 + Notifications[Notifications]

24 +

25 + NC("**Netdata Cloud**

26 +- Horizontal scalability

27 +- Role based access

28 +- Access from anywhere

29 +- Central dispatch of Alert notifications

30 +- Custom Dashboards

31 +- Advanced customization")

32 +

33 +Users("**Unified Dashboards**

34 +across the infrastructure,

35 +multi-cloud, hybrid-cloud")

36 +

37 +Notifications("**Alert Notifications**

38 +Slack, e-mail, Mobile App,

39 +PagerDuty, and more")

40 +

41 +Users <--> NC

42 +NC --> Notifications

43 +

44 +subgraph infrastructure["On-Prem Infrastructure"]

45 +direction TB

46 +Agents[Agents]

47 +TimeSeries[TimeSeries]

48 +PrivateAgents[PrivateAgents]

49 +

50 +Agents("**Netdata Agents**

51 +Standalone,

52 +Children, Parents

53 +(possibly overlapping)")

54 +

55 +TimeSeries("Time-Series

56 +metric samples

57 +database")

58 +

59 +PrivateAgents("Private

60 +Netdata Agents")

61 +

62 +Agents <--> TimeSeries

63 +Agents --- PrivateAgents

64 +end

65 +

66 +NC <--> Agents

67 +

68 +classDef cloud fill: #e8f4fd, stroke: #4a90e2, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

69 +classDef users fill: #fff2e8, stroke: #f39c12, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

70 +classDef notifications fill: #ffe8e8, stroke: #e74c3c, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

71 +classDef agents fill: #e8f5e8, stroke: #27ae60, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

72 +classDef timeseries fill: #f3e8ff, stroke: #9b59b6, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

73 +classDef private fill: #f0f8ff, stroke: #87ceeb, stroke-width: 2px, color: #2c3e50, rx: 10, ry: 10

74 +classDef subgraphStyle fill: #f8f9fa, stroke: #6c757d, stroke-width: 2px, color: #2c3e50, rx: 15, ry: 15

75 +

76 +class NC cloud

77 +class Users users

78 +class Notifications notifications

79 +class Agents agents

80 +class TimeSeries timeseries

81 +class PrivateAgents private

82 +class infrastructure subgraphStyle

83 ```

47 -Netdata Cloud provides the following features, on top of what the Agents already provide:

85 +</details>

86 +

87 +Netdata Cloud provides you with the following features, on top of what the Agents already provide:

49 -| Feature | Description |

50 -|:------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

51 -| **Horizontal Scalability** | • Scale your observability infrastructure effortlessly • Add [Parents and Children](/docs/observability-centralization-points/README.md) as needed • Manage all nodes from a single [Space](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md#spaces) |

52 -| [**Role-Based Access Control (RBAC)**](/docs/netdata-cloud/authentication-and-authorization/role-based-access-model.md) | • Fine-grained access management • Control team member privileges across your Space • Secure, role-appropriate access to monitoring data |

53 -| **Global Remote Access** | • Access your monitoring from anywhere • No VPN configuration required • Secure access to local dashboards while data stays on premises |

54 -| **Centralized Alert Management** | • Unified alert dispatch from a central location • Cloud-specific alerts and monitoring • Mobile push notifications via [Netdata Mobile App](/integrations/cloud-notifications/integrations/netdata_mobile_app.md) (paid plans) |

55 -| [**Custom Dashboards**](/docs/dashboards-and-charts/dashboards-tab.md) | • Create and save custom views • Share dashboards across teams • Build focused views for specific needs |

56 -| **Personal Customization** | • Individual user visualization preferences • Tailored dashboard experiences • Flexible viewing options for different roles |

89 +| Feature | Description |

90 +|:------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

91 +| **Horizontal Scalability** | • Scale your observability infrastructure effortlessly • Add [Parents and Children](/docs/observability-centralization-points/README.md) as needed • Manage all nodes from a single [Space](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md) |

92 +| [**Role-Based Access Control (RBAC)**](/docs/netdata-cloud/authentication-and-authorization/role-based-access-model.md) | • Fine-grained access management • Control team member privileges across your Space • Secure, role-appropriate access to monitoring data |

93 +| **Global Remote Access** | • Access your monitoring from anywhere • No VPN configuration required • Secure access to local dashboards while data stays on premises |

94 +| **Centralized Alert Management** | • Unified alert dispatch from a central location • Cloud-specific alerts and monitoring • Mobile push notifications via [Netdata Mobile App](/integrations/cloud-notifications/integrations/netdata_mobile_app.md) (paid plans) |

95 +| [**Custom Dashboards**](/docs/dashboards-and-charts/dashboards-tab.md) | • Create and save custom views • Share dashboards across teams • Build focused views for specific needs |

96 +| **Personal Customization** | • Individual user visualization preferences • Tailored dashboard experiences • Flexible viewing options for different roles |

58 -## Stored metadata

98 +## Stored Metadata

100 Netdata Cloud doesn't store your metrics or logs.

101

62 -**What Netdata Cloud Does Store**:

102 +:::info

103 +

104 +**What Netdata Cloud Does Store:**

105

106 - Node information and labels

107 - Metric names, labels, and retention periods

108 - Active collectors

109 - Alert configurations and state changes

110

69 -**How Data Flows**:

111 +**How Data Flows:**

112

113 1. Metadata (listed above) is synchronized between Agents and Cloud

114 2. Metric data and logs remain stored locally on your Agents

115 3. When you view dashboards:

116 - Data is transferred directly from Agents to your browser via Cloud

117 - Cloud aggregates responses from multiple Agents into a unified view

76 - - No metric or log data is stored in Cloud during this process

118 + - No metric or log data is stored in the Cloud during this process

119 +

120 +:::

121

122 ## Fidelity and Resolution

123

@@ -87,15 +131,17 @@ The data you see is identical to what you would get by accessing Agents directly

131

132 ## FAQ

133

90 -<details><summary>details</summary>

134 +<details>

135 +<summary>Does the Cloud require Observability Centralization Points?</summary>

136

92 -### Does the Cloud require Observability Centralization Points?

93 -

94 -No. Any or all Agents can be connected directly to the Cloud.

137 +No. You can connect any or all Agents directly to the Cloud.

138

139 We recommend creating [Observability Centralization Points](/docs/observability-centralization-points/README.md), as required for operational efficiency (ephemeral nodes, teams or services isolation, central control of alerts, production systems performance), security policies (internet isolation), or cost optimization (use existing capacities before allocating new ones).

140

98 -### When I have Parents, do I need to connect the Children to the Cloud too?

141 +</details>

142 +

143 +<details>

144 +<summary>When I have Parents, do I need to connect the Children to the Cloud too?</summary>

145

146 No, it is not necessary, but it provides high availability.

147

@@ -109,6 +155,6 @@ The Cloud prefers:

155

156 - The closest (to the Child) Parent available for [Top Monitoring](/docs/top-monitoring-netdata-functions.md). The streaming protocol of Parents and Children is able to forward such requests to the leaf child, via the Parents, to respond with live and accurate data.

157

112 -Children may be connected to the Cloud for high-availability, in cases where their Parents become unreachable.

158 +You may connect Children to the Cloud for high-availability, in cases where their Parents become unreachable.

159

160 </details>

docs/netdata-cloud/authentication-and-authorization/README.md

+12 -8

@@ -1,17 +1,21 @@

1 # Authentication & Authorization

3 -This documentation covers the authentication methods available in Netdata Cloud and explains how authorization controls access and permissions for team members.

3 +Learn how to authenticate with Netdata Cloud and manage team member permissions through role-based authorization.

5 ## Authentication

7 -| Method | Description | Setup Process |

8 -|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|

9 -| Email | • Standard email and password authentications • Recommended for individual user | 1. Visit Netdata Cloud 2. Enter email address 3. Follow verification process 4. Set up password (new accounts) |

10 -| Google OAuth | • Authentication using Google account credentials • Account will be linked to your Google email address | 1. Visit Netdata Cloud 2. Click Google sign-in 3. Complete Google authentication flow |

11 -| GitHub OAuth | • Authentication using GitHub account credentials • Account will be linked to your GitHub email address | 1. Visit Netdata Cloud 2. Click GitHub sign-in 3. Complete GitHub authentication flow |

12 -| Enterprise SSO | • Advanced authentication for organizations using identity providers • Features: &emsp; - Identity provider integration &emsp; - Centralized management &emsp; - Enhanced security &emsp; - Audit logging | See [Enterprise SSO documentation](/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md) |

7 +| Method | Description | Setup Process |

8 +|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------|

9 +| **Email** | • Standard email and password authentication • Recommended for individual users | 1. Visit Netdata Cloud 2. Enter email address 3. Follow verification process 4. Set up password (new accounts) |

10 +| **Google OAuth** | • Authentication using Google account credentials • Your account will be linked to your Google email address | 1. Visit Netdata Cloud 2. Click Google sign-in 3. Complete Google authentication flow |

11 +| **GitHub OAuth** | • Authentication using GitHub account credentials • Your account will be linked to your GitHub email address | 1. Visit Netdata Cloud 2. Click GitHub sign-in 3. Complete GitHub authentication flow |

12 +| **Enterprise SSO** | • Advanced authentication for organizations using identity providers • Features: &emsp; - Identity provider integration &emsp; - Centralized management &emsp; - Enhanced security &emsp; - Audit logging | See [Enterprise SSO documentation](/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md) |

14 -> **Important**: When using OAuth, your Netdata Cloud account will be automatically associated with the email address provided by the OAuth provider. Ensure you have access to this email address.

14 +:::important

15 +

16 +When using OAuth, your Netdata Cloud account will be automatically associated with the email address provided by the OAuth provider. Ensure you have access to this email address.

17 +

18 +:::

20 ## Authorization

docs/netdata-cloud/authentication-and-authorization/api-tokens.md

+61 -16

@@ -1,37 +1,82 @@

1 # API Tokens

3 -API tokens (Bearer tokens) enable programmatic access to Netdata resources. These tokens authenticate and authorize API requests, allowing you to interact with Netdata services securely from external applications, scripts, or integrations.

3 +API tokens (Bearer tokens) enable you to access Netdata resources programmatically. These tokens authenticate and authorize API requests, allowing you to interact with Netdata services securely from external applications, scripts, or integrations.

5 -> **Important**: API tokens never expire but should be managed carefully as they grant access to your Netdata resources.

5 +:::important

6 +

7 +API tokens never expire but should be managed carefully as they grant access to your Netdata resources.

8 +

9 +:::

11 ## Token Generation

9 -**Location**:

13 +**Location**

11 -Access token management through the Netdata UI:

15 +You can access token management through the Netdata UI:

17 1. Click your profile picture in the bottom-left corner

18 2. Select "User Settings"

19 3. Navigate to the API Tokens section

17 -**Available Scopes**:

21 +**Available Scopes**

22 +

23 +You can limit each token to specific scopes that define its access permissions:

24 +

25 +| Scope | Description | API Access |

26 +|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------|

27 +| `scope:all` | Grants the same permissions as the user who created the token. Use case: Terraform provider integration. | Full access to all API endpoints |

28 +| `scope:agent-ui` | Used by Agent for accessing the Cloud UI | Access to UI-related endpoints |

29 +| `scope:grafana-plugin` | Used for the [Netdata Grafana plugin](https://github.com/netdata/netdata-grafana-datasource-plugin/blob/master/README.md) to access Netdata charts | Access to chart and data endpoints |

30 +

31 +## API Versions

32 +

33 +Netdata provides three API versions that you can access with API tokens:

19 -Each token can be limited to specific scopes that define its access permissions:

35 +- **v1**: The original API, focused on single-node operations

36 +- **v2**: Multi-node API with advanced grouping and aggregation capabilities

37 +- **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features

21 -| Scope | Description |

22 -|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|

23 -| `scope:all` | Grants the same permissions as the user who created the token. Use case: Terraform provider integration. |

24 -| `scope:agent-ui` | Used by Agent for accessing the Cloud UI |

25 -| `scope:grafana-plugin` | Used for the [Netdata Grafana plugin](https://github.com/netdata/netdata-grafana-datasource-plugin/blob/master/README.md) to access Netdata charts |

39 +## Common Endpoints

27 -> **Info**

28 ->

29 -> Currently, Netdata Cloud is not exposing the stable API.

41 +With appropriate API tokens, you can access endpoints including:

31 -## Example usage

43 +- `/api/v2/nodes` - Node information

44 +- `/api/v2/data` - Multi-dimensional data queries

45 +- `/api/v2/contexts` - Context metadata

46 +- `/api/v2/weights` - Metric scoring/correlation

47 +- `/api/v2/q` - Full-text search

48 +- `/api/v1/info` - Agent information

49 +- `/api/v1/charts` - Chart information

50 +- `/api/v1/data` - Single node data queries

33 -**get the Netdata Cloud space list**

52 +:::info

53 +

54 +Currently, Netdata Cloud is not exposing the stable API.

55 +

56 +:::

57 +

58 +## Example Usage

59 +

60 +**Get the Netdata Cloud space list**

62 ```console

63 curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/spaces

64 ```

65 +

66 +**Get node information**

67 +

68 +```console

69 +curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/nodes

70 +```

71 +

72 +**Query metric data**

73 +

74 +```console

75 +curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/data?contexts=system.cpu&after=-600

76 +```

77 +

78 +**Get context information**

79 +

80 +```console

81 +curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/contexts

82 +```

docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md

+26 -19

@@ -1,47 +1,54 @@

1 # Enterprise SSO Authentication

3 -Enterprise Single Sign-On (SSO) integration enables organizations to manage Netdata Cloud access through their existing identity management solution. This simplifies user authentication and improves security through centralized access control.

3 +Enterprise Single Sign-On (SSO) integration enables you to manage Netdata Cloud access through your existing identity management solution. This simplifies user authentication and improves security through centralized access control.

5 -> **Important**: Enterprise SSO handles authentication only. User and role management must be configured separately within Netdata Cloud.

5 +:::important

6 +

7 +Enterprise SSO handles authentication only. You must configure user and role management separately within Netdata Cloud.

8 +

9 +:::

11 ## Prerequisites

9 -| Requirement | Details |

10 -|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|

11 -| SSO Provider | Must be [supported by Netdata](https://learn.netdata.cloud/docs/netdata-cloud/authentication-&-authorization/cloud-authentication-&-authorization-integrations) |

12 -| Account Status | Active Netdata Cloud account |

13 -| Subscription | Business plan or higher |

14 -| Access Level | Space Administrator permissions |

13 +| Requirement | Details |

14 +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|

15 +| **SSO Provider** | Must be [supported by Netdata](https://learn.netdata.cloud/docs/netdata-cloud/authentication-&-authorization/cloud-authentication-&-authorization-integrations) |

16 +| **Account Status** | Active Netdata Cloud account |

17 +| **Subscription** | Business plan or higher |

18 +| **Access Level** | Space Administrator permissions |

20 ## Setup

18 -**Netdata Cloud Configuration**:

22 +### Netdata Cloud Configuration

24 To configure SSO in your Netdata Cloud space:

22 -1. Navigate to Space Settings (gear icon above profile)

26 +1. Navigate to Space Settings (⚙️ above profile)

27 2. Select User Management → Authentication & Authorization

28 3. Locate your desired SSO integration

29 4. Click "Configure" and fill in the required integration attributes

27 -**Domain Verification**:

31 +### Domain Verification

33 Domain verification is required to establish secure SSO connectivity:

31 -1. Access the DNS TXT record:

35 +1. **Access the DNS TXT record:**

36 - Go to Space Settings → User Management → Authentication & Authorization

37 - Click "DNS TXT record" button to reveal verification code

34 -2. Add DNS Record:

38 +

39 +2. **Add DNS Record:**

40 - Log into your domain provider's DNS management

41 - Create a new TXT record with these specifications:

38 - | Field | Value |

39 - |--------------------------|----------------------------------------------|

40 - | Value/Answer/Description | `"netdata-verification=[VERIFICATION CODE]"` |

41 - | Name/Host/Alias | Leave blank or use @ for subdomain |

42 - | TTL (Time to Live) | 86400 (or use provider default) |

43 +| Field | Value |

44 +|------------------------------|----------------------------------------------|

45 +| **Value/Answer/Description** | `"netdata-verification=[VERIFICATION CODE]"` |

46 +| **Name/Host/Alias** | Leave blank or use @ for subdomain |

47 +| **TTL (Time to Live)** | 86400 (or use provider default) |

48 +

49 +### SSO Provider Configuration

44 -**SSO Provider Configuration**: Consult your provider's documentation for detailed instructions.

51 +Consult your provider's documentation for detailed instructions.

53 ## How to Authenticate

docs/netdata-cloud/authentication-and-authorization/role-based-access-model.md

+229 -152

@@ -1,152 +1,229 @@

1 -# Role-Based Access model (RBAC)

2 -

3 -Netdata Cloud's Role-Based Access mechanism allows you to control what functionalities a user can access.

4 -

5 -## Roles

6 -

8 -|:---------------------------------------------------------------------------------------------------------------------------------------|:-------------------|:-------------------|:-------------------|:-----------------------|

14 -

15 -## Features

16 -

17 -### Space Management

18 -

20 -|:-----------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|

23 -| Delete Space | :heavy_check_mark: | - | - | - | - |

24 -| Change name | :heavy_check_mark: | - | - | - | - |

25 -| Change description | :heavy_check_mark: | - | - | - | - |

26 -| Change slug | :heavy_check_mark: | - | - | - | - |

27 -| Change preferred nodes | :heavy_check_mark: | - | - | - | - |

28 -

29 -### Node Management

30 -

32 -|:------------------------------------------|:------------------:|:------------------:|:------------------:|:------------:|:-----------:|

33 -| See all Nodes in Space (_All Nodes_ Room) | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

34 -| Connect Node to Space | :heavy_check_mark: | - | - | - | - |

35 -| Delete Node from Space | :heavy_check_mark: | - | - | - | - |

36 -

37 -### User Management

38 -

40 -|:-----------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

41 -| See all Users in Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

42 -| Invite new User to Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

43 -| Delete Pending Invitation to Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

44 -| Delete User from Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

45 -| Appoint Administrators | :heavy_check_mark: | - | - | - | - |

46 -| Appoint Billing user | :heavy_check_mark: | - | - | - | - |

47 -| Appoint Managers | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

48 -| Appoint Troubleshooters | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

49 -| Appoint Observer | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

50 -| Appoint Member | :heavy_check_mark: | - | - | - | - |

52 -| Invite existing user to Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

53 -| Remove user from Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

54 -

55 -### Room Management

56 -

58 -|:-----------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

59 -| See all Rooms in a Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

60 -| Join any Room in a Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

62 -| Create a new Room in a Space | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

63 -| Delete Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

64 -| Change Room name | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

65 -| Change Room description | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

66 -| Add existing Nodes to Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

67 -| Remove Nodes from Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

68 -

69 -### Notification Management

70 -

72 -|:--------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

74 -| Add new configuration | :heavy_check_mark: | - | - | - | - | |

75 -| Enable/Disable configuration | :heavy_check_mark: | - | - | - | - | |

76 -| Edit configuration | :heavy_check_mark: | - | - | - | - | Some exceptions apply depending on [service level](/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/manage-notification-methods.md#available-actions-per-notification-method-based-on-service-level) |

77 -| Delete configuration | :heavy_check_mark: | - | - | - | - | |

79 -| See Space Alert notification silencing rules | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

80 -| Add new Space Alert notification silencing rule | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

81 -| Enable/Disable Space Alert notification silencing rule | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

82 -| Edit Space Alert notification silencing rule | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

83 -| Delete Space Alert notification silencing rule | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

85 -

86 -> **Note**

87 ->

88 -> Enable, Edit and Add actions over specific notification methods will only be allowed if your plan has access to those (see [service classification](/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/centralized-cloud-notifications-reference.md#service-classification))

89 -

90 -### Dashboards

91 -

93 -|:-----------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

96 -| Edit any dashboard in Room | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - |

98 -| Delete any dashboard in Room | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - |

100 -

101 -### Functions

102 -

104 -|:-------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

106 -| Run any function in Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

108 -| Run sensitive function in Room | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

109 -

110 -### Events feed

111 -

113 -|:-----------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

116 -

117 -### Billing

118 -

120 -|:---------------------------|:------------------:|:-----------:|:------------------:|:------------:|:------------------:|:----------------------------------------------------------------|

121 -| See Plan & Billing details | :heavy_check_mark: | - | - | - | :heavy_check_mark: | Current plan and usage figures |

122 -| Update plans | :heavy_check_mark: | - | - | - | - | This includes cancelling current plan (going to Community plan) |

123 -| See invoices | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

124 -| Manage payment methods | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

125 -| Update billing email | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

126 -

127 -### Dynamic Configuration Manager

128 -

129 -> **Note**

130 ->

131 -> Netdata Cloud paid subscription required for all actions except "List All".

132 -

134 -|:--------------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|

136 -| Enable/Disable | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

137 -| Add | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

138 -| Update | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

139 -| Remove | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

140 -| Test | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

141 -| View | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

142 -| View File Format | :heavy_check_mark: | :heavy_check_mark: | - | - | - |

143 -

144 -### Other permissions

145 -

147 -|:---------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|

149 -| Add Bookmark to Space | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - |

150 -| Delete Bookmark from Space | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - |

1 +# Role-Based Access Control (RBAC)

2 +

3 +## Overview

4 +

5 +You can control what functionalities users can access in Netdata Cloud through the Role-Based Access mechanism. RBAC helps you secure your monitoring infrastructure by ensuring team members only access the data and features they need for their specific responsibilities.

6 +

7 +**What RBAC enables you to do:**

8 +

9 +- Restrict access to sensitive monitoring data

10 +- Control who can modify configurations and settings

11 +- Manage billing and subscription access

12 +- Organize teams with appropriate permission levels

13 +- Maintain audit trails of user actions

14 +

15 +## Choose the Right Role

16 +

17 +### Role Selection Guide

18 +

19 +**When assigning roles, consider:**

20 +

21 +| **If the user needs to...** | **Recommended Role** |

22 +|:-------------------------------------------------------------------------------------------------|:---------------------|

23 +| **Full system control** - manage everything including billing, users, and all configurations | **Admin** |

24 +| **Team and infrastructure management** - manage users, rooms, and configurations but not billing | **Manager** |

25 +| **Active troubleshooting** - investigate issues, run diagnostics, create dashboards | **Troubleshooter** |

26 +| **View-only access** - monitor specific systems without making changes | **Observer** |

27 +| **Billing management** - handle invoices and payments without system access | **Billing** |

28 +

29 +## Quick Reference

30 +

31 +<details>

32 +<summary>Role Comparison by Plan</summary>

33 +

35 +|:---------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:|:----------------------:|

41 +

42 +</details>

43 +

44 +### Key Permissions Summary

45 +

47 +|:---------------------|:------------:|:----------------:|:-------------------:|:-------------------:|:------------:|

54 +

55 +## Detailed Permissions

56 +

57 +<details>

58 +<summary>Space Management</summary>

59 +

61 +|:---------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:----------|

64 +| **Delete Space** | :heavy_check_mark: | - | - | - | - | |

65 +| **Change name** | :heavy_check_mark: | - | - | - | - | |

66 +| **Change description** | :heavy_check_mark: | - | - | - | - | |

67 +| **Change slug** | :heavy_check_mark: | - | - | - | - | |

68 +| **Change preferred nodes** | :heavy_check_mark: | - | - | - | - | |

69 +

70 +</details>

71 +

72 +<details>

73 +<summary>Node Management</summary>

74 +

76 +|:----------------------------------------------|:------------------:|:------------------:|:------------------:|:------------:|:-----------:|:----------|

77 +| **See all Nodes in Space (_All Nodes_ Room)** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

78 +| **Connect Node to Space** | :heavy_check_mark: | - | - | - | - | |

79 +| **Delete Node from Space** | :heavy_check_mark: | - | - | - | - | |

80 +

81 +</details>

82 +

83 +<details>

84 +<summary>User Management</summary>

85 +

87 +|:---------------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

88 +| **See all Users in Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

89 +| **Invite new User to Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

90 +| **Delete Pending Invitation to Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

91 +| **Delete User from Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

92 +| **Appoint Administrators** | :heavy_check_mark: | - | - | - | - | |

93 +| **Appoint Billing user** | :heavy_check_mark: | - | - | - | - | |

94 +| **Appoint Managers** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

95 +| **Appoint Troubleshooters** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

96 +| **Appoint Observer** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

97 +| **Appoint Member** | :heavy_check_mark: | - | - | - | - | |

99 +| **Invite existing user to Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

100 +| **Remove user from Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

101 +

102 +</details>

103 +

104 +<details>

105 +<summary>Room Management</summary>

106 +

108 +|:---------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

109 +| **See all Rooms in a Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

110 +| **Join any Room in a Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

112 +| **Create a new Room in a Space** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

113 +| **Delete Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

114 +| **Change Room name** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

115 +| **Change Room description** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

116 +| **Add existing Nodes to Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

117 +| **Remove Nodes from Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

118 +

119 +</details>

120 +

121 +<details>

122 +<summary>Notification Management</summary>

123 +

125 +|:------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

127 +| **Add new configuration** | :heavy_check_mark: | - | - | - | - | |

128 +| **Enable/Disable configuration** | :heavy_check_mark: | - | - | - | - | |

129 +| **Edit configuration** | :heavy_check_mark: | - | - | - | - | Some exceptions apply depending on [service level](/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/manage-notification-methods.md#available-actions-per-notification-method-based-on-service-level) |

130 +| **Delete configuration** | :heavy_check_mark: | - | - | - | - | |

132 +| **See Space Alert notification silencing rules** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

133 +| **Add new Space Alert notification silencing rule** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

134 +| **Enable/Disable Space Alert notification silencing rule** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

135 +| **Edit Space Alert notification silencing rule** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

136 +| **Delete Space Alert notification silencing rule** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

138 +

139 +</details>

140 +

141 +<details>

142 +<summary>Dashboards</summary>

143 +

145 +|:---------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

148 +| **Edit any dashboard in Room** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

150 +| **Delete any dashboard in Room** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

152 +

153 +</details>

154 +

155 +<details>

156 +<summary>Functions</summary>

157 +

159 +|:-----------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

161 +| **Run any function in Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

163 +| **Run sensitive function in Room** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

164 +

165 +</details>

166 +

167 +<details>

168 +<summary>Events Tab</summary>

169 +

171 +|:---------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

174 +

175 +</details>

176 +

177 +<details>

178 +<summary>Billing</summary>

179 +

181 +|:-------------------------------|:------------------:|:-----------:|:------------------:|:------------:|:------------------:|:----------------------------------------------------------------|

182 +| **See Plan & Billing details** | :heavy_check_mark: | - | - | - | :heavy_check_mark: | Current plan and usage figures |

183 +| **Update plans** | :heavy_check_mark: | - | - | - | - | This includes cancelling current plan (going to Community plan) |

184 +| **See invoices** | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

185 +| **Manage payment methods** | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

186 +| **Update billing email** | :heavy_check_mark: | - | - | - | :heavy_check_mark: | |

187 +

188 +</details>

189 +

190 +<details>

191 +<summary>Dynamic Configuration Manager</summary>

192 +

194 +|:------------------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:----------|

196 +| **Enable/Disable** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

197 +| **Add** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

198 +| **Update** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

199 +| **Remove** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

200 +| **Test** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

201 +| **View** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

202 +| **View File Format** | :heavy_check_mark: | :heavy_check_mark: | - | - | - | |

203 +

204 +</details>

205 +

206 +<details>

207 +<summary>Other Permissions</summary>

208 +

210 +|:-------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|:-----------:|:----------|

212 +| **Add Bookmark to Space** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

213 +| **Delete Bookmark from Space** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | - | - | |

216 +

217 +</details>

218 +

219 +:::note

220 +

221 +Enable, Edit and Add actions over specific notification methods will only be allowed if your plan has access to those (see [service classification](/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/centralized-cloud-notifications-reference.md#service-classification))

222 +

223 +:::

224 +

225 +:::note

226 +

227 +Netdata Cloud paid subscription required for all actions except "List All" in Dynamic Configuration Manager.

228 +

229 +:::

docs/netdata-cloud/node-rule-based-room-assignment.md

+49 -38

@@ -1,30 +1,57 @@

1 # Node Rule-Based Room Assignment

3 -Organize Nodes within Rooms automatically using configurable label-based rules. This feature simplifies infrastructure management by dynamically assigning Nodes to appropriate Rooms based on their host labels, eliminating manual intervention.

3 +You can organize Nodes within Rooms automatically using configurable label-based rules. This feature simplifies infrastructure management by dynamically assigning Nodes to appropriate Rooms based on their host labels, eliminating manual intervention.

5 -**Important**:

5 +## How It Works

7 -- Rules work with all Rooms except the "All Nodes" Room, as it includes all Nodes by default.

8 -- Creating and editing Rules requires Node management permissions.

9 -- Rules are evaluated in real-time as labels change.

10 -- Exclusion rules always override inclusion rules.

7 +Rules automatically assign Nodes to Rooms based on their host labels. When you create a rule, it continuously evaluates all Nodes and assigns them to the appropriate Room when they match your criteria.

8 +

9 +**Rule Evaluation Order:**

10 +

11 +- Exclusion rules are evaluated first

12 +- Inclusion rules are evaluated second

13 +

14 +In cases where both an inclusion and exclusion rule match, the exclusion rule takes precedence.

15 +

16 +:::important

17 +

18 +- You can use rules with all Rooms except the "All Nodes" Room, as it includes all Nodes by default

19 +- You need Node management permissions to create and edit Rules

20 +- Rules are evaluated in real-time as labels change

21 +- Exclusion rules always override inclusion rules

22 +

23 +:::

24 +

25 +## Create Your First Rule

26 +

27 +1. **Access Settings**

28 + - Click ⚙️ (Room settings)

29 + - Select "Nodes" tab

30 +

31 +2. **Create Rule**

32 + - Click "Add new Rule"

33 + - Select Action (Include/Exclude)

34 + - Add clause(s)

35 + - Save changes

37 ## Rule Structure

14 -The rules consist of the following elements:

39 +You can build rules with the following elements:

16 -| Element | Description |

17 -|:--------|:--------------------------------------------------------------------------------------------------|

18 -| Action | Determines whether matching Nodes will be included or excluded from the Room |

19 -| Clauses | Set of conditions that determine which Nodes match the Rule (all must be satisfied - logical AND) |

41 +| Element | Description |

42 +|:------------|:--------------------------------------------------------------------------------------------------|

43 +| **Action** | Determines whether matching Nodes will be included or excluded from the Room |

44 +| **Clauses** | Set of conditions that determine which Nodes match the Rule (all must be satisfied - logical AND) |

46 Each clause consists of:

23 -| Element | Description |

24 -|:---------|:-----------------------------|

25 -| Label | The host label to check |

26 -| Value | The comparison method |

27 -| Operator | The value to compare against |

48 +| Element | Description |

49 +|:-------------|:-----------------------------|

50 +| **Label** | The host label to check |

51 +| **Value** | The comparison method |

52 +| **Operator** | The value to compare against |

53 +

54 +**Example Rule Structure:**

56 Below is a conceptual representation of a rule that includes all production database Nodes. The structure is shown in YAML format for clarity:

@@ -41,7 +68,7 @@ Clauses:

69 ### Comparison Operators

44 -The following operators can be used to compare label values:

71 +You can use the following operators to compare label values:

73 | Operator | Description |

74 |:------------|:----------------------------------------------------|

@@ -50,24 +77,6 @@ The following operators can be used to compare label values:

77 | ends_with | Matches if the value ends with the specified text |

78 | contains | Matches if the text appears anywhere in the value |

53 -## Rule Evaluation Order

54 -

55 -- Exclusion rules are evaluated first

56 -- Inclusion rules are evaluated second

57 -

58 -In cases where both an inclusion and exclusion rule match, the exclusion rule takes precedence.

59 -

60 -## Creating Rules

61 -

62 -1. Access Settings

63 - - Click ⚙️ (Room settings)

64 - - Select "Nodes" tab

65 -2. Create Rule

66 - - Click "Add new Rule"

67 - - Select Action (Include/Exclude)

68 - - Add clause(s)

69 - - Save changes

70 -

80 ## Membership Status

82 Nodes can have multiple membership types in a Room:

@@ -80,6 +89,8 @@ Nodes can have multiple membership types in a Room:

90 You can view each Node's membership status in the Room's Nodes table under the "Membership" column.

83 -> **Note**

84 ->

85 -> Group membership can be either STATIC or RULE—these work independently. A node can belong to groups through STATIC assignments (added manually) or through RULE assignments (matched automatically). RULEs cannot override STATIC memberships, and removing a node's STATIC membership does not affect its RULE memberships.

92 +:::note

93 +

94 +Group membership can be either STATIC or RULE—these work independently. A node can belong to groups through STATIC assignments (added manually) or through RULE assignments (matched automatically). RULEs cannot override STATIC memberships, and removing a node's STATIC membership does not affect its RULE memberships.

95 +

96 +:::

docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md

+43 -86

@@ -1,118 +1,75 @@

1 # Spaces and Rooms

3 -This guide explains how to effectively organize your infrastructure monitoring using Netdata Cloud.

3 +This guide explains how you can effectively organize your infrastructure monitoring using Netdata Cloud.

5 -Netdata Cloud uses two primary organizational concepts:

5 +## Overview

7 -- [Spaces](#spaces): High-level containers for your entire infrastructure.

8 -- [Rooms](#rooms): Flexible groupings within Spaces for specific monitoring needs.

7 +You can organize your monitoring with two primary concepts that work together.

10 -## Spaces

9 +**Spaces** serve as your primary collaboration environment where you organize team members and manage access levels, connect nodes for monitoring, and create a unified monitoring environment.

12 -**What is a Space?**

11 +**Rooms** function as organizational units within Spaces that provide infrastructure-wide dashboards, real-time metrics visualization, focused monitoring views, and flexible node grouping.

14 -Space serves as your primary collaboration environment in Netdata Cloud. It allows you to:

13 +**Key Relationship:** Each node can only belong to **one** Space, but you can assign a node to **multiple** Rooms within that Space.

16 -- Organize team members and manage access levels.

17 -- Connect nodes for monitoring.

18 -- Create a unified monitoring environment.

15 +## Getting Started

20 -**Key Space Characteristics**

17 +### Create Your Space

22 -- Each node can only belong to **one** Space.

23 -- You can create multiple Spaces, but we recommend using a single Space for most use cases.

24 -- All team members in a Space can access its monitoring data based on their assigned roles.

19 +1. Use the left-most sidebar to switch between Spaces

20 +2. Click the plus (**+**) icon to create a new Space

26 -### Space Management

22 +:::tip

28 -**Navigation**

24 +You can create multiple Spaces, but we recommend using a single Space for most use cases. All team members in a Space can access its monitoring data based on their assigned roles.

30 -1. Use the left-most sidebar to switch between Spaces.

31 -2. Click the plus (**+**) icon to create a new Space.

26 +:::

33 -**Settings and Configuration**

28 +### Set Up Team Access

35 -1. Select your Space.

36 -2. Click the gear icon in the lower left corner.

37 -3. Access settings for:

38 - - Room management.

39 - - Node configuration.

40 - - Integration setup.

41 - - General Space settings.

42 -

43 -## Rooms

44 -

45 -**What is a Room?**

46 -

47 -Rooms are organizational units within a Space that provide:

48 -

49 -- Infrastructure-wide dashboards.

50 -- Real-time metrics visualization.

51 -- Focused monitoring views.

52 -- Flexible node grouping.

53 -

54 -**Key Room Characteristics**

55 -

56 -- A node can belong to **multiple** Rooms.

57 -- All nodes automatically appear in the "All nodes" Room.

58 -- Each Room has independent dashboards and monitoring tools.

59 -

60 -### Room Organization Strategies

30 +1. Click "Invite Users" in the Space's sidebar

31 +2. Set appropriate access levels:

32 + - Rooms

33 + - User roles

62 -1. **Service-Based Organization**

35 +:::tip

64 - Group nodes by:

65 - - Specific services (Nginx, MySQL, Pulsar).

66 - - Purpose (webserver, database, application).

67 - - Physical location.

68 - - Infrastructure type (bare metal, containers).

69 - - Cloud provider.

37 +**Best Practices for Team Access:** Invite all relevant team members (SRE, DevOps, ITOps) and configure role-based access control. Maintain clear permission hierarchies and conduct regular access reviews and updates.

71 -2. **End-to-End Application Monitoring**

39 +:::

73 - Create Rooms for:

74 - - Complete SaaS product stacks.

75 - - Internal service dependencies.

76 - - Full application ecosystems including Kubernetes clusters, Docker containers, Proxies, Databases, Web servers, and Message brokers.

41 +### Create Your First Room

78 -3. **Incident Response**

43 +1. Access Rooms through the Space's sidebar

44 +2. Click the green plus (**+**) icon next to "Rooms" to create new Rooms

80 - Create dedicated Rooms for:

81 - - Active incident investigation.

82 - - Problem diagnosis.

83 - - Performance troubleshooting.

84 - - Root cause analysis.

46 + <img src="https://github.com/user-attachments/assets/16958ba8-53ac-4e78-a51f-7ea328e97f31" height="400px" alt="Individual Space sidebar"/>

86 -### Room Management

48 +:::info

88 -**Navigation**

50 +All nodes automatically appear in the "All nodes" Room. Each Room has independent dashboards and monitoring tools.

90 -1. Access Rooms through the Space's sidebar.

91 -2. Click the green plus (**+**) icon next to "Rooms" to create new Rooms.

52 +:::

93 - <img src="https://github.com/user-attachments/assets/16958ba8-53ac-4e78-a51f-7ea328e97f31" height="400px" alt="Individual Space sidebar"/>

54 +## Organize Your Infrastructure

95 -**Settings and Configuration**

56 +### Room Organization Strategies

97 -1. Click the gear icon next to the Room name.

98 -2. Manage:

99 - - Room access.

100 - - Node grouping.

101 - - Dashboard settings.

102 - - Monitoring configurations.

58 +| Strategy | Use Case | Examples |

59 +|---------------------------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

60 +| **Service-Based Organization** | Group nodes by **specific services**, **purpose**, **location**, or **infrastructure type** | **Nginx**, **MySQL**, **Pulsar**, **webserver**, **database**, **application**, **physical location**, **bare metal**, **containers**, **cloud provider** |

61 +| **End-to-End Application Monitoring** | Create Rooms for **complete application stacks** and **service dependencies** | **Complete SaaS product stacks**, **internal service dependencies**, **full application ecosystems** including **Kubernetes clusters**, **Docker containers**, **Proxies**, **Databases**, **Web servers**, **Message brokers** |

62 +| **Incident Response** | Create dedicated Rooms for **troubleshooting** and **problem resolution** | **Active incident investigation**, **problem diagnosis**, **performance troubleshooting**, **root cause analysis** |

104 -## Team Collaboration

64 +## Manage Your Setup

106 -**Inviting Team Members**

66 +### Space Configuration

108 -1. Click "Invite Users" in the Space's sidebar.

109 -2. Set appropriate access levels:

110 - - Rooms.

111 - - User roles.

68 +1. Select your Space

69 +2. Click the ⚙️ in the lower left corner

70 +3. Access settings for room management, node configuration, integration setup, and general Space settings

113 -**Best Practices for Team Access**

72 +### Room Configuration

115 -- Invite all relevant team members (SRE, DevOps, ITOps).

116 -- Configure role-based access control.

117 -- Maintain clear permission hierarchies.

118 -- Regular access review and updates.

74 +1. Click the ⚙️ next to the Room name

75 +2. Manage room access, node grouping, dashboard settings, and monitoring configurations

src/claim/README.md

+129 -83

@@ -1,35 +1,35 @@

1 # Connect Agent to Cloud

3 -This section guides you through installing and securely connecting a new Agent to Netdata Cloud via the encrypted Agent-Cloud Link ([ACLK](/src/aclk/README.md)). Connecting your Agent to your Space in Netdata Cloud unlocks additional features like centralized monitoring and easier collaboration.

3 +This section guides you through installing and securely connecting a new Agent to Netdata Cloud via the encrypted Agent-Cloud Link ([ACLK](/src/aclk/README.md)). Connecting your Agent to your Space unlocks centralized monitoring, easier collaboration, and more.

5 -## Connect

5 +## Quick Start - New Installation

7 -### Install and Connect a New Agent

7 +**For new installations**, Netdata Cloud generates a command that you can execute on your Node to install and connect the Agent to your Space.

9 -There are three places in the UI where you can add/connect your Node:

9 +You can find this command in three places in the UI:

11 - **Space/Room settings**: Click the cogwheel (the bottom-left corner or next to the Room name at the top) and select "Nodes." Click the "+" button to add a new node.

12 - [**Nodes tab**](/docs/dashboards-and-charts/nodes-tab.md): Click on the "Add nodes" button.

13 - **Integrations page**: From the "Deploy" groups of integrations, select the OS or container environment your node runs on, and follow the instructions.

15 -Netdata Cloud will generate a command that you can execute on your Node to install and connect the Agent to your Space.

15 +## Connect Existing Agent

17 -### Connect an existing Agent

17 +**For Agents already installed**, you can connect them to your Space using one of three methods:

19 -There are three methods to connect an already installed Agent to your Space.

19 +### Method 1: Via UI (Recommended)

21 -#### Manually, via the UI

21 +**Best for:** Most users, easiest setup

23 -The UI method is the easiest and recommended way to connect your Agent. Here's how:

23 +1. Open your Agent's local dashboard (normally under `IP:19999`)

24 +2. Sign in to your Netdata Cloud account

25 +3. Click the "Connect" button

26 +4. Follow the on-screen instructions to connect your Agent

25 -1. Open your Agent's local dashboard (normally under `IP:19999`).

26 -2. Sign in to your Netdata Cloud account.

27 -3. Click the "Connect" button.

28 -4. Follow the on-screen instructions to connect your Agent.

28 +### Method 2: Via Configuration File

30 -#### Automatically, via a provisioning system or the command line

30 +**Best for:** Automated deployments, multiple Agents

32 -Netdata Agents can be connected to Netdata Cloud by creating `/INSTALL_PREFIX/etc/netdata/claim.conf`:

32 +Create `/INSTALL_PREFIX/etc/netdata/claim.conf`:

34 ```bash

35 [global]

@@ -40,65 +40,94 @@ Netdata Agents can be connected to Netdata Cloud by creating `/INSTALL_PREFIX/et

40 insecure = no

41 ```

43 +**Configuration Options:**

44 +

45 | option | description | required |

46 |:--------:|:---------------------------------------------------------------------------------------|:--------:|

47 | url | The Netdata Cloud base URL (defaults to `https://app.netdata.cloud`) | no |

48 | token | The claiming token for your Netdata Cloud Space | yes |

49 | rooms | A comma-separated list of Rooms that the Agent will be added to | no |

48 -| proxy | Check below for possible values | no |

50 +| proxy | See [proxy configuration](#proxy-configuration) below | no |

51 | insecure | A boolean (either `yes`, or `no`) and when set to `yes` it disables host verification. | no |

51 -If the Agent is already running, you can either run `netdatacli reload-claiming-state` or [restart the Agent](/docs/netdata-agent/start-stop-restart.md). Otherwise, the Agent will be connected when it starts.

53 +**Applying the Configuration:**

53 -If the connection process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v3/info`.

55 +If the Agent is already running, you can either run `netdatacli reload-claiming-state` or [restart the Agent](/docs/netdata-agent/start-stop-restart.md). Otherwise, the Agent connects when it starts.

55 -##### Proxy configuration for claiming via claim.conf

57 +### Method 3: Via Environment Variables

57 -The `proxy` option at the `[global]` section in `claim.conf` can be set to:

59 +**Best for:** Container deployments, CI/CD pipelines

59 -- empty, to disable proxy configuration.

60 -- `none` to disable proxy configuration.

61 -- `env` to use the environment variable `http_proxy` (this is the default).

62 -- `http://[user:pass@]host:port`, to connect via a web proxy.

63 -- `socks5[h]://[user:pass@]host:port`, to connect via a SOCKS5 proxy.

61 +You can configure Netdata using the following environment variables:

65 -The `http_proxy` environment variable is used only when the `proxy` option is set to `env` (which is the default). The `http_proxy` environment can be:

63 +| Option | Description | Required |

64 +|----------------------------|---------------------------------------------------------------------------------------------------|----------|

65 +| `NETDATA_CLAIM_URL` | The Netdata Cloud base URL (defaults to `https://app.netdata.cloud`) | no |

66 +| `NETDATA_CLAIM_TOKEN` | The claiming token for your Netdata Cloud Space | yes |

67 +| `NETDATA_CLAIM_ROOMS` | A comma-separated list of Rooms that the Agent will be added to | no |

68 +| `NETDATA_CLAIM_PROXY` | The URL of a proxy server to use for the connection | no |

69 +| `NETDATA_EXTRA_CLAIM_OPTS` | May contain a space-separated list of options. The option `-insecure` is the only currently used. | no |

67 -- `http://[user:pass@]host:port`, to connect via an HTTP proxy.

68 -- `socks5[h]://[user:pass@]host:port`, to connect via a SOCKS5 or SOCKS5h proxy.

71 +### Connection Troubleshooting

70 -**IMPORTANT**: Netdata does not currently support secure connections to proxies. Data exchanged between Netdata Agents and Netdata Cloud are still end-to-end encrypted, since the Netdata Agent requests a TCP tunnel (HTTP `CONNECT`) from the proxy, and the Netdata Agent directly handles all encryption required for Netdata Cloud communication, however the initial communication from the Netdata Agent to the proxy is not encrypted.

73 +If the connection process fails, you can find the reason in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v3/info`.

72 -The current implementation uses HTTP proxies in a way that maintains end-to-end encryption between the Netdata agent and Netdata Cloud. Here's how it works:

75 +## Advanced Configuration

74 -1. **Proxy Connection**: The agent connects to the HTTP proxy using a plain HTTP connection.

75 -2. **TCP Tunneling Request**: The agent sends an HTTP CONNECT request to the proxy, asking it to establish a TCP tunnel to the Netdata Cloud server.

76 -3. **Proxy Tunneling**: Once the proxy accepts the CONNECT request (responds with HTTP 200), it creates a TCP tunnel between the agent and the Netdata Cloud server. At this point, the proxy simply forwards raw TCP data in both directions without interpreting it.

77 -4. **Encrypted Communication**: The agent then establishes a TLS/SSL connection through this tunnel directly with the Netdata Cloud server. All subsequent data (including the WebSocket handshake and MQTT protocol data) is encrypted end-to-end.

77 +### Proxy Configuration

79 -The proxy never sees the decrypted content of the communication - it only sees encrypted TLS traffic flowing through the tunnel it established. This is a standard way of using HTTP proxies for secure connections and is often called "TCP tunneling" or "HTTP CONNECT tunneling."

79 +You can configure proxy settings for both the configuration file and environment variable methods.

81 -Keep in mind that there are 2 distinct connection libraries involved. Claiming uses libcurl which may be more flexible, but later at the establishment of the actual Netdata Cloud connection a different library implements MQTT over WebSockets over HTTPS (MQTToWSoHTTPS) and this library does not support encrypted connections to proxies. So, while claiming (libcurl) may work via an encrypted connection to a proxy, the actual Netdata Cloud connection (MQTToWSoHTTPS) will later fail if the proxy connection is encrypted.

81 +#### For Configuration File (claim.conf)

83 -The proxy configuration patterns described above, work for both libraries and provide end-to-end encryption for Netdata Cloud communication.

83 +You can set the `proxy` option at the `[global]` section in `claim.conf` to:

85 -#### Automatically, via environment variables

85 +- empty, to disable proxy configuration

86 +- `none` to disable proxy configuration

87 +- `env` to use the environment variable `http_proxy` (this is the default)

88 +- `http://[user:pass@]host:port`, to connect via a web proxy

89 +- `socks5[h]://[user:pass@]host:port`, to connect via a SOCKS5 proxy

87 -Netdata will use the following environment variables:

91 +#### Environment Variable Proxy Settings

89 -| Option | Description | Required |

90 -|----------------------------|---------------------------------------------------------------------------------------------------|----------|

91 -| `NETDATA_CLAIM_URL` | The Netdata Cloud base URL (defaults to `https://app.netdata.cloud`) | no |

92 -| `NETDATA_CLAIM_TOKEN` | The claiming token for your Netdata Cloud Space | yes |

93 -| `NETDATA_CLAIM_ROOMS` | A comma-separated list of Rooms that the Agent will be added to | no |

94 -| `NETDATA_CLAIM_PROXY` | The URL of a proxy server to use for the connection | no |

95 -| `NETDATA_EXTRA_CLAIM_OPTS` | May contain a space-separated list of options. The option `-insecure` is the only currently used. | no |

93 +Netdata uses the `http_proxy` environment variable only when you set the `proxy` option to `env` (which is the default). You can set the `http_proxy` environment variable to:

94 +

95 +- `http://[user:pass@]host:port`, to connect via an HTTP proxy

96 +- `socks5[h]://[user:pass@]host:port`, to connect via a SOCKS5 or SOCKS5h proxy

97 +

98 +#### Proxy Security Considerations

99 +

100 +:::note

101 +

102 +Netdata does not support secure connections to proxies. **Data between Netdata Agents and Netdata Cloud remains end-to-end encrypted** since the Agent requests a TCP tunnel (HTTP `CONNECT`) from the proxy and handles all encryption directly, however initial Agent-to-proxy communication is not encrypted.

103 +

104 +:::

105 +

106 +**How End-to-End Encryption Works with Proxies:**

107 +

108 +1. **Proxy Connection**: The Agent connects to the HTTP proxy using a plain HTTP connection.

109 +2. **TCP Tunneling Request**: The Agent sends an HTTP CONNECT request to the proxy, asking it to establish a TCP tunnel to the Netdata Cloud server.

110 +3. **Proxy Tunneling**: Once the proxy accepts the CONNECT request (responds with HTTP 200), it creates a TCP tunnel between the Agent and the Netdata Cloud server. At this point, the proxy simply forwards raw TCP data in both directions without interpreting it.

111 +4. **Encrypted Communication**: The Agent then establishes a TLS/SSL connection through this tunnel directly with the Netdata Cloud server. All subsequent data (including the WebSocket handshake and MQTT protocol data) is encrypted end-to-end.

112

97 -If the connection process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v3/info`.

113 +:::note

114

99 -## Reconnect

115 +The proxy only sees encrypted TLS traffic flowing through the tunnel it established, never the decrypted content. This standard method is called "TCP tunneling" or "HTTP CONNECT tunneling."

116

101 -### Linux based installations

117 +:::

118 +

119 +:::info

120 +

121 +Netdata uses **two connection libraries**: **libcurl for claiming and MQTToWSoHTTPS for the actual Cloud connection**. While libcurl supports encrypted proxy connections, MQTToWSoHTTPS does not - so encrypted proxy connections will fail during the Cloud connection phase. The proxy configuration patterns above work for both libraries and provide end-to-end encryption for Netdata Cloud communication.

122 +

123 +:::

124 +

125 +## Manage Connections

126 +

127 +### Reconnect Agent

128 +

129 +<details>

130 +<summary>Linux-based Installations</summary>

131

132 To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory.

133

@@ -107,79 +136,90 @@ cd /var/lib/netdata # Replace with your Netdata library directory, if not /var

136 sudo rm -rf cloud.d/

137 ```

138

110 -> **IMPORTANT**

111 ->

112 -> Keep in mind that the Agent will be **re-claimed automatically** if the environment variables or `claim.conf` exist when the Agent is restarted.

139 +:::note

140 +

141 +The Agent will be **re-claimed automatically** if the environment variables or `claim.conf` exist when you restart the Agent.

142 +

143 +:::

144

145 This node will no longer have access to the credentials it used when connecting to Netdata Cloud via the ACLK.

146

116 -### Docker based installations

147 +</details>

148 +

149 +<details>

150 +<summary>Docker-based Installations</summary>

151

152 To remove a node from your Space and connect it to another, follow these steps:

153

120 -1. Enter the running container you wish to remove from your Space

154 +1. **Enter the running container** you wish to remove from your Space

155

156 ```bash

157 docker exec -it CONTAINER_NAME sh

158 ```

159

126 - Replacing `CONTAINER_NAME` with either the container's name or ID.

160 + Replace `CONTAINER_NAME` with either the container's name or ID.

161

128 -2. Delete `/var/lib/netdata/cloud.d` and `/var/lib/netdata/registry/netdata.public.unique.id`

162 +2. **Delete the connection files**

163

164 ```bash

165 rm -rf /var/lib/netdata/cloud.d/

166 rm /var/lib/netdata/registry/netdata.public.unique.id

167 ```

168

135 -3. Stop and remove the container

169 +3. **Stop and remove the container**

170

171 **Docker CLI:**

138 -

172 ```bash

173 docker stop CONTAINER_NAME

174 docker rm CONTAINER_NAME

175 ```

143 -

144 - Replacing `CONTAINER_NAME` with either the container's name or ID.

176 + Replace `CONTAINER_NAME` with either the container's name or ID.

177

178 **Docker Compose:**

179 Inside the directory that has the `docker-compose.yml` file, run:

148 -

180 ```bash

181 docker compose down

182 ```

183

184 **Docker Swarm:**

185 Run the following, and replace `STACK` with your Stack's name:

155 -

186 ```bash

187 docker stack rm STACK

188 ```

189

160 -4. Finally, go to your new Space, copy the installation command with the new claim token and run it.

161 - If you’re using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token.

162 - The node should now appear online in that Space.

190 +4. **Connect to new Space**

191 +

192 + Go to your new Space, copy the installation command with the new claim token and run it. If you're using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token. The node should now appear online in that Space.

193 +

194 +</details>

195 +

196 +### Regenerate Claiming Token

197 +

198 +You may need to revoke your previous Claiming Token and generate a new one for security reasons.

199

164 -## Regenerate Claiming Token

200 +:::note

201

166 -There may be situations where you need to revoke your previous Claiming Token and generate a new one for security reasons. Here's how to do it:

202 +Only **Administrators** of a Space in Netdata Cloud can regenerate Claim Tokens.

203

168 -**Requirements**:

204 +:::

205

170 -- Only Administrators of a Space in Netdata Cloud can regenerate Claim Tokens.

206 +**Steps:**

207

172 -**Steps**:

208 +1. Navigate to [any screen](#quick-start---new-installation) containing the Connection command

209 +2. Click the "Regenerate token" button. This action invalidates your previous token and generates a new one

210

174 -1. Navigate to [any screen](#install-and-connect-a-new-agent) containing the Connection command.

175 -2. Click the "Regenerate token" button. This action will invalidate your previous token and generate a new one.

211 +## Troubleshooting

212

177 -## Troubleshoot

213 +### Check Connection Status

214

215 If you're having trouble connecting a node, this may be because the [ACLK](/src/aclk/README.md) cannot connect to Cloud.

216

217 +**Method 1: Web Interface**

218 +

219 With the Netdata Agent running, visit `http://NODE:19999/api/v3/info` in your browser, replacing `NODE` with the IP address or hostname of your Agent. The returned JSON contains a section called `cloud` with helpful information to diagnose any issues you might be having with the ACLK or connection process.

220

221 +**Method 2: Command Line**

222 +

223 You can also run `sudo netdatacli aclk-state` to get some diagnostic information about ACLK:

224

225 ```bash

@@ -194,29 +234,35 @@ Used Cloud Protocol: New

234

235 Use these keys and the information below to troubleshoot the ACLK.

236

197 -### kickstart: unsupported Netdata installation

237 +### Common Issues

238 +

239 +#### kickstart: unsupported Netdata installation

240

199 -If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package.

241 +**Problem:** If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package.

242

201 -Check our [installation section](/packaging/installer/README.md) to find the proper way of installing Netdata on your system.

243 +**Solution:** Check our [installation section](/packaging/installer/README.md) to find the proper way of installing Netdata on your system.

244

203 -### kickstart: Failed to write new machine GUID

245 +#### kickstart: Failed to write new machine GUID

246

205 -You might encounter this error if you run the Netdata kickstart script without sufficient permissions:

247 +**Problem:** You might encounter this error if you run the Netdata kickstart script without sufficient permissions:

248

249 ```bash

250 Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id.

251 ```

252

211 -To resolve this issue, you have two options:

253 +**Solution:** To resolve this issue, you have two options:

254

255 1. Run the script with root privileges.

256 2. Run the script with the user that runs the Netdata Agent.

257

216 -### Connecting to Cloud on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)

258 +#### Connecting to Cloud on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)

259 +

260 +**Problem:** If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS 6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which helps securely encrypt SSL connections.

261 +

262 +**Solution:** We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart.md#install-type), which uses an up-to-date version of OpenSSL with hostname validation enabled.

263

218 -If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS 6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which helps securely encrypt SSL connections.

264 +:::warning

265

220 -We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart.md#install-type), which uses an up-to-date version of OpenSSL with hostname validation enabled.

266 +If you choose to continue using the **outdated version of OpenSSL**, your node will still connect to Netdata Cloud, but **with hostname verification disabled**. Without verification, your Netdata Cloud connection could be vulnerable to man-in-the-middle attacks.

267

222 -If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to man-in-the-middle attacks.

268 +:::