Before we touch a single keyword, we need to understand the problem that schema validation solves. It is simpler than it sounds.

Kubernetes in sixty seconds

A cluster is a group of computers that work together to run your applications. Inside the cluster there is a central program called the API server (its real name is kube-apiserver). Think of it as the front desk of a hotel. Every request, whether it comes from a person typing kubectl or from another program, goes through this one desk. Nobody is allowed to walk into the back rooms.

Behind the front desk sits etcd, a small, reliable database that stores the official record of everything in the cluster. Around it work many controllers, which are programs that constantly compare “what the record says should exist” with “what actually exists” and then fix any difference. If the record says “run three copies of this web server” and only two are running, a controller starts a third.

This style is called declarative. You do not give step-by-step orders. You describe the end result you want, store that description, and let the controllers do the work. It is like leaving a note for a house cleaner that says “the kitchen should be spotless” instead of standing next to them giving directions.

What goes wrong without a form

Because controllers trust whatever is in the record, a bad record is dangerous. Imagine someone stores a database object with a replica count of “many” instead of a number. The controller reads it, cannot understand it, and either crashes or silently ignores it. If the controller crashes in a loop, every other object it manages also stops getting attention. The mistake spreads from one typo to a whole team’s outage.

The longer a bad value sits in storage, the harder it is to clean up. The best moment to catch a mistake is the moment it is submitted, when the person who made it is still looking at their screen. This idea is often called fail fast. Validation at the front desk is the cheapest form of failing fast, because the error message appears right in the terminal, naming the exact field that is wrong.

Where the idea came from

Kubernetes was open-sourced by Google in 2014, shaped by lessons from the internal cluster systems the company had run for years. From the start, the built-in object types such as Pods and Deployments were checked by hand-written code inside the API server. That worked well for the types the core team wrote. It did not work for everyone else who wanted to teach Kubernetes about their own things, such as certificates, databases, message queues or machine-learning jobs.

The answer was to let users add new object types without changing the API server’s code. Early on this was done with a feature called ThirdPartyResources, which was awkward and was soon replaced. Its successor, the CustomResourceDefinition, became the standard way to extend Kubernetes. A CRD says, in effect, “from now on this cluster also understands objects of this new kind.” Along with the new kind comes a schema, so the API server can do the same checking for custom objects that it does for built-in ones.

A handful of words appear again and again in this topic. Learn them once and the rest of the article will feel easy.

What is OpenAPI, really?

OpenAPI is a public standard for describing how an API behaves and what data it sends and receives. It started life as a project called Swagger and was later donated to a neutral industry group, the OpenAPI Initiative, which is part of the Linux Foundation. Today it is used by companies of every size to produce documentation, client libraries and automatic checks.

The part of OpenAPI that matters for Kubernetes is the schema object. A schema object is a small description of a piece of data: “this is a string no longer than 63 characters,” or “this is a list of numbers, at least one and at most ten.” It is based on JSON Schema, a separate standard for describing JSON data. Kubernetes uses version 3 of the OpenAPI schema language, which is why you will see the field name openAPIV3Schema inside a CRD.

Kubernetes does not support every feature of OpenAPI. It takes a carefully chosen subset and adds its own extra keywords, all starting with x-kubernetes-. The standard allows custom extensions with an x- prefix, and Kubernetes uses that door to add behaviours such as “treat this list like a map.” We will meet them in Chapter 7.

A CRD is just another Kubernetes object, and it has a handful of important parts. The schema sits inside one of them.

When you create a CRD, you are talking to a built-in component of the API server called the apiextensions server. It watches for new CRDs. As soon as one is accepted, it starts serving a brand-new set of web addresses for the new type, with no restart and no new code. The new type then behaves like any built-in type: you can create, read, update, delete, list and watch it, and kubectl understands it.

