From 23d5279087e75c5ed51d01042fec374640bea1bd Mon Sep 17 00:00:00 2001 From: shiv Date: Sat, 22 Aug 2026 12:21:57 +0530 Subject: [PATCH 1/4] docs: add deployment path selector, first-value outcome verification steps, resolve auth/sizing contradictions, and clean FAQ --- doc-server/README.md | 52 ++++---- doc-server/docs/FAQ.md | 124 ++++++++---------- doc-server/docs/index.md | 69 ++++++---- .../installation/agent/installation/index.md | 15 ++- .../installation/proxy-agent/quick-start.md | 17 +++ doc-server/docs/installation/server/index.md | 41 +++--- 6 files changed, 178 insertions(+), 140 deletions(-) diff --git a/doc-server/README.md b/doc-server/README.md index 0a4980af..2cd1a3eb 100755 --- a/doc-server/README.md +++ b/doc-server/README.md @@ -1,41 +1,37 @@ -# Website +# NudgeBee Documentation -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This repository hosts the official documentation for [NudgeBee](https://nudgebee.com), built using [Docusaurus 3](https://docusaurus.io/). -### Installation +## Prerequisites -``` -$ npm install -``` +- **Node.js**: v18.0.0 or higher +- **npm**: v9.0.0 or higher -### Local Development +## Local Development -``` -$ npm start -``` +1. **Install dependencies**: + ```bash + npm install + ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +2. **Start the local dev server**: + ```bash + npm start + ``` + This command starts the local development server at `http://localhost:3000` (or `http://localhost:4000`). Edits in `docs/` reflect live via hot-reloading. -### Build - -``` -$ npm run build -``` +## Production Build -This command generates static content into the `build` directory and can be served using any static contents hosting service. +To verify and generate static assets: -### Deployment - -Using SSH: - -``` -$ USE_SSH=true npm run deploy +```bash +npm run build ``` -Not using SSH: +The compiled output will be generated inside the `build/` directory. -``` -$ GIT_USER= npm run deploy -``` +To preview the production build locally: -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +```bash +npm run serve +``` diff --git a/doc-server/docs/FAQ.md b/doc-server/docs/FAQ.md index cffe6b51..707dc572 100644 --- a/doc-server/docs/FAQ.md +++ b/doc-server/docs/FAQ.md @@ -7,15 +7,16 @@ sidebar_position: 100 ### What are the open-source tools that NudgeBee uses? #### Agent -- Prometheus (or VictoriaMetrics) - Metrics Collection and alerting -- OpenCost for calculating cost metrics for Pods/Workloads etc. -- Trivy for generating Docker image vulnerability related security recommendations -- Popeye for generating best practices related recommendations -- Kubewatch for K8s events collection +- **Prometheus** (or VictoriaMetrics) — Metrics collection and alerting +- **Logs Engine** (Loki / OpenObserve / Elasticsearch / Fluentbit) — Log querying and stream aggregation +- **Distributed Tracing** (OpenTelemetry Collector / ClickHouse / Tempo) — Distributed tracing +- **Trivy** — Container image vulnerability scanning +- **Popeye** — Kubernetes cluster sanitizing and best practice audits +- **Kubewatch** — Kubernetes event streaming and lifecycle capture ### What are the ML libraries that NudgeBee uses? What are the dependencies? -- TensorFlow for recommendations for replicas -- AWS Bedrock using LLAMA (optional) for AI-based recommendations on logs/errors +- **TensorFlow & Scikit-learn** — Predictive analytics for workload replica and resource rightsizing +- **Cortex & DAIR Router** — In-VPC Small Language Model serving (vLLM / Ollama) with optional routing to AWS Bedrock, OpenAI, Anthropic, or Google Gemini ### What are the hard dependencies for the NudgeBee Server? - **PostgreSQL**: Hard requirement. Stores cluster configurations, user metadata, alert rules, and workflow states. Queries and services fail without it. @@ -27,128 +28,109 @@ sidebar_position: 100 - **The Agent** is required inside each cluster to collect real-time workload metrics, stream pod logs, capture eBPF network telemetry, and perform automated AI root cause analysis. - For full AI troubleshooting and cost optimizations on a cluster, installing the Agent is required. -### What are the pre-conditions(software/hardware) for installing NudgeBee on my cluster? +### What are the pre-conditions (software/hardware) for installing NudgeBee on my cluster? #### For Agent: -- Helm chart for installation -- Prometheus, if already configured, else NudgeBee agent installs it -- Currently, NudgeBee uses Loki for log queries. For log-specific features, we will require Loki running on the cluster. We don't provide Loki as part of the Agent Installer. -- Permissions as specified in Helm charts +- Helm 3.10+ and Kubernetes 1.24+ +- Existing Prometheus instance (or install bundled Prometheus via Helm) +- For log-specific triage: Existing log aggregator (Loki, Elasticsearch, OpenObserve) or cluster log access +- Standard cluster RBAC permissions as specified in the Helm chart -### What is the typical system requirement for running NB on my cluster? What is the expected cost of operations for running the base NudgeBee +### What is the typical system requirement for running NudgeBee? #### For Agent: -Agent has multiple components. All of them combined take around 6GB memory and 3 core CPUs -This also includes Prometheus(Alertmanager/KubestateMetrics) -If we remove Prometheus components, then it takes around 3GB and 2 cores +- **Core Agent (Runner + Collector)**: Lightweight — requests **~200m CPU** and **256 MiB RAM**. +- **Optional In-Cluster Monitoring Stack (Prometheus / Alertmanager / KSM)**: **~1–2 CPU cores** and **2–4 GB RAM** depending on metric cardinality. +- **Node Agent (DaemonSet)**: **~50m CPU** and **64 MiB RAM** per worker node for eBPF and node telemetry. #### For Server: -All server components take around 12GB RAM and 4 core CPUs -This includes running postgres/rabbitmq etc. If the customer is managing these dependencies, then it will take around 8GB RAM and 2 core CPUs +- **Evaluation / Small Install (Bundled Postgres & RabbitMQ)**: **~4 CPU cores** and **8–12 GB RAM** across all backend pods. +- **Production Install (External Managed Databases)**: **~2–4 CPU cores** and **4–8 GB RAM** for NudgeBee application pods. ### How NudgeBee Optimizations Work with GitOps -Raise PRs from NudgeBee -- We have added support for raising PRs from specific optimization screens in NudgeBee. - -GitOps(Flux/Argo) Reconciliation -- Disable reconciliation for given resources. - -NudgeBee Autopilot Reconciliation -- NudgeBee provides annotations which can be used to ignore specific resources. - -GitOps Way Of Configuring NudgeBee Optimizations - -- We want to provide this as an option using CRDs, though it's part of the roadmap. +- **Raise PRs from NudgeBee**: Create automated pull requests with rightsized resource limits directly to your Git repository. +- **GitOps Reconciliation (Flux / Argo CD)**: Annotate manifests or configure automated PR merges to ensure GitOps state remains the single source of truth. +- **NudgeBee Autopilot Reconciliation**: Apply `nudgebee.io/ignore: "true"` annotations to exclude specific workloads from automated rightsizing. ### Can NudgeBee work on K3s/Kind/Minikube? -Yes, please refer to the Installation Guide for local testing. +Yes, please refer to the [Server Installation Guide](/docs/installation/server/) and [Agent Installation Guide](/docs/installation/agent/installation/) for local evaluation instructions. ### How are NudgeBee Docker images secured? -NudgeBee uses minimal Alpine-based images to reduce attack surface and image size. Images are scanned for known vulnerabilities as part of the release pipeline. To report a suspected vulnerability, see the [security policy](https://github.com/nudgebee/nudgebee-docs/blob/main/SECURITY.md). +NudgeBee uses minimal Alpine and distroless base images to minimize the attack surface. All images are signed and scanned for known vulnerabilities as part of the release pipeline. To report a suspected vulnerability, see the [security policy](https://github.com/nudgebee/nudgebee-docs/blob/main/SECURITY.md). ### Is NudgeBee penetration tested? -Yes. NudgeBee undergoes regular security testing, including automated and manual penetration testing, as part of its release process. +Yes. NudgeBee undergoes regular security testing, including automated SAST/DAST and third-party penetration testing, as part of its release compliance. ### Can I configure multiple clusters within a single NudgeBee server? -Yes, configure agents on each targeted cluster. +Yes. A single NudgeBee Server can monitor dozens of Kubernetes clusters across multiple clouds and on-premises environments by deploying the lightweight Agent into each target cluster. ### What are the different NudgeBee distributions / editions? -NudgeBee is available in three editions — see the [Editions page](./editions.md) for the full side-by-side comparison. +NudgeBee is available in three editions — see the [Editions & Capabilities page](/docs/editions) for the full comparison: -- **Community** — free, open-source (Apache 2.0), fully functional self-hosted. Pull public images from `ghcr.io/nudgebee`; no license key. -- **Enterprise** — self-hosted with a commercial license. Adds SAML 2.0 SSO, NudgeBee's managed models (`nb-llm` / `nb-slm`), and commercial support. -- **Cloud** (SaaS) — fully managed at [app.nudgebee.com](https://app.nudgebee.com). Fastest way to evaluate. - -Use Cloud for fastest evaluation; Community for a free, self-hosted deployment; Enterprise when you need SAML, managed models, or a commercial SLA while staying on-prem. +- **Community** — Free self-hosted edition. Server is licensed under **BSL 1.1**; Agents are **Apache 2.0**. Pull public images from `ghcr.io/nudgebee` with no license key required. +- **Enterprise** — Self-hosted with a commercial license. Adds SAML 2.0 SSO, NudgeBee-managed models (`nb-llm` / `nb-slm`), and commercial SLA support. +- **Cloud (SaaS)** — Fully managed at [app.nudgebee.com](https://app.nudgebee.com). Passwordless signup with fastest time to evaluate. ### What is the NudgeBee release cycle? -We target to have a weekly release cycle with hotfixes as per requirements. We follow SemVer for our versioning. +We follow a weekly release cadence for server and agent enhancements, with hotfixes published as needed. All versions follow Semantic Versioning (`vMAJOR.MINOR.PATCH`). ### Can you provide more details on Data Retention Policies? -Currently, NudgeBee stores most of the data in Agents which get deployed on the cluster, so data remains within the cluster. Data retention for Agent components (traces/metrics/logs) is configurable and can be managed by the customer. +Currently, NudgeBee stores most telemetry data inside your cluster or dedicated VPC storage: #### Agents store the following data: - -Traces - Using ClickHouse, you can adjust how long you want to retain ClickHouse data. The default is 7 days. -Metrics - Using Prometheus, you can adjust Prometheus data retention. -Logs - We integrate with existing log services like Loki/ELK, so again, it depends on their data retention. - +- **Traces**: Stored in ClickHouse / Tempo. Configurable retention with a default of 7 days. +- **Metrics**: Stored in Prometheus / VictoriaMetrics. Configurable retention based on your storage class. +- **Logs**: Integrated with existing log services (Loki / Elasticsearch / OpenObserve). #### Servers store the following data: - -Aggregated Metrics - Aggregated on a daily basis and retained for long-term trend analysis. -Events - Troubleshooting pages. Default retention is 60 days, and is configurable. -Deleted Pods/Workloads etc. - Records of deleted workloads/pods are retained to support historical analysis. - -### Does NudgeBee support Anomaly Detection? -No, this is part of the roadmap. +- **Aggregated Metrics**: Daily rollups for long-term capacity planning and FinOps cost trend analysis. +- **Events & Incidents**: Troubleshooting events with default configurable retention of 60 days. +- **Workload Metadata**: Historical records of deleted pods and workloads to support post-incident analysis. ### Does NudgeBee support Predictive Analysis? -Yes, NudgeBee uses predictive analytics for replica rightsizing and continuous rightsizing. +Yes, NudgeBee uses predictive analytics for workload replica rightsizing, resource trend forecasting, and continuous FinOps optimization. ### How does NudgeBee discover cloud resources across AWS, Azure, and GCP? -NudgeBee automatically discovers cloud resources when you onboard an account. It searches for common services like VMs, load balancers, databases, and storage. The platform syncs with daily billing data and performs periodic updates for continuous resource tracking. For AWS specifically, NudgeBee uses EventBridge to receive real-time notifications for resource updates, creation, and deletion events.​ +NudgeBee automatically discovers cloud resources when you onboard an account. It scans common services like VMs, load balancers, managed databases, and object storage. The platform syncs with daily billing data and listens to real-time events (e.g. AWS EventBridge) to track resource creation, modification, and deletion. ### Does NudgeBee support Kubernetes resource discovery? -Yes, NudgeBee agents automatically discover all Kubernetes resources across all namespaces in your cluster. The agent runs within your Kubernetes environment and uses the Kubernetes API to continuously track workloads.​ +Yes, NudgeBee agents automatically discover all Kubernetes resources across all namespaces in your cluster via the Kubernetes API. ### What observability tools does NudgeBee integrate with? -NudgeBee provides prebuilt, out-of-the-box connectors for major observability platforms. These include Datadog, Prometheus (and all variations), Chronosphere, Signoz, OpenObserve, ELK, AWS CloudWatch, Azure Monitor, and Google Cloud Monitoring. The integrations work seamlessly with your existing stack without requiring replacements.​ +NudgeBee provides prebuilt connectors for Datadog, Prometheus, Chronosphere, SigNoz, OpenObserve, Elasticsearch, AWS CloudWatch, Azure Monitor, and Google Cloud Monitoring. ### Can I deploy NudgeBee with its own observability stack? -Yes, for new deployments or greenfield environments, NudgeBee ships with a complete observability stack. This includes VictoriaMetrics for metrics collection, ClickHouse with OpenTelemetry for distributed traces, and Loki for log aggregation.​ +Yes, for greenfield environments, NudgeBee can bundle Prometheus for metrics collection, ClickHouse with OpenTelemetry for distributed traces, and Loki for log aggregation. ### How does NudgeBee integrate with existing knowledge base systems? -NudgeBee natively integrates with Atlassian Confluence and ServiceNow knowledge bases. You can also define custom knowledge base sources including Google Docs, Notion, and SharePoint. These sources are used by NudgeBee's AI agents during troubleshooting workflows.​ +NudgeBee natively integrates with Atlassian Confluence, ServiceNow, Notion, Google Docs, and SharePoint. These sources are indexed into the Semantic Knowledge Graph to ground NuBi's root cause investigations in your team's existing runbooks. ### Does NudgeBee learn from resolved incidents automatically? -Yes, NudgeBee automatically learns from issues it has resolved. User feedback can be configured to flow directly into the knowledge base, continuously improving the AI agent's troubleshooting capabilities over time.​ +Yes, NudgeBee automatically learns from resolved incidents. Resolution notes and verified postmortems flow directly into the knowledge base to continually improve future triage accuracy. ### How does NudgeBee handle event deduplication and aggregation? -NudgeBee generates unique fingerprints for each event it receives. These fingerprints form the foundation for intelligent aggregation and deduplication within the platform. This prevents alert fatigue by consolidating related events into single actionable incidents.​ +NudgeBee generates unique fingerprints for each incoming alert. These fingerprints form the foundation for intelligent aggregation and deduplication, consolidating cascading alert storms into single, actionable incidents. ### What is NudgeBee's Knowledge Graph and how does it correlate events? -NudgeBee uses a Knowledge Graph to establish linkages between entities like configurations, logs, metrics, traces, cloud bills, SLO/SLAs, tickets, code, and secrets. When an event occurs, the system searches for related entities and identifies recent events that may have caused the new issue. It then builds a comprehensive event timeline based on these correlations.​ +NudgeBee uses a live Semantic Knowledge Graph to establish topological links between workloads, pods, nodes, cloud services, metrics, traces, git commits, and tickets. When an incident occurs, the system correlates dependent entities across the timeline to identify the precise triggering change. ### What event sources can NudgeBee consume for incident management? -NudgeBee consumes events from Prometheus Alertmanager, Kubernetes, Datadog, PagerDuty, and ServiceNow. Users can also send custom events to NudgeBee's webhook endpoints for proprietary or internal monitoring systems.​ - -### How does NudgeBee's SRE Agent prioritize and analyze incidents? -For each incoming event, NudgeBee's SRE Agent performs deduplication and urgency assessment based on historical incident data. Events are then automatically analyzed for root cause using an AI-based workflow system. Users can extend the analysis by providing custom instructions tailored to their environment.​ +NudgeBee consumes events from Prometheus Alertmanager, Kubernetes events, Datadog, PagerDuty, ServiceNow, and custom webhooks. ### Where can I access NudgeBee's SRE Agent (NuBi)? -NuBi, NudgeBee's SRE agent, is accessible through communication channels like Slack and Microsoft Teams, or directly through the NudgeBee UI. This enables ChatOps workflows where team members can ask questions about infrastructure, logs, and metrics.​ +NuBi is accessible directly through the web dashboard, Slack, and Microsoft Teams for seamless ChatOps. ### What are the primary capabilities of NuBi for SRE teams? -NuBi handles ChatOps by responding to user questions about infrastructure, logs, and metrics. It performs live debugging of active incidents and conducts root cause analysis using AI-driven workflows. Teams can create custom agents based on specific requirements, extend existing agent instructions, and provide global context for tenant or account-level behaviors.​ +NuBi investigates live alerts, runs ad-hoc infrastructure queries, correlates logs and traces, hypothesizes root causes, and suggests actionable remediation commands. ### What types of automated resolutions does NudgeBee support? -NudgeBee generates automated pull requests for code and CI/CD issues. For lower environments, it can automate configuration changes with approval workflows. The platform also handles quick fixes like pod restarts and memory/CPU adjustments automatically.​ +NudgeBee can generate automated pull requests for GitOps and CI/CD configurations, trigger approved runbooks (e.g. pod restarts or cache flushes), and execute policy-gated right-sizing actions. ### Can I customize NudgeBee's automation workflows? -Yes, users can create custom resolution workflows using NudgeBee's AI-Ops Workflow Builder. You can customize existing workflows or extend them with additional components, APIs, and integrations tailored to your infrastructure.​ +Yes, users can compose custom automation DAGs using NudgeBee's visual AI-Ops Workflow Builder. ### What ITSM and ticketing systems does NudgeBee integrate with? -NudgeBee provides out-of-the-box integration with GitHub Issues, Jira, and ServiceNow (available in the December 2025 release). These integrations support automated ticketing, incident management system integration for listening and responding to incidents, and CMDB/KB integration (Planned for future releases).​ +NudgeBee provides out-of-the-box integrations with GitHub Issues, Jira, PagerDuty, and ServiceNow. These integrations support automated ticket creation, bidirectional incident status sync, and knowledge base grounding. diff --git a/doc-server/docs/index.md b/doc-server/docs/index.md index 5d8a6f99..dab423d7 100644 --- a/doc-server/docs/index.md +++ b/doc-server/docs/index.md @@ -10,38 +10,59 @@ NudgeBee is an **AI Agents & Agentic Workflow Platform for SRE, CloudOps, and Su NudgeBee's Semantic Knowledge Graph correlates logs, metrics, traces, and code to give your team Cloud-Ops Intelligence that reduces MTTR from hours to minutes. Pre-packaged but not a black box — every agent and workflow is fully extensible, modular, and controllable. -:::tip[NudgeBee is open source] -The **Community** edition is free, Apache 2.0 licensed, and fully functional — self-host it from public images on `ghcr.io/nudgebee` with no license key. See [Editions](./editions.md) for the Community / Enterprise / Cloud comparison. +:::tip[Open Architecture & Licensing] +The **Community** edition is free and fully functional for internal production and operations — server licensed under **BSL 1.1** and agents under **Apache 2.0**. See [Editions & Capabilities](./editions.md) for the Community / Enterprise / Cloud comparison. :::
--- ---- - -## Get Started in 3 Steps: Fork in the Road - -Choose your path to get up and running: +## Choose Your Deployment Path + +Select the path that matches your evaluation and security requirements: + +
+
+
+

