Skip to content

PowerShell Usage

If you're using KubeBuddy via PowerShell, this guide covers the module-based compatibility wrapper. For the native binary, use Native CLI Usage.

🔧 Prerequisites

Before running KubeBuddy via PowerShell, ensure you: - Are connected to a Kubernetes cluster/context. - Have kubectl installed and configured. - Are using a supported platform for the bundled native binary, or have a fallback native kubebuddy binary available - Have Azure authentication available for AKS or Azure-authenticated Prometheus when those features are used.

The PowerShell module bundles the native binary and should work immediately after Install-Module.

Optional override example:

$env:KUBEBUDDY_BINARY = "/usr/local/bin/kubebuddy"

(Optional) Enable AI Recommendations

If you’d like to use OpenAI to automatically generate enhanced recommendations, set your OpenAI API key as an environment variable:

$env:OpenAIKey = "<your-openai-api-key>"

KubeBuddy will detect this and enrich reports with AI-generated summaries and HTML guidance where applicable.

If you're running AKS checks or using the -Aks flag, see the full AKS Configuration & Best Practices Setup guide for prerequisites and role setup.

For generic Kubernetes (non-AKS) scans, see Kubernetes Scan Permissions for the required read-only RBAC setup.

Available Commands

The following table provides a quick reference for common PowerShell wrapper commands:

Action Command Example
Launch the unified TUI Invoke-KubeBuddy -Tui
Launch guided report mode directly Invoke-KubeBuddy -Guided
Launch the interactive check browser directly Invoke-KubeBuddy -Menu
Run KubeBuddy Invoke-KubeBuddy
Generate an HTML report Invoke-KubeBuddy -HtmlReport
Generate a JSON report Invoke-KubeBuddy -jsonReport
Generate a text report Invoke-KubeBuddy -txtReport
Generate a CSV report Invoke-KubeBuddy -CsvReport
Generate reports with custom path Invoke-KubeBuddy -HtmlReport -OutputPath ./custom-report
Use cluster-specific config file Invoke-KubeBuddy -HtmlReport -ConfigPath ~/.kube/kubebuddy-config-prod.yaml
Exclude configured + extra namespaces Invoke-KubeBuddy -HtmlReport -ExcludeNamespaces -AdditionalExcludedNamespaces "azure-monitor","istio-system"
Run AKS best-practice checks Invoke-KubeBuddy -Aks -SubscriptionId <subscriptionID> -ResourceGroup <resourceGroup> -ClusterName <clusterName>
Run AKS best practices check and HTML report Invoke-KubeBuddy -HtmlReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName
Run AKS best practices check and text report Invoke-KubeBuddy -txtReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName
Upload JSON scan to Radar (Pro) Invoke-KubeBuddy -jsonReport -RadarUpload -RadarEnvironment prod
Compare latest run with previous in Radar (Pro) Invoke-KubeBuddy -jsonReport -RadarUpload -RadarCompare -RadarEnvironment prod
Fetch a saved Radar cluster config (Pro) Invoke-KubeBuddy -RadarFetchConfig -RadarConfigId <cluster-config-id>

Radar uploads always use the JSON report payload.

Set your Radar credentials first (WordPress username + Application Password):

$env:KUBEBUDDY_RADAR_API_USER = "<wordpress-username>"
$env:KUBEBUDDY_RADAR_API_PASSWORD = "<wordpress-app-password>"

1. Running KubeBuddy

To run KubeBuddy on your Kubernetes cluster:

Invoke-KubeBuddy

This invokes the native Go CLI through the PowerShell wrapper while preserving the Invoke-KubeBuddy command surface. If you do not specify a report switch, the wrapper defaults to -HtmlReport.

Interactive TUI

To launch the native terminal UI from PowerShell:

Invoke-KubeBuddy -Tui

Direct compatibility entrypoints are also available:

Invoke-KubeBuddy -Guided
Invoke-KubeBuddy -Menu

2. Running KubeBuddy with AKS Best Practices

To check best practices for an Azure Kubernetes Service (AKS) cluster:

Invoke-KubeBuddy -Aks -SubscriptionId <subscriptionID> -ResourceGroup <resourceGroup> -ClusterName <clusterName>

You must provide your Azure Subscription ID, the Resource Group where your AKS cluster resides, and the Cluster Name.

3. Generating Reports

Generate an HTML Report

Invoke-KubeBuddy -HtmlReport
Screenshot of KubeBuddy HTML Report

View Sample HTML Report

The Overview tab includes a Rightsizing at a Glance section when Prometheus sizing checks are available, summarizing node and pod sizing opportunities with quick links to PROM006 and PROM007.

Generate a JSON Report

Invoke-KubeBuddy -jsonReport

Generate a Text Report

Invoke-KubeBuddy -txtReport
Screenshot of KubeBuddy Text Report

View Sample txt Report

Generate a CSV Report

Invoke-KubeBuddy -CsvReport

Exports all scan results to a .csv file. Each row represents a single finding with the following columns:

Column Description
ID Check identifier (e.g. NET004, SEC001)
Name Human-readable check name
Category Check category (e.g. Security, Networking)
Severity critical, warning, or info
Status PASS, FAIL, or ERROR
Message Affected resource and issue description
Recommendation Remediation guidance
URL Link to relevant documentation