flowchart TD
  A["CustomResourceDefinition"] --> B["group and names"]
  A --> C["scope"]
  A --> D["versions list"]
  D --> E["served flag"]
  D --> F["storage flag"]
  D --> G["openAPIV3Schema"]
  D --> H["subresources"]
  D --> I["additionalPrinterColumns"]
  G --> J["properties and types"]
  G --> K["validation keywords"]
  G --> L["x-kubernetes-validations"]
    

Read the diagram from top to bottom. The CRD has a name and group at the top, a scope, and a list of versions. Each version carries its own schema, so version one of your type can have different rules from version two. Inside the schema you find the plain shape (properties and types), the standard validation keywords, and the Kubernetes-specific CEL rules.

Spec and status: two halves of one object

Most custom resources follow a convention borrowed from built-in types. The spec section holds what the user wants. The status section holds what the controller observed. Users write the spec, controllers write the status. When you enable the status subresource, the API server enforces this split: updating the main object ignores changes to status, and updating the status address ignores changes to spec. That separation means a user cannot accidentally (or deliberately) forge a controller’s report.

Validation applies to both halves. A good schema constrains the spec tightly, because it is human input, and also describes the status carefully, so tools and dashboards know what to expect.

Scope and version flags in practice

The served flag lets you retire an old version gracefully. Setting it to false stops clients from using that version while the data in storage is still readable through newer versions. The storage flag decides which version’s shape is written to etcd. Changing the storage version later does not rewrite old data on its own; objects are converted when they are next written or when you run a migration. We return to this in Chapter 10.

A schema is built from a small toolbox. Once you know each tool, you can read almost any CRD in the wild.

Types: the six basic shapes

Every piece of data in a schema has a type. There are six you need to know. A string is text. An integer is a whole number. A number is any number, including decimals. A boolean is true or false. An object is a bundle of named fields, like a form with labelled boxes. An array is an ordered list of items, like a shopping list.

Objects and arrays are special because they contain other things. An object lists its fields under properties, and each property has its own schema. An array describes what each entry looks like under items. This nesting is how a tiny schema grows into a description of a very large object, one small piece at a time.

The validation toolbox

Required versus optional, and why it matters

By default, every field in an object is optional. You turn a field into a mandatory one by adding its name to the object’s required list. This is a decision with real consequences, because once a field is required, every existing tool that creates the object must supply it. Adding a new required field to a version people already use will break their automation the next time it runs. As a rule of thumb, start with fewer required fields and use defaults, then tighten later only in a new version.

Closed lists with enum

The enum keyword is the simplest and most powerful tool for catching typos. If a field called tier can only be “free”, “standard” or “premium”, then writing “premuim” fails immediately with an error that lists the allowed values. Without an enum, the typo would be stored happily, and the controller would either guess or fail much later.

Strings need limits too

An unlimited string is an open invitation for trouble. A name that is a million characters long could slow down the API server, bloat etcd and break tools that print it. Setting maxLength and, where it makes sense, a pattern keeps values sensible. There is also a hidden reason to set limits that we cover in Chapter 8: CEL rules need to know how big a value can get, and without a limit the API server assumes the worst case.

Maps: when the field names are not known in advance

Sometimes you cannot list every field name ahead of time. Labels on a Pod are a good example: users invent their own keys. For this the schema uses additionalProperties, which describes the shape of every value in a “free-keyed” object, such as “each value must be a string.” This is the schema’s way of saying “a dictionary of names to values.”

An object can use either properties (a fixed list of named fields) or additionalProperties (a dictionary), but not both on the same level. Choosing between them is a design decision: fixed fields give you strong checking and nice documentation; dictionaries give flexibility but weaker checks.

OpenAPI is flexible. Kubernetes deliberately narrows it. Understanding why makes the rules feel logical instead of annoying.

In the stable CRD API, a schema must be structural. That is a fancy word for a simple idea: the schema must describe the real shape of the data clearly enough that the API server can work with it automatically. The server needs to know, for every piece of data, exactly what type it is and where it lives. Only then can it safely remove unknown fields, fill in defaults and run CEL rules.

