fix: support for external types with optional domain fields

In certain scenarios, domains must be empty, such as when scaffolding APIs for CertManager. In other cases, both group and domain must be specified to generate the correct scaffolds.

This commit removes the check that enforces both fields to be non-empty, and properly documents and tests these scenarios in the testdata.

Author: camilamacedo86

docs/book/src/reference/using_an_external_resource.md

@@ -28,22 +28,22 @@ kubebuilder create api --group <theirgroup> --version <theirversion> --kind <the
 For example, if you're managing Certificates from Cert Manager:
 
 ```shell
-kubebuilder create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=cert-manager.io
+kubebuilder create api --group cert-manager.io --version v1 --kind Certificate --controller=true --resource=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
 ```
 
-See the RBAC markers generated for this:
+See the RBAC [markers][markers-rbac] generated for this:
 
 ```go
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates/status,verbs=get;update;patch
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates/finalizers,verbs=update
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates/finalizers,verbs=update
 ```
 
 Also, the RBAC role:
 
 ```ymal
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates
   verbs:
@@ -55,7 +55,7 @@ Also, the RBAC role:
   - update
   - watch
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates/finalizers
   verbs:
@@ -70,6 +70,50 @@ Also, the RBAC role:
   - update
 ```
 
+However, if we are scaffolding an API that has a domain defined, we need to explicitly set the domain using the `--external-api-domain`
+flag in the Kubebuilder command. For example, if we want to scaffold a controller for the ServiceMonitor
+API provided and defined in the [Prometheus Operator][prometheus-operator], we would scaffold it as follows:
+
+```shell
+kubebuilder create api --group "monitoring" --version v1 --kind ServiceMonitor --controller=true --resource=false --make=false --external-api-path=github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1 --external-api-domain=coreos.com
+```
+
+In this case:
+
+- The **group** is `"monitoring"`.
+- The **domain** is `"coreos.com"`, as indicated by `--external-api-domain=coreos.com`.
+
+This structure ensures that the API group and domain are correctly applied to generate the
+[markers][markers-rbac] and scaffolds accordingly.
+
+In this scenario, the [markers][markers-rbac] scaffolded in the controller will look like this:
+
+```go
+// +kubebuilder:rbac:groups=monitoring.coreos.com,resources=servicemonitors,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=monitoring.coreos.com,resources=servicemonitors/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=monitoring.coreos.com,resources=servicemonitors/finalizers,verbs=update
+
+```
+
+These [markers][markers-rbac] will generate the corresponding permissions under config/rbac/, such as:
+
+```ymal
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/finalizers
+  verbs:
+  - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/status
+  verbs:
+  - get
+  - patch
+  - update
+```
+
 This scaffolds a controller for the external type but skips creating new resource
 definitions since the type is defined in an external project.
 
@@ -118,15 +162,15 @@ For instance, to create a controller to manage Deployment the command would be l
 create api --group apps --version v1 --kind Deployment --controller=true --resource=false
 ```
 
-See the RBAC markers generated for this:
+See the RBAC [markers][markers-rbac] generated for this:
 
 ```go
 // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=apps,resources=deployments/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=apps,resources=deployments/finalizers,verbs=update
 ```
 
-Also, the RBAC for the above markers:
+Also, the RBAC for the above [markers][markers-rbac]:
 
 ```yaml
 - apiGroups:
@@ -170,3 +214,5 @@ Webhook support for Core Types is not currently automated by the tool. However,
 </aside>
 
 [webhook-for-core-types]: ./webhook-for-core-types.md
+[prometheus-operator]: https://github.com/prometheus-operator/prometheus-operator
+[markers-rbac]: ./markers/rbac.md

pkg/plugins/golang/v4/api.go

@@ -146,14 +146,6 @@ func (p *createAPISubcommand) InjectResource(res *resource.Resource) error {
 		}
 	}
 
