Debug API for Kubernetes

Overview

The Debug API is a Kubernetes-native, declarative framework for secure, interactive debugging in multi-tenant environments. It leverages Kubernetes authentication, authorization, and RBAC to map user identities to roles and enforce F5 access policies accordingly.

The API is built on the Kubernetes Aggregation Layer and integrates directly with the Kubernetes API Server:

  • All debug requests traverse the Kubernetes API Server, which authenticates the user, authorizes the action, and forwards the request with the authenticated user context to the aggregated API service.

  • Users never interact directly with backend components, ensuring centralized security enforcement, consistent auditing, and secure multi-tenant isolation.

Relationship to the Legacy CWC Debug API

The Kubernetes-native Debug API framework is an evolution of the legacy CWC Debug API, purpose-built for cloud-native operations. It adds Kubernetes-native authentication and authorization, RBAC-driven access control, secure multi-tenancy, and interactive real-time debugging workflows. The legacy Debug API remains available for existing operational use cases.

Enhancements provided by the new Debug API include:

  • Kubernetes-native authentication and authorization

  • Declarative, RBAC-driven access controls

  • Secure multi-tenant isolation

  • Real-time, interactive debugging workflows

  • Synchronous command execution and diagnostics

  • Centralized auditing and policy enforcement via the Kubernetes API Server

  • Extensible, cloud-native integration architecture

This approach enables advanced, Kubernetes-aligned debugging while preserving support for legacy operational models and integrations.

Role-Based Access Control (RBAC)

The Debug API supports three roles with distinct access levels - f5-ops-admin, f5-ops-operator, f5-ops-tenant. If role bindings are conflicting, the least-privileged applicable role is used. If a user is not bound to any F5 DEBUG API role, requests may return Forbidden responses.

RBAC integration:

  • Users, groups, and service accounts are bound to predefined F5 roles via RoleBindings or ClusterRoleBindings.

  • Kubernetes authorization gates every request before it reaches the aggregated API.

  • Assigned roles determine accessible operations and resources; F5 policies further enforce command- and tenant-specific restrictions.

Available Roles

The following roles are installed in the same namespace as the f5-toda-kal container (ordered high to low privilege):

Role

Code

Access Level

Administrator

f5-ops-admin

Unrestricted cluster-wide access. Full visibility and ability to execute all supported debug/ops commands.

Operator

f5-ops-operator

Access limited to tmms and debug(tmms/exec) only

Tenant

f5-ops-tenant

Access limited to tmms and debug(tmms/exec) only

Command Permissions by Role

Commands may be restricted by role and scoped to tenant namespace resources.

Notes on source IP restrictions:

  • Tenant role: cannot select source IPs; certain network tools are disallowed or constrained.

  • Operator role: defaults to pod self_IP for network tools; additional source IP selection may be restricted.

  • Admin role: no role-based limitations.

The debug sidecar runs alongside the TMM pod and executes operational debugging commands.

tmms/exec Commands

Command

Admin

Operator

Tenant

Notes

ping

Allowed

Allowed

Allowed

Not with -I

traceroute

Allowed

Allowed

Allowed

Not with -s

tcpdump

Allowed

Restricted

Restricted

mrfdb

Allowed

Restricted

Restricted

lsndb

Allowed

Restricted

Restricted

tmctl

Allowed

Restricted

Restricted

configview

Allowed

Restricted

Restricted

bdt_cli

Allowed

Restricted

Restricted

dns-cache-stats

Allowed

Restricted

Restricted

dns-profile-stats

Allowed

Restricted

Restricted

gslbs/exec Commands

Command

Admin

Operator

Tenant

ping

Allowed

Restricted

Restricted

traceroute

Allowed

Restricted

Restricted

tcpdump

Allowed

Restricted

Restricted

Prerequisites & Setup

Customer Binding Guide

Use a RoleBinding to assign an existing role to a user, group, or service account within a namespace.

Warning:

  • If a subject is not bound to any F5 DEBUG API role (f5-ops-admin, f5-ops-operator, f5-ops-tenant), requests may be Forbidden.

  • If a subject is bound to multiple F5 DEBUG API roles, the least-privileged role is applied.