The rules, in plain words

Why so strict?

Each rule protects a feature. The type rule makes pruning possible, because you cannot decide whether a field is “unknown” if you do not know what is known. The no-reference rule keeps the schema fast and simple to walk through at high speed, which matters because the API server checks it on every single write. The ban on uniqueItems exists because checking uniqueness over big lists can be slow and expensive, so Kubernetes offers list-type markers and CEL as safer alternatives.

For the machines, the benefits are huge. A structural schema can be turned into accurate documentation, into client code, into a form in a web console, and into the OpenAPI document that kubectl downloads. In other words, the strict rules are what make the whole tool ecosystem work smoothly around your CRD.

Validation is not only about saying no. Because the schema is structural, the API server can also tidy up and fill in your objects automatically.

Pruning: trimming what the schema does not know

Pruning means that any field the schema does not describe is quietly removed from the object before it is stored. If your schema knows about replicas and a user sends replcas (a typo), the misspelled field is not part of the shape, so the API server drops it. The object is stored without it.

Why would Kubernetes do something that sounds so silent? Because stored data should always match a known shape. Without pruning, old and new versions of a controller could end up arguing over mystery fields that nobody documented, and a malicious or careless user could stash arbitrary data in your objects. Pruning keeps etcd clean and keeps the contract between the schema and the controller honest.

Pruning happens at two moments. It is applied to every incoming request, and it is also applied when objects are read back from etcd. The second part matters when you change the schema: if you remove a field from a version, the old data for that field disappears from what clients see immediately, and it is gone from storage the next time the object is written.

The silent-typo trap and how to avoid it

Silent pruning is a double-edged sword. It protects storage, but it can hide a typo from the person who made it. To fix this, Kubernetes supports field validation on the server. A client can ask the server to be Strict (reject objects with unknown or duplicate fields), Warn (accept, but send back a warning message) or Ignore (prune silently). Current versions of kubectl ask for strict checking by default, so a typo normally produces a clear error. Other tools, such as a custom script, might not ask, so the safe habit is to make your own clients request strict validation too.

When you really do want unknown fields

Sometimes a field is meant to hold free-form data that you cannot describe. A plugin configuration blob is a classic example. For these cases the schema can add the marker x-kubernetes-preserve-unknown-fields set to true on that one node. Pruning then leaves everything under that node alone. Use it sparingly and on the smallest possible node, because inside that node you lose most of the checking.

Defaulting: filling in the blanks

Defaulting means that when a field is missing, the API server inserts the value you named in the default keyword. A user who leaves out replicas gets 1; a user who leaves out protocol gets “TCP”. The stored object then always contains an explicit value, so controllers never have to guess.

The built-in Deployment object is a familiar example. If you do not say how many copies to run, you get one. If you do not set an update strategy, you get a rolling update that replaces pods gradually, and the revision history kept for rollbacks is limited to a sensible number. Users enjoy short manifests, and the system enjoys complete records. Defaults on a CRD give your custom types the same comfort.

Defaulting runs at three moments: on the incoming request, after any mutating admission step that changed the object, and again when reading from etcd. The last one is very handy. If you add a new field with a default in a later version of your CRD, old objects that were stored without the field will appear to have it, without anyone rewriting them.

What about null?

JSON allows an explicit null, which means “I deliberately set this to nothing.” In a CRD, a field that does not declare nullable: true treats null as if the field were absent: the null is pruned away, and then the default, if any, is applied. If you do want to allow null as a real value, mark the field nullable. Be careful with this choice, because many languages and tools handle null in surprising ways.

Plain OpenAPI cannot express a few things that Kubernetes needs. The x-kubernetes- keywords fill those gaps.

Int-or-string in action