For FAIL results, one row is written per affected resource. The file is written as UTF-8 with BOM so it opens correctly in Excel.

To include AKS best practice checks in the CSV: 

Invoke-KubeBuddy -CsvReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName

Customizing Report Output Path

You can specify a custom filename or directory for the report using -OutputPath.

Save report in a specific directory

Invoke-KubeBuddy -HtmlReport -OutputPath ./reports
✔️ Saves the HTML report as: 
./reports/kubebuddy-report-YYYYMMDD-HHMMSS.html


Invoke-KubeBuddy -jsonReport -OutputPath ./reports
✔️ Saves the JSON report as: 
./reports/kubebuddy-report-YYYYMMDD-HHMMSS.json


Invoke-KubeBuddy -txtReport -OutputPath ./reports
✔️ Saves the TXT report as: 
./reports/kubebuddy-report-YYYYMMDD-HHMMSS.txt


Invoke-KubeBuddy -CsvReport -OutputPath ./reports
✔️ Saves the CSV report as: 
./reports/kubebuddy-report-YYYYMMDD-HHMMSS.csv

Generate report with a custom filename

Invoke-KubeBuddy -HtmlReport -OutputPath ./custom-report.html
✔️ Saves the HTML report as: 
./custom-report.html


Invoke-KubeBuddy -jsonReport -OutputPath ./custom-report.json
✔️ Saves the JSON report as: 
./custom-report.json


Invoke-KubeBuddy -txtReport -OutputPath ./custom-report.txt
✔️ Saves the TXT report as: 
./custom-report.txt


Invoke-KubeBuddy -CsvReport -OutputPath ./custom-report.csv
✔️ Saves the CSV report as: 
./custom-report.csv

4. Running an AKS Health Check alongside the HTML report

To check best practices for an Azure Kubernetes Service (AKS) cluster, ensure you are authenticated to Azure and using the correct subscription:

Invoke-KubeBuddy -HtmlReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName
Screenshot of KubeBuddy HTML + AKS Report

View Sample HTML Report

5. Running an AKS Health Check alongside the JSON report

To check best practices for an Azure Kubernetes Service (AKS) cluster:

Invoke-KubeBuddy -jsonReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName

6. Running an AKS Health Check alongside the CSV report

To check best practices for an Azure Kubernetes Service (AKS) cluster and export results to CSV:

Invoke-KubeBuddy -CsvReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName

View Sample CSV Report

7. Running an AKS Health Check alongside the txt report

To check best practices for an Azure Kubernetes Service (AKS) cluster:

az login
az account set --subscription <subscription-id>
Invoke-KubeBuddy -txtReport -Aks -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -ClusterName $ClusterName
Screenshot of KubeBuddy Text + AKS Report

View Sample text Report

8. Additional Parameters

Parameter Type Default Description
-OutputPath String $HOME/kubebuddy-report Folder or file name where report files are saved. Supports custom filenames.
-ConfigPath String ~/.kube/kubebuddy-config.yaml Path to a specific KubeBuddy config file for this run (supports per-cluster configs).
-Aks Switch (N/A) Runs AKS best practices checks. Requires -SubscriptionId, -ResourceGroup, -ClusterName.
-SubscriptionId String (None) Azure subscription ID (used with -Aks).
-ResourceGroup String (None) Azure resource group (used with -Aks).
-ClusterName String (None) AKS cluster name (used with -Aks).
-ExcludeNamespaces Switch (N/A) Applies namespace exclusions from kubebuddy-config.yaml (excluded_namespaces).
-AdditionalExcludedNamespaces String[] (None) Adds extra namespaces to exclude at runtime; implies -ExcludeNamespaces.
-HtmlReport Switch (N/A) Generates an HTML report in -OutputPath.
-JsonReport Switch (N/A) Generates a JSON report in -OutputPath.
-txtReport Switch (N/A) Generates a text report in -OutputPath.
-CsvReport Switch (N/A) Generates a CSV report in -OutputPath. One row per finding; UTF-8 with BOM for Excel.
-RadarUpload Switch (N/A) Uploads generated JSON report to KubeBuddy Radar (Pro feature).
-RadarCompare Switch (N/A) Fetches run-to-run compare summary from Radar after upload.
-RadarFetchConfig Switch (N/A) Fetches a saved Radar cluster config and applies it before the scan runs.
-RadarConfigId String (None) Radar cluster config ID to fetch (for example ccfg_...).
-RadarApiBaseUrl String https://radar.kubebuddy.io/api/kb-radar/v1 Overrides Radar API base URL.
-RadarEnvironment String prod Environment label used by Radar (for example prod, staging, dev).
-RadarApiUserEnv String KUBEBUDDY_RADAR_API_USER Environment variable name containing Radar username.
-RadarApiSecretEnv String KUBEBUDDY_RADAR_API_PASSWORD Environment variable name containing Radar app password/secret.

Cluster-Specific Config Files

You can keep multiple config files (for example one per cluster) and point KubeBuddy to the right one at runtime:

Invoke-KubeBuddy -HtmlReport -ConfigPath ~/.kube/kubebuddy-config-prod.yaml
Invoke-KubeBuddy -HtmlReport -ConfigPath ~/.kube/kubebuddy-config-dev.yaml

This is useful for per-cluster excluded_checks, excluded_namespaces, thresholds, and trusted registries.