Skip to content

6.09 Kubernetes API Groups

🎯 What is the Kubernetes API?

All cluster operations interact with the kube-apiserver:

  • kubectl
  • curl
  • Controllers
  • Operators
  • CI/CD systems

Example:

curl https://kube-master:6443/version
curl https://kube-master:6443/api/v1/pods

Note

Port 6443 is the default secure Kubernetes API port.

🌐 Important Top-Level API Paths

Path Purpose
/version Cluster version
/healthz Health check
/metrics Monitoring metrics
/logs Logging integrations
/api Core APIs
/apis Named API groups

🧩 API Group Structure

Kubernetes APIs are divided into:

1️⃣ Core Group (/api)

Path example:

/api/v1/pods

Core resources include:

  • namespaces
  • pods
  • nodes
  • services
  • endpoints
  • configmaps
  • secrets
  • persistentvolumes
  • persistentvolumeclaims
  • events

2️⃣ Named Groups (/apis)

Path example:

/apis/apps/v1/deployments

Common named groups:

API Group Example Resources
apps deployments, replicasets, statefulsets
networking.k8s.io networkpolicies
storage.k8s.io storageclasses
authentication.k8s.io tokenreviews
authorization.k8s.io subjectaccessreviews
certificates.k8s.io certificatesigningrequests

Tip

All newer Kubernetes features are added under named API groups.

🏗 Resources and Verbs

Each resource supports operations (verbs):

  • list
  • get
  • create
  • update
  • delete
  • watch

Example:

/apis/apps/v1/deployments

Supports:

  • list deployments
  • create deployment
  • delete deployment
  • watch deployment

🔍 Discover API Groups

Discover root APIs:

curl https://localhost:6443 -k

Discover named groups:

curl https://localhost:6443/apis -k

🔐 Authentication Required

Unauthenticated access:

curl https://localhost:6443 -k

Returns:

403 Forbidden

Authenticated access:

curl https://localhost:6443 -k \
  --key admin.key \
  --cert admin.crt \
  --cacert ca.crt

🔄 kubectl proxy

Instead of manually passing certificates:

kubectl proxy

Starts local proxy:

http://localhost:8001

Now:

curl http://localhost:8001/api

Warning

kubectl proxy uses credentials from your kubeconfig file.

❗ kube-proxy vs kubectl proxy

Component Purpose
kube-proxy Pod ↔ Service networking inside cluster
kubectl proxy Local HTTP proxy to API server

Danger

These are completely different components.

🛡 Production Best Practices

✅ DO

Success

  • Use RBAC to control verbs per API group
  • Restrict access to sensitive groups (certificates, authorization)
  • Monitor API server audit logs
  • Use kubectl proxy only for debugging
  • Disable anonymous authentication in production
  • Secure API server with TLS

❌ DON'T

Danger

  • Do NOT expose API server publicly without firewall
  • Do NOT grant wildcard verbs (*)
  • Do NOT allow cluster-admin unnecessarily
  • Do NOT rely on anonymous API access
  • Do NOT confuse kube-proxy with kubectl proxy

🚨 Production Risks

Risk Impact
Over-permissive RBAC Privilege escalation
Exposed API endpoint Full cluster compromise
Anonymous enabled Unauthorized discovery
Excessive verbs Data deletion / takeover

🎯 Summary

  • Kubernetes APIs are grouped into Core and Named
  • Resources belong to groups
  • Actions are defined as verbs
  • Authorization policies use API groups + resources + verbs
  • Secure API access is critical in production

Quote

API Groups define what exists.
Verbs define what you can do.
RBAC defines who can do it.