Think of a form box that says “How much of the fleet can be offline during an update?” Some people want to answer “2 machines”, others want to answer “10 percent”. The int-or-string marker allows both answers. When you use it, you typically also add a pattern to limit the text form, so that only values such as “10%” are accepted and random words are not.

Lists as sets and maps: why merging matters

Kubernetes has a modern editing system called server-side apply. It lets many different tools and people each own different parts of the same object. For this to work, the server must understand how to merge changes to lists. A plain list is ambiguous: if two tools each add an entry, is that two entries or a clash?

The list-type marker removes the doubt. A list marked atomic is treated as one indivisible value, so whoever writes last replaces the whole list. A list marked set holds unique simple values, such as a list of finalizer names, and the server merges them like a bag of tokens. A list marked map holds objects that each have a key, such as the containers in a Pod, which are identified by name. The server merges them entry by entry using that key.

These markers also deliver validation as a bonus. For a set, the API server rejects duplicate values. For a map, it rejects two entries with the same key. This is the safe, built-in replacement for the banned uniqueItems keyword. When you choose the map style, the key fields must be either required or have defaults, so every entry can be identified.

Embedded resources

Some custom types carry a full Kubernetes object inside them. A typical case is a template, such as “when you create one of these, also create a Pod that looks like this.” Marking such a field as an embedded resource tells the server to confirm the inner object has the three standard identity fields: apiVersion, kind and metadata. It also prevents pruning of that identity and validates the metadata like any other object.

Schema keywords check one field at a time. Real-world rules usually compare fields. This is where the Common Expression Language shines.

The gap that CEL fills

Suppose your CRD has minReplicas and maxReplicas. Each is a number between 1 and 1000, and the plain keywords check that. But nothing in plain OpenAPI says “minimum must not be larger than maximum.” Another case: “if the storage type is set to disk, then a disk size is required.” These rules look across fields, and the standard schema keywords cannot say them.

For years, people solved this by running a separate program, an admission webhook, that the API server would call on every write. Webhooks work, but they are extra servers to deploy, secure, monitor and keep available. If the webhook is down, writes can fail for the whole cluster. CEL moves these rules into the CRD itself, so the API server runs them directly with no network call.

What is CEL?

The Common Expression Language is a tiny, fast language that Google designed for evaluating rules safely. It is used in many places outside Kubernetes, for example in network proxies and security-rule engines. CEL is deliberately limited. It has no loops that can run forever, no ability to write files or call the network, and every expression is guaranteed to finish. That makes it safe to run inside a shared, critical program like the API server.

A CEL expression reads a bit like a sentence in a spreadsheet formula: you compare values, combine conditions with “and” and “or”, test whether text starts with something, count items in a list, and so on. The expression must come out as true or false. True means “the object is fine”; false means “reject it with my message.”

How the rules are attached

Rules are written in a list called x-kubernetes-validations, placed on any node of the schema. Each entry in the list has these parts:

Inside a rule, the name self means “the value at the node where this rule is placed.” If you put the rule on the spec node, then self is the whole spec, and the rule can reach into its fields. If you put it on a single field, self is just that field’s value. This is helpful because the closer the rule sits to the data, the clearer the error message.

Transition rules: remembering the past

CEL has one more trick. On an update, a rule can use oldSelf, which means “the value of this node before the change.” Rules that use it are called transition rules, because they judge the move from old to new. They are the standard way to build immutability. A rule that says “the new value must equal the old value” makes a field settable at creation and frozen forever after. Another rule might say “a status can only move forward, never backward”, or “the storage size may grow but never shrink.”

Transition rules only run on updates, because a create has no old object. If you want a rule to run on create too, with the old value treated as optional, that is what optionalOldSelf is for.

Examples of rules, in words

The cost budget: why unbounded fields cause errors

