1 // -*- fill-column: 70 -*- 2 3 // Copyright 2020-2021 Datawire. All rights reserved 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); you 6 // may not use this file except in compliance with the License. You 7 // may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 // implied. See the License for the specific language governing 15 // permissions and limitations under the License. 16 17 ////////////////////////////////////////////////////////////////////// 18 // 0. Table of Contents ////////////////////////////////////////////// 19 ////////////////////////////////////////////////////////////////////// 20 // 21 // This file deals with common package/apiVersion-level things not 22 // specific to any individual CRD: 23 // 24 // 1. Magic markers: Document the various magic "+marker" comments 25 // that are used in this package, and set up the package-level 26 // markers. 27 // 28 // 2. Package documentation: The `godoc` package-wide documentation. 29 // 30 // 3. Scheme: Set up the Group/Version/SchemeBuilder/AddToScheme for 31 // this apiVersion. 32 // 33 // Things that are shared between multiple CRDs, but are for 34 // individual CRDs rather than the package/apiVersion as a whole, do 35 // not belong in this file; they belong in `common.go`. 36 37 ////////////////////////////////////////////////////////////////////// 38 // 1. Magic markers ////////////////////////////////////////////////// 39 ////////////////////////////////////////////////////////////////////// 40 // 41 // We use a bunch of magic comments called "+markers" that serve as 42 // input to `controller-gen` and `conversion-gen`. Note that while 43 // `controller-gen` doesn't care about what file these are in, the 44 // older `k8s.io/gengo`-based `conversion-gen` specifically looks for 45 // `doc.go`. Mostly they annotate a type, or a field within a struct. 46 // Just below here, we do the "global" package-level markers; these 47 // package-level markers need to come before the "package" line. 48 // 49 // The type markers of interest are: 50 // 51 // - "+kubebuilder:object:generate=bool" whether to generate 52 // `DeepCopy` and `DeepCopyInto` methods for this type; but we 53 // don't actually set this on types, since we can set it to true 54 // for all types at the package-level. 55 // 56 // - "+kubebuilder:object:root=bool" whether to *also* generate a 57 // `DeepCopyObject` method. It upsets me that controller-gen 58 // doesn't infer this based on the presence of metav1.TypeMeta 59 // inside of the type. 60 // 61 // - "+kubebuilder:subresource:status" whether to add "status" as a 62 // subresource for that type. It upsets me that controller-gen 63 // doesn't infer this based on the presence of a `status` field 64 // inside of the type. 65 // 66 // The field markers of interest are: 67 // 68 // - The "+kubebuilder:validation:*" markers control the OpenAPI v3 69 // validation schema that is generated for this field. ":Optional" 70 // or ":Required" may be applied at the package-level in order to 71 // set the default for all fields. Most of the others can also be 72 // set at the type level. 73 // 74 // Package-level markers: 75 // 76 // The group name to use for the CRDs in the generated YAML: 77 // +groupName=getambassador.io 78 // +versionName=v1 79 // 80 // By default, mark all types in this package to have DeepCopy methods 81 // generated (so we don't need to specify this for every type): 82 // +kubebuilder:object:generate=true 83 // 84 // By default, mark all fields as optional (so we don't need to 85 // specify this for every optional field, since most fields are 86 // optional; and also because controller-gen's "required-by-default" 87 // mode is broken and always makes everything optional, even if it's 88 // explicitly marked as required): 89 // +kubebuilder:validation:Optional 90 // 91 // Have conversion-gen help write the code to convert to and from 92 // newer CRD versions. 93 // +k8s:conversion-gen=github.com/datawire/ambassador/v2/pkg/api/getambassador.io/v2 94 95 ////////////////////////////////////////////////////////////////////// 96 // 2. Package documentation ////////////////////////////////////////// 97 ////////////////////////////////////////////////////////////////////// 98 99 // Package v1 contains API Schema definitions for the getambassador.io 100 // v1 API group 101 package v1 102 103 ////////////////////////////////////////////////////////////////////// 104 // 3. Scheme ///////////////////////////////////////////////////////// 105 ////////////////////////////////////////////////////////////////////// 106 107 import ( 108 "k8s.io/apimachinery/pkg/runtime/schema" 109 "sigs.k8s.io/controller-runtime/pkg/scheme" 110 ) 111 112 var ( 113 // GroupVersion is group version used to register these objects 114 GroupVersion = schema.GroupVersion{Group: "getambassador.io", Version: "v1"} 115 116 // SchemeBuilder is used to add go types to the GroupVersionKind scheme 117 SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion} 118 119 // AddToScheme adds the types in this group-version to the given scheme. 120 AddToScheme = SchemeBuilder.AddToScheme 121 122 // This is so the generated conversion code will compile. 123 localSchemeBuilder = &SchemeBuilder.SchemeBuilder 124 ) 125