github.com/TheSpiritXIII/controller-tools@v0.14.1/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