Songbird 🐦

songbird is a comprehensive command-line interface (CLI) tool for Kubernetes network troubleshooting. It helps you analyze network connectivity, diagnose Network Policy configurations, and resolve DNS issues in Kubernetes clusters.

<img align=left src="public/gopher-songbird.png" width="170vw" />

<br/><br/>

✨ Key Features

• 🔍 Network Policy Analysis: Test connectivity between pods and external IPs
• 🎯 Interactive Fuzzy Finder: Use fzf-style menus for easy resource selection
• 🔧 DNS Troubleshooting: Query CoreDNS and check DNS connectivity
• 📋 Policy Generation: Auto-generate NetworkPolicy YAML configurations
• 📊 Multiple Output Formats: Table, wide, and JSON output support

<br/><br/>

---

🔧 Installation & Setup

Prerequisites

• kubeconfig: Configured access to your Kubernetes cluster
• RBAC Permissions: See RBAC Requirements below

Quick Start

1. Ensure your kubeconfig is properly configured
2. Apply the required RBAC permissions to your cluster
3. Run songbird commands directly

---

🛡️ RBAC Requirements

Songbird requires specific Kubernetes permissions depending on which features you use. Below are the minimum required permissions for each command group.

Comprehensive RBAC (All Features)

For full songbird functionality, use this ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: songbird-full-access
rules:
  # Core resources for all network policy operations
  - apiGroups: ['']
    resources: ['pods', 'namespaces']
    verbs: ['get', 'list', 'watch']
  # Network policies for connectivity analysis
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['get', 'list', 'watch']
  # Port forwarding for DNS lookups (requires pods/portforward)
  - apiGroups: ['']
    resources: ['pods/portforward']
    verbs: ['create']
  # ConfigMaps for cluster domain detection
  - apiGroups: ['']
    resources: ['configmaps']
    verbs: ['get', 'list']

Command-Specific RBAC

Network Policy Commands (netpol check, netpol show, netpol create)

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: songbird-netpol-access
rules:
  - apiGroups: ['']
    resources: ['pods', 'namespaces']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['get', 'list', 'watch']

DNS Commands (dns check)

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: songbird-dns-check-access
rules:
  - apiGroups: ['']
    resources: ['pods', 'namespaces']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['get', 'list', 'watch']

DNS Lookup Command (dns lookup)

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: songbird-dns-lookup-access
rules:
  - apiGroups: ['']
    resources: ['pods']
    verbs: ['get', 'list']
  - apiGroups: ['']
    resources: ['pods/portforward']
    verbs: ['create']
  - apiGroups: ['']
    resources: ['configmaps']
    verbs: ['get', 'list']

Binding the ClusterRole

Create a ClusterRoleBinding to assign permissions to users or service accounts:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: songbird-binding
subjects:
- kind: User
  name: your-username  # Replace with actual username
  apiGroup: rbac.authorization.k8s.io
# Or for a service account:
# - kind: ServiceAccount
#   name: songbird-sa
#   namespace: default
roleRef:
  kind: ClusterRole
  name: songbird-full-access  # Use appropriate ClusterRole name
  apiGroup: rbac.authorization.k8s.io

📖 Command Reference

Songbird provides two main command groups for different types of network troubleshooting:

Available Commands

songbird [command]

Available Commands:
  netpol      Troubleshoot Kubernetes Network Policies  
  dns         Troubleshoot and query DNS records
  help        Help about any command

Flags:
  -h, --help               help for songbird
  -l, --log-level string   Override log level (debug, info)
  -v, --version            display version information

Network Policy Commands (netpol)

netpol check

Evaluate network policies to check connectivity between pods and IP addresses.

Usage:

songbird netpol check [flags]

Key Flags:

• -a, --address string: IP address to check connectivity to
• -P, --pod string: Target pod in format 'namespace/podname'
• -p, --port int: Port number to check (required)
• -n, --namespace string: Namespace to filter source pods
• -d, --direction string: Traffic direction (ingress, egress, all) (default "all")
• -o, --output string: Output format (wide, json)
• --denied-only: Show only denied connections

netpol show

Display NetworkPolicies affecting a specific pod.

Usage:

