Netdata Cloud On-Prem Installation

Before You Begin

Ensure you have the following ready before starting the installation:

Required:

• AWS CLI installed and configured
• Helm (version 3.12+ with OCI Configuration)
• Kubectl with access to your Kubernetes cluster
• AWS credentials with ECR access permissions

System Requirements:

Component	Details
Kubernetes	Version 1.23 or newer, Metrics server installed (for autoscaling), Default storage class configured (SSD-based preferred)
TLS certificate	Single certificate for all endpoints, or separate certificates for frontend, API, and MQTT. Must be trusted by all connecting entities.
Netdata Cloud Services	4 CPU cores, 15GiB memory (Cloud services are ephemeral)
Third-Party Services	8 CPU cores, 14GiB memory, 160GiB SSD storage for PVCs

note

These requirements were tested with 1,000 directly connected nodes. Resource needs may vary based on your workload. The initial sync of directly connected Agents is the most compute-intensive operation.

For example, a Postgres instance with 2 vCPU, 8GiB memory, and 1k IOPS can handle 1,000 nodes in a steady environment when adding nodes in batches of 10–30.

Required Components

Third-Party Services

All components below are included in the netdata-cloud-dependency package:

Component	Version	Purpose	Notes
PostgreSQL	14.15	Main metadata database
EMQX	5.8.6	MQTT Broker for Agent communication
Apache Pulsar	2.10+	Inter-container message broker
Traefik	3.x	Internal API Gateway	Should be running with v2 rule format
Elasticsearch	8.8.x	Events feed storage
Redis	8.x	Caching layer
Ingress Controller	-	HTTPS support
imagePullSecret	-	Secured ECR repository access

warning

For Production Use: The provided dependency versions require additional configuration for production environments. Configure these applications according to your production requirements and policies.

Step by Step Guide to Install

warning

Critical Installation Order: Dependencies must be installed first, followed by the main Netdata Cloud On-Prem application. Do not skip the dependency installation step.

Step 1: Configure AWS CLI

Set up your AWS credentials to access the ECR repository containing the Helm charts.

Option 1: Environment Variables

export AWS_ACCESS_KEY_ID=<your_secret_id>
export AWS_SECRET_ACCESS_KEY=<your_secret_key>

Option 2: Interactive Setup

aws configure

Step 2: Configure Helm for ECR Access

Generate a token for ECR access to allow Helm to pull charts from the secured repository:

aws ecr get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin 362923047827.dkr.ecr.us-east-1.amazonaws.com

Step 3: Download Helm Charts

Pull the required charts to your local machine. The charts will be extracted to your current working directory:

helm pull oci://362923047827.dkr.ecr.us-east-1.amazonaws.com/netdata-cloud-dependency --untar  # Optional
helm pull oci://362923047827.dkr.ecr.us-east-1.amazonaws.com/netdata-cloud-onprem --untar

tip

Configuration files location: After extraction, you'll find values.yaml files in the respective chart directories that need to be configured for your environment.

Step 4: Install Dependencies (Required First)

The netdata-cloud-dependency chart must be installed before the main application in netdata-cloud-onprem. This chart installs all required third-party applications.

1. Configure the installation by editing values.yaml in your netdata-cloud-dependency chart directory
   
2. Install the dependencies:
   

cd [your helm chart location]
helm upgrade --wait --install netdata-cloud-dependency -n netdata-cloud --create-namespace -f values.yaml .

tip

For production environments, we recommend using your own configured versions of these components rather than the provided defaults. netdata-cloud-dependency helm chart is designed

Step 5: Install Netdata Cloud On-Prem

Install the main application after dependencies are successfully running:

1. Configure the installation by editing values.yaml in your netdata-cloud-onprem chart directory
   
2. Install the application:
   

cd [your helm chart location]
helm upgrade --wait --install netdata-cloud-onprem -n netdata-cloud --create-namespace -f values.yaml .

warning

Critical: During first installation, a netdata-cloud-common secret is created containing critical encryption data. This secret persists through reinstalls and should never be deleted as this will result in data loss.

Verify It Works

After completing the installation steps, verify that everything is running correctly:

Check Installation Status

Verify Helm installations:

helm list -n netdata-cloud

