internal/generate: align CRD generator with controller-gen (#2201)

This commit aligns the CRD generator with controller-gen's.

* cmd/operator-sdk: replace CRD scaffold with CRD generator

* internal/generate/gen: Config configures Generator's using common
data they may find useful. Config should be passed to a Generator's
Constructor. See internal/generate/crd.NewCRDGo for an example

* internal/generate/crd: CRD generator for Go and non-Go operators

* test/test-framework: update operator types with storageversion
annotations

* internal/util/fileutil: DotPath prepends "./" or ".\" to a local
path, depending on OS

* doc: discuss storage versions in CRDs

Author: Eric Stroczynski

cmd/operator-sdk/add/api.go

@@ -124,7 +124,6 @@ func apiRun(cmd *cobra.Command, args []string) error {
 		&scaffold.Register{Resource: r},
 		&scaffold.Doc{Resource: r},
 		&scaffold.CR{Resource: r},
-		&scaffold.CRD{Resource: r, IsOperatorGo: projutil.IsOperatorGo()},
 	)
 	if err != nil {
 		return fmt.Errorf("api scaffold failed: (%v)", err)

cmd/operator-sdk/add/crd.go

@@ -20,6 +20,8 @@ import (
 	"path/filepath"
 	"strings"
 
+	gencrd "github.com/operator-framework/operator-sdk/internal/generate/crd"
+	gen "github.com/operator-framework/operator-sdk/internal/generate/gen"
 	"github.com/operator-framework/operator-sdk/internal/scaffold"
 	"github.com/operator-framework/operator-sdk/internal/scaffold/input"
 	"github.com/operator-framework/operator-sdk/internal/util/projutil"
@@ -74,7 +76,7 @@ func crdFunc(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	log.Infof("Generating Custom Resource Definition (CRD) version %s for kind %s.", apiVersion, kind)
+	log.Infof("Generating CustomResourceDefinition (CRD) version %s for kind %s.", apiVersion, kind)
 
 	// generate CR/CRD file
 	resource, err := scaffold.NewResource(apiVersion, kind)
@@ -84,11 +86,6 @@ func crdFunc(cmd *cobra.Command, args []string) error {
 
 	s := scaffold.Scaffold{}
 	err = s.Execute(cfg,
-		&scaffold.CRD{
-			Input:        input.Input{IfExistsAction: input.Skip},
-			Resource:     resource,
-			IsOperatorGo: projutil.IsOperatorGo(),
-		},
 		&scaffold.CR{
 			Input:    input.Input{IfExistsAction: input.Skip},
 			Resource: resource,
@@ -98,6 +95,14 @@ func crdFunc(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("crd scaffold failed: (%v)", err)
 	}
 
+	// This command does not consider an APIs dir. Instead it adds a plain CRD
+	// for the provided resource. We can use NewCRDNonGo to get this behavior.
+	gcfg := gen.Config{}
+	crd := gencrd.NewCRDNonGo(gcfg, *resource)
+	if err := crd.Generate(); err != nil {
+		return fmt.Errorf("error generating CRD for %s: %w", resource, err)
+	}
+
 	// update deploy/role.yaml for the given resource r.
 	if err := scaffold.UpdateRoleForResource(resource, cfg.AbsProjectPath); err != nil {
 		return fmt.Errorf("failed to update the RBAC manifest for the resource (%v, %v): (%v)", resource.APIVersion, resource.Kind, err)

cmd/operator-sdk/generate/crds.go

@@ -18,6 +18,8 @@ import (
 	"fmt"
 
 	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/internal/genutil"
+
+	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
@@ -45,5 +47,10 @@ func crdsFunc(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("command %s doesn't accept any arguments", cmd.CommandPath())
 	}
 
-	return genutil.CRDGen()
+	// Skip usage printing on error, since this command will never fail from
+	// improper CLI usage.
+	if err := genutil.CRDGen(); err != nil {
+		log.Fatal(err)
+	}
+	return nil
 }

cmd/operator-sdk/internal/genutil/crds.go

@@ -16,12 +16,10 @@ package genutil
 
 import (
 	"fmt"
-	"path/filepath"
-	"strings"
 
+	gencrd "github.com/operator-framework/operator-sdk/internal/generate/crd"
+	gen "github.com/operator-framework/operator-sdk/internal/generate/gen"
 	"github.com/operator-framework/operator-sdk/internal/scaffold"
-	"github.com/operator-framework/operator-sdk/internal/scaffold/input"
-	"github.com/operator-framework/operator-sdk/internal/util/k8sutil"
 	"github.com/operator-framework/operator-sdk/internal/util/projutil"
 
 	log "github.com/sirupsen/logrus"
@@ -31,49 +29,12 @@ import (
 func CRDGen() error {
 	projutil.MustInProjectRoot()
 
-	absProjectPath := projutil.MustGetwd()
-	repoPkg := projutil.GetGoPkg()
+	log.Info("Running CRD generator.")
 
-	gvMap, err := k8sutil.ParseGroupSubpackages(scaffold.ApisDir)
-	if err != nil {
-		return fmt.Errorf("failed to parse group versions: (%v)", err)
-	}
-	gvb := &strings.Builder{}
-	for g, vs := range gvMap {
-		gvb.WriteString(fmt.Sprintf("%s:%v, ", g, vs))
-	}
-
-	log.Infof("Running CRD generation for Custom Resource group versions: [%v]\n", gvb.String())
-
-	s := &scaffold.Scaffold{}
-	cfg := &input.Config{
-		Repo:           repoPkg,
-		AbsProjectPath: absProjectPath,
-		ProjectName:    filepath.Base(absProjectPath),
-	}
-	crds, err := k8sutil.GetCRDs(scaffold.CRDsDir)
-	if err != nil {
-		return err
-	}
-	for _, crd := range crds {
-		g, v, k := crd.Spec.Group, crd.Spec.Version, crd.Spec.Names.Kind
-		if v == "" {
-			if len(crd.Spec.Versions) != 0 {
-				v = crd.Spec.Versions[0].Name
-			} else {
-				return fmt.Errorf("crd of group %s kind %s has no version", g, k)
-			}
-		}
-		r, err := scaffold.NewResource(g+"/"+v, k)
-		if err != nil {
-			return err
-		}
-		err = s.Execute(cfg,
-			&scaffold.CRD{Resource: r, IsOperatorGo: projutil.IsOperatorGo()},
-		)
-		if err != nil {
-			return err
-		}
+	cfg := gen.Config{}
+	crd := gencrd.NewCRDGo(cfg)
+	if err := crd.Generate(); err != nil {
+		return fmt.Errorf("error generating CRDs from APIs in %s: %w", scaffold.ApisDir, err)
 	}
 
 	log.Info("CRD generation complete.")

cmd/operator-sdk/new/cmd.go

@@ -22,6 +22,8 @@ import (
 	"path/filepath"
 	"strings"
 
+	gencrd "github.com/operator-framework/operator-sdk/internal/generate/crd"
+	gen "github.com/operator-framework/operator-sdk/internal/generate/gen"
 	"github.com/operator-framework/operator-sdk/internal/scaffold"
 	"github.com/operator-framework/operator-sdk/internal/scaffold/ansible"
 	"github.com/operator-framework/operator-sdk/internal/scaffold/helm"
@@ -231,7 +233,6 @@ func doAnsibleScaffold() error {
 		&scaffold.ServiceAccount{},
 		&scaffold.Role{},
 		&scaffold.RoleBinding{},
-		&scaffold.CRD{Resource: resource},
 		&scaffold.CR{Resource: resource},
 		&ansible.BuildDockerfile{GeneratePlaybook: generatePlaybook},
 		&ansible.RolesReadme{Resource: *resource},
@@ -267,6 +268,10 @@ func doAnsibleScaffold() error {
 		return fmt.Errorf("new ansible scaffold failed: (%v)", err)
 	}
 
+	if err = generateCRDNonGo(projectName, *resource); err != nil {
+		return err
+	}
+
 	// Remove placeholders from empty directories
 	err = os.Remove(filepath.Join(s.AbsProjectPath, roleFiles.Path))
 	if err != nil {
@@ -343,7 +348,6 @@ func doHelmScaffold() error {
 		&roleScaffold,
 		&scaffold.RoleBinding{IsClusterScoped: roleScaffold.IsClusterScoped},
 		&helm.Operator{},
-		&scaffold.CRD{Resource: resource},
 		&scaffold.CR{
 			Resource: resource,
 			Spec:     crSpec,
@@ -353,12 +357,30 @@ func doHelmScaffold() error {
 		return fmt.Errorf("new helm scaffold failed: %w", err)
 	}
 
+	if err = generateCRDNonGo(projectName, *resource); err != nil {
+		return err
+	}
+
 	if err := scaffold.UpdateRoleForResource(resource, cfg.AbsProjectPath); err != nil {
 		return fmt.Errorf("failed to update the RBAC manifest for resource (%v, %v): %w", resource.APIVersion, resource.Kind, err)
 	}
 	return nil
 }
 
+func generateCRDNonGo(projectName string, resource scaffold.Resource) error {
+	crdsDir := filepath.Join(projectName, scaffold.CRDsDir)
+	gcfg := gen.Config{
+		Inputs:    map[string]string{gencrd.CRDsDirKey: crdsDir},
+		OutputDir: crdsDir,
+	}
+	crd := gencrd.NewCRDNonGo(gcfg, resource)
+	if err := crd.Generate(); err != nil {
+		return fmt.Errorf("error generating CRD for %s: %w", resource, err)
+	}
+	log.Info("Generated CustomResourceDefinition manifests.")
+	return nil
+}
+
 func verifyFlags() error {
 	if operatorType != projutil.OperatorTypeGo && operatorType != projutil.OperatorTypeAnsible && operatorType != projutil.OperatorTypeHelm {
 		return errors.Wrap(projutil.ErrUnknownOperatorType{Type: operatorType}, "value of --type can only be `go`, `ansible`, or `helm`")

doc/user-guide.md

@@ -96,7 +96,7 @@ type MemcachedSpec struct {
 	Size int32 `json:"size"`
 }
 type MemcachedStatus struct {
-	// Nodes are the names of the memcached pods 
+	// Nodes are the names of the memcached pods
 	Nodes []string `json:"nodes"`
 }
 ```
@@ -107,7 +107,22 @@ After modifying the `*_types.go` file always run the following command to update
 $ operator-sdk generate k8s
 ```
 
-### OpenAPI validation
+### Updating CRD manifests
+
+Now that `MemcachedSpec` and `MemcachedStatus` have fields and possibly annotations, the CRD corresponding to the API's group and kind must be updated. To do so, run the following command:
+
+```console
+$ operator-sdk generate crds
+```
+
+**Notes:**
+- - Your CRD *must* specify exactly one [storage version][crd-storage-version]. Use the `+kubebuilder:storageversion` [marker][crd-markers] to indicate the GVK that should be used to store data by the API server. This marker should be in a comment above your `Memcached` type.
+
+[crd-storage-version]:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects
+[crd-markers]:https://book.kubebuilder.io/reference/markers/crd.html
+[api-rules]: https://github.com/kubernetes/kubernetes/tree/36981002246682ed7dc4de54ccc2a96c1a0cbbdb/api/api-rules
+
+#### OpenAPI validation
 
 OpenAPIv3 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached Custom Resource when it is created or updated.
 
@@ -146,7 +161,6 @@ To learn more about OpenAPI v3.0 validation schemas in Custom Resource Definitio
 [generating-crd]: https://book.kubebuilder.io/reference/generating-crd.html
 [markers]: https://book.kubebuilder.io/reference/markers.html
 [crd-markers]: https://book.kubebuilder.io/reference/markers/crd-validation.html
-[api-rules]: https://github.com/kubernetes/kubernetes/tree/36981002246682ed7dc4de54ccc2a96c1a0cbbdb/api/api-rules
 
 ## Add a new Controller
 
@@ -679,4 +693,4 @@ When the operator is not running in a cluster, the Manager will return an error
 [result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result
 [metrics_doc]: ./user/metrics/README.md
 [quay_link]: https://quay.io
-[multi-namespaced-cache-builder]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder
+[multi-namespaced-cache-builder]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder

doc/user/migrating-existing-apis.md

@@ -207,13 +207,12 @@ This command will automatically update all CRD manifests.
 
 #### CRD Versioning
 
-<!-- TODO: change SDK version to the last release before controller-tools v0.2.0 refactor -->
+Kubernetes 1.11+ supports CRD [`spec.versions`][crd-versions] and `spec.version` is [deprecated][crd-version-deprecated] as of Kubernetes 1.12. SDK versions `v0.10.x` and below leverage [`[email protected]`][controller-tools]' CRD generator which generates a now-deprecated `spec.version` value based on the version contained in an API's import path. Names of CRD manifest files generated by those SDK versions contain the `spec.version`, i.e. one CRD manifest is created *per version in a group* with the file name format `<group>_<version>_<kind>_crd.yaml`. SDK versions `v0.11+` use `controller-tools@v0.2.x`, which generates `spec.versions` but not `spec.version` by default, and use the file name format `<full_group>_<resource>_crd.yaml`.
 
-Kubernetes 1.11+ supports CRD [`spec.versions`][crd-versions] and `spec.version` is [deprecated][crd-version-deprecated] as of Kubernetes 1.12. SDK versions `v0.10.x` and below leverage [`controller-tools`][controller-tools]' CRD generator `v0.1.x` which generates a now-deprecated `spec.version` value based on the version contained in an APIs import path. Names of CRD manifest files generated by those SDK versions contain the `spec.version`, i.e. one CRD manifest is created *per version in a group* with the form `<group>_<version>_<kind>_crd.yaml`. The SDK is in the process of upgrading to `controller-tools` `v0.2.x`, which generates `spec.versions` but not `spec.version` by default. Once the upgrade is complete, future SDK versions will place all versions in a group in `spec.versions`. File names will then have the format `<full_group>_<resource>_crd.yaml`.
-
-**Note**: `<full group>` is the full group name of your CRD while `<group>` is the last subdomain of `<full group>`, ex. `foo.bar.com` vs `foo`. `<resource>` is the plural lower-case of CRD `Kind` specified at `spec.names.plural`.
-
-**Note:** If your operator does not have custom data manually added to its CRD's, you can skip to the [following section](#golang-api-migrations-types-and-commonalities); `operator-sdk generate crds` will handle CRD updates in that case.
+**Notes:**
+- `<full group>` is the full group name of your CRD while `<group>` is the last subdomain of `<full group>`, ex. `foo.bar.com` vs `foo`. `<resource>` is the plural lower-case of CRD `Kind` specified at `spec.names.plural`.
+- Your CRD *must* specify exactly one [storage version][crd-storage-version]. Use the `+kubebuilder:storageversion` [marker][crd-markers] to indicate the GVK that should be used to store data by the API server. This marker should be in a comment above your `CatalogSourceConfig` type.
+- If your operator does not have custom data manually added to its CRD's, you can skip to the [following section](#golang-api-migrations-types-and-commonalities); `operator-sdk generate crds` will handle CRD updates in that case.
 
 Upgrading from `spec.version` to `spec.versions` will be demonstrated using the following CRD manifest example:
 
@@ -400,6 +399,8 @@ TODO
 [k8s-versioning]:https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning
 [deepcopy-gen]:https://godoc.org/k8s.io/gengo/examples/deepcopy-gen
 [client-gen]:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/generating-clientset.md
+[crd-storage-version]:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects
+[crd-markers]:https://book.kubebuilder.io/reference/markers/crd.html
 [controller-tools]:https://github.com/kubernetes-sigs/controller-tools
 [crd-versions]:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/
 [crd-conv]:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/#webhook-conversion