songbird netpol show <namespace>/<podname> [flags]

Flags:

• -o, --output string: Output format (yaml for full policy details)

netpol create

Generate NetworkPolicy YAML to allow connectivity.

Usage:

songbird netpol create <namespace>/<podname> [flags]

Key Flags:

• -P, --peer-pod string: Peer pod in format 'namespace/podname'
• -a, --address string: IP address or CIDR block (e.g., 192.168.1.10/32)
• -p, --port int: Port number (required)
• -d, --direction string: Traffic direction (ingress, egress, all) (default "all")

DNS Commands (dns)

dns check

Check connectivity to CoreDNS pods on port 53.

Usage:

songbird dns check [flags]

Flags:

• -n, --namespace string: Namespace to filter source pods
• -o, --output string: Output format (wide, json)

dns lookup

Perform DNS queries using port-forward to CoreDNS.

Usage:

songbird dns lookup <domain-name>

Examples:

songbird dns lookup kubernetes.default
songbird dns lookup my-service.my-namespace

---

📚 Examples & Use Cases

Network Policy Testing Examples

Example 1: Check Connectivity to External IP

Check if any pod in the flux-system namespace can send egress and receive ingress traffic to/from the IP 1.1.1.1 on port 53.

Command:

songbird netpol check -a 1.1.1.1 -p 53 -o wide -n flux-system

Output:

NAMESPACE    POD                                       DIRECTION  TARGET   PORT  NETWORK_POLICIES                                                                                STATUS
flux-system  flux-operator-6dc5986d74-nsl7v            to         1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              ALLOWED ✅
flux-system  flux-operator-6dc5986d74-nsl7v            from       1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              DENIED ❌
flux-system  helm-controller-cdcf95449-knmb2           to         1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              ALLOWED ✅
flux-system  helm-controller-cdcf95449-knmb2           from       1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              DENIED ❌
flux-system  kustomize-controller-86447b847-t8t5x      to         1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              ALLOWED ✅
flux-system  kustomize-controller-86447b847-t8t5x      from       1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              DENIED ❌
flux-system  notification-controller-55d7f99bf9-kp2j6  to         1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, flux-system/allow-webhooks, dmp/deny-all  ALLOWED ✅
flux-system  notification-controller-55d7f99bf9-kp2j6  from       1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, flux-system/allow-webhooks, dmp/deny-all  DENIED ❌
flux-system  source-controller-ffb777895-gv7c7         to         1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              ALLOWED ✅
flux-system  source-controller-ffb777895-gv7c7         from       1.1.1.1  53    flux-system/allow-egress, flux-system/allow-scraping, dmp/deny-all                              DENIED ❌

Example 2: Check Pod-to-Pod Connectivity (Denied Only)

Check if any pod in the fluent namespace can receive ingress or egress traffic from the pod debug in namespace monitoring on port 8443, showing only denied results.

Command:

songbird netpol check -P monitoring/debug -n fluent -p 8443 --denied-only

Output:

NAMESPACE  POD    DIRECTION  TARGET            PORT  STATUS
fluent     debug  from       monitoring/debug  8443  DENIED ❌

Example 3: Show Network Policies Affecting a Pod

Display the YAML of network policies affecting a specific pod.

Command:

songbird show flux-system/flux-operator-86fdfcd59-p2vvq -o yaml

Output:

---
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"networking.k8s.io/v1","kind":"NetworkPolicy","metadata":{"annotations":{},"name":"allow-ingress-to-flux-operator","namespace":"flux-system"},"spec":{"ingress":[{"from":[{"namespaceSelector":{"matchLabels":{"kubernetes.io/metadata.name":"ark"}},"podSelector":{"matchLabels":{"app.kubernetes.io/name":"island"}}}],"ports":[{"port":40,"protocol":"TCP"}]}],"podSelector":{"matchLabels":{"app.kubernetes.io/name":"flux-operator"}},"policyTypes":["Ingress"]}}
  creationTimestamp: "2025-08-11T20:29:09Z"
  generation: 4
  managedFields:
  - apiVersion: networking.k8s.io/v1
    fieldsType: FieldsV1
    fieldsV1:
      f:metadata:
        f:annotation