API Design Lessons From Kubernetes

Kubernetes is a wildly successful container orchestrator. Much of this success comes from a strong architectural foundation that allows composition, extensibility, and stability. In this talk, we will examine patterns and design choices made for the Kubernetes API. We will look at how these patterns affect the stability and resiliency of Kubernetes. We will see how patterns apply to specific use cases, like Kubernetes controllers that watch for changes. Finally, we will see how you can apply these patterns and principles to your own APIs and distributed systems.

Transcript

1. API Design Lessons From Kubernetes
2. https://manifold.co James Bowes Technical Lead
3. @jrbowes Photo by Maximilian Weisbecker on Unsplash KUBERNETES?
4. @jrbowes
5. @jrbowes
6. @jrbowes
7. @jrbowes
8. @jrbowes Photo by Gamze Bozkaya on Unsplash THE CLIENT API
9. @jrbowes
10. @jrbowes
11. @jrbowes
12. @jrbowes Photo by Jakob Owens on Unsplash PATCHING
13. JSON Merge Patch • Plain JSON document only containing changes • Declarative and simple • RFC 7386
14. JSON Merge Patch ... metadata: labels: service: worker app: marketplace spec: containers: - image: manifold/worker:1.31.18 name: worker
15. JSON Merge Patch metadata: labels: service: billing-worker spec: containers: - image: manifold/sidecar:1.0.0 name: metrics
16. JSON Merge Patch ... metadata: labels: service: billing-worker app: marketplace spec: containers: - image: manifold/sidecar:1.0.0 name: metrics
17. JSON Merge Patch ... metadata: labels: service: billing-worker app: marketplace spec: containers: - image: manifold/sidecar:1.0.0 name: metrics
18. JSON Merge Patch • Objects are always merged • Arrays are always replaced • No explicit null See also JSON Patch (RFC 6902) - Operation based
19. Strategic Merge Patch • Adds replace, merge, delete for objects and arrays • Merge keys for array elements • Schema defined defaults • Client directive overrides
20. Strategic Merge Patch ... metadata: labels: service: worker app: marketplace spec: containers: - image: manifold/worker:1.31.18 name: worker
21. Strategic Merge Patch spec: containers: - image: manifold/sidecar:1.0.0 name: metrics
22. Strategic Merge Patch ... spec: containers: - image: manifold/worker:1.31.18 name: worker - image: manifold/sidecar:1.0.0 name: metrics
23. Strategic Merge Patch ... spec: containers: - image: manifold/worker:1.31.18 name: worker - image: manifold/sidecar:1.0.0 name: metrics
24. Strategic Merge Patch spec: containers: - image: manifold/sidecar:1.0.0 name: metrics - $patch: replace
25. LONG RUNNING OPERATIONS Photo by Luke Stackpoole on Unsplash @jrbowes
26. Queue Endpoint PUT https://my.api/songs/2 HTTP/1.1 202 Accepted Location: /queue/2890 status: "pending" lastMessage: "request accepted" created: "2018-09-24T13:35:05Z"
27. Queue Endpoint • Good for infrequent operations • Requires clients to understand two resource types • What about resources that are continually experiencing long running changes?
28. Spec and Status • Include operation status in the resource • spec describes a resource’s desired state • status describes a resource’s current state • status does not mirror spec
29. Spec and Status apiVersion: extensions/v1beta1 kind: Deployment spec: replicas: 2 ... status: availableReplicas: 2 ...
30. @jrbowes Photo by Gamze Bozkaya on Unsplash THE INTERNAL MODEL
31. @jrbowes
32. @jrbowes
33. @jrbowes
34. @jrbowes
35. @jrbowes Photo by David Kovalenko on Unsplash LOST DATA
36. @jrbowes
37. @jrbowes
38. @jrbowes
39. @jrbowes
40. @jrbowes Photo by Fabrizio Verrecchia on Unsplash SLOW REACTIONS
41. @jrbowes
42. @jrbowes
43. @jrbowes Photo by Matt Artz on Unsplash PREVENTION AND REPAIR
44. Lost Intermediate Data • Edge triggered ◦ Track last seen revision number ◦ Perform a resync on missing version • Not an issue for level triggered
45. Stale Data • Heartbeat • Periodic resync (done in Kubernetes)
46. Slow Reactions • Edge triggered ◦ Keep state for last value ◦ Compute change to apply with real value, last seen, and changed • Not an issue for level triggered
47. @jrbowes Photo by Hans-Peter Gauster on Unsplash PIECING IT TOGETHER
48. TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others. - Jon Postel, RFC 761
49. be exhaustive in what you send, be explicit in what you receive from others.
50. @jrbowes Photo by Annie Spratt on Unsplash WRAPPING UP
51. @jrbowes Photo by Michael Hoyt on Unsplash COLOCATE COMPLEX LOGIC WITH STATE
52. @jrbowes Photo by Roman Koester on Unsplash IDENTIFY THE AUDIENCE AND BUILD FOR THEM
53. @jrbowes Photo by Andrés Canchón on Unsplash MAKE IT HARD FOR THE AUDIENCE TO FAIL
54. Thank you!