diff --git a/README.md b/README.md index 3f5dbd374..25492a48d 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,6 @@ Compatible with kube-prometheus-stack, Prometheus Operator, and more. Robusta integrates with Prometheus by webhook and adds features like: * [**Smart Grouping**](https://docs.robusta.dev/master/configuration/notification-grouping.html) - reduce notification spam with Slack threads 🧡 -* [**AI Investigation**](https://docs.robusta.dev/master/configuration/holmesgpt/index.html#ai-analysis) - Kickstart alert investigation with AI (optional) * [**Alert Enrichment**](https://docs.robusta.dev/master/how-it-works/index.html#automatically-investigate-a-prometheus-alert) - see pod logs and other data alongside your alerts * [**Self-Healing**](https://docs.robusta.dev/master/tutorials/alert-remediation.html#remediate-prometheus-alerts) - define auto-remediation rules for faster fixes * [**Advanced Routing**](https://docs.robusta.dev/master/notification-routing/configuring-sinks.html) based on team, namespace, and more @@ -294,8 +293,6 @@ Robusta is installed with Helm. For convenience, we provide a CLI wizard to gene You can install Robusta alongside your existing Prometheus, or as an all-in-one bundle with Robusta and a preconfigured `kube-prometheus-stack`. -To get *even more* out of Robusta, we recommend creating [a free Robusta UI account](#-free-robusta-ui). Learn more below. - [Create a free Robusta UI account Β»](https://platform.robusta.dev/signup?utm_source=github&utm_medium=robusta-readme&utm_content=installing_robusta_section) [Installation instructions Β»](https://docs.robusta.dev/master/setup-robusta/installation/index.html) @@ -360,17 +357,6 @@ To get *even more* out of Robusta, we recommend creating [a free Robusta UI acco -## πŸ–₯ Free Robusta UI -Take your Kubernetes monitoring to the next level with the [Robusta SaaS platform](https://platform.robusta.dev/signup?utm_source=github&utm_medium=robusta-readme&utm_content=free_robusta_ui_section). Creating an account is free, and includes: - -- **AI Assistant**: Solve alerts faster with an AI assistant that highlights relevant observability data -- **Alert Timeline**: View Prometheus alerts across multiple clusters and spot correlations with a powerful timeline view -- **Change Tracking**: Correlate alerts with changes to your infrastructure or applications, with Robusta's automatic change tracking for Kubernetes - - - - -

(back to top)

diff --git a/docs/_ext/region_box.py b/docs/_ext/region_box.py deleted file mode 100644 index fc5d38126..000000000 --- a/docs/_ext/region_box.py +++ /dev/null @@ -1,161 +0,0 @@ -""" -Directives and role for Robusta platform URL / code components with an -embedded region selector. - -Usage in .rst:: - - .. robusta-url:: https://platform.robusta.dev/account - - .. robusta-code:: bash - - curl --location --request POST 'https://api.robusta.dev/api/alerts' \ - --header 'Authorization: Bearer API-KEY' - - Sign up at :robusta-url:`https://platform.robusta.dev/signup` to get started. - - Or with custom link text: - - Visit :robusta-url:`our platform ` today. - -The rendered HTML carries ``robusta-region-box`` (block) or -``robusta-region-inline`` (inline) classes; the client-side script in -``_static/region-selector.js`` injects the US/EU/AP selector and keeps -every region-aware component on the page in sync. -""" - -import re -from html import escape - -from docutils import nodes -from docutils.parsers.rst import directives -from sphinx.util import parselinenos -from sphinx.util.docutils import SphinxDirective - - -_LABELLED_URL_RE = re.compile(r"^\s*(.+?)\s*<\s*([^<>\s]+)\s*>\s*$", re.DOTALL) - - -class RobustaUrlDirective(SphinxDirective): - has_content = True - required_arguments = 0 - optional_arguments = 1 - final_argument_whitespace = True - - def run(self): - if self.arguments: - url = self.arguments[0].strip() - else: - url = "\n".join(self.content).strip() - if not url: - return [ - self.state.document.reporter.warning( - "robusta-url requires a URL argument or content", - line=self.lineno, - ) - ] - - url_attr = escape(url, quote=True) - url_text = escape(url) - html = ( - f'
' - f'
' - f'{url_text}' - f'
' - ) - return [nodes.raw("", html, format="html")] - - -class RobustaCodeDirective(SphinxDirective): - has_content = True - required_arguments = 0 - optional_arguments = 1 - final_argument_whitespace = False - option_spec = { - "emphasize-lines": directives.unchanged_required, - } - - def run(self): - language = self.arguments[0] if self.arguments else "text" - code = "\n".join(self.content) - if not code.strip(): - return [ - self.state.document.reporter.warning( - "robusta-code requires a code block as content", - line=self.lineno, - ) - ] - - container = nodes.container(classes=["robusta-region-box", "robusta-region-box--code"]) - literal = nodes.literal_block(code, code) - literal["language"] = language - - emphasize_spec = self.options.get("emphasize-lines") - if emphasize_spec: - try: - nlines = len(code.split("\n")) - hl_lines = [x + 1 for x in parselinenos(emphasize_spec, nlines) if 0 <= x < nlines] - except ValueError: - hl_lines = [] - if hl_lines: - literal["highlight_args"] = {"hl_lines": hl_lines} - - container += literal - return [container] - - -class RobustaRegionPickerDirective(SphinxDirective): - """Standalone region picker: a 'Select Region' label + dropdown, no URL.""" - - has_content = False - required_arguments = 0 - optional_arguments = 1 - final_argument_whitespace = True - - def run(self): - label = (self.arguments[0].strip() if self.arguments else "Select Region") - html = ( - f'
' - f'{escape(label)}' - f'' - f"
" - ) - return [nodes.raw("", html, format="html")] - - -def robusta_url_role(name, rawtext, text, lineno, inliner, options=None, content=None): - """Inline ``:robusta-url:`URL``` or ``:robusta-url:`label ```.""" - raw_text = nodes.unescape(text) - match = _LABELLED_URL_RE.match(raw_text) - if match: - label = match.group(1).strip() - url = match.group(2).strip() - else: - url = raw_text.strip() - label = url - if not label: - label = url - if not url: - msg = inliner.reporter.error( - "robusta-url role requires a URL", line=lineno - ) - return [inliner.problematic(rawtext, rawtext, msg)], [msg] - - html = ( - f'' - f'' - f"{escape(label)}" - f"" - ) - return [nodes.raw("", html, format="html")], [] - - -def setup(app): - app.add_directive("robusta-url", RobustaUrlDirective) - app.add_directive("robusta-code", RobustaCodeDirective) - app.add_directive("robusta-region-picker", RobustaRegionPickerDirective) - app.add_role("robusta-url", robusta_url_role) - return { - "version": "0.3", - "parallel_read_safe": True, - "parallel_write_safe": True, - } diff --git a/docs/_static/custom.css b/docs/_static/custom.css index c858b5add..c6a8be02c 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -352,262 +352,3 @@ h3 { .success-icon { color: #28a745; /* or any green color you prefer */ } - -/* Robusta region-aware URL / code component */ -.md-typeset .robusta-region-box, -.robusta-region-box { - margin: 1rem 0 1.5rem !important; - border: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.12)); - border-radius: 4px; - background-color: var(--md-code-bg-color, rgba(0, 0, 0, 0.04)); - overflow: hidden; -} - -.md-typeset .robusta-region-box__bar, -.robusta-region-box__bar { - display: flex !important; - align-items: center; - gap: 0.6rem; - padding: 0.35rem 0.6rem; - background-color: var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.06)); - border-bottom: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.08)); - font-size: 0.72rem; - line-height: 1.2; -} - -.md-typeset .robusta-region-box__bar-label, -.robusta-region-box__bar-label { - font-weight: 600; - color: var(--md-default-fg-color--light, rgba(0, 0, 0, 0.6)); -} - -.md-typeset .robusta-region-box__region-options, -.robusta-region-box__region-options { - display: inline-flex !important; - align-items: center; - gap: 0; - border-radius: 3px; - overflow: hidden; -} - -.md-typeset .robusta-region-box__region-btn, -.robusta-region-box__region-btn { - -webkit-appearance: none; - appearance: none; - display: inline-block !important; - border: 1px solid var(--md-default-fg-color--lighter, rgba(0, 0, 0, 0.26)) !important; - background: var(--md-default-bg-color, #fff) !important; - color: var(--md-default-fg-color, #333) !important; - padding: 0.2rem 0.7rem !important; - margin: 0 !important; - cursor: pointer; - font: inherit; - font-size: 0.72rem !important; - font-weight: 600; - line-height: 1.2; - min-width: 2.2rem; - text-align: center; - box-shadow: none; - border-radius: 0 !important; - transition: background-color 0.15s ease, color 0.15s ease, border-color 0.15s ease; -} - -.md-typeset .robusta-region-box__region-btn + .robusta-region-box__region-btn, -.robusta-region-box__region-btn + .robusta-region-box__region-btn { - border-left-width: 0 !important; -} - -.md-typeset .robusta-region-box__region-btn:first-child, -.robusta-region-box__region-btn:first-child { - border-top-left-radius: 3px !important; - border-bottom-left-radius: 3px !important; -} - -.md-typeset .robusta-region-box__region-btn:last-child, -.robusta-region-box__region-btn:last-child { - border-top-right-radius: 3px !important; - border-bottom-right-radius: 3px !important; -} - -.md-typeset .robusta-region-box__region-btn:hover, -.robusta-region-box__region-btn:hover { - color: var(--md-primary-fg-color, #1976d2) !important; -} - -.md-typeset .robusta-region-box__region-btn.is-active, -.robusta-region-box__region-btn.is-active { - background: var(--md-primary-fg-color, #1976d2) !important; - border-color: var(--md-primary-fg-color, #1976d2) !important; - color: var(--md-primary-bg-color, #fff) !important; - z-index: 1; - position: relative; -} - -.md-typeset .robusta-region-box__region-btn:focus-visible, -.robusta-region-box__region-btn:focus-visible { - outline: 2px solid var(--md-accent-fg-color, #1976d2); - outline-offset: 2px; - z-index: 1; - position: relative; -} - -/* URL body */ -.md-typeset .robusta-region-box__body, -.robusta-region-box__body { - padding: 0.6rem 0.85rem; - font-family: var(--md-code-font, "Roboto Mono", monospace); - font-size: 0.78rem; - word-break: break-all; -} - -.md-typeset .robusta-region-box--url a.robusta-region-box__url, -.robusta-region-box--url a.robusta-region-box__url { - color: var(--md-typeset-a-color, var(--md-primary-fg-color, #1976d2)); - text-decoration: none; -} - -.md-typeset .robusta-region-box--url a.robusta-region-box__url:hover, -.robusta-region-box--url a.robusta-region-box__url:hover { - text-decoration: underline; -} - -/* Let the inner literal block sit flush inside the frame */ -.md-typeset .robusta-region-box--code > .highlight, -.md-typeset .robusta-region-box--code > div[class*="highlight"], -.md-typeset .robusta-region-box--code > pre { - margin: 0 !important; - border: 0 !important; - border-radius: 0 !important; -} - -/* Inline region-aware URL: small picker beside the link */ -.md-typeset .robusta-region-inline, -.robusta-region-inline { - display: inline-flex; - align-items: baseline; - gap: 0.3rem; - white-space: nowrap; - max-width: 100%; -} - -.md-typeset .robusta-region-inline__url, -.robusta-region-inline__url { - word-break: break-all; - white-space: normal; -} - -.md-typeset .robusta-region-inline__picker, -.robusta-region-inline__picker { - position: relative; - display: inline-block !important; - vertical-align: baseline; - line-height: 1; - font-size: 0.72rem; - font-weight: 600; - white-space: nowrap; -} - -.md-typeset .robusta-region-inline__trigger, -.robusta-region-inline__trigger { - -webkit-appearance: none; - appearance: none; - display: inline-flex !important; - align-items: center; - gap: 0.2rem; - border: 1px solid var(--md-default-fg-color--lighter, rgba(0, 0, 0, 0.26)) !important; - background: var(--md-default-bg-color, #fff) !important; - color: var(--md-default-fg-color, #333) !important; - padding: 0.1rem 0.45rem !important; - margin: 0 !important; - cursor: pointer; - font: inherit; - font-size: 0.72rem !important; - font-weight: 600; - line-height: 1.2; - border-radius: 3px !important; - box-shadow: none; - transition: border-color 0.15s ease, color 0.15s ease; -} - -.md-typeset .robusta-region-inline__trigger:hover, -.robusta-region-inline__trigger:hover { - border-color: var(--md-primary-fg-color, #1976d2) !important; - color: var(--md-primary-fg-color, #1976d2) !important; -} - -.md-typeset .robusta-region-inline__trigger:focus-visible, -.robusta-region-inline__trigger:focus-visible { - outline: 2px solid var(--md-accent-fg-color, #1976d2); - outline-offset: 2px; -} - -.md-typeset .robusta-region-inline__caret, -.robusta-region-inline__caret { - font-size: 0.7em; - line-height: 1; - opacity: 0.7; -} - -.md-typeset .robusta-region-inline__menu, -.robusta-region-inline__menu { - position: absolute; - top: calc(100% + 2px); - left: 0; - z-index: 30; - display: none !important; - margin: 0 !important; - padding: 0.15rem 0 !important; - list-style: none !important; - min-width: 100%; - width: auto; - background: var(--md-default-bg-color, #fff); - border: 1px solid var(--md-default-fg-color--lighter, rgba(0, 0, 0, 0.18)); - border-radius: 4px; - box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12); - font-weight: 500; -} - -.md-typeset .robusta-region-inline__picker.is-open .robusta-region-inline__menu, -.robusta-region-inline__picker.is-open .robusta-region-inline__menu { - display: block !important; -} - -.md-typeset .robusta-region-inline__option, -.robusta-region-inline__option { - display: block !important; - padding: 0.25rem 0.5rem !important; - margin: 0 !important; - cursor: pointer; - color: var(--md-default-fg-color, #333); - user-select: none; - text-align: center; - line-height: 1.2; -} - -.md-typeset .robusta-region-inline__option:hover, -.robusta-region-inline__option:hover { - background: var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.06)); -} - -.md-typeset .robusta-region-inline__option.is-active, -.robusta-region-inline__option.is-active { - background: var(--md-primary-fg-color, #1976d2); - color: var(--md-primary-bg-color, #fff); -} - -/* Standalone region picker block (label + dropdown, no URL) */ -.md-typeset .robusta-region-picker, -.robusta-region-picker { - display: inline-flex !important; - align-items: center; - gap: 0.5rem; - margin: 0.75rem 0 0.5rem !important; - font-size: 0.78rem; - line-height: 1.4; -} - -.md-typeset .robusta-region-picker__label, -.robusta-region-picker__label { - font-weight: 600; - color: var(--md-default-fg-color--light, rgba(0, 0, 0, 0.7)); -} diff --git a/docs/_static/region-selector.js b/docs/_static/region-selector.js deleted file mode 100644 index 878a3be21..000000000 --- a/docs/_static/region-selector.js +++ /dev/null @@ -1,344 +0,0 @@ -(function () { - "use strict"; - - const REGIONS = { - us: { label: "US", infix: "" }, - eu: { label: "EU", infix: ".eu" }, - ap: { label: "AP", infix: ".ap" }, - }; - const STORAGE_KEY = "robusta-docs-region"; - const URL_PATTERN = /\b(platform|api|relay|sp)(?:\.(?:eu|ap))?\.robusta\.dev\b/g; - const DETECT_PATTERN = /\b(?:platform|api|relay|sp)(?:\.(?:eu|ap))?\.robusta\.dev\b/; - const BAR_CLASS = "robusta-region-box__bar"; - const BTN_CLASS = "robusta-region-box__region-btn"; - const INLINE_PICKER_CLASS = "robusta-region-inline__picker"; - const INLINE_BTN_CLASS = "robusta-region-inline__btn"; - - function getRegion() { - try { - const r = localStorage.getItem(STORAGE_KEY); - return REGIONS[r] ? r : "us"; - } catch (e) { - return "us"; - } - } - - function saveRegion(r) { - try { - localStorage.setItem(STORAGE_KEY, r); - } catch (e) {} - } - - function rewrite(text, regionKey) { - const infix = REGIONS[regionKey].infix; - return text.replace(URL_PATTERN, function (_, sub) { - return sub + infix + ".robusta.dev"; - }); - } - - // All URL occurrences across the page content (text nodes + relevant - // attributes). Boxes are separate β€” each holds its selector buttons so - // every box on the page stays visually in sync on region change. - const targets = []; - const boxes = []; - - function collectTargets(root) { - const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, { - acceptNode: function (node) { - if (!node.nodeValue || !DETECT_PATTERN.test(node.nodeValue)) { - return NodeFilter.FILTER_REJECT; - } - const parent = node.parentNode; - if (parent && (parent.tagName === "SCRIPT" || parent.tagName === "STYLE")) { - return NodeFilter.FILTER_REJECT; - } - return NodeFilter.FILTER_ACCEPT; - }, - }); - let node; - while ((node = walker.nextNode())) { - targets.push({ kind: "text", node: node, original: node.nodeValue }); - } - const ATTR_NAMES = ["href", "src", "data-clipboard-text", "value", "title"]; - const selector = ATTR_NAMES.map(function (a) { return "[" + a + "]"; }).join(","); - root.querySelectorAll(selector).forEach(function (el) { - ATTR_NAMES.forEach(function (attr) { - const v = el.getAttribute(attr); - if (v && DETECT_PATTERN.test(v)) { - targets.push({ kind: "attr", node: el, attr: attr, original: v }); - } - }); - }); - } - - function applyRegion(regionKey) { - for (let i = 0; i < targets.length; i++) { - const t = targets[i]; - const next = rewrite(t.original, regionKey); - if (t.kind === "text") { - if (t.node.nodeValue !== next) t.node.nodeValue = next; - } else { - if (t.node.getAttribute(t.attr) !== next) t.node.setAttribute(t.attr, next); - } - } - for (let j = 0; j < boxes.length; j++) { - const box = boxes[j]; - if (box.buttons) { - for (let k = 0; k < box.buttons.length; k++) { - const btn = box.buttons[k]; - const active = btn.getAttribute("data-region") === regionKey; - btn.classList.toggle("is-active", active); - btn.setAttribute("aria-checked", String(active)); - } - } - if (box.items) { - if (box.currentEl) box.currentEl.textContent = REGIONS[regionKey].label; - for (let m = 0; m < box.items.length; m++) { - const item = box.items[m]; - const active = item.getAttribute("data-region") === regionKey; - item.classList.toggle("is-active", active); - item.setAttribute("aria-selected", String(active)); - } - } - } - } - - function syncAll(regionKey) { - saveRegion(regionKey); - applyRegion(regionKey); - } - - function closeAllInlineMenus(except) { - document.querySelectorAll("." + INLINE_PICKER_CLASS + ".is-open").forEach(function (p) { - if (p === except) return; - p.classList.remove("is-open"); - const trig = p.querySelector(".robusta-region-inline__trigger"); - if (trig) trig.setAttribute("aria-expanded", "false"); - }); - } - - function buildInlinePicker(currentRegion) { - const picker = document.createElement("span"); - picker.className = INLINE_PICKER_CLASS; - - const trigger = document.createElement("button"); - trigger.type = "button"; - trigger.className = "robusta-region-inline__trigger"; - trigger.setAttribute("aria-haspopup", "listbox"); - trigger.setAttribute("aria-expanded", "false"); - - const currentEl = document.createElement("span"); - currentEl.className = "robusta-region-inline__current"; - currentEl.textContent = REGIONS[currentRegion].label; - - const caret = document.createElement("span"); - caret.className = "robusta-region-inline__caret"; - caret.setAttribute("aria-hidden", "true"); - caret.textContent = "β–Ύ"; - - trigger.appendChild(currentEl); - trigger.appendChild(caret); - - const menu = document.createElement("ul"); - menu.className = "robusta-region-inline__menu"; - menu.setAttribute("role", "listbox"); - - const items = []; - - function focusItem(idx) { - if (idx < 0) idx = items.length - 1; - if (idx >= items.length) idx = 0; - items.forEach(function (it, i) { it.tabIndex = i === idx ? 0 : -1; }); - items[idx].focus(); - } - - function selectItem(key) { - syncAll(key); - picker.classList.remove("is-open"); - trigger.setAttribute("aria-expanded", "false"); - trigger.focus(); - } - - Object.keys(REGIONS).forEach(function (key) { - const item = document.createElement("li"); - item.setAttribute("role", "option"); - item.setAttribute("data-region", key); - item.className = "robusta-region-inline__option"; - const isActive = key === currentRegion; - item.setAttribute("aria-selected", String(isActive)); - item.tabIndex = isActive ? 0 : -1; - if (isActive) item.classList.add("is-active"); - item.textContent = REGIONS[key].label; - item.addEventListener("click", function (e) { - e.preventDefault(); - selectItem(key); - }); - item.addEventListener("keydown", function (e) { - const idx = items.indexOf(item); - switch (e.key) { - case "Enter": - case " ": - e.preventDefault(); - selectItem(key); - break; - case "ArrowDown": - e.preventDefault(); - focusItem(idx + 1); - break; - case "ArrowUp": - e.preventDefault(); - focusItem(idx - 1); - break; - case "Home": - e.preventDefault(); - focusItem(0); - break; - case "End": - e.preventDefault(); - focusItem(items.length - 1); - break; - case "Tab": - picker.classList.remove("is-open"); - trigger.setAttribute("aria-expanded", "false"); - break; - case "Escape": - e.preventDefault(); - picker.classList.remove("is-open"); - trigger.setAttribute("aria-expanded", "false"); - trigger.focus(); - break; - } - }); - menu.appendChild(item); - items.push(item); - }); - - function openMenu() { - closeAllInlineMenus(picker); - picker.classList.add("is-open"); - trigger.setAttribute("aria-expanded", "true"); - const activeIdx = items.findIndex(function (it) { return it.classList.contains("is-active"); }); - focusItem(activeIdx >= 0 ? activeIdx : 0); - } - - trigger.addEventListener("click", function (e) { - e.preventDefault(); - e.stopPropagation(); - if (picker.classList.contains("is-open")) { - picker.classList.remove("is-open"); - trigger.setAttribute("aria-expanded", "false"); - } else { - openMenu(); - } - }); - - trigger.addEventListener("keydown", function (e) { - if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") { - e.preventDefault(); - openMenu(); - } else if (e.key === "ArrowUp") { - e.preventDefault(); - openMenu(); - focusItem(items.length - 1); - } - }); - - picker.appendChild(trigger); - picker.appendChild(menu); - - return { picker: picker, trigger: trigger, currentEl: currentEl, items: items }; - } - - function buildBar(currentRegion) { - const bar = document.createElement("div"); - bar.className = BAR_CLASS; - - const label = document.createElement("span"); - label.className = "robusta-region-box__bar-label"; - label.textContent = "Select Region"; - bar.appendChild(label); - - const group = document.createElement("div"); - group.className = "robusta-region-box__region-options"; - group.setAttribute("role", "radiogroup"); - group.setAttribute("aria-label", "Select your Robusta region"); - - const buttons = []; - Object.keys(REGIONS).forEach(function (key) { - const btn = document.createElement("button"); - btn.type = "button"; - btn.setAttribute("role", "radio"); - btn.setAttribute("data-region", key); - btn.className = BTN_CLASS; - btn.textContent = REGIONS[key].label; - const active = key === currentRegion; - btn.setAttribute("aria-checked", String(active)); - if (active) btn.classList.add("is-active"); - btn.addEventListener("click", function () { - syncAll(key); - }); - group.appendChild(btn); - buttons.push(btn); - }); - - bar.appendChild(group); - return { bar: bar, buttons: buttons }; - } - - function init() { - targets.length = 0; - boxes.length = 0; - - const content = - document.querySelector(".md-content__inner") || - document.querySelector("article") || - document.querySelector("main") || - document.body; - if (!content) return; - - const region = getRegion(); - - content.querySelectorAll(".robusta-region-box").forEach(function (el) { - const existingBar = el.querySelector(":scope > ." + BAR_CLASS); - if (existingBar) existingBar.remove(); - const built = buildBar(region); - el.insertBefore(built.bar, el.firstChild); - boxes.push({ buttons: built.buttons }); - }); - - content.querySelectorAll(".robusta-region-inline").forEach(function (el) { - const existingPicker = el.querySelector(":scope > ." + INLINE_PICKER_CLASS); - if (existingPicker) existingPicker.remove(); - const built = buildInlinePicker(region); - el.appendChild(built.picker); - boxes.push({ currentEl: built.currentEl, items: built.items }); - }); - - collectTargets(content); - - if (targets.length === 0 && boxes.length === 0) return; - - applyRegion(region); - } - - document.addEventListener("click", function (e) { - const open = document.querySelector("." + INLINE_PICKER_CLASS + ".is-open"); - if (open && !open.contains(e.target)) closeAllInlineMenus(null); - }); - document.addEventListener("keydown", function (e) { - if (e.key === "Escape") closeAllInlineMenus(null); - }); - - if (document.readyState === "loading") { - document.addEventListener("DOMContentLoaded", init); - } else { - init(); - } - - // Material/Sphinx-Immaterial instant navigation swaps the content area - // without firing DOMContentLoaded. The theme exposes an RxJS `document$` - // observable that emits on every swap; re-run init() on each emission. - if (typeof window !== "undefined" && window.document$ && typeof window.document$.subscribe === "function") { - window.document$.subscribe(init); - } -})(); diff --git a/docs/conf.py b/docs/conf.py index a00a1619d..4ee9e6978 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,7 +50,6 @@ "sphinx_design", "sphinxcontrib.images", "autorobusta", - "region_box", "sphinx_immaterial", "sphinxcontrib.details.directive", "sphinx_jinja", @@ -371,7 +370,7 @@ "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css", ] -html_js_files = ["analytics.js", "region-selector.js"] +html_js_files = ["analytics.js"] html_favicon = "_static/favicon.png" diff --git a/docs/configuration/alertmanager-integration/_testing_integration.rst b/docs/configuration/alertmanager-integration/_testing_integration.rst index b9e5c80ac..d1b6282fa 100644 --- a/docs/configuration/alertmanager-integration/_testing_integration.rst +++ b/docs/configuration/alertmanager-integration/_testing_integration.rst @@ -13,28 +13,8 @@ Send a dummy alert to AlertManager: robusta demo-alert - .. tab-item:: Robusta UI - In the Robusta UI, go to the "Clusters" tab, choose the right cluster and click "Simulate Alert". - - .. image:: /images/robusta-ui-simulate-alert-1.png - :alt: Choose the cluster - :width: 900 - :align: center - - Then - - 1. Check **Send alert with no resource**. - 2. Provide a name for the alert in the **Alert name (identifier)** field (e.g., "Testing Prod AlertManager"). - 3. Select **Alert Manager** under the "Send alert to" section. - 4. Click the **Simulate Alert** button to send the test alert. - - .. image:: /images/robusta-ui-simulate-alert-2.png - :alt: Send Test Alert - :width: 600 - :align: center - -If everything is setup properly, this alert will reach Robusta. It will show up in the Robusta UI, Slack, and other configured sinks. +If everything is setup properly, this alert will reach Robusta. It will show up in Slack and other configured sinks. .. note:: diff --git a/docs/configuration/alertmanager-integration/azure-managed-prometheus.rst b/docs/configuration/alertmanager-integration/azure-managed-prometheus.rst deleted file mode 100644 index 127a04388..000000000 --- a/docs/configuration/alertmanager-integration/azure-managed-prometheus.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Azure Managed Prometheus Alerts -********************************* - -This guide shows how to send alerts from Azure Managed Prometheus to Robusta. - -For configuring metric querying and advanced settings, see :doc:`/configuration/metric-providers-azure`. - -Send Alerts to Robusta -=============================== - -This integration sends Azure Managed Prometheus alerts to Robusta. To configure it: - -1. Login to the Robusta UI and navigate to the ``Settings`` > ``Advanced`` tab. -2. In the Azure Webhook section click ``Generate URL`` and save the generated url. -3. Login to the Microsoft Azure Portal, go to ``Alerts`` > ``Action groups`` -4. Create a new action group, or edit an existing one. -5. Under the `Actions` tabs (**not** the Notifications tab) add a ``Webhook`` and copy the url from step 2, into the URI input. Make sure to select ``Enable the common alert schema``. - -.. details:: Why do I see a banner in the UI that "Alerts won't show up"? - :class: warning - - This notification is displayed until the first alert to Robusta. - -Configure Metric Querying -=============================== - -To enable Robusta to pull metrics from Azure Managed Prometheus, see :doc:`/configuration/metric-providers-azure`. diff --git a/docs/configuration/alertmanager-integration/coralogix_managed_prometheus.rst b/docs/configuration/alertmanager-integration/coralogix_managed_prometheus.rst deleted file mode 100644 index d86b016d6..000000000 --- a/docs/configuration/alertmanager-integration/coralogix_managed_prometheus.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Coralogix Alerts -***************** - -This guide shows how to send alerts from Coralogix to Robusta. - -For configuring metric querying from Coralogix Prometheus, see :doc:`/configuration/metric-providers-coralogix`. - -Send Alerts to Robusta -=============================== - -This integration lets you send Coralogix alerts to Robusta. - -You need to create two webhooks: one for firing alerts and one for resolved alerts. - -Common Configuration (for both webhooks) ------------------------------------------ - -1. In the Coralogix site go to Data Flow, then Outbound Webhooks, and click ``Generic webhook``. -2. In the url insert: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/alertmanager - -3. Select the Post Method. -4. In the Edit headers replace it with - -.. code-block:: json - - { - "Content-Type": "application/json", - "Authorization": "Bearer " # where token is ' ' - } - - -Firing Alerts Webhook ---------------------- - -5. Configure this webhook to trigger on **firing** alerts (when alerts are triggered/started). -6. For the firing alerts webhook, in Edit body add: - -.. code-block:: json - - { - "externalURL": "", - "groupKey": "coralogix/alert:${ALERT_ID}", - "version": "1", - "status": "firing", - "receiver": "robusta receiver", - "alerts": [ - { - "status": "firing", - "startsAt": "$EVENT_TIMESTAMP_ISO", - "endsAt": "1970-01-01T00:00:00Z", - "generatorURL": "$ALERT_URL", - "source": "Coralogix", - "description": "$ALERT_DESCRIPTION", - "fingerprint": "$ALERT_UNIQUE_IDENTIFIER", - "annotations": {}, - "labels": { - "cluster_name": "MY_CLUSTER_NAME", # make sure to add your cluster name here for this webhook. Both "cluster" or "cluster_name" labels are also supported - "alertname": "$ALERT_NAME", - "severity": "$EVENT_SEVERITY", - "application": "$APPLICATION_NAME", - "subsystem": "$SUBSYSTEM_NAME", - "team": "$TEAM_NAME", - "alert_url": "$ALERT_URL" - # Add any additional alert specific fields here - # see here for more parameters https://coralogix.com/docs/alert-webhooks/#custom-alert-webhooks - } - } - ] - } - -7. Click the 'Test Config' button and check your robusta sink for a "Test configuration" alert. -8. Click Save - -Resolved Alerts Webhook ------------------------ - -9. Create a second webhook following steps 1-4 above with the same URL and headers. -10. Configure this webhook to trigger on **resolved** alerts (when alerts are resolved/ended). -11. For the resolved alerts webhook, in Edit body add: - -.. code-block:: json - - { - "externalURL": "", - "groupKey": "coralogix/alert:${ALERT_ID}", - "version": "1", - "status": "resolved", - "receiver": "robusta receiver", - "alerts": [ - { - "status": "resolved", - "startsAt": "$EVENT_TIMESTAMP_ISO", - "endsAt": "$EVENT_TIMESTAMP_ISO", - "generatorURL": "$ALERT_URL", - "source": "Coralogix", - "description": "$ALERT_DESCRIPTION", - "fingerprint": "$ALERT_UNIQUE_IDENTIFIER", - "annotations": {}, - "labels": { - "cluster_name": "MY_CLUSTER_NAME", # make sure to add your cluster name here for this webhook. Both "cluster" or "cluster_name" labels are also supported - "alertname": "$ALERT_NAME", - "severity": "$EVENT_SEVERITY", - "application": "$APPLICATION_NAME", - "subsystem": "$SUBSYSTEM_NAME", - "team": "$TEAM_NAME", - "alert_url": "$ALERT_URL" - } - } - ] - } - -12. Click the 'Test Config' button and check your robusta sink for a "Test configuration" alert. -13. Click Save - -.. note:: - Make sure to update the ``cluster_name`` value in both webhook bodies to match your cluster name. Both "cluster" or "cluster_name" labels are also supported. - For more parameters, see `Coralogix alert webhooks documentation `_. - - -Configure Metric Querying -============================== - -To enable Robusta to pull metrics from Coralogix Prometheus, see :doc:`/configuration/metric-providers-coralogix` metrics provider settings. diff --git a/docs/configuration/alertmanager-integration/dynatrace.rst b/docs/configuration/alertmanager-integration/dynatrace.rst deleted file mode 100644 index 8310ef16f..000000000 --- a/docs/configuration/alertmanager-integration/dynatrace.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Dynatrace Integration with Robusta -================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -This guide explains how to forward **Dynatrace problem notifications** to Robusta via a webhook. - -Requirements ------------- - -- Robusta is deployed and running. -- You have access to the Robusta UI (to create an API key and find your ``account_id``). -- You have admin access to the Dynatrace platform (to configure Problem notifications). - -Step 1: Get Robusta Account ID and API Key ------------------------------------------- - -1. In the Robusta UI, go to **Settings β†’ API Keys**. -2. Click **New API Key**, select **Alerts: Write** permissions, and **Save**. -3. Copy the generated API key β€” you will use it as a Bearer token in Dynatrace. -4. Find your ``account_id`` in the Robusta UI under **Settings β†’ General**. - -Step 2: Create a Dynatrace Problems Webhook -------------------------------------------- - -1. In Dynatrace, open the **command palette** (**Cmd+K** on macOS / **Ctrl+K** on Windows/Linux). -2. Search for **problem notification** and open **Problem notifications**. -3. Click **Add notification** and choose **Webhook**. -4. Configure the **URL**: - - :robusta-url:`https://api.robusta.dev/integrations/generic/dynatrace` - -5. Set the **Custom payload** to the Dynatrace macro: - - .. code-block:: text - - {ProblemDetailsJSONv2} - -6. Add the following **HTTP headers**: - - .. code-block:: text - - Authorization: Bearer - account-id: - - Replace ```` with the Robusta API key from Step 1 and ```` with your Robusta account ID. - -7. Save the webhook notification. - diff --git a/docs/configuration/alertmanager-integration/eks-managed-prometheus.rst b/docs/configuration/alertmanager-integration/eks-managed-prometheus.rst deleted file mode 100644 index 6edd7b660..000000000 --- a/docs/configuration/alertmanager-integration/eks-managed-prometheus.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. include:: ../_legacy_banner.rst - -AWS Managed Prometheus Alerts -****************************** - -.. warning:: - - Due to updates in the AWS Managed Prometheus API, these instructions may be outdated. - Please contact our team for support on Slack (https://bit.ly/robusta-slack) or by email (support@robusta.dev). - We're working on updating the documentation. - -AWS Managed Prometheus uses Amazon Managed Grafana for alerting. To send alerts to Robusta, configure your Grafana instance to forward alerts. - -For configuring metric querying from AWS Managed Prometheus, see :doc:`/configuration/metric-providers-aws`. - -Send Alerts to Robusta -====================== - -Since AWS Managed Prometheus doesn't have a built-in AlertManager, you'll need to: - -1. Set up Amazon Managed Grafana with your AMP workspace -2. Configure Grafana alerts to send to Robusta -3. See :doc:`grafana-self-hosted` for detailed Grafana alerting setup - -Configure Metric Querying -========================= - -To enable Robusta to pull metrics from AWS Managed Prometheus, see :doc:`/configuration/metric-providers-aws`. diff --git a/docs/configuration/alertmanager-integration/gcp-monitoring.rst b/docs/configuration/alertmanager-integration/gcp-monitoring.rst deleted file mode 100644 index 629d42c5c..000000000 --- a/docs/configuration/alertmanager-integration/gcp-monitoring.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. include:: ../_legacy_banner.rst - -GCP Cloud Monitoring Integration with Robusta -============================================= - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -.. note:: - Every alert must carry a ``cluster`` or ``cluster_name`` label. Set it to the Robusta ``cluster_name`` configured for the target cluster, or use ``external`` when the alerts do not belong to a specific runner. - -This guide explains how to forward **GCP Cloud Monitoring alerts** to Robusta via a managed notification channel webhook. - -Requirements ------------- - -- Robusta is deployed and running. -- You have access to the Robusta UI (to create an API key and find your ``account_id``). -- You have access to GCP Cloud Monitoring with permissions to create notification channels. - -Step 1: Get Robusta Account ID and API Key ------------------------------------------- - -1. In the Robusta UI, go to **Settings -> API Keys**. -2. Click **New API Key**, select **Alerts: Write** permissions, and **Save**. -3. Copy the generated API key β€” you will use it as the password for basic authentication. -4. Find your ``account_id`` in the Robusta UI under **Settings -> General**. - -Step 2: Create a Webhook Notification Channel in GCP ----------------------------------------------------- - -1. In the GCP Console, navigate to **Monitoring -> Alerting -> Edit Notification Channels**. -2. Under **Webhooks**, click **Add New**. -3. Configure the webhook with the following settings: - - - **Display Name**: ``RobustaWebhook`` - - **Endpoint URL**: :robusta-url:`https://api.robusta.dev/integrations/generic/gcp` - - **Authentication**: Select **Basic Authentication** - - **Username**: Your Robusta ``account_id`` from Step 1 - - **Password**: Your Robusta API key from Step 1 - -4. Click **Save** to create the notification channel. - -Step 3: Use the Webhook in Alerting Policies --------------------------------------------- - -1. Navigate to **Monitoring -> Alerting -> Policies**. -2. Create a new alerting policy or edit an existing one. -3. In the **Notifications** section, select the **RobustaWebhook** notification channel. -4. **Add a cluster label** (required): In the policy's **Documentation** section, add a custom label: - - - **Key**: ``cluster_name`` - - **Value**: Your Robusta cluster name (e.g., ``my-gcp-cluster``) or ``external`` for non-Kubernetes alerts - -5. Save the alerting policy. - -Validation ----------- - -- Trigger a test alert or wait for an existing alerting policy to fire. -- In Robusta's UI, verify the alert appears with the expected details. diff --git a/docs/configuration/alertmanager-integration/google-managed-alertmanager.rst b/docs/configuration/alertmanager-integration/google-managed-alertmanager.rst deleted file mode 100644 index 916a51d97..000000000 --- a/docs/configuration/alertmanager-integration/google-managed-alertmanager.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Google Managed Alertmanager -=========================== - -This guide shows how to forward alerts from Google Managed Prometheus (GMP) managed Alertmanager to Robusta using Robusta's generic Alertmanager webhook. - -.. note:: - - Every alert must carry a ``cluster_name`` label. Set it to the Robusta ``cluster_name`` configured for the target cluster, or use ``external`` when the alerts do not belong to a specific runner. - - For configuring metric querying from Google Managed Prometheus, see :doc:`/configuration/metric-providers-google`. For other Alertmanager integrations, see :doc:`outofcluster-prometheus` or :doc:`alert-manager`. - -Requirements -************ - -- Robusta ``account_id`` and ``signing_key`` from your ``generated_values.yaml`` file. -- A GMP workspace with managed Alertmanager enabled. - -Configure the Alertmanager webhook -********************************** - -Apply the following Secret in the GMP namespace (default ``gmp-public``). Replace ```` and ```` with your credentials. - -.. robusta-code:: yaml - - apiVersion: v1 - kind: Secret - metadata: - name: alertmanager - namespace: gmp-public - type: Opaque - stringData: - alertmanager.yaml: | - receivers: - - name: 'robusta' - webhook_configs: - - url: 'https://api.robusta.dev/integrations/generic/alertmanager' - http_config: - authorization: - # Replace , with your account_id and signing_key - credentials: 'Bearer ' - send_resolved: true - - route: - receiver: 'robusta' - group_by: ['...'] - group_wait: 1s - group_interval: 1s - repeat_interval: 4h - -Ensure alerts include ``cluster_name`` -************************************** - -Use an ``OperatorConfig`` to add external labels to both collection and rule evaluation so every alert contains the required ``cluster_name`` label. - -.. code-block:: yaml - - apiVersion: monitoring.googleapis.com/v1 - kind: OperatorConfig - metadata: - name: config - namespace: gmp-public - collection: - externalLabels: - cluster_name: gmp-demo-cluster # Match your Robusta cluster_name, or use "external" - location: us-central1-c - project_id: my-gcp-project - rules: - externalLabels: - cluster_name: gmp-demo-cluster - location: us-central1-c - project_id: my-gcp-project - -Deploy a demo alert -******************* - -Create a simple alerting rule to confirm delivery to Robusta. - -.. code-block:: yaml - - apiVersion: monitoring.googleapis.com/v1 - kind: Rules - metadata: - name: test-alert - namespace: gmp-public - spec: - groups: - - name: test - interval: 30s - rules: - - alert: TestAlertForGCPAlertmanager - expr: vector(1) - for: 0m - labels: - severity: warning - annotations: - summary: "Test alert to verify Alertmanager webhook" - description: "This is a test alert. Delete the Rules resource to stop it." - -Optional: verify credentials with curl -************************************** - -You can manually validate the webhook and credentials by posting a sample alert: - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/integrations/generic/alertmanager' \ - -H 'Authorization: Bearer ' \ - -H 'Content-Type: application/json' \ - -d '{ - "externalURL": "https://console.cloud.google.com/monitoring", - "groupKey": "gmp/test-alert:gmp-webhook-test-001", - "version": "1", - "status": "firing", - "receiver": "robusta", - "alerts": [ - { - "status": "firing", - "startsAt": "2026-01-13T13:30:50Z", - "endsAt": "1970-01-01T00:00:00Z", - "generatorURL": "https://console.cloud.google.com/monitoring", - "source": "GMP", - "description": "Test alert to verify GMP Alertmanager webhook configuration", - "fingerprint": "gmp-test-alert-12345", - "annotations": { - "summary": "GMP Webhook Test Alert", - "description": "If you see this in Robusta, the webhook URL and credentials are working correctly!" - }, - "labels": { - "cluster_name": "external", - "cluster": "external", - "alertname": "GMP_WebhookTest", - "severity": "warning", - "namespace": "gmp-public", - "source": "gmp-managed-alertmanager" - } - } - ] - }' - -You should see the test alert in Robusta shortly after applying the resources or running the curl command. - diff --git a/docs/configuration/alertmanager-integration/google-managed-prometheus.rst b/docs/configuration/alertmanager-integration/google-managed-prometheus.rst index d3a720802..bd0bca17d 100644 --- a/docs/configuration/alertmanager-integration/google-managed-prometheus.rst +++ b/docs/configuration/alertmanager-integration/google-managed-prometheus.rst @@ -13,7 +13,7 @@ This guide shows how to send alerts from `Google Managed Prometheus `_ For configuring metric querying from Google Managed Prometheus, see :doc:`/configuration/metric-providers-google`. diff --git a/docs/configuration/alertmanager-integration/grafana-cloud.rst b/docs/configuration/alertmanager-integration/grafana-cloud.rst deleted file mode 100644 index 75d05a2a2..000000000 --- a/docs/configuration/alertmanager-integration/grafana-cloud.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Grafana Cloud -************* - -This guide shows how to send alerts from Grafana Cloud's AlertManager to Robusta. - -For configuring metric querying and advanced settings, see :doc:`/configuration/metric-providers-grafana-cloud`. - -Send Alerts to Robusta -======================= - -Configure Grafana Cloud to forward alerts to Robusta: - -1. **Get Your Webhook URL**: - - - Log into the Robusta UI - - Navigate to ``Settings`` > ``Advanced`` - - In the Grafana webhook section, click ``Generate URL`` - - Save the generated webhook URL - -2. **Create Contact Point in Grafana Cloud**: - - - Log into your Grafana Cloud instance - - Go to ``Alerting`` > ``Contact points`` - - Click ``Add contact point`` - - Set **Name**: ``robusta`` - - Set **Integration**: ``Webhook`` - - Set **URL**: Paste the webhook URL from step 1 - - Click ``Test`` to verify connectivity - - Click ``Save contact point`` - -3. **Configure Notification Policy**: - - - Go to ``Alerting`` > ``Notification policies`` - - Edit the default policy or create a new one - - Set the contact point to ``robusta`` - - Save the policy - -.. details:: Why do I see a banner in the UI that "Alerts won't show up"? - :class: warning - - This notification is displayed until the first alert arrives at Robusta. - -Configure Metric Querying -========================== - -To enable Robusta to pull metrics from Grafana Cloud's Mimir, see :doc:`/configuration/metric-providers-grafana-cloud`. diff --git a/docs/configuration/alertmanager-integration/grafana-self-hosted.rst b/docs/configuration/alertmanager-integration/grafana-self-hosted.rst deleted file mode 100644 index 0f9696d21..000000000 --- a/docs/configuration/alertmanager-integration/grafana-self-hosted.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Grafana - Self-Hosted -********************* - -Grafana can send alerts to the Robusta timeline for visualization and AI investigation. - -.. image:: /images/grafana-docs-robusta-ui.png - :width: 600 - :align: center - -.. note:: - - **Using Grafana Cloud?** See the :doc:`Grafana Cloud ` guide. - -Option 1: Send Alerts to Robusta's Timeline -=========================================== - -Send Grafana alerts to Robusta's Timeline for visualization and AI investigation. - -To configure it: - -1. Get your Robusta ``account_id`` from the Robusta UI under **Settings β†’ General**. - -2. Create an ``api key`` - -In the Robusta UI, navigate to the ``settings`` page, and select the ``API Keys`` tab. - -.. image:: /images/robusta-api-keys.png - :width: 600 - :align: center - - -Click ``New API Key``. Select a name for your key, and check the ``Alerts Write`` capability. -Generate and save your new ``API Key`` - -.. image:: /images/new-api-key.png - :width: 600 - :align: center - - -3. In the Grafana UI, navigate to the ``Alerting`` tab, click on ``Manage Contact Points``, and then ``Create contact point``. - -Select ``Webhook`` from the Integration options. -Add the following URL. Add your ``account_id`` to it: - -.. robusta-code:: - - https://api.robusta.dev/integrations/alerts/grafana?account_id=YOUR_ACCOUNT_ID - -.. image:: /images/robusta-contact-point-1.png - :width: 600 - :align: center - -On the ``Optional Webhook settings`` add your ``API Key`` in the ``Bearer Token`` field: - -.. image:: /images/robusta-contact-point-2.png - :width: 600 - :align: center - -Lastly, on the ``Notification settings``, check the ``Send resolved`` checkbox: - -.. image:: /images/grafana-send-resolved.png - :width: 600 - :align: center - -Click the ``Test`` button. If successful, you will receive a notification in the Robusta UI under the ``external`` cluster. - -Save your new ``Contact Point`` - -4. Create a new ``Notification Policy``. Navigate to ``Alerting`` tab, and click ``Manage notification policies`` -Create a new policy. - -Add a policy without matchers, that handles all alerts. Disable grouping, by specifying ``Group By = ...`` - -.. image:: /images/robusta-new-notification-policy.png - :width: 600 - :align: center - - -Save your new ``Notification Policy`` - - -That's it! - -You can now see your Grafana alerts in the Robusta Timeline, and use AI to analyze it. - -Correlating Alerts with Kubernetes Resources ----------------------------------------------- - -To enable Robusta to correlate your Grafana alerts with the specific Kubernetes resources they're related to (pods, deployments, etc.), make sure the ``cluster`` label in your alerts matches ``clusterName`` in Robusta's ``generated_values.yaml``. - -.. note:: - - This is only required for Kubernetes alerts. You can send any alert to the Robusta timeline, including non-Kubernetes alerts. - -Option 2: Inline Alert Enrichment and Routing -============================================== - -Use Robusta to enrich alerts inline with extra context and route them to :doc:`other systems ` (Slack, Microsoft Teams, etc.). Learn more about :doc:`alert routing `. - -This is an alternative to Option 1, where alerts are only sent to Robusta's Timeline without inline enrichment or routing to other destinations. - -To configure it: - -1. In the Grafana UI, navigate to the ``Alerting`` tab, click on ``Add contact point``, and select ``Webhook`` from the Integration options. - -.. image:: /images/grafana-alertmanager-contact-point.png - :width: 600 - :align: center - -2. Insert the following URL: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/alertmanager - -.. image:: /images/grafana-alertmanager-url.png - :align: center - -3. Change the HTTP Method to POST in the ``Optional Webhook Settings``. -4. Enter your `` `` in the ``Authorization Headers - Credentials`` box (locate this in your generated_values.yaml file). - - For example, if ``account_id: f88debc9-68b9-4c2a-e372-e948941518d2`` and ``signing_key: be48413c-e23f-b648-c6b5-773739a377f7``, then use ``f88debc9-68b9-4c2a-e372-e948941518d2 be48413c-e23f-b648-c6b5-773739a377f7`` as the value. - -.. image:: /images/grafana-alertmanager-post.png - :width: 600 - :align: center - -5. Click "Test" button. Select "custom" and add a ``cluster_name`` or ``cluster`` label to send a test alert (Robusta requires that every alert have the ``cluster_name`` or ``cluster`` label). - -.. image:: /images/grafana-alertmanager-test.png - :width: 600 - :align: center - -If successful, you will receive a notification in the Robusta UI, Slack or any other destination configured in Robusta, such as Microsoft Teams. - -.. image:: /images/grafana-alertmanager-robusta-ui.png - :width: 600 - :align: center - -6. Finally, click "Save contact point" to complete the Robusta integration. diff --git a/docs/configuration/alertmanager-integration/launchdarkly.rst b/docs/configuration/alertmanager-integration/launchdarkly.rst deleted file mode 100644 index 22ebf4548..000000000 --- a/docs/configuration/alertmanager-integration/launchdarkly.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. include:: ../_legacy_banner.rst - -LaunchDarkly Integration with Robusta -===================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -This guide explains how to route LaunchDarkly feature flag changes to Robusta's UI via a webhook. - -Requirements ------------- - -- Robusta must already be deployed and running in your environment. -- You have admin access to the Robusta UI (to create API keys and view your ``account_id``). -- You have admin access to LaunchDarkly (to create webhook integrations). - -Integration Steps ------------------ - -We will configure: - -1. A Robusta API key and account ID. -2. A LaunchDarkly **Webhook Integration** pointing to Robusta. -3. Configure the webhook to send feature flag change events. - -Step 1: Get Account ID and API Key -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Obtain your Robusta ``account_id`` and create an API key: - -1. In the Robusta UI, navigate to **Settings β†’ API Keys**. -2. Click **New API Key**. -3. Name the key **LaunchDarkly**, grant it **Read/Write** access to alerts, and click **Generate API Key**. -4. Copy and securely store the generated API key. -5. In **Settings β†’ General**, copy your **account_id**. - -Step 2: Create a Webhook Integration in LaunchDarkly -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In LaunchDarkly: - -1. Go to **Settings β†’ Integrations β†’ Webhook**. -2. Click the **Add integration** button. -3. Configure: - - - **Name**: ``Robusta`` - - **URL**: :robusta-url:`https://api.robusta.dev/integrations/generic/launchdarkly?api_key=YOUR_API_KEY_HERE&account_id=YOUR_ACCOUNT_ID_HERE` - - Replace ``YOUR_API_KEY_HERE`` with the API key from Step 1. - - Replace ``YOUR_ACCOUNT_ID_HERE`` with your account ID from Step 1. - -4. **Statement**: Click the Add the statement button. -5. **Resource type**: Select **FLAG**. -6. **Select flags**: Choose the specific flags you want to monitor, or select all. -7. **Project and environments**: Select the projects and environments you want to track. -8. Save the integration. - -.. Note:: - - Other resource types other than **FLAG** are not verified to work though they might function without additional configuration. - -Alternative: Using Headers Instead of URL Parameters ------------------------------------------------------ - -Including API keys in URLs can expose them in logs, browser history, and monitoring tools. A more secure approach is to send the key in the request headers whenever possible. - -If you’re using a third-party service that supports custom headers, configure the webhook like this: - -- **URL**: :robusta-url:`https://api.robusta.dev/integrations/generic/launchdarkly?account_id=YOUR_ACCOUNT_ID_HERE` -- **Headers**: - - .. code-block:: text - - Authorization: Bearer - - -What Gets Tracked ------------------ - -The integration automatically tracks: - -- **Feature flag changes**: When flags are turned on/off, created, or modified -- **Environment changes**: Changes to flag configurations in specific environments -- **Member actions**: Who made the changes and when -- **Configuration diffs**: Before and after states of flag configurations -- **Approval workflows**: Approval requests and status changes - -Alert Information ------------------ - -Each LaunchDarkly change creates a Robusta alert with: - -- **Title**: Descriptive title showing who made the change and what flag was affected -- **Description**: Detailed information about the change, including member details -- **Labels**: Flag key, environment, action type, and source information -- **Evidence**: - - Configuration diff showing before/after states - - Markdown summary with flag details, project, environment, and reason -- **Fingerprint**: Unique identifier for change aggregation - -Validation ----------- - -1. Make a test change to a feature flag in LaunchDarkly (turn it on/off, modify targeting, etc.). -2. In Robusta's UI, verify the alert appears with: - - Correct flag name and environment - - Member information (who made the change) - - Configuration diff showing the change - - Proper labels and annotations - -Troubleshooting ---------------- - -- **No alerts appearing**: Verify the webhook URL is correct and the API key has proper permissions. -- **Missing member information**: Ensure the LaunchDarkly webhook payload includes member details. -- **Wrong environment**: Check that the correct projects and environments are selected in the LaunchDarkly webhook configuration. -- **Missing configuration diffs**: Ensure the webhook is configured to send both ``previousVersion`` and ``currentVersion`` data. - -For additional support, check the Robusta logs for any LaunchDarkly webhook processing errors. - -Holmes Configuration --------------------- - -To enable Holmes to pull LaunchDarkly changes into the AI assistant, add the following configuration to your ``generated_values.yaml`` file and upgrade the Robusta Helm chart: - -.. code-block:: yaml - - holmes: - additionalEnvVars: - - name: PULL_EXTERNAL_FINDINGS - value: "true" - -After updating the configuration: - -1. Save the ``generated_values.yaml`` file. -2. Run: ``helm upgrade robusta robusta/robusta -f generated_values.yaml`` -3. Restart the Holmes pod to pick up the new environment variable. - -This enables Holmes to access and analyze LaunchDarkly feature flag changes, allowing you to ask questions like: -- "What feature flags were changed recently?" -- "Who modified the authentication flag?" -- "Show me all flag changes in the production environment." diff --git a/docs/configuration/alertmanager-integration/nagios.rst b/docs/configuration/alertmanager-integration/nagios.rst deleted file mode 100644 index 467beedb0..000000000 --- a/docs/configuration/alertmanager-integration/nagios.rst +++ /dev/null @@ -1,224 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Nagios Integration with Robusta -=============================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -This guide explains how to set up Nagios to send alert webhooks to Robusta. - -Requirements ------------- - -- Robusta must already be deployed and running in your environment. -- The Nagios host must be able to send `curl` requests to the Robusta API endpoint: - - .. robusta-code:: - - https://api.robusta.dev/integrations/generic/nagios - - -Integration Steps ------------------ - -We will configure: - -1. A Nagios contact for Robusta. -2. A Bash script to send alerts. -3. Two Nagios commands (for host and service alerts). - -Step 1: Get Account ID and Token -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Obtain your Robusta `account_id` from the Robusta UI under **Settings β†’ General**. - -To generate an API token: - -1. In the Robusta UI, navigate to **Settings β†’ API Keys**. -2. Click **New API Key**. -3. Name the key **Nagios**, grant it **Read/Write** access to alerts, and click **Generate API Key**. -4. Copy and securely store the generated API key β€” you’ll use this as your `api_token`. - - -Step 2: Define the Robusta Contact -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Insert the following contact definition into your Nagios configuration to register Robusta as a notification target. Be sure to replace the placeholders for `_account_id` and `_robusta_api_token` with your actual values. - -.. code-block:: text - - define contact { - contact_name robusta - alias Robusta Webhook - service_notification_period 24x7 - host_notification_period 24x7 - service_notification_options w,u,c,r - host_notification_options d,u,r - service_notification_commands notify-service-by-robusta - host_notification_commands notify-host-by-robusta - _account_id ****** - _robusta_api_token ****** - } - - -Step 3: Add Robusta to a Contact Group -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Ensure Robusta is part of a contact group or explicitly included in your alert definitions: - -.. code-block:: text - - define contactgroup { - contactgroup_name all_contacts - alias Nagios Administrators - members (other contacts listed here),robusta - } - -Step 4: Create the Bash Command Script -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Save this as `notify-robusta.sh`, ensure it's executable (`chmod +x notify-robusta.sh`), and Nagios can access it. - -.. robusta-code:: bash - - #!/bin/sh - - # Usage: - # ./notify-robusta.sh -n host|service -t NOTIFICATIONTYPE \ - # -f key=value -f key=value ... -f account_id=... -f api_token=... - - alert_type="" - notification_type="" - account_id="" - api_token="" - json="" - - while [ "$#" -gt 0 ]; do - case "$1" in - -n) - alert_type="$2" - shift 2 - ;; - -t) - notification_type="$2" - shift 2 - ;; - -f) - kv="$2" - key=$(printf "%s" "$kv" | cut -d'=' -f1) - value=$(printf "%s" "$kv" | cut -d'=' -f2-) - - if [ "$key" = "account_id" ]; then - account_id="$value" - elif [ "$key" = "api_token" ]; then - api_token="$value" - else - esc_key=$(printf "%s" "$key" | sed 's/\\/\\\\/g; s/"/\\"/g') - esc_val=$(printf "%s" "$value" | sed 's/\\/\\\\/g; s/"/\\"/g') - [ -n "$json" ] && json="$json," - json="$json\"$esc_key\":\"$esc_val\"" - fi - shift 2 - ;; - *) - echo "Unknown argument: $1" - exit 1 - ;; - esac - done - - [ -z "$account_id" ] || [ -z "$api_token" ] && { - echo "Missing account_id or api_token" - exit 2 - } - - json="{$json}" - - curl -X POST "https://api.robusta.dev/integrations/generic/nagios" \ - -H "Content-Type: application/json" \ - -H "account-id: $account_id" \ - -H "Authorization: Bearer $api_token" \ - -d "$json" - -Step 5: Define Robusta Notification Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before proceeding, if your Nagios setup monitors multiple clusters, you can optionally set the `cluster_name` variable per host using custom `_cluster_name` properties: - -.. code-block:: text - - define host { - host_name order-management - alias checkout.robusta-payments.com - address 10.100.253.97 - ... - _cluster_name eu-prod-atc-eks - } - - define host { - host_name payment-processor - alias api.robusta-payments.com - address 10.100.183.73 - ... - _cluster_name eu-stg-eks - } - -Now, define the notification commands and replace `PATH_TO_SCRIPT_HERE` with the actual path to your Bash script (`notify-robusta.sh`). - -.. code-block:: text - - define command { - command_name notify-service-by-robusta - command_line PATH_TO_SCRIPT_HERE/notify-robusta.sh \ - -f account_id="$_CONTACTACCOUNT_ID$" \ - -f api_token="$_CONTACTROBUSTA_API_TOKEN$" \ - -f fingerprint="$SERVICEPROBLEMID$" \ - -f notification_type="$NOTIFICATIONTYPE$" \ - -f host="$HOSTNAME$" \ - -f host_display_name="$HOSTDISPLAYNAME$" \ - -f service="$SERVICEDESC$" \ - -f service_display_name="$SERVICEDISPLAYNAME$" \ - -f service_state="$SERVICESTATE$" \ - -f service_output="$SERVICEOUTPUT$" \ - -f service_check_command="$SERVICECHECKCOMMAND$" \ - -f long_datetime="$LONGDATETIME$" \ - -f cluster_name="$_HOSTCLUSTER_NAME$" - } - - define command { - command_name notify-host-by-robusta - command_line PATH_TO_SCRIPT_HERE/notify-robusta.sh \ - -f account_id="$_CONTACTACCOUNT_ID$" \ - -f api_token="$_CONTACTROBUSTA_API_TOKEN$" \ - -f fingerprint="$HOSTPROBLEMID$" \ - -f notification_type="$NOTIFICATIONTYPE$" \ - -f host="$HOSTNAME$" \ - -f host_display_name="$HOSTDISPLAYNAME$" \ - -f host_state="$HOSTSTATE$" \ - -f host_output="$HOSTOUTPUT$" \ - -f host_check_command="$HOSTCHECKCOMMAND$" \ - -f long_datetime="$LONGDATETIME$" \ - -f cluster_name="$_HOSTCLUSTER_NAME$" - } - -Step 6: Add Extra Variables (Optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To include additional data in alerts, use: - -.. code-block:: bash - - -f variable_name="$INTERNAL_VARIABLE_NAME$" - -Example: - -.. code-block:: bash - - -f contact_email="$_CONTACTEMAIL$" - -Restart Nagios to apply your changes: - -.. code-block:: bash - - systemctl restart nagios diff --git a/docs/configuration/alertmanager-integration/newrelic.rst b/docs/configuration/alertmanager-integration/newrelic.rst deleted file mode 100644 index 8c96563ee..000000000 --- a/docs/configuration/alertmanager-integration/newrelic.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. include:: ../_legacy_banner.rst - -New Relic Integration with Robusta -================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -This guide explains how to route New Relic alerts to Robusta's UI via a webhook. - -Requirements ------------- - -- Robusta must already be deployed and running in your environment. -- You have admin access to the Robusta UI (to create API keys and view your ``account_id``). -- You have admin access to New Relic Alerts (to create Destinations and Workflows). - -Integration Steps ------------------ - -We will configure: - -1. A Robusta API key and account ID. -2. A New Relic **Webhook Destination** pointing to Robusta. -3. A New Relic **Workflow** that always sends notifications to Robusta using a custom payload template. - -Step 1: Get Account ID and API Key -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Obtain your Robusta ``account_id`` and create an API key: - -1. In the Robusta UI, navigate to **Settings β†’ API Keys**. -2. Click **New API Key**. -3. Name the key **New Relic**, grant it **Read/Write** access to alerts, and click **Generate API Key**. -4. Copy and securely store the generated API key β€” you’ll use it as a **Bearer token** in New Relic. -5. In **Settings β†’ General**, copy your **account_id**. - -Step 2: Create a Webhook Destination in New Relic -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In New Relic: - -1. Go to **Alerts β†’ Destinations**. -2. Click **New destination** β†’ choose **Webhook**. -3. Configure: - - - **URL**: :robusta-url:`https://api.robusta.dev/integrations/generic/newrelic` - - **Authentication**: **Bearer token** - - **Token**: paste the **Robusta API key** from Step 1. - -4. Save the destination. (Optional) Use **Send test notification** to verify connectivity. - -Step 3: Configure a Workflow to Send Alerts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Go to **Alerts β†’ Workflows**. -2. Use an existing workflow or click **New workflow**. -3. **When**: set to **Always send notifications** (or choose your preferred filter). -4. **Then**: add an **Action β†’ Webhook** and select the **Robusta** destination created in Step 2. -5. **Template**: choose **Custom payload** and paste the JSON template below. -6. Replace ``ACCOUNT_ID_HERE`` with your **account_id** from Step 1. -7. Save and enable the workflow. - -Webhook Payload Template (JSON) -------------------------------- - -Paste this into the **Template** field for the webhook action. Replace ``ACCOUNT_ID_HERE`` with your actual account ID. - -.. code-block:: text - - { - "account_id": "ACCOUNT_ID_HERE", - "title": {{#if annotations}}{{#if annotations.title}}{{ json annotations.title.[0] }}{{else}}"N/A"{{/if}}{{else}}"N/A"{{/if}}, - "description": {{#if annotations}}{{#if annotations.description}}{{ json annotations.description.[0] }}{{else}}{{#if annotations.title}}{{ json annotations.title.[0] }}{{else}}"N/A"{{/if}}{{/if}}{{else}}"N/A"{{/if}}, - "source": "newrelic", - "priority": {{#if priority}}{{ json priority }}{{else if severity}}{{ json severity }}{{else}}null{{/if}}, - "aggregation_key": {{#if accumulations.conditionName}}{{ json accumulations.conditionName.[0] }}{{else}}null{{/if}}, - "starts_at": {{#if createdAt}}{{#timezone createdAt 'UTC'}}{{/timezone}}{{else}}"2025-09-22 00:00:00 UTC"{{/if}}, - "ends_at": {{#eq state "CLOSED"}}{{#if updatedAt}}{{#timezone updatedAt 'UTC'}}{{/timezone}}{{else}}null{{/if}}{{else}}null{{/eq}}, - "cluster": {{#if [latest clusterName]}} - {{ json [latest clusterName] }} - {{else if accumulations}} - {{#if accumulations.tag}} - {{#if accumulations.tag.k8s.clusterName}} - {{ json accumulations.tag.k8s.clusterName.[0] }} - {{else if accumulations.tag.cluster}} - {{ json accumulations.tag.cluster.[0] }} - {{else if tag.k8s.clusterName}} - {{ json tag.k8s.clusterName.[0] }} - {{else}} - "external" - {{/if}} - {{else}} - "external" - {{/if}} - {{else}} - "external" - {{/if}}, - "raw_alert_data": {{ json . }} - } - -Optional: Field Mapping Notes ------------------------------ - -- ``title`` / ``description`` are sourced from ``annotations`` when present, otherwise fall back to ``"N/A"``. -- ``priority`` prefers ``priority`` and falls back to ``severity`` when available. -- ``aggregation_key`` maps to the Alert name to help group similar alerts in Robusta. -- ``starts_at`` / ``ends_at`` are normalized to **UTC** by New Relic templating. -- ``cluster`` attempts multiple common locations for Kubernetes cluster identifiers and defaults to ``"external"``. -- ``raw_alert_data`` includes the full New Relic payload for troubleshooting in Robusta. - -Validation ----------- - -- Trigger a test alert that matches the workflow (or use **Send test notification** on the Destination). -- In Robusta's UI, verify the alert appears with the expected title, description, priority, and cluster. diff --git a/docs/configuration/alertmanager-integration/outofcluster-prometheus.rst b/docs/configuration/alertmanager-integration/outofcluster-prometheus.rst deleted file mode 100644 index fe7713fb7..000000000 --- a/docs/configuration/alertmanager-integration/outofcluster-prometheus.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. include:: ../_legacy_banner.rst - -AlertManager - external -************************ - -Follow this guide to connect Robusta to a central Prometheus (e.g. Thanos/Mimir), running outside the cluster monitored by Robusta. - -.. note:: - - **Using Grafana Cloud?** For Grafana Cloud with Mimir, see the dedicated guide: :doc:`grafana-cloud` - -You will need to configure two integrations: one to send alerts to Robusta and another to let Robusta query metrics and create silences. - -Send Alerts to Robusta -============================== - -This integration lets your central Prometheus send alerts to Robusta, as if they were in the same cluster: - -1. Verify that all alerts contain a label named ``cluster_name`` or ``cluster``, matching the :ref:`cluster_name defined in Robusta's configuration `. This is necessary to identify which robusta-runner should receive alerts. -2. Edit the configuration for your centralized AlertManager: - -.. admonition:: alertmanager.yaml - - .. robusta-code:: yaml - - receivers: - - name: 'robusta' - webhook_configs: - - url: 'https://api.robusta.dev/integrations/generic/alertmanager' - http_config: - authorization: - # Replace with a string in the format ` ` - credentials: - send_resolved: true # (3) - - route: # (1) - routes: - - receiver: 'robusta' - group_by: [ '...' ] - group_wait: 1s - group_interval: 1s - matchers: - - severity =~ ".*" - repeat_interval: 4h - continue: true # (2) - - .. code-annotations:: - 1. Make sure the Robusta ``route`` is the first ``route`` defined. If it isn't the first route, it might not receive alerts. When a ``route`` is matched, the alert will not be sent to following routes, unless the ``route`` is configured with ``continue: true``. - 2. Ensures that alerts continue to be sent even after a match is found - 3. Enables sending resolved alerts to Robusta - -.. include:: ./_testing_integration.rst - -Send Alerts to Robusta with API Key -====================================== - -If you are using a third-party AlertManager and want to give it separate credentials (instead of using the signing key from ``generated_values.yaml``), you can create a dedicated API key in the Robusta UI. - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -1. Verify that all alerts contain a label named ``cluster_name`` or ``cluster``, matching the :ref:`cluster_name defined in Robusta's configuration `. This is necessary to identify which robusta-runner should receive alerts. -2. In the Robusta UI, go to **Settings β†’ API Keys**. -3. Click **New API Key**, select **Alerts: Write** permissions, and **Save**. -4. Copy the generated API key. -5. Find your ``account_id`` in the Robusta UI under **Settings β†’ General**. - -6. Edit the configuration for your AlertManager, using the API key in place of the signing key: - -.. admonition:: alertmanager.yaml - - .. robusta-code:: yaml - - receivers: - - name: 'robusta' - webhook_configs: - - url: 'https://api.robusta.dev/integrations/generic/alertmanager' - http_config: - authorization: - # Replace with your Robusta account ID - # Replace with the API key you created above - credentials: ' ' - send_resolved: true - - route: - routes: - - receiver: 'robusta' - group_by: [ '...' ] - group_wait: 1s - group_interval: 1s - matchers: - - severity =~ ".*" - repeat_interval: 4h - continue: true - -.. include:: ./_testing_integration.rst - -.. include:: ./_pull_integration.rst - -Filtering Prometheus Queries by Cluster -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the same external Prometheus is used for many clusters, you will want to add a cluster name to all queries. - -You can do so with the ``prometheus_url_query_string`` parameter, shown below: - -.. code-block:: yaml - - globalConfig: - # Additional query string parameters to be appended to the Prometheus connection URL (optional) - prometheus_url_query_string: "cluster=prod1&x=y" \ No newline at end of file diff --git a/docs/configuration/alertmanager-integration/pagerduty-alerting.rst b/docs/configuration/alertmanager-integration/pagerduty-alerting.rst deleted file mode 100644 index e296812a4..000000000 --- a/docs/configuration/alertmanager-integration/pagerduty-alerting.rst +++ /dev/null @@ -1,186 +0,0 @@ -.. include:: ../_legacy_banner.rst - -PagerDuty Integration -**************************************** - -PagerDuty can send both incidents and full alert-level data to Robusta for enrichment and resolution tracking. - -This guide explains how to set up both integrations, and how to forward alerts from sources like Alertmanager using PagerDuty AIOps Event Orchestration. - -After completing this tutorial, we recommend confirming that findings appear correctly in the Robusta UI timeline. - -Prerequisite -================================= -* A Robusta account with API access. -* For alert-level forwarding: an AIOps-enabled PagerDuty plan. -* A Robusta cluster name, as defined in your ``generated_values.yaml``. - -Send Incidents to Robusta -============================ - -To send PagerDuty incidents (triggered/resolved) to Robusta: - -Step 1: Create a Robusta API Key ---------------------------------- -1. In the Robusta UI, navigate to **Settings β†’ API Keys**. -2. Click **New API Key**. -3. Name the key ``PagerDuty``, grant it ``Read/Write`` access to alerts, then click **Generate API Key**. -4. Copy and securely save the generated API key. - -Step 2: Get Your Account ID -------------------------------- -1. In the Robusta UI, go to **Settings β†’ General** and copy your ``account_id``. - It will look like: - -.. code-block:: - - account_id: caa68d87-XXXX-XXXX-XXXX-a6514ccb11eb - -Step 3: Create a Webhook in PagerDuty -------------------------------------------- -1. In PagerDuty, go to **Integrations β†’ Generic Webhooks v3**. -2. Click **New Webhook**. - -Step 4: Configure the Webhook ----------------------------------------- -Set the following values: - -* **Webhook URL**: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/pagerduty/incidents - -* **Custom Headers**: - -.. code-block:: - - account-id: - Authorization: Bearer - -Replace the placeholders with values from Step 1 and Step 2. - -Once configured, PagerDuty will begin sending incident-level data to Robusta. These will appear in the Robusta UI timeline. - -Send Alerts to Robusta (AIOps Plans Only) -============================================== - -For Robusta AIOps users, you can send full alert-level data in addition to incidents. - -Step 1: Go to AIOps β†’ Event Orchestration ----------------------------------------------- -1. In PagerDuty, go to **AIOps β†’ Event Orchestration**. -2. Click **New Orchestration** and name it ``Robusta``. - -Forwarding Alerts via Event Orchestration ----------------------------------------------- - -**Recommended for Alertmanager Users** - -If you already use PagerDuty Event Orchestration to forward alerts from systems like Alertmanager, we recommend forwarding those alerts **directly to Robusta**. - -Why this matters -~~~~~~~~~~~~~~~~ -Robusta’s AIOps integration works best when it receives structured alert data directly. Routing alerts through intermediate services or limited integrations may strip important context. - -Step 1: Create an Integration for Alertmanager -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. In Event Orchestration, create a new **Integration** named ``Alertmanager``. -2. Use the following webhook URL: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/pagerduty/alerts - -Step 2: Configure a Service Route -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. At the end of your orchestration rule chain, add a **Service Route**. -2. Route events with the source ``Alertmanager`` to the ``Robusta`` webhook. - -This ensures full alert payloads are delivered directly to Robusta. - -Step 2: Add a New Rule ----------------------------- -1. Under your ``Robusta`` orchestration, add a new rule. -2. For **"When this rule is applied"**, select **Always, for all events**. -3. Click **Next**. - -Step 3: Add a Webhook Action -------------------------------- -1. Under **Automation β†’ Webhook Actions**, enable: - ``Use webhooks if an event reaches this rule``. - -2. Configure the webhook as follows: - -* **Name**: ``Robusta`` - -* **URL**: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/pagerduty/alerts - -* **Headers**: - -.. code-block:: - - account-id: - Authorization: Bearer - -* **Body (key-value pairs)**: - -.. code-block:: json - - { - "custom_details": "{{event.custom_details}}", - "summary": "{{event.summary}}", - "source": "{{event.source}}", - "dedup_key": "{{event.dedup_key}}", - "severity": "{{event.severity}}" - } - -3. Click **Save**. - -Step 4: Route Matching ---------------------------- -In the routing configuration, route it to the service of your choice or you can do it dynamically by setting the route to: - -.. code-block:: - - event.source - -Using this regular expression: - -.. code-block:: - - .* - -This ensures all alert sources are routed properly to their Pagerduty Services. - -Verify it Works -============================= - -To confirm the integration: - -* Trigger an alert from Alertmanager, Nagios, or another connected system. -* Check that the alert appears in the Robusta UI timeline under the correct cluster. -* Confirm the incident is routed to the correct Service in Pagerduty. - -Optional: Cluster Name via Query Param -============================================ - -You can specify the target cluster using a query parameter in the webhook URL: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/pagerduty/incidents?cluster=your-cluster-name - -This is useful for multi-cluster setups where Robusta should assign findings to a specific cluster. - -For example: - -.. robusta-code:: - - https://api.robusta.dev/integrations/generic/pagerduty/incidents?cluster=test-cluster - -This will create findings in ``test-cluster``. \ No newline at end of file diff --git a/docs/configuration/alertmanager-integration/solarwinds.rst b/docs/configuration/alertmanager-integration/solarwinds.rst deleted file mode 100644 index bba8a9931..000000000 --- a/docs/configuration/alertmanager-integration/solarwinds.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. include:: ../_legacy_banner.rst - -SolarWinds Integration with Robusta -=================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -This guide explains how to configure SolarWinds to send alert webhooks directly to Robusta. - -Requirements ------------- - -- Robusta must already be deployed and running in your environment. -- You must have access to the SolarWinds web interface with permission to manage webhooks and alert actions. - -Step 1: Get Your Account ID ---------------------------- - -You can find your Robusta `account_id` in the Robusta UI under **Settings β†’ General**. - -Step 2: Generate an API Token ------------------------------ - -1. In the Robusta UI, go to **Settings β†’ API Keys**. -2. Click **New API Key**. -3. Name the key **SolarWinds**, grant it **Read/Write** access to alerts, and click **Generate API Key**. -4. Copy and securely store the generated API key β€” this will be your `ROBUSTA_API_TOKEN`. - -Step 3: Create a Webhook Configuration in SolarWinds ------------------------------------------------------ - -1. In the SolarWinds UI, go to **Settings β†’ All Settings β†’ Notification Services β†’ Webhook**. -2. Click **Create Configuration**. -3. Fill in the form: - - **Name**: Robusta - - **Description**: Robusta Webhook - - **Destination URL**: - - .. robusta-code:: - - https://api.robusta.dev/integrations/generic/solarwinds?account_id=ACCOUNT_ID_HERE - - - Replace `ACCOUNT_ID_HERE` with your actual Robusta account ID. - -4. Click **Advanced Settings** to expand the section. -5. Under **Authentication**: - - Select **Token**. - - **Header**: `Authorization` - - **Value**: `Bearer ROBUSTA_API_TOKEN` - - Replace `ROBUSTA_API_TOKEN` with your real API token. - -6. Click **Save**. - -Step 4: Attach Webhook to Alerts --------------------------------- - -You must now configure each alert you want to send to Robusta: - -1. Navigate to **Alerts β†’ Alerts Settings**. -2. For each alert you want to integrate: - - Click **Edit**. - - Go to the **Actions** tab. - - Click **Add Action**. - - Select **Webhook** as the action type. - - For the webhook configuration, choose **Robusta**. - - Set **Resend notification frequency** to **1 hour** (optional but recommended). - - Toggle **Send additional notification when cleared** to **ON** (this ensures Robusta receives both firing and resolved states). -3. Save the alert. - -You should now begin seeing alerts appear in the Robusta UI when they are triggered in SolarWinds. - -.. note:: - - The Robusta SolarWinds API integration supports the following alert types: - - - Metric Group Alerts - - Events Alerts - - Logs Alerts - - Entity Alerts - - Other alert types might be supported but are not guaranteed. \ No newline at end of file diff --git a/docs/configuration/exporting/alert-export-api.rst b/docs/configuration/exporting/alert-export-api.rst deleted file mode 100644 index ade78debe..000000000 --- a/docs/configuration/exporting/alert-export-api.rst +++ /dev/null @@ -1,163 +0,0 @@ -Alert Export API -============================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to export alert history data. You can filter the results based on specific criteria using query parameters such as ``alert_name``, ``account_id``, and time range. - -.. _alert-export-api: - -GET https://api.robusta.dev/api/query/alerts ------------------------------------------------------- - -Query Parameters -^^^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 20 10 70 10 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier (found in the Robusta UI under **Settings** -> **General**). - - Yes - * - ``start_ts`` - - string - - Start timestamp for the alert history query (in ISO 8601 format, e.g., ``2024-09-02T04:02:05.032Z``). - - Yes - * - ``end_ts`` - - string - - End timestamp for the alert history query (in ISO 8601 format, e.g., ``2024-09-17T05:02:05.032Z``). - - Yes - * - ``alert_name`` - - string - - The name of the alert to filter by (e.g., ``CrashLoopBackoff``). - - No - * - ``namespace`` - - string - - The namespace of the alert to filter by (e.g., ``monitoring``). - - No - -Example Request -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following ``curl`` command demonstrates how to export alert history data for the ``CrashLoopBackoff`` alert: - -.. robusta-code:: bash - - curl --location 'https://api.robusta.dev/api/query/alerts?alert_name=CrashLoopBackoff&account_id=ACCOUNT_ID&start_ts=2024-09-02T04%3A02%3A05.032Z&end_ts=2024-09-17T05%3A02%3A05.032Z' \ - --header 'Authorization: Bearer API-KEY' - -In the command, make sure to replace the following placeholders: - -- ``ACCOUNT_ID``: Your account ID, which can be found in the Robusta UI under **Settings** -> **General**. -- ``API-KEY``: Your API Key for authentication. You can generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Read Alerts" permission. - -Request Headers -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have "Read Alerts" permission. - -Response Format -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The API will return a list of alerts in JSON format. Each alert object contains detailed information about the alert, including the name, priority, source, and related resource information. - -Example Response -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: json - - [ - { - "alert_name": "CrashLoopBackoff", - "title": "Crashing pod api-gateway-123abc in namespace prod", - "description": null, - "source": "kubernetes_api_server", - "priority": "HIGH", - "started_at": "2024-09-03T04:09:31.342818+00:00", - "resolved_at": null, - "cluster": "prod-cluster-1", - "namespace": "prod", - "app": "api-gateway", - "kind": null, - "resource_name": "api-gateway-123abc", - "resource_node": "gke-prod-cluster-1-node-1" - }, - { - "alert_name": "CrashLoopBackoff", - "title": "Crashing pod billing-service-xyz789 in namespace billing", - "description": null, - "source": "kubernetes_api_server", - "priority": "HIGH", - "started_at": "2024-09-03T04:09:31.496713+00:00", - "resolved_at": null, - "cluster": "prod-cluster-2", - "namespace": "billing", - "app": "billing-service", - "kind": null, - "resource_name": "billing-service-xyz789", - "resource_node": "gke-prod-cluster-2-node-3" - } - ] - -Response Fields -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 25 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``alert_name`` - - string - - Name of the alert (e.g., ``CrashLoopBackoff``). - * - ``title`` - - string - - A brief description of the alert event. - * - ``source`` - - string - - Source of the alert (e.g., ``kubernetes_api_server``). - * - ``priority`` - - string - - Priority level of the alert (e.g., ``HIGH``). - * - ``started_at`` - - string - - Timestamp when the alert was triggered, in ISO 8601 format. - * - ``resolved_at`` - - string - - Timestamp when the alert was resolved, or ``null`` if still unresolved. - * - ``cluster`` - - string - - The cluster where the alert originated. - * - ``namespace`` - - string - - Namespace where the alert occurred. - * - ``app`` - - string - - The application that triggered the alert. - * - ``resource_name`` - - string - - Name of the resource that caused the alert. - * - ``resource_node`` - - string - - The node where the resource is located. - -Quick Start Example -^^^^^^^^^^^^^^^^^^^ - -There is a quick-start `Prometheus report-generator `_ on GitHub that demonstrates how to use the export APIs. \ No newline at end of file diff --git a/docs/configuration/exporting/alert-statistics-api.rst b/docs/configuration/exporting/alert-statistics-api.rst deleted file mode 100644 index b2fcfdbe1..000000000 --- a/docs/configuration/exporting/alert-statistics-api.rst +++ /dev/null @@ -1,132 +0,0 @@ -Alert Statistics API -============================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to retrieve aggregated alert data, including the count of each type of alert during a specified time range. Filters can be applied using query parameters such as `account_id` and the time range. - -.. _alert-reporting-api: - -GET https://api.robusta.dev/api/query/report ------------------------------------------------------------- - -Query Parameters -^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 20 10 70 10 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier (found in the Robusta UI under **Settings** -> **General**). - - Yes - * - ``start_ts`` - - string - - Start timestamp for the query (in ISO 8601 format, e.g., ``2024-10-27T04:02:05.032Z``). - - Yes - * - ``end_ts`` - - string - - End timestamp for the query (in ISO 8601 format, e.g., ``2024-11-27T05:02:05.032Z``). - - Yes - - -Example Request -^^^^^^^^^^^^^^^^^^^^^^^ - -The following `curl` command demonstrates how to query aggregated alert data for a specified time range: - -.. robusta-code:: bash - - curl --location 'https://api.robusta.dev/api/query/report?account_id=XXXXXX-XXXX_XXXX_XXXXX7&start_ts=2024-10-27T04:02:05.032Z&end_ts=2024-11-27T05:02:05.032Z' \ - --header 'Authorization: Bearer API-KEY' - - -In the command, make sure to replace the following placeholders: - -- `account_id`: Your account ID, which can be found in the Robusta UI under **Settings** -> **General**. -- `API-KEY`: Your API Key for authentication. Generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Read Alerts" permission. - - - -Request Headers -^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have "Read Alerts" permission. - -Response Format -^^^^^^^^^^^^^^^^^^^^ - -The API will return a JSON array of aggregated alerts, with each object containing: - -- **`aggregation_key`**: The unique identifier of the alert type (e.g., `KubeJobFailed`). -- **`alert_count`**: The total count of occurrences of this alert type within the specified time range. - -Example Response -^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: json - - [ - {"aggregation_key": "KubeJobFailed", "alert_count": 17413}, - {"aggregation_key": "KubePodNotReady", "alert_count": 11893}, - {"aggregation_key": "KubeDeploymentReplicasMismatch", "alert_count": 2410}, - {"aggregation_key": "KubeDeploymentRolloutStuck", "alert_count": 923}, - {"aggregation_key": "KubePodCrashLooping", "alert_count": 921}, - {"aggregation_key": "KubeContainerWaiting", "alert_count": 752}, - {"aggregation_key": "PrometheusRuleFailures", "alert_count": 188}, - {"aggregation_key": "KubeMemoryOvercommit", "alert_count": 187}, - {"aggregation_key": "PrometheusOperatorRejectedResources", "alert_count": 102}, - {"aggregation_key": "KubeletTooManyPods", "alert_count": 94}, - {"aggregation_key": "NodeMemoryHighUtilization", "alert_count": 23}, - {"aggregation_key": "TargetDown", "alert_count": 19}, - {"aggregation_key": "test123", "alert_count": 7}, - {"aggregation_key": "KubeAggregatedAPIDown", "alert_count": 4}, - {"aggregation_key": "KubeAggregatedAPIErrors", "alert_count": 4}, - {"aggregation_key": "KubeMemoryOvercommitTEST2", "alert_count": 1}, - {"aggregation_key": "TestAlert", "alert_count": 1}, - {"aggregation_key": "TestAlert2", "alert_count": 1}, - {"aggregation_key": "dsafd", "alert_count": 1}, - {"aggregation_key": "KubeMemoryOvercommitTEST", "alert_count": 1}, - {"aggregation_key": "vfd", "alert_count": 1} - ] - - - -Response Fields -^^^^^^^^^^^^^^^^^^^^ -.. list-table:: - :widths: 25 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``aggregation_key`` - - string - - The unique key representing the type of alert (e.g., ``KubeJobFailed``). - * - ``alert_count`` - - integer - - The number of times this alert occurred within the specified time range. - -Notes -^^^^^^^^^^^^^^^ - -- Ensure that the `start_ts` and `end_ts` parameters are in ISO 8601 format and are correctly set to cover the desired time range. -- Use the correct `Authorization` token with sufficient permissions to access the alert data. - -Quick Start Example -^^^^^^^^^^^^^^^^^^^ - -There is a quick-start `Prometheus report-generator `_ on GitHub that demonstrates how to use the export APIs. \ No newline at end of file diff --git a/docs/configuration/exporting/configuration-changes-api.rst b/docs/configuration/exporting/configuration-changes-api.rst deleted file mode 100644 index f8958e8d2..000000000 --- a/docs/configuration/exporting/configuration-changes-api.rst +++ /dev/null @@ -1,192 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Configuration Changes API -============================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to send configuration changes to Robusta. You can send up to 1000 configuration changes in a single request. - -.. _send-configuration-changes-api: - -POST https://api.robusta.dev/api/config-changes --------------------------------------------------------------------- - -Request Body Schema -^^^^^^^^^^^^^^^^^^^ - -The request body must include the following fields: - -.. list-table:: - :widths: 25 10 70 10 - :header-rows: 1 - - * - Field - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier. - - Yes - * - ``config_changes`` - - list - - A list of configuration changes. - - Yes - -Configuration Change Schema -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each configuration change in the ``config_changes`` list must follow the specific schema, which includes the following fields: - -.. list-table:: - :widths: 25 10 70 10 - :header-rows: 1 - - * - Field - - Type - - Description - - Required - * - ``title`` - - string - - A short description of the configuration change. - - Yes - * - ``old_config`` - - string - - The previous configuration value. - - Yes - * - ``new_config`` - - string - - The new configuration value. - - Yes - * - ``resource_name`` - - string - - The name of the resource affected by the configuration change. - - Yes - * - ``description`` - - string - - A detailed description of the configuration change (optional). - - No - * - ``source`` - - string - - The source of the configuration change (default: ``external``). - - No - * - ``cluster`` - - string - - The cluster where the configuration change occurred (default: ``external``). - - No - * - ``labels`` - - dict - - Extra labels for the alert (optional). - - No - * - ``annotations`` - - dict - - Extra annotations for the configuration change (optional). - - No - * - ``subject_name`` - - string - - The name of the subject related to the configuration change (optional). - - No - * - ``subject_namespace`` - - string - - The namespace of the subject related to the configuration change (optional). - - No - * - ``subject_node`` - - string - - The node where the subject related to the configuration change is located (optional). - - No - * - ``subject_type`` - - string - - The type of subject related to the configuration change (optional). - - No - * - ``service_key`` - - string - - A key identifying the service related to the configuration change (optional). - - No - * - ``fingerprint`` - - string - - A unique identifier for the configuration change (optional). - - No - -Example Request -^^^^^^^^^^^^^^^^^^^^ - -Here is an example of a ``POST`` request to send a list of configuration changes: - -.. robusta-code:: bash - - curl --location --request POST 'https://api.robusta.dev/api/config-changes' \ - --header 'Authorization: Bearer API-KEY' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "account_id": "ACCOUNT_ID", - "config_changes": [ - { - "title": "Updated test-service deployment", - "old_config": "apiVersion: apps/v1\nkind: Deployment\n....", - "new_config": "apiVersion: apps/v1...", - "resource_name": "test sercvice", - "description": "Changed deployemnt", - "source": "test-service", - "cluster": "prod-cluster-1", - "labels": { - "environment": "production" - }, - "annotations": { - "env1": "true" - }, - "subject_namespace": "prod", - "subject_node": "gke-prod-cluster-1-node-1" - } - ] - }' - -In this request, replace the following placeholders: - -- ``ACCOUNT_ID``: Your account ID, which can be found in the Robusta UI under **Settings** -> **General**. -- ``API-KEY``: Your API Key for authentication. You can generate this token by navigating to **Settings** -> **API Keys** -> **New API Key**. - -Request Headers -^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have the necessary permissions to submit configuration changes. - * - ``Content-Type`` - - Must be set to ``application/json``. - -Response Format -^^^^^^^^^^^^^^^^^^^^ - -Success Response -"""""""""""""""" - -If the request is successful, the API will return the following response: - -.. code-block:: json - - { - "success": true - } - -- **Status Code**: `200 OK` - -Error Response -"""""""""""""" - -If there is an error in processing the request, the API will return the following format: - -.. code-block:: json - - { - "msg": "Error message here", - "error_code": 123 - } - -- **Status Code**: Varies based on the error (e.g., `400 Bad Request`, `500 Internal Server Error`). \ No newline at end of file diff --git a/docs/configuration/exporting/custom-webhooks.rst b/docs/configuration/exporting/custom-webhooks.rst deleted file mode 100644 index 74ba9df7d..000000000 --- a/docs/configuration/exporting/custom-webhooks.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Custom Webhooks -=============== - -Send alerts from any monitoring system to Robusta via HTTP webhooks. - -.. note:: - This feature requires Robusta Pro (SaaS or self-hosted commercial plans). - -Overview --------- - -Forward alerts from any system that can send HTTP POST requests. Robusta will automatically enrich these alerts with Kubernetes context and apply your automation rules. - -Webhook Endpoint ----------------- - -Send alerts to Robusta using the following endpoint: - -.. robusta-code:: bash - - POST https://api.robusta.dev/api/alerts - -Authentication --------------- - -You'll need your API key and account ID: - -1. **Account ID**: Found in the Robusta platform under **Settings** β†’ **General** -2. **API Key**: Generate this in the Robusta platform under **Settings** β†’ **API Keys** β†’ **New API Key** - -For detailed API documentation including request format, authentication, and examples, see :doc:`Send Alerts API `. - -Quick Example -------------- - -Here's a simple example of sending a custom alert: - -.. robusta-code:: bash - - curl --location --request POST 'https://api.robusta.dev/api/alerts' \ - --header 'Authorization: Bearer YOUR_API_KEY' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "account_id": "YOUR_ACCOUNT_ID", - "alerts": [ - { - "title": "Test Service Down", - "description": "The Test Service is not responding.", - "source": "monitoring-system", - "priority": "high", - "aggregation_key": "test-service-issues" - } - ] - }' - -Next Steps ----------- - -For complete API documentation including all available fields and response formats, see :doc:`Send Alerts API `. \ No newline at end of file diff --git a/docs/configuration/exporting/llm-models-api.rst b/docs/configuration/exporting/llm-models-api.rst deleted file mode 100644 index bd368385a..000000000 --- a/docs/configuration/exporting/llm-models-api.rst +++ /dev/null @@ -1,117 +0,0 @@ -LLM Models API -============== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to list the Robusta-hosted LLM models available to your account, along with the account's default model. This is useful if you are building a tool that lets a user pick a model, or that needs to know which model Holmes will use by default. - -.. _llm-models-api: - -POST https://api.robusta.dev/api/llm/models ---------------------------------------------- - -Request Body -^^^^^^^^^^^^ - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier (found in the Robusta UI under **Settings** -> **General**). - - Yes - * - ``session_token`` - - string - - Unused for API key authentication; pass an empty string. - - Yes - -Authentication -^^^^^^^^^^^^^^ - -Send your Robusta API key as a Bearer token: - -.. code-block:: - - Authorization: Bearer - -The key must have the "Robusta AI" resource with "Write" permission. You can generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Robusta AI" resource and "Write" permission. - -Example Request -^^^^^^^^^^^^^^^ - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/llm/models' \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer API-KEY' \ - --data '{ - "account_id": "ACCOUNT_ID", - "session_token": "" - }' - -Example Response -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "models": ["claude-sonnet-4-5", "gpt-5.4"], - "models_holmes_args": {}, - "default_model": "claude-sonnet-4-5" - } - -Response Fields -^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 25 15 60 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``models`` - - array - - Robusta-hosted model names available to the account. - * - ``models_holmes_args`` - - object - - Per-model arguments Holmes needs to invoke each listed model. - * - ``default_model`` - - string - - The account's fallback Robusta-hosted model β€” used when a requested model is unavailable. Not necessarily the account's overall default, which may be a model defined on a connected agent instead of a Robusta-hosted one. - -Error Responses -^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 15 30 55 - :header-rows: 1 - - * - Status - - Error - - Description - * - 401 - - Unauthorized - - Invalid or missing API key. - * - 403 - - Forbidden - - API key lacks required "Robusta AI: Write" permission. - * - 503 - - Service Unavailable - - LLM registry is not configured, or account model settings are unavailable. - -Other Versions -^^^^^^^^^^^^^^ - -``/api/llm/models/v2`` and ``/api/llm/models/v3`` use the same authentication and request body, and return a more detailed per-model payload (a model-name-keyed object rather than a flat list, plus the account's model preferences on ``v3``). They power the Robusta Platform's own model-picker UI; most integrations should use ``/api/llm/models`` above. - -See Also --------- - -* :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>` β€” the ``model`` field on a chat request accepts any model name returned here. diff --git a/docs/configuration/exporting/namespace-resources-api.rst b/docs/configuration/exporting/namespace-resources-api.rst deleted file mode 100644 index 61f9c06e2..000000000 --- a/docs/configuration/exporting/namespace-resources-api.rst +++ /dev/null @@ -1,140 +0,0 @@ -Namespace Resources API -============================================== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to retrieve an **active count of specific Kubernetes resources** within a namespace. This is the same data displayed in the **Namespaces** tab of the Robusta UI. - -You can specify exactly which resource kinds you want to query in the request. - -.. _namespaces-resources-api: - -POST https://api.robusta.dev/api/namespaces/resources ------------------------------------------------------- - -Prerequisites -^^^^^^^^^^^^^ - -This API relies on resource types configured in the Robusta UI sink. -Make sure to configure all the individual resources you need as described in :ref:`cb-robusta-ui-sink-namespace-config`. - -Request Body Schema -^^^^^^^^^^^^^^^^^^^ - -The request body must include the following fields: - -.. list-table:: - :widths: 25 10 70 10 - :header-rows: 1 - - * - Field - - Type - - Description - - Required - * - ``namespace`` - - string - - The name of the namespace you want to inspect. - - Yes - * - ``account_id`` - - string - - The unique account identifier. - - Yes - * - ``cluster_name`` - - string - - The name of the cluster where the namespace resides. - - Yes - * - ``resources`` - - list - - A list of resource types to count, each including ``kind``, ``apiGroup``, and ``apiVersion``. - - Yes - -Resource Schema -^^^^^^^^^^^^^^^ - -Each item in the ``resources`` list must include: - -* ``kind`` (e.g., `Deployments`) -* ``apiGroup`` (e.g., `apps`, or empty string for core group) -* ``apiVersion`` (e.g., `v1`, `v2`) - -Example Request -^^^^^^^^^^^^^^^^^^^^ - -Here is an example of a ``POST`` request to query the resource count in a namespace: - -.. robusta-code:: bash - - curl --location 'https://api.robusta.dev/api/namespaces/resources' \ - --header 'Authorization: Bearer API-KEY-HERE' \ - --header 'Content-Type: application/json' \ - --data '{ - "namespace": "your-namespace", - "account_id": "your-account-id", - "cluster_name": "your-cluster-name", - "resources": [ - {"kind": "Deployments", "apiGroup": "apps", "apiVersion": "v1"}, - {"kind": "Services", "apiGroup": "", "apiVersion": "v1"}, - {"kind": "Ingresses", "apiGroup": "networking.k8s.io", "apiVersion": "v1"}, - {"kind": "CronJobs", "apiGroup": "batch", "apiVersion": "v1"} - ] - }' - -Replace: - -- ``API-KEY-HERE`` with your API Key from **Settings β†’ API Keys β†’ New API Key**. - Make sure the key has **Clusters β†’ Read** permissions to access namespace resource data. -- ``your-account-id`` with the ID found in the Robusta UI under **Settings β†’ General** -- ``your-cluster-name`` and ``your-namespace`` accordingly - -Response Format -^^^^^^^^^^^^^^^^^^^^ - -Success Response -"""""""""""""""" - -If the request is successful, the API returns the following structure: - -.. code-block:: text - - { - "cluster": "your-cluster-name", - "namespace": "your-namespace", - "resources": [ - { - "apiGroup": "apps", - "apiVersion": "v1", - "count": 2, - "kind": "Deployments" - }, - { - "apiGroup": "", - "apiVersion": "v1", - "count": 3, - "kind": "Services" - }, - { - "apiGroup": "networking.k8s.io", - "apiVersion": "v1", - "count": 1, - "kind": "Ingresses" - }, - ... - ] - } - -- **Status Code**: `200 OK` - -Error Response -"""""""""""""" - -If an error occurs, you will receive a response in the following format: - -.. code-block:: json - - { - "msg": "Error message here", - "error_code": 456 - } - -- **Status Code**: Varies depending on the error (e.g., `400`, `403`, `500`) \ No newline at end of file diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst deleted file mode 100644 index d6fdbd8e9..000000000 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ /dev/null @@ -1,142 +0,0 @@ -Platform MCP API -================= - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Robusta exposes a `Model Context Protocol (MCP) `_ server that lets any MCP client β€” Claude Code, Claude Desktop, or your own agent β€” run cross-cluster investigation tools against every cluster connected to your account. - -.. _platform-mcp-api: - -POST https://api.robusta.dev/api/platform-mcp ------------------------------------------------ - -A standard MCP `Streamable HTTP `_ endpoint. It accepts the usual MCP JSON-RPC methods (``initialize``, ``tools/list``, ``tools/call``) as a single request or a batch. - -Enabling external access -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Cross-cluster tool calls from an external MCP client are opt-in per account. Turn on **Robusta MCP Server Enabled** under **Settings β†’ AI Assistant β†’ MCP Server Settings** before an API key can list or call any ``remote_*`` tool. It is off by default. - -Authentication -^^^^^^^^^^^^^^ - -Send your Robusta API key as a Bearer token, with your account ID as the first word: - -.. code-block:: - - Authorization: Bearer - -The key must have the **Robusta AI: Write** permission. You can generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Robusta AI" resource and "Write" permission. - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Authorization`` - - ``Bearer ``. The account ID and key are both required; there is no separate account ID parameter. - -Example Request -^^^^^^^^^^^^^^^ - -A real MCP client opens every session with the standard ``initialize`` / ``notifications/initialized`` handshake before calling any tool method. The endpoint itself is stateless β€” it does not issue or check a session ID between requests β€” but showing the full sequence here keeps this example valid input for any spec-compliant MCP client, not just this server. - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/platform-mcp' \ - --header 'Content-Type: application/json' \ - --header 'Accept: application/json, text/event-stream' \ - --header 'MCP-Protocol-Version: 2025-03-26' \ - --header 'Authorization: Bearer ACCOUNT_ID API-KEY' \ - --data '{ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "example-client", "version": "1.0.0"} - } - }' - - curl -X POST 'https://api.robusta.dev/api/platform-mcp' \ - --header 'Content-Type: application/json' \ - --header 'Accept: application/json, text/event-stream' \ - --header 'MCP-Protocol-Version: 2025-03-26' \ - --header 'Authorization: Bearer ACCOUNT_ID API-KEY' \ - --data '{ - "jsonrpc": "2.0", - "method": "notifications/initialized" - }' - - curl -X POST 'https://api.robusta.dev/api/platform-mcp' \ - --header 'Content-Type: application/json' \ - --header 'Accept: application/json, text/event-stream' \ - --header 'MCP-Protocol-Version: 2025-03-26' \ - --header 'Authorization: Bearer ACCOUNT_ID API-KEY' \ - --data '{ - "jsonrpc": "2.0", - "id": 2, - "method": "tools/list" - }' - -MCP client configuration -^^^^^^^^^^^^^^^^^^^^^^^^^ - -For Claude Code: - -.. robusta-code:: bash - - claude mcp add --transport http robusta-platform \ - "https://api.robusta.dev/api/platform-mcp" \ - --header "Authorization: Bearer ACCOUNT_ID API-KEY" - -For Claude Desktop or any generic MCP client (``mcp.json``): - -.. code-block:: json - - { - "mcpServers": { - "robusta-platform": { - "type": "http", - "url": "https://api.robusta.dev/api/platform-mcp", - "headers": { - "Authorization": "Bearer ACCOUNT_ID API-KEY" - } - } - } - } - -What an API key can call -^^^^^^^^^^^^^^^^^^^^^^^^^ - -An API key is treated as an external caller and can only reach the cross-cluster ``remote_*`` tools (for example, listing available clusters and dispatching a tool call to one of them). It cannot call the static Slack, Teams, or incident-triage tools β€” those are reserved for Holmes' own internal use of this endpoint. - -Calls run with the RBAC of the user who created the API key, not as an account-wide superuser: a key only reaches the clusters and namespaces its owner can already access. Deleting or demoting that user's access also narrows what the key can do. - -Rate limits and errors -^^^^^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 15 30 55 - :header-rows: 1 - - * - Status - - Error - - Description - * - 401 - - Unauthorized - - Missing/malformed ``Authorization`` header, invalid API key, or the key lacks the "Robusta AI: Write" capability. - * - 429 - - Too Many Requests - - Rate limit exceeded. Each actual tool call (not ``initialize``/``tools/list``) consumes one request against the limit; the response includes a ``Retry-After`` header. - * - 500 - - Internal Server Error - - Unhandled error while processing the request. - -See Also --------- - -* :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>` β€” for a single-turn "ask Holmes a question" REST API instead of a full MCP tool session. diff --git a/docs/configuration/exporting/prometheus-query-api.rst b/docs/configuration/exporting/prometheus-query-api.rst deleted file mode 100644 index 10494e97d..000000000 --- a/docs/configuration/exporting/prometheus-query-api.rst +++ /dev/null @@ -1,205 +0,0 @@ -Prometheus Query API -==================== - -.. note:: - - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. - It is not available in the open-source version. - -The Prometheus Query API allows you to run PromQL queries against the Prometheus instance -in your connected clusters. - -Endpoint --------- - -.. robusta-code:: - - POST https://api.robusta.dev/api/accounts/{account_id}/clusters/{cluster_name}/prometheus/query - -Path Parameters ---------------- - -.. list-table:: - :header-rows: 1 - :widths: 20 10 70 - - * - Parameter - - Required - - Description - * - account_id - - Yes - - Your Robusta account ID (found in the Robusta UI under **Settings** -> **General**) - * - cluster_name - - Yes - - The name of the cluster to query (as shown in the Robusta UI) - -Request Body ------------- - -.. list-table:: - :header-rows: 1 - :widths: 20 10 15 55 - - * - Field - - Required - - Default - - Description - * - promql_query - - Yes - - - - The PromQL query to execute - * - duration_minutes - - No - - 60 - - Time range in minutes (looking back from now) - * - starts_at - - No - - - - Start time for date range queries (format: ``YYYY-MM-DD HH:MM:SS UTC``) - * - ends_at - - No - - - - End time for date range queries (format: ``YYYY-MM-DD HH:MM:SS UTC``) - * - step - - No - - 1m - - Query resolution step (e.g., ``30s``, ``1m``, ``5m``) - -.. note:: - - You can specify either ``duration_minutes`` OR both ``starts_at`` and ``ends_at``, but not both. - If neither is specified, ``duration_minutes`` defaults to 60. - -Authentication --------------- - -Include an API key in the Authorization header: - -.. code-block:: - - Authorization: Bearer - -The API key must have **Read Metrics** permission. You can generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Read Metrics" permission. - -Example Request ---------------- - -Using duration (last 5 minutes): - -.. robusta-code:: bash - - curl -X POST "https://api.robusta.dev/api/accounts/ACCOUNT_ID/clusters/CLUSTER_NAME/prometheus/query" \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "promql_query": "up", - "duration_minutes": 5, - "step": "1m" - }' - -Using date range: - -.. robusta-code:: bash - - curl -X POST "https://api.robusta.dev/api/accounts/ACCOUNT_ID/clusters/CLUSTER_NAME/prometheus/query" \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "promql_query": "kube_resourcequota{type=\"hard\"}", - "starts_at": "2024-01-27 10:00:00 UTC", - "ends_at": "2024-01-27 11:00:00 UTC", - "step": "1m" - }' - -Replace ``ACCOUNT_ID``, ``CLUSTER_NAME``, and ``YOUR_API_KEY`` with your actual values. - -Response Format ---------------- - -Success response: - -.. code-block:: json - - { - "status": "success", - "query": "up", - "data": [ - { - "metric": { - "__name__": "up", - "job": "kubelet", - "namespace": "kube-system", - "node": "worker-node-1" - }, - "timestamps": [1706356800.0, 1706356860.0, 1706356920.0], - "values": ["1", "1", "1"] - }, - { - "metric": { - "__name__": "up", - "job": "coredns", - "namespace": "kube-system", - "pod": "coredns-7c68b4b998-abc12" - }, - "timestamps": [1706356800.0, 1706356860.0, 1706356920.0], - "values": ["1", "1", "1"] - } - ] - } - -Response Fields ---------------- - -.. list-table:: - :header-rows: 1 - :widths: 20 80 - - * - Field - - Description - * - status - - ``success`` or ``error`` - * - query - - The PromQL query that was executed - * - data - - Array of time series results - * - data[].metric - - Labels identifying the time series - * - data[].timestamps - - Array of Unix timestamps for each data point - * - data[].values - - Array of values corresponding to each timestamp - -Error Response --------------- - -.. code-block:: json - - { - "status": "error", - "query": "invalid_query", - "error": "Error message describing what went wrong" - } - -Common Queries --------------- - -Resource quotas (OpenShift/Kubernetes): - -.. code-block:: json - - {"promql_query": "kube_resourcequota{type=\"hard\"}"} - {"promql_query": "kube_resourcequota{type=\"used\"}"} - -CPU and memory: - -.. code-block:: json - - {"promql_query": "sum(rate(container_cpu_usage_seconds_total[5m])) by (pod, namespace)"} - {"promql_query": "container_memory_usage_bytes{namespace=\"default\"}"} - -Pod status: - -.. code-block:: json - - {"promql_query": "kube_pod_status_phase{phase=\"Running\"}"} - {"promql_query": "kube_pod_container_status_restarts_total"} diff --git a/docs/configuration/exporting/rbac-api.rst b/docs/configuration/exporting/rbac-api.rst deleted file mode 100644 index 2e00394a7..000000000 --- a/docs/configuration/exporting/rbac-api.rst +++ /dev/null @@ -1,467 +0,0 @@ -RBAC Configuration API -====================== - -The RBAC (Role-Based Access Control) Configuration API allows you to programmatically manage permission groups and scopes for your Robusta account. - -.. note:: - This API is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Overview --------- - -The RBAC API provides a single endpoint with three operations: - -* **GET** - Retrieve current RBAC configuration -* **POST** - Set/update RBAC configuration -* **DELETE** - Remove all RBAC configurations - -Prerequisites -------------- - -Before using the RBAC API, you need: - - - Create at: https://platform.robusta.dev/settings#api-keys - - * **RBAC: READ** β€” required for ``GET`` - * **RBAC: WRITE** β€” required for ``POST`` and ``DELETE`` - -2. **Account ID** - - Find at: https://platform.robusta.dev/settings/general - -Authentication --------------- - -All requests require API key authentication. Include your API key in the request headers: - -.. code-block:: bash - - Authorization: Bearer YOUR_API_KEY - -API Endpoint ------------- - -``/api/rbac?account_id=YOUR_ACCOUNT_ID`` - -All operations use the same endpoint with different HTTP methods. - -Operations ----------- - -Get RBAC Configuration -^^^^^^^^^^^^^^^^^^^^^^ - -Retrieve the current RBAC configuration for your account. - -**Request:** - -.. robusta-code:: bash - - curl -X GET 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' - -**Response (200 OK):** - -.. code-block:: json - - { - "account_id": "YOUR_ACCOUNT_ID", - "scopes": [ - { - "name": "production-scope", - "type": "namespace", - "clusters": { - "production-cluster": ["default", "app-namespace"] - } - } - ], - "groups": [ - { - "name": "developers", - "provider_group_id": "dev-team-id", - "type": "namespace", - "scopes": ["production-scope"], - "permissions": ["APP_VIEW", "POD_LOGS", "METRICS_VIEW"] - } - ], - "role_permission_groups": [ - { - "name": "admin-group", - "provider_group_id": "admin-team-id", - "type": "ADMIN" - } - ] - } - -Set RBAC Configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -Create or update the RBAC configuration for your account. - -.. warning:: - This operation **completely replaces** all existing RBAC configurations. The API will: - - * Delete ALL existing scopes, groups, and role_permission_groups - * Create new configurations based on the provided request body - - If you omit any of these fields (scopes, groups, or role_permission_groups), those configurations will be deleted and not replaced. To preserve existing configurations, you must include them in your request. - -**Request:** - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' \ - -H 'Content-Type: application/json' \ - -d '{ - "account_id": "YOUR_ACCOUNT_ID", - "scopes": [...], - "groups": [...], - "role_permission_groups": [...] - }' - -**Request Body Example:** - -.. code-block:: json - - { - "account_id": "YOUR_ACCOUNT_ID", - "scopes": [ - { - "name": "production-scope", - "type": "namespace", - "clusters": { - "production-cluster": ["default", "app-namespace"] - } - }, - { - "name": "staging-scope", - "type": "cluster", - "clusters": { - "staging-cluster": ["*"] - } - } - ], - "groups": [ - { - "name": "developers", - "provider_group_id": "dev-team-id", - "type": "namespace", - "scopes": ["production-scope"], - "permissions": ["APP_VIEW", "POD_LOGS", "METRICS_VIEW"] - }, - { - "name": "devops", - "provider_group_id": "devops-team-id", - "type": "cluster", - "scopes": ["staging-scope"], - "permissions": ["NODE_VIEW", "CLUSTER_VIEW", "KRR_SCAN"] - } - ], - "role_permission_groups": [ - { - "name": "admin-group", - "provider_group_id": "admin-team-id", - "type": "ADMIN" - } - ] - } - -**Response (201 Created):** - -.. code-block:: json - - { - "msg": "RBAC definitions processed successfully", - "account_id": "YOUR_ACCOUNT_ID", - "scopes_count": 2, - "groups_count": 2 - } - -Delete RBAC Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Remove all RBAC configurations for your account. - -**Request:** - -.. robusta-code:: bash - - curl -X DELETE 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' - -**Response (200 OK):** - -.. code-block:: json - - { - "msg": "RBAC role deleted successfully" - } - -Configuration Schema --------------------- - -Scopes -^^^^^^ - -Scopes define the resources (clusters and namespaces) that permissions apply to. - -.. code-block:: json - - { - "name": "string", // Unique name for the scope - "type": "namespace|cluster", // Scope type - "clusters": { // Cluster-to-namespace mapping - "cluster-name": ["namespace1", "namespace2"] // or ["*"] for all namespaces - } - } - -**Scope Types:** - -* ``namespace`` - Permissions apply to specific namespaces within clusters -* ``cluster`` - Permissions apply to entire clusters - -Groups -^^^^^^ - -Groups define permission sets that can be assigned to users via SSO provider groups. - -.. code-block:: json - - { - "name": "string", // Group name - "provider_group_id": "string", // SSO provider group ID - "type": "namespace|cluster", // Permission scope type - "scopes": ["scope-name"], // List of scope names - "permissions": ["PERMISSION_NAME"] // List of permissions - } - -Role Permission Groups -^^^^^^^^^^^^^^^^^^^^^^ - -Role permission groups assign predefined roles to SSO provider groups. - -.. code-block:: json - - { - "name": "string", // Group name - "provider_group_id": "string", // SSO provider group ID - "type": "ADMIN|USER" // Predefined role (note: field name is "type" not "role") - } - -**Available Roles:** - -* ``ADMIN`` - Full administrative access -* ``USER`` - Standard user access - -Available Permissions ---------------------- - -**Permissions for Namespace-Type Groups:** - -These permissions are available for groups with ``type: "namespace"``: - -* ``APP_VIEW`` - View applications -* ``APP_RESTART`` - Restart applications -* ``JOB_VIEW`` - View jobs -* ``JOB_DELETE`` - Delete jobs -* ``POD_LOGS`` - View pod logs -* ``POD_DELETE`` - Delete pods -* ``KRR_VIEW`` - View KRR recommendations -* ``POPEYE_VIEW`` - View Popeye scan results -* ``METRICS_VIEW`` - View metrics -* ``HOLMES_INVESTIGATE`` - Use Holmes AI investigation -* ``TIMELINE_VIEW`` - View event timeline - -**Permissions for Cluster-Type Groups:** - -Cluster-type groups (``type: "cluster"``) have access to all namespace permissions above, plus these cluster-specific permissions: - -* ``NODE_VIEW`` - View nodes -* ``NODE_DRAIN`` - Drain nodes -* ``NODE_CORDON`` - Cordon nodes -* ``NODE_UNCORDON`` - Uncordon nodes -* ``CLUSTER_VIEW`` - View cluster information -* ``CLUSTER_DELETE`` - Delete clusters -* ``KRR_SCAN`` - Run KRR scans -* ``POPEYE_SCAN`` - Run Popeye scans -* ``ALERT_CONFIG_EDIT`` - Edit alert configurations -* ``ALERT_CONFIG_VIEW`` - View alert configurations -* ``SILENCES_VIEW`` - View alert silences -* ``SILENCES_EDIT`` - Edit alert silences -* ``HOLMES_CHAT`` - Use Holmes AI chat -* ``HOLMES_CUSTOMIZE`` - Customize Holmes AI - -Error Responses ---------------- - -The API returns standard HTTP status codes: - -* **200** - Success (GET, DELETE) -* **201** - Created (POST) -* **400** - Bad Request (e.g., account_id mismatch) -* **401** - Unauthorized (invalid or missing API key) -* **403** - Forbidden (insufficient permissions) -* **500** - Internal Server Error - -Error Response Format: - -.. code-block:: json - - { - "msg": "Error message", - "error_code": 0 - } - -Examples --------- - -**Set up namespace-level permissions for developers:** - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' \ - -H 'Content-Type: application/json' \ - -d '{ - "account_id": "YOUR_ACCOUNT_ID", - "scopes": [ - { - "name": "dev-namespaces", - "type": "namespace", - "clusters": { - "production": ["dev", "staging"], - "development": ["*"] - } - } - ], - "groups": [ - { - "name": "developers", - "provider_group_id": "github-dev-team", - "type": "namespace", - "scopes": ["dev-namespaces"], - "permissions": ["APP_VIEW", "APP_RESTART", "POD_LOGS", "METRICS_VIEW"] - } - ] - }' - -**Set up cluster-wide admin access:** - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' \ - -H 'Content-Type: application/json' \ - -d '{ - "account_id": "YOUR_ACCOUNT_ID", - "role_permission_groups": [ - { - "name": "platform-admins", - "provider_group_id": "github-admin-team", - "type": "ADMIN" - } - ] - }' - -**Complex configuration with multiple scopes and permission groups:** - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' \ - -H 'Content-Type: application/json' \ - -d '{ - "account_id": "YOUR_ACCOUNT_ID", - "scopes": [ - { - "name": "prod-apps", - "type": "namespace", - "clusters": { - "prod-cluster": ["app-1", "app-2", "app-3"] - } - }, - { - "name": "staging-full", - "type": "cluster", - "clusters": { - "staging-cluster": ["*"] - } - } - ], - "groups": [ - { - "name": "prod-developers", - "provider_group_id": "github-prod-dev", - "type": "namespace", - "scopes": ["prod-apps"], - "permissions": [ - "APP_VIEW", - "APP_RESTART", - "POD_LOGS", - "METRICS_VIEW", - "TIMELINE_VIEW" - ] - }, - { - "name": "devops-team", - "provider_group_id": "github-devops", - "type": "cluster", - "scopes": ["staging-full"], - "permissions": [ - "NODE_VIEW", - "NODE_DRAIN", - "CLUSTER_VIEW", - "KRR_SCAN", - "ALERT_CONFIG_VIEW" - ] - } - ], - "role_permission_groups": [ - { - "name": "sre-admins", - "provider_group_id": "github-sre", - "type": "ADMIN" - } - ] - }' - -**Retrieve current configuration:** - -.. robusta-code:: bash - - curl -X GET 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' - -**Clear all RBAC configurations:** - -.. robusta-code:: bash - - curl -X DELETE 'https://api.robusta.dev/api/rbac?account_id=YOUR_ACCOUNT_ID' \ - -H 'Authorization: Bearer YOUR_API_KEY' - -Important Notes ---------------- - -1. **Cluster Scope Auto-Population**: When creating configurations, the API automatically populates cluster scopes based on your account's active clusters. Use ``"*"`` as the cluster name to apply to all clusters. - -2. **Provider Group IDs**: The ``provider_group_id`` should match the group identifier from your SSO provider (e.g., GitHub team ID, Okta group ID). - -3. **Scope References**: Groups reference scopes by name. Ensure scope names are defined before referencing them in groups. - -4. **Account ID Validation**: The ``account_id`` in the request body must match the ``account_id`` in the query parameter. - -5. **No Active Clusters**: The API will return an error if no active clusters are found for your account. - -6. **Automatic Permission Inclusion**: The API automatically includes minimal permissions for each group type. Namespace groups receive basic view permissions, and cluster groups receive basic view and node permissions. - -7. **Wildcard Permissions**: Using ``["*"]`` as permissions will grant all available permissions for that scope type. - -8. **Cluster Scope Validation**: For cluster-type scopes, namespaces must be ``["*"]`` only. Specific namespace lists are not allowed for cluster scopes. - -See Also --------- - -* :doc:`send-alerts-api` - Send alerts to Robusta -* :doc:`alert-export-api` - Export alerts from Robusta \ No newline at end of file diff --git a/docs/configuration/exporting/robusta-pro-features.rst b/docs/configuration/exporting/robusta-pro-features.rst deleted file mode 100644 index 388434df5..000000000 --- a/docs/configuration/exporting/robusta-pro-features.rst +++ /dev/null @@ -1,78 +0,0 @@ -HTTP APIs -========= - -.. note:: - These APIs are available with the Robusta SaaS platform and self-hosted commercial plans. They are not available in the open-source version. - -The Robusta Platform exposes REST APIs for programmatic access to alerts, investigations, and platform data. Every request is authenticated with an :ref:`API key `, scoped to one or more of the permissions below. - -Robusta AI ----------- - -* :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>`: Send questions to HolmesGPT for on-demand root cause analysis via REST, including a streaming (SSE) mode -* :doc:`Platform MCP API `: Connect an external MCP client (Claude Code, Claude Desktop, or your own agent) to run Robusta's cross-cluster investigation tools -* :doc:`LLM Models API `: List the Robusta-hosted LLM models available to your account and its default model - -Data Export and Reporting --------------------------- - -* :doc:`Alert Export API `: Export historical alert data with filtering by time range, alert name, and account -* :doc:`Alert Reporting API `: Get aggregated statistics and counts for different alert types -* :doc:`Send Events API `: Send alerts, incidents, and changes from any monitoring source via a single webhook endpoint - -RBAC ----- - -* :doc:`RBAC Configuration API `: Programmatically manage role-based access control configurations - -.. _http-api-key-permissions: - -API Key Permissions --------------------- - -Every API key is scoped by a set of resource/action pairs, chosen when the key is created under **Settings** β†’ **API Keys** β†’ **New API Key**. The table below lists every permission and the HTTP APIs it unlocks. - -.. list-table:: - :widths: 15 15 45 25 - :header-rows: 1 - - * - Resource - - Action - - Grants access to - - Docs - * - Alerts - - Read - - Export alert history and aggregated alert statistics - - :doc:`Alert Export API `, :doc:`Alert Reporting API ` - * - Alerts - - Write - - Ingest alerts, incidents, and config changes into Robusta - - :doc:`Send Events API `, :doc:`Send Alerts API (legacy) `, :doc:`Configuration Changes API (legacy) ` - * - Robusta AI - - Write - - Ask HolmesGPT to investigate, run MCP tools against your clusters, and list available LLM models - - :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>`, :doc:`Platform MCP API `, :doc:`LLM Models API ` - * - RBAC - - Read / Write - - Read or replace the account's role-based access control configuration - - :doc:`RBAC Configuration API ` - * - Agents - - Read - - Read active Kubernetes resource counts for a namespace, as shown in the UI's Namespaces tab - - :doc:`Namespace Resources API ` (Robusta Classic) - * - KRR - - Read - - Retrieve KRR resource-sizing recommendations for a cluster - - :ref:`KRR API ` (Robusta Classic) - * - Metrics - - Read - - Run a PromQL query against a connected cluster's Prometheus - - :doc:`Prometheus Query API ` (Robusta Classic) - -Getting Started ---------------- - -To access these APIs: - -1. :robusta-url:`Sign up ` for Robusta SaaS or contact support@robusta.dev for self-hosted plans -2. Generate API keys in the Robusta Platform under **Settings** β†’ **API Keys** diff --git a/docs/configuration/exporting/send-alerts-api.rst b/docs/configuration/exporting/send-alerts-api.rst deleted file mode 100644 index 7ed2e9fdc..000000000 --- a/docs/configuration/exporting/send-alerts-api.rst +++ /dev/null @@ -1,269 +0,0 @@ -.. include:: ../_legacy_banner.rst - -Send Alerts API -=============== - -Send alerts to Robusta to have HolmesGPT automatically run an AI-powered root cause analysis on each one. HolmesGPT investigates the alert against your live cluster state, logs, metrics, and connected data sources, then attaches its findings to help accelerate triage. - -Integration Methods -------------------- - -There are two main ways to send alerts to Robusta for HolmesGPT to investigate: - -1. **Pre-built Integrations**: Use our existing integrations for AlertManager, Nagios, SolarWinds, and other monitoring systems. See :doc:`Send Alerts <../index>`. - -2. **Programmatic API**: Send alerts directly using our REST API (detailed below). - -Send Alerts API ---------------- - -Use this endpoint to send alert data to Robusta. You can send up to 1000 alerts in a single request. - -.. _send-alerts-api: - -POST endpoint -^^^^^^^^^^^^^ - -.. robusta-url:: https://api.robusta.dev/api/alerts - -Request Body Schema -"""""""""""""""""""" - -The request body must include the following fields: - -.. list-table:: - :widths: 25 10 70 10 - :header-rows: 1 - - * - Field - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier. - - Yes - * - ``alerts`` - - list - - A list of alerts to be sent. - - Yes - -Alert Schema -"""""""""""" - -Each alert in the ``alerts`` list must follow the specific schema, which includes the following fields: - -.. list-table:: - :widths: 20 10 70 10 - :header-rows: 1 - - * - Field - - Type - - Description - - Required - * - ``title`` - - string - - A short description of the alert. - - Yes - * - ``description`` - - string - - A detailed description of the alert - - Yes - * - ``source`` - - string - - The source of the alert. - - Yes - * - ``priority`` - - string (one of: ``critical``, ``high``, ``medium``, ``error``, ``warning``, ``info``, ``low``, ``debug``) - - The priority level of the alert. - - Yes - * - ``aggregation_key`` - - string - - A key to group alerts that are related. - - Yes - * - ``failure`` - - boolean - - Indicates whether the alert represents a failure (default: ``false``). - - No - * - ``starts_at`` - - string (ISO 8601 timestamp) - - The timestamp when the alert started (optional). - - No - * - ``ends_at`` - - string (ISO 8601 timestamp) - - The timestamp when the alert ended (optional). - - No - * - ``labels`` - - dict - - Extra labels for the alert (optional). - - No - * - ``annotations`` - - dict - - Extra annotations for the alert (optional). - - No - * - ``cluster`` - - string - - Alert's cluster (default: ``external``) - - No - * - ``service_key`` - - string - - A key identifying the service related to the alert (optional). - - No - * - ``subject_type`` - - string - - The type of subject related to the alert (optional). - - No - * - ``subject_name`` - - string - - The name of the subject related to the alert (optional) - - No - * - ``subject_namespace`` - - string - - The namespace of the subject related to the alert (optional). - - No - * - ``subject_node`` - - string - - The node where the subject related to the alert is located (optional). - - No - * - ``fingerprint`` - - string - - A unique identifier for the alert (optional). - - No - -Example Request -""""""""""""""" - -Here is an example of a ``POST`` request to send a list of alerts: - -.. robusta-code:: bash - - curl --location --request POST 'https://api.robusta.dev/api/alerts' \ - --header 'Authorization: Bearer API-KEY' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "account_id": "ACCOUNT_ID", - "alerts": [ - { - "title": "Test Service Down", - "description": "The Test Service is not responding.", - "source": "monitoring-system", - "priority": "high", - "aggregation_key": "test-service-issues", - "failure": true, - "starts_at": "2024-10-07T10:00:00Z", - "labels": { - "environment": "production" - }, - "annotations": { - "env1": "true" - }, - "cluster": "prod-cluster-1", - "subject_namespace": "prod", - "subject_node": "gke-prod-cluster-1-node-1" - } - ] - }' - -In this request, replace the following placeholders: - -- ``ACCOUNT_ID``: Your account ID, which can be found in the Robusta UI under **Settings** -> **General**. -- ``API-KEY``: Your API Key for authentication. You can generate this token by navigating to **Settings** -> **API Keys** -> **New API Key**. - -Request Headers -""""""""""""""" - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have the necessary permissions to submit alerts. - * - ``Content-Type`` - - Must be set to ``application/json``. - -Response Format -""""""""""""""" - -Success Response -~~~~~~~~~~~~~~~~ - -If the request is successful, the API will return the following response: - -.. code-block:: json - - { - "success": true - } - -- **Status Code**: `200 OK` - -Error Response -~~~~~~~~~~~~~~ - -If there is an error in processing the request, the API will return the following format: - -.. code-block:: json - - { - "msg": "Error message here", - "error_code": 123 - } - -- **Status Code**: Varies based on the error (e.g., `400 Bad Request`, `500 Internal Server Error`). - -Troubleshooting ---------------- - -.. tab-set:: - - .. tab-item:: General Issues - - **Not receiving alerts in Robusta UI?** - - 1. **Just installed?** Wait 10 minutes after installation for all components to initialize - 2. **Check your specific integration:** Each alert source has its own troubleshooting guide on its documentation page - 3. **Verify authentication:** Ensure API keys and webhook URLs are correctly configured - - .. tab-item:: AlertManager - - **Not receiving alerts?** - - 1. **Verify routing configuration:** - - - Ensure Robusta is the first receiver in your AlertManager configuration, or - - All previous receivers have ``continue: true`` set - - See configuration examples in your specific alert source documentation - - 2. **Check logs for errors:** - - - Review AlertManager logs for webhook errors - - Check Prometheus Operator logs (if using kube-prometheus-stack) - - Look for errors in Robusta runner logs - - 3. **Check pod health (embedded Prometheus stack):** - - - Verify all Prometheus and AlertManager pods are running - - Look for OOMKills and increase memory limits if needed - - See :doc:`Embedded Prometheus troubleshooting <../alertmanager-integration/embedded-prometheus>` - - **Alerts arriving but missing Kubernetes context?** - - Check :doc:`Customize Labels and Priorities ` to customize how Prometheus labels map to Kubernetes resources. - -Testing Your Integration ------------------------- - -Each alert source has specific testing methods: - -* **Standard AlertManager**: Use ``robusta demo-alert`` command -* **Cloud Services**: Check the specific service's documentation for test procedures -* **Custom API**: Use the curl example above with test data - -Refer to your specific integration documentation for detailed testing steps. - -Need More Help? ---------------- - -* Join our `Slack community `_ for direct support \ No newline at end of file diff --git a/docs/configuration/exporting/send-events-api.rst b/docs/configuration/exporting/send-events-api.rst deleted file mode 100644 index 5c12c71dc..000000000 --- a/docs/configuration/exporting/send-events-api.rst +++ /dev/null @@ -1,211 +0,0 @@ -Send Events API -================ - -Send alerts from your monitoring system to Robusta through a single webhook endpoint. - -This is the recommended ingestion path for new integrations. The legacy :doc:`Send Alerts API ` remains available for existing customers. - -.. toctree:: - :maxdepth: 1 - :hidden: - - send-events/alertmanager - send-events/aws-cloudwatch - send-events/azure-monitor - send-events/datadog - send-events/dynatrace - send-events/f5 - send-events/gcp-monitoring - send-events/grafana - send-events/jsm - send-events/nagios - send-events/newrelic - send-events/opsgenie - send-events/pagerduty - send-events/rootly - send-events/sentry - send-events/solarwinds - send-events/splunk - -Endpoint --------- - -.. robusta-code:: - - POST https://api.robusta.dev/webhooks?type=alert&origin=&account_id=&cluster= - -Query Parameters ----------------- - -.. list-table:: - :widths: 20 70 - :header-rows: 1 - - * - Parameter - - Description - * - ``type`` - - Must be ``alert``. - * - ``origin`` - - Identifies the monitoring product. Must be one of the supported origins listed under `Integrations`_ below. - * - ``account_id`` - - Your Robusta account ID, found in the Robusta UI under **Settings β†’ General**. - * - ``cluster`` - - Recommended. The cluster to file the alert under β€” use the exact name shown in the Robusta UI. Overrides any cluster in the alert payload. If omitted, the cluster is taken from the payload, or silently defaults to ``external``. - -Authentication --------------- - -Send your Robusta API key as a Bearer token. Generate keys in the Robusta UI under **Settings β†’ API Keys β†’ New API Key**. - -.. code-block:: - - Authorization: Bearer - -The key must be scoped to the ``account_id`` query parameter. Mismatches return ``401``. - -Example Request ---------------- - -.. robusta-code:: bash - - curl --location --request POST \ - 'https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=ACCOUNT_ID&cluster=CLUSTER_NAME' \ - --header 'Authorization: Bearer API_KEY' \ - --header 'Content-Type: application/json' \ - --data-raw '{ "title": "High error rate", "severity": "high" }' - -Response --------- - -A successful request returns ``200`` with the ID of the stored event: - -.. code-block:: json - - { "id": "8f1b...e21" } - -Errors: - -* ``400`` β€” missing or empty ``account_id``, ``origin``, or ``type``; invalid ``type`` value. -* ``401`` β€” invalid or out-of-scope API key. -* ``429`` β€” rate limit exceeded (300 requests per 5-minute window per account). -* ``503`` β€” transient storage failure; vendors should retry. - -Integrations ------------- - -Pick your monitoring system below for step-by-step instructions. Each page provides the URL to paste into your vendor's webhook configuration along with the API key. - -Prometheus & AlertManager -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` AlertManager - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/alertmanager - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Grafana - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/grafana - :link-type: doc - -APM & Observability -~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` Datadog - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/datadog - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` New Relic - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/newrelic - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Dynatrace - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/dynatrace - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Splunk - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/splunk - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Sentry - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/sentry - :link-type: doc - -Cloud Provider Monitoring -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`server;1em;` GCP Cloud Monitoring - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/gcp-monitoring - :link-type: doc - - .. grid-item-card:: :octicon:`server;1em;` Azure Monitor - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/azure-monitor - :link-type: doc - - .. grid-item-card:: :octicon:`server;1em;` AWS CloudWatch - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/aws-cloudwatch - :link-type: doc - -Incident Management -~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` PagerDuty - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/pagerduty - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Opsgenie - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/opsgenie - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Jira Service Management - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/jsm - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Rootly - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/rootly - :link-type: doc - -Other -~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` F5 Distributed Cloud - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/f5 - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Nagios - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/nagios - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` SolarWinds - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/solarwinds - :link-type: doc diff --git a/docs/configuration/exporting/send-events/alertmanager.rst b/docs/configuration/exporting/send-events/alertmanager.rst deleted file mode 100644 index 24ac5a122..000000000 --- a/docs/configuration/exporting/send-events/alertmanager.rst +++ /dev/null @@ -1,52 +0,0 @@ -AlertManager -============= - -Forward Prometheus alerts from AlertManager directly to Robusta. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts, generated under **Settings β†’ API Keys β†’ New API Key**. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -.. note:: - - Alerts can also carry the cluster as a ``cluster`` or ``cluster_name`` label (e.g. via Prometheus ``externalLabels``); the URL parameter takes precedence. The :doc:`in-cluster integration ` is a separate mechanism that routes by label only. - -Configure AlertManager ----------------------- - -Add a webhook receiver to ``alertmanager.yml``: - -.. robusta-code:: yaml - - receivers: - - name: robusta - webhook_configs: - - url: 'https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=&cluster=' - send_resolved: true - http_config: - authorization: - type: Bearer - credentials: - - route: - receiver: robusta - continue: true - -Set ``continue: true`` if Robusta is not your only receiver, so alerts also reach your other destinations. - -Verify ------- - -Open **Settings β†’ Delivery Log** in the Robusta UI to see the request arrive, then check the timeline for the parsed alert. diff --git a/docs/configuration/exporting/send-events/aws-cloudwatch.rst b/docs/configuration/exporting/send-events/aws-cloudwatch.rst deleted file mode 100644 index 300c2ac93..000000000 --- a/docs/configuration/exporting/send-events/aws-cloudwatch.rst +++ /dev/null @@ -1,66 +0,0 @@ -AWS CloudWatch -=============== - -Forward CloudWatch alarms to Robusta. CloudWatch cannot POST to arbitrary HTTPS endpoints directly, so the recipe is **CloudWatch β†’ SNS β†’ Lambda β†’ Robusta**. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* AWS account permissions to create Lambda functions and SNS topics. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=aws-cloudwatch&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Recipe ------- - -1. Create an SNS topic named ``robusta``. Add it as a notification action on the CloudWatch alarms you want forwarded. -2. Create a Lambda function (Python 3.12) and subscribe it to the ``robusta`` SNS topic. Store the Robusta API key in **Lambda β†’ Configuration β†’ Environment variables** as ``ROBUSTA_API_KEY``. -3. Use the following handler: - - .. robusta-code:: python - - import json - import os - import urllib.error - import urllib.request - - URL = "https://api.robusta.dev/webhooks?type=alert&origin=aws-cloudwatch&account_id=&cluster=" - TIMEOUT_SECONDS = 5 - - def lambda_handler(event, context): - for record in event["Records"]: - body = record["Sns"]["Message"] - req = urllib.request.Request( - URL, - data=body.encode("utf-8"), - method="POST", - headers={ - "Content-Type": "application/json", - "Authorization": f"Bearer {os.environ['ROBUSTA_API_KEY']}", - }, - ) - try: - urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS).read() - except urllib.error.URLError as exc: - print(f"failed to forward CloudWatch alarm to Robusta: {exc}") - raise - return {"ok": True} - -4. Replace ```` with your Robusta account ID and ```` with your cluster's name as it appears in the Robusta UI, then deploy. - -Alternatively, if you already use **Amazon EventBridge β†’ API destination**, point the destination at the same URL with a Bearer token connection β€” no Lambda required. - -Verify ------- - -Use the **Test alarm** action in CloudWatch. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/azure-monitor.rst b/docs/configuration/exporting/send-events/azure-monitor.rst deleted file mode 100644 index c68b0c350..000000000 --- a/docs/configuration/exporting/send-events/azure-monitor.rst +++ /dev/null @@ -1,40 +0,0 @@ -Azure Monitor -============== - -Forward Azure Monitor alerts to Robusta via an Action Group webhook receiver. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* Azure ``Contributor`` access to the resource group hosting the Action Group. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=azure-monitor&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Azure ---------------- - -Action Group webhook receivers do not allow custom headers, so authenticate via the URL: - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=azure-monitor&account_id=&cluster=&token= - -1. In the Azure Portal, open **Monitor β†’ Action groups** and either create a new group or edit an existing one. -2. Under **Actions**, add an action of type **Webhook**. -3. Name it ``Robusta`` and set the **URI** to the URL above. Leave **Enable the common alert schema** on. -4. Save the action group and attach it to the alert rules you want to forward. - -Verify ------- - -Use the action group's **Test** option. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/datadog.rst b/docs/configuration/exporting/send-events/datadog.rst deleted file mode 100644 index a51972d47..000000000 --- a/docs/configuration/exporting/send-events/datadog.rst +++ /dev/null @@ -1,81 +0,0 @@ -Datadog -======== - -Forward Datadog monitor alerts to Robusta via a Datadog webhook integration. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* A Datadog admin able to create webhook integrations. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, Robusta uses the alert's ``kube_cluster_name`` tag, or files the alert under a generic ``external`` cluster when there is none. - -Configure Datadog ------------------ - -1. In Datadog, go to **Integrations β†’ Webhooks β†’ New** and name the webhook ``robusta``. -2. Set the URL to the webhook URL above. -3. Under **Custom Headers**, add: - - .. code-block:: json - - { "Authorization": "Bearer " } - -4. Replace the **Payload** with: - - .. code-block:: json - - { - "body": "$EVENT_MSG", - "last_updated": "$LAST_UPDATED", - "event_type": "$EVENT_TYPE", - "title": "$EVENT_TITLE", - "date": "$DATE", - "org": {"id": "$ORG_ID", "name": "$ORG_NAME"}, - "id": "$ID", - "tags": "$TAGS", - "aggreg_key": "$AGGREG_KEY", - "alert_transition": "$ALERT_TRANSITION" - } - - This is Datadog's default payload plus three fields: - - * ``tags``: cluster, namespace, and the affected Kubernetes resource (for example ``kube_deployment``, ``kube_stateful_set`` or ``pod_name``). - * ``aggreg_key``: links a recovery to the alert it resolves. - * ``alert_transition``: tells Robusta whether the alert is firing or recovered. - -5. Save. In any monitor, set the **Notify** field to ``@webhook-robusta`` to forward its alerts to Robusta. - -.. note:: - - Datadog's unmodified default payload is also accepted, but alerts then carry less information and group less reliably. Use the payload above. - -Verify ------- - -Trigger a test alert from a Datadog monitor. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. - -Optional: alert names ---------------------- - -By default every Datadog alert is named ``Datadog alert``, so all Datadog alerts share one row on the timeline. To name alerts per monitor, add an ``alert_name`` field to the payload: - -.. code-block:: json - - "alert_name": "$TAGS[alertname]" - -and add a tag such as ``alertname:CrashLoopBackOff`` to each monitor. Monitors without the tag keep the default name. - -.. warning:: - - Use a name that is the same for every alert from a monitor. A dynamic value such as ``"$ALERT_TITLE"`` includes the pod or host that fired, so every pod or host gets its own row on the timeline. diff --git a/docs/configuration/exporting/send-events/dynatrace.rst b/docs/configuration/exporting/send-events/dynatrace.rst deleted file mode 100644 index d60c5ff79..000000000 --- a/docs/configuration/exporting/send-events/dynatrace.rst +++ /dev/null @@ -1,40 +0,0 @@ -Dynatrace -========== - -Forward Dynatrace problems to Robusta via a Dynatrace custom webhook integration. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* A Dynatrace admin able to add problem notifications. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=dynatrace&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Dynatrace -------------------- - -1. In Dynatrace, go to **Settings β†’ Integration β†’ Problem notifications** and **Set up notifications** β†’ **Custom integration**. -2. Set the **Webhook URL** to the URL above. -3. Add a custom HTTP header: - - .. code-block:: - - Authorization: Bearer - -4. Use the default JSON payload template. -5. Save and assign the integration to your alerting profile. - -Verify ------- - -Use the **Send test notification** button. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/f5.rst b/docs/configuration/exporting/send-events/f5.rst deleted file mode 100644 index 4f89eb251..000000000 --- a/docs/configuration/exporting/send-events/f5.rst +++ /dev/null @@ -1,45 +0,0 @@ -F5 Distributed Cloud -===================== - -Forward alerts from F5 Distributed Cloud (XC) to Robusta via a webhook alert receiver. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* An F5 Distributed Cloud tenant with permission to manage alert receivers and alert policies. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=f5&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure F5 Distributed Cloud ------------------------------- - -1. In the F5 Distributed Cloud Console, go to **Multi-Cloud App Connect β†’ Alerts Management β†’ Alert Receivers** (under Shared Configuration in some tenants) and select **Add Alert Receiver**. -2. Set **Receiver** to ``Webhook`` and name it ``robusta``. -3. Set the **URL** to the webhook URL above. -4. Under **Authentication**, choose **Token** and set the token value to your Robusta API key. F5 sends it as ``Authorization: Bearer ``. -5. Save the receiver. -6. Go to **Alert Policies β†’ Add Alert Policy**, name it ``robusta``, and add the receiver you just created under **Alert Receivers**. -7. Under **Policy Rules**, select which alerts to route β€” choose **Select All Alerts** to forward everything, or filter by alert group/severity. -8. Save the policy. Only alerts matched by an active alert policy are forwarded. - -Verify ------- - -Use **Send Test Alert** on the alert receiver (available from the receiver's action menu). The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. - -Notes ------ - -* F5 severities map to Robusta priorities as follows: ``critical`` and ``major`` β†’ ``HIGH``, ``minor`` β†’ ``LOW``, ``info`` β†’ ``INFO``. -* The ``namespace`` on an F5 alert is a Distributed Cloud namespace, not a Kubernetes one; it is kept as an alert label along with ``tenant``, ``site``, and ``group``. -* F5 alerts are not tied to a Kubernetes cluster. To associate them with one of your clusters anyway, append ``&cluster=`` to the webhook URL. diff --git a/docs/configuration/exporting/send-events/gcp-monitoring.rst b/docs/configuration/exporting/send-events/gcp-monitoring.rst deleted file mode 100644 index 108f82d95..000000000 --- a/docs/configuration/exporting/send-events/gcp-monitoring.rst +++ /dev/null @@ -1,42 +0,0 @@ -GCP Cloud Monitoring -===================== - -Forward Cloud Monitoring alerting policies to Robusta via a GCP webhook notification channel. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* A GCP project with the ``Monitoring Notification Channel Editor`` role. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=gcp-monitoring&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure GCP -------------- - -GCP webhook notification channels do not support custom headers in the console, so include the API key in the URL: - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=gcp-monitoring&account_id=&cluster=&token= - -The ``token`` query parameter is accepted as an alternative to the ``Authorization`` header. - -1. In the GCP Console, go to **Monitoring β†’ Alerting β†’ Edit Notification Channels**. -2. Click **Add new** under **Webhooks**. -3. Set the **Endpoint URL** to the URL above and name it ``Robusta``. -4. Save and attach the channel to the alerting policies you want to forward. - -Verify ------- - -Use **Send test notification** on the channel. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/grafana.rst b/docs/configuration/exporting/send-events/grafana.rst deleted file mode 100644 index dffe173f2..000000000 --- a/docs/configuration/exporting/send-events/grafana.rst +++ /dev/null @@ -1,40 +0,0 @@ -Grafana -======== - -Forward alerts from Grafana (Cloud or self-hosted) to Robusta via a Grafana contact point of type ``Webhook``. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* Grafana 9.0+ with Grafana-managed alerting enabled. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=grafana&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Grafana ------------------ - -1. In Grafana, go to **Alerting β†’ Contact points β†’ Add contact point**. -2. Set the integration to **Webhook** and name it ``Robusta``. -3. Set the **URL** to the webhook URL above. -4. Under **Optional Webhook settings β†’ HTTP method**, leave ``POST``. Under **Authorization Header**, set: - - * **Scheme**: ``Bearer`` - * **Credentials**: ```` - -5. Save the contact point. -6. Update your **Notification policy** so the desired alert rules route to ``Robusta``. - -Verify ------- - -Use Grafana's **Test** button on the contact point. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/jsm.rst b/docs/configuration/exporting/send-events/jsm.rst deleted file mode 100644 index 4208a2433..000000000 --- a/docs/configuration/exporting/send-events/jsm.rst +++ /dev/null @@ -1,41 +0,0 @@ -Jira Service Management -======================== - -Forward Jira Service Management (JSM) alerts to Robusta via the JSM outgoing webhook integration. - -Prerequisites -------------- - -* A Jira Service Management **Premium** or **Enterprise** plan β€” outgoing webhook integrations are not available on lower tiers. -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts, generated under **Settings β†’ API Keys β†’ New API Key**. -* Admin access to Operations in Jira Service Management. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=jsm&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Jira Service Management ---------------------------------- - -1. In Jira Service Management, go to **Operations β†’ Integrations β†’ Add integration**. -2. Search for **Webhook** and select the outgoing webhook integration. -3. Set the **Webhook URL** to the URL above. -4. Add a custom **Header**: - - .. code-block:: - - Authorization: Bearer - -5. Choose which alert actions (``Create``, ``Acknowledge``, ``Close``, …) trigger the webhook and turn the integration on. - -Verify ------- - -Create a test alert in Jira Service Management. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/nagios.rst b/docs/configuration/exporting/send-events/nagios.rst deleted file mode 100644 index 89544ba12..000000000 --- a/docs/configuration/exporting/send-events/nagios.rst +++ /dev/null @@ -1,76 +0,0 @@ -Nagios -======= - -Forward Nagios host and service problems to Robusta from a Nagios notification command. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* Shell access to your Nagios host with permission to edit ``commands.cfg`` and ``contacts.cfg``. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=nagios&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Nagios ----------------- - -Store the API key in ``resource.cfg`` so it does not appear in command definitions or process listings: - -.. code-block:: - - # /etc/nagios/resource.cfg - $USER20$= - -Restrict the file to the Nagios user: - -.. code-block:: bash - - chown root:nagios /etc/nagios/resource.cfg - chmod 640 /etc/nagios/resource.cfg - -Define a notification command that references ``$USER20$``: - -.. robusta-code:: - - define command { - command_name notify-robusta-service - command_line /usr/bin/curl -sS -X POST \ - -H 'Authorization: Bearer $USER20$' \ - -H 'Content-Type: application/json' \ - --data '{ - "host": "$HOSTNAME$", - "service": "$SERVICEDESC$", - "state": "$SERVICESTATE$", - "type": "$NOTIFICATIONTYPE$", - "output": "$SERVICEOUTPUT$" - }' \ - 'https://api.robusta.dev/webhooks?type=alert&origin=nagios&account_id=&cluster=' - } - -Define an analogous ``notify-robusta-host`` command, then attach both to a Nagios contact: - -.. code-block:: - - define contact { - contact_name robusta - service_notification_commands notify-robusta-service - host_notification_commands notify-robusta-host - service_notification_options w,u,c,r - host_notification_options d,u,r - } - -Add ``robusta`` to the ``contact_groups`` you want to forward. - -Verify ------- - -Acknowledge a test problem to fire a notification. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/newrelic.rst b/docs/configuration/exporting/send-events/newrelic.rst deleted file mode 100644 index 3a5c85249..000000000 --- a/docs/configuration/exporting/send-events/newrelic.rst +++ /dev/null @@ -1,40 +0,0 @@ -New Relic -========== - -Forward New Relic alerts to Robusta via a New Relic webhook destination. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* A New Relic admin able to create webhook destinations. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=newrelic&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure New Relic -------------------- - -1. In New Relic, go to **Alerts & AI β†’ Destinations** and add a **Webhook** destination named ``Robusta``. -2. Set the **Endpoint URL** to the webhook URL above. -3. Add a custom header: - - .. code-block:: - - Authorization: Bearer - -4. Use the default payload template. -5. Create a **Workflow** that routes the desired policy to this destination. - -Verify ------- - -Trigger a test incident in New Relic. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/opsgenie.rst b/docs/configuration/exporting/send-events/opsgenie.rst deleted file mode 100644 index 4849b9321..000000000 --- a/docs/configuration/exporting/send-events/opsgenie.rst +++ /dev/null @@ -1,39 +0,0 @@ -Opsgenie -========= - -Forward Opsgenie alerts to Robusta via the Opsgenie outgoing webhook integration. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* Opsgenie admin access. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=opsgenie&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Opsgenie ------------------- - -1. In Opsgenie, go to **Settings β†’ Integrations β†’ Add Integration β†’ Webhook**. -2. Set the **Webhook URL** to the URL above. -3. Add a custom **Header**: - - .. code-block:: - - Authorization: Bearer - -4. Choose which alert actions (``Create``, ``Acknowledge``, ``Close``, …) trigger the webhook and save. - -Verify ------- - -Create a test alert in Opsgenie. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/pagerduty.rst b/docs/configuration/exporting/send-events/pagerduty.rst deleted file mode 100644 index ef336855d..000000000 --- a/docs/configuration/exporting/send-events/pagerduty.rst +++ /dev/null @@ -1,40 +0,0 @@ -PagerDuty -========== - -Forward PagerDuty alerts to Robusta via PagerDuty AIOps Event Orchestration. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts, generated under **Settings β†’ API Keys β†’ New API Key**. -* An AIOps-enabled PagerDuty plan with admin access to Event Orchestration. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=pagerduty&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure PagerDuty -------------------- - -1. In PagerDuty, go to **AIOps β†’ Event Orchestration** and open the orchestration that handles the alerts you want forwarded. -2. Under **Automation β†’ Webhook Actions**, add a new webhook. -3. Set the **Webhook URL** to the URL above. -4. Add a custom header: - - .. code-block:: - - Authorization: Bearer - -5. Save. - -Verify ------- - -Trigger a test alert in PagerDuty. It should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/rootly.rst b/docs/configuration/exporting/send-events/rootly.rst deleted file mode 100644 index b236380cc..000000000 --- a/docs/configuration/exporting/send-events/rootly.rst +++ /dev/null @@ -1,39 +0,0 @@ -Rootly -======= - -Forward Rootly alert lifecycle events to Robusta via a Rootly outgoing webhook. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts, generated under **Settings β†’ API Keys β†’ New API Key**. -* A Rootly admin able to create outgoing webhooks. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=rootly&account_id=&cluster=&token= - -Replace ```` with your Robusta account id, ```` with the API key you generated, and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Rootly ----------------- - -1. In Rootly, go to **Integrations β†’ Webhooks β†’ New Webhook**. -2. Set the **URL** to the webhook URL above. -3. Subscribe the webhook to the alert events you want forwarded β€” at minimum ``alert.created``. If the Rootly UI offers other ``alert.*`` events (for example to notify on resolution), subscribe to those as well; Robusta accepts the whole ``alert.*`` family and uses the alert object's ``ended_at`` field to tell firing from resolved, so the parser stays correct regardless of which specific event names Rootly emits. -4. Save. Rootly will start delivering alerts immediately. - -Payload -------- - -Rootly sends a fixed JSON envelope; no body template is required. The relay extracts the alert summary, status, source system, labels, and timestamps. Severity is read from ``data.labels[]`` (Rootly's ``[{key, value}]`` array) or from the freeform ``data.data`` object if the upstream system propagated it there. The ``data.external_id`` field is used as the deduplication fingerprint so retransmissions of the same upstream alert fold into a single Robusta timeline entry. - -Verify ------- - -Trigger a test alert in Rootly (or wait for the next real alert). The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/sentry.rst b/docs/configuration/exporting/send-events/sentry.rst deleted file mode 100644 index 052a20c7d..000000000 --- a/docs/configuration/exporting/send-events/sentry.rst +++ /dev/null @@ -1,255 +0,0 @@ -Sentry -======= - -Forward Sentry alerts and issues to Robusta via Sentry's Internal -Integration. - -Sentry can send events to Robusta in two different ways. Use either -one, or enable both on the same integration: - -* :ref:`Issue Lifecycle Webhook ` fires - on every issue created / resolved / assigned / archived / - unresolved across the org. Lighter payload (no per-event details, - no event-level tags), zero alert-rule plumbing. Use this when you - want every Sentry issue on the Robusta timeline. -* :ref:`Send alert webhook ` fires only when - a Sentry Issue Alert Rule (or Metric Alert Rule) triggers and lists - Robusta as one of its actions. Richer payload (event detail, rule - name, and all tags attached to the event). Use this when you want - rule-driven, throttled alerts. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts, generated - under **Settings β†’ API Keys β†’ New API Key**. -* Sentry **Owner** or **Manager** role on the org (lower roles can't - create Custom Integrations). - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=sentry&account_id=&cluster=&token= - -Replace ```` with your Robusta account id, -```` with the API key you just generated, and -```` with your cluster's name exactly as it appears in -the Robusta UI. If ``cluster`` is omitted, alerts are filed under a -generic ``external`` cluster. - -.. note:: - - Sentry Internal Integrations **do not let you add custom outgoing - HTTP headers** (the only auth header Sentry sends is its own - ``Sentry-Hook-Signature``). The Robusta API key therefore goes in - the ``&token=`` URL parameter rather than an ``Authorization`` - header. - -Create the Custom Integration ------------------------------ - -1. In Sentry, navigate to **Settings β†’ Integrations β†’ Custom - Integrations**. -2. Click **Create New Integration** in the top right. -3. In the **Choose Integration Type** dialog, select **Internal - Integration** and click **Next**. -4. **Name**: ``Robusta`` (or ``Robusta Prod Alerts``, etc. β€” this is - only for display in Sentry). -5. **Webhook URL**: paste the URL from the previous section. - -Then configure -:ref:`Issue Lifecycle Webhook `, -:ref:`Send alert webhook `, or both, and save -the integration at the end. - -.. _sentry-path-issue-lifecycle: - -Issue Lifecycle Webhook ------------------------ - -Subscribe to lifecycle events so every Sentry issue lands on the -Robusta timeline. - -In the **PERMISSIONS** section of the same form: - -1. **Issue & Event**: set to **Read**. - -Then in the **WEBHOOKS** section: - -2. Tick **only** the ``issue`` checkbox (sub-events: ``created``, - ``resolved``, ``assigned``, ``archived``, ``unresolved``). - -.. warning:: - - Do **not** enable the ``error`` checkbox. It fires on every - individual error event (not per issue) β€” a noisy service will - generate far more webhook traffic than the issue checkbox does. - -3. Click **Save Changes** at the bottom of the form. The integration - now appears under **INTERNAL INTEGRATIONS** on the Custom - Integrations list page. - -.. _sentry-path-alert-rule: - -Send alert webhook ------------------- - -Register Robusta as a selectable action inside Sentry Issue Alert and -Metric Alert rules so the integration receives the rich -``event_alert`` payload only when a rule fires. Two parts: configure -the integration, then add Robusta to an existing alert rule. - -Configure the integration -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the **INTERNAL INTEGRATION DETAILS** section of the same form: - -1. **Alert Rule Action**: tick this checkbox. - -2. **Schema**: paste the following JSON so Robusta appears in - Sentry's alert rule action picker. - - .. code-block:: json - - { - "elements": [ - { - "type": "alert-rule-action", - "title": "Send to Robusta", - "settings": { - "type": "alert-rule-settings", - "uri": "/webhooks", - "required_fields": [ - { - "type": "select", - "label": "Destination", - "name": "destination", - "options": [["robusta", "Robusta"]] - } - ] - } - } - ] - } - - The ``title`` is the action label that shows up inside Sentry's - alert rule editor. The schema is what tells Sentry how to render - the integration in the picker β€” without it, Robusta won't appear - in the "Send a notification via an integration" dropdown. - -Then in the **PERMISSIONS** section: - -3. **Alerts**: set to **Read**. - -4. Click **Save Changes** at the bottom of the form. The integration - now appears under **INTERNAL INTEGRATIONS** on the Custom - Integrations list page. - -Add Robusta to an existing alert rule -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The integration is now selectable in alert rules, but until a rule -references it Sentry won't POST anything. For each Sentry alert rule -you want to forward to Robusta: - -1. In the project that owns the rule, open **Alerts β†’ Alert Rules** - and click the rule you want to forward. -2. Under **Then perform these actions**, click **Add action** and - select **Send a notification via an integration β†’ Robusta**. -3. The "Destination" dropdown the schema declared appears here; - leave it at "Robusta". -4. **Save** the rule. - -When the rule's conditions match, Sentry POSTs the ``event_alert`` -payload to Robusta, and the rule name shows up as the Robusta -aggregation key. - -.. _sentry-verify: - -Verify ------- - -Trigger an event end-to-end to confirm the pipeline: - -* **Issue Lifecycle Webhook**: in Sentry, pick any existing issue β†’ - click **Resolve** β†’ then **Unresolve**. Two ``issue`` webhooks fire - back-to-back. -* **Send alert webhook**: trigger an Issue Alert Rule that targets - the Robusta integration (or set the rule to "An event is seen" - with no filters and trigger any error in the app). - -Then: - -1. Open the integration's **Dashboard** tab in Sentry β€” each POST - should show HTTP **200** from Robusta. -2. Open **Settings β†’ Delivery Log** in the Robusta UI β€” the event - should appear with ``parse_status=parsed``. -3. Open the Robusta timeline β€” the Sentry-sourced row should land - within a few seconds. - -.. _sentry-troubleshooting: - -Troubleshooting ---------------- - -Sentry exposes its own delivery history on the Custom Integration's -**Dashboard** tab β€” open **Settings β†’ Integrations β†’ Custom -Integrations** and, near the Robusta integration, click the -**Dashboard** button. The dashboard lists every outgoing webhook -with the HTTP status code Robusta returned, the timestamp, the -request body Sentry sent, and the response body Robusta replied -with. Always start debugging here β€” it tells you whether the problem -is on Sentry's side (no requests showing up) or Robusta's side -(requests present but non-200). - -Common responses and what they mean: - -.. list-table:: - :header-rows: 1 - :widths: 12 30 58 - - * - Status - - Meaning - - Fix - * - **200** - - Robusta accepted the event. - - If you don't see it on the timeline shortly after, check the - Robusta **Delivery Log** for parse failures. - * - **400** - - Missing or invalid query parameter. - - Re-check ``account_id``, ``origin=sentry``, and ``type=alert`` - in the Webhook URL. - * - **401** - - API key rejected. - - The ``token`` in the URL is wrong, expired, or not scoped to the - same ``account_id``. Regenerate the API key with - ``Read/Write`` access to alerts and update the Webhook URL. - * - **429** - - Rate limit exceeded. - - More than 300 requests in 5 minutes from this account. Throttle - the Sentry alert rule or unsubscribe from the high-volume - ``error`` webhook event. - * - **5xx** - - Robusta-side failure. - - Open the Robusta **Delivery Log** for the event id Sentry - displays in the response body; if it isn't there, contact - Robusta support with the request id from the Sentry dashboard. - -If the dashboard shows **no recent requests** even though you -triggered an event: - -* For the **Issue Lifecycle Webhook**, verify the ``issue`` checkbox - under **Webhooks** is enabled and the integration is saved. -* For the **Send alert webhook** path, verify the **Alert Rule - Action** checkbox is on, the **Schema** is saved, and the alert - rule in your project lists Robusta as one of its actions. - -If the dashboard shows **200 responses but nothing appears in the -Robusta timeline**, open the Robusta **Delivery Log** and look for -rows with ``origin=sentry`` and ``parse_status=failed`` β€” the -``parser_error`` column tells you which field the parser couldn't -read. diff --git a/docs/configuration/exporting/send-events/solarwinds.rst b/docs/configuration/exporting/send-events/solarwinds.rst deleted file mode 100644 index 5be16bfcb..000000000 --- a/docs/configuration/exporting/send-events/solarwinds.rst +++ /dev/null @@ -1,37 +0,0 @@ -SolarWinds -=========== - -Forward SolarWinds Orion alerts to Robusta from an alert action. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* SolarWinds Orion admin access. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=solarwinds&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure SolarWinds --------------------- - -SolarWinds does not ship a native bearer-token webhook action. Use the **Execute an external program** alert action to invoke ``curl`` (bundled with Windows 10+ and Windows Server 2019+): - -.. robusta-code:: - - curl -sS -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" --data "{ \"alertName\": \"${N=Alerting;M=AlertName}\", \"node\": \"${N=SwisEntity;M=Caption}\", \"severity\": \"${N=Alerting;M=Severity}\", \"message\": \"${N=Alerting;M=AlertMessage}\" }" "https://api.robusta.dev/webhooks?type=alert&origin=solarwinds&account_id=&cluster=" - -Save the action and attach it to the alerts you want forwarded. - -Verify ------- - -Manually trigger the alert from the **Alert Manager** UI. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/exporting/send-events/splunk.rst b/docs/configuration/exporting/send-events/splunk.rst deleted file mode 100644 index eb3da5e94..000000000 --- a/docs/configuration/exporting/send-events/splunk.rst +++ /dev/null @@ -1,40 +0,0 @@ -Splunk -======= - -Forward Splunk alerts to Robusta via a Splunk webhook alert action. - -Prerequisites -------------- - -* A Robusta account with API access. -* Your Robusta ``account_id``, found in the Robusta UI under **Settings β†’ General**. -* A Robusta API key with ``Read/Write`` access to alerts. -* Splunk admin access to define alert actions. - -Webhook URL ------------ - -.. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=splunk&account_id=&cluster= - -Replace ```` with your Robusta account id and ```` with your cluster's name exactly as it appears in the Robusta UI. If ``cluster`` is omitted, alerts are filed under a generic ``external`` cluster. - -Configure Splunk ----------------- - -Splunk's built-in **Webhook** alert action does not let you set custom headers, so authenticate via the URL. - -1. Open or create a Splunk saved search and choose **Add Actions β†’ Webhook**. -2. Set the **URL** to the webhook URL above with ``&token=`` appended, so authentication travels with the request: - - .. robusta-code:: - - https://api.robusta.dev/webhooks?type=alert&origin=splunk&account_id=&cluster=&token= - -3. Save the search. If your Splunk environment has the **Webhook Alert Action** app installed, you can instead set an ``Authorization: Bearer `` header and use the plain webhook URL without ``&token=…``. - -Verify ------- - -Trigger the saved search manually. The event should appear in **Settings β†’ Delivery Log** and on the Robusta timeline. diff --git a/docs/configuration/github-actions/holmes-pr-review.rst b/docs/configuration/github-actions/holmes-pr-review.rst deleted file mode 100644 index ee2353c9d..000000000 --- a/docs/configuration/github-actions/holmes-pr-review.rst +++ /dev/null @@ -1,137 +0,0 @@ -HolmesGPT PR Review -=================== - -.. note:: - This integration is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use HolmesGPT as a GitHub Action to automatically review pull requests. On every PR open, reopen, or push, the action asks HolmesGPT to review the change and post its review as a comment on the pull request. You control what Holmes checks by editing the prompt β€” it can flag risky changes, check code against runbooks, cross-reference logs or metrics, or run any investigation available via its :doc:`data sources <../holmesgpt/main-features>`. - -Example review posted by HolmesGPT on a pull request: - -.. image:: /images/holmes-pr-review-example.png - :width: 700 - :align: center - -How It Works ------------- - -1. A pull request event triggers the GitHub Action. -2. The action calls the :ref:`Holmes Chat API ` with your review prompt and the PR URL. -3. HolmesGPT uses the GitHub toolset to read the pull request, reason about it using the data sources you have configured, and post its review as a comment on the PR. - -Prerequisites -------------- - -Before setting up the action, you must enable the Holmes GitHub integration so HolmesGPT can read pull requests and post comments. Follow the `HolmesGPT GitHub toolset guide `_. - -Setup ------ - -Step 1: Create a Robusta API Key -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the Robusta Platform, navigate to **Settings** β†’ **API Keys** and click **New API Key**. - -Give the key a descriptive name (for example, ``HolmesGPT github action``) and check the **Robusta AI Write** capability. Click **Generate API Key** and copy the key β€” you will not be able to view it again. - -.. image:: /images/new-api-key.png - :width: 600 - :align: center - -Step 2: Get Your Account ID and Cluster ID -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the Robusta Platform, navigate to **Settings** β†’ **General** and copy your **Account ID**. - -Then pick the cluster HolmesGPT should run the investigation on and copy its **Cluster ID**. Any cluster connected to your account can be used β€” HolmesGPT will use its data sources (logs, metrics, Kubernetes state, etc.) from that cluster when reviewing the PR. - -Step 3: Add GitHub Secrets -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In your GitHub repository, go to **Settings** β†’ **Secrets and variables** β†’ **Actions** and add the following repository secrets: - -.. list-table:: - :widths: 25 75 - :header-rows: 1 - :width: 100% - - * - Secret - - Value - * - ``ROBUSTA_API_KEY`` - - The API key you generated in Step 1. - * - ``ROBUSTA_ACCOUNT_ID`` - - The account ID from Step 2. - * - ``ROBUSTA_CLUSTER_ID`` - - The cluster ID from Step 2. - -Step 4: Add the Workflow File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Create a new file in your repository at ``.github/workflows/holmes-pr-review.yaml`` with the following contents: - -.. robusta-code:: yaml - - name: Holmes PR review - on: - pull_request: - types: [opened, synchronize, reopened] - jobs: - review: - runs-on: ubuntu-latest - env: - RELAY_BASE_URL: https://api.robusta.dev - ACCOUNT_ID: ${{ secrets.ROBUSTA_ACCOUNT_ID }} - API_KEY: ${{ secrets.ROBUSTA_API_KEY }} - CLUSTER_ID: ${{ secrets.ROBUSTA_CLUSTER_ID }} - PR_URL: ${{ github.event.pull_request.html_url }} - PROMPT: | - Review the pull request at the URL below. Flag risky, unclear, or - incomplete changes. You MUST post your review as a single PR comment - on that pull request using your GitHub toolset. Do not reply with the - review in chat only β€” posting the comment is required. - steps: - - name: Ask Holmes (Holmes posts the comment) - run: | - set -euo pipefail - jq -n \ - --arg ask "$PROMPT"$'\n\nPull request: '"$PR_URL" \ - --arg cluster "$CLUSTER_ID" \ - '{ask: $ask, cluster_id: $cluster, stream: false}' > body.json - curl -fsS --retry 2 \ - -H "Authorization: Bearer $API_KEY" \ - -H "Content-Type: application/json" \ - --data-binary @body.json \ - "$RELAY_BASE_URL/api/holmes/$ACCOUNT_ID/chat" > response.json - # Log analysis for debugging; Holmes is expected to have posted the comment. - jq -r '.analysis // "(no analysis text returned)"' response.json - -Commit and push the workflow file. The next pull request opened against the repository will trigger the action, and HolmesGPT will post its review as a PR comment. - -Customizing the Review Prompt ------------------------------ - -The ``PROMPT`` environment variable controls what HolmesGPT checks. Edit it to match your team's review policy. For example: - -* Enforce coding standards or architecture rules. -* Cross-reference the change against runbooks, incident history, or documentation in Confluence/Notion. -* Validate that related Kubernetes manifests, Helm values, or Prometheus alert rules are consistent with the code changes. -* Require that PRs changing specific paths include tests. - -Whatever you put in the prompt, keep the instruction to post the review as a PR comment β€” otherwise Holmes will return the review only in the API response. - -Configuration Reference ------------------------ - -The action calls the :ref:`Holmes Chat API `. Any parameter supported by that endpoint (for example, ``model`` or ``additional_system_prompt``) can be added to the JSON body in the workflow. - -Troubleshooting ---------------- - -No comment appears on the PR - Check the action logs. The final step prints the ``analysis`` field returned by the API β€” if it contains a review but no comment was posted, the GitHub integration is not enabled for HolmesGPT. Re-check the `GitHub toolset guide `_. - -``401 Unauthorized`` - The ``ROBUSTA_API_KEY`` secret is missing, invalid, or lacks the **Robusta AI Write** capability. Regenerate the key in the Robusta Platform. - -``404 Not Found`` or cluster errors - The ``ROBUSTA_CLUSTER_ID`` secret does not match a cluster connected to your account. Copy the cluster ID from the Robusta Platform again. diff --git a/docs/configuration/github-actions/index.rst b/docs/configuration/github-actions/index.rst deleted file mode 100644 index ad2994f41..000000000 --- a/docs/configuration/github-actions/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -GitHub Actions -============== - -.. note:: - These integrations are available with the Robusta SaaS platform and self-hosted commercial plans. They are not available in the open-source version. - -Run HolmesGPT inside your GitHub workflows to automate code review and investigation directly from GitHub events. - -Available Actions ------------------ - -* :doc:`HolmesGPT PR Review `: Automatically review pull requests with HolmesGPT and post the review as a PR comment. diff --git a/docs/configuration/holmesgpt/holmes-chat-api.rst b/docs/configuration/holmesgpt/holmes-chat-api.rst deleted file mode 100644 index b085992bd..000000000 --- a/docs/configuration/holmesgpt/holmes-chat-api.rst +++ /dev/null @@ -1,558 +0,0 @@ -Holmes Chat API -=============== - -.. note:: - This feature is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version. - -Use this endpoint to send questions to Holmes AI for root cause analysis. You can provide alert context and Holmes will investigate and return a detailed markdown analysis. - -.. _holmes-chat-api: - -POST https://api.robusta.dev/api/holmes//chat ---------------------------------------------------------- - -URL Parameters -^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 20 10 70 10 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``account_id`` - - string - - The unique account identifier (found in the Robusta UI under **Settings** -> **General**). - - Yes - -Request Body -^^^^^^^^^^^^ - -.. list-table:: - :widths: 20 10 60 10 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``cluster_id`` - - string - - The cluster to query. If not provided, Holmes will try to extract it from the payload or use the single connected cluster. - - No - * - ``ask`` - - string - - The question to ask Holmes. - - Yes - * - ``payload`` - - object - - Alert payload or context data for Holmes to analyze (e.g., Prometheus alert labels). - - No - * - ``additional_system_prompt`` - - string - - Additional instructions to include in the system prompt. - - No - * - ``model`` - - string - - The AI model to use. If not provided, uses the account default. - - No - -Example Request -^^^^^^^^^^^^^^^ - -The following ``curl`` command demonstrates how to ask Holmes about a failing pod: - -.. robusta-code:: bash - - curl -X POST 'https://api.robusta.dev/api/holmes/ACCOUNT_ID/chat' \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer API-KEY' \ - --data '{ - "cluster_id": "my-cluster", - "ask": "Which pods are failing in the cluster?", - "payload": { - "alertname": "KubeContainerWaiting", - "container": "frontend", - "namespace": "production", - "pod": "frontend-59fbcd7965-drx6w", - "reason": "ContainerCreating", - "severity": "warning" - } - }' - -In the command, make sure to replace the following placeholders: - -- ``ACCOUNT_ID``: Your account ID, which can be found in the Robusta UI under **Settings** -> **General**. -- ``API-KEY``: Your API Key for authentication. You can generate this token in the platform by navigating to **Settings** -> **API Keys** -> **New API Key**, and creating a key with the "Robusta AI" resource and "Write" permission. - -Request Headers -^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Description - * - ``Content-Type`` - - Must be ``application/json``. - * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have "Robusta AI" resource with "Write" permission. - -Response Format -^^^^^^^^^^^^^^^ - -The API returns a JSON object containing the cluster ID and the analysis in markdown format. - -Example Response -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "cluster_id": "my-cluster", - "analysis": "## Investigation Summary\n\n### Failing Pods\n\n| Pod | Namespace | Status | Reason |\n|-----|-----------|--------|--------|\n| `frontend-59fbcd7965-drx6w` | production | Pending | ContainerCreating |\n\n**Root Cause**: Missing Secret - The pod is stuck because the secret `frontend-api-keys` does not exist.\n\n### Fix\n\n```bash\nkubectl create secret generic frontend-api-keys --from-literal=API_KEY= -n production\n```" - } - -Response Fields -^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 25 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``cluster_id`` - - string - - The cluster that was queried. - * - ``analysis`` - - string - - Holmes AI analysis in markdown format. Contains investigation findings, root cause analysis, and remediation steps. - -Handling the Markdown Response -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``analysis`` field contains markdown text with escaped newlines (``\n``). To render it properly: - -**Python:** - -.. code-block:: python - - import json - - response_data = json.loads(response.text) - markdown_text = response_data["analysis"] # Already unescaped by json.loads - print(markdown_text) # Renders with proper line breaks - -**JavaScript:** - -.. code-block:: javascript - - const data = JSON.parse(responseText); - const markdownText = data.analysis; // Already unescaped by JSON.parse - // Use a markdown renderer like marked.js or react-markdown - -**Bash (using jq):** - -.. code-block:: bash - - curl ... | jq -r '.analysis' # -r outputs raw string with actual newlines - -Error Responses -^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 15 30 55 - :header-rows: 1 - - * - Status - - Error - - Description - * - 400 - - Bad Request - - Invalid request body or could not determine cluster. - * - 401 - - Unauthorized - - Invalid or missing API key. - * - 403 - - Forbidden - - API key lacks required permissions. - * - 404 - - Not Found - - Specified cluster is not connected to this account. - * - 500 - - Internal Server Error - - Holmes request failed. - -Cluster Resolution -^^^^^^^^^^^^^^^^^^ - -If ``cluster_id`` is not provided in the request, Holmes will attempt to determine the cluster using the following logic: - -1. Extract from ``payload`` fields (``cluster_name``, ``cluster``, ``cluster_id``, ``source``, or from ``labels``/``annotations``). -2. Use AI to extract the cluster name from the payload content. -3. If only one cluster is connected to the account, use that cluster. - -If none of these methods succeed and multiple clusters are connected, the API will return an error listing the available clusters. - - -Streaming (SSE) Mode ---------------------- - -The same endpoint supports streaming responses via `Server-Sent Events (SSE) `_. -Instead of waiting for the full analysis, you receive a real-time stream of events as Holmes investigates β€” including tool calls, intermediate AI messages, and the final answer. - -To enable streaming, set ``stream`` to ``true`` in the request body. All other parameters remain the same. - -Example Streaming Request -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. robusta-code:: bash - - curl -N -X POST 'https://api.robusta.dev/api/holmes/ACCOUNT_ID/chat' \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer API-KEY' \ - --data '{ - "cluster_id": "my-cluster", - "ask": "Which pods are failing in the cluster?", - "stream": true, - "payload": { - "alertname": "KubeContainerWaiting", - "container": "frontend", - "namespace": "production", - "pod": "frontend-59fbcd7965-drx6w" - } - }' - -.. note:: - The ``-N`` flag disables output buffering in curl, which is important for seeing events as they arrive. - -Streaming Response Format -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The response has ``Content-Type: text/event-stream`` and uses the standard SSE wire format. Each event consists of an ``event`` line specifying the type, a ``data`` line containing a JSON payload, and a blank line: - -.. code-block:: text - - event: - data: - -Events are delivered in order as the investigation progresses. A typical stream looks like this: - -.. code-block:: text - - event: start_tool_calling - data: {"tool_name": "kubectl_find_resource", "id": "call_1"} - - event: tool_calling_result - data: {"tool_call_id": "call_1", "name": "kubectl_find_resource", "result": {"status": "success", "data": "..."}} - - event: ai_message - data: {"content": "I found a pod stuck in ContainerCreating state. Let me investigate further."} - - event: start_tool_calling - data: {"tool_name": "kubectl_describe_resource", "id": "call_2"} - - event: tool_calling_result - data: {"tool_call_id": "call_2", "name": "kubectl_describe_resource", "result": {"status": "success", "data": "..."}} - - event: token_count - data: {"metadata": {"usage": {"prompt_tokens": 1520, "completion_tokens": 305, "total_tokens": 1825}, ...}} - - event: ai_answer_end - data: {"analysis": "## Investigation Summary\n\nThe pod `frontend-59fbcd7965-drx6w` is stuck ..."} - -SSE Event Types -^^^^^^^^^^^^^^^ - -.. list-table:: - :widths: 22 78 - :header-rows: 1 - - * - Event Type - - Description - * - ``start_tool_calling`` - - Holmes has started executing a tool (e.g., a ``kubectl`` command). Useful for showing progress indicators. - * - ``tool_calling_result`` - - A tool call has completed. Contains the result or error information. - * - ``ai_message`` - - An intermediate text message from the AI while it is still investigating. These are partial thoughts, not the final answer. - * - ``ai_answer_end`` - - The final analysis. The ``analysis`` field contains the same markdown text you would receive from the non-streaming endpoint. **This is a terminal event** β€” no more events follow. - * - ``error`` - - An error occurred during the investigation. **This is a terminal event.** - * - ``token_count`` - - Token usage statistics for the request. - * - ``approval_required`` - - Holmes needs user approval before executing a potentially dangerous tool. See :ref:`approval-required-event` below. - -Event Payloads -^^^^^^^^^^^^^^ - -``start_tool_calling`` -"""""""""""""""""""""" - -Emitted when Holmes begins executing a tool. - -.. code-block:: json - - { - "tool_name": "kubectl_find_resource", - "id": "call_abc123" - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``id`` - - string - - Unique identifier for this tool call. Matches the ``tool_call_id`` of the corresponding ``tool_calling_result``. - * - ``tool_name`` - - string - - Name of the tool being executed. - -A human-readable description of the call (for example, the ``kubectl`` command it ran) arrives with the result, in the ``tool_calling_result`` event's ``description`` field. - -``tool_calling_result`` -""""""""""""""""""""""" - -Emitted when a tool call completes. - -.. code-block:: json - - { - "tool_call_id": "call_abc123", - "name": "kubectl_find_resource", - "result": { - "status": "success", - "data": "NAME READY STATUS RESTARTS AGE\nfrontend-59fbcd7965-drx6w 0/1 ContainerCreating 0 12m" - } - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``tool_call_id`` - - string - - Matches the ``id`` from the corresponding ``start_tool_calling`` event. - * - ``name`` - - string - - Name of the tool that was called. - * - ``description`` - - string - - Human-readable description of the call, such as the command it ran. - * - ``result`` - - object - - Result object with a ``status`` field (``"success"``, ``"error"``, ``"no_data"``, or ``"approval_required"``) and either a ``data`` field (on success) or an ``error`` field (on failure). - * - ``result_type`` - - string - - Optional. ``"txt"`` (default) or ``"png"`` for image results. - -``ai_message`` -"""""""""""""" - -Emitted when the AI produces intermediate text during its investigation. - -.. code-block:: json - - { - "content": "I found a pod stuck in ContainerCreating state. Let me check the events." - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``content`` - - string - - The text content of the AI's intermediate message. - -``ai_answer_end`` -""""""""""""""""" - -Emitted once when the investigation is complete. This is a **terminal event** β€” the stream ends after this. - -.. code-block:: json - - { - "analysis": "## Investigation Summary\n\n**Root Cause**: Missing Secret ..." - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``analysis`` - - string - - The complete analysis in markdown format. Identical to the ``analysis`` field in the non-streaming response. - -``error`` -""""""""" - -Emitted when an error occurs. This is a **terminal event** β€” the stream ends after this. - -.. code-block:: json - - { - "msg": "Failed to connect to cluster", - "error_code": "CLUSTER_ERROR" - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``msg`` - - string - - Human-readable error message. - * - ``error_code`` - - string - - Optional error code identifier. - -``token_count`` -""""""""""""""" - -Emitted with token usage statistics. - -.. code-block:: json - - { - "metadata": { - "usage": { - "prompt_tokens": 1520, - "completion_tokens": 305, - "total_tokens": 1825, - "cached_tokens": 0 - }, - "max_tokens": 1000000, - "max_output_tokens": 120000 - } - } - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``metadata.usage.prompt_tokens`` - - integer - - Input tokens of the last LLM call. - * - ``metadata.usage.completion_tokens`` - - integer - - Output tokens of the last LLM call. - * - ``metadata.usage.total_tokens`` - - integer - - Input plus output tokens of the last LLM call. - * - ``metadata.usage.cached_tokens`` - - integer - - Optional. Input tokens of the last LLM call served from the provider's prompt cache. - * - ``metadata.max_tokens`` - - integer - - Context window of the model. - * - ``metadata.max_output_tokens`` - - integer - - Maximum output tokens of the model. - -.. _approval-required-event: - -``approval_required`` -""""""""""""""""""""" - -Emitted when Holmes needs explicit user approval before executing a tool. This is a **terminal event** β€” the stream pauses until approval is granted. - -.. code-block:: json - - { - "conversation_history": [ - { - "role": "assistant", - "content": "I need to run a command that modifies resources.", - "tool_calls": [ - { - "id": "call_xyz789", - "pending_approval": true, - "function": { - "name": "kubectl_exec", - "arguments": "{\"command\": \"kubectl delete pod test-pod -n default\"}" - } - } - ] - } - ] - } - -.. list-table:: - :widths: 25 10 65 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``conversation_history`` - - array - - The full conversation history including the pending tool call. Assistant messages contain a ``tool_calls`` array where entries with ``"pending_approval": true`` are the tools awaiting approval. - -Consuming the Stream -^^^^^^^^^^^^^^^^^^^^ - -**Python (using requests):** - -.. robusta-code:: python - - import requests - import json - - response = requests.post( - "https://api.robusta.dev/api/holmes/ACCOUNT_ID/chat", - headers={ - "Content-Type": "application/json", - "Authorization": "Bearer API-KEY", - }, - json={ - "ask": "Which pods are failing on cluster prod-us?", - "stream": True, - }, - stream=True, - ) - response.raise_for_status() - - event_type = None - for line in response.iter_lines(decode_unicode=True): - if not line: - continue - if line.startswith("event: "): - event_type = line[7:] - elif line.startswith("data: ") and event_type: - data = json.loads(line[6:]) - if event_type == "ai_answer_end": - print("Final analysis:", data["analysis"]) - elif event_type == "ai_message": - print("AI:", data["content"]) - elif event_type == "start_tool_calling": - print(f"Running tool: {data['tool_name']}") - elif event_type == "error": - print(f"Error: {data['msg']}") - event_type = None diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index ce2dc56d9..a095e92df 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -11,47 +11,11 @@ Connect your monitoring system to Robusta, to enrich alerts and apply automation :maxdepth: 1 :hidden: - exporting/send-alerts-api - exporting/configuration-changes-api - alertmanager-integration/outofcluster-prometheus alertmanager-integration/alert-manager - alertmanager-integration/eks-managed-prometheus - alertmanager-integration/azure-managed-prometheus - alertmanager-integration/coralogix_managed_prometheus alertmanager-integration/embedded-prometheus alertmanager-integration/google-managed-prometheus - alertmanager-integration/google-managed-alertmanager - alertmanager-integration/grafana-self-hosted - alertmanager-integration/grafana-cloud alertmanager-integration/victoria-metrics - alertmanager-integration/dynatrace - alertmanager-integration/gcp-monitoring - alertmanager-integration/nagios - alertmanager-integration/newrelic - alertmanager-integration/pagerduty-alerting - alertmanager-integration/solarwinds alertmanager-integration/customize-labels-priorities - exporting/custom-webhooks - -Programmatic Integration -------------------------- - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`code;1em;` Send Alerts API - :class-card: sd-bg-light sd-bg-text-light - :link: exporting/send-alerts-api - :link-type: doc - - Send alerts programmatically via the legacy ``/api/alerts`` REST endpoint. - - .. grid-item-card:: :octicon:`code;1em;` Configuration Changes API - :class-card: sd-bg-light sd-bg-text-light - :link: exporting/configuration-changes-api - :link-type: doc - - Send configuration changes programmatically via the legacy REST endpoint. Prometheus & AlertManager -------------------------- @@ -59,31 +23,11 @@ Prometheus & AlertManager .. grid:: 1 1 2 3 :gutter: 3 - .. grid-item-card:: :octicon:`pulse;1em;` AlertManager - external - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/outofcluster-prometheus - :link-type: doc - .. grid-item-card:: :octicon:`pulse;1em;` AlertManager - in-cluster :class-card: sd-bg-light sd-bg-text-light :link: alertmanager-integration/alert-manager :link-type: doc - .. grid-item-card:: :octicon:`pulse;1em;` AWS Managed Prometheus - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/eks-managed-prometheus - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Azure Managed Prometheus - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/azure-managed-prometheus - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Coralogix - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/coralogix_managed_prometheus - :link-type: doc - .. grid-item-card:: :octicon:`pulse;1em;` Embedded Prometheus Stack :class-card: sd-bg-light sd-bg-text-light :link: alertmanager-integration/embedded-prometheus @@ -94,62 +38,11 @@ Prometheus & AlertManager :link: alertmanager-integration/google-managed-prometheus :link-type: doc - .. grid-item-card:: :octicon:`pulse;1em;` Google Managed Alertmanager - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/google-managed-alertmanager - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Grafana - Self-Hosted - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/grafana-self-hosted - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Grafana Cloud - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/grafana-cloud - :link-type: doc - .. grid-item-card:: :octicon:`pulse;1em;` VictoriaMetrics :class-card: sd-bg-light sd-bg-text-light :link: alertmanager-integration/victoria-metrics :link-type: doc -Other ------- - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` Dynatrace - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/dynatrace - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` GCP Cloud Monitoring - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/gcp-monitoring - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Nagios - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/nagios - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` New Relic - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/newrelic - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` PagerDuty - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/pagerduty-alerting - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` SolarWinds - :class-card: sd-bg-light sd-bg-text-light - :link: alertmanager-integration/solarwinds - :link-type: doc - Advanced --------- @@ -160,8 +53,3 @@ Advanced :class-card: sd-bg-light sd-bg-text-light :link: alertmanager-integration/customize-labels-priorities :link-type: doc - - .. grid-item-card:: :octicon:`plug;1em;` Other - Custom Webhooks - :class-card: sd-bg-light sd-bg-text-light - :link: exporting/custom-webhooks - :link-type: doc diff --git a/docs/configuration/metric-providers-aws.rst b/docs/configuration/metric-providers-aws.rst index cc763a9b3..1aea88afe 100644 --- a/docs/configuration/metric-providers-aws.rst +++ b/docs/configuration/metric-providers-aws.rst @@ -64,24 +64,6 @@ Quick Start .. code-block:: yaml - holmes: - serviceAccount: - annotations: - eks.amazonaws.com/role-arn: arn:aws:iam:::role/ - toolsets: - prometheus/metrics: - enabled: true - config: - prometheus_url: "https://aps-example-workspace.us-east-1.amazonaws.com/workspaces/ws-12345678" - aws_region: us-east-1 - aws_service_name: aps - prometheus_ssl_enabled: true - additional_labels: # Add cluster label to all queries - cluster: my_cluster_name - # Optional: Configure cross-account role assumption for AMP - # Set assume_role_arn if your Prometheus workspace is in a different AWS account - # than the one running your Kubernetes service account. - # assume_role_arn: arn:aws:iam:::role/ runnerServiceAccount: annotations: diff --git a/docs/configuration/metric-providers-coralogix.rst b/docs/configuration/metric-providers-coralogix.rst index 9e77c63da..8501b4b5e 100644 --- a/docs/configuration/metric-providers-coralogix.rst +++ b/docs/configuration/metric-providers-coralogix.rst @@ -48,5 +48,5 @@ Next Steps ---------- - Configure :doc:`alert routing ` -- Set up :doc:`Coralogix alerts integration ` +- Set up `Coralogix alerts integration `_ - Learn about :doc:`common configuration options ` \ No newline at end of file diff --git a/docs/configuration/metric-providers-external.rst b/docs/configuration/metric-providers-external.rst index 518679289..334224961 100644 --- a/docs/configuration/metric-providers-external.rst +++ b/docs/configuration/metric-providers-external.rst @@ -185,5 +185,5 @@ Next Steps ---------- - Configure :doc:`alert routing ` -- :robusta-url:`Set up AI-powered insights ` +- `Set up AI-powered insights `_ - Learn about :doc:`common configuration options ` \ No newline at end of file diff --git a/docs/configuration/metric-providers-google.rst b/docs/configuration/metric-providers-google.rst index deaf3bf0a..76dbbc728 100644 --- a/docs/configuration/metric-providers-google.rst +++ b/docs/configuration/metric-providers-google.rst @@ -93,6 +93,6 @@ Next Steps ---------- - Configure :doc:`alert routing ` -- Set up :doc:`Google Managed Alertmanager integration ` (recommended for GMP managed Alertmanager) +- Set up `Google Managed Alertmanager integration `_ (recommended for GMP managed Alertmanager) - Set up :doc:`Google Cloud alerting integration ` (legacy guide) - Learn about :doc:`common configuration options ` \ No newline at end of file diff --git a/docs/configuration/metric-providers-grafana-cloud.rst b/docs/configuration/metric-providers-grafana-cloud.rst index 29971bc04..ac71c7147 100644 --- a/docs/configuration/metric-providers-grafana-cloud.rst +++ b/docs/configuration/metric-providers-grafana-cloud.rst @@ -77,10 +77,6 @@ Make sure ``clusterName`` in Robusta Helm's values matches the ``cluster`` label clusterName: "production-us-east" -HolmesGPT Configuration ------------------------ - -Give HolmesGPT - Robusta's AI Agent - read access to metrics. See the `Grafana Cloud (Mimir) Configuration `_ guide. Next Steps ---------- diff --git a/docs/configuration/metric-providers-in-cluster.rst b/docs/configuration/metric-providers-in-cluster.rst index e3745214e..d2466138a 100644 --- a/docs/configuration/metric-providers-in-cluster.rst +++ b/docs/configuration/metric-providers-in-cluster.rst @@ -37,9 +37,11 @@ Verification After configuration, verify the connection: -**Using Robusta UI**: - -Open the Robusta UI, navigate to any application, and check if CPU/memory graphs are displayed. If graphs appear, the integration is working correctly. +**Check the runner logs**: + +.. code-block:: bash + + kubectl logs -n robusta deployment/robusta-runner | grep -i prometheus Advanced Configuration ---------------------- diff --git a/docs/configuration/metric-providers.rst b/docs/configuration/metric-providers.rst index dd58b939f..bd40520ff 100644 --- a/docs/configuration/metric-providers.rst +++ b/docs/configuration/metric-providers.rst @@ -27,7 +27,6 @@ When Robusta has access to your metrics it can help with: - **Alert Enrichment** - Automatically attach relevant graphs to alerts - **Historical Context** - Query past data to understand trends - **Alert Silencing** - Create and manage silences directly from Robusta -- **AI Insights** - Provide HolmesGPT with metrics for better root cause analysis Supported Providers ------------------- diff --git a/docs/configuration/resource-recommender.rst b/docs/configuration/resource-recommender.rst index 2fa56ec7e..a9cd98136 100644 --- a/docs/configuration/resource-recommender.rst +++ b/docs/configuration/resource-recommender.rst @@ -7,12 +7,11 @@ It gathers pod usage data from Prometheus and recommends requests and limits for Robusta can run KRR scans on a :ref:`schedule ` using playbooks. Because KRR is so popular, it has dedicated documentation here. You can: 1. Send weekly scan reports to Slack or other sinks via Robusta OSS (disabled by default, configure below) -2. View scans from all your clusters in the Robusta UI (enabled by default for UI users) Sending Weekly KRR Scan Reports to Slack =========================================== -With or without the UI, you can configure additional scans on a :ref:`schedule `. The results can be sent as a PDF to Slack. Follow the steps below to set it up +You can configure scans on a :ref:`schedule `. The results can be sent as a PDF to Slack. Follow the steps below to set it up 1. Install Robusta with Helm to your cluster and configure Slack sink. 2. Create your KRR slack playbook by adding the following to ``generated_values.yaml``: @@ -45,10 +44,6 @@ With or without the UI, you can configure additional scans on a :ref:`schedule < .. image:: /images/krr_slack_example.png :width: 1000px - .. md-tab-item:: Robusta UI - - .. image:: /images/krr_example.png - :width: 1000px Taints, Tolerations and NodeSelectors ============================================ @@ -67,11 +62,11 @@ To run KRR on an ARM cluster or on specific nodes you can set custom tolerations nodeSelector: nodeName: "your-selector" -Customizing Efficiency Recommendations in the Robusta UI +Customizing Efficiency Recommendations ==================================================================================== You can tweak KRR's recommendation algorithm to suit your environment using the ``krr_args`` setting in Robusta's Helm chart. -Add the following config to the top of your ``generated_values.yaml`` with your custom values. KRR will use these values every time it sends data to the Robusta UI or other destinations. +Add the following config to the top of your ``generated_values.yaml`` with your custom values. KRR will use these values every time it runs a scan. If you are having performance issues, specifically with Prometheus using a lot of memory, reduce ``max_workers`` to reduce memory usage. KRR uses 3 workers by default. @@ -81,9 +76,9 @@ If you are having performance issues, specifically with Prometheus using a lot o krr_args: "--cpu-min 15 --mem-min 200 --cpu_percentile 90 --memory_buffer_percentage 25" max_workers: 2 -Enabling HPA Recommendations in the Robusta UI +Enabling HPA Recommendations ------------------------------------------------------------ -To enable Horizontal Pod Autoscaler (HPA) recommendations in the Robusta UI, add the following to your ``generated_values.yaml`` file: +To enable Horizontal Pod Autoscaler (HPA) recommendations, add the following to your ``generated_values.yaml`` file: .. code-block:: yaml @@ -166,203 +161,6 @@ To enable KRR security context, add the following to your ``generated_values.yam -.. _krr-api: - -KRR API -====================================== - -You can retrieve KRR recommendations programmatically using the Robusta API. This allows you to integrate resource recommendations into your own tools and workflows. - - -Authentication ---------------------- - -The KRR API requires authentication via API key. - -To create your key, on the ``Robusta Platform``, go to the ``settings`` page, and choose the ``API keys`` tab. - -Click ``New API Key``. Choose a name for your key, and check the ``KRR Read`` capability. - -.. image:: /images/krr-api-key.png - :width: 500px - -GET /api/krr/recommendations ----------------------------------------------------- - -Retrieves KRR resource recommendations for a specific cluster and namespace. - -**Query Parameters** - -.. list-table:: - :widths: 20 15 40 15 - :header-rows: 1 - - * - Parameter - - Type - - Description - - Required - * - ``account_id`` - - STRING - - The account ID associated with the API key - - Yes - * - ``cluster_id`` - - STRING - - The cluster ID to get recommendations for - - Yes - * - ``namespace`` - - STRING - - The namespace to filter recommendations (optional) - - No - -**Request Headers** - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Header - - Value - * - ``Authorization`` - - ``Bearer `` - * - ``Content-Type`` - - ``application/json`` - -**Example Request** - -.. robusta-code:: bash - - curl -X GET "https://api.robusta.dev/api/krr/recommendations?account_id=YOUR_ACCOUNT_ID&cluster_id=my-cluster&namespace=default" \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -H "Content-Type: application/json" - -**Success Response (200 OK)** - -.. code-block:: json - - { - "cluster_id": "my-cluster", - "scan_id": "12345-67890-abcde", - "scan_date": "2024-01-07T12:00:00Z", - "scan_state": "success", - "results": [ - { - "cluster_id": "my-cluster", - "namespace": "default", - "name": "nginx-deployment", - "kind": "Deployment", - "container": "nginx", - "priority": "MEDIUM", - "current_cpu_request": 100, - "recommended_cpu_request": 50, - "current_cpu_limit": 500, - "recommended_cpu_limit": 200, - "current_memory_request": 134217728, - "recommended_memory_request": 67108864, - "current_memory_limit": 536870912, - "recommended_memory_limit": 268435456, - "pods_count": 3 - } - ] - } - -**Response Fields** - -.. list-table:: - :widths: 30 15 55 - :header-rows: 1 - - * - Field - - Type - - Description - * - ``cluster_id`` - - STRING - - The cluster ID for which recommendations were generated - * - ``scan_id`` - - STRING - - Unique identifier for this KRR scan - * - ``scan_date`` - - STRING - - Timestamp when the scan was completed (ISO 8601 format) - * - ``scan_state`` - - STRING - - State of the scan (e.g., "success") - * - ``results`` - - ARRAY - - Array of KRR recommendations for workloads - * - ``results[].cluster_id`` - - STRING - - Cluster ID of the workload - * - ``results[].namespace`` - - STRING - - Namespace of the workload - * - ``results[].name`` - - STRING - - Name of the Kubernetes workload - * - ``results[].kind`` - - STRING - - Type of Kubernetes resource (Deployment, StatefulSet, etc.) - * - ``results[].container`` - - STRING - - Container name within the workload - * - ``results[].priority`` - - STRING - - Priority level of the recommendation - * - ``results[].current_cpu_request`` - - NUMBER - - Current CPU request in millicores - * - ``results[].recommended_cpu_request`` - - NUMBER - - Recommended CPU request in millicores - * - ``results[].current_cpu_limit`` - - NUMBER - - Current CPU limit in millicores - * - ``results[].recommended_cpu_limit`` - - NUMBER - - Recommended CPU limit in millicores - * - ``results[].current_memory_request`` - - NUMBER - - Current memory request in bytes - * - ``results[].recommended_memory_request`` - - NUMBER - - Recommended memory request in bytes - * - ``results[].current_memory_limit`` - - NUMBER - - Current memory limit in bytes - * - ``results[].recommended_memory_limit`` - - NUMBER - - Recommended memory limit in bytes - * - ``results[].pods_count`` - - INTEGER - - Number of pods for this workload - -**Error Responses** - -**401 Unauthorized** - -.. code-block:: json - - { - "error": "Invalid or missing API key" - } - -**400 Bad Request** - -.. code-block:: json - - { - "msg": "Bad query parameters [error details]", - "error_code": "BAD_PARAMETER" - } - -**500 Internal Server Error** - -.. code-block:: json - - { - "msg": "Failed to query KRR recommendations", - "error_code": "UNEXPECTED_ERROR" - } - Reference ====================================== .. robusta-action:: playbooks.robusta_playbooks.krr.krr_scan on_schedule diff --git a/docs/configuration/sinks/RobustaUI.rst b/docs/configuration/sinks/RobustaUI.rst deleted file mode 100644 index 7ea3ba58d..000000000 --- a/docs/configuration/sinks/RobustaUI.rst +++ /dev/null @@ -1,103 +0,0 @@ -Robusta UI -################# - -The Robusta UI sink connects your Robusta installation to the Robusta SaaS platform, where you can investigate alerts with HolmesGPT, review timelines, and more. - -For the full list of platform features, see `home.robusta.dev `_. - - -Configuring the Robusta UI Sink ------------------------------------------------- - -.. tip:: - This guide is for users who have already installed Robusta on their cluster. If you haven't installed Robusta yet, we recommend starting by :robusta-url:`creating a free Robusta UI account β†— ` instead. - -Use the ``robusta`` CLI to generate a token: - -.. code-block:: - :name: cb-robusta-ui-sink-generate-token - - robusta integrations ui - -Add a new sink to your Helm values (``generated_values.yaml``), under ``sinksConfig``, with the token you generated: - -.. code-block:: bash - :name: cb-robusta-ui-sink-config-basic - - sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: - ttl_hours: 4380 - -Perform a :ref:`Helm Upgrade `. - -Handling Short-Lived Clusters in the UI -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - - This is a Robusta classic feature for Kubernetes monitoring and does not apply to HolmesGPT. - -By default, inactive Robusta clusters will be kept in the UI for 6 months **data retention**. (4380 hours) - -If you have many short-lived clusters, you can remove them from the UI automatically once they stop running. -To do so, configure a shorter retention period by setting the ``ttl_hours`` in the Robusta UI sink settings: - -.. code-block:: bash - :name: cb-robusta-ui-sink-config-ttl - - sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: - # automatically clean up old clusters in the UI if they are disconnected 12+ hours - ttl_hours: 12 - - -.. _cb-robusta-ui-sink-namespace-config: - -Monitoring Specific Resources in Namespaces -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - - This is a Robusta classic feature for Kubernetes monitoring and does not apply to HolmesGPT. - -By default, the Robusta UI sink discovers the standard resources in all namespaces using the standard discovery interval. -However, we have a configuration to monitor custom namespaced resources, and an API is exposed via the Robusta Backend to see how many of each resource you have in a namespace. - -To configure this, use the ``namespace_discovery_seconds`` and ``namespaceMonitoredResources`` settings in the Robusta UI sink: - -.. code-block:: bash - :name: cb-robusta-ui-sink-namespace-config-code - - sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: - # how often to re-scan for new namespaces (in seconds) - namespace_discovery_seconds: 3600 - # what resource types to actively count per namespace - namespaceMonitoredResources: - - apiGroup: "" - apiVersion: "v1" - kind: "Services" - - apiGroup: "apps" - apiVersion: "v1" - kind: "Deployments" - - apiGroup: "apps.openshift.io" - apiVersion: "v1" - kind: "DeploymentConfig" - - apiGroup: "batch" - apiVersion: "v1" - kind: "CronJob" - - apiGroup: "networking.k8s.io" - apiVersion: "v1" - kind: "Ingress" - - - -More Information about the UI -------------------------------------- -For more information on UI features, view `robusta.dev `_. diff --git a/docs/configuration/sinks/index.rst b/docs/configuration/sinks/index.rst index 4376a052a..0a271f1f7 100644 --- a/docs/configuration/sinks/index.rst +++ b/docs/configuration/sinks/index.rst @@ -44,11 +44,6 @@ Click a sink for setup instructions. :link: ms-teams-graph :link-type: doc - .. grid-item-card:: :octicon:`cpu;1em;` Robusta UI - :class-card: sd-bg-light sd-bg-text-light - :link: RobustaUI - :link-type: doc - .. grid-item-card:: :octicon:`cpu;1em;` Telegram :class-card: sd-bg-light sd-bg-text-light :link: telegram diff --git a/docs/configuration/sinks/ms-teams.rst b/docs/configuration/sinks/ms-teams.rst index e22e56c4f..aca1ccdac 100644 --- a/docs/configuration/sinks/ms-teams.rst +++ b/docs/configuration/sinks/ms-teams.rst @@ -6,13 +6,6 @@ MS Teams For new setups, we recommend connecting HolmesGPT to MS Teams instead of using this legacy sink. - Open the `MS Teams settings page `_ in the Robusta platform to connect HolmesGPT to MS Teams. This adds a single HolmesGPT bot that powers all of the flows below: - - - **Chat** β€” ``@mention`` the bot in any channel to investigate issues on demand; it replies in the thread. - - **Alerts** β€” let `Alerts Triage `_ automatically investigate incoming alerts and post the findings to MS Teams. - - **Custom events** β€” use :ref:`Triggered Workflows ` to react to arbitrary events and notify MS Teams. - - These are separate flows that share the same bot: chat is interactive, while Alerts Triage and Triggered Workflows run automatically. Robusta can report issues and events in your Kubernetes cluster to a MS Teams webhook. @@ -91,22 +84,6 @@ Example: webhook_url: teams-incoming-webhook # see instructions below webhook_override: ${annotations.kubernetes.io/service-name} -Redirect to Platform -------------------------------------------------------------------- - -By default, MS Teams notifications include buttons to view more information in the Robusta SaaS platform. -If you don't use Robusta SaaS you can modify these links to point at Prometheus instead. -To do so, set prefer_redirect_to_platform: false. - -For example: - -.. code-block:: yaml - - sinks_config: - - ms_teams_sink: - name: main_ms_teams_sink - webhook_url: teams-incoming-webhook - prefer_redirect_to_platform: false File Attachments ------------------------------------------------------------------- diff --git a/docs/configuration/sinks/slack.rst b/docs/configuration/sinks/slack.rst index 7c3696aec..2d3fd9d24 100644 --- a/docs/configuration/sinks/slack.rst +++ b/docs/configuration/sinks/slack.rst @@ -6,15 +6,8 @@ Slack For new setups, we recommend connecting HolmesGPT to Slack instead of using this legacy sink. - Open the `Slack settings page `_ in the Robusta platform to connect HolmesGPT to Slack. This adds a single HolmesGPT Slack bot that powers all of the flows below: - - **Chat** β€” ``@mention`` the bot in any channel to investigate issues on demand; it replies in the thread. - - **Alerts** β€” let `Alerts Triage `_ automatically investigate incoming alerts and post the findings to Slack. - - **Custom events** β€” use :ref:`Triggered Workflows ` to react to arbitrary events and notify Slack. - - These are separate flows that share the same bot: chat is interactive, while Alerts Triage and Triggered Workflows run automatically. - -Robusta can proxy Prometheus alerts to Slack, adding powerful features like :ref:`AI investigation `, :ref:`smart grouping ` and more. +Robusta can proxy Prometheus alerts to Slack, adding powerful features like :ref:`smart grouping ` and more. .. image:: /images/robusta-slack.png :width: 600px @@ -31,14 +24,7 @@ Robusta can send both Prometheus alerts and direct Kubernetes notifications (pod Quick Start ------------------------------------------------ -**Option 1: Automatic Setup (Recommended)** - -Sign up for a `free Robusta account `_ and connect Slack during the signup wizard. This automatically configures Slack using our `official -Slack app `_. -Note: Robusta can only write messages and doesn't require read permissions. - -**Option 2: Manual Configuration** Generate a Slack API key on your own (see :ref:`Creating Custom Slack Apps` below), then add it to your ``generated_values.yaml``: @@ -52,7 +38,6 @@ Generate a Slack API key on your own (see :ref:`Creating Custom Slack Apps` belo slack_channel: MY SLACK CHANNEL max_log_file_limit_kb: # (Default: 1000) The maximum allowed file size for "snippets" (in kilobytes) uploaded to the Slack channel. Larger files can be sent to Slack, but they may not be viewable directly within the Slack. channel_override: DYNAMIC SLACK CHANNEL OVERRIDE (Optional) - investigate_link: true/false # optional, if false no investigate links/buttons will be included in Slack messages .. warning:: @@ -121,12 +106,12 @@ Set the ``SLACK_FORWARD_URL`` environment variable on the Robusta Runner pod to Add the following to your ``values.yaml`` file and upgrade: -.. robusta-code:: yaml +.. code-block:: yaml runner: additional_env_vars: - name: SLACK_FORWARD_URL - value: "https://api.robusta.dev/slack/" + value: "https:///" Handling Slack Rate Limits @@ -154,24 +139,6 @@ of longer delays between a notification being generated and being delivered β€” retry waits for the ``Retry-After`` value returned by Slack (typically a few seconds, but can be longer under heavy throttling). -Redirect to Platform -------------------------------------------------------------------- - -By default, Slack notifications include buttons to view more information in the Robusta SaaS platform. -If you don't use Robusta SaaS you can modify these links to point at Prometheus instead. -To do so, set prefer_redirect_to_platform: false. - -For example: - -.. code-block:: yaml - - sinksConfig: - # slack integration params - - slack_sink: - name: main_slack_sink - api_key: xoxb-112... - slack_channel: my-fallback-channel - prefer_redirect_to_platform: false Using Private Channels diff --git a/docs/configuration/sinks/webex.rst b/docs/configuration/sinks/webex.rst index d82da7d5a..8ac818f8b 100644 --- a/docs/configuration/sinks/webex.rst +++ b/docs/configuration/sinks/webex.rst @@ -100,9 +100,6 @@ Configuration parameters * - ``send_to_default_if_missing`` - ``true`` - When overrides don't resolve, send to ``room_id`` (``true``) or drop the finding (``false``). - * - ``disable_platform_links`` - - ``false`` - - When ``true``, omits the Robusta platform ``Investigate`` and ``Silence`` links from messages. Dynamic Room Routing ------------------------------------------------ diff --git a/docs/configuration/sinks/webhook.rst b/docs/configuration/sinks/webhook.rst index 3b3c0f627..9d10bc1e1 100644 --- a/docs/configuration/sinks/webhook.rst +++ b/docs/configuration/sinks/webhook.rst @@ -68,7 +68,7 @@ JSON payload When ``format: json`` is set, the POST body is a JSON object with the following top-level fields: -.. robusta-code:: json +.. code-block:: json { "title": "CrashLoopBackOff", @@ -96,13 +96,9 @@ When ``format: json`` is set, the POST body is a JSON object with the following {"name": "Runbook", "url": "https://...", "type": null}, {"name": "Graph", "url": "https://...", "type": "prometheus_generator_url"} ], - "investigate": "https://platform.robusta.dev/...", - "silence": "https://platform.robusta.dev/silences/create?...", "enrichments": [ ... ] } -``investigate`` and ``silence`` are present only when the Robusta platform is enabled -(``silence`` additionally requires ``add_silence_url`` on the finding). If the serialized payload exceeds ``size_limit``, the largest field (``enrichments``) is dropped first so that core metadata and ``links`` survive truncation. diff --git a/docs/help.rst b/docs/help.rst index 5de4072ca..69bce454f 100644 --- a/docs/help.rst +++ b/docs/help.rst @@ -59,7 +59,7 @@ Problems when running ``helm install`` command or installing via GitOps. .. details:: at least one sink must be defined - Verify ``sinksConfig`` is defined in your Robusta values file, with at least one sink like Slack, Teams or Robusta UI ("robusta_sink"). If it's your first time installing, the fastest solution is to start configue creation from scratch. + Verify ``sinksConfig`` is defined in your Robusta values file, with at least one sink like Slack or Teams. If it's your first time installing, the fastest solution is to start configue creation from scratch. .. code-block:: bash @@ -115,36 +115,6 @@ Issues after installation when pods are running but not working correctly. kubectl get pods -A | grep robusta-runner # get the name and the namespace of the robusta pod kubectl logs -n # get the logs - .. details:: Discovery Error - - .. code-block:: - - 2023-04-17 23:37:43.019 ERROR Discovery process internal error - 2023-04-17 23:37:43.022 INFO Initialized new discovery pool - 2023-04-17 23:37:43.022 ERROR Failed to run publish discovery for robusta_ui_sink - Traceback (most recent call last): - File "/app/src/robusta/core/sinks/robusta/robusta_sink.py", line 175, in __discover_resources - results: DiscoveryResults = Discovery.discover_resources() - File "/app/src/robusta/core/discovery/discovery.py", line 288, in discover_resources - raise e - File "/app/src/robusta/core/discovery/discovery.py", line 280, in discover_resources - return future.result() - File "/usr/local/lib/python3.9/concurrent/futures/_base.py", line 446, in result - return self.__get_result() - File "/usr/local/lib/python3.9/concurrent/futures/_base.py", line 391, in __get_result - raise self._exception - concurrent.futures.process.BrokenProcessPool: A process in the process pool was terminated abruptly while the future was running or pending. - - This error might be due to memory issues. Increase the memory request in Robusta's Helm values: - - .. code-block:: yaml - - runner: - resources: - requests: - memory: 2048Mi - limits: - memory: 2048Mi .. details:: Blocked by firewall / HTTP proxy @@ -177,38 +147,6 @@ Issues after installation when pods are running but not working correctly. --set kube-prometheus-stack.prometheus.prometheusSpec.storageSpec.volumeClaimTemplate.spec.resources.requests.storage=10Gi \ --set kube-prometheus-stack.prometheus.prometheusSpec.resources.requests.memory=512Mi -Holmes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. details:: Error in Holmes: binascii.a2b_base64(s, strict_mode=validate) - - If the Holmes pod fail to start, with this exception: - - .. code-block:: - - 2024-09-20 15:37:57.961 INFO loading config /etc/robusta/config/active_playbooks.yaml - Traceback (most recent call last): - File "/app/server.py", line 65, in - dal = SupabaseDal() - ^^^^^^^^^^^^^ - File "/app/holmes/core/supabase_dal.py", line 38, in __init__ - self.enabled = self.__init_config() - ^^^^^^^^^^^^^^^^^^^^ - File "/app/holmes/core/supabase_dal.py", line 68, in __init_config - robusta_token = self.__load_robusta_config() - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - File "/app/holmes/core/supabase_dal.py", line 61, in __load_robusta_config - return RobustaToken(**json.loads(base64.b64decode(token))) - ^^^^^^^^^^^^^^^^^^^^^^^ - File "/usr/local/lib/python3.11/base64.py", line 88, in b64decode - return binascii.a2b_base64(s, strict_mode=validate) - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - binascii.Error: Invalid base64-encoded string: number of data characters (21) cannot be 1 more than a multiple of 4 - - - It's often because the ``Robusta UI Token`` is pulled from a secret, and Holmes cannot read it. - - See :ref:`Using Existing Secrets ` to configure Holmes to read the ``token`` Phase 3: Integration Issues ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -258,9 +196,6 @@ Alert Manager is not working Receiver url has namespace TBD - .. tip:: - - If you're using the Robusta UI, you can test alert routing by :robusta-url:`Simulating an alert `. diff --git a/docs/how-it-works/architecture.rst b/docs/how-it-works/architecture.rst deleted file mode 100644 index 0cef5e512..000000000 --- a/docs/how-it-works/architecture.rst +++ /dev/null @@ -1,62 +0,0 @@ -Architecture -================== - -Robusta uses `HolmesGPT `_ to automatically investigate and root-cause alerts. HolmesGPT runs as part of the **in-cluster Agent**, connects to your existing **data sources**, and reports findings through the **Robusta Platform** (SaaS or self-hosted). - -.. image:: ../images/architecture-overview.png - :width: 800 - :align: center - -| - -Agent (In-Cluster) -^^^^^^^^^^^^^^^^^^^ - -The Robusta Agent runs inside your Kubernetes cluster. It includes HolmesGPT and is responsible for: - -- Fetching data from external `data sources `_ -- Optional: tracking Kubernetes deploys, changes, and events for teams troubleshooting Kubernetes itself - -The Agent keeps your data secure β€” it fetches data from your data sources directly, so there is no direct connection from the Robusta Platform to your data sources. - -Robusta Platform -^^^^^^^^^^^^^^^^^ - -The Robusta Platform is a centralized place to control your SRE agents and chat with them. It is available as **SaaS** (hosted by Robusta) or **self-hosted** (for enterprise deployments). - -The Platform receives investigation results from HolmesGPT and provides: - -- AI-powered root cause analysis results for every alert -- Centralized alert management and triage -- Historical alert analysis and timelines -- HolmesGPT Slack and Teams bot β€” tag the AI agent like a teammate to investigate issues on demand - -Data Sources -^^^^^^^^^^^^^ - -HolmesGPT integrates with a wide range of `data sources `_ in your environment to gather evidence during investigations. - -All data source connections are made by the Agent within your environment. The Robusta Platform never connects to your data sources directly. - -Security & Networking -^^^^^^^^^^^^^^^^^^^^^ - -- The Agent runs entirely within your cluster with configurable RBAC permissions -- Data sources are accessed only by the in-cluster Agent, never by the Platform -- SaaS connectivity is outbound-only β€” no inbound access is required - -Next Steps -^^^^^^^^^^ - -:robusta-url:`Ready to install Robusta? Get started. ` - -.. _Robusta Classic: - ----- - -A Note on Robusta Classic -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You may see references to "Robusta Classic" in parts of this documentation. Robusta Classic is the original open source alert engine that provides deterministic, rule-based enrichment using configurable playbooks β€” automatically attaching pod logs, resource state, and related events to alerts before routing them to Slack, Teams, PagerDuty, and :doc:`other notification channels <../configuration/configuring-sinks>`. - -Robusta Classic can be installed as part of the Agent and runs alongside HolmesGPT, if you like. diff --git a/docs/how-it-works/coverage.rst b/docs/how-it-works/coverage.rst deleted file mode 100644 index 65288de8b..000000000 --- a/docs/how-it-works/coverage.rst +++ /dev/null @@ -1,65 +0,0 @@ -Insights Coverage -#################################### - -Robusta's monitors these alerts and errors by default. It finds insights and suggests fixes. - -.. warning:: - - This page is under construction! Current contents are incomplete. - -Prometheus Alerts ----------------------- - -* CPUThrottlingHigh - show the reason and how to fix it -* HostOomKillDetected - show which pods were killed -* KubeNodeNotReady - show node resources and effected pods -* HostHighCpuLoad - show CPU usage analysis -* KubernetesDaemonsetMisscheduled - flag known false positives and suggest fixes -* KubernetesDeploymentReplicasMismatch - show the deployment's status -* NodeFilesystemSpaceFillingUp - show disk usage - -.. warning:: - - You must send your Prometheus alerts to Robusta by webhook for these to work. See :doc:`AlertManager Integration `. - -Other errors ----------------- - -These are identified by listening to the API Server: - -* CrashLoopBackOff -* ImagePullBackOff -* Node NotReady - -Additionally, all Kubernetes Events (``kubectl get events``) of WARNING level and above are sent to the Robusta UI. - -Change Tracking ----------------- - -By default all changes to Deployments, DaemonSets, and StatefulSets are sent to the Robusta UI for correlation -with Prometheus alerts and other errors. - -These changes are not sent to other sinks (e.g. Slack) by default because they are spammy. See :doc:`Notification Routing ` to learn how to selectively track changes you care about in Slack as well. - -We also wrote a blog post `Why everyone should track Kubernetes changes and top four ways to do so `_ - -Optional add-ons ---------------------------- - -These have the potential to be spammy so they aren't enabled by default. - -We will enable them once we finish the fine-tuning. Until them, you can enable them yourself. - -.. robusta-action:: playbooks.robusta_playbooks.autoscaler.alert_on_hpa_reached_limit - - -.. - these are all commented out for now - no point in showing how they're configured as it doesn't add anything - this is an RST comment BTW as are the lines below - .. robusta-action:: playbooks.robusta_playbooks.node_enrichments.node_health_watcher - .. robusta-action:: playbooks.robusta_playbooks.restart_loop_reporter.restart_loop_reporter - .. robusta-action:: playbooks.robusta_playbooks.cpu_throttling.cpu_throttling_analysis_enricher - .. robusta-action:: playbooks.robusta_playbooks.image_pull_backoff_enricher.image_pull_backoff_reporter - .. robusta-action:: playbooks.robusta_playbooks.oom_killer.oom_killer_enricher - .. robusta-action:: playbooks.robusta_playbooks.daemonsets.daemonset_misscheduled_analysis_enricher - .. robusta-action:: playbooks.robusta_playbooks.daemonsets.daemonset_misscheduled_smart_silencer diff --git a/docs/how-it-works/index.rst b/docs/how-it-works/index.rst deleted file mode 100644 index 3e2c069d2..000000000 --- a/docs/how-it-works/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -:hide-toc: - -Overview -==================== - -.. grid:: 1 1 2 3 - :gutter: 2 - - .. grid-item-card:: :octicon:`cpu;1em;` Architecture - :class-card: sd-bg-text-light - :link: architecture - :link-type: doc - - How Robusta's components work together β€” the Agent, HolmesGPT, data sources, and the Platform. - - .. grid-item-card:: :octicon:`package;1em;` Deployment Options - :class-card: sd-bg-light sd-bg-text-light - :link: oss-vs-saas - :link-type: doc - - SaaS, self-hosted, or open source HolmesGPT. - -.. toctree:: - :maxdepth: 1 - :hidden: - - Architecture - Deployment Options diff --git a/docs/how-it-works/oss-vs-saas.rst b/docs/how-it-works/oss-vs-saas.rst deleted file mode 100644 index b70f3c96f..000000000 --- a/docs/how-it-works/oss-vs-saas.rst +++ /dev/null @@ -1,49 +0,0 @@ -Deployment Options -################################ - -Robusta is delivered through the **Robusta Platform** β€” a centralized place to control your SRE agents, triage alerts, and review investigation timelines. The Platform is available as **SaaS** (hosted by Robusta) or **Self-Hosted** (for organizations with dedicated infrastructure requirements). - -SaaS (Hosted) -^^^^^^^^^^^^^^ - -The hosted Platform runs in Robusta's infrastructure. You install the in-cluster Agent, sign up at :robusta-url:`platform.robusta.dev `, and your alerts and investigations stream into the hosted UI. - -The SaaS Platform is **SOC 2 compliant** and available in multiple regions, including the **US**, **EU**, and **Asia Pacific**. - -Most teams use SaaS β€” it's the fastest path to the complete feature set. - -Self-Hosted -^^^^^^^^^^^^ - -The same Platform, deployed inside your own infrastructure. Intended for organizations that require dedicated infrastructure (regulatory, data residency, or air-gapped requirements). - -Self-hosted deployments are available on enterprise plans β€” contact support@robusta.dev. - -Pricing -^^^^^^^^^^^^ - -The SaaS Platform is `free to get started `_, with paid tiers for larger teams and advanced features. Self-hosted deployments require an enterprise plan. - -Open Source -^^^^^^^^^^^^ - -`HolmesGPT `_ β€” the SRE agent at the core of Robusta β€” is MIT-licensed and a CNCF sandbox project. - -Standalone HolmesGPT: - -- CLI only β€” no web UI -- HTTP API for programmatic access - -The Robusta Platform (SaaS or Self-Hosted) adds on top: - -- A web interface -- HolmesGPT bots for Slack and Microsoft Teams -- Automatic alert triage and grouping -- Background agents that proactively investigate and surface issues - -Robusta Classic -^^^^^^^^^^^^^^^^ - -Before HolmesGPT, Robusta's open source engine focused on rule-based automation β€” enriching alerts with extra context (logs, pod status, resource graphs) and routing them to Slack, Teams, and other sinks using configurable playbooks. This is sometimes referred to as **Robusta Classic**. - -If you are running Robusta Classic, upgrading to HolmesGPT is a configuration change β€” no migration required. diff --git a/docs/images/architecture-overview.png b/docs/images/architecture-overview.png deleted file mode 100644 index e822b22c3..000000000 Binary files a/docs/images/architecture-overview.png and /dev/null differ diff --git a/docs/images/crd_demo.png b/docs/images/crd_demo.png deleted file mode 100644 index c2159a128..000000000 Binary files a/docs/images/crd_demo.png and /dev/null differ diff --git a/docs/images/grafana-alertmanager-contact-point.png b/docs/images/grafana-alertmanager-contact-point.png deleted file mode 100644 index 9139be56d..000000000 Binary files a/docs/images/grafana-alertmanager-contact-point.png and /dev/null differ diff --git a/docs/images/grafana-alertmanager-post.png b/docs/images/grafana-alertmanager-post.png deleted file mode 100644 index 8d36e1675..000000000 Binary files a/docs/images/grafana-alertmanager-post.png and /dev/null differ diff --git a/docs/images/grafana-alertmanager-robusta-ui.png b/docs/images/grafana-alertmanager-robusta-ui.png deleted file mode 100644 index f179ed261..000000000 Binary files a/docs/images/grafana-alertmanager-robusta-ui.png and /dev/null differ diff --git a/docs/images/grafana-alertmanager-test.png b/docs/images/grafana-alertmanager-test.png deleted file mode 100644 index 176574e75..000000000 Binary files a/docs/images/grafana-alertmanager-test.png and /dev/null differ diff --git a/docs/images/grafana-alertmanager-url.png b/docs/images/grafana-alertmanager-url.png deleted file mode 100644 index e86d4ad3b..000000000 Binary files a/docs/images/grafana-alertmanager-url.png and /dev/null differ diff --git a/docs/images/grafana-docs-robusta-ui.png b/docs/images/grafana-docs-robusta-ui.png deleted file mode 100644 index d6a31c5be..000000000 Binary files a/docs/images/grafana-docs-robusta-ui.png and /dev/null differ diff --git a/docs/images/grafana-send-resolved.png b/docs/images/grafana-send-resolved.png deleted file mode 100644 index a7661eef6..000000000 Binary files a/docs/images/grafana-send-resolved.png and /dev/null differ diff --git a/docs/images/helm-release-deployed.png b/docs/images/helm-release-deployed.png deleted file mode 100644 index 62a49954b..000000000 Binary files a/docs/images/helm-release-deployed.png and /dev/null differ diff --git a/docs/images/helm-release-failed.png b/docs/images/helm-release-failed.png deleted file mode 100644 index 62d778f52..000000000 Binary files a/docs/images/helm-release-failed.png and /dev/null differ diff --git a/docs/images/helm-release-unhealthy.png b/docs/images/helm-release-unhealthy.png deleted file mode 100644 index 28894f1ee..000000000 Binary files a/docs/images/helm-release-unhealthy.png and /dev/null differ diff --git a/docs/images/holmes-pr-review-example.png b/docs/images/holmes-pr-review-example.png deleted file mode 100644 index eafa6f12d..000000000 Binary files a/docs/images/holmes-pr-review-example.png and /dev/null differ diff --git a/docs/images/krr-api-key.png b/docs/images/krr-api-key.png deleted file mode 100644 index a9b9f5479..000000000 Binary files a/docs/images/krr-api-key.png and /dev/null differ diff --git a/docs/images/krr_example.png b/docs/images/krr_example.png deleted file mode 100644 index 1fec5a417..000000000 Binary files a/docs/images/krr_example.png and /dev/null differ diff --git a/docs/images/new-api-key.png b/docs/images/new-api-key.png deleted file mode 100644 index e1a0267bf..000000000 Binary files a/docs/images/new-api-key.png and /dev/null differ diff --git a/docs/images/robusta-api-keys.png b/docs/images/robusta-api-keys.png deleted file mode 100644 index 1fda07556..000000000 Binary files a/docs/images/robusta-api-keys.png and /dev/null differ diff --git a/docs/images/robusta-contact-point-1.png b/docs/images/robusta-contact-point-1.png deleted file mode 100644 index 91944f101..000000000 Binary files a/docs/images/robusta-contact-point-1.png and /dev/null differ diff --git a/docs/images/robusta-contact-point-2.png b/docs/images/robusta-contact-point-2.png deleted file mode 100644 index c098830ae..000000000 Binary files a/docs/images/robusta-contact-point-2.png and /dev/null differ diff --git a/docs/images/robusta-metrics.png b/docs/images/robusta-metrics.png deleted file mode 100644 index 038dec334..000000000 Binary files a/docs/images/robusta-metrics.png and /dev/null differ diff --git a/docs/images/robusta-new-notification-policy.png b/docs/images/robusta-new-notification-policy.png deleted file mode 100644 index 6d8b9fa63..000000000 Binary files a/docs/images/robusta-new-notification-policy.png and /dev/null differ diff --git a/docs/images/robusta-ui-alerts-ui.gif b/docs/images/robusta-ui-alerts-ui.gif deleted file mode 100644 index 950e0478b..000000000 Binary files a/docs/images/robusta-ui-alerts-ui.gif and /dev/null differ diff --git a/docs/images/robusta-ui-simulate-alert-1.png b/docs/images/robusta-ui-simulate-alert-1.png deleted file mode 100644 index 5a6b6ec7b..000000000 Binary files a/docs/images/robusta-ui-simulate-alert-1.png and /dev/null differ diff --git a/docs/images/robusta-ui-simulate-alert-2.png b/docs/images/robusta-ui-simulate-alert-2.png deleted file mode 100644 index ef8497a70..000000000 Binary files a/docs/images/robusta-ui-simulate-alert-2.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index 2992d27da..cf3891170 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,84 +6,32 @@ :hidden: self - how-it-works/architecture - how-it-works/oss-vs-saas -.. toctree:: - :maxdepth: 4 - :caption: Installation - :hidden: - - setup-robusta/index - -.. toctree:: - :maxdepth: 4 - :caption: HTTP APIs - :hidden: +Robusta Classic +==================== - Overview - Holmes Chat API - configuration/exporting/platform-mcp-api - configuration/exporting/llm-models-api - configuration/exporting/send-events-api - configuration/exporting/alert-export-api - configuration/exporting/alert-statistics-api - configuration/exporting/rbac-api +Robusta is an open source runner that monitors your Kubernetes cluster, enriches alerts with context, and sends them to your notification sinks. .. toctree:: :maxdepth: 4 - :caption: GitHub Actions - :hidden: + :caption: Installation - Overview - HolmesGPT PR Review + setup-robusta/index .. toctree:: :maxdepth: 4 :caption: Robusta Classic - :hidden: Send Alerts to Robusta - Track Config Changes Connect Metrics Notification Sinks Alert Routing - CRDs Monitoring Playbooks Self-Monitoring - Managed Prometheus Alerts Cost Savings (KRR) - Namespace Resources API - Prometheus Query API .. toctree:: :maxdepth: 4 :caption: Help - :hidden: help - -Welcome to Robusta -==================== - -Robusta is an AI-powered SRE agent that automatically investigates alerts and finds root causes. It is built on `HolmesGPT `_. - -**How it works:** - -* **Automatic investigation** β€” every alert is analyzed with AI-powered root cause analysis -* **Your data sources** β€” HolmesGPT connects to your existing monitoring, ITSM, cloud tools, and MCP servers to gather evidence -* **Chat with your agent** β€” tag HolmesGPT in Slack or Teams to investigate issues on demand -* **Centralized control** β€” the `Robusta Platform `_ gives you a single place to manage your SRE agents, triage alerts, and review investigation timelines - -Robusta is available as **SaaS**, **self-hosted**, or **open source**. See :doc:`how-it-works/oss-vs-saas` for details. - -Ready to get started? ---------------------- - -.. robusta-region-picker:: - -.. button-link:: https://platform.robusta.dev/signup - :color: primary - :outline: - - Get Started β†’ diff --git a/docs/notification-routing/configuring-sinks.rst b/docs/notification-routing/configuring-sinks.rst index aadfa83ad..64af8cdc0 100644 --- a/docs/notification-routing/configuring-sinks.rst +++ b/docs/notification-routing/configuring-sinks.rst @@ -13,7 +13,6 @@ Defining Sinks ../configuration/sinks/slack ../configuration/sinks/ms-teams ../configuration/sinks/ms-teams-graph - ../configuration/sinks/RobustaUI ../configuration/sinks/telegram ../configuration/sinks/discord ../configuration/sinks/DataDog @@ -136,7 +135,6 @@ By default, when Robusta fails to initialize any of the Sinks, it will not start On some scenarios, you may want to ignore Sinks initialization errors. -For example, if Robusta is not allowed to connect to Slack, but you still want to receive notifications on the Robusta UI. In order to enable that, add the below to ``globalConfig`` in your ``generated_values.yaml`` file: diff --git a/docs/notification-routing/routing-with-scopes.rst b/docs/notification-routing/routing-with-scopes.rst index 966be353a..1983a869b 100644 --- a/docs/notification-routing/routing-with-scopes.rst +++ b/docs/notification-routing/routing-with-scopes.rst @@ -277,7 +277,7 @@ Testing Alert Routing ---------------------- .. tip:: - Use the Robusta UI to test your alert routing rules by :robusta-url:`simulating an alert `. + Test your alert routing rules by sending a test alert with ``robusta demo-alert``. Scope Reference ----------------- diff --git a/docs/playbook-reference/actions/develop-actions/my-first-custom-action.rst b/docs/playbook-reference/actions/develop-actions/my-first-custom-action.rst index c4c086891..a42ea5888 100644 --- a/docs/playbook-reference/actions/develop-actions/my-first-custom-action.rst +++ b/docs/playbook-reference/actions/develop-actions/my-first-custom-action.rst @@ -63,8 +63,6 @@ To investigate you look at the event log: Aha! "1 node(s) didn't match Pod's node affinity/selector." ALRIGHT! -.. note:: - You can see this event on an informative timeline in `Robusta UI `_. Check it out! Wait, what does it mean? πŸ˜– (Hint: Check the YAML config for the spoiler) diff --git a/docs/playbook-reference/actions/miscellaneous.rst b/docs/playbook-reference/actions/miscellaneous.rst index 889a6dcce..41b673f58 100644 --- a/docs/playbook-reference/actions/miscellaneous.rst +++ b/docs/playbook-reference/actions/miscellaneous.rst @@ -38,78 +38,3 @@ Stress Testing and Chaos Engineering Adding Slack user/group mentions to k8s/Prometheus events --------------------------------------------------------- .. robusta-action:: playbooks.robusta_playbooks.alerts_integration.mention_enricher - -Robusta Platform Triggered Workflows ---------------------------------------------------------- - -.. robusta-action:: playbooks.robusta_playbooks.workflow_trigger.trigger_workflow on_prometheus_alert - -.. robusta-action:: playbooks.robusta_playbooks.workflow_trigger.trigger_workflow_event on_deployment_rollout_complete - -Run a workflow after every Deployment rollout -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pair ``trigger_workflow_event`` with :ref:`on_deployment_rollout_complete` -to have Holmes check each release once all its pods run the new version, with no CI/CD integration. -Add :ref:`on_deployment_rollout_failure` to also run it when a rollout gets stuck: - -.. code-block:: yaml - - customPlaybooks: - - name: "WorkflowOnRollout" - triggers: - - on_deployment_rollout_complete: - namespace_prefix: payments - - on_deployment_rollout_failure: - namespace_prefix: payments - actions: - - trigger_workflow_event: - workflow_id: "b7f9d2e4-1234-4c56-9abc-0123456789ab" - api_key: "{{ env.ROBUSTA_PLATFORM_API_KEY }}" - -The workflow receives a payload like the one below. ``trigger`` and the ``subject`` fields are handy for -workflow filters (e.g. ``namespace`` = ``payments``). ``description`` says whether the rollout completed or -failed, and ``resource`` is the Deployment's current manifest (Secret values are always redacted). -``rollout`` names the revision that fired: its revision number, the ReplicaSet running it and the image of -each container. On a Deployment update the controller hasn't processed yet, ``revision`` and ``replicaset`` -are ``null``, because the new revision doesn't exist yet. With triggers that set ``change_filters`` (e.g. ``on_deployment_update``), the payload also -carries a ``diff`` of the fields those filters kept. - -.. code-block:: json - - { - "cluster_name": "prod-eu-1", - "event": { - "trigger": "DeploymentChangeEvent", - "subject": {"kind": "deployment", "name": "checkout-api", "namespace": "payments", "node": null, - "labels": {"app": "checkout-api", "team": "payments"}}, - "operation": "update", - "description": "Rollout of Deployment `checkout-api` in namespace `payments` completed", - "rollout": {"revision": "7", "replicaset": "checkout-api-5f6b86d797", - "images": {"app": "registry.example.com/checkout-api:2.14.0"}}, - "resource": {"apiVersion": "apps/v1", "kind": "Deployment", "metadata": {"...": "..."}, - "spec": {"...": "..."}, "status": {"...": "..."}} - } - } - -The workflow's investigation looks at the cluster as it is when the run starts, not as it was when the -rollout completed. If another rollout of the same Deployment lands in between (a quick fix-forward, or a -``rollout undo`` right after a failure), the investigation sees the newer revision. Have the workflow -prompt judge the revision in ``rollout`` instead. The Deployment keeps its old ReplicaSets -(``revisionHistoryLimit``), so the ReplicaSet and its events can still be checked, though its pods are gone -once it is scaled down. For example: - -.. code-block:: text - - A Deployment rollout just completed or failed; the trigger payload names it in `rollout`. - Judge that revision: the pods of the ReplicaSet in `rollout.replicaset` running the images in - `rollout.images`. Check that they are running and ready, and look for restarts, warning events - and error logs. If the Deployment has since moved to another revision, say so and judge the - revision in the payload from what remains: the ReplicaSet's status and the events of it and - its pods. End with exactly one word, the verdict for the revision in the payload rather than the - current one: healthy / degraded / failed, or unknown if what remains is not enough to tell. - -Each cluster's runner triggers the workflow for its own rollouts, so a release rolled out to five clusters -runs the workflow five times, each against its own cluster. To run it once per release, add the playbook -only to the cluster you deploy to first. Set ``rate_limit_seconds`` to also cap how often a single -Deployment can trigger it. \ No newline at end of file diff --git a/docs/playbook-reference/actions/scans.rst b/docs/playbook-reference/actions/scans.rst index 691955a29..b76395beb 100644 --- a/docs/playbook-reference/actions/scans.rst +++ b/docs/playbook-reference/actions/scans.rst @@ -6,7 +6,6 @@ Robusta includes built-in actions to scan and get insights on Kubernetes cluster These actions can be triggered: * Automatically, on a schedule. -* On demand, via the Robusta UI. * On demand, via :ref:`cli command `. There are two built-in: KRR and Popeye. diff --git a/docs/playbook-reference/index.rst b/docs/playbook-reference/index.rst index 241995d30..c71db435d 100644 --- a/docs/playbook-reference/index.rst +++ b/docs/playbook-reference/index.rst @@ -18,7 +18,7 @@ Playbooks Basics Playbooks are deterministic rules for responding to alerts and unhealthy conditions in a Kubernetes cluster. -Playbooks are recommended for advanced use cases. Most users should start with the :robusta-url:`Robusta SRE Agent `, which requires far less configuration. +Playbooks are recommended for advanced use cases. Most users should start with the `Robusta SRE Agent `_, which requires far less configuration. How Playbooks Work ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/playbook-reference/logs-triggers/index.rst b/docs/playbook-reference/logs-triggers/index.rst index 8bf68831c..05f076c3e 100644 --- a/docs/playbook-reference/logs-triggers/index.rst +++ b/docs/playbook-reference/logs-triggers/index.rst @@ -360,7 +360,6 @@ Wait a few minutes (typically up to 5) for the alert to fire. This delay is due Once the alert fires, you’ll see the ``MySqlConnectionErrors`` alert in: -- The Robusta UI (if installed) - Slack, Microsoft Teams, or your configured destination .. image:: /images/mysql-connection-error-alert.png diff --git a/docs/playbook-reference/triggers/elasticsearch.rst b/docs/playbook-reference/triggers/elasticsearch.rst deleted file mode 100644 index 57ba1fd26..000000000 --- a/docs/playbook-reference/triggers/elasticsearch.rst +++ /dev/null @@ -1,86 +0,0 @@ -Elasticsearch -######################### - -Robusta actions can run in response to `Elasticsearch/Kibana watchers `_ -by using `Elasticsearch webhook actions `_. - -A common use case is gathering troubleshooting data with Robusta when pods write specific error logs. - -Robusta Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. The Robusta-relay must be enabled so that it can route Elasticsearch webhooks to the appropriate Robusta runner -2. The following variables must be defined in your ``generated_values.yaml`` file: - -.. code-block:: yaml - - globalConfig: - account_id: "" # your official Robusta account_id - signing_key: "" # a secret key used to verify the identity of Elasticsearch - -You do **not** define playbooks for Elasticsearch triggers in ``generated_values.yaml``. Instead the playbook is defined -entirely on the Elasticsearch side. - -Example Elasticsearch Watcher -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following Elasticsearch Watcher configuration will trigger a Robusta playbook. -Make sure you update ````, ````, and ```` in the emphasized line. -These should match the Robusta Helm chart values. - -.. robusta-code:: json - :emphasize-lines: 26,27,33 - - { - "trigger": { - "schedule": { - "interval": "30m" - } - }, - "input": { - "simple": { - "str": "val1", - "obj": { - "str": "val2" - }, - "num": 23 - } - }, - "condition": { - "always": {} - }, - "actions": { - "robusta_webhook": { - "throttle_period_in_millis": 0, - "transform": { - "script": { - "source": """ - return ['body' : - ['account_id' : 'some_account', - 'cluster_name' : 'gke_arabica-300319_us-central1-c_cluster-5', - 'origin' : 'elasticsearch', - 'action_name' : 'echo', - 'action_params' : ['message' : 'Hello Robusta!'], - 'sinks' : ['slack'] - ], - 'key' : 'very_secret']""", - "lang": "painless" - } - }, - "webhook": { - "scheme": "https", - "host": "api.robusta.dev", - "port": 443, - "method": "post", - "path": "/integrations/generic/actions_with_key", - "params": {}, - "headers": {}, - "body": "{{#toJson}}ctx.payload{{/toJson}}" - } - } - } - } - -.. note:: - - Most Robusta actions can be triggered in this manner. Try changing ``action_name`` and ``action_params`` above to trigger a different action diff --git a/docs/playbook-reference/triggers/helm-releases-monitoring.rst b/docs/playbook-reference/triggers/helm-releases-monitoring.rst deleted file mode 100644 index 8f1e97e96..000000000 --- a/docs/playbook-reference/triggers/helm-releases-monitoring.rst +++ /dev/null @@ -1,117 +0,0 @@ -Helm Releases Monitoring -############################# - -Robusta can monitor your Helm releases and notify you about updates or problems. For example: - -* Get notified in Slack when a Helm release fails -* Get notified in MSTeams if a Helm release is pending for more than X seconds -* Send details on your Helm history to external tools - -…and more - -Prerequisites ---------------- -There are two prerequisites for using Helm triggers: - -* The :ref:`Robusta UI` sink must be enabled -* ``monitorHelmReleases: true`` must be set in Robusta's Helm values - -Triggers ------------ - -The following triggers are available: - -.. _on_helm_release_unhealthy: - -.. details:: on_helm_release_unhealthy - - - ``on_helm_release_unhealthy`` triggers when a Helm release remains unhealthy for over ``duration`` seconds. Unhealthy states are: ``uninstalling``, ``pending-install``, ``pending-upgrade``, and ``pending-rollback``. - - - **Available options**: - - * ``rate_limit``: Limit firing to once every `rate_limit` seconds. - * ``names``: List of Helm releases for this trigger to monitor. Leaving this field empty monitors all releases in the namespace. Optional. - * ``namespace``: The Kubernetes namespace for this trigger to monitor. Leaving this field empty monitors all namespaces in the cluster. Optional. - * ``duration``: Minimum time, in seconds, that a release must remain unhealthy before the trigger fires. If the unhealthy state lasts less than this duration, the trigger won't fire. Default value is 900 seconds (15 minutes). Optional. - - .. admonition:: Example - - Monitor the ``demo-app`` Helm release in the ``default`` namespace. Send notifications when it is unhealthy for more than 15 minutes (900 seconds). Do not send further notifications for at least 4 hours (14400 seconds). - - .. code-block:: yaml - - customPlaybooks: - - triggers: - - on_helm_release_unhealthy: - names: ["demo-app"] # optional - namespace: "default" # optional - duration: 900 # optional - rate_limit: 14400 - actions: - - helm_status_enricher: {} - - - .. image:: /images/helm-release-unhealthy.png - :width: 1000 - :align: center - - -.. _on_helm_release_fail: - -.. details:: on_helm_release_fail - - ``on_helm_release_fail`` is triggered when a Helm release enters a ``failed`` state. This is a one-time trigger, meaning that it only fires once when the release fails. - - **Available options**: - - * ``names``: List of Helm releases for this trigger to monitor. Leaving this field empty monitors all releases in the namespace. Optional. - * ``namespace``: The Kubernetes namespace for this trigger to monitor. Leaving this field empty monitors all namespaces in the cluster. Optional. - - .. admonition:: Example - - Monitor the ``demo-app`` Helm release in the ``default`` namespace and send notifications when it is failing. - - .. code-block:: yaml - - customPlaybooks: - - triggers: - - on_helm_release_fail: - names: ["demo-app"] # optional - namespace: "default" # optional - actions: - - helm_status_enricher: {} - - .. image:: /images/helm-release-failed.png - :width: 1000 - :align: center - -.. _on_helm_release_deploy: - -.. details:: on_helm_release_deploy - - The ``on_helm_release_deploy`` is triggered when a Helm release enters a ``deployed`` state. This is a one-time trigger, meaning that it only fires once when the release is successfully deployed. - - **Available options**: - - * ``names``: List of Helm releases for this trigger to monitor. Leaving this field empty monitors all releases in the namespace. Optional. - * ``namespace``: The Kubernetes namespace for this trigger to monitor. Leaving this field empty monitors all namespaces in the cluster. Optional. - - .. admonition:: Example - - Monitor the ``demo-app`` Helm release in the ``default`` namespace and send notifications when it is deployed. - - .. code-block:: yaml - - customPlaybooks: - - triggers: - - on_helm_release_deploy: - names: ["demo-app"] # optional - namespace: "default" # optional - actions: - - helm_status_enricher: {} - - .. image:: /images/helm-release-deployed.png - :width: 1000 - :align: center diff --git a/docs/playbook-reference/triggers/index.rst b/docs/playbook-reference/triggers/index.rst index 91a9bc24c..10e7c7d3f 100644 --- a/docs/playbook-reference/triggers/index.rst +++ b/docs/playbook-reference/triggers/index.rst @@ -15,11 +15,9 @@ You can trigger Robusta playbooks on the following events: Kubernetes (API Server) Prometheus and AlertManager - Helm Releases Monitoring Scheduled Webhooks Manual Triggers - ElasticSearch .. grid:: 1 1 2 2 @@ -35,11 +33,6 @@ You can trigger Robusta playbooks on the following events: :link: prometheus :link-type: doc - .. grid-item-card:: :octicon:`cpu;1em;` Helm Releases Monitoring - :class-card: sd-bg-light sd-bg-text-light - :link: helm-releases-monitoring - :link-type: doc - .. grid-item-card:: :octicon:`cpu;1em;` Scheduled Triggers :class-card: sd-bg-light sd-bg-text-light :link: scheduled @@ -55,11 +48,6 @@ You can trigger Robusta playbooks on the following events: :link: manual-triggers :link-type: doc - .. grid-item-card:: :octicon:`cpu;1em;` ElasticSearch Monitors - :class-card: sd-bg-light sd-bg-text-light - :link: elasticsearch - :link-type: doc - diff --git a/docs/playbook-reference/triggers/kubernetes.rst b/docs/playbook-reference/triggers/kubernetes.rst index ba978733d..9a8a84fd1 100644 --- a/docs/playbook-reference/triggers/kubernetes.rst +++ b/docs/playbook-reference/triggers/kubernetes.rst @@ -229,8 +229,6 @@ every change, including the spec change that starts a rollout: aggregation_key: "DeploymentRolloutFailure" - deployment_events_enricher: {} -To run a Robusta Triggered Workflow on these, see :ref:`Robusta Platform Triggered Workflows`. - Warning Event Triggers ------------------------ diff --git a/docs/playbook-reference/triggers/webhook.rst b/docs/playbook-reference/triggers/webhook.rst index 6de3b2dae..fea3d305c 100644 --- a/docs/playbook-reference/triggers/webhook.rst +++ b/docs/playbook-reference/triggers/webhook.rst @@ -14,21 +14,3 @@ From inside the cluster you can trigger any manual playbook action over http: This endpoint is not exposed externally for security reasons. -External webhooks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -From outside the cluster you can trigger manual playbook actions if you've enabled the Robusta-relay. For security reasons, -this requires the runner's signing key. - -See the :ref:`Elasticsearch` integration for an example. - -Prerequisites --------------- -1. The Robusta-relay must be enabled so that it can route webhooks to the appropriate Robusta runner -2. The following variables must be defined in your Helm values file: - -.. code-block:: yaml - - globalConfig: - account_id: "" # your official Robusta account_id - signing_key: "" # a secret key used to verify that webhook callers are allowed to trigger playbooks diff --git a/docs/setup-robusta/alertsui.rst b/docs/setup-robusta/alertsui.rst deleted file mode 100644 index a30a8e8f9..000000000 --- a/docs/setup-robusta/alertsui.rst +++ /dev/null @@ -1,109 +0,0 @@ -Managed Prometheus Alerts -########################## - -You can manage your Prometheus alerts with the Robusta Alerts UI, instead of managing them as PrometheusRule YAMLs in-cluster. - -This lets your team create and customize Prometheus alerts with templates, without needing to know PromQL. - -.. image:: /images/robusta-ui-alerts-ui.gif - -This guide covers how it works, and also the steps involved to use this feature. - -How it works --------------------- - -Robusta manages the list of alerts in the Robusta UI and syncs them to your clusters as managed PrometheusRule files (CRDs). - -You can disable/enable individual alerts and change thresholds via the UI. - -Robusta uses the ``enabledManagedConfiguration`` Helm value to determine whether to sync alerts from the Alerts UI to your cluster, by default in ``generated_values.yaml`` it is set to ``true``. - -.. code-block:: yaml - - enabledManagedConfiguration: true - -Important to mention that Robusta stores its managed rules in PrometheusRules custom resources that start with ``robusta-prometheus.rules--``. If left in the cluster, you might have double alerts. - - -Enable Alerts UI for your cluster -******************************************** - -Choose the appropriate instructions below, based on whether you use the Prometheus bundled with Robusta or your own Prometheus. - -.. tab-set:: - .. tab-item:: Robusta’s Prometheus - - Make sure that the ``enabledManagedConfiguration`` value is set to ``true`` in ``generated_values.yaml``: - - .. code-block:: yaml - - enabledManagedConfiguration: true - - Then perform a :ref:`Helm Upgrade `. - - .. tab-item:: External Prometheus - - First, ensure you have the Prometheus operator installed by running the following command: - - .. code-block:: bash - - kubectl get crd | grep prometheus - - To make sure Prometheus picks up Robusta's rule files, add the following to the Kube Prometheus Stack configuration: - - .. code-block:: yaml - - prometheus: # collect rules from all namespaces and ignore label filters - ruleNamespaceSelector: {} - ruleSelector: {} - ruleSelectorNilUsesHelmValues: false - - Finally, make sure that the following snippet is in Robusta’s Helm values file named ``generated_values.yaml``: - - .. code-block:: yaml - - enabledManagedConfiguration: true # Enables managed alerts - - Then perform a :ref:`Helm Upgrade `. - - -Customizing PrometheusRule Labels and Group Name -************************************************** - -When you create alerts in the Robusta Alerts UI, they are synced to your cluster as PrometheusRule CRDs. You can customize the labels and group name that are applied to these UI-created rules. - -Add the following to your ``globalConfig`` section in ``generated_values.yaml``: - -.. code-block:: yaml - - globalConfig: - # Custom group name for PrometheusRule alerts created from the Robusta Alerts UI - prometheus_rule_group_name: "robusta-rule-group" - - # Custom labels to add to PrometheusRule metadata for rules created from the UI - prometheus_rule_custom_labels: - my_label: "my_value" - -Then perform a :ref:`Helm Upgrade `. - -.. note:: - These settings only apply to PrometheusRules created from the Robusta Alerts UI. - - -Disabling the Feature ---------------------------------- - -If you choose to stop using the Robusta Alerts UI - -1. Set ``enabledManagedConfiguration: false`` in ``generated_values.yaml`` and do a :ref:`Helm Upgrade `. -2. Identify the PrometheusRule custom resources added by Robusta - -.. code-block:: bash - - kubectl get prometheusrules -A | grep robusta-prometheus - -3. Modify and run the following command for all the Robusta rule custom resources present in your cluster. - -.. code-block:: bash - - kubectl delete prometheusrules.monitoring.coreos.com robusta-prometheus.rules -n diff --git a/docs/setup-robusta/configuration-secrets.rst b/docs/setup-robusta/configuration-secrets.rst index 1985f89c8..d24638de2 100644 --- a/docs/setup-robusta/configuration-secrets.rst +++ b/docs/setup-robusta/configuration-secrets.rst @@ -42,14 +42,6 @@ Add the following to your Helm values (generated_values.yaml): name: my-robusta-secrets key: secret_grafana_key - # if you're configuring a secret for HolmesGPT it would be: - holmes: - additionalEnvVars: - - name: GRAFANA_KEY - valueFrom: - secretKeyRef: - name: my-robusta-secrets - key: secret_grafana_key **3. Use the Environment Variable in Robusta Config** @@ -64,19 +56,3 @@ You can now reference the environment variable elsewhere in your configuration u This setup keeps sensitive values out of your Helm files and version control, while still allowing them to be dynamically injected at runtime. -.. _Reading the Robusta UI Token from a secret in HolmesGPT: - -Using an Existing Secret for the Robusta UI Token --------------------------------------------------------- - -If you store the Robusta UI token in a Kubernetes secret (instead of directly in Helm values), you need to pass it to HolmesGPT: - -.. code-block:: yaml - - holmes: - additionalEnvVars: - - name: ROBUSTA_UI_TOKEN - valueFrom: - secretKeyRef: - name: my-robusta-secrets # Your existing secret - key: ui-token # Your existing key diff --git a/docs/setup-robusta/crds.rst b/docs/setup-robusta/crds.rst deleted file mode 100644 index 0d188ba8c..000000000 --- a/docs/setup-robusta/crds.rst +++ /dev/null @@ -1,177 +0,0 @@ -============================================= -Custom Resource Definitions (CRDs) Monitoring -============================================= - -Overview --------- - -The CRDs monitoring feature enables you to view and manage Custom Resource Definitions and their instances directly from the Robusta UI. This powerful feature provides visibility into: - -* All CRDs deployed in your clusters -* Individual CR (Custom Resource) instances and their status -* Resource events and history -* Full YAML manifests -* Detailed resource descriptions - -.. image:: /images/crd_demo.png - :width: 800 - :align: center - :alt: CRDs monitoring in Robusta UI - -Prerequisites -------------- - -To enable CRD monitoring, the Robusta agent needs appropriate permissions to read custom resources in your cluster. This requires adding cluster role rules to your Robusta configuration. - -Configuration -------------- - -Finding CRD Names and API Groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get the CRD names and API groups to use in the configuration below: - -.. code-block:: bash - - kubectl get crd \ - -o custom-columns=NAME:.spec.names.plural,API_GROUP:.spec.group - -This will output something like: - -.. code-block:: text - - NAME API_GROUP - alertmanagerconfigs monitoring.coreos.com - alertmanagers monitoring.coreos.com - imagejobs eraser.sh - imagelists eraser.sh - nodenetworkconfigs acn.azure.com - overlayextensionconfigs acn.azure.com - ... - -Basic Configuration -^^^^^^^^^^^^^^^^^^^ - -Specify read permissions for the CRDs you need to monitor. You can list specific resources or use ``"*"`` to monitor all resources in an API group: - -.. code-block:: yaml - - runner: - customClusterRoleRules: - - apiGroups: - - "cert-manager.io" - resources: - - "certificates" - - "certificaterequests" - - "issuers" - - "clusterissuers" - verbs: - - "list" - - "get" - -Or to monitor all resources in an API group: - -.. code-block:: yaml - - runner: - customClusterRoleRules: - - apiGroups: - - "cert-manager.io" - resources: - - "*" - verbs: - - "list" - - "get" - -Default CRD Permissions -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Robusta includes read-only permissions for common Kubernetes operators and tools by default. These can be individually enabled or disabled: - -.. code-block:: yaml - - runner: - crdPermissions: - argo: true # Argo CD, Argo Workflows, Argo Rollouts - flux: true # Flux CD (GitOps toolkit) - kafka: true # Strimzi Kafka - keda: true # KEDA autoscaler - crossplane: true # Crossplane - istio: true # Istio service mesh - gatewayApi: true # Kubernetes Gateway API - velero: true # Velero backup/restore - externalSecrets: true # External Secrets Operator - - -Applying the Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Update your ``values.yaml`` file with the desired configuration -2. Apply the changes using Helm: - -.. code-block:: bash - - helm upgrade robusta robusta/robusta \ - --values values.yaml \ - --namespace robusta \ - --reuse-values - -Automatic Configuration with Holmes AI ---------------------------------------- - -Instead of manually configuring permissions for each CRD, you can use Holmes AI to automatically generate the configuration for all CRDs in your cluster. - -Using Holmes to Generate Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Navigate to the **Holmes Ask** page in the Robusta UI -2. Use the following prompt: - -.. code-block:: text - - I want to add read only cluster roles for all the crds in my cluster. - This is the format for adding one: - runner: - customClusterRoleRules: - - apiGroups: - - "storage.k8s.io" - resources: - - "storageclasses" - verbs: - - "list" - - "get" - Prepare my config - -3. Holmes will analyze your cluster and generate a complete configuration including all CRDs -4. Copy the generated configuration and add it to your ``values.yaml`` -5. Apply the configuration using Helm as described above - -.. tip:: - After Holmes generates the configuration, you can review and modify it to remove any CRDs you don't want to monitor before applying it. - -Troubleshooting ---------------- - -Common Issues and Solutions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Issue 1: CRDs not appearing in UI** - -* **Check permissions**: Verify the ClusterRole has the correct permissions - - .. code-block:: bash - - kubectl get clusterrole robusta-runner -o yaml - -* **Check agent logs**: Look for permission errors - - .. code-block:: bash - - kubectl logs -n robusta deployment/robusta-runner | grep -i "forbidden" - -**Issue 2: "Forbidden" errors when accessing CRDs** - -* **Solution**: Add the specific apiGroup and resource to ``customClusterRoleRules`` -* **Example error**: ``cannot get resource "certificates" in API group "cert-manager.io"`` -* **Fix**: Add the cert-manager.io apiGroup with certificates resource - diff --git a/docs/setup-robusta/gitops/argocd.rst b/docs/setup-robusta/gitops/argocd.rst index 5f25d8bf4..09907991a 100644 --- a/docs/setup-robusta/gitops/argocd.rst +++ b/docs/setup-robusta/gitops/argocd.rst @@ -6,7 +6,7 @@ This tutorial installs Robusta with `ArgoCD `_. Prerequisites --------------------- * A Kubernetes cluster with ArgoCD -* A ``generated_values.yaml`` file. Follow the :ref:`Generate a Config` tutorial to generate this. +* A ``generated_values.yaml`` file. Follow :doc:`/setup-robusta/installation/helm` to create one. .. include:: ../_questions.rst @@ -23,15 +23,12 @@ Example ``generated_values.yaml``: .. code-block:: yaml clusterName: my_cluster_name # <- This is the line to be added - globalConfig: - signing_key: xxxxxx - account_id: xxxxxx sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: xxxxxx + - slack_sink: + name: main_slack_sink + api_key: xxxxxx + slack_channel: xxxxxx enablePrometheusStack: true - enablePlatformPlaybooks: true runner: sendAdditionalTelemetry: true diff --git a/docs/setup-robusta/gitops/flux.rst b/docs/setup-robusta/gitops/flux.rst index 17b040272..ee2096c89 100644 --- a/docs/setup-robusta/gitops/flux.rst +++ b/docs/setup-robusta/gitops/flux.rst @@ -6,7 +6,7 @@ This tutorial installs Robusta with `Flux `_ using Flux `Hel Prerequisites --------------------- * A Kubernetes cluster with Flux installed. -* A ``generated_values.yaml`` file. Follow the :ref:`Generate a Config` tutorial to generate this. +* A ``generated_values.yaml`` file. Follow :doc:`/setup-robusta/installation/helm` to create one. .. include:: ../_questions.rst @@ -24,15 +24,12 @@ Example ``generated_values.yaml``: .. code-block:: yaml clusterName: my_cluster_name # <- This is the line to be added - globalConfig: - signing_key: xxxxxx - account_id: xxxxxx sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: xxxxxx + - slack_sink: + name: main_slack_sink + api_key: xxxxxx + slack_channel: xxxxxx enablePrometheusStack: true - enablePlatformPlaybooks: true runner: sendAdditionalTelemetry: true diff --git a/docs/setup-robusta/holmes-only.rst b/docs/setup-robusta/holmes-only.rst deleted file mode 100644 index edc38bf1d..000000000 --- a/docs/setup-robusta/holmes-only.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _holmes-only-install: - -Holmes-Only Install (Without the Runner) -======================================== - -The ``robusta`` chart can install HolmesGPT alone, without the Robusta runner or kubewatch. -Holmes connects to the Robusta platform directly, so Ask Holmes, Triggered Workflows, alert -triage and scheduled prompts work for the cluster. - -Setting ``runner.enabled: false`` turns this on. The default is ``true``, so existing installs -are unchanged. - -Values ------- - -Start from your ``generated_values.yaml`` and add: - -.. code-block:: yaml - - runner: - enabled: false - kubewatch: - enabled: false - enableHolmesGPT: true - - clusterName: my-cluster - globalConfig: - account_id: - signing_key: - sinksConfig: - - robusta_sink: - name: robusta_ui_sink - token: - - holmes: - additionalEnvVars: - - name: ROBUSTA_AI - value: "true" - -The chart still renders ``robusta-playbooks-config-secret``, with only the cluster name, -account id, signing key and robusta sink. Holmes reads its platform credentials from it. Rendering -fails if ``enableHolmesGPT`` is false or if there is no ``robusta_sink``. Other sinks are -ignored, because only the runner uses them. - -If the sink token is a reference such as ``{{ env.UI_SINK_TOKEN }}``, the variable must be set on -Holmes, not on the runner. Add it under ``holmes.additionalEnvVars``: - -.. code-block:: yaml - - holmes: - additionalEnvVars: - - name: UI_SINK_TOKEN - valueFrom: - secretKeyRef: - name: - key: - -Sending alerts --------------- - -With no runner, there is no in-cluster ``-runner`` endpoint for Alertmanager. Send alerts to -the Robusta platform directly instead. See :doc:`Send alerts from AlertManager -`. - -If you use the bundled Prometheus stack (``enablePrometheusStack: true``), its default ``robusta`` -receiver points at the runner, and rendering fails until you replace it: - -.. robusta-code:: yaml - - kube-prometheus-stack: - alertmanager: - config: - receivers: - - name: 'null' - - name: robusta - webhook_configs: - - url: 'https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=&cluster=' - send_resolved: true - http_config: - authorization: - type: Bearer - credentials: diff --git a/docs/setup-robusta/index.rst b/docs/setup-robusta/index.rst index 9788ef0dd..661e16d0a 100644 --- a/docs/setup-robusta/index.rst +++ b/docs/setup-robusta/index.rst @@ -3,7 +3,7 @@ .. toctree:: :hidden: - installation/index + installation/helm .. toctree:: :hidden: @@ -13,19 +13,13 @@ .. toctree:: :hidden: - multi-cluster - holmes-only upgrade tuning-performance json-logging configuration-secrets openshift read-only-service-account - rbac-namespace-scoping - rbac-namespace-scoped-runner node-selector proxies - privacy-and-security - installation-faq diff --git a/docs/setup-robusta/installation-faq.rst b/docs/setup-robusta/installation-faq.rst deleted file mode 100644 index 67e78cd9f..000000000 --- a/docs/setup-robusta/installation-faq.rst +++ /dev/null @@ -1,44 +0,0 @@ -FAQ -################################ - -I have an error installing Robusta -================================================ -Please refer to :ref:`Help ` for common errors and solutions. - -The helm chart in GitHub doesn't work. Why? -======================================================== -It has certain placeholders. For example, ``runner.image`` is set during our release workflow. - -Use our Helm repository instead of our GitHub repository. See above. - -Can I install Robusta in a different namespace? -================================================ - -Yes. By default Robusta is installed in the ``default`` namespace but you can change that. - -For example, to install in the ``robusta`` namespace: - -.. code-block:: bash - :name: cb-helm-install-robusta-custom - - helm install robusta robusta/robusta -f ./generated_values.yaml -n robusta --create-namespace --set clusterName= - -Verify success by checking that Robusta pods are running: - -.. code-block:: bash - :name: cb-get-pods-robusta-logs-custom - - kubectl get pods -n robusta - -Can I run two Robusta instances in the same cluster? -====================================================== - -Yes. Install each instance with a different Helm release name in its own namespace: - -.. code-block:: bash - :name: cb-helm-install-robusta-two-instances - - helm install robusta robusta/robusta -f ./generated_values.yaml -n namespace-1 --create-namespace --set clusterName= - helm install robusta-2 robusta/robusta -f ./generated_values.yaml -n namespace-2 --create-namespace --set clusterName= - -Use a unique ``clusterName`` for each instance so they appear separately in the Robusta UI. diff --git a/docs/setup-robusta/installation/_see_robusta_in_action-2.rst b/docs/setup-robusta/installation/_see_robusta_in_action-2.rst index af65fe648..97b7d85ec 100644 --- a/docs/setup-robusta/installation/_see_robusta_in_action-2.rst +++ b/docs/setup-robusta/installation/_see_robusta_in_action-2.rst @@ -55,7 +55,6 @@ Once the pod has reached two restarts, you'll get notified in Slack (or whatever .. image:: /images/crash-report.png -Now open the :robusta-url:`Robusta UI ` and look for the same message there. Finally, clean up the crashing pod: diff --git a/docs/setup-robusta/installation/helm.rst b/docs/setup-robusta/installation/helm.rst new file mode 100644 index 000000000..33982e369 --- /dev/null +++ b/docs/setup-robusta/installation/helm.rst @@ -0,0 +1,53 @@ +Install with Helm +################# + +This guide installs the Robusta runner with Helm and sends its notifications to a Slack channel. + +Prerequisites +------------- + +* A Kubernetes cluster +* Helm +* A Slack API key and channel. See :ref:`Creating Custom Slack Apps`. + +Add the Helm repository +----------------------- + +.. code-block:: bash + + helm repo add robusta https://robusta-charts.storage.googleapis.com + helm repo update + +Write a values file +------------------- + +The chart needs at least one sink. Save the following as ``generated_values.yaml``: + +.. code-block:: yaml + + sinksConfig: + - slack_sink: + name: main_slack_sink + api_key: + slack_channel: + +To keep the Slack key out of this file, see :ref:`Managing Secrets`. For other destinations, see :doc:`/notification-routing/configuring-sinks`. + +Install +------- + +.. code-block:: bash + + helm install robusta robusta/robusta -f ./generated_values.yaml --set clusterName= + +``clusterName`` is required. + +Verify that Robusta is running and there are no errors in the logs: + +.. code-block:: bash + + kubectl logs -n -l app=robusta-runner + +Keep ``generated_values.yaml``: you pass it again on every :ref:`upgrade `. + +Next, send Prometheus alerts to Robusta: see :doc:`/configuration/index`. diff --git a/docs/setup-robusta/installation/index.rst b/docs/setup-robusta/installation/index.rst deleted file mode 100644 index 84796e5ab..000000000 --- a/docs/setup-robusta/installation/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -:hide-footer: - -:tocdepth: 2 - -.. _install: -.. _install-barebones: - -Install Robusta -================ - -Use Robusta's AI Agent alongside any observability stack β€” DataDog, NewRelic, Prometheus, SolarWinds, and more. - -Prerequisites ---------------------- - -* A Kubernetes cluster -* Helm - -Sign Up and Install ---------------------- - -Sign up :robusta-url:`for a free Robusta account β†— ` and follow the install wizard. It generates a ``generated_values.yaml`` file and provides the Helm install commands tailored to your cluster. - -.. note:: - - **Save your generated_values.yaml file** β€” you'll need it to install Robusta on new clusters or upgrade. It contains sensitive values; refer to :ref:`Managing Secrets` for tips on protecting them. diff --git a/docs/setup-robusta/json-logging.rst b/docs/setup-robusta/json-logging.rst index 5c7c5ce12..6db5dbf15 100644 --- a/docs/setup-robusta/json-logging.rst +++ b/docs/setup-robusta/json-logging.rst @@ -21,8 +21,6 @@ This single switch is shared across the Robusta components: * **robusta-runner** emits JSON logs. * **KRR** scan jobs inherit the setting from the runner (when scan results are pushed back over the API, which is the default). -* **HolmesGPT** (when deployed via the chart) emits JSON logs as well β€” the - ``global`` value is passed through to the Holmes sub-chart. The default is ``false``, which preserves the existing colored text output. No change is needed unless you want JSON logs. diff --git a/docs/setup-robusta/multi-cluster.rst b/docs/setup-robusta/multi-cluster.rst deleted file mode 100644 index 6cbf20ec9..000000000 --- a/docs/setup-robusta/multi-cluster.rst +++ /dev/null @@ -1,41 +0,0 @@ -:hide-toc: - -Multi-cluster -############################## - -This guide is for environments with more than one Kubernetes cluster. - -It's important to add all clusters to the same Robusta account. - -Installing Robusta on multiple clusters ------------------------------------------- - -1. Install Robusta on the first cluster, as described in :ref:`install`. - -2. Do a ``helm install`` on each additional cluster, **re-using** your existing ``generated_values.yaml``. - - .. code-block:: bash - :name: cb-helm-install-only-robusta - - helm install robusta robusta/robusta -f ./generated_values.yaml --set clusterName= - -.. warning:: - - Set a unique ``clusterName`` on each cluster (via ``--set clusterName=``). The rest of ``generated_values.yaml`` stays the same across all clusters β€” that's how the Robusta UI groups them under the same account. - -Frequently Asked Questions ----------------------------- - -Where is my ``generated_values.yaml``? -******************************************************* - -If you lost your ``generated_values.yaml`` file, you can extract it from any cluster running Robusta. - -.. code-block:: bash - - helm get values -o yaml robusta | grep -v clusterName: | grep -v isSmallCluster: > generated_values.yaml - -.. note:: - - The above command strips the ``clusterName`` and ``isSmallCluster`` options so you don't copy them accidentally. - These options should be determined on a cluster by cluster basis. diff --git a/docs/setup-robusta/node-selector.rst b/docs/setup-robusta/node-selector.rst index 3a82121bd..14b4b2fb3 100644 --- a/docs/setup-robusta/node-selector.rst +++ b/docs/setup-robusta/node-selector.rst @@ -127,8 +127,6 @@ Add the following to your Helm values: value: "robusta" effect: "NoSchedule" - holmes: - tolerations: ... # copy from above runner: tolerations: ... # copy from above diff --git a/docs/setup-robusta/privacy-and-security.rst b/docs/setup-robusta/privacy-and-security.rst deleted file mode 100644 index 710826995..000000000 --- a/docs/setup-robusta/privacy-and-security.rst +++ /dev/null @@ -1,28 +0,0 @@ -Privacy and Security -############################ - -Robusta was designed with security in mind. Our four guiding security principles are: - -1. **Less is more:** Don't send mountains of observability data when small subsets of the *right* data will do. -2. **Secure by default, configurable if necessary:** Do the right thing for most companies by default. Make it easy for companies with stricter compliance needs to lock-down Robusta further or run it on-prem. -3. **Design for security:** Secure systems are designed to be secure from day one. Discuss security when planning new features. -4. **Experience matters:** Hire engineers who have built secure enterprise platforms before. Make security a core part of company culture. - -Running Robusta in Airgapped Environments -****************************************** -Refer to :ref:`Deploying Behind Proxies`. - -To run the Robusta UI on premise, :ref:`speak to our team `. - -Handling Secrets in Robusta's Helm Values -****************************************** -Refer to :ref:`Managing Secrets`. - -Limiting Robusta's Access in Your Cluster -******************************************* - -To reduce the permissions that Robusta needs in your cluster: - -- On OpenShift you can deploy Robusta with a limited SCC - refer to :ref:`OpenShift` - -To further limit Robusta's permissions, :ref:`speak to our team for guidance `. diff --git a/docs/setup-robusta/proxies.rst b/docs/setup-robusta/proxies.rst index 6a6cbbf93..7598d9c1b 100644 --- a/docs/setup-robusta/proxies.rst +++ b/docs/setup-robusta/proxies.rst @@ -1,7 +1,7 @@ Deploying Behind Proxies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If your Kubernetes cluster is behind an HTTP proxy or firewall, follow the instructions below to ensure Robusta and HolmesGPT have the necessary access. +If your Kubernetes cluster is behind an HTTP proxy or firewall, follow the instructions below to ensure Robusta has the necessary access. Configuring Proxy Settings ---------------------------------------- @@ -17,13 +17,6 @@ Set the ``HTTP_PROXY`` and ``HTTPS_PROXY`` environment variables in your Helm va - name: HTTPS_PROXY value: "http://your-proxy:port" - holmes: - additionalEnvVars: - - name: HTTP_PROXY - value: "http://your-proxy:port" - - name: HTTPS_PROXY - value: "http://your-proxy:port" - To set many variables at once, ``runner.additional_env_froms`` accepts a Kubernetes ``envFrom`` source. See `this GitHub issue `_ for details and examples. .. _firewall-allowlist: @@ -39,18 +32,12 @@ When deploying Robusta in a tightly restricted environment, the runner needs out Runtime ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Required whenever the runner is running. The Robusta platform addresses depend on the region your account is hosted in β€” select your region to see the correct values: +Reached whenever the runner is running: -.. robusta-code:: text +.. code-block:: text - # Robusta SaaS platform (required if robusta_sink enabled) - *.robusta.dev - api.robusta.dev # platform REST API: cluster registration, action relay, telemetry - relay.robusta.dev # WebSocket relay (wss://); override with WEBSOCKET_RELAY_ADDRESS - platform.robusta.dev # Robusta UI (links rendered into Slack/Teams/email) - sp.robusta.dev # platform storage - docs.robusta.dev # doc links embedded in notifications (not strictly required) - *.supabase.co # cluster data store; exact subdomain comes from your token's store_url + api.robusta.dev # telemetry, identified by SHA-256 hashes of the account ID and cluster name; set ENABLE_TELEMETRY=false in runner.additional_env_vars to turn it off + docs.robusta.dev # doc links embedded in notifications (not strictly required) Installation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -63,7 +50,6 @@ Installation registry-1.docker.io auth.docker.io production.cloudflare.docker.com - us-central1-docker.pkg.dev # HolmesGPT MCP server images and bundled tooling quay.io # only with bundled kube-prometheus-stack subchart ghcr.io # only with bundled kube-prometheus-stack subchart @@ -74,7 +60,7 @@ Only needed for the integrations and features you actually enable. .. code-block:: text - # Error reporting (only if runner.sentry_dsn / holmes.sentryDSN is set; default points to .de.sentry.io) + # Error reporting (only if runner.sentry_dsn is set; default points to .de.sentry.io) *.sentry.io *.ingest.sentry.io *.ingest.de.sentry.io @@ -111,18 +97,8 @@ Only needed for the integrations and features you actually enable. botapi.messenger.yandex.net # Yandex (override with YM_API_BASE_URL) # Mattermost, RocketChat, Zulip, generic Webhook, Kafka: allow the host you configured - # HolmesGPT LLM providers (only those you use) - api.openai.com # OpenAI - api.anthropic.com # Anthropic - *.openai.azure.com # Azure OpenAI (your resource subdomain) - login.microsoftonline.com # Azure AD OAuth (Azure OpenAI / Azure Managed Prometheus) - *.amazonaws.com # AWS Bedrock - bedrock-runtime..amazonaws.com - sts.amazonaws.com - *.googleapis.com # Google Vertex AI / Gemini - aiplatform.googleapis.com - generativelanguage.googleapis.com - oauth2.googleapis.com + # Azure AD OAuth (only with Azure Managed Prometheus) + login.microsoftonline.com # Cloud / observability auth (only if you use these managed backends) prometheus.monitor.azure.com # Azure Managed Prometheus query endpoint @@ -132,8 +108,7 @@ If you mirror images to a private registry, override ``image.registry`` (and the If your private registry requires authentication, set ``global.imagePullSecrets``. This applies the pull secret to the runner, kubewatch, and the pods the runner launches at runtime (e.g. KRR, Popeye, -via the runner ServiceAccount). To also cover HolmesGPT, set ``holmes.imagePullSecrets`` β€” HolmesGPT -is a subchart, so set it explicitly alongside the global value: +via the runner ServiceAccount): .. code-block:: yaml @@ -141,108 +116,28 @@ is a subchart, so set it explicitly alongside the global value: imagePullSecrets: - name: my-registry-secret - # HolmesGPT is a subchart β€” set its pull secret as well - holmes: - imagePullSecrets: - - name: my-registry-secret - -A per-component value (e.g. ``runner.imagePullSecrets``, ``kubewatch.imagePullSecrets``, -``holmes.imagePullSecrets``) overrides the global one for that component. Leaving +A per-component value (e.g. ``runner.imagePullSecrets``, ``kubewatch.imagePullSecrets``) +overrides the global one for that component. Leaving ``global.imagePullSecrets`` empty keeps the previous behavior. Verifying the Allowlist ---------------------------------------- -After applying firewall rules, you can sanity-check connectivity from inside the runner pod. Select your region to get the correct addresses: +After applying firewall rules, you can sanity-check connectivity from inside the runner pod: -.. robusta-code:: bash +.. code-block:: bash kubectl exec -n deploy/robusta-runner -- \ - sh -c 'for host in api.robusta.dev relay.robusta.dev platform.robusta.dev sp.robusta.dev; do + sh -c 'for host in api.robusta.dev docs.robusta.dev; do echo "== $host =="; curl -sS -o /dev/null -w "%{http_code}\n" https://$host/ || true done' A non-zero HTTP code (including ``401``/``404``) confirms TCP + TLS reach the host. Connection timeouts indicate the firewall is still blocking. -Copying Images to a Private Image Registry ------------------------------------------- - -If you are running the Robusta **self-hosted platform** (the ``robusta-platform`` Helm chart) in an environment that cannot pull from public registries (Docker Hub, ``us-central1-docker.pkg.dev``, ``quay.io``), mirror the images below to your internal registry and override the registry fields in your Helm values. - -The list reflects the images pulled by the chart at the versions shipped in the current release. Image tags change between chart versions β€” re-check ``values.yaml`` of the chart version you are installing. - -**Images from the Robusta registry** (default: ``us-central1-docker.pkg.dev/genuine-flight-317411/devel``) - -.. code-block:: text - - robusta-db:14.1.1 # Supabase Postgres 14 (default DB image) - robusta-db:15.0.0 # Supabase Postgres 15 (only if usePostgres15=true) - db-migration:0.0.66 # DB migration init Job - realtime:v2.96.0 # Robusta fork of supabase/realtime (JWT_REQUIRE_EXP) - platform-relay:0.22.0 # Relay (WebSocket + API) β€” only if enableRelay=true - robusta-ui:0.2.87 # Platform UI β€” only if enableRobustaUI=true - rbac-import:0.3.0 # Optional RBAC import CronJob (rbacImport.enabled) - -**Images from Docker Hub** (controlled by ``dockerRegistry``) - -.. code-block:: text - - supabase/gotrue:v2.189.0 - supabase/postgres-meta:v0.96.5 - supabase/studio:2026.05.11-sha-5a5099a - postgrest/postgrest:v14.6 - kong:3.9.1 - postgres:15-alpine # realtime schema-init container - busybox:1.37 # init containers for rest/meta/migration - -**Optional images** (only if the corresponding feature is enabled) - -.. code-block:: text - - quay.io/prometheuscommunity/postgres-exporter:v0.15.0 # monitoring.postgresExporter.enabled - -After mirroring, point the chart at your registry by overriding the following values: - -.. code-block:: yaml - - # Robusta-built images - robustaRegistry: my-registry.example.com/robusta - - # Public images β€” value is used as a prefix, so include the trailing slash - dockerRegistry: my-registry.example.com/ - - # Subchart registries (robusta-ui and robusta-relay are dependencies) - robusta-ui: - registry: my-registry.example.com/robusta - robusta-relay: - registry: my-registry.example.com/robusta - - # Monitoring image is a full path β€” override directly if enabled - monitoring: - postgresExporter: - image: my-registry.example.com/prometheuscommunity/postgres-exporter:v0.15.0 - - # If your registry requires auth - imagePullSecrets: - - name: my-registry-secret - -.. tip:: - - **Override the registry, not the tags.** The chart exposes per-image fields - (``dbImage``, ``authImage``, ``realtimeImage``, ``migrationImage``, etc.) but - these are intended for internal use β€” they pin the exact tags that have been - tested with the current chart version. If you pin them yourself, every chart - upgrade will silently roll your images back to the tags you hard-coded, and - you will need to bump each one by hand on every release. - - For mirrored-registry setups, override only ``robustaRegistry`` / - ``dockerRegistry`` (and the matching subchart ``registry`` fields). The chart - will continue to use the image tags shipped with each version, just pulled - from your private registry β€” so ``helm upgrade`` keeps working seamlessly. - Your mirroring workflow only needs to re-pull the new tags from - ``values.yaml`` before each upgrade. Running Robusta in Air-Gapped or Offline Environments ------------------------------------------------------------------------------ Contact support@robusta.dev for self-hosted deployment options that work in fully air-gapped or offline environments (private image registry, on-prem platform, no SaaS dependency). + +The self-hosted platform's container images are listed in its own operator documentation. diff --git a/docs/setup-robusta/rbac-namespace-scoped-runner.rst b/docs/setup-robusta/rbac-namespace-scoped-runner.rst deleted file mode 100644 index 41845e11d..000000000 --- a/docs/setup-robusta/rbac-namespace-scoped-runner.rst +++ /dev/null @@ -1,244 +0,0 @@ -.. _rbac-namespace-scoped-runner: - -RBAC: Namespace-Scoped Runner -======================================== - -By default, the Robusta runner is a cluster-wide agent: it discovers workloads in every namespace, -reads cluster-scoped resources (nodes, namespaces, persistent volumes) and runs with a ``ClusterRole`` -bound by a ``ClusterRoleBinding``. - -This guide runs the runner with **access limited to a single namespace** β€” the namespace Robusta is -installed in. Setting ``runner.rbac.namespaceScoped: true`` makes the chart render namespaced RBAC -(a ``Role`` + ``RoleBinding`` instead of the ClusterRole + ClusterRoleBinding) and presets the -runner's scoped-mode environment variables. Everything stays Helm-managed β€” no hand-applied RBAC β€” -and because all rendered objects are namespaced, you can install **multiple independent Robusta -instances in different namespaces** without name collisions. The default (``false``) keeps today's -cluster-wide behavior. - -What works and what doesn't ---------------------------- - -In this mode the runner keeps working as a platform agent: it connects to the Robusta platform, -reports cluster status (workload counts for its namespace, Kubernetes version, provider), answers -UI requests for resources **in its namespace**, and can reach Holmes and an explicitly-configured -Prometheus/Alertmanager. - -The following are **not available** with a namespace-scoped service account: - -- Cluster-wide resource discovery (the UI's apps/nodes/namespaces inventory) β€” disabled via - ``DISABLE_DISCOVERY``. -- Kubernetes change tracking and ``on_kubernetes_*`` triggers β€” the kubewatch forwarder is disabled (see below). -- Playbooks. This setup assumes **all playbooks are disabled**. Many built-in actions need - cluster-scoped access (nodes, persistent volumes, cluster-wide events and pod listings) and will - fail with permission errors if invoked. -- Node-based features: node enrichments, drains, node count (reported as ``1``), auto-detection of - the cluster provider (declare it with ``CLUSTER_PROVIDER`` instead). -- Auto-discovery of Prometheus/Alertmanager β€” set ``prometheus_url`` / ``alertmanager_url`` - explicitly, or leave them unset to run without those integrations. - -Setup ------ - -Add the following to your Helm values: - -.. code-block:: yaml - - # scoped-values.yaml - runner: - rbac: - # renders a namespaced Role + RoleBinding (no ClusterRole/ClusterRoleBinding) - # and presets the scoped-mode env vars listed below - namespaceScoped: true - additional_env_vars: - - name: CLUSTER_PROVIDER - value: "EKS" # your provider; or "OpenShift", "Unknown", ... - - name: ENABLE_TELEMETRY - value: "false" # optional - - # no playbooks in this mode β€” many built-in actions need cluster-wide access - builtinPlaybooks: [] - customPlaybooks: [] - enablePlatformPlaybooks: false - - # Robusta-managed Prometheus alerts sync PrometheusRule CRs in the installation - # namespace. Disable it (your generated_values.yaml may have it enabled), or keep it - # and grant the prometheusrules rule via runner.customClusterRoleRules (see note below). - enabledManagedConfiguration: false - - # if you use Prometheus/Alertmanager, point at them explicitly instead of auto-discovery - # globalConfig: - # prometheus_url: "http://prometheus.monitoring.svc.cluster.local:9090" - # alertmanager_url: "http://alertmanager.monitoring.svc.cluster.local:9093" - - # don't deploy the kubewatch forwarder at all (see the section below) - kubewatch: - enabled: false - -Then install: - -.. code-block:: bash - - helm upgrade --install robusta robusta/robusta \ - -f generated_values.yaml \ - -f scoped-values.yaml \ - -n robusta --create-namespace - -For multiple instances, repeat per namespace with a **unique** ``clusterName`` per install (each -instance appears as its own cluster in the Robusta platform). - -What ``runner.rbac.namespaceScoped`` does ------------------------------------------ - -**RBAC** β€” instead of ``-runner-cluster-role`` (ClusterRole) + ClusterRoleBinding, the -chart renders ``-runner-role`` (a namespaced ``Role`` with the same rules) bound by a -``RoleBinding`` in the release namespace. The ServiceAccount and the namespaced create-permissions -Role (``-runner-local-role``) are unchanged. Because a Role is namespaced, multiple -installs β€” even with the same release name β€” cannot collide on cluster-scoped RBAC objects. - -**Environment variables** β€” the flag presets these on the runner (any entry you add to -``runner.additional_env_vars`` with the same name overrides the preset): - -.. list-table:: - :header-rows: 1 - :widths: 32 23 45 - - * - Variable - - Preset by the flag - - Effect - * - ``DISABLE_DISCOVERY`` - - ``true`` - - Disables the cluster-wide resource discovery loop. - * - ``CLUSTER_STATS_NAMESPACE`` - - the release namespace - - Cluster-status workload counts are taken from this namespace only; the node count is - reported as ``1`` and telemetry skips node listing. - * - ``NAMESPACE_DATA_MODE`` - - ``namespaced`` - - Namespace labels/annotations (used by sink scopes) are read only for the installation - namespace. Other values: ``cluster`` (all namespaces), ``disabled`` (no API call). - * - ``HOLMES_DISCOVERY_NAMESPACE`` - - the release namespace - - Search for the Holmes service only in this namespace. Alternatively set ``holmes_url`` - in ``globalConfig``. - * - ``DISABLE_PROMETHEUS_DISCOVERY`` - - ``true`` - - Never search the cluster for a Prometheus/Victoria Metrics service. Set ``prometheus_url`` - in ``globalConfig`` if you use Prometheus. - * - ``DISABLE_ALERTMANAGER_DISCOVERY`` - - ``true`` - - Never search the cluster for an Alertmanager service. Set ``alertmanager_url`` in - ``globalConfig`` if you use Alertmanager (e.g. for silences). - * - ``CLUSTER_PROVIDER`` - - not preset - - Declare the cluster provider instead of detecting it from nodes. One of: ``GKE``, ``AKS``, - ``EKS``, ``Kind``, ``Minikube``, ``RancherDesktop``, ``Kapsule``, ``Kops``, - ``DigitalOcean``, ``OpenShift``, ``Unknown``. Recommended β€” without it the provider shows - as ``Unknown``. - * - ``ENABLE_TELEMETRY`` - - not preset - - Set ``false`` to disable the telemetry thread entirely (optional). - -.. note:: - - The Role carries the same rules as the default ClusterRole, so cluster-scoped entries in it - (``nodes``, ``persistentvolumes``, ...) are legal but grant nothing β€” a RoleBinding - structurally cannot grant cluster-scoped access. One side effect: ``kubectl auth can-i list - nodes -n `` may answer ``yes`` even though a real ``kubectl get nodes`` is denied; check - without ``-n`` (as in the verification below) for the true answer. - -.. note:: - - If you keep **Robusta-managed Prometheus alerts** (``enabledManagedConfiguration: true``), - also add this to your values β€” the runner syncs ``PrometheusRule`` CRs in its own namespace, - and ``customClusterRoleRules`` entries are added to the scoped Role: - - .. code-block:: yaml - - runner: - customClusterRoleRules: - - apiGroups: ["monitoring.coreos.com"] - resources: ["prometheusrules"] - verbs: ["get", "list", "create", "update", "patch", "delete"] - -Alternative: bring your own service account -------------------------------------------- - -If your security process requires RBAC managed outside the chart, set -``runner.createServiceAccount: false`` (nothing RBAC-related is rendered) plus -``runner.customServiceAccount: ``, and create the ServiceAccount, a Role with the rules the -runner needs (workload reads for cluster stats and self-registration, ``configmaps`` -``get/create/update`` for the ``scheduled-jobs`` scheduler state, ``services`` ``list`` for Holmes -discovery, ``namespaces`` ``get`` for ``NAMESPACE_DATA_MODE=namespaced``, and ``events`` -``get/list`` in **both** the ``""`` core and ``events.k8s.io`` API groups for resource event -enrichment) and a RoleBinding yourself. In that setup also set -the environment variables from the table above yourself via ``runner.additional_env_vars`` β€” the -presets come from ``runner.rbac.namespaceScoped``, which you may still enable together with a -custom service account. - -Disabling kubewatch -------------------- - -The kubewatch forwarder is a separate Deployment with its own cluster-wide ``ClusterRole`` β€” it is -what watches the API server for changes and feeds them to the runner. ``kubewatch.enabled: false`` -removes it entirely: the Deployment, Service, ConfigMap, ServiceAccount, ClusterRole and -ClusterRoleBinding are not rendered. Kubernetes change tracking and ``on_kubernetes_*`` triggers do -not work without it (which is consistent with this setup β€” playbooks are disabled anyway). - -Verifying the scope -------------------- - -.. code-block:: bash - - SA=system:serviceaccount:robusta:robusta-runner-service-account - - kubectl auth can-i list pods --as=$SA -n robusta # -> yes - kubectl auth can-i list pods --as=$SA -n kube-system # -> no - kubectl auth can-i list nodes --as=$SA # -> no - kubectl auth can-i list namespaces --as=$SA # -> no - -Then check the runner logs β€” there should be no recurring ``Forbidden`` (403) errors, and the -platform should show the cluster as connected, with workload counts for the scoped namespace and a -node count of 1. - -Troubleshooting ---------------- - -**The runner exits with** ``configmaps "scheduled-jobs" is forbidden ... cannot get resource -"configmaps"`` β€” the runner's service account has no ``configmaps get`` in its namespace. With -``runner.rbac.namespaceScoped: true`` and the chart-created service account this cannot happen; it -means a bring-your-own RoleBinding is not matching the pod's service account. This error is fatal -(the runner restarts in a loop until fixed). Check, in the installation namespace: - -.. code-block:: bash - - NS=robusta # your namespace - SA=robusta-runner-service-account # your service account name - - # 1. which service account is the pod actually running as? - kubectl get deployment robusta-runner -n $NS \ - -o jsonpath='{.spec.template.spec.serviceAccountName}' - - # 2. does the RoleBinding reference the right Role and the right subject? - kubectl get rolebinding -n $NS -o yaml | grep -B2 -A8 "$SA" - - # 3. the direct check: - kubectl auth can-i get configmaps --as=system:serviceaccount:$NS:$SA -n $NS # must be yes - -Common causes: the RoleBinding's ``subjects[].name`` doesn't match the ServiceAccount name used in -``runner.customServiceAccount`` (e.g. after renaming one but not the other), the ``roleRef.name`` -doesn't match the Role, or the objects were applied to a different namespace. - -**Recurring** ``prometheusrules.monitoring.coreos.com is forbidden`` **errors ("An error occurred -while creating CR rules")** β€” Robusta-managed Prometheus alerts are enabled -(``enabledManagedConfiguration: true``, often present in ``generated_values.yaml``). Either set -``enabledManagedConfiguration: false``, or grant the ``prometheusrules`` rule via -``runner.customClusterRoleRules`` as shown above. This error is not fatal, but it repeats every -sync cycle. - -Related guides --------------- - -- :ref:`Read-Only Service Account ` β€” keep cluster-wide read access but - remove all write permissions. -- :ref:`RBAC: Namespace-Scoped HolmesGPT ` β€” the equivalent setup for - HolmesGPT. diff --git a/docs/setup-robusta/rbac-namespace-scoping.rst b/docs/setup-robusta/rbac-namespace-scoping.rst deleted file mode 100644 index e7455b8e4..000000000 --- a/docs/setup-robusta/rbac-namespace-scoping.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. _rbac-namespace-scoping: - -RBAC: Namespace-Scoped HolmesGPT -======================================== - -By default, HolmesGPT uses cluster-wide RBAC: the chart creates a ``ClusterRole`` and binds it with a -``ClusterRoleBinding``, so Holmes can read resources in every namespace. - -There are two ways to restrict it, depending on what you need: - -- **Scope Holmes to its own installation namespace** (e.g. one Holmes + runner instance per - namespace) β€” set ``holmes.namespaceScopedRBAC: true``. Fully Helm-managed, nothing to delete - after upgrades, and multiple installs in different namespaces cannot collide. See - :ref:`Option 1 `. -- **Grant one Holmes access to a set of other namespaces** β€” create your own ``RoleBinding`` - objects that reuse the chart's ClusterRole, and remove the cluster-wide binding. See - :ref:`Option 2 `. - -.. _holmes-namespace-scoped-rbac: - -Option 1 β€” scope Holmes to its own namespace (``namespaceScopedRBAC``) ----------------------------------------------------------------------- - -Set in your Helm values: - -.. code-block:: yaml - - holmes: - namespaceScopedRBAC: true - -Instead of ``-holmes-cluster-role`` (ClusterRole) + ClusterRoleBinding, the chart renders -``-holmes-role`` β€” a namespaced ``Role`` with the same rules β€” bound by a ``RoleBinding`` -in the release namespace. Holmes can then only read namespaced resources in the namespace it is -installed in. Because everything rendered is namespaced: - -- ``helm upgrade`` manages the RBAC end to end β€” there is no ClusterRoleBinding to delete, ever. -- Multiple Holmes installs in different namespaces cannot collide on cluster-scoped RBAC names, - even with identical release names. - -The flag also sets the ``SCOPED_NAMESPACES`` environment variable on the Holmes pod, which injects -the access scope into Holmes' system prompt β€” investigations start with namespace-scoped commands -right away, instead of Holmes trying cluster-wide queries first and learning its limits from -``Forbidden`` errors. - -This pairs with the runner's ``runner.rbac.namespaceScoped: true`` for a fully namespace-scoped -Robusta install β€” see :ref:`RBAC: Namespace-Scoped Runner `, which -also covers the runner-side environment variables, disabling playbooks and kubewatch, and -verification. - -.. note:: - - ``namespaceScopedRBAC`` requires a Holmes chart **newer than 0.41.0**. If the Robusta chart - version you run still bundles an older Holmes chart, use Option 2 below, or set - ``holmes.createServiceAccount: false`` + ``holmes.customServiceAccountName`` and manage the - namespaced RBAC yourself. - -.. _holmes-rolebindings-manual: - -Option 2 β€” grant one Holmes access to a set of namespaces ---------------------------------------------------------- - -To give a single Holmes instance access to specific namespaces (rather than its own only), create -your own ``RoleBinding`` objects that **reuse the ServiceAccount and ClusterRole the chart already -creates**, and remove the cluster-wide binding. You do not need to create a ServiceAccount or -ClusterRole yourself. - -What the chart already creates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -With the default values, the Holmes chart creates these objects (```` is your Helm release name, -usually ``robusta``, in the release namespace): - -.. list-table:: - :header-rows: 1 - :widths: 30 30 40 - - * - Kind - - Name - - Purpose - * - ServiceAccount - - ``-holmes-service-account`` - - Identity the Holmes pod runs as - * - ClusterRole - - ``-holmes-cluster-role`` - - The read permissions Holmes needs (rules only) - * - ClusterRoleBinding - - ``-holmes-cluster-role-binding`` - - Grants the ClusterRole **cluster-wide** β€” this is what makes Holmes see every namespace - -Reuse the ServiceAccount and ClusterRole; replace the binding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Step 1 β€” Create a ``RoleBinding`` in each namespace Holmes should access. It binds the **existing** -ServiceAccount to the **existing** ClusterRole, but a ``RoleBinding`` only grants those rules inside its own -namespace: - -.. code-block:: yaml - - # holmes-rolebindings.yaml (one RoleBinding per target namespace) - apiVersion: rbac.authorization.k8s.io/v1 - kind: RoleBinding - metadata: - name: holmes-namespace-scoped - namespace: default # repeat this file for "monitoring", etc. - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole # reuse the chart's ClusterRole (rules only) - name: robusta-holmes-cluster-role - subjects: - - kind: ServiceAccount - name: robusta-holmes-service-account # reuse the chart's ServiceAccount - namespace: - -.. code-block:: bash - - kubectl apply -f holmes-rolebindings.yaml - -Step 2 β€” Remove the cluster-wide binding, otherwise it still grants Holmes access to every namespace and the -RoleBindings above are redundant: - -.. code-block:: bash - - kubectl delete clusterrolebinding robusta-holmes-cluster-role-binding - -Holmes now has read access only in the namespaces where you created a RoleBinding. - -.. warning:: - - A ``helm upgrade`` re-creates ``robusta-holmes-cluster-role-binding`` (the chart always renders it), - which restores cluster-wide access. After each upgrade, re-run the ``kubectl delete`` above, or manage - the deletion/RoleBindings through your GitOps/post-render tooling. - -How it works -~~~~~~~~~~~~ - -In Kubernetes RBAC a ``ClusterRole`` is only a set of permissions. On its own it grants nothing β€” the -**binding type** decides where those permissions apply: - -.. list-table:: - :header-rows: 1 - :widths: 40 60 - - * - Binding - - Effective scope - * - ``ClusterRoleBinding`` β†’ ClusterRole - - Every namespace **plus** cluster-scoped resources (nodes, persistentvolumes, ...) - * - ``RoleBinding`` (in namespace ``X``) β†’ ClusterRole - - Only namespaced resources **in namespace** ``X`` - -A ``RoleBinding`` may reference a ``ClusterRole``; when it does, Kubernetes applies that ClusterRole's rules -but confined to the RoleBinding's own namespace. That is why we can reuse the chart's ClusterRole without -duplicating its rules β€” one rule set, one thin binding per namespace. When Holmes' ServiceAccount makes a -request, the authorizer checks all ClusterRoleBindings plus the RoleBindings in the request's namespace: a -``list pods`` in ``default`` matches the RoleBinding there and is allowed; the same request in -``kube-system`` matches nothing and is denied. - -.. important:: - - Access is limited to **namespaced** resources in the bound namespaces. **Cluster-scoped** resources - (for example ``nodes``, ``persistentvolumes``, cluster-level events) are no longer granted, because a - ``RoleBinding`` structurally cannot grant them β€” only a ``ClusterRoleBinding`` can. Tools that rely on - them (node health, cluster-wide resource views) will not work in scoped mode. - -.. note:: - - ``kubectl auth can-i list nodes --as= -n default`` may return ``yes`` even though real node - access is denied. Passing ``-n default`` evaluates the check *inside* the default namespace, where the - RoleBinding grants the ``nodes`` rule, and the authorizer matches verb+resource without re-checking that - ``nodes`` is cluster-scoped. A real ``kubectl get nodes`` (empty namespace) matches no binding and is denied. - -Verifying the scope -~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - SA=system:serviceaccount::robusta-holmes-service-account - - kubectl auth can-i list pods --as=$SA -n default # -> yes - kubectl auth can-i list pods --as=$SA -n monitoring # -> yes - kubectl auth can-i list pods --as=$SA -n kube-system # -> no - -Tell Holmes which namespaces it can access -------------------------------------------- - -Holmes has no way to discover its own RBAC scope. A denial only ever names the resource and namespace that -were **rejected** ("...cannot list resource pods ... in the namespace kube-system"); it never lists the -namespaces that are **allowed**. Without guidance, Holmes may assume it has cluster-wide access, repeatedly -retry cluster-wide queries (``kubectl get pods -A``, ``get nodes``), or mistake the ``Forbidden`` errors for -a broken cluster. - -After scoping, add a **global instruction** telling Holmes exactly which namespaces it may use. Global -instructions are account-level and are injected into Holmes' system prompt for every investigation; set them -in the Robusta UI (HolmesGPT settings β†’ global instructions). Keep the list in sync with the namespaces you -bound above. - -Example global instruction (Option 2, one Holmes with a fixed namespace list): - -.. code-block:: text - - This HolmesGPT instance has namespace-scoped RBAC. You can only read Kubernetes resources in the - "default" and "monitoring" namespaces. Always scope kubectl queries with `-n default` or `-n monitoring`. - Do not run cluster-wide queries such as `kubectl get pods -A`, `kubectl get nodes`, or - `kubectl get namespaces` β€” they will be denied. If something you need is in another namespace, report - that it is outside your permitted scope instead of retrying. - -With **Option 1** this is handled automatically: ``namespaceScopedRBAC`` sets the -``SCOPED_NAMESPACES`` environment variable and the scope instructions are injected into Holmes' -system prompt β€” no global instruction needed. The guidance below applies to Option 2, and to -Option 1 on Holmes chart versions that predate ``SCOPED_NAMESPACES``. - -Because global instructions are **account-level** (shared by every cluster and instance in the -account), a fixed namespace list only works when all your instances share the same scope. With -multiple namespace-scoped instances, phrase the instruction generically instead: - -.. code-block:: text - - Each HolmesGPT instance in this account has namespace-scoped RBAC, limited to the namespace it is - installed in. Always scope kubectl queries to your own namespace with `-n`. Do not run cluster-wide - queries such as `kubectl get pods -A`, `kubectl get nodes`, or `kubectl get namespaces` β€” they will - be denied. If something you need is in another namespace, report that it is outside your permitted - scope instead of retrying. - -Notes on the runner -------------------- - -By default the Robusta runner remains cluster-wide. To reduce the runner's permissions, use -:ref:`a read-only ClusterRole ` via ``runner.overrideClusterRoles``, -or run the runner itself with a namespace-scoped service account β€” see -:ref:`RBAC: Namespace-Scoped Runner ` (requires disabling discovery, -playbooks and the kubewatch forwarder). diff --git a/docs/setup-robusta/read-only-service-account.rst b/docs/setup-robusta/read-only-service-account.rst index 8ea2f4ad0..af57af3cb 100644 --- a/docs/setup-robusta/read-only-service-account.rst +++ b/docs/setup-robusta/read-only-service-account.rst @@ -10,7 +10,7 @@ By default, Robusta's runner service account has permissions to update and delet If you only want to remove the namespace-scoped create permissions (used for scan Jobs, debugger pods and the KRR auth Secret), set ``runner.rbac.disableCreateFromServiceAccount: true`` in your Helm values. This removes the namespaced Role and disables the built-in playbooks that - depend on it (``NodeFSSpaceAlerts``, ``WeeklyKRRScan``); actions that create resources + depend on it (``NodeFSSpaceAlerts``); actions that create resources (scans, kubectl/netshoot/stress, debugger pods, chaos engineering) will fail without permissions. For fully read-only mode, use ``overrideClusterRoles`` as described below. @@ -21,8 +21,6 @@ Read-only mode is useful in scenarios where you want to: - **Prevent accidental modifications**: Ensure that even if a playbook or investigation logic has a bug, no cluster resources will be modified - **Comply with security policies**: Meet organizational requirements for read-only access in certain environments -- **Prevent node operations**: Prevent users from draining or restarting nodes through investigations -- **Audit-only mode**: Run Holmes for investigation and diagnostics without remediation capabilities Limitations of Read-Only Mode ----------------------------- diff --git a/docs/setup-robusta/robusta-runner-metrics.rst b/docs/setup-robusta/robusta-runner-metrics.rst index b6c781b58..1381b144b 100644 --- a/docs/setup-robusta/robusta-runner-metrics.rst +++ b/docs/setup-robusta/robusta-runner-metrics.rst @@ -1,17 +1,13 @@ Self-Monitoring ====================================== -Robusta Metrics Graphs +Robusta Metrics ************************** Robusta runner supports Prometheus and exposes performance and error metrics on the `/metrics` endpoint. -After Prometheus discovers the ServiceMonitor, the robusta-runner page in the UI will automatically include graphs as shown below. -.. image:: /images/robusta-metrics.png - :align: center -This guide will help you setup Robusta to observe the collected monitoring data on the Robusta platform. Exposing Robusta metrics endpoint *********************************** @@ -126,4 +122,3 @@ Robusta helm installation will deploy the following ServiceMonitor CRD into your Adjust the Robusta ServiceMontior labels so they match the Prometheus CRD. -Now the metrics graph should be visible on the Robusta UI. diff --git a/docs/track-changes/kubernetes-changes.rst b/docs/track-changes/kubernetes-changes.rst deleted file mode 100644 index 5de8b5d9b..000000000 --- a/docs/track-changes/kubernetes-changes.rst +++ /dev/null @@ -1,12 +0,0 @@ -Kubernetes Changes -================== - -.. toctree:: - :maxdepth: 1 - :hidden: - - LaunchDarkly <../configuration/alertmanager-integration/launchdarkly> - -When using Robusta SaaS, Robusta automatically tracks all Kubernetes changes and correlates them with alerts. - -This provides context about recent changes when investigating issues, helping you quickly identify if a deployment, configuration update, or other change caused a problem.