-	// Ensure that if any external API flag is set, both must be provided.
-	if len(p.options.ExternalAPIPath) != 0 || len(p.options.ExternalAPIDomain) != 0 {
-		if len(p.options.ExternalAPIPath) == 0 || len(p.options.ExternalAPIDomain) == 0 {
-			return errors.New("Both '--external-api-path' and '--external-api-domain' must be " +
-				"specified together when referencing an external API.")
-		}
-	}
-
 	p.options.UpdateResource(p.resource, p.config)
 
 	if err := p.resource.Validate(); err != nil {

test/testdata/generate.sh

@@ -46,7 +46,8 @@ function scaffold_test_project {
     $kb create api --group crew --version v1 --kind Admiral --plural=admirales --controller=true --resource=true --namespaced=false --make=false
     $kb create webhook --group crew --version v1 --kind Admiral --plural=admirales --defaulting
     # Controller for External types
-    $kb create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=cert-manager.io
+    $kb create api --group "cert-manager.io" --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
+    $kb create api --group "monitoring" --version v1 --kind ServiceMonitor --controller=true --resource=false --make=false --external-api-path=github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1 --external-api-domain=coreos.com
   fi
 
   if [[ $project =~ multigroup ]]; then
@@ -72,7 +73,8 @@ function scaffold_test_project {
     $kb create api --group foo --version v1 --kind Bar --controller=true --resource=true --make=false
     $kb create api --group fiz --version v1 --kind Bar --controller=true --resource=true --make=false
     # Controller for External types
-    $kb create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=cert-manager.io
+    $kb create api --group "cert-manager.io" --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
+    $kb create api --group "monitoring" --version v1 --kind ServiceMonitor --controller=true --resource=false --make=false --external-api-path=github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1 --external-api-domain=coreos.com
   fi
 
   if [[ $project =~ multigroup ]] || [[ $project =~ with-plugins ]] ; then

testdata/project-v4-multigroup/PROJECT

@@ -126,12 +126,18 @@ resources:
   path: sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/api/fiz/v1
   version: v1
 - controller: true
-  domain: cert-manager.io
   external: true
-  group: certmanager
+  group: cert-manager.io
   kind: Certificate
   path: github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
   version: v1
+- controller: true
+  domain: coreos.com
+  external: true
+  group: monitoring
+  kind: ServiceMonitor
+  path: github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1
+  version: v1
 - api:
     crdVersion: v1
     namespaced: true

testdata/project-v4-multigroup/cmd/main.go

@@ -35,7 +35,9 @@ import (
 	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
 	"sigs.k8s.io/controller-runtime/pkg/webhook"
 
-	certmanagerv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
+	certmanageriov1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
 
 	crewv1 "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/api/crew/v1"
 	examplecomv1alpha1 "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/api/example.com/v1alpha1"
@@ -48,12 +50,13 @@ import (
 	shipv1beta1 "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/api/ship/v1beta1"
 	shipv2alpha1 "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/api/ship/v2alpha1"
 	appscontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/apps"
-	certmanagercontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/certmanager"
+	certmanageriocontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/cert-manager.io"
 	crewcontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/crew"
 	examplecomcontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/example.com"
 	fizcontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/fiz"
 	foocontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/foo"
 	foopolicycontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/foo.policy"
+	monitoringcontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/monitoring"
 	seacreaturescontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/sea-creatures"
 	shipcontroller "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/controller/ship"
 	webhookcrewv1 "sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup/internal/webhook/crew/v1"
@@ -81,7 +84,8 @@ func init() {
 	utilruntime.Must(foopolicyv1.AddToScheme(scheme))
 	utilruntime.Must(foov1.AddToScheme(scheme))
 	utilruntime.Must(fizv1.AddToScheme(scheme))
-	utilruntime.Must(certmanagerv1.AddToScheme(scheme))
+	utilruntime.Must(certmanageriov1.AddToScheme(scheme))
+	utilruntime.Must(monitoringv1.AddToScheme(scheme))
 	utilruntime.Must(examplecomv1alpha1.AddToScheme(scheme))
 	// +kubebuilder:scaffold:scheme
 }
@@ -276,13 +280,20 @@ func main() {
 		setupLog.Error(err, "unable to create controller", "controller", "Bar")
 		os.Exit(1)
 	}
-	if err = (&certmanagercontroller.CertificateReconciler{
+	if err = (&certmanageriocontroller.CertificateReconciler{
 		Client: mgr.GetClient(),
 		Scheme: mgr.GetScheme(),
 	}).SetupWithManager(mgr); err != nil {
 		setupLog.Error(err, "unable to create controller", "controller", "Certificate")
 		os.Exit(1)
 	}
+	if err = (&monitoringcontroller.ServiceMonitorReconciler{
+		Client: mgr.GetClient(),
+		Scheme: mgr.GetScheme(),
+	}).SetupWithManager(mgr); err != nil {
+		setupLog.Error(err, "unable to create controller", "controller", "ServiceMonitor")
+		os.Exit(1)
+	}
 	if err = (&examplecomcontroller.MemcachedReconciler{
 		Client:   mgr.GetClient(),
 		Scheme:   mgr.GetScheme(),

testdata/project-v4-multigroup/config/rbac/role.yaml

@@ -46,7 +46,7 @@ rules:
   - patch
   - update
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates
   verbs:
@@ -58,13 +58,13 @@ rules:
   - update
   - watch
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates/finalizers
   verbs:
   - update
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates/status
   verbs:
@@ -181,6 +181,32 @@ rules:
   - get
   - patch
   - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/finalizers
+  verbs:
+  - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/status
+  verbs:
+  - get
+  - patch
+  - update
 - apiGroups:
   - sea-creatures.testproject.org
   resources:

testdata/project-v4-multigroup/dist/install.yaml

@@ -1177,7 +1177,7 @@ rules:
   - patch
   - update
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates
   verbs:
@@ -1189,13 +1189,13 @@ rules:
   - update
   - watch
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates/finalizers
   verbs:
   - update
 - apiGroups:
-  - certmanager.cert-manager.io
+  - cert-manager.io
   resources:
   - certificates/status
   verbs:
@@ -1312,6 +1312,32 @@ rules:
   - get
   - patch
   - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/finalizers
+  verbs:
+  - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors/status
+  verbs:
+  - get
+  - patch
+  - update
 - apiGroups:
   - sea-creatures.testproject.org
   resources:

testdata/project-v4-multigroup/go.mod

@@ -1,11 +1,14 @@
 module sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup
 
-go 1.22.0
+go 1.23
+
+toolchain go1.23.2
 
 require (
 	github.com/cert-manager/cert-manager v1.16.1
 	github.com/onsi/ginkgo/v2 v2.19.0
 	github.com/onsi/gomega v1.33.1
+	github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring v0.77.1
 	k8s.io/api v0.31.1
 	k8s.io/apimachinery v0.31.1
 	k8s.io/client-go v0.31.1

testdata/project-v4-multigroup/internal/controller/certmanager/certificate_controller.go renamed to testdata/project-v4-multigroup/internal/controller/cert-manager.io/certificate_controller.go

@@ -14,12 +14,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package certmanager
+package certmanagerio
 
 import (
 	"context"
 
-	certmanagerv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
+	certmanageriov1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
@@ -32,9 +32,9 @@ type CertificateReconciler struct {
 	Scheme *runtime.Scheme
 }
 
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates/status,verbs=get;update;patch
-// +kubebuilder:rbac:groups=certmanager.cert-manager.io,resources=certificates/finalizers,verbs=update
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=cert-manager.io,resources=certificates/finalizers,verbs=update
 
 // Reconcile is part of the main kubernetes reconciliation loop which aims to
 // move the current state of the cluster closer to the desired state.
@@ -56,7 +56,7 @@ func (r *CertificateReconciler) Reconcile(ctx context.Context, req ctrl.Request)
 // SetupWithManager sets up the controller with the Manager.
 func (r *CertificateReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
-		For(&certmanagerv1.Certificate{}).
-		Named("certmanager-certificate").
+		For(&certmanageriov1.Certificate{}).
+		Named("cert-manager.io-certificate").
 		Complete(r)
 }