Because CEL runs inside the API server, Kubernetes must make sure no rule can eat too much time. When you create a CRD, the server estimates the worst-case cost of every rule before accepting it. The estimate depends on how big the data could possibly be. If a string has no maxLength, the server must assume it could be enormous, and if a list has no maxItems, it must assume it could hold a huge number of entries. A rule that loops over such a list can then be judged too expensive, and the CRD is rejected with an error saying the estimated rule cost exceeds the budget.

The cure is almost always the same: add sensible limits to the strings and lists the rule touches. This is a nice side effect, because limits are good practice anyway. There is also a separate runtime limit, so even if a rule passes the estimate, a request that makes it do too much work is stopped. And there is a total budget per CRD, so many expensive rules cannot add up to a problem.

Let us follow a single request from your keyboard to the database, and see exactly where each check happens.

flowchart LR
  A["Client request"] --> B["Authentication"]
  B --> C["Authorization"]
  C --> D["Decode, prune, apply defaults"]
  D --> E["Mutating admission"]
  E --> F["Schema and CEL validation"]
  F --> G["Validating admission"]
  G --> H["Write to etcd"]
  H --> I["Response to client"]
  F -.->|invalid| X["422 error to client"]
  G -.->|denied| Y["Denied error to client"]
    

The order is not an accident. Validation happens after mutating admission so that it judges the final shape of the object, not an earlier draft. If validation ran first, a mutating webhook could then turn a valid object into an invalid one and nobody would notice. Validating webhooks run after schema validation so that they can assume a well-formed object and spend their effort on business rules.

How the schema is applied so quickly

The API server handles a very large number of writes in a busy cluster, so it cannot afford to re-read the CRD from scratch every time. When a CRD is created or changed, the apiextensions server compiles the schema into an internal validator and keeps it in memory. The same is done for CEL rules: each expression is parsed and checked once, and the compiled form is reused. A request then simply runs the prepared checks. This is why even complicated schemas add only a small delay to each request.

When a CRD itself is bad

The CRD is itself validated when you create it. If its schema is not structural, the object reports a condition named NonStructuralSchema in its status. Conditions are small status notes, a bit like a traffic-light panel on a dashboard. You will also see conditions such as NamesAccepted (are the names free and valid?) and Established (is the new API address live?). When something goes wrong, running kubectl describe on the CRD and reading these conditions usually points straight to the cause.

A schema is not written once and forgotten. It must change as your product grows, and old objects are still sitting in storage.

Versions and conversion

A CRD can serve several versions at once, for example v1beta1 and v1. Clients can read and write whichever version they like, but the server stores each object in just one: the storage version. When a client asks for a version different from the stored one, the server converts the object on the fly.

Conversion comes in two flavours. With the default strategy, called None, the server simply changes the apiVersion label and leaves the fields alone. This works only if the shapes are identical. With the Webhook strategy, the server calls a conversion service you run, which translates field by field, such as turning a single host field into a list of hosts. Because a conversion webhook sits on the path of reads and writes, it must be extremely reliable, so many teams try hard to avoid needing one by making only additive changes.

Safe and unsafe schema changes

Validation ratcheting: forgiving the past

Imagine you tighten a rule: names must now be at most 30 characters, and some old objects have 40. Without special help, the next time anyone updates such an object, say to change an unrelated label, validation would fail, because the old name no longer passes. The user would be forced to fix a field they never touched.

Validation ratcheting solves this. A ratchet is a gear that turns one way only. On an update, if validation finds errors, the server compares the failing fields with the old object. If the failing parts have not changed, those errors are ignored, because the object was already in that state before. Only errors in fields the user actually changed cause a rejection. It became available as a beta feature turned on by default from Kubernetes 1.30, and it has since moved forward toward stable status. In practice it means schema authors can add stricter rules with much less fear of stranding existing objects.

flowchart TD
  A["Update request arrives"] --> B["Validate new object against schema"]
  B -->|no errors| OK["Accept and store"]
  B -->|errors found| C["Compare failing fields with the old object"]
  C -->|failing fields unchanged| OK
  C -->|failing fields changed| R["Reject with 422"]
    

