Grafana Image Renderer Setup Prompt

You are a senior Grafana admin who deploys the image renderer for panel PNGs, alert notification images, and reports.

I will provide:
- The Grafana deployment (container, VM, HA)
- What needs rendering (alerts, reports, shared images)
- Current rendering config

Your job:

1. **Choose an install mode**:
   - Plugin (`grafana-image-renderer`) installed alongside Grafana
   - Remote rendering service (separate container, recommended for HA)
2. **For the remote service**:
   - Run the `grafana/grafana-image-renderer` container
   - Set `[rendering] server_url` and `callback_url` in grafana.ini
   - `callback_url` must be the address the renderer can reach Grafana on
3. **Size the renderer**:
   - Headless Chromium is memory-hungry; set concurrency limits
   - Use `RENDERING_MODE=clustered` with `RENDERING_CLUSTERING_MODE`
   - Cap `RENDERING_CLUSTERING_MAX_CONCURRENCY`
4. **Wire alert images**:
   - Contact points reference rendered panel images
   - Requires the renderer to reach Grafana and load the panel
5. **Handle auth and networking**:
   - Renderer needs network access to Grafana; secure that path
   - Behind a proxy, set the callback URL correctly or images fail
6. **Tune timeouts**:
   - Increase render timeout for heavy dashboards
   - Watch for Chromium zombie processes; set restart policy
7. **Validate**:
   - Hit `/render/version`; render a test panel via API
   - Confirm alert images and report PDFs render end to end

Mark DESTRUCTIVE: restarting Grafana to apply rendering config (brief downtime), changing callback_url (breaks all rendering if wrong).

---

Deployment: [DESCRIBE]
What needs rendering: [DESCRIBE]
Current config: [DESCRIBE]

Why this prompt works

Rendering fails in ways that look mysterious: blank alert images, failed report PDFs, “rendering plugin not available.” Almost always it is the callback_url, missing Chromium libraries, or concurrency-driven OOM. This prompt picks the right install mode and locks down the networking + sizing that actually determine whether rendering works.

How to use it

1. Pick plugin vs remote service (remote for HA).
2. Set server_url and callback_url correctly.
3. Cap concurrency to avoid OOM.
4. Render a test panel end to end.

Useful commands

# Install as a plugin
grafana-cli plugins install grafana-image-renderer

# Run the remote renderer container
docker run -d --name renderer -p 8081:8081 \
  -e RENDERING_MODE=clustered \
  -e RENDERING_CLUSTERING_MODE=browser \
  -e RENDERING_CLUSTERING_MAX_CONCURRENCY=5 \
  grafana/grafana-image-renderer:latest

# Confirm it is up
curl -s http://renderer:8081/render/version

# Render a panel image via Grafana API to test end to end
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  "http://grafana:3000/render/d-solo/$DASH_UID/panel?panelId=2&width=1000&height=500" -o test.png

Example config

# grafana.ini — remote rendering service
[rendering]
server_url = http://renderer:8081/render
callback_url = http://grafana:3000/
concurrent_render_request_limit = 10

[log]
filters = rendering:debug

# docker-compose renderer service
services:
  renderer:
    image: grafana/grafana-image-renderer:latest
    ports:
      - "8081:8081"
    environment:
      RENDERING_MODE: clustered
      RENDERING_CLUSTERING_MAX_CONCURRENCY: "5"
      RENDERING_VIEWPORT_MAX_WIDTH: "3000"

Common findings this catches

• Blank/failed images → wrong callback_url.
• “Rendering plugin not available” → plugin not installed or renderer down.
• OOM kills → concurrency uncapped.
• Missing libs error → base image lacks Chromium dependencies.
• Timeouts on big boards → render timeout too low.
• Zombie processes → no restart policy on the renderer.

When to escalate

• HA renderer sizing and autoscaling — capacity planning.
• Securing the renderer-to-Grafana network path — security team.
• Persistent Chromium instability — upgrade or containerize the renderer.