⚡ Cloud SaaS

+

Best for: Quickest evaluation with zero control plane infrastructure to manage.

+

Estimated time: 5–10 minutes

+
    +
  1. Sign up at app.nudgebee.com.
    2. +
  2. Install the Agent on your target Kubernetes cluster.
    3. +
  3. Connect Slack and run your first NuBi investigation.
    4. +
+
+ Start Free Cloud Trial → +
-
-
-

⚡ Option A: Cloud SaaS (5 mins)

-

Zero infrastructure to manage. Evaluated and ready instantly.

-
    -
  1. Sign up at app.nudgebee.com.
    2. -
  2. Install the Agent on your cluster (or connect your cloud account).
    3. -
  3. Connect Slack and start exploring AI insights.
    4. -
+
+
+

🚀 Community (Self-Hosted)

+

Best for: Engineers testing on local or dev clusters (Kind, Minikube, EKS, GKE, AKS).

+

Estimated time: 20–30 minutes

+
    +
  1. Deploy NudgeBee Server using the default Helm chart.
    2. +
  2. Connect your BYOM model provider (OpenAI, Bedrock, Ollama).
    3. +
  3. Install the Agent to start gathering cluster telemetry.
    4. +
+
+ Community Quick Start →
-
-

🛡️ Option B: Self-Hosted / On-Prem