Read the diagram from the top. A request arrives and the new object is validated. If there are no errors the update is accepted. If there are errors, the server looks at where they are. If they sit in parts that are identical in the old object, the update is allowed anyway. If the user changed one of the failing fields, the update is rejected. Ratcheting has a few limits: it generally does not forgive errors on lists that cannot be matched item by item, and it does not rescue a rule that was always broken for a field the user is now editing.

Migrating stored data

Changing the storage version only affects objects as they are written. Objects nobody touches stay in the old format in etcd. Over a long time, you may want to rewrite all of them, so that you can safely stop serving the old version. The common approach is to read and write every object once, using a storage version migration tool, and then remove the old version from the CRD’s list of stored versions. Until you do, the CRD keeps a record of every version that may still exist in storage, and the API server will refuse to drop a version still listed there.

The schema is not only for the API server. It is also published, so every tool in your pipeline can use it.

Built-in resources versus CRDs

The built-in types, such as Pods, Services and Deployments, are validated by hand-written code in the API server. The rules for them are compiled into the program. Custom resources do not have that luxury; the API server has no custom code for them, so everything comes from the schema and the CEL rules you supply. From the user’s point of view the experience is meant to feel identical: the same error format, the same status codes and the same field-level messages.

Publishing: how kubectl learns your schema

The API server collects the schemas of all built-in types and all installed CRDs and serves them as a single OpenAPI document at well-known web addresses. This is the reason kubectl explain can show help for a type that was installed five minutes ago. It downloads the published document and prints the descriptions from your schema. Editors and IDE plugins use the same document to offer auto-complete and red underlines as people write manifests, which is validation before the request is even sent.

Three places to catch errors

Dry run: rehearsing a request

A server-side dry run asks the API server to process the request fully, including pruning, defaulting, webhooks and validation, and then to return the result without storing anything. It is the most trustworthy way to test a manifest because it uses the true rules of the true cluster, including any extra webhooks that clients do not know about. A common pipeline step is to dry-run every changed manifest against a staging cluster before deploying to production.

Field validation modes at a glance

Schema validation is the first line of defence, not the only one. Knowing where it ends helps you choose the right tool for each rule.

A schema can only judge one object, in isolation, at the moment it is written. It cannot know that the name you picked is already used by something else, that your team has run out of its quota, or that the image you named is not on the approved list. For rules like these, Kubernetes offers more layers, and each layer trades power for cost.

flowchart TD
  A["Incoming object"] --> L1["Layer 1 Structural schema: shape and types"]
  L1 --> L2["Layer 2 CEL rules: relations between fields"]
  L2 --> L3["Layer 3 ValidatingAdmissionPolicy: cluster wide policy"]
  L3 --> L4["Layer 4 Admission webhooks: external logic"]
  L4 --> L5["Layer 5 Controller checks: runtime reality"]
    

The diagram shows five layers. The first two are part of your CRD and travel with it. The third is a cluster-level policy that an administrator installs. The fourth is an outside program the API server calls over the network. The fifth is your own controller, which discovers problems that are only visible when it tries to act, such as “the cloud account you pointed me to does not exist.”

ValidatingAdmissionPolicy: CEL for the whole cluster

A ValidatingAdmissionPolicy, which became stable in Kubernetes 1.30, takes the idea of CEL rules and applies it to any resource, built-in or custom, from outside the CRD. A cluster administrator writes a policy such as “no workload may use the latest tag for its image,” then attaches it to a set of resources with a binding. The binding also decides what happens on a violation: deny the request, warn the user but allow it, or only record it in the audit log. Policies can read an extra parameter object, so one policy can be reused with different limits per team.

This is a perfect fit for organisation-wide rules owned by platform teams, while the CRD’s own CEL rules stay in the hands of the CRD author. The two do not conflict; both must pass.