1. Bind a role to a service account (recommended)

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kal-admin-sa-binding
subjects:
  - kind: ServiceAccount
    name: <service-account-name>
    namespace: <service-account-namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: f5-ops-admin

2. Bind a role to a user

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kal-operator-user-binding
subjects:
  - kind: User
    name: <user-identity>
    apiGroup: rbac.authorization.k8s.io
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: f5-ops-operator

3. Bind a role to a group

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kal-tenant-group-binding
subjects:
  - kind: Group
    name: <idp-group-name>
    apiGroup: rbac.authorization.k8s.io
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: f5-ops-tenant

Security Hardening Guidance

  • Prefer namespace-scoped bindings.

  • Avoid unnecessary cluster-scoped permissions.

  • Review RoleBindings regularly and remove stale identities.

  • Enable Kubernetes audit logs for RBAC changes and denied authorizations.

Verification Commands

Use verification commands to confirm that a subject has the required permissions within a namespace. Validate RBAC access with kubectl auth can-i for the expected users or service accounts, and ensure the appropriate RoleBinding resources are deployed in each tenant namespace.

kubectl auth can-i --as=<user-identity> --namespace=<your-namespace> get <resource>.<ops-group>

The kubectl f5ops Plugin

The kubectl f5ops plugin (“Plugin”) provides a kubectl-native interface for the KAL aggregated API under the ops.f5net.com/v1alpha1 group. While the Plugin performs the same functions as kubectl get for F5 resources, it is recommended for a streamlined, kubectl-native experience. It simplifies workflows and provides a consistent interaction model with the aggregated API.

Supported Platforms and Architectures

Platform

Architecture

linux

amd64, arm64

darwin

arm64

Download and Install

Default download (linux/amd64):

kubectl get --raw /apis/ops.f5net.com/v1alpha1/download/kubectl-f5ops.tar.gz > kubectl-f5ops.tar.gz
tar -xzf kubectl-f5ops.tar.gz
chmod +x kubectl-f5ops
cp kubectl-f5ops /usr/local/bin/kubectl-f5ops

Download a specific build (example: darwin/arm64):

kubectl get --raw '/apis/ops.f5net.com/v1alpha1/download/kubectl-f5ops.tar.gz?platform=darwin&arch=arm64' > kubectl-f5ops.tar.gz
tar -xzf kubectl-f5ops.tar.gz

Note: The download endpoint defaults to platform=linux and arch=amd64. The endpoint serves tar.gz-packaged plugin artifacts that must be extracted before installation or execution.

f5ops get

The f5ops get command provides a kubectl-native method for listing and retrieving F5 resources. It mirrors the familiar kubectl get syntax and options, supports standard Kubernetes output formats, and can be used to list and inspect F5 resources such as TMMs.

Syntax

kubectl f5ops get <resource name>

Examples

List all TMMs:

kubectl f5ops get tmms
kubectl get tmms

Get a single TMM by name:

kubectl f5ops get tmms tmm1[tmm2 tmm3 ....]
kubectl get tmms tmm1[tmm2 tmm3 ....]

GSLB

List all GSLB:

kubectl f5ops get gslbs
kubectl get gslbs

Get

kubectl f5ops get gslbs gslb1[gslb2 ...]
kubectl get gslbs gslb1[gslb2 ...]

f5ops debug

The f5ops debug command executes diagnostic and troubleshooting commands against the TMM/GSLB debug sidecar container.

It provides an interactive kubectl exec-style command. The -i and -t options are enabled by default.

Syntax

kubectl f5ops debug <tmm-pod / gslb-pod> [flags] -- [command...]

Examples

Run a ping test:

kubectl f5ops debug <tmm-pod> -- ping 127.0.0.1

Run traceroute:

kubectl f5ops debug <gslb-pod> -- traceroute 127.0.0.1

Run a tmctl query:

kubectl f5ops debug <tmm-pod> -n <namespace> -- tmctl virtual_server_stat

Query ConfigView:

kubectl f5ops debug <tmm-pod> -n <namespace> -- configview <object-name>