diff --git a/pkg/crd/markers/crd.go b/pkg/crd/markers/crd.go index 1b1cf5ede..ac3513279 100644 --- a/pkg/crd/markers/crd.go +++ b/pkg/crd/markers/crd.go @@ -55,6 +55,9 @@ var CRDMarkers = []*definitionWithHelp{ must(markers.MakeDefinition("kubebuilder:metadata", markers.DescribesType, Metadata{})). WithHelp(Metadata{}.Help()), + + must(markers.MakeDefinition("kubebuilder:field:scope", markers.DescribesField, FieldScope(""))). + WithHelp(FieldScope("").Help()), } // TODO: categories and singular used to be annotations types @@ -388,3 +391,12 @@ func (s Metadata) ApplyToCRD(crd *apiext.CustomResourceDefinition, _ string) err return nil } + +// +controllertools:marker:generateHelp:category=CRD +// FieldScope specifies the scope of the field. If the field scope does not match the outer-most +// resource scope, then this field is ignored and not included in the final CRD. +type FieldScope string + +func (m FieldScope) Value() string { + return string(m) +} diff --git a/pkg/crd/markers/zz_generated.markerhelp.go b/pkg/crd/markers/zz_generated.markerhelp.go index d8a910824..eaa99ebfe 100644 --- a/pkg/crd/markers/zz_generated.markerhelp.go +++ b/pkg/crd/markers/zz_generated.markerhelp.go @@ -28,8 +28,8 @@ func (Default) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "sets the default value for this field. ", - Details: "A default value will be accepted as any value valid for the field. Formatting for common types include: boolean: `true`, string: `Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy: \"delete\"}`). Defaults should be defined in pruned form, and only best-effort validation will be performed. Full validation of a default requires submission of the containing CRD to an apiserver.", + Summary: "sets the default value for this field.", + Details: "A default value will be accepted as any value valid for the\nfield. Formatting for common types include: boolean: `true`, string:\n`Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy:\n\"delete\"}`). Defaults should be defined in pruned form, and only best-effort\nvalidation will be performed. Full validation of a default requires\nsubmission of the containing CRD to an apiserver.", }, FieldHelp: map[string]markers.DetailedHelp{ "Value": { @@ -71,8 +71,8 @@ func (Example) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "sets the example value for this field. ", - Details: "An example value will be accepted as any value valid for the field. Formatting for common types include: boolean: `true`, string: `Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy: \"delete\"}`). Examples should be defined in pruned form, and only best-effort validation will be performed. Full validation of an example requires submission of the containing CRD to an apiserver.", + Summary: "sets the example value for this field.", + Details: "An example value will be accepted as any value valid for the\nfield. Formatting for common types include: boolean: `true`, string:\n`Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy:\n\"delete\"}`). Examples should be defined in pruned form, and only best-effort\nvalidation will be performed. Full validation of an example requires\nsubmission of the containing CRD to an apiserver.", }, FieldHelp: map[string]markers.DetailedHelp{ "Value": { @@ -105,12 +105,23 @@ func (ExclusiveMinimum) Help() *markers.DefinitionHelp { } } +func (FieldScope) Help() *markers.DefinitionHelp { + return &markers.DefinitionHelp{ + Category: "CRD", + DetailedHelp: markers.DetailedHelp{ + Summary: "specifies the scope of the field. If the field scope does not match the outer-most", + Details: "resource scope, then this field is ignored and not included in the final CRD.", + }, + FieldHelp: map[string]markers.DetailedHelp{}, + } +} + func (Format) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies additional \"complex\" formatting for this field. ", - Details: "For example, a date-time field would be marked as \"type: string\" and \"format: date-time\".", + Summary: "specifies additional \"complex\" formatting for this field.", + Details: "For example, a date-time field would be marked as \"type: string\" and\n\"format: date-time\".", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -120,8 +131,8 @@ func (ListMapKey) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD processing", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies the keys to map listTypes. ", - Details: "It indicates the index of a map list. They can be repeated if multiple keys must be used. It can only be used when ListType is set to map, and the keys should be scalar types.", + Summary: "specifies the keys to map listTypes.", + Details: "It indicates the index of a map list. They can be repeated if multiple keys\nmust be used. It can only be used when ListType is set to map, and the keys\nshould be scalar types.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -131,8 +142,8 @@ func (ListType) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD processing", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies the type of data-structure that the list represents (map, set, atomic). ", - Details: "Possible data-structure types of a list are: \n - \"map\": it needs to have a key field, which will be used to build an associative list. A typical example is a the pod container list, which is indexed by the container name. \n - \"set\": Fields need to be \"scalar\", and there can be only one occurrence of each. \n - \"atomic\": All the fields in the list are treated as a single value, are typically manipulated together by the same actor.", + Summary: "specifies the type of data-structure that the list", + Details: "represents (map, set, atomic).\n\n\nPossible data-structure types of a list are:\n\n\n - \"map\": it needs to have a key field, which will be used to build an\n associative list. A typical example is a the pod container list,\n which is indexed by the container name.\n\n\n - \"set\": Fields need to be \"scalar\", and there can be only one\n occurrence of each.\n\n\n - \"atomic\": All the fields in the list are treated as a single value,\n are typically manipulated together by the same actor.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -142,8 +153,8 @@ func (MapType) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD processing", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies the level of atomicity of the map; i.e. whether each item in the map is independent of the others, or all fields are treated as a single unit. ", - Details: "Possible values: \n - \"granular\": items in the map are independent of each other, and can be manipulated by different actors. This is the default behavior. \n - \"atomic\": all fields are treated as one unit. Any changes have to replace the entire map.", + Summary: "specifies the level of atomicity of the map;", + Details: "i.e. whether each item in the map is independent of the others,\nor all fields are treated as a single unit.\n\n\nPossible values:\n\n\n - \"granular\": items in the map are independent of each other,\n and can be manipulated by different actors.\n This is the default behavior.\n\n\n - \"atomic\": all fields are treated as one unit.\n Any changes have to replace the entire map.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -197,8 +208,8 @@ func (Metadata) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD", DetailedHelp: markers.DetailedHelp{ - Summary: "configures the additional annotations or labels for this CRD. For example adding annotation \"api-approved.kubernetes.io\" for a CRD with Kubernetes groups, or annotation \"cert-manager.io/inject-ca-from-secret\" for a CRD that needs CA injection.", - Details: "", + Summary: "configures the additional annotations or labels for this CRD.", + Details: "For example adding annotation \"api-approved.kubernetes.io\" for a CRD with Kubernetes groups,\nor annotation \"cert-manager.io/inject-ca-from-secret\" for a CRD that needs CA injection.", }, FieldHelp: map[string]markers.DetailedHelp{ "Annotations": { @@ -272,7 +283,7 @@ func (Nullable) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "marks this field as allowing the \"null\" value. ", + Summary: "marks this field as allowing the \"null\" value.", Details: "This is often not necessary, but may be helpful with custom serialization.", }, FieldHelp: map[string]markers.DetailedHelp{}, @@ -303,8 +314,8 @@ func (PrintColumn) Help() *markers.DefinitionHelp { Details: "", }, "Type": { - Summary: "indicates the type of the column. ", - Details: "It may be any OpenAPI data type listed at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types.", + Summary: "indicates the type of the column.", + Details: "It may be any OpenAPI data type listed at\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types.", }, "JSONPath": { Summary: "specifies the jsonpath expression used to extract the value of the column.", @@ -315,12 +326,12 @@ func (PrintColumn) Help() *markers.DefinitionHelp { Details: "", }, "Format": { - Summary: "specifies the format of the column. ", - Details: "It may be any OpenAPI data format corresponding to the type, listed at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types.", + Summary: "specifies the format of the column.", + Details: "It may be any OpenAPI data format corresponding to the type, listed at\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types.", }, "Priority": { - Summary: "indicates how important it is that this column be displayed. ", - Details: "Lower priority (*higher* numbered) columns will be hidden if the terminal width is too small.", + Summary: "indicates how important it is that this column be displayed.", + Details: "Lower priority (*higher* numbered) columns will be hidden if the terminal\nwidth is too small.", }, }, } @@ -335,24 +346,24 @@ func (Resource) Help() *markers.DefinitionHelp { }, FieldHelp: map[string]markers.DetailedHelp{ "Path": { - Summary: "specifies the plural \"resource\" for this CRD. ", - Details: "It generally corresponds to a plural, lower-cased version of the Kind. See https://book.kubebuilder.io/cronjob-tutorial/gvks.html.", + Summary: "specifies the plural \"resource\" for this CRD.", + Details: "It generally corresponds to a plural, lower-cased version of the Kind.\nSee https://book.kubebuilder.io/cronjob-tutorial/gvks.html.", }, "ShortName": { - Summary: "specifies aliases for this CRD. ", - Details: "Short names are often used when people have work with your resource over and over again. For instance, \"rs\" for \"replicaset\" or \"crd\" for customresourcedefinition.", + Summary: "specifies aliases for this CRD.", + Details: "Short names are often used when people have work with your resource\nover and over again. For instance, \"rs\" for \"replicaset\" or\n\"crd\" for customresourcedefinition.", }, "Categories": { - Summary: "specifies which group aliases this resource is part of. ", - Details: "Group aliases are used to work with groups of resources at once. The most common one is \"all\" which covers about a third of the base resources in Kubernetes, and is generally used for \"user-facing\" resources.", + Summary: "specifies which group aliases this resource is part of.", + Details: "Group aliases are used to work with groups of resources at once.\nThe most common one is \"all\" which covers about a third of the base\nresources in Kubernetes, and is generally used for \"user-facing\" resources.", }, "Singular": { - Summary: "overrides the singular form of your resource. ", + Summary: "overrides the singular form of your resource.", Details: "The singular form is otherwise defaulted off the plural (path).", }, "Scope": { - Summary: "overrides the scope of the CRD (Cluster vs Namespaced). ", - Details: "Scope defaults to \"Namespaced\". Cluster-scoped (\"Cluster\") resources don't exist in namespaces.", + Summary: "overrides the scope of the CRD (Cluster vs Namespaced).", + Details: "Scope defaults to \"Namespaced\". Cluster-scoped (\"Cluster\") resources\ndon't exist in namespaces.", }, }, } @@ -362,8 +373,8 @@ func (Schemaless) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "marks a field as being a schemaless object. ", - Details: "Schemaless objects are not introspected, so you must provide any type and validation information yourself. One use for this tag is for embedding fields that hold JSONSchema typed objects. Because this field disables all type checking, it is recommended to be used only as a last resort.", + Summary: "marks a field as being a schemaless object.", + Details: "Schemaless objects are not introspected, so you must provide\nany type and validation information yourself. One use for this\ntag is for embedding fields that hold JSONSchema typed objects.\nBecause this field disables all type checking, it is recommended\nto be used only as a last resort.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -373,8 +384,8 @@ func (SkipVersion) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD", DetailedHelp: markers.DetailedHelp{ - Summary: "removes the particular version of the CRD from the CRDs spec. ", - Details: "This is useful if you need to skip generating and listing version entries for 'internal' resource versions, which typically exist if using the Kubernetes upstream conversion-gen tool.", + Summary: "removes the particular version of the CRD from the CRDs spec.", + Details: "This is useful if you need to skip generating and listing version entries\nfor 'internal' resource versions, which typically exist if using the\nKubernetes upstream conversion-gen tool.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -384,8 +395,8 @@ func (StorageVersion) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD", DetailedHelp: markers.DetailedHelp{ - Summary: "marks this version as the \"storage version\" for the CRD for conversion. ", - Details: "When conversion is enabled for a CRD (i.e. it's not a trivial-versions/single-version CRD), one version is set as the \"storage version\" to be stored in etcd. Attempting to store any other version will result in conversion to the storage version via a conversion webhook.", + Summary: "marks this version as the \"storage version\" for the CRD for conversion.", + Details: "When conversion is enabled for a CRD (i.e. it's not a trivial-versions/single-version CRD),\none version is set as the \"storage version\" to be stored in etcd. Attempting to store any\nother version will result in conversion to the storage version via a conversion webhook.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -395,8 +406,8 @@ func (StructType) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD processing", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies the level of atomicity of the struct; i.e. whether each field in the struct is independent of the others, or all fields are treated as a single unit. ", - Details: "Possible values: \n - \"granular\": fields in the struct are independent of each other, and can be manipulated by different actors. This is the default behavior. \n - \"atomic\": all fields are treated as one unit. Any changes have to replace the entire struct.", + Summary: "specifies the level of atomicity of the struct;", + Details: "i.e. whether each field in the struct is independent of the others,\nor all fields are treated as a single unit.\n\n\nPossible values:\n\n\n - \"granular\": fields in the struct are independent of each other,\n and can be manipulated by different actors.\n This is the default behavior.\n\n\n - \"atomic\": all fields are treated as one unit.\n Any changes have to replace the entire struct.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -419,8 +430,8 @@ func (SubresourceScale) Help() *markers.DefinitionHelp { Details: "", }, "SelectorPath": { - Summary: "specifies the jsonpath to the pod label selector field for the scale's status. ", - Details: "The selector field must be the *string* form (serialized form) of a selector. Setting a pod label selector is necessary for your type to work with the HorizontalPodAutoscaler.", + Summary: "specifies the jsonpath to the pod label selector field for the scale's status.", + Details: "The selector field must be the *string* form (serialized form) of a selector.\nSetting a pod label selector is necessary for your type to work with the HorizontalPodAutoscaler.", }, }, } @@ -441,8 +452,8 @@ func (Type) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "overrides the type for this field (which defaults to the equivalent of the Go type). ", - Details: "This generally must be paired with custom serialization. For example, the metav1.Time field would be marked as \"type: string\" and \"format: date-time\".", + Summary: "overrides the type for this field (which defaults to the equivalent of the Go type).", + Details: "This generally must be paired with custom serialization. For example, the\nmetav1.Time field would be marked as \"type: string\" and \"format: date-time\".", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -463,7 +474,7 @@ func (UnservedVersion) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD", DetailedHelp: markers.DetailedHelp{ - Summary: "does not serve this version. ", + Summary: "does not serve this version.", Details: "This is useful if you need to drop support for a version in favor of a newer version.", }, FieldHelp: map[string]markers.DetailedHelp{}, @@ -474,8 +485,8 @@ func (XEmbeddedResource) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "EmbeddedResource marks a fields as an embedded resource with apiVersion, kind and metadata fields. ", - Details: "An embedded resource is a value that has apiVersion, kind and metadata fields. They are validated implicitly according to the semantics of the currently running apiserver. It is not necessary to add any additional schema for these field, yet it is possible. This can be combined with PreserveUnknownFields.", + Summary: "EmbeddedResource marks a fields as an embedded resource with apiVersion, kind and metadata fields.", + Details: "An embedded resource is a value that has apiVersion, kind and metadata fields.\nThey are validated implicitly according to the semantics of the currently\nrunning apiserver. It is not necessary to add any additional schema for these\nfield, yet it is possible. This can be combined with PreserveUnknownFields.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -485,8 +496,8 @@ func (XIntOrString) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "IntOrString marks a fields as an IntOrString. ", - Details: "This is required when applying patterns or other validations to an IntOrString field. Knwon information about the type is applied during the collapse phase and as such is not normally available during marker application.", + Summary: "IntOrString marks a fields as an IntOrString.", + Details: "This is required when applying patterns or other validations to an IntOrString\nfield. Knwon information about the type is applied during the collapse phase\nand as such is not normally available during marker application.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -496,8 +507,8 @@ func (XPreserveUnknownFields) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD processing", DetailedHelp: markers.DetailedHelp{ - Summary: "PreserveUnknownFields stops the apiserver from pruning fields which are not specified. ", - Details: "By default the apiserver drops unknown fields from the request payload during the decoding step. This marker stops the API server from doing so. It affects fields recursively, but switches back to normal pruning behaviour if nested properties or additionalProperties are specified in the schema. This can either be true or undefined. False is forbidden. \n NB: The kubebuilder:validation:XPreserveUnknownFields variant is deprecated in favor of the kubebuilder:pruning:PreserveUnknownFields variant. They function identically.", + Summary: "PreserveUnknownFields stops the apiserver from pruning fields which are not specified.", + Details: "By default the apiserver drops unknown fields from the request payload\nduring the decoding step. This marker stops the API server from doing so.\nIt affects fields recursively, but switches back to normal pruning behaviour\nif nested properties or additionalProperties are specified in the schema.\nThis can either be true or undefined. False\nis forbidden.\n\n\nNB: The kubebuilder:validation:XPreserveUnknownFields variant is deprecated\nin favor of the kubebuilder:pruning:PreserveUnknownFields variant. They function\nidentically.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -507,8 +518,8 @@ func (XValidation) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "CRD validation", DetailedHelp: markers.DetailedHelp{ - Summary: "marks a field as requiring a value for which a given expression evaluates to true. ", - Details: "This marker may be repeated to specify multiple expressions, all of which must evaluate to true.", + Summary: "marks a field as requiring a value for which a given", + Details: "expression evaluates to true.\n\n\nThis marker may be repeated to specify multiple expressions, all of\nwhich must evaluate to true.", }, FieldHelp: map[string]markers.DetailedHelp{ "Rule": { diff --git a/pkg/crd/schema.go b/pkg/crd/schema.go index e76d3ea88..b82dd920e 100644 --- a/pkg/crd/schema.go +++ b/pkg/crd/schema.go @@ -22,6 +22,7 @@ import ( "go/ast" "go/token" "go/types" + "reflect" "strings" apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" @@ -328,6 +329,11 @@ func mapToSchema(ctx *schemaContext, mapType *ast.MapType) *apiext.JSONSchemaPro } } +// fieldScopePropertyName is the name of the property used to sore field scope information. A more +// appropriate solution would be to use a custom extension, but that's not possible yet. +// See: https://github.com/kubernetes/kubernetes/issues/82942 +const fieldScopePropertyName = "x-kubebuilder-field-scopes" + // structToSchema creates a schema for the given struct. Embedded fields are placed in AllOf, // and can be flattened later with a Flattener. func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSONSchemaProps { @@ -341,6 +347,7 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON return props } + var clusterScopedFields, namespaceScopedFields []string for _, field := range ctx.info.Fields { // Skip if the field is not an inline field, ignoreUnexportedFields is true, and the field is not exported if field.Name != "" && ctx.ignoreUnexportedFields && !ast.IsExported(field.Name) { @@ -372,6 +379,30 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON fieldName := jsonOpts[0] inline = inline || fieldName == "" // anonymous fields are inline fields in YAML/JSON + if scope := field.Markers.Get("kubebuilder:field:scope"); scope != nil { + value, ok := scope.(crdmarkers.FieldScope) + if !ok { + ctx.pkg.AddError(loader.ErrFromNode(fmt.Errorf("encountered non-string struct %q field %q scope %s", ctx.info.Name, field.Name, reflect.ValueOf(scope).Type().Name()), field.RawField)) + continue + } + var scope apiext.ResourceScope + switch value { + case "": + scope = apiext.NamespaceScoped + default: + scope = apiext.ResourceScope(value) + } + switch scope { + case apiext.ClusterScoped: + clusterScopedFields = append(clusterScopedFields, fieldName) + case apiext.NamespaceScoped: + namespaceScopedFields = append(namespaceScopedFields, fieldName) + default: + ctx.pkg.AddError(loader.ErrFromNode(fmt.Errorf("invalid struct %q field %q scope %q", ctx.info.Name, field.Name, value), field.RawField)) + continue + } + } + // if no default required mode is set, default to required defaultMode := "required" if ctx.PackageMarkers.Get("kubebuilder:validation:Optional") != nil { @@ -412,6 +443,22 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON props.Properties[fieldName] = *propSchema } + if len(clusterScopedFields) > 0 || len(namespaceScopedFields) > 0 { + props.Properties[fieldScopePropertyName] = apiext.JSONSchemaProps{ + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + string(apiext.ClusterScoped): { + Type: "object", + Required: clusterScopedFields, + }, + string(apiext.NamespaceScoped): { + Type: "object", + Required: namespaceScopedFields, + }, + }, + } + } + return props } diff --git a/pkg/crd/spec.go b/pkg/crd/spec.go index 5fd246c3f..f3ec18ca9 100644 --- a/pkg/crd/spec.go +++ b/pkg/crd/spec.go @@ -17,6 +17,7 @@ package crd import ( "fmt" + "slices" "sort" "strings" @@ -104,6 +105,7 @@ func (p *Parser) NeedCRDFor(groupKind schema.GroupKind, maxDescLen *int) { }, } crd.Spec.Versions = append(crd.Spec.Versions, ver) + } // markers are applied *after* initial generation of objects @@ -130,6 +132,15 @@ func (p *Parser) NeedCRDFor(groupKind schema.GroupKind, maxDescLen *int) { } } + // Apply field-scoped resources. The markers live on the field, not in the top-level CRD, so we + // must apply them manually here. + for versionIndex := range crd.Spec.Versions { + version := &crd.Spec.Versions[versionIndex] + if err := applyFieldScopes(version.Schema.OpenAPIV3Schema, crd.Spec.Scope); err != nil { + packages[0].AddError(fmt.Errorf("CRD for %s was unable to apply field scopes", groupKind)) + } + } + // fix the name if the plural was changed (this is the form the name *has* to take, so no harm in changing it). crd.Name = crd.Spec.Names.Plural + "." + groupKind.Group @@ -176,3 +187,38 @@ func (p *Parser) NeedCRDFor(groupKind schema.GroupKind, maxDescLen *int) { p.CustomResourceDefinitions[groupKind] = crd } + +func applyFieldScopes(props *apiext.JSONSchemaProps, scope apiext.ResourceScope) error { + var removed string + if scope == apiext.NamespaceScoped { + removed = string(apiext.ClusterScoped) + } else if scope == apiext.ClusterScoped { + removed = string(apiext.NamespaceScoped) + } + if err := removeScope(props, removed); err != nil { + return err + } + return nil +} + +func removeScope(props *apiext.JSONSchemaProps, scope string) error { + scopes, ok := props.Properties[fieldScopePropertyName] + if ok { + for _, item := range scopes.Properties[scope].Required { + delete(props.Properties, item) + + index := slices.Index(props.Required, item) + if index == -1 { + continue + } + props.Required = slices.Delete(props.Required, index, index+1) + } + } + delete(props.Properties, fieldScopePropertyName) + + for name, p := range props.Properties { + removeScope(&p, scope) + props.Properties[name] = p + } + return nil +} diff --git a/pkg/crd/spec_test.go b/pkg/crd/spec_test.go new file mode 100644 index 000000000..24b70dc50 --- /dev/null +++ b/pkg/crd/spec_test.go @@ -0,0 +1,225 @@ +/* +Copyright 2019 The Kubernetes Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ +package crd + +import ( + "testing" + + "github.com/google/go-cmp/cmp" + apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" +) + +func TestApplyFieldScopes(t *testing.T) { + testCases := []struct { + desc string + scope apiext.ResourceScope + props *apiext.JSONSchemaProps + expected *apiext.JSONSchemaProps + }{ + { + desc: "cluster-scoped", + scope: apiext.ClusterScoped, + props: &apiext.JSONSchemaProps{ + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "nonScopedRequired": { + Type: "string", + }, + "nonScopedOptional": { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "innerCluster": { + Type: "string", + }, + "innerNamespaced": { + Type: "string", + }, + fieldScopePropertyName: { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + string(apiext.ClusterScoped): { + Type: "object", + Required: []string{"innerCluster"}, + }, + string(apiext.NamespaceScoped): { + Type: "object", + Required: []string{"innerNamespaced"}}, + }, + }, + }, + Required: []string{"innerCluster", "innerNamespaced"}, + }, + "clusterScopedRequired": { + Type: "string", + }, + "clusterScopedOptional": { + Type: "string", + }, + "namespaceScopedRequired": { + Type: "string", + }, + "namespaceScopedOptional": { + Type: "string", + }, + fieldScopePropertyName: { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + string(apiext.ClusterScoped): { + Type: "object", + Required: []string{"clusterScopedRequired", "clusterScopedOptional"}, + }, + string(apiext.NamespaceScoped): { + Type: "object", + Required: []string{"namespaceScopedRequired", "namespaceScopedOptional"}}, + }, + }, + }, + Required: []string{ + "nonScopedRequired", + "clusterScopedRequired", + "namespaceScopedRequired", + }, + }, + expected: &apiext.JSONSchemaProps{ + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "nonScopedRequired": { + Type: "string", + }, + "nonScopedOptional": { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "innerCluster": { + Type: "string", + }, + }, + Required: []string{"innerCluster"}, + }, + "clusterScopedRequired": { + Type: "string", + }, + "clusterScopedOptional": { + Type: "string", + }, + }, + Required: []string{ + "nonScopedRequired", + "clusterScopedRequired", + }, + }, + }, + { + desc: "namespaced", + scope: apiext.NamespaceScoped, + props: &apiext.JSONSchemaProps{ + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "nonScopedRequired": { + Type: "string", + }, + "nonScopedOptional": { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "innerCluster": { + Type: "string", + }, + "innerNamespaced": { + Type: "string", + }, + fieldScopePropertyName: { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + string(apiext.ClusterScoped): { + Type: "object", + Required: []string{"innerCluster"}, + }, + string(apiext.NamespaceScoped): { + Type: "object", + Required: []string{"innerNamespaced"}}, + }, + }, + }, + Required: []string{"innerCluster", "innerNamespaced"}, + }, + "clusterScopedRequired": { + Type: "string", + }, + "clusterScopedOptional": { + Type: "string", + }, + "namespaceScopedRequired": { + Type: "string", + }, + "namespaceScopedOptional": { + Type: "string", + }, + fieldScopePropertyName: { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + string(apiext.ClusterScoped): { + Type: "object", + Required: []string{"clusterScopedRequired", "clusterScopedOptional"}, + }, + string(apiext.NamespaceScoped): { + Type: "object", + Required: []string{"namespaceScopedRequired", "namespaceScopedOptional"}}, + }, + }, + }, + Required: []string{ + "nonScopedRequired", + "clusterScopedRequired", + "namespaceScopedRequired", + }, + }, + expected: &apiext.JSONSchemaProps{ + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "nonScopedRequired": { + Type: "string", + }, + "nonScopedOptional": { + Type: "object", + Properties: map[string]apiext.JSONSchemaProps{ + "innerNamespaced": { + Type: "string", + }, + }, + Required: []string{"innerNamespaced"}, + }, + "namespaceScopedRequired": { + Type: "string", + }, + "namespaceScopedOptional": { + Type: "string", + }, + }, + Required: []string{ + "nonScopedRequired", + "namespaceScopedRequired", + }, + }, + }, + } + for _, tc := range testCases { + t.Run(tc.desc, func(t *testing.T) { + applyFieldScopes(tc.props, tc.scope) + if diff := cmp.Diff(tc.props, tc.expected); diff != "" { + t.Errorf("invalid field scopes (-want +got):\n%s", diff) + } + }) + } +} diff --git a/pkg/crd/testdata/gen/scope/scope.example.com_clusterfoos.yaml b/pkg/crd/testdata/gen/scope/scope.example.com_clusterfoos.yaml new file mode 100644 index 000000000..2685f5035 --- /dev/null +++ b/pkg/crd/testdata/gen/scope/scope.example.com_clusterfoos.yaml @@ -0,0 +1,52 @@ +--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + controller-gen.kubebuilder.io/version: (devel) + name: clusterfoos.scope.example.com +spec: + group: scope.example.com + names: + kind: ClusterFoo + listKind: ClusterFooList + plural: clusterfoos + singular: clusterfoo + scope: Cluster + versions: + - name: scope + schema: + openAPIV3Schema: + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + properties: + alwaysExists: + description: This field appears regardless of scope. + type: string + existsInCluster: + description: This field only appears for cluster-scoped objects. + type: string + required: + - alwaysExists + - existsInCluster + type: object + type: object + served: true + storage: true diff --git a/pkg/crd/testdata/gen/scope/scope.example.com_namespacedfoos.yaml b/pkg/crd/testdata/gen/scope/scope.example.com_namespacedfoos.yaml new file mode 100644 index 000000000..697ed0f9b --- /dev/null +++ b/pkg/crd/testdata/gen/scope/scope.example.com_namespacedfoos.yaml @@ -0,0 +1,52 @@ +--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + controller-gen.kubebuilder.io/version: (devel) + name: namespacedfoos.scope.example.com +spec: + group: scope.example.com + names: + kind: NamespacedFoo + listKind: NamespacedFooList + plural: namespacedfoos + singular: namespacedfoo + scope: Namespaced + versions: + - name: scope + schema: + openAPIV3Schema: + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + properties: + alwaysExists: + description: This field appears regardless of scope. + type: string + existsInNamespaced: + description: This field only appears for namespace-scoped objects. + type: string + required: + - alwaysExists + - existsInNamespaced + type: object + type: object + served: true + storage: true diff --git a/pkg/crd/testdata/gen/scope/scope_types.go b/pkg/crd/testdata/gen/scope/scope_types.go new file mode 100644 index 000000000..defdacc0e --- /dev/null +++ b/pkg/crd/testdata/gen/scope/scope_types.go @@ -0,0 +1,47 @@ +/* + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +//go:generate ../../../../../.run-controller-gen.sh crd:crdVersions=v1 paths=. output:dir=. + +// +groupName=scope.example.com +package scope + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +type ScopeSpec struct { + // This field appears regardless of scope. + AlwaysExists string `json:"alwaysExists"` + // This field only appears for cluster-scoped objects. + // +kubebuilder:field:scope=Cluster + ExistsInCluster string `json:"existsInCluster"` + // This field only appears for namespace-scoped objects. + // +kubebuilder:field:scope=Namespaced + ExistsInNamespaced string `json:"existsInNamespaced"` +} + +type NamespacedFoo struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + Spec ScopeSpec `json:"spec,omitempty"` +} + +// +kubebuilder:resource:scope=Cluster +type ClusterFoo struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + Spec ScopeSpec `json:"spec,omitempty"` +} diff --git a/pkg/crd/zz_generated.markerhelp.go b/pkg/crd/zz_generated.markerhelp.go index 68b7619ad..f28df829c 100644 --- a/pkg/crd/zz_generated.markerhelp.go +++ b/pkg/crd/zz_generated.markerhelp.go @@ -33,20 +33,20 @@ func (Generator) Help() *markers.DefinitionHelp { }, FieldHelp: map[string]markers.DetailedHelp{ "IgnoreUnexportedFields": { - Summary: "indicates that we should skip unexported fields. ", + Summary: "indicates that we should skip unexported fields.", Details: "Left unspecified, the default is false.", }, "AllowDangerousTypes": { - Summary: "allows types which are usually omitted from CRD generation because they are not recommended. ", - Details: "Currently the following additional types are allowed when this is true: float32 float64 \n Left unspecified, the default is false", + Summary: "allows types which are usually omitted from CRD generation", + Details: "because they are not recommended.\n\n\nCurrently the following additional types are allowed when this is true:\nfloat32\nfloat64\n\n\nLeft unspecified, the default is false", }, "MaxDescLen": { - Summary: "specifies the maximum description length for fields in CRD's OpenAPI schema. ", - Details: "0 indicates drop the description for all fields completely. n indicates limit the description to at most n characters and truncate the description to closest sentence boundary if it exceeds n characters.", + Summary: "specifies the maximum description length for fields in CRD's OpenAPI schema.", + Details: "0 indicates drop the description for all fields completely.\nn indicates limit the description to at most n characters and truncate the description to\nclosest sentence boundary if it exceeds n characters.", }, "CRDVersions": { - Summary: "specifies the target API versions of the CRD type itself to generate. Defaults to v1. ", - Details: "Currently, the only supported value is v1. \n The first version listed will be assumed to be the \"default\" version and will not get a version suffix in the output filename. \n You'll need to use \"v1\" to get support for features like defaulting, along with an API server that supports it (Kubernetes 1.16+).", + Summary: "specifies the target API versions of the CRD type itself to", + Details: "generate. Defaults to v1.\n\n\nCurrently, the only supported value is v1.\n\n\nThe first version listed will be assumed to be the \"default\" version and\nwill not get a version suffix in the output filename.\n\n\nYou'll need to use \"v1\" to get support for features like defaulting,\nalong with an API server that supports it (Kubernetes 1.16+).", }, "GenerateEmbeddedObjectMeta": { Summary: "specifies if any embedded ObjectMeta in the CRD should be generated", diff --git a/pkg/deepcopy/zz_generated.markerhelp.go b/pkg/deepcopy/zz_generated.markerhelp.go index 55df3bfab..081c06551 100644 --- a/pkg/deepcopy/zz_generated.markerhelp.go +++ b/pkg/deepcopy/zz_generated.markerhelp.go @@ -28,8 +28,8 @@ func (Generator) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "generates code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.", - Details: "", + Summary: "generates code containing DeepCopy, DeepCopyInto, and", + Details: "DeepCopyObject method implementations.", }, FieldHelp: map[string]markers.DetailedHelp{ "HeaderFile": { diff --git a/pkg/genall/zz_generated.markerhelp.go b/pkg/genall/zz_generated.markerhelp.go index 6f58013b2..998061b9b 100644 --- a/pkg/genall/zz_generated.markerhelp.go +++ b/pkg/genall/zz_generated.markerhelp.go @@ -28,7 +28,7 @@ func (InputPaths) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "represents paths and go-style path patterns to use as package roots. ", + Summary: "represents paths and go-style path patterns to use as package roots.", Details: "Multiple paths can be specified using \"{path1, path2, path3}\".", }, FieldHelp: map[string]markers.DetailedHelp{}, @@ -39,8 +39,8 @@ func (OutputArtifacts) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "outputs artifacts to different locations, depending on whether they're package-associated or not. ", - Details: "Non-package associated artifacts are output to the Config directory, while package-associated ones are output to their package's source files' directory, unless an alternate path is specified in Code.", + Summary: "outputs artifacts to different locations, depending on", + Details: "whether they're package-associated or not.\n\n\nNon-package associated artifacts\nare output to the Config directory, while package-associated ones are output\nto their package's source files' directory, unless an alternate path is\nspecified in Code.", }, FieldHelp: map[string]markers.DetailedHelp{ "Config": { @@ -59,8 +59,8 @@ func (OutputToDirectory) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "outputs each artifact to the given directory, regardless of if it's package-associated or not.", - Details: "", + Summary: "outputs each artifact to the given directory, regardless", + Details: "of if it's package-associated or not.", }, FieldHelp: map[string]markers.DetailedHelp{}, } @@ -81,7 +81,7 @@ func (outputToStdout) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "outputs everything to standard-out, with no separation. ", + Summary: "outputs everything to standard-out, with no separation.", Details: "Generally useful for single-artifact outputs.", }, FieldHelp: map[string]markers.DetailedHelp{}, diff --git a/pkg/rbac/zz_generated.markerhelp.go b/pkg/rbac/zz_generated.markerhelp.go index 5a83941c3..20c707b1d 100644 --- a/pkg/rbac/zz_generated.markerhelp.go +++ b/pkg/rbac/zz_generated.markerhelp.go @@ -65,8 +65,8 @@ func (Rule) Help() *markers.DefinitionHelp { Details: "", }, "ResourceNames": { - Summary: "specifies the names of the API resources that this rule encompasses. ", - Details: "Create requests cannot be restricted by resourcename, as the object's name is not known at authorization time.", + Summary: "specifies the names of the API resources that this rule encompasses.", + Details: "Create requests cannot be restricted by resourcename, as the object's name\nis not known at authorization time.", }, "Verbs": { Summary: "specifies the (lowercase) kubernetes API verbs that this rule encompasses.", @@ -77,8 +77,8 @@ func (Rule) Help() *markers.DefinitionHelp { Details: "", }, "Namespace": { - Summary: "specifies the scope of the Rule. If not set, the Rule belongs to the generated ClusterRole. If set, the Rule belongs to a Role, whose namespace is specified by this field.", - Details: "", + Summary: "specifies the scope of the Rule.", + Details: "If not set, the Rule belongs to the generated ClusterRole.\nIf set, the Rule belongs to a Role, whose namespace is specified by this field.", }, }, } diff --git a/pkg/schemapatcher/zz_generated.markerhelp.go b/pkg/schemapatcher/zz_generated.markerhelp.go index 6e1d5a18c..db4cdb074 100644 --- a/pkg/schemapatcher/zz_generated.markerhelp.go +++ b/pkg/schemapatcher/zz_generated.markerhelp.go @@ -28,8 +28,8 @@ func (Generator) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "", DetailedHelp: markers.DetailedHelp{ - Summary: "patches existing CRDs with new schemata. ", - Details: "It will generate output for each \"CRD Version\" (API version of the CRD type itself) , e.g. apiextensions/v1) available.", + Summary: "patches existing CRDs with new schemata.", + Details: "It will generate output for each \"CRD Version\" (API version of the CRD type\nitself) , e.g. apiextensions/v1) available.", }, FieldHelp: map[string]markers.DetailedHelp{ "ManifestsPath": { @@ -37,8 +37,8 @@ func (Generator) Help() *markers.DefinitionHelp { Details: "", }, "MaxDescLen": { - Summary: "specifies the maximum description length for fields in CRD's OpenAPI schema. ", - Details: "0 indicates drop the description for all fields completely. n indicates limit the description to at most n characters and truncate the description to closest sentence boundary if it exceeds n characters.", + Summary: "specifies the maximum description length for fields in CRD's OpenAPI schema.", + Details: "0 indicates drop the description for all fields completely.\nn indicates limit the description to at most n characters and truncate the description to\nclosest sentence boundary if it exceeds n characters.", }, "GenerateEmbeddedObjectMeta": { Summary: "specifies if any embedded ObjectMeta in the CRD should be generated", diff --git a/pkg/webhook/zz_generated.markerhelp.go b/pkg/webhook/zz_generated.markerhelp.go index 4dae86046..d40bcc81f 100644 --- a/pkg/webhook/zz_generated.markerhelp.go +++ b/pkg/webhook/zz_generated.markerhelp.go @@ -28,29 +28,29 @@ func (Config) Help() *markers.DefinitionHelp { return &markers.DefinitionHelp{ Category: "Webhook", DetailedHelp: markers.DetailedHelp{ - Summary: "specifies how a webhook should be served. ", - Details: "It specifies only the details that are intrinsic to the application serving it (e.g. the resources it can handle, or the path it serves on).", + Summary: "specifies how a webhook should be served.", + Details: "It specifies only the details that are intrinsic to the application serving\nit (e.g. the resources it can handle, or the path it serves on).", }, FieldHelp: map[string]markers.DetailedHelp{ "Mutating": { - Summary: "marks this as a mutating webhook (it's validating only if false) ", - Details: "Mutating webhooks are allowed to change the object in their response, and are called *before* all validating webhooks. Mutating webhooks may choose to reject an object, similarly to a validating webhook.", + Summary: "marks this as a mutating webhook (it's validating only if false)", + Details: "Mutating webhooks are allowed to change the object in their response,\nand are called *before* all validating webhooks. Mutating webhooks may\nchoose to reject an object, similarly to a validating webhook.", }, "FailurePolicy": { - Summary: "specifies what should happen if the API server cannot reach the webhook. ", - Details: "It may be either \"ignore\" (to skip the webhook and continue on) or \"fail\" (to reject the object in question).", + Summary: "specifies what should happen if the API server cannot reach the webhook.", + Details: "It may be either \"ignore\" (to skip the webhook and continue on) or \"fail\" (to reject\nthe object in question).", }, "MatchPolicy": { - Summary: "defines how the \"rules\" list is used to match incoming requests. Allowed values are \"Exact\" (match only if it exactly matches the specified rule) or \"Equivalent\" (match a request if it modifies a resource listed in rules, even via another API group or version).", - Details: "", + Summary: "defines how the \"rules\" list is used to match incoming requests.", + Details: "Allowed values are \"Exact\" (match only if it exactly matches the specified rule)\nor \"Equivalent\" (match a request if it modifies a resource listed in rules, even via another API group or version).", }, "SideEffects": { - Summary: "specify whether calling the webhook will have side effects. This has an impact on dry runs and `kubectl diff`: if the sideEffect is \"Unknown\" (the default) or \"Some\", then the API server will not call the webhook on a dry-run request and fails instead. If the value is \"None\", then the webhook has no side effects and the API server will call it on dry-run. If the value is \"NoneOnDryRun\", then the webhook is responsible for inspecting the \"dryRun\" property of the AdmissionReview sent in the request, and avoiding side effects if that value is \"true.\"", - Details: "", + Summary: "specify whether calling the webhook will have side effects.", + Details: "This has an impact on dry runs and `kubectl diff`: if the sideEffect is \"Unknown\" (the default) or \"Some\", then\nthe API server will not call the webhook on a dry-run request and fails instead.\nIf the value is \"None\", then the webhook has no side effects and the API server will call it on dry-run.\nIf the value is \"NoneOnDryRun\", then the webhook is responsible for inspecting the \"dryRun\" property of the\nAdmissionReview sent in the request, and avoiding side effects if that value is \"true.\"", }, "TimeoutSeconds": { - Summary: "allows configuring how long the API server should wait for a webhook to respond before treating the call as a failure. If the timeout expires before the webhook responds, the webhook call will be ignored or the API call will be rejected based on the failure policy. The timeout value must be between 1 and 30 seconds. The timeout for an admission webhook defaults to 10 seconds.", - Details: "", + Summary: "allows configuring how long the API server should wait for a webhook to respond before treating the call as a failure.", + Details: "If the timeout expires before the webhook responds, the webhook call will be ignored or the API call will be rejected based on the failure policy.\nThe timeout value must be between 1 and 30 seconds.\nThe timeout for an admission webhook defaults to 10 seconds.", }, "Groups": { Summary: "specifies the API groups that this webhook receives requests for.", @@ -61,8 +61,8 @@ func (Config) Help() *markers.DefinitionHelp { Details: "", }, "Verbs": { - Summary: "specifies the Kubernetes API verbs that this webhook receives requests for. ", - Details: "Only modification-like verbs may be specified. May be \"create\", \"update\", \"delete\", \"connect\", or \"*\" (for all).", + Summary: "specifies the Kubernetes API verbs that this webhook receives requests for.", + Details: "Only modification-like verbs may be specified.\nMay be \"create\", \"update\", \"delete\", \"connect\", or \"*\" (for all).", }, "Versions": { Summary: "specifies the API versions that this webhook receives requests for.", @@ -73,20 +73,24 @@ func (Config) Help() *markers.DefinitionHelp { Details: "", }, "Path": { - Summary: "specifies that path that the API server should connect to this webhook on. Must be prefixed with a '/validate-' or '/mutate-' depending on the type, and followed by $GROUP-$VERSION-$KIND where all values are lower-cased and the periods in the group are substituted for hyphens. For example, a validating webhook path for type batch.tutorial.kubebuilder.io/v1,Kind=CronJob would be /validate-batch-tutorial-kubebuilder-io-v1-cronjob", - Details: "", + Summary: "specifies that path that the API server should connect to this webhook on. Must be", + Details: "prefixed with a '/validate-' or '/mutate-' depending on the type, and followed by\n$GROUP-$VERSION-$KIND where all values are lower-cased and the periods in the group\nare substituted for hyphens. For example, a validating webhook path for type\nbatch.tutorial.kubebuilder.io/v1,Kind=CronJob would be\n/validate-batch-tutorial-kubebuilder-io-v1-cronjob", }, "WebhookVersions": { - Summary: "specifies the target API versions of the {Mutating,Validating}WebhookConfiguration objects itself to generate. The only supported value is v1. Defaults to v1.", - Details: "", + Summary: "specifies the target API versions of the {Mutating,Validating}WebhookConfiguration objects", + Details: "itself to generate. The only supported value is v1. Defaults to v1.", }, "AdmissionReviewVersions": { - Summary: "is an ordered list of preferred `AdmissionReview` versions the Webhook expects.", - Details: "", + Summary: "is an ordered list of preferred `AdmissionReview`", + Details: "versions the Webhook expects.", }, "ReinvocationPolicy": { - Summary: "allows mutating webhooks to request reinvocation after other mutations ", - Details: "To allow mutating admission plugins to observe changes made by other plugins, built-in mutating admission plugins are re-run if a mutating webhook modifies an object, and mutating webhooks can specify a reinvocationPolicy to control whether they are reinvoked as well.", + Summary: "allows mutating webhooks to request reinvocation after other mutations", + Details: "To allow mutating admission plugins to observe changes made by other plugins,\nbuilt-in mutating admission plugins are re-run if a mutating webhook modifies\nan object, and mutating webhooks can specify a reinvocationPolicy to control\nwhether they are reinvoked as well.", + }, + "URL": { + Summary: "allows mutating webhooks configuration to specify an external URL when generating", + Details: "the manifests, instead of using the internal service communication. Should be in format of\nhttps://address:port/path\nWhen this option is specified, the serviceConfig.Service is removed from webhook the manifest.\nThe URL configuration should be between quotes.\n`url` cannot be specified when `path` is specified.", }, }, }