Admission webhooks: the heavy hammer

A validating admission webhook is a small web service that the API server calls with the proposed object. The service replies with allow or deny. Because it is ordinary code, it can do anything: look up other objects, call an external database, check a company-wide naming registry. That freedom is also the cost. The service must be highly available, because a failing webhook can block writes; it must be secured with certificates; and it adds delay to each request. Teams therefore choose them only when schema, CEL and policies are not enough.

Policy engines

Projects such as Kyverno and OPA Gatekeeper package the webhook approach into ready-made policy engines. Teams write policies in a simpler language, and the engine handles the web service, reporting and audit. They are popular for compliance rules like “every namespace must have an owner label” or “only images from our registry.” They sit in layers three and four of the diagram.

Validation is a security feature and an operational signal at the same time. Treat it as both.

Schema as a security tool

Every limit you write is a small shield. A maxLength on a name stops someone from filling etcd with giant strings. A maxItems on a list stops a flood of entries. An enum stops free-form input where only a handful of values make sense. These limits matter because etcd has a cap on how big a single request can be (around 1.5 megabytes by default), and a very large object slows down every controller that watches it.

Regular expressions in a pattern are checked by Go’s standard engine, which runs in time proportional to the input and so avoids the “catastrophic” slowdowns some other engines suffer. Even so, keep patterns short and simple. Anything that needs a long pattern is often easier to read as a CEL rule.

Who may create a CRD?

Creating or editing a CRD is a very powerful permission. It can add new web addresses to the cluster’s API and, through conversion webhooks, route traffic to outside services. Grant it only to cluster administrators and trusted automation. Meanwhile, give users access to the custom resources themselves through ordinary role-based access control, with fine-grained rules for who may read, write or touch the status.

Validation is not authorization

A schema checks that a value is well formed, not that the caller is allowed to ask for it. A perfectly valid request to give an application cluster-admin rights is still dangerous. Always combine schema checks with roles, and use the status subresource so that only your controller can write the status.

Keep secrets out of custom resources

Custom resources are stored like any other object. Passwords and keys should live in Secret objects, and your CRD should hold only a reference by name. If you must keep sensitive data in a custom resource, make sure encryption at rest is set up for it on the cluster.

What to watch

Good error messages are an operations tool

When validation fails at 3 a.m. during a deployment, the error message is the first and often only clue an engineer sees. A message that names the field, the bad value and the allowed range lets them fix the problem in a minute. A vague message turns a one-minute fix into a long search. Treat your message text as part of your product, and review it with the same care as the rules.

Experienced CRD authors keep returning to the same handful of good habits, and the same handful of traps.

Patterns worth copying

Traps to avoid

A short checklist you can keep next to your keyboard, followed by the errors that appear most often in real clusters.

Best practices

Common mistakes and quick fixes

Trade-offs at a glance

The best way to see why this matters is to look at the popular projects that rely on it every day.

A typical journey at a growing company

A small team begins with a single CRD for its internal deployment tool. At first the schema is loose, and engineers send whatever works. After a few incidents caused by typos, the team adds enums, limits and required fields. A migration is planned using defaults and ratcheting, so existing objects keep working. Later, a platform group introduces ValidatingAdmissionPolicies for organisation-wide rules such as naming and ownership labels. Only a few rules that need external data, such as checking a budget system, remain in a webhook. By then the schema, the policies and the controller each have a clear job, and incidents from malformed objects become rare.

Schema validation is the printed order form of Kubernetes. It lets the API server say “no” quickly and clearly, before a mistake reaches storage and the controllers that trust it. The OpenAPI v3 schema describes the shape of each custom object, the strict structural rules make that description precise enough for the server to prune, default and check automatically, and CEL adds the cross-field and immutability rules that plain keywords cannot express. Around that core sit policies, webhooks and controllers, each handling the checks that only they can do.