API Evolution With CRDs: Best Practices For Authoring & Fuzz Testing APIs

Best practices for creating Kubernetes APIs using OpenAPI schemas

• Breaking down the model into more resources
• Writing a complete schema is required for V1 CRDs
• Use Cube CTL explain to ensure a complete schema
• OpenAPI schemas allow for validation and defaulting without expensive network round trips
• Testing methodologies are important to ensure the resiliency of the controller and code in production

One common mistake is not specifying a max length for strings, which can lead to an unbounded amount of data and cause problems for the API server. Additionally, testing for error conditions is important to ensure the resiliency of the controller and code in production.

CustomResourceDefinitions are prolific in Kubernetes. With so many new projects being prototyped, developed and released into the ecosystem, it's essential to ensure you're designing your APIs in a scalable, well tested way. Projects like Kubebuilder and the Operator Framework provide plentiful tooling to keep you on 'the straight and narrow', but some fundamental issues still trip up even the most experienced Kubernetes engineers. In this talk, we'll go over strategies & tooling that can help ensure you are successful when authoring and evolving your APIs, including:* How to ensure your APIs follow best practices/standards (and linting OpenAPI schemas!)* Fuzz & integration testing API version conversion functions to ensure platform stability in your clusters* Automatically validating your OpenAPI schemas are up to date for your type definitions* Best practices in 2022 for writing validations & mutations* Ensuring your OpenAPI schema changes are backwards compatible within an API versionJames has helped bring various API groups to stability across projects in the ecosystem and both he and Andrea have experience with unique problems that are found when projects reach a certain scale & maturity, having helped take CRDs through a full alpha to beta to GA deprecation cycle.