Check pod status:

kubectl get pods -n netdata-cloud

Check services:

kubectl get svc -n netdata-cloud

All pods should be in Running status and services should have appropriate endpoints configured.

Architecture Components

View detailed microservices description

Microservice	Description
cloud-accounts-service	Handles user registration & authentication
cloud-agent-data-ctrl-service	Forwards requests from the OCP to the relevant Agents. The requests include fetching Chart metadata, Chart data and Function data from the Agents.
cloud-agent-mqtt-input-service	Forwards MQTT messages emitted by the Agent to the internal Pulsar broker. They are related to the Agent entities and include Agent connection state updates.
cloud-agent-mqtt-output-service	Forwards Pulsar messages emitted on the OCP to the MQTT broker. They are related to the Agent entities. From there, the messages reach the relevant Agent.
cloud-alarm-config-mqtt-input-service	Forwards MQTT messages emitted by the Agent to the internal Pulsar broker. They related to the alarm-config entities like data for the alarm configuration as seen by the Agent.
cloud-alarm-log-mqtt-input-service	Forwards MQTT messages emitted by the Agent to the internal Pulsar broker. They are related to the alarm-log entities containing data about the alarm transitions that occurred in an Agent.
cloud-alarm-mqtt-output-service	Forwards Pulsar messages emitted in the Cloud to the MQTT broker. They are related to the alarm entities and from there, the messages reach the relevant Agent.
cloud-alarm-processor-service	Persists latest Alert status received from the Agent in the OCP. Aggregates Alert statuses from relevant node instances. Exposes API endpoints to fetch Alert data for visualization on the Cloud. Determines if notifications need to be sent when Alert statuses change and emits relevant messages to Pulsar. Exposes API endpoints to store and return notification-silencing data
cloud-alarm-streaming-service	Responsible for starting the Alert stream between the Agent and the OCP. Ensures messages are processed in correct order, and starts a reconciliation process between the Cloud and the Agent if out-of-order processing occurs
cloud-charts-mqtt-input-service	Forwards MQTT messages emitted by the Agent related to the chart entities to the internal Pulsar broker. These include the chart metadata that is used to display relevant charts on the Cloud.
cloud-charts-mqtt-output-service	Forwards Pulsar messages emitted in the Cloud related to the charts entities to the MQTT broker. From there, the messages reach the relevant Agent.
cloud-charts-service	Exposes API endpoints to fetch the chart metadata. Forwards data requests via the cloud-agent-data-ctrl-service to the relevant Agents to fetch chart data points. Exposes API endpoints to call various other endpoints on the Agent, for instance, functions
cloud-custom-dashboard-service	Exposes API endpoints to fetch and store custom dashboard data
cloud-environment-service	Serves as the first contact point between the Agent and the OCP. Returns authentication and MQTT endpoints to connecting Agents
cloud-feed-service	Processes incoming feed events and stores them in Elasticsearch. Exposes API endpoints to fetch feed events from Elasticsearch
cloud-frontend	Contains the OCP website. Serves static content.
cloud-iam-user-service	Acts as a middleware for authentication on most of the API endpoints. Validates incoming token headers, injects the relevant ones, and forwards the requests
cloud-metrics-exporter	Exports various metrics from an OCP installation. Uses the Prometheus metric exposition format
cloud-netdata-assistant	Exposes API endpoints to fetch a human-friendly explanation of various Netdata configuration options, namely the Alerts.
cloud-node-mqtt-input-service	Forwards MQTT messages emitted by the Agent related to the node entities to the internal Pulsar broker. These include the node metadata as well as their connectivity state, either direct or via Parents
cloud-node-mqtt-output-service	Forwards Pulsar messages emitted in the OCP related to the charts entities to the MQTT broker. From there, the messages reach the relevant Agent
cloud-notifications-dispatcher-service	Exposes API endpoints to handle integrations. Handles incoming notification messages and uses the relevant channels(email, slack...) to notify relevant users
cloud-spaceroom-service	Exposes API endpoints to fetch and store relations between Agents, nodes, spaces, users, and rooms. Acts as a provider of authorization for other Cloud endpoints. Exposes API endpoints to authenticate Agents connecting to the Cloud