sigs.k8s.io/controller-tools@v0.15.1-0.20240515195456-85686cb69316/pkg/crd/doc.go (about) 1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 // Package crd contains utilities for generating CustomResourceDefinitions and 18 // their corresponding OpenAPI validation schemata. 19 // 20 // # Markers 21 // 22 // Markers live under the markers subpackage. Two types of markers exist: 23 // those that modify schema generation (for validation), and those that modify 24 // the rest of the CRD. See the subpackage for more information and all 25 // supported markers. 26 // 27 // # Collecting Types and Generating CRDs 28 // 29 // The Parser is the entrypoint for collecting the information required to 30 // generate CRDs. Like loader and collector, its methods are idemptotent, not 31 // doing extra work if called multiple times. 32 // 33 // Parser's method start with Need. Calling NeedXYZ indicates that XYZ should 34 // be made present in the eqivalent field in the Parser, where it can then be 35 // loaded from. Each Need method will in turn call Need on anything it needs. 36 // 37 // In general, root packages should first be loaded into the Parser with 38 // NeedPackage. Then, CRDs can be generated with NeedCRDFor. 39 // 40 // Errors are generally attached directly to the relevant Package with 41 // AddError. 42 // 43 // # Known Packages 44 // 45 // There are a few types from Kubernetes that have special meaning, but don't 46 // have validation markers attached. Those specific types have overrides 47 // listed in KnownPackages that can be added as overrides to any parser. 48 // 49 // # Flattening 50 // 51 // Once schemata are generated, they can be used directly by external tooling 52 // (like JSONSchema validators), but must first be "flattened" to not contain 53 // references before use in a CRD (Kubernetes doesn't allow references in the 54 // CRD's validation schema). 55 // 56 // The Flattener built in to the Parser takes care of flattening out references 57 // when requesting the CRDs, but can be invoked manually. It will not modify 58 // the input schemata. 59 // 60 // Flattened schemata may further be passed to FlattenEmbedded to remove the 61 // use of AllOf (which is used to describe embedded struct fields when 62 // references are in use). This done automatically when fetching CRDs. 63 package crd