-

Complete data isolation inside your own Kubernetes environment.

-
    -
  1. Deploy NudgeBee Server on your Kubernetes cluster via Helm.
    2. -
  2. Configure your BYOM LLM provider (or local Ollama/vLLM).
    3. -
  3. Install the Agent on monitored clusters.
    4. -
+ +
+
+

🏢 Enterprise (Self-Hosted)

+

Best for: Production-grade deployments requiring SAML SSO, high availability, and compliance.

+

Estimated time: 30–60+ minutes

+
    +
  1. Provision external PostgreSQL, Redis, and RabbitMQ.
    2. +
  2. Deploy the Server with Enterprise Helm values and license key.
    3. +
  3. Configure SAML 2.0 SSO and air-gapped SLMs.
    4. +
+
+ Enterprise Setup Guide →
diff --git a/doc-server/docs/installation/agent/installation/index.md b/doc-server/docs/installation/agent/installation/index.md index 392c2e11..814b8c75 100644 --- a/doc-server/docs/installation/agent/installation/index.md +++ b/doc-server/docs/installation/agent/installation/index.md @@ -185,9 +185,21 @@ Look for log confirmation: `Connected to NudgeBee Relay successfully` and `Regis 2. Navigate to **Kubernetes**. 3. Your cluster should display with a **Connected** badge, and nodes and workload pods will start populating within 2 minutes. +### 4. Run Your First Investigation with NuBi (First Successful Outcome) +1. In the NudgeBee dashboard, click the **NuBi AI drawer** on the right side of the screen. +2. Run a concrete diagnostic prompt: + ```text + Which workloads in this cluster have restarted or experienced OOMKills in the last 24 hours? + ``` +3. **Expected Result**: NuBi queries live telemetry from the connected agent, correlates the Kubernetes event stream and Prometheus metrics, and returns: + - A ranked list of affected workloads, namespaces, and pod names. + - Specific failure reasons (e.g. `OOMKilled exit code 137` or failed readiness probes). + - Recommended rightsizing actions or direct links to inspect pod logs. +4. **Success Verification**: When you receive a structured response grounded in your cluster's live workloads, your agent telemetry pipeline is verified and fully operational. + --- -## 3. Troubleshooting Agent Installation Errors +## 4. Troubleshooting Agent Installation Errors Use this diagnostic reference to resolve common agent deployment and communication issues. @@ -201,7 +213,6 @@ Use this diagnostic reference to resolve common agent deployment and communicati | **`node-agent CrashLoopBackOff` (eBPF load failure)** | Kernel < 4.2 or non-standard distro (Bottlerocket, Talos, GKE COS) | Check kernel with `uname -r`. Ensure `/sys/kernel/debug` is accessible, or disable eBPF with `--set nodeAgent.ebpf.enabled=false`. | | **`WebSocket Dial Timeout / EOF`** | Outbound firewall or NetworkPolicy blocking TCP 443 | Verify egress to `wss://relay.nudgebee.com` (SaaS) or your relay Ingress. Ensure port 443 is open. | | **`Prometheus connection refused / empty metrics`** | Wrong Prometheus service URL or missing KSM | Point `globalConfig.prometheus_url` to valid service DNS (e.g. `http://..svc:9090`). | -| **OpenCost shows $0.00 / Missing Cost Data** | Missing cloud provider pricing API key | Provide `--set opencost.opencost.exporter.cloudProviderApiKey=""` or AWS CUR integration. | | **`CRD / Webhook timeout error`** | Prometheus operator CRDs not yet established | Wait 30 seconds and re-run the `helm upgrade` command. | --- diff --git a/doc-server/docs/installation/proxy-agent/quick-start.md b/doc-server/docs/installation/proxy-agent/quick-start.md index 1f4d688a..4a481ab3 100644 --- a/doc-server/docs/installation/proxy-agent/quick-start.md +++ b/doc-server/docs/installation/proxy-agent/quick-start.md @@ -157,6 +157,23 @@ Check the agent logs for confirmation: The datasource should now appear as **Healthy** in the NudgeBee Integrations page. +## Step 6: Run Your First Database Investigation with NuBi + +Verify end-to-end proxy connectivity through your firewall by asking NuBi to inspect the database: + +1. In the NudgeBee UI, open the **NuBi AI drawer** on the right side. +2. Run a concrete diagnostic query: + ```text + Check the connected PostgreSQL database: show me the top 5 largest tables, table bloat, and any long-running transactions. + ``` +3. **Expected Result**: NuBi securely relays the query through the Proxy Agent to your database without exposing any open inbound firewall ports, and returns: + - A markdown table listing the top 5 tables by disk footprint (table size + index size). + - Bloat estimates and dead tuple percentages. + - Active database connections, locks, and cache hit ratios. +4. **Success Verification**: When you receive live table metrics, your Proxy Agent tunnel is fully established and secure. + +--- + ## What's Next You're done! You can now ask NudgeBee questions about your database — it will query through the proxy agent automatically. diff --git a/doc-server/docs/installation/server/index.md b/doc-server/docs/installation/server/index.md index 9e6d8713..c769e55b 100644 --- a/doc-server/docs/installation/server/index.md +++ b/doc-server/docs/installation/server/index.md @@ -324,9 +324,13 @@ You should receive an `HTTP/1.1 200 OK` (or `307 Temporary Redirect` to `/auth/s --- -## 4. Access the UI +## 4. Access the UI & Authenticate -### Without Ingress (Port-Forwarding) +### Understanding Authentication by Deployment Mode +- **Cloud SaaS (`app.nudgebee.com`)**: Completely passwordless — users sign in using OAuth SSO (Google, GitHub, Okta, Microsoft) or email magic links. No passwords are stored or generated. +- **Self-Hosted Community & Enterprise**: Initializes with a secure bootstrap admin password stored in an in-cluster Kubernetes secret so administrators can complete initial setup and configure SSO. + +### Accessing Without Ingress (Port-Forwarding) Forward the NudgeBee UI to your local machine: @@ -334,11 +338,11 @@ Forward the NudgeBee UI to your local machine: kubectl port-forward svc/app 3000:80 -n nudgebee --kube-context $KUBE_CONTEXT ``` -Then open [http://localhost:3000](http://localhost:3000) in your browser. You should see the NudgeBee login page. +Then open [http://localhost:3000](http://localhost:3000) in your browser to view the login screen. -Log in with the admin email address configured during installation (for Enterprise, this is the email associated with your NudgeBee license). The initial password is auto-generated during installation and stored in a Kubernetes secret. +### Retrieving the Bootstrap Admin Credentials -Retrieve the password by decoding the secret: +Retrieve the auto-generated bootstrap password from the `nudgebee` secret: ```shell kubectl get secret nudgebee -n nudgebee \ @@ -347,25 +351,32 @@ kubectl get secret nudgebee -n nudgebee \ echo ``` -Use the decoded password along with the admin email to sign in. +Use your admin email (e.g. `admin@nudgebee.local` or the email provided during install) and the decoded password to sign in. :::caution Production Security -**The dummy credentials provider is intended for initial evaluation only.** For production environments, configure a proper identity provider (SSO, SAML, or LDAP) and disable dummy credentials. See [Authentication Integrations](../../integrations/Authentication/) for details. +**The bootstrap credentials provider is intended for initial onboarding and evaluation only.** For production, configure an enterprise identity provider (SAML 2.0 or OAuth SSO) and disable dummy credentials. See [Authentication Integrations](../../integrations/Authentication/) for details. ::: -:::info -**Relay and Collector URLs for Agent Installation**: When you install the NudgeBee Agent later, you will need these internal service URLs: -- **Relay Server URL**: `ws://relay-server.nudgebee.svc:8080` -- **Collector Server URL**: `http://k8s-collector.nudgebee.svc` -::: +--- + +## 5. Verify Your First Successful Outcome with NuBi -### With Ingress (Public URL) +Once logged into the dashboard, verify end-to-end intelligence by running your first AI-SRE investigation: -If you configured Ingress (see next section), navigate to the URL you set as `BASE_URL` — for example, `https://nudgebee.yourcompany.com`. +1. **Open the NuBi AI Drawer**: Click the **NuBi** icon in the right-hand sidebar or navigation bar. +2. **Run a Concrete Diagnostic Prompt**: + ```text + What workloads in this cluster have experienced restarts or OOMKills in the last 24 hours? + ``` +3. **Expected Result**: NuBi inspects live telemetry, queries the Kubernetes event stream, and responds with: + - A structured list of affected workloads, namespaces, and pod names. + - Exact exit codes (e.g. `137 OOMKilled` or `CrashLoopBackOff`). + - Root cause hypothesis and recommended next steps (e.g. memory request adjustments or inspecting application stack traces). +4. **Success Verification**: When you receive a structured response with direct links to the relevant workloads, your NudgeBee Control Plane and AI engine are verified and healthy! --- -## 5. Add Ingress and SSL (Recommended for Production) +## 6. Add Ingress and SSL (Recommended for Production) The minimal installation above works with port-forwarding, but for production use you should expose NudgeBee via Ingress with SSL. This enables: From adef745e114b4b66ab7f9f97887af05b6908249b Mon Sep 17 00:00:00 2001 From: shiv Date: Sat, 22 Aug 2026 16:06:35 +0530 Subject: [PATCH 2/4] docs: resolve licensing, authentication, sizing, telemetry, and onboarding sequencing review items --- doc-server/docs/editions.md | 10 +-- doc-server/docs/index.md | 74 +++++++++++++++---- .../installation/agent/installation/index.md | 16 ++-- doc-server/docs/installation/server/index.md | 36 +++++---- 4 files changed, 88 insertions(+), 48 deletions(-) diff --git a/doc-server/docs/editions.md b/doc-server/docs/editions.md index 9efd4bd5..2e58be04 100644 --- a/doc-server/docs/editions.md +++ b/doc-server/docs/editions.md @@ -10,7 +10,7 @@ documentation — this page is the source of truth for what each one includes. | | **Community** | **Enterprise** | **Cloud** | |---|---|---|---| -| **What it is** | Free self-hosted edition. Server is licensed under **BSL 1.1**; Agents are **Apache 2.0**. Fully functional. | Self-hosted with a commercial license. Adds enterprise features and SLA support. | Fully managed SaaS, hosted and operated by NudgeBee. | +| **What it is** | Free, source-available self-hosted edition. The Server is licensed under **BSL 1.1** (converting to Apache 2.0 on change date); Agents are **Apache 2.0**. | Self-hosted with a commercial license. Adds enterprise features, SAML SSO, and SLA support. | Fully managed SaaS, hosted and operated by NudgeBee. | | **Where it runs** | Your own Kubernetes cluster | Your own Kubernetes cluster | [app.nudgebee.com](https://app.nudgebee.com) | | **Container images** | Public — `ghcr.io/nudgebee` (no authentication) | Licensed — `registry.nudgebee.com` | Managed for you | | **License key** | Not required | Required | Managed in cloud account | @@ -19,16 +19,12 @@ documentation — this page is the source of truth for what each one includes. | **Support** | Community ([GitHub Issues & Discussions](https://github.com/nudgebee)) | Commercial support (SLA) | Commercial support (SLA) | :::tip -Not sure where to start? The **Community** edition is fully functional and free -— monitoring, the Semantic Knowledge Graph, cost optimizations, troubleshooting, -the Workflow Builder, and Autopilot all work out of the box. You can move to -Enterprise or Cloud later without losing your configuration. +Not sure where to start? The **Community** edition is a production-capable self-hosted edition containing the complete core monitoring, troubleshooting, optimization, workflow, and BYOM experience — the Semantic Knowledge Graph, cost optimizations, alerting, the Workflow Builder, and Autopilot all work out of the box. You can move to Enterprise or Cloud later without losing your configuration. ::: ## What's in the Community edition -The Community edition is **fully functional** for self-hosted Kubernetes -operations. It includes: +The Community edition provides a comprehensive foundation for self-hosted Kubernetes operations. It includes: - The NudgeBee **Server** (control plane, UI, API) and **Agent** - The **Semantic Knowledge Graph** diff --git a/doc-server/docs/index.md b/doc-server/docs/index.md index dab423d7..9a33e2f1 100644 --- a/doc-server/docs/index.md +++ b/doc-server/docs/index.md @@ -11,7 +11,7 @@ NudgeBee is an **AI Agents & Agentic Workflow Platform for SRE, CloudOps, and Su NudgeBee's Semantic Knowledge Graph correlates logs, metrics, traces, and code to give your team Cloud-Ops Intelligence that reduces MTTR from hours to minutes. Pre-packaged but not a black box — every agent and workflow is fully extensible, modular, and controllable. :::tip[Open Architecture & Licensing] -The **Community** edition is free and fully functional for internal production and operations — server licensed under **BSL 1.1** and agents under **Apache 2.0**. See [Editions & Capabilities](./editions.md) for the Community / Enterprise / Cloud comparison. +The **Community** edition is a free, source-available self-hosted edition containing the complete core monitoring, troubleshooting, optimization, workflow, and BYOM experience. The Server is licensed under **BSL 1.1** (converting to Apache 2.0 on its stated change date), and Agents are licensed under **Apache 2.0**. See [Editions & Capabilities](./editions.md) for the Community / Enterprise / Cloud comparison. :::
@@ -44,8 +44,8 @@ Select the path that matches your evaluation and security requirements:

