Skip to content

API Server Compatibility Checklist

This document outlines what the current babyctl api-server already exposes and what still needs to be implemented before kubectl can treat it like a general-purpose Kubernetes API server.

What the server already does

  • Discovery endpoints plus sample CRUD – the HTTP router in pkg/apiserver/server.go wires up handlers for GET /api, GET /apis, and GET /apis/<group>/<version> plus two babyctl-specific helper routes for resource definitions and controllers. Cluster-scoped CRUD endpoints are now registered for any resource that exposes a REST controller (the bundled babyctl.dev/v1alpha1/widgets definition exercises GET, POST, PUT, and DELETE).
  • File-backed resource metadata – API groups, versions, and resource lists are read from YAML files under ~/.babyctl/apis (or --api-path) via the loader. This keeps discovery data in sync with whatever definitions you install locally.
  • In-memory cache – the server preloads API resources at startup and filters out empty groups so kubectl’s discovery calls only see definitions that also have controller implementations.

These capabilities are sufficient for kubectl api-resources / api-versions, but kubectl requires more when you attempt get, apply, or other resource verbs.

Gaps to close for kubectl compatibility

  1. Resource endpoints for each verb
  2. Cluster-scoped CRUD handlers exist for resources that include a REST controller (see the widgets sample), but namespaced URLs, collection deletes, and patch verbs are not implemented yet.
  3. The handlers must support namespaced URLs, subresources such as /status, and JSON Patch/Merge Patch (PATCH with the proper Content-Type).

  4. Until these semantics are added kubectl will still fail when targeting built-in resources such as deployments.

  5. List/watch semantics

  6. kubectl get and the informer cache expect list plus watch verbs to stream events. Implement chunking, resourceVersion, continue, labelSelector, and fieldSelector query parameters so clients can paginate or resume watches.

  7. Watches require HTTP streaming with the Kubernetes watch event envelope ({"type":"ADDED","object":...}).

  8. Object schemas and metadata

  9. Responses need Kubernetes-style metadata fields (apiVersion, kind, metadata.{name,namespace,uid,resourceVersion}) for every resource.

  10. Consider generating OpenAPI (/openapi/v2 or /openapi/v3) so kubectl can validate manifests.

  11. Status and scale subresources

  12. Many built-in commands (kubectl rollout status, kubectl scale) rely on /status and /scale.

  13. Expose separate handlers that delegate to the underlying resourceconfig.Controller implementations or return “method not allowed” unless the definition explicitly supports them.

  14. Error handling and admission-style validation

  15. Use Kubernetes API status responses (Status objects with status, reason, message, code).

  16. Validate request bodies and enforce optimistic concurrency via metadata.resourceVersion to match kubectl expectations for update/patch.

  17. Authentication, authorization, and TLS

  18. Real kubectl clients default to HTTPS with certificate verification. Add TLS flags (cert/key/CA) and optionally webhook-style authn/authz to avoid having to invoke kubectl --server=http://... --insecure-skip-tls-verify.

  19. Miscellaneous Kubernetes endpoints

  20. Implement /version, /readyz, /healthz, and /livez so kubectl and tooling can perform health checks.

  21. Consider supporting /.well-known/openid-configuration if you later add token auth, because kubectl will call it when OIDC data is referenced in kubeconfig contexts.

  22. Dynamic reloading or informer refresh

  23. Today the loader only reads definitions at startup. Add file watchers or an admin endpoint to reload definitions so cluster admins don’t have to restart the server when installing new APIs.

  24. Multi-user reliability

  25. Add request logging, structured errors, and rate limiting.
  26. Provide consistent concurrency guarantees for controllers so concurrent kubectl operations do not corrupt backing systems.

Addressing the points above will move the server from “discovery-only shim” to something kubectl can treat like a full API server.