Overview
Welcome to Kubegrade
Kubegrade is an operational layer for Kubernetes teams that need to keep clusters reliable, auditable, and maintainable as environments grow.
It helps platform teams and developers:
- Understand what is running across clusters
- Detect risk (drift, misconfigurations, upgrade issues)
- Investigate incidents faster
- Propose safe fixes as pull requests
- Execute changes through existing GitOps workflows
Kubegrade is built for real production environments and supports cloud, on-prem, and hybrid deployments. (Kubegrade)
What Kubegrade is (and isn’t)
What Kubegrade is
Kubegrade is a Kubernetes operations platform focused on day-2 operations, including:
- Upgrade management
- Troubleshooting
- Drift detection
- Visualization and dependency mapping
- GitOps-based remediation
- Guided/agentic workflows with human approval
It combines cluster state, configuration context, and workflow automation to help teams move from detection to action faster. (Kubegrade)
What Kubegrade isn’t
Kubegrade is not:
- A replacement for your Kubernetes provider (EKS/GKE/AKS/OpenShift)
- A cluster provisioner by default
- A generic CI/CD platform
- A pure observability tool
- A “black box” auto-remediator that bypasses human review
Kubegrade is designed to work with your existing tooling and processes, not replace them. The platform emphasizes human-in-the-loop approvals and GitOps execution. (Kubegrade)
Architecture at a glance
Kubegrade typically includes the following components:
1) Kubegrade Control Plane
The central service/UI where users:
- View cluster posture
- Run investigations
- Review plans and recommendations
- Approve remediations
- Manage policies, roles, and workflows
2) In-Cluster Agent(s)
Lightweight agents/controllers deployed in target clusters that:
- Collect telemetry/metadata
- Execute approved workflows
- Respect cluster RBAC and network boundaries
- Support upgrade planning and operational actions
Your current docs draft already describes Kubegrade agents as lightweight controllers that execute plans and collect telemetry securely, while respecting RBAC/network isolation. (Archbee)
3) IaC / Git / GitOps Integrations
Kubegrade connects to:
- IaC/config sources (Terraform, Helm, Kustomize)
- Git repositories
- GitOps systems (Argo CD / Flux) to generate auditable PRs and align runtime state with declared state.
4) Observability / Notification Integrations
Kubegrade can connect to monitoring, alerting, and collaboration systems to enrich context and route actions.
Core workflow: Scan → Visualize → Propose PR → Approve → Execute (GitOps)
This is Kubegrade’s core operating loop and mirrors your current site workflow. (Kubegrade)
1) Scan
Kubegrade analyzes:
- Cluster resources and workload state
- Events and signals
- Configuration and policy posture
- IaC / Git definitions (when connected)
Purpose:
- Identify drift, risk, failures, or upgrade blockers
- Build context for troubleshooting and change recommendations
2) Visualize
Kubegrade presents interactive views of:
- Cluster objects and dependencies
- Service relationships
- Warning states and impacted components
- Relevant context for investigations
This aligns with your current positioning around interactive dependency graphs and detailed insights. (Kubegrade)
3) Propose PR
Kubegrade drafts changes as pull requests (e.g., YAML, Helm values, Terraform changes) so teams can review proposed remediations in their existing workflow. Your homepage explicitly references AI-drafted PRs and GitOps execution. (Kubegrade)
4) Approve
Teams review:
- Proposed changes
- Safety checks and policy outcomes
- Scope of impact
- Execution plan / timing
Kubegrade is designed to keep humans in the loop. (Kubegrade)
5) Execute (GitOps)
Changes are applied through your GitOps process (e.g., Argo CD or Flux), preserving:
- Auditability
- Review controls
- Provenance of change
- Rollback paths
Glossary
Agent
A lightweight Kubegrade component deployed in a cluster that collects metadata/telemetry and executes approved workflows within the permissions granted to it. (Archbee)
Audit Trail
A record of user actions, system recommendations, approvals, and executed changes.
Cluster
A Kubernetes environment managed by a provider or self-hosted control plane.
Drift
A mismatch between desired configuration (Git/IaC) and actual runtime cluster state.
Environment
A logical stage of delivery such as dev, staging, or production.
GitOps Remediation
A workflow where Kubegrade proposes infrastructure/application changes as pull requests and changes are applied by GitOps tooling after merge.
Human-in-the-loop
A control model where Kubegrade can automate analysis and recommendations, but users review/approve before execution.
Policy / Guardrail
A rule that constrains or validates what changes are allowed, who can run actions, and when.
Project
A logical grouping of clusters, workflows, and policies tied to a team or application area.
Workspace
A higher-level boundary used to organize projects, clusters, users, and policies (especially for larger teams). Your draft docs already mention workspaces grouping clusters, policies, and automation workflows. (Archbee)
Getting Started
Quickstart (first cluster in 5 mins)
This quickstart gets you from account access to a connected cluster and first safe change proposal.
Step 1 — Sign in to Kubegrade
- Create/login to your Kubegrade account
- Select or create an organization/workspace
Step 2 — Add a cluster
- Choose your provider (EKS / GKE / AKS / OpenShift / self-managed)
- Install the Kubegrade agent into the target cluster
- Confirm cluster registration in the UI
Step 3 — Connect GitOps and/or IaC (recommended)
- Link your Git provider/repository
- Optionally connect Terraform/Helm/Kustomize sources
- Map cluster/workspace to repo(s)
Step 4 — Run an initial scan
- Trigger a cluster scan
- Review health, warnings, drift indicators, and object graph
Step 5 — Run a safe workflow
Example:
- Select a non-production namespace
- Trigger a validation/fix recommendation workflow
- Review generated PR
- Approve and merge via your normal Git process
- Confirm rollout status in GitOps
Requirements
Minimum platform requirements
- A Kubernetes cluster you can administer (or delegated access to install an agent)
- Permission to create Kubernetes resources (agent install)
- Outbound network access from the cluster to Kubegrade endpoints (for SaaS/hybrid modes)
- Access to your Git/IaC repositories for PR workflows (optional but strongly recommended)
Recommended operational prerequisites
- One GitOps tool (Argo CD or Flux)
- Namespace/environment conventions (dev/stage/prod)
- Basic RBAC model for platform/dev/auditor roles
- Staging environment for testing before production rollout
Supported targets (high level)
- Managed Kubernetes providers (EKS, GKE, AKS)
- Enterprise/self-managed clusters (OpenShift, Rancher/RKE, upstream Kubernetes)
- Hybrid/multi-cluster environments
Deployment options (SaaS / on-prem / hybrid)
SaaS
Kubegrade control plane is hosted by Kubegrade. You install agents in your clusters and connect supported integrations.
Best for:
- Faster setup
- Lower operational overhead
- Centralized management
On-prem
Kubegrade control plane and data plane components run in your environment.
Best for:
- Regulated workloads
- Strict data residency or network constraints
- Enterprises requiring private deployment models
Hybrid
A mix of hosted and private components (e.g., hosted control plane with private agents/connectivity and controlled data paths).
Best for:
- Enterprises that want managed UX plus controlled execution/data boundaries
Your homepage explicitly states cloud, on-prem, and hybrid support. (Kubegrade)
Connect your first cluster
1) Choose provider and cluster
From the Kubegrade UI:
- Select Add Cluster
- Choose provider type
- Name the cluster and assign environment (dev/stage/prod)
- Assign workspace/project
2) Install Kubegrade agent
Deploy the provided manifest/Helm chart to the cluster.
Typical installation includes:
- Namespace for Kubegrade agent components
- Service account and RBAC resources
- Deployment(s) for agent/controller
- Optional secret/config resources (depending on integration mode)
3) Register and validate
Kubegrade validates:
- Agent heartbeat
- API connectivity
- Permission scope
- Basic cluster inventory access
4) Assign scope
Optionally restrict the cluster integration to:
- Specific namespaces
- Specific actions/workflows
- Read-only mode for initial rollout
Connect IaC
Kubegrade becomes more powerful when it can compare live state against declared configuration and generate changes in the same systems your team already uses.
Supported IaC/config types
- Terraform
- Helm
- Kustomize
What connecting IaC enables
- Runtime vs IaC comparison
- Drift detection with source context
- PR generation against your actual config repo
- Safer remediation with reviewable changes
Typical setup flow
- Connect Git provider/repository
- Select repo path(s)
- Identify config format (Terraform/Helm/Kustomize)
- Map repo to cluster/workspace/environment
- Validate access and test diff parsing
Your site and docs drafts already emphasize cluster + IaC context, PR suggestions, and support for Helm/Terraform/Argo CD integrations. (Kubegrade)
Verify access + health checks
After cluster and IaC connection, confirm the following:
Cluster connectivity
- Agent is online
- Cluster API reachable
- Inventory sync successful
Permissions
- Agent can read required resource types
- Write/execute permissions align with intended mode (read-only vs execution-enabled)
- Namespace restrictions are correctly enforced
Integrations
- Git repository access verified
- GitOps system connection valid (if configured)
- Observability integrations reachable (if configured)
Health checks (recommended)
- Run a metadata-only scan
- Open dependency graph view
- Test a dry-run recommendation (no execution)
- Review audit log entries for setup actions
First workflow run (example: safe change via PR)
Use a low-risk, non-production example to validate end-to-end flow.
Example workflow: Fix configuration drift in a dev namespace
- Select cluster and namespace (dev)
- Run drift detection scan
- Review identified drift
- Ask Kubegrade to propose remediation
- Review generated PR (files, diffs, rationale)
- Approve PR generation
- Merge PR in Git provider
- Let Argo CD / Flux apply the change
- Confirm drift resolved in Kubegrade
What success looks like
- Drift warning cleared
- PR linked in audit trail
- GitOps rollout status visible
- No unapproved direct mutation in cluster
Platform Concepts
Organizations, workspaces, projects
Organization
Top-level account boundary for:
- Users
- Billing
- Security settings
- Shared policies and integrations
Workspace
Operational grouping for teams or business units. Your draft docs describe workspaces as grouping clusters, policies, and automation workflows. (Archbee)
Use workspaces to separate:
- Teams
- Business domains
- Regions
- Compliance zones
Project
A scoped unit within a workspace used to group:
- Related clusters
- Applications/services
- Policies
- Workflow defaults
Recommended pattern:
- Org = company
- Workspace = platform domain / BU / region
- Project = product/service/application group
Clusters and environments (dev/stage/prod)
Kubegrade supports managing multiple clusters and mapping them to lifecycle environments.
Cluster
A Kubernetes environment (EKS/GKE/AKS/OpenShift/self-managed) connected to Kubegrade.
Environment
A logical delivery stage:
- dev: experimentation, low-risk validation
- staging: production-like testing and upgrade rehearsals
- prod: business-critical execution with stricter controls
Best practices
- Tag clusters with environment metadata
- Apply stricter guardrails to production
- Rehearse upgrades/remediations in staging before prod
- Use separate approval policies per environment
Your draft docs already define clusters as logical units representing environments such as dev/staging/prod. (Archbee)
Namespaces and scope controls
Namespaces are the primary unit for multi-tenant control within a cluster.
Kubegrade supports scope control at multiple layers:
- Cluster-level scope
- Namespace-level scope
- Workflow/action-level scope
- Role-based access scope
Common use cases
- Developers can view and run approved workflows only in assigned namespaces
- Platform admins can manage upgrades cluster-wide
- Auditors get read-only access to dashboards and logs
Recommended rollout
- Start with read-only access across the cluster
- Enable execution for non-prod namespaces first
- Expand gradually with explicit policies
Policies and guardrails
Policies and guardrails define what Kubegrade can recommend or execute, and under what conditions.
Policy types (typical)
- Approval requirements (who must approve)
- Time windows (maintenance windows only)
- Scope restrictions (namespace/cluster/workspace)
- Change restrictions (e.g., no prod write actions without multi-approval)
- Execution mode (read-only, suggest-only, execute-via-GitOps)
- Severity-based routing (critical issues escalate)
Guardrail goals
- Prevent unsafe actions
- Maintain consistency
- Enforce compliance requirements
- Preserve human oversight
Human-in-the-loop approvals
Kubegrade is designed to support automation without removing operator control. Your site and troubleshooting page both emphasize human-in-the-loop operation. (Kubegrade)
What human-in-the-loop means in Kubegrade
- Kubegrade can analyze and propose actions
- Users review generated plans/PRs
- Execution requires approval based on policy
- GitOps remains the system of execution when enabled
Approval stages (common)
- Recommendation review
- PR generation approval
- Merge approval (in Git provider)
- Post-change verification review (optional)
Why this matters
- Reduced risk
- Better auditability
- Easier adoption by platform teams
- Compliance alignment
Audit trail model
Kubegrade maintains a traceable history of operational activity.
Typical audit events
- User sign-in / role changes
- Cluster connection updates
- Policy changes
- Workflow runs
- Recommendations generated
- PRs created/linked
- Approvals granted/denied
- Execution outcomes
- Rollback actions
Audit trail goals
- Explain what changed
- Show who approved it
- Link recommendations to actual diffs/PRs
- Support incident reviews and compliance checks
Your draft docs mention audit logs and historical audit timelines/execution trails. (Archbee)
Roles & permissions (owner / admin / developer / viewer)
Your draft docs already describe a role model including organization owner, cluster administrator/admin, developer, and viewer/auditor. (Archbee)
Owner
Full access to the organization. Can typically:
- Manage billing and org-wide settings
- Manage all users and roles
- Configure identity integration
- View all projects/clusters/workspaces
- Override policy defaults (if permitted)
Admin
Administrative access within assigned workspace/project/cluster scopes. Can typically:
- Connect clusters and integrations
- Manage policies and team assignments
- Run and approve operational workflows (within scope)
- Configure execution settings
Developer
Operational access for application teams within assigned scopes. Can typically:
- View cluster/workload state
- Run approved workflows in assigned namespaces
- Review recommendations and open PRs
- Access dashboards and troubleshooting views
Viewer
Read-only access. Can typically:
- View dashboards, graphs, and audit logs
- Review compliance/audit posture
- Export reports (if enabled) Cannot execute or approve changes.
Security & Infrastructure
Security overview
Kubegrade is designed for enterprise Kubernetes operations with strong emphasis on:
- Least-privilege access
- Human-in-the-loop approvals
- GitOps-based change execution
- Auditability
- Support for private/on-prem/hybrid deployments
Your public messaging already emphasizes secure, auditable workflows and human oversight. (Kubegrade)
Data handling & what leaves the cluster
Kubegrade should be documented as using a minimum necessary data model, with deployment-mode differences.
Typical data used by Kubegrade
- Kubernetes object metadata and configuration state
- Events / status conditions
- Health and dependency context
- Workflow execution metadata
- Optional integration metadata (Git/IaC references, alert identifiers)
What may leave the cluster (SaaS / hybrid)
Depending on configuration:
- Telemetry metadata
- Resource state summaries
- Policy/drift findings
- Workflow request/response metadata
- Optional logs/diagnostic snippets (if enabled)
What should be explicitly documented by deployment mode
- Whether payloads include object specs vs metadata only
- Whether secrets are collected (recommended: no secret values)
- Retention periods
- Encryption in transit / at rest
- Regional hosting options (if any)
Your draft docs note agents collecting telemetry securely and not exfiltrating beyond telemetry metadata; formalize exact behavior here. (Archbee)
Network requirements (egress, proxies)
Outbound connectivity (typical)
Agents usually require outbound access to:
- Kubegrade control plane endpoints
- Identity endpoints (if SSO-enabled)
- Git provider APIs (if PR generation enabled)
- Optional observability APIs/integrations
Inbound connectivity
Prefer no inbound internet exposure to clusters for SaaS mode (outbound-only agent pattern), where possible.
Proxy support
Document support for:
- HTTP/HTTPS proxy
- Authenticated proxies
- Custom CA bundles
- NO_PROXY exclusions for internal services
Recommended documentation items
- Exact FQDNs / ports
- TLS requirements
- Timeout/retry behavior
- Firewall allowlist guidance
Private connectivity (VPC/VNet peering / PrivateLink equivalent if applicable)
If supported, document private connectivity options by cloud:
- AWS: PrivateLink / VPC peering / Transit Gateway patterns
- Azure: Private Endpoint / VNet peering
- GCP: Private Service Connect / VPC peering
- Enterprise private routing for on-prem hybrid deployments
If not yet GA:
- Mark as “available by deployment model / enterprise request”
- Document supported reference architectures
- Clarify what remains public (if anything)
IP allowlisting
For environments enforcing outbound restrictions:
- Publish Kubegrade egress destination IPs/CIDRs (if static)
- Or publish endpoint domains with certificate pinning guidance
- Document IP rotation/change notification policy
- Provide separate lists for SaaS regions if applicable
For inbound (if any webhooks/callbacks used):
- Publish Kubegrade source IPs for webhook delivery
TLS / certificates
In transit
- TLS for agent ↔ control plane communication
- TLS for web UI/API access
- TLS for integration calls (Git, observability, identity providers)
Enterprise requirements
Document support for:
- Custom CA trust bundles
- Internal PKI certificates (on-prem)
- TLS termination models (if self-hosted)
- Certificate rotation practices
Best practice
- Never disable certificate verification in production
- Rotate credentials/certs on schedule
- Separate certs per environment where possible
Secrets management
Kubegrade should avoid collecting or storing secret values unless strictly required.
Recommended approach
- Use Kubernetes Secrets only for agent/integration credentials where necessary
- Prefer external secret managers and short-lived credentials
- Scope credentials per workspace/project/integration
- Encrypt secrets at rest
- Redact secrets from logs/UI/audit exports
Documentation should specify
- Where secrets live (SaaS/on-prem/hybrid differences)
- Rotation procedures
- Revocation procedures
- How to re-authenticate integrations without downtime
RBAC model + least privilege
Your draft docs already emphasize access controls and agent respect for RBAC. (Archbee)
RBAC principles
- Least privilege by default
- Read-only initial onboarding mode
- Explicit elevation for execution-enabled workflows
- Namespace scoping where practical
- Separate permissions for analysis vs action
Kubernetes-side RBAC
Document:
- Required API groups/resources for read operations
- Additional permissions required for execution workflows
- Optional privileges by module (upgrades, drift remediation, troubleshooting actions)
Kubegrade app RBAC
Document:
- Owner/Admin/Developer/Viewer permissions
- Scope inheritance (org → workspace → project → cluster)
- Approval authority vs execution authority separation
Compliance notes (SOC2/ISO)
Use this page as a factual capability page (not a marketing claim page).
Include only confirmed claims
Document:
- Compliance frameworks supported by platform controls (e.g., audit logs, RBAC, approval workflows, least privilege)
- Security practices relevant to customer audits
- Deployment models for regulated environments (on-prem/hybrid)
- Data handling controls
If certifications are in progress
State clearly:
- “SOC 2 / ISO 27001 status” (in progress / planned / certified)
- Scope of certification (company vs product vs hosting environment)
Do not overstate certification or attestation status unless already formalized.
Product Modules (mirrors your website product pages)
Upgrade Management
Overview
Kubegrade Upgrade Management helps teams reduce manual effort and upgrade risk by turning Kubernetes upgrades into a guided, auditable workflow.
Core outcomes:
- Faster upgrade planning
- Preflight validation before changes
- Safer execution with approvals
- PR-based, GitOps-compatible remediation where config changes are required
- Better auditability and rollback readiness
Your public messaging strongly emphasizes upgrade automation, safety checks, and reduced manual toil. (Kubegrade)
Supported Kubernetes versions/providers
Document support as a compatibility matrix.
Providers
- EKS
- GKE
- AKS
- OpenShift
- Rancher/RKE (if supported)
- Self-managed upstream Kubernetes
Version support format (recommended)
Provide:
- Minimum supported version per provider
- Tested upgrade paths (N → N+1, etc.)
- Unsupported/skipped paths
- Provider-specific notes (managed add-ons, control plane sequencing, nodegroup specifics)
Preflight checks (API deprecations, add-ons, constraints)
Preflight checks are run before upgrade execution to identify blockers and risk.
Typical checks
- Kubernetes API deprecations in manifests
- Add-on compatibility (CNI, CSI, ingress controllers, metrics stack)
- Version skew constraints
- Pod disruption budget / capacity constraints
- Node image/runtime prerequisites
- Admission controller and policy conflicts
- Deprecated Helm chart APIs / CRD compatibility
- Cluster health baseline (unhealthy nodes, failing workloads)
Output
Preflight results should be categorized as:
- Blockers (must fix)
- Warnings (recommended fixes)
- Informational notes
Upgrade plans (single / multi-cluster)
Single-cluster upgrade plan
Includes:
- Cluster target version
- Preflight status
- Required remediations
- Maintenance window
- Rollback strategy
- Approval requirements
Multi-cluster upgrade plan
Adds:
- Sequencing (canary → staging → production)
- Cluster grouping by environment/provider/team
- Parallelism constraints
- Success gates between waves
- Standardized runbook application
Recommended pattern
- Canary cluster
- Staging cluster(s)
- Limited production wave
- Broad production rollout
Scheduling + maintenance windows
Kubegrade should support scheduling upgrades and workflows within controlled windows.
Scheduling capabilities (recommended)
- One-time scheduled execution
- Recurring maintenance windows
- Timezone-aware windows
- Environment-specific restrictions
- Freeze windows / blackout periods
Operational controls
- Preflight refresh before execution
- Re-approval if conditions changed
- Auto-cancel on critical health regressions (if configured)
What gets written where (PR contents, provenance)
When Kubegrade proposes upgrade-related changes, document exactly what gets generated.
Typical PR contents
- Manifest or values updates
- Version pin changes
- Compatibility fixes
- Config changes required by target version
- Explanatory summary of why changes are required
- References to preflight findings
Provenance metadata (recommended)
- Workflow run ID
- Cluster / environment
- Policy checks passed/failed
- Agent/version used
- Timestamp
- Approver(s) (linked in audit trail)
This aligns with your PR suggestion + GitOps execution model and auditability positioning. (Kubegrade)
Runbooks: common upgrade failure modes
1) Node upgrade stalls
Possible causes:
- Pod disruption budgets too strict
- Capacity shortage
- DaemonSet rollout blocking drain
- Misconfigured eviction settings
Response:
- Review draining events
- Temporarily scale capacity / relax constraints (approved)
- Retry wave
2) Workloads fail after upgrade
Possible causes:
- API deprecations missed
- Admission/policy incompatibility
- Ingress/controller changes
- CRD/version mismatch
Response:
- Review failing workloads and dependency graph impact
- Generate remediation PR
- Roll back workload config or cluster wave if needed
3) Add-on incompatibility
Possible causes:
- Unsupported add-on version for target K8s version
- CSI/CNI version skew
- Metrics/monitoring stack incompatibility
Response:
- Pin compatible add-on version
- Upgrade add-ons in required order
- Re-run preflight
4) Control plane/node version skew issues
Response:
- Validate provider sequencing rules
- Reconcile managed nodegroups
- Apply supported path only
Troubleshooting
Overview
Kubegrade Troubleshooting turns Kubernetes troubleshooting from a reactive, manual process into a guided, context-rich workflow with automation and human control.
Your current product page explicitly positions troubleshooting as intelligent/automated, with multi-layer diagnosis, dependency graphs, and human-in-the-loop controls. (Kubegrade)
Guided investigations (what Kubegrade inspects)
Kubegrade investigates issues using correlated signals across Kubernetes layers.
Common inspection domains
- Pod and container status
- Events and recent changes
- Resource pressure (CPU/memory)
- Scheduling constraints
- Service/endpoints/ingress routing
- DNS/network indicators
- ConfigMaps/Secrets references and misconfigurations
- Dependency relationships across workloads/services
Your troubleshooting page specifically mentions issue propagation via dependency graphs and common problem categories including DNS, scheduling, ConfigMaps/Secrets, and performance/resource bottlenecks. (Kubegrade)
Common incident playbooks (CrashLoopBackOff, OOM, 5xx, DNS, etc.)
CrashLoopBackOff
Kubegrade checks:
- Container logs
- Exit codes
- Liveness/readiness probe failures
- Missing env/config/secret references
- Recent config changes
Typical outputs:
- Root-cause candidates
- Impacted dependent services
- Proposed config or probe adjustments via PR
OOMKilled / resource exhaustion
Kubegrade checks:
- Memory limits/requests
- Actual usage patterns
- Recent release changes
- Node pressure and eviction signals
Typical outputs:
- Right-size recommendations
- HPA/resource tuning suggestions
- PR-ready config updates (if enabled)
5xx / ingress/service routing issues
Kubegrade checks:
- Ingress/controller status
- Service selectors/endpoints
- Pod readiness
- Upstream dependency health
- DNS/network path issues
DNS / network connectivity issues
Kubegrade checks:
- CoreDNS status
- Service DNS resolution
- NetworkPolicy constraints
- Endpoint availability
- Namespace/service name mismatches
Scheduling failures
Kubegrade checks:
- Resource requests vs node capacity
- Taints/tolerations
- Node selectors / affinity
- PDB interactions
Evidence collection + timelines
Kubegrade should present investigations as a structured evidence chain.
Evidence types
- Events
- Status transitions
- Metrics snapshots
- Dependency graph changes
- Config diffs / Git changes
- Alert triggers (if integrated)
Timelines
A useful incident timeline should show:
- First observed symptom
- Related alerts and state transitions
- Changes preceding the incident
- Actions taken (manual or Kubegrade-assisted)
- Recovery confirmation
Your draft docs mention historical audit timelines and execution trails, which can be reused here. (Archbee)
Suggested remediations → PR workflow
For supported cases, Kubegrade can convert troubleshooting findings into reviewable changes.
Flow:
- Investigation identifies root-cause candidates
- Kubegrade proposes remediation options
- User selects/edits preferred option
- Kubegrade generates PR against Git/IaC source
- User reviews and merges
- GitOps applies
- Kubegrade verifies recovery signals
This directly matches your PR + GitOps model. (Kubegrade)
Post-incident review / export
After resolution, Kubegrade can support review and reporting.
Post-incident review contents
- Incident summary
- Affected clusters/namespaces/services
- Timeline of events and changes
- Root cause (confirmed/probable)
- Actions taken
- PR links / approvals
- Prevention follow-ups
Export options (recommended)
- JSON/CSV event export
- PDF/markdown incident report
- Webhook push to ticketing systems
- Linkable audit record
Drift Detection
Overview
Kubegrade Drift Detection identifies mismatches between your live cluster state and intended state (Git/IaC/policy baselines) so teams can correct drift before it becomes an outage or audit problem.
Your homepage and draft docs explicitly reference drift detection and cluster+IaC context. (Kubegrade)
Drift sources (cluster vs IaC vs Git)
Cluster vs IaC drift
Live cluster resources differ from Terraform/Helm/Kustomize-defined state.
Cluster vs Git drift
Git-tracked manifests/configs no longer match what is running in the cluster.
Policy baseline drift
Cluster/workload configuration diverges from internal standards or approved baselines.
Cross-environment drift
Staging/prod environments diverge unintentionally over time.
Drift policies (what to flag / severity)
What to flag (examples)
- Manual changes outside GitOps
- Resource limits/requests changed in cluster only
- NetworkPolicy differences
- Ingress/service selector mismatches
- Deprecated/unsupported API usage
- Missing labels/annotations required by policy
- Image tag/version deviations
- RBAC drift
Severity model (recommended)
- Critical: security/compliance risk, production impact likely
- High: likely operational risk or audit issue
- Medium: inconsistency or future risk
- Low: informational / cosmetic drift
Drift remediation via PR
Kubegrade should support turning drift findings into PRs that restore desired state.
Remediation modes
- Reconcile cluster to Git/IaC (preferred in GitOps environments)
- Update Git/IaC to reflect approved runtime changes (controlled exceptions)
- Open review-only recommendation without PR
PR contents
- Exact diff to restore alignment
- Drift classification and severity
- Evidence of where mismatch was detected
- Impact notes (if applicable)
Exclusions and suppression rules
Not all drift should trigger alerts.
Common exclusions
- Auto-generated labels/annotations
- Runtime status fields
- Ephemeral resources
- Known provider-managed mutations
- Approved temporary overrides (time-bound)
Suppression best practices
- Scope suppressions narrowly (resource/namespace/path)
- Add expiration date
- Require reason/comment
- Track suppressions in audit logs
Intelligent Dependency Graphs
Overview
Kubegrade provides deep cluster visualization and dependency mapping to help teams understand relationships, blast radius, and warning states quickly.
Your site and docs drafts both reference interactive dependency graphs and dynamic visual dashboards. (Kubegrade)
Object-level graph model (workloads/services/ingress/network)
Kubegrade’s graph should model object-level relationships such as:
- Namespace → workload (Deployment/StatefulSet/DaemonSet)
- Workload → pods
- Service → endpoints/pods
- Ingress → services
- ConfigMap/Secret references
- NetworkPolicy relationships
- Storage dependencies (PVC/PV)
- Optional external dependencies (via integrations/annotations)
Purpose:
- Faster root cause analysis
- Change impact assessment
- Upgrade dependency planning
Filters, scopes, saved views
Filters
- Cluster / environment
- Namespace
- Application/service
- Resource kind
- Health state / warning severity
- Owner/team labels
Scopes
Users should be able to graph:
- Full cluster
- Namespace only
- Service-centric blast radius
- Incident-specific subgraph
Saved views
Save and reuse views for:
- Critical services
- Upgrade canary scope
- Audit/compliance reviews
- Team handoffs
Warning states + “what changed” views
Warning states
Overlay graph nodes/edges with states such as:
- Degraded
- Pending / unschedulable
- Failed probes
- Policy violation
- Drift detected
- Upgrade blocker
“What changed” views
Compare graph snapshots over time to identify:
- New/removed dependencies
- Routing changes
- Config-linked impact
- Service endpoint shifts
This is especially useful for post-incident reviews and upgrade regressions.
Sharing and exporting views
Sharing
- Link-based internal sharing (RBAC-respected)
- Saved workspace/project views
- Embed in incident tickets/docs (if supported)
Exporting
- Image export (PNG/SVG)
- Data export (JSON graph metadata)
- Snapshot attachment to incident reports
AI Agents
Overview (agents are “goal-oriented workflows”)
Kubegrade AI Agents are goal-oriented operational workflows designed to help teams complete specific Kubernetes tasks (e.g., troubleshooting, upgrades, PR generation) with strong context and human control.
Your draft docs and public pages already describe agentic workflows, AI-driven assistance, and human-in-the-loop operation. (Archbee)
Built-in agents (upgrade, troubleshoot, PR generation)
Upgrade Agent
Purpose:
- Analyze target version readiness
- Run preflight checks
- Propose upgrade sequencing and remediation steps
- Generate PRs for required config changes
Troubleshooting Agent
Purpose:
- Investigate symptoms across multiple signal layers
- Identify probable causes
- Suggest and optionally prepare remediations
PR Generation Agent
Purpose:
- Convert approved remediation plans into repo-specific pull requests
- Preserve format/structure conventions
- Attach rationale and provenance metadata
Custom agents (your MCP / tool connectors model)
Custom agents let teams define workflows that combine Kubegrade context with external tool context.
Typical custom agent inputs
- Cluster metadata and object state
- Dependency graph context
- IaC source context (Terraform/Helm/Kustomize)
- Git/GitOps state
- External tools via connectors/MCPs (e.g., Terraform/ArgoCD/etc.)
Example custom use cases
- Policy enforcement workflows
- Scheduled drift checks + PR creation
- Environment readiness checks before releases
- Cost/risk posture reviews across fleet
Prompting patterns + guardrails
Even for AI-assisted workflows, outputs should be constrained.
Recommended prompting patterns
- Goal + scope + constraints (cluster/env/namespace)
- Desired action mode (analyze-only / propose / PR-ready)
- Risk tolerance and change restrictions
- Output format requirements (summary, checklist, PR body)
Guardrails
- Read-only by default for new workflows
- Policy checks before proposing or executing
- Explicit approval for PR generation/execution
- Scope limits (namespace/workspace/project)
- Logging/audit of agent actions and outputs
Approval + execution controls
Kubegrade keeps AI-assisted workflows under operator control.
Controls to document
- Approval requirements by severity/environment
- Who can run agents vs who can approve results
- Suggest-only mode vs PR generation mode
- Execution via GitOps only (recommended default for prod)
- Time-window restrictions
Feedback loop (how to improve suggestions)
Kubegrade can improve agent usefulness over time through operator feedback.
Feedback signals (recommended)
- Accepted vs rejected suggestions
- Edits made before PR generation
- Rollback frequency
- Time to resolution after applying recommendation
- “Incorrect root cause” or “missing context” tags
Why it matters
- Better remediation quality
- Less noisy suggestions
- More consistent outputs across teams
Your draft docs already mention learning from feedback to refine future operations. (Archbee)
GitOps Remediation
Overview
GitOps Remediation is Kubegrade’s workflow for converting operational findings (drift, incidents, upgrade blockers, optimization recommendations) into reviewable pull requests and applying changes through your existing GitOps system.
Your site explicitly describes PR suggestions and GitOps execution. (Kubegrade)
Supported repo layouts
Document support patterns clearly.
Common layouts
- Monorepo (all environments/services)
- Environment-per-folder
- Service-per-folder
- Repo-per-service
- Platform repo + app repos split
- Helm values repos
- Terraform module + environment composition repos
Best practice
Require users to define:
- Repo path mappings per cluster/environment
- File ownership / CODEOWNERS expectations
- Branch strategy
PR generation rules (naming, commit strategy, reviewers)
Branch naming (recommended)
kubegrade/<module>/<cluster>/<issue-or-workflow-id>
Examples:
- kubegrade/drift/prod-eu1/restore-nginx-limits
- kubegrade/upgrade/staging/1-29-preflight-fixes
Commit strategy
- One commit per logical remediation (preferred)
- Squash option for noisy generated changes
- Signed commits if required by org policy
Reviewers
- Auto-assign based on CODEOWNERS
- Add platform approvers for prod scopes
- Tag relevant service owners for workload-level changes
Policy checks before PR
Before opening a PR, Kubegrade should validate:
- Scope and permissions
- Policy compliance
- Environment restrictions
- Change-type restrictions
- Required approvals
- Optional dry-run validation/tests (if integrated)
If checks fail:
- Open recommendation without PR
- Show blocking reasons and remediation steps
Merge-to-apply mechanics
Kubegrade should document how changes get applied after PR merge.
Typical flow
- PR merged in Git provider
- GitOps tool (Argo CD / Flux) detects commit
- GitOps sync applies changes to cluster
- Kubegrade watches rollout status / post-change signals
- Audit trail links PR → sync → outcome
Recommended controls
- Sync windows
- Manual sync for production
- Health checks before marking complete
Rollback PRs
Rollback support should be explicit and safe.
Rollback approaches
- Revert generated PR commit(s)
- Generate rollback PR from known-good state
- Partial rollback for specific resources (advanced / policy-controlled)
Rollback triggers (examples)
- Failed post-change health checks
- Elevated error rates
- Dependency graph degradation
- SLO breach detected via integrations
Auditability: change provenance
Every GitOps remediation should be traceable.
Provenance fields (recommended)
- Workflow source (drift/troubleshoot/upgrade/etc.)
- Cluster/environment/namespace
- Agent/workflow version
- Trigger type (manual/scheduled/alert-driven)
- Approvers and timestamps
- PR link and commit SHA
- GitOps sync result
- Verification result
Alert Sorting (coming soon)
Overview
Alert Sorting will help teams reduce alert noise by grouping related events, surfacing high-priority issues, and connecting alerts to Kubegrade workflows for faster action.
This module is coming soon and details may evolve.
Ingest sources (Prometheus/Alertmanager etc.)
Planned/common sources:
- Prometheus Alertmanager
- Grafana alerts
- Datadog monitors
- PagerDuty incidents/events
- Webhook-based alert feeds
- Additional observability tools (as integrations expand)
Dedup, grouping, suppression
Planned capabilities:
- Deduplicate repeated alerts
- Group by service/namespace/cluster/root-cause candidate
- Suppress known-noisy or low-signal alerts
- Correlate alerts with active incidents and graph state
Routing rules (team/service/cluster)
Planned routing based on:
- Team ownership
- Cluster/environment
- Namespace/service labels
- Severity
- Time windows/on-call schedules (via integrations)
Suggested actions + links into workflows
Planned actions:
- Open troubleshooting investigation with alert context
- Jump to impacted dependency graph
- Trigger drift scan on affected namespace
- Draft remediation PR (where applicable)
- Create/update Jira/PagerDuty ticket
Noise tuning playbook
Recommended future playbook structure:
- Identify top noisy alert classes
- Define ownership labels and routing metadata
- Add dedup/grouping rules
- Add suppressions with expiry
- Track MTTA/MTTR and false-positive reduction
- Review monthly
Fleet Management (coming soon)
Overview
Fleet Management will help platform teams standardize and operate many clusters consistently across providers, teams, and environments.
This module is coming soon and behavior/capabilities may evolve.
Standardization (policies/baselines across clusters)
Planned capabilities:
- Shared policy baselines
- Cluster posture templates
- Environment-specific controls
- Compliance baseline comparisons
Bulk actions (safe modes only)
Planned safe actions:
- Bulk scans
- Bulk policy checks
- Bulk upgrade planning
- Bulk drift posture refresh
- Bulk PR generation (with per-cluster review gates)
Recommended constraint:
- No blind bulk execution in production without approval and wave controls
Drift/upgrade posture dashboards
Planned dashboards:
- Upgrade readiness across fleet
- Drift severity distribution
- Policy compliance by cluster/team
- Risk hotspots by provider/environment
Segmentation (by env/team/provider)
Fleet views should segment by:
- Environment (dev/stage/prod)
- Team/workspace/project
- Cloud provider
- Region
- Compliance zone
- Cluster criticality tier
Integrations
Kubernetes Providers
EKS
Connect Amazon EKS clusters to Kubegrade for:
- Inventory and health visibility
- Upgrade planning and preflight checks
- Drift and troubleshooting workflows
- GitOps remediation suggestions
Document:
- Auth method(s)
- Required RBAC
- EKS-specific upgrade sequence notes
- Managed add-on compatibility considerations
GKE
Connect Google Kubernetes Engine clusters for:
- Cluster/workload visibility
- Troubleshooting and drift analysis
- Upgrade readiness and planning workflows
Document:
- GKE auth options
- Autopilot vs Standard support differences (if any)
- GKE version/support caveats
AKS
Connect Azure Kubernetes Service clusters for:
- Upgrade readiness and execution planning
- Drift detection
- Troubleshooting and dependency mapping
Document:
- Auth and identity setup
- Nodepool considerations
- AKS-specific maintenance windows/provider constraints
OpenShift
Connect Red Hat OpenShift clusters for:
- Cluster operations visibility
- Troubleshooting and compliance workflows
- Drift and GitOps remediation support
Document:
- OpenShift API/auth specifics
- SCC/RBAC considerations
- OpenShift route/operator compatibility notes
Rancher / RKE (if applicable)
If supported, document whether Kubegrade connects:
- Directly to downstream clusters
- Via Rancher-managed contexts
- To RKE/RKE2 clusters with standard Kubernetes APIs
Include any version limitations.
Self-managed clusters
Kubegrade can support upstream/self-managed Kubernetes clusters where:
- Agent installation is allowed
- Required RBAC is granted
- Network connectivity to Kubegrade endpoints exists (SaaS/hybrid)
Document supported distributions and known constraints.
IaC & Config
Terraform
Use Terraform integration to:
- Compare declared infrastructure/Kubernetes config to runtime state
- Generate PRs for remediation or upgrade prep changes
- Preserve auditable workflows via Git
Your docs draft explicitly references Terraform support and imports/integrations. (Archbee)
Helm
Use Helm integration to:
- Inspect chart values and manifests
- Detect value drift or incompatible settings
- Generate PRs against values files / chart config
Kustomize
Use Kustomize integration to:
- Parse overlays and environment-specific manifests
- Compare desired state vs live cluster
- Generate patch updates via PRs
GitOps
Argo CD
Kubegrade integrates with Argo CD to:
- Map Git changes to cluster sync behavior
- Track application sync/health after PR merge
- Route remediation through existing GitOps controls
Your docs draft references ArgoCD support. (Archbee)
Flux
Kubegrade integrates with Flux for:
- Git-driven remediation execution
- Rollout tracking after merge
- Drift reconciliation workflows in GitOps-first environments
CI/CD
GitHub Actions
Use GitHub Actions with Kubegrade to:
- Trigger scans/checks on PRs
- Validate generated remediations
- Enforce policy checks before merge
GitLab CI
Use GitLab CI to:
- Run Kubegrade checks in pipeline stages
- Validate environment readiness
- Gate merges with policy/drift/upgrade checks
Jenkins
Use Jenkins to:
- Trigger Kubegrade workflows from existing enterprise pipelines
- Ingest outputs into release processes
- Link remediation and upgrade checks into change management flows
Your docs draft mentions Jenkins, GitHub Actions, and GitLab CI integration ecosystem. (Archbee)
Observability & Logging
Prometheus
Prometheus can provide metrics context for:
- Troubleshooting investigations
- Upgrade risk/health validation
- Alert correlation
- Post-change verification
Your docs draft references Prometheus exports/integration. (Archbee)
Grafana
Grafana integration can support:
- Linking dashboards to Kubegrade investigations
- Visual context during incident analysis
- Shared operational dashboards
Datadog
Datadog integration can support:
- Alert and monitor context
- Incident signal enrichment
- Post-remediation verification checks
Your docs draft mentions Datadog support/export. (Archbee)
(others you support)
Create a generic pattern page for additional integrations documenting:
- Authentication
- Scope/permissions
- Data ingested
- Supported workflows
- Limitations
- Troubleshooting
ChatOps & Ticketing
Slack
Slack integration can be used to:
- Send workflow notifications
- Route approval requests
- Share incident summaries
- Link directly to Kubegrade investigations/PRs
Microsoft Teams
Teams integration can provide:
- Notifications for alerts/workflows
- Approval routing (if supported)
- Incident timeline sharing
Jira
Jira integration can support:
- Ticket creation from incidents/drift findings
- Status updates with PR/execution links
- Traceability between platform ops and change records
PagerDuty
PagerDuty integration can support:
- Incident/event ingestion
- Ownership and escalation routing
- Linking PagerDuty incidents to Kubegrade investigations
Webhooks
Webhook integration supports custom automation and system interoperability.
Document:
- Event types
- Payload schema
- Signing/authentication
- Retry behavior
- IP allowlisting requirements
Identity & Access
SSO overview
Kubegrade supports centralized identity integration for enterprise access control (where enabled).
Use SSO to:
- Centralize authentication
- Enforce MFA and org policies
- Manage user lifecycle and access consistency
Your draft docs reference external identity providers and access controls. (Archbee)
SAML / OIDC
Document supported modes and setup steps.
SAML
Include:
- Metadata exchange
- ACS URL / Entity ID
- Group/role mapping
- Certificate rotation
OIDC
Include:
- Issuer URL
- Client ID/secret
- Redirect URIs
- Claims mapping
- Group/role mapping
Role mapping best practices
- Map IdP groups to Kubegrade roles (Owner/Admin/Developer/Viewer)
- Scope groups by workspace/project where possible
- Keep production approval roles restricted
Administration
User management
Admins/Owners can:
- Invite users
- Remove users
- Assign roles
- Manage access scope by workspace/project/cluster
Recommended documentation:
- Invite flow
- Pending invites
- Deactivation behavior
- Access review process
Team/role management
Document how to:
- Create teams
- Assign default roles
- Map teams to clusters/projects
- Enforce separation of duties (view vs approve vs execute)
Workspace/project settings
Document settings such as:
- Naming and metadata
- Cluster associations
- Default policies
- Notification settings
- Integration mappings
- Environment labels and conventions
Policy management
Admins should be able to:
- Create and update policies
- Assign policies by scope
- Test policy impact (dry-run)
- Review policy violations and exceptions
- Track policy changes in audit logs
Audit logs
Provide admin guidance for:
- Searching/filtering logs
- Exporting logs
- Retention and storage settings
- Linking logs to incidents/workflows/PRs
Your draft docs explicitly mention compliance audit logs. (Archbee)
Billing (if relevant in docs)
If exposed:
- Seats/users
- Cluster-based billing units
- Usage dimensions (if any)
- Invoice access
- Billing contacts
- Plan changes and renewals
If not public yet, keep minimal and note “contact support/sales.”
Reference
Configuration reference
This page should be a canonical reference for:
- Global settings
- Cluster connection settings
- Agent configuration
- Network/proxy settings
- Policy defaults
- Integration configuration keys
Format recommendation:
- Option name
- Type
- Default
- Required?
- Example
- Notes
Agent CRDs / manifests reference
If Kubegrade installs CRDs or custom resources, document:
- CRD names and versions
- Spec fields
- Status fields
- Examples
- RBAC implications
If no CRDs are exposed yet, document install manifests/Helm values instead.
API reference
Document:
- Authentication
- Base URLs (SaaS/on-prem)
- Rate limits
- Endpoints by resource (clusters, workflows, policies, audit logs, integrations)
- Webhook subscription endpoints
- Error codes and pagination
Webhooks reference
Document webhook events and payloads.
Recommended fields:
- event_type
- event_id
- timestamp
- org/workspace/project
- cluster/environment
- severity (if applicable)
- resource references
- links (UI, PR, incident)
Also document:
- Signature verification
- Retries
- Idempotency guidance
Limits & quotas
Publish practical limits to reduce support friction.
Examples:
- Max clusters per workspace (plan-dependent)
- Max concurrent workflow runs
- Max integrations per workspace
- Retention periods
- Payload size limits
- API rate limits
Release notes / changelog
Use a consistent format:
- Date
- Version
- New
- Improved
- Fixed
- Breaking changes
- Migration notes (if needed)
Include module tags (Upgrade, Troubleshooting, Drift, AI Agents, GitOps, Integrations).
FAQ
Security FAQ
Does Kubegrade execute changes directly in my cluster?
Kubegrade supports controlled execution models and is designed to keep humans in the loop. In GitOps workflows, changes are proposed as PRs and applied through your GitOps system after review/merge. (Kubegrade)
Can Kubegrade run in private or regulated environments?
Yes, Kubegrade publicly positions support for cloud, on-prem, and hybrid environments. Exact deployment architecture depends on your setup and requirements. (Kubegrade)
What permissions does the agent need?
Permissions depend on enabled modules and whether you use read-only or execution-enabled workflows. Start with least privilege and expand only as needed.
Does Kubegrade collect secrets?
Kubegrade should not collect secret values unless explicitly required for a configured integration. Secret handling behavior must be documented by deployment mode and integration.
Pricing/billing FAQ (optional)
How is Kubegrade priced?
Document your actual pricing model only (e.g., by cluster, node, seat, or enterprise plan). If still evolving, say so and direct to sales.
Is on-prem pricing different from SaaS?
Typically yes, because support, deployment complexity, and infrastructure requirements differ. Publish only confirmed commercial policy.
Are there limits on clusters or users?
List plan-based limits here and link to the Limits & Quotas page.
Troubleshooting FAQ
Why is my cluster showing as disconnected?
Common causes:
- Agent not running
- Network egress blocked
- TLS/certificate trust issue
- Invalid credentials/token
- Proxy misconfiguration
Why can’t Kubegrade generate a PR?
Common causes:
- Git repo not connected
- Insufficient repo permissions
- Path mapping not configured
- Policy blocked PR generation
- Unsupported repo layout edge case
Why is drift reported for fields we don’t manage?
You may need exclusions/suppression rules for provider-managed or runtime-generated fields.
Why is execution blocked after approval?
A second gate may still apply:
- Maintenance window closed
- Policy check failed on re-validation
- GitOps sync restrictions
- Environment freeze window