Estimated time: 20–30 minutes

  1. Deploy NudgeBee Server using the default Helm chart.
    2. +
  2. Install the Agent on your monitored cluster.
  3. Connect your BYOM model provider (OpenAI, Bedrock, Ollama).
    4. -
  4. Install the Agent to start gathering cluster telemetry.
Community Quick Start → @@ -57,9 +57,9 @@ Select the path that matches your evaluation and security requirements:

Best for: Production-grade deployments requiring SAML SSO, high availability, and compliance.

Estimated time: 30–60+ minutes

    -
  1. Provision external PostgreSQL, Redis, and RabbitMQ.
    2. -
  2. Deploy the Server with Enterprise Helm values and license key.
    3. -
  3. Configure SAML 2.0 SSO and air-gapped SLMs.
    4. +
  4. Choose bundled dependencies for evaluation, or external PostgreSQL & RabbitMQ for HA.
    5. +
  5. Deploy Server with Enterprise Helm values and license key.
    6. +
  6. Optionally configure SAML 2.0 SSO and air-gapped SLMs.
Enterprise Setup Guide → @@ -82,13 +82,13 @@ Select the path that matches your evaluation and security requirements: ## Deployment Models -NudgeBee is available in two deployment models — and self-hosted comes in two **editions** (free Community and licensed Enterprise — see [Editions](./editions.md)). Choose what fits your organization's requirements: +NudgeBee is available in two deployment models — and self-hosted comes in two **editions** (free Community and licensed Enterprise — see [Editions & Capabilities](./editions.md)). Choose what fits your organization's requirements: | | **Cloud SaaS** | **Self-Hosted (On-Prem)** | |---|---|---| -| **How it works** | NudgeBee hosts and manages the server for you. You connect your infrastructure to the NudgeBee cloud. | You install the NudgeBee server on your own Kubernetes cluster. Available as the free open-source **Community** edition or the licensed **Enterprise** edition. | +| **How it works** | NudgeBee hosts and manages the server for you. You connect your infrastructure to the NudgeBee cloud. | You install the NudgeBee server on your own Kubernetes cluster. Available as the free Community edition (BSL 1.1) or the licensed Enterprise edition. | | **Best for** | SRE, CloudOps, and Support teams that want to get started quickly without managing additional infrastructure. | Organizations with strict data residency, compliance, or air-gapped environment requirements — or anyone who wants a free, fully-functional self-hosted deployment. | -| **Security** | SOC 2 Type II and ISO 27001 certified. | Full data control within your own infrastructure. No telemetry — see [Telemetry & Privacy](./telemetry.md). | +| **Security & Telemetry** | SOC 2 Type II and ISO 27001 certified. | No product analytics or phone-home telemetry is sent to NudgeBee. Operational telemetry collected from your workloads remains strictly within your self-hosted environment. See [Telemetry & Privacy](./telemetry.md). | | **Get started** | Sign up at [app.nudgebee.com](https://app.nudgebee.com) | Follow the [Server Installation Guide](./installation/server/) | --- @@ -105,7 +105,7 @@ NudgeBee has two components, both packaged as Helm charts that deploy natively o | **[NudgeBee Agent](./installation/agent/installation/index.md)** | Lightweight collector that runs inside each cluster you want to monitor. Collects workload data and sends it to the server. | **Everyone** — both SaaS and self-hosted users. | :::info Infrastructure Prerequisite -**Self-hosted users**: You need a dedicated Kubernetes cluster (or namespace) to run the NudgeBee Server before connecting your monitored clusters. Sizing typically requires a 2-node cluster with 16 GB RAM and 4 cores per node. If you do not have Kubernetes clusters to run the server on, choose **Cloud SaaS**. +**Self-hosted users**: You need a Kubernetes cluster (or namespace) to run the NudgeBee Server. Sizing requires **~4 CPU cores and 8–12 GB RAM total** with bundled dependencies (PostgreSQL, RabbitMQ, Redis), or **~2–4 CPU cores and 4–8 GB RAM** with externally managed databases. See the [Server Installation Sizing Table](./installation/server/index.md#system--sizing-requirements) for details. ::: ### Architecture at a Glance @@ -207,16 +207,60 @@ After installation or sign-up, access the NudgeBee UI: ### Login Options -NudgeBee supports multiple authentication methods: +NudgeBee supports multiple authentication methods depending on your deployment: -- **SSO (Single Sign-On)**: Log in with Google, Azure, Okta, or Auth0. Available when [authentication integration](./integrations/Authentication/) is configured. -- **Magic Link**: Enter your email address and receive a one-time login link — no password needed. This is the default method when SSO is not configured. -- **Admin Invite**: If your team admin has added you, you will receive an email invitation with a login link. +- **Bootstrap Administrator Credentials**: For initial self-hosted installation, retrieve the auto-generated password from the `nudgebee` Kubernetes secret. Disable this in production after configuring SSO. +- **SSO (Single Sign-On)**: Log in with Google, Microsoft/Azure AD, Okta, or Auth0 (all editions). SAML 2.0 with IdP group mapping is supported on Enterprise and Cloud. +- **Magic Link**: Enter your email address and receive a one-time login link — no password needed (Cloud SaaS default). +- **Admin Invite**: Accept an email invitation link sent by your organization administrator. -:::info -NudgeBee does not store passwords. Authentication is handled through SSO providers or magic email links, keeping your login secure and simple. +:::info Authentication Privacy +NudgeBee Cloud uses passwordless authentication. Self-hosted installations initially create a bootstrap administrator credential, which should be disabled after configuring production authentication. ::: +--- + +## Progressive Capability Matrix + +NudgeBee delivers value in stages as you connect components of your stack: + +| Stage | Connected Component | What It Unlocks | +|:---:|---|---| +| **1** | **Server Only** | Control plane UI, admin settings, user management, and API access | +| **2** | **K8s Agent Connected** | Real-time cluster inventory, pod health, node statuses, and Kubernetes event stream | +| **3** | **Metrics & Observability** | CPU/memory utilization graphs, SLO tracking, rightsizing recommendations, and cost breakdown | +| **4** | **LLM (BYOM) Connected** | NuBi AI Assistant, natural-language cluster queries, automated incident RCA, and runbook suggestions | +| **5** | **Notifications (Slack / Teams)** | Incident alerting, interactive ChatOps triage buttons, and daily digest summaries | +| **6** | **Git Repository (GitHub / GitLab)** | Automated PR generation for resource limit changes and GitOps reconciliation | + +--- + +## Onboarding Troubleshooting Decision Tree + +If you encounter an issue during initial setup, use this decision tree to pinpoint the cause: + +```text +1. Can you load the Web UI at http://localhost:3000 (or your ingress domain)? + ├── NO → Check server pods: `kubectl get pods -n nudgebee` + │ See Server Troubleshooting: /docs/installation/server/#troubleshooting-installation-failures + └── YES → Proceed to step 2 + +2. Does your Kubernetes cluster appear with a "Connected" badge in the UI? + ├── NO → Check agent runner logs: `kubectl logs -n nudgebee-agent -l app=nudgebee-runner` + │ Ensure outbound TCP port 443 is permitted in your cluster NetworkPolicy. + └── YES → Proceed to step 3 + +3. Are CPU and memory metric charts populating for workloads? + ├── NO → Verify Prometheus URL: check `globalConfig.prometheus_url` in agent values.yaml. + └── YES → Proceed to step 4 + +4. Does NuBi answer natural-language cluster questions? + ├── NO → Verify BYOM model provider API key under Settings → AI / LLM. + └── YES → Setup is healthy and complete! +``` + +--- + ### What to Do After Your First Login Once you are logged in, here is what to explore first: diff --git a/doc-server/docs/installation/agent/installation/index.md b/doc-server/docs/installation/agent/installation/index.md index 814b8c75..a4058d54 100644 --- a/doc-server/docs/installation/agent/installation/index.md +++ b/doc-server/docs/installation/agent/installation/index.md @@ -187,15 +187,17 @@ Look for log confirmation: `Connected to NudgeBee Relay successfully` and `Regis ### 4. Run Your First Investigation with NuBi (First Successful Outcome) 1. In the NudgeBee dashboard, click the **NuBi AI drawer** on the right side of the screen. -2. Run a concrete diagnostic prompt: +2. **Deterministic Cluster Overview Prompt** (verifies live telemetry on any cluster): ```text - Which workloads in this cluster have restarted or experienced OOMKills in the last 24 hours? + List the namespaces, nodes, and visible workloads in this cluster with their health status and latest telemetry timestamp. ``` -3. **Expected Result**: NuBi queries live telemetry from the connected agent, correlates the Kubernetes event stream and Prometheus metrics, and returns: - - A ranked list of affected workloads, namespaces, and pod names. - - Specific failure reasons (e.g. `OOMKilled exit code 137` or failed readiness probes). - - Recommended rightsizing actions or direct links to inspect pod logs. -4. **Success Verification**: When you receive a structured response grounded in your cluster's live workloads, your agent telemetry pipeline is verified and fully operational. + **Expected Result**: NuBi inspects live cluster state and returns a structured summary table listing detected namespaces, node capacities, active workload counts, and recent telemetry heartbeat timestamps. +3. **Follow-Up Diagnostic Prompt** (for incident triage): + ```text + Which workloads in this cluster have restarted, entered CrashLoopBackOff, or experienced OOMKills in the last 24 hours? + ``` + **Expected Result**: On a healthy cluster, NuBi confirms 0 active restart anomalies. On clusters with issues, it provides a ranked list with exit codes and remediation suggestions. +4. **Success Verification**: When you receive structured responses grounded in your cluster's live workloads, your agent telemetry pipeline is verified and fully operational. --- diff --git a/doc-server/docs/installation/server/index.md b/doc-server/docs/installation/server/index.md index c769e55b..e00f3993 100644 --- a/doc-server/docs/installation/server/index.md +++ b/doc-server/docs/installation/server/index.md @@ -17,10 +17,10 @@ The NudgeBee Server is the central control plane of the NudgeBee platform. It ho ::: :::tip[Choosing an edition] -The self-hosted server comes in two editions (see [Editions](../../editions.md) for the full comparison): +The self-hosted server comes in two editions (see [Editions & Capabilities](../../editions.md) for the full comparison): -- **Community** — free and open source (Apache 2.0), fully functional. Images are pulled from the public `ghcr.io/nudgebee` registry. **No license key required.** OAuth SSO (Google, Okta, OneLogin, Azure AD / B2C, Auth0), magic-link email, and credentials login are all included. -- **Enterprise** — adds **SAML 2.0** SSO, NudgeBee's managed models (`nb-llm`, `nb-slm`), and commercial support. Images are pulled from `registry.nudgebee.com` and require a license key. +- **Community** — free, source-available self-hosted edition. The Server is licensed under **BSL 1.1** (converting to Apache 2.0 on its stated change date); Agents are **Apache 2.0**. Images are pulled from the public `ghcr.io/nudgebee` registry. **No license key required.** OAuth SSO (Google, Okta, OneLogin, Azure AD / B2C, Auth0), magic-link email, and credentials login are all included. +- **Enterprise** — adds **SAML 2.0** SSO, NudgeBee's managed models (`nb-llm`, `nb-slm`), and commercial SLA support. Images are pulled from `registry.nudgebee.com` and require a license key. The installation steps below use tabs — pick your edition in each step. ::: @@ -262,13 +262,17 @@ Replace `` with your NudgeBee license key and generate ### Step 3: Run the Helm Install ```shell +# 1. Set your target Kubernetes context (or omit --kube-context if already using current context): +export KUBE_CONTEXT="$(kubectl config current-context)" + +# 2. Deploy NudgeBee Server: helm upgrade nudgebee $NUDGEBEE_CHART \ -f values.yaml \ --install \ --namespace nudgebee \ --create-namespace \ --wait \ - --kube-context $KUBE_CONTEXT + --kube-context "$KUBE_CONTEXT" ``` To install a specific version, add `--version $CHART_VERSION` to the command. See the [Server Releases](../../releases/server/) page for available versions. @@ -335,7 +339,7 @@ You should receive an `HTTP/1.1 200 OK` (or `307 Temporary Redirect` to `/auth/s Forward the NudgeBee UI to your local machine: ```shell -kubectl port-forward svc/app 3000:80 -n nudgebee --kube-context $KUBE_CONTEXT +kubectl port-forward svc/app 3000:80 -n nudgebee ``` Then open [http://localhost:3000](http://localhost:3000) in your browser to view the login screen. @@ -346,8 +350,7 @@ Retrieve the auto-generated bootstrap password from the `nudgebee` secret: ```shell kubectl get secret nudgebee -n nudgebee \ - -o jsonpath='{.data.NEXTAUTH_DUMMY_CREDS_PASSWORD}' \ - --kube-context $KUBE_CONTEXT | base64 -d + -o jsonpath='{.data.NEXTAUTH_DUMMY_CREDS_PASSWORD}' | base64 -d echo ``` @@ -359,20 +362,15 @@ Use your admin email (e.g. `admin@nudgebee.local` or the email provided during i --- -## 5. Verify Your First Successful Outcome with NuBi +## 5. Verify Control Plane Health & Next Steps + +Once logged into the dashboard, complete your initial control plane verification: -Once logged into the dashboard, verify end-to-end intelligence by running your first AI-SRE investigation: +1. **Verify UI & Dashboard Navigation**: Navigate through **Kubernetes**, **Troubleshoot**, and **Optimizations** to confirm all views load without errors. +2. **Connect an LLM Provider (BYOM)**: Navigate to **Settings → AI / LLM** and configure your API key ([OpenAI, AWS Bedrock, or Ollama](../../integrations/LLM/)) to enable NuBi AI investigations and automated RCA. +3. **Next Step: Install the K8s Agent**: The NudgeBee Server is the control plane. To begin ingesting real-time pod telemetry, logs, and metrics from your target clusters, proceed to: -1. **Open the NuBi AI Drawer**: Click the **NuBi** icon in the right-hand sidebar or navigation bar. -2. **Run a Concrete Diagnostic Prompt**: - ```text - What workloads in this cluster have experienced restarts or OOMKills in the last 24 hours? - ``` -3. **Expected Result**: NuBi inspects live telemetry, queries the Kubernetes event stream, and responds with: - - A structured list of affected workloads, namespaces, and pod names. - - Exact exit codes (e.g. `137 OOMKilled` or `CrashLoopBackOff`). - - Root cause hypothesis and recommended next steps (e.g. memory request adjustments or inspecting application stack traces). -4. **Success Verification**: When you receive a structured response with direct links to the relevant workloads, your NudgeBee Control Plane and AI engine are verified and healthy! +👉 **[Install the NudgeBee Agent on Your Cluster](../agent/installation/index.md)** --- From 9a3c6e30e1f9e98b4b7e53870c7c3b4c56fe7d3e Mon Sep 17 00:00:00 2001 From: shiv Date: Sat, 22 Aug 2026 16:10:01 +0530 Subject: [PATCH 3/4] docs: finalize sizing agreement, integration requirement labels, preflight validation, and success criteria --- doc-server/docs/index.md | 16 ++++++++-------- .../installation/agent/installation/index.md | 6 +++--- doc-server/docs/installation/server/index.md | 19 +++++++++++++++++++ 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/doc-server/docs/index.md b/doc-server/docs/index.md index 9a33e2f1..bc737ae6 100644 --- a/doc-server/docs/index.md +++ b/doc-server/docs/index.md @@ -44,8 +44,8 @@ Select the path that matches your evaluation and security requirements:

Estimated time: 20–30 minutes

  1. Deploy NudgeBee Server using the default Helm chart.
    2. -
  2. Install the Agent on your monitored cluster.
  3. Connect your BYOM model provider (OpenAI, Bedrock, Ollama).
    4. +
  4. Install the Agent on your monitored cluster.
Community Quick Start → @@ -105,7 +105,7 @@ NudgeBee has two components, both packaged as Helm charts that deploy natively o | **[NudgeBee Agent](./installation/agent/installation/index.md)** | Lightweight collector that runs inside each cluster you want to monitor. Collects workload data and sends it to the server. | **Everyone** — both SaaS and self-hosted users. | :::info Infrastructure Prerequisite -**Self-hosted users**: You need a Kubernetes cluster (or namespace) to run the NudgeBee Server. Sizing requires **~4 CPU cores and 8–12 GB RAM total** with bundled dependencies (PostgreSQL, RabbitMQ, Redis), or **~2–4 CPU cores and 4–8 GB RAM** with externally managed databases. See the [Server Installation Sizing Table](./installation/server/index.md#system--sizing-requirements) for details. +**Self-hosted users**: You need a Kubernetes cluster (or namespace) to run the NudgeBee Server. Sizing requires **12 GB RAM and 4 CPU cores total** with bundled dependencies (PostgreSQL, RabbitMQ, Redis), or **8 GB RAM and 2 CPU cores total** with externally managed databases. See the [Server Installation Sizing Table](./installation/server/index.md#system--sizing-requirements) for details. ::: ### Architecture at a Glance @@ -156,14 +156,14 @@ SaaS users get a NudgeBee-managed LLM by default. The [LLM integration section]( ## What You Can Do with NudgeBee -NudgeBee ships with 30+ pre-built Cloud-Ops Agents and 30+ integrations. Capabilities grow as you connect more of your stack. The table below shows what each integration unlocks. +NudgeBee ships with 30+ pre-built Cloud-Ops Agents and 30+ integrations. Capabilities grow as you connect more of your stack. The table below shows what each integration unlocks: -| Integration | What It Unlocks | Required? | +| Integration | What It Unlocks | When It's Needed | |---|---|---| -| **[Kubernetes cluster](./installation/agent/installation/index.md)** or **[Cloud account](./features/Cloud/index.md)** | Core monitoring, [Semantic Knowledge Graph](./features/knowledge-graph.md), [cost optimizations](./features/optimizations.md) | **Required** (one of the two) | -| **[Observability source](./integrations/Observability/index.md)** (Prometheus, Datadog, New Relic, etc.) | Metrics, [SLOs](./features/slo.md), alerting, [troubleshooting](./features/troubleshooting/index.md) | **Required** | -| **[LLM connection](./integrations/LLM/index.md)** | NuBi AI agent, AI-powered troubleshooting, pre-built agents, [auto-runbooks](./features/autopilot/auto_runbook/index.md) | Recommended | -| **[IM channel](./integrations/Notifications/index.md)** (Slack, Teams, Google Chat) | [Notifications](./features/notifications.md), interactive alerts, ChatOps | Recommended | +| **[Kubernetes cluster](./installation/agent/installation/index.md)** or **[Cloud account](./features/Cloud/index.md)** | Core monitoring, [Semantic Knowledge Graph](./features/knowledge-graph.md), [cost optimizations](./features/optimizations.md) | **Required for infrastructure visibility** | +| **[Observability source](./integrations/Observability/index.md)** (Prometheus, Datadog, New Relic, etc.) | Metrics, [SLOs](./features/slo.md), alerting, [troubleshooting](./features/troubleshooting/index.md) | **Required for metrics, SLOs, and utilization graphs** | +| **[LLM connection](./integrations/LLM/index.md)** (BYOM) | NuBi AI agent, natural-language triage, [auto-runbooks](./features/autopilot/auto_runbook/index.md) | **Required for NuBi and AI-powered features** | +| **[IM channel](./integrations/Notifications/index.md)** (Slack, Teams, Google Chat) | [Notifications](./features/notifications.md), interactive alerts, ChatOps | **Optional; recommended for operational alerting** | | **Email** | Email notifications and daily reports | Optional | | **[GitHub](./integrations/Code%20Repository/GitHub/github-integration.md)** / **[GitLab](./integrations/Code%20Repository/GitLab/gitlab-integration.md)** | Auto-PRs for optimization recommendations, code-level troubleshooting | Optional | | **[CI/CD system](./integrations/CICD/argocd-integration.md)** (ArgoCD) | Deployment change correlation, rollback insights | Optional | diff --git a/doc-server/docs/installation/agent/installation/index.md b/doc-server/docs/installation/agent/installation/index.md index a4058d54..070d0f9e 100644 --- a/doc-server/docs/installation/agent/installation/index.md +++ b/doc-server/docs/installation/agent/installation/index.md @@ -191,13 +191,13 @@ Look for log confirmation: `Connected to NudgeBee Relay successfully` and `Regis ```text List the namespaces, nodes, and visible workloads in this cluster with their health status and latest telemetry timestamp. ``` - **Expected Result**: NuBi inspects live cluster state and returns a structured summary table listing detected namespaces, node capacities, active workload counts, and recent telemetry heartbeat timestamps. + **Expected Result**: NuBi identifies the connected cluster and returns current namespaces, nodes, and visible workloads grounded in recent telemetry. Exact formatting may vary depending on the configured model. 3. **Follow-Up Diagnostic Prompt** (for incident triage): ```text Which workloads in this cluster have restarted, entered CrashLoopBackOff, or experienced OOMKills in the last 24 hours? ``` - **Expected Result**: On a healthy cluster, NuBi confirms 0 active restart anomalies. On clusters with issues, it provides a ranked list with exit codes and remediation suggestions. -4. **Success Verification**: When you receive structured responses grounded in your cluster's live workloads, your agent telemetry pipeline is verified and fully operational. + **Expected Result**: On a healthy cluster, NuBi confirms no active restart anomalies are detected. On clusters with issues, it provides affected workloads with exit codes and recommended remediation steps. +4. **Success Verification**: When you receive responses grounded in your cluster's live workloads and node statuses, your agent telemetry pipeline is verified and fully operational. --- diff --git a/doc-server/docs/installation/server/index.md b/doc-server/docs/installation/server/index.md index e00f3993..dc772155 100644 --- a/doc-server/docs/installation/server/index.md +++ b/doc-server/docs/installation/server/index.md @@ -134,6 +134,25 @@ The NudgeBee server relies on core backend services. You can run them bundled in | **Registry Access** | `ghcr.io/nudgebee` (Community) or `registry.nudgebee.com` (Enterprise) | Same | Air-gapped environments can mirror images internally | | **NudgeBee License Key** | Enterprise only | Enterprise only | Community edition does not require a key | +### Preflight Cluster Validation + +Before deploying, run this quick check in your terminal to verify your cluster meets the version, capacity, and storage requirements: + +```bash +# 1. Verify kubectl context and Kubernetes server version (v1.27+) +kubectl config current-context +kubectl version --short 2>/dev/null || kubectl version + +# 2. Verify Helm version (v3.10+) +helm version --short + +# 3. Check allocatable CPU and memory across your nodes +kubectl get nodes -o custom-columns=NAME:.metadata.name,STATUS:.status.conditions[-1].type,ALLOCATABLE_CPU:.status.allocatable.cpu,ALLOCATABLE_MEM:.status.allocatable.memory + +# 4. Verify default StorageClass exists for persistent volumes +kubectl get storageclass +``` + ### Network Requirements & Decision Rationale Your cluster needs the following network access. Understanding why each rule exists helps you configure firewalls with least privilege: From e2ba17921f63f9775b9c0c0e4d45ca583eb591bf Mon Sep 17 00:00:00 2001 From: shiv Date: Sat, 22 Aug 2026 16:13:49 +0530 Subject: [PATCH 4/4] docs: synchronize Quick Start table with Server -> BYOM -> Agent sequence --- doc-server/docs/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc-server/docs/index.md b/doc-server/docs/index.md index bc737ae6..b0e865a5 100644 --- a/doc-server/docs/index.md +++ b/doc-server/docs/index.md @@ -178,15 +178,15 @@ Follow these steps to go from zero to a working NudgeBee setup. The path differs | Step | Cloud SaaS | Self-Hosted | |---|---|---| -| **1. Get access** | [Sign up at app.nudgebee.com](https://app.nudgebee.com) — no installation needed, you are ready in seconds. | [Install the NudgeBee Server](./installation/server/index.md) on a Kubernetes cluster. Takes 15–30 minutes. | -| **2. Connect your clusters** | [Install the Agent](./installation/agent/installation/index.md) on each cluster, or [connect a cloud account](./features/Cloud/index.md) for auto-discovery. | Same — [install the Agent](./installation/agent/installation/index.md) or [connect a cloud account](./features/Cloud/index.md). | -| **3. Connect observability** | Connect your existing monitoring tools (Prometheus, Datadog, New Relic, etc.). See [Observability Integrations](./integrations/Observability/index.md). | Same — connect your monitoring tools. | -| **4. Enable AI** | Already included — a managed LLM is provided. Nothing to configure. | [Connect an LLM provider](./integrations/LLM/index.md) (BYOM) to enable NuBi and AI-powered troubleshooting. | -| **5. Set up notifications** | Connect [Slack](./integrations/Notifications/slack.md), [Teams](./integrations/Notifications/msteams.md), or [Google Chat](./integrations/Notifications/google_chat.md). | Same — connect your messaging tool. | -| **6. Explore** | You are ready! Check [Optimizations](./features/optimizations.md), [Troubleshooting](./features/troubleshooting/index.md), and the [Semantic Knowledge Graph](./features/knowledge-graph.md). | Same — start exploring the dashboard. | +| **1. Get access** | [Sign up at app.nudgebee.com](https://app.nudgebee.com) — ready in seconds with zero infrastructure to manage. | [Install the NudgeBee Server](./installation/server/index.md) on a Kubernetes cluster. Takes 15–30 minutes. | +| **2. Connect AI (LLM)** | Managed LLM included by default. Nothing to configure. | [Connect your BYOM model provider](./integrations/LLM/index.md) (OpenAI, Bedrock, Ollama) under Settings → AI / LLM. | +| **3. Connect your clusters** | [Install the Agent](./installation/agent/installation/index.md) on each cluster, or [connect a cloud account](./features/Cloud/index.md). | Same — [install the Agent](./installation/agent/installation/index.md) on each monitored cluster. | +| **4. Verify observability** | Ingest metrics from the agent or connect external tools ([Prometheus, Datadog](./integrations/Observability/index.md)). | Same — verify bundled Prometheus or connect your observability stack. | +| **5. Run first investigation** | Open the **NuBi AI drawer** to run your first cluster health investigation. | Same — run your first natural-language triage investigation with NuBi. | +| **6. Configure integrations** | Connect [Slack/Teams](./integrations/Notifications/) for alerts and [GitHub/GitLab](./integrations/Code%20Repository/GitHub/github-integration.md) for auto-PRs. | Same — configure notification channels, ticketing, and GitOps repositories. | :::tip -Steps 3–5 can be done in any order. Each integration adds capabilities independently — you do not need to complete everything before you start seeing value. +Steps 4–6 can be tailored to your workflow. Each integration expands platform capabilities independently. ::: ---