feat: document enablement flags, validate ingress enablement flags

internal/manager/config.go

@@ -89,6 +89,8 @@ type Config struct {
 
 // onOffUsage is used to indicate what textual options are used to enable or disable a feature.
 const onOffUsage = "Can be one of [enabled, disabled]."
+const onOffAutoIngressUsage = "Can be one of [enabled, disabled, auto]. If multiple ingress API versions are set to 'auto', then the newest out of these will be used."
+const onOffAutoCRDUsage = "Can be one of [enabled, disabled, auto]. 'auto' means that enablement will depend on the detected presence of the appropriate CRD in the cluster."
 
 // -----------------------------------------------------------------------------
 // Controller Manager - Config - Methods
@@ -156,15 +158,15 @@ func (c *Config) FlagSet() *pflag.FlagSet {
 		`Indicates if the ingress controller should update the status of resources (e.g. IP/Hostname for v1.Ingress, e.t.c.)`)
 
 	// Kubernetes API toggling
-	flagSet.enablementStatusVar(&c.IngressNetV1Enabled, "controller-ingress-networkingv1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version networking.k8s.io/v1)."+onOffUsage)
+	flagSet.enablementStatusVar(&c.IngressNetV1Enabled, "controller-ingress-networkingv1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version networking.k8s.io/v1)."+onOffAutoIngressUsage)
 	// TODO the other Ingress versions remain disabled for now. 2.x does not yet support version negotiation
-	flagSet.enablementStatusVar(&c.IngressNetV1beta1Enabled, "controller-ingress-networkingv1beta1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version networking.k8s.io/v1beta1)."+onOffUsage)
-	flagSet.enablementStatusVar(&c.IngressExtV1beta1Enabled, "controller-ingress-extensionsv1beta1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version extensions/v1beta1)."+onOffUsage)
+	flagSet.enablementStatusVar(&c.IngressNetV1beta1Enabled, "controller-ingress-networkingv1beta1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version networking.k8s.io/v1beta1)."+onOffAutoIngressUsage)
+	flagSet.enablementStatusVar(&c.IngressExtV1beta1Enabled, "controller-ingress-extensionsv1beta1", util.EnablementStatusAuto, "Enable or disable the Ingress controller (using API version extensions/v1beta1)."+onOffAutoIngressUsage)
 	flagSet.enablementStatusVar(&c.UDPIngressEnabled, "controller-udpingress", util.EnablementStatusEnabled, "Enable or disable the UDPIngress controller. "+onOffUsage)
 	flagSet.enablementStatusVar(&c.TCPIngressEnabled, "controller-tcpingress", util.EnablementStatusEnabled, "Enable or disable the TCPIngress controller. "+onOffUsage)
-	flagSet.enablementStatusVar(&c.KnativeIngressEnabled, "controller-knativeingress", util.EnablementStatusAuto, "Enable or disable the KnativeIngress controller. "+onOffUsage)
+	flagSet.enablementStatusVar(&c.KnativeIngressEnabled, "controller-knativeingress", util.EnablementStatusAuto, "Enable or disable the KnativeIngress controller. "+onOffAutoCRDUsage)
 	flagSet.enablementStatusVar(&c.KongIngressEnabled, "controller-kongingress", util.EnablementStatusEnabled, "Enable or disable the KongIngress controller. "+onOffUsage)
-	flagSet.enablementStatusVar(&c.KongClusterPluginEnabled, "controller-kongclusterplugin", util.EnablementStatusAuto, "Enable or disable the KongClusterPlugin controller. "+onOffUsage)
+	flagSet.enablementStatusVar(&c.KongClusterPluginEnabled, "controller-kongclusterplugin", util.EnablementStatusAuto, "Enable or disable the KongClusterPlugin controller. "+onOffAutoCRDUsage)
 	flagSet.enablementStatusVar(&c.KongPluginEnabled, "controller-kongplugin", util.EnablementStatusEnabled, "Enable or disable the KongPlugin controller. "+onOffUsage)
 	flagSet.enablementStatusVar(&c.KongConsumerEnabled, "controller-kongconsumer", util.EnablementStatusEnabled, "Enable or disable the KongConsumer controller. "+onOffUsage)
 	flagSet.enablementStatusVar(&c.ServiceEnabled, "controller-service", util.EnablementStatusEnabled, "Enable or disable the Service controller. "+onOffUsage)

internal/manager/controllerdef.go

@@ -68,7 +68,23 @@ func (c *ControllerDef) MaybeSetupWithManager(mgr ctrl.Manager) error {
 // Controller Manager - Controller Setup Functions
 // -----------------------------------------------------------------------------
 
+// validateIngressEnablement ensures that no Ingress API is 'enabled' when at least one is 'auto'.
+func validateIngressEnablement(cfg *Config) error {
+	switch util.EnablementStatusAuto {
+	case cfg.IngressExtV1beta1Enabled, cfg.IngressNetV1beta1Enabled, cfg.IngressNetV1Enabled:
+		switch util.EnablementStatusEnabled {
+		case cfg.IngressExtV1beta1Enabled, cfg.IngressNetV1beta1Enabled, cfg.IngressNetV1Enabled:
+			return fmt.Errorf("cannot mark core ingress APIs as enabled if another version is auto")
+		}
+	}
+	return nil
+}
+
 func setupControllers(logger logr.Logger, mgr manager.Manager, proxy proxy.Proxy, c *Config) ([]ControllerDef, error) {
+	// Choose the best API version of Ingress to inform which ingress controller to enable.
+	if err := validateIngressEnablement(c); err != nil {
+		return nil, err
+	}
 	var ingressPicker ingressControllerStrategy
 	if err := ingressPicker.Initialize(c, mgr.GetClient()); err != nil {
 		return nil, fmt.Errorf("ingress version picker failed: %w", err)
@@ -224,32 +240,39 @@ func setupControllers(logger logr.Logger, mgr manager.Manager, proxy proxy.Proxy
 	return controllers, nil
 }
 
+// crdExistsChecker verifies whether the resource type defined by GVR is supported by the k8s apiserver.
 type crdExistsChecker struct {
 	GVR schema.GroupVersionResource
 }
 
+// CRDExists returns true iff the apiserver supports the specified group/version/resource.
 func (c crdExistsChecker) CRDExists(r client.Client) bool {
 	return ctrlutils.CRDExists(r, c.GVR)
 }
 
+// ingressControllerStrategy picks the best Ingress API supported by k8s apiserver.
 type ingressControllerStrategy struct {
 	chosenVersion IngressAPI
 }
 
+// Initialize negotiates the best Ingress API version supported by both KIC and the k8s apiserver.
 func (s ingressControllerStrategy) Initialize(cfg *Config, cl client.Client) error {
 	var err error
 	s.chosenVersion, err = negotiateIngressAPI(cfg, cl)
 	return err
 }
 
+// IsExtV1beta1 returns true iff the best supported API version is extensions/v1beta1.
 func (s ingressControllerStrategy) IsExtV1beta1(_ client.Client) bool {
 	return s.chosenVersion == ExtensionsV1beta1
 }
 
+// IsExtV1beta1 returns true iff the best supported API version is networking.k8s.io/v1beta1.
 func (s ingressControllerStrategy) IsNetV1beta1(_ client.Client) bool {
 	return s.chosenVersion == NetworkingV1beta1
 }
 
+// IsExtV1beta1 returns true iff the best supported API version is networking.k8s.io/v1.
 func (s ingressControllerStrategy) IsNetV1(_ client.Client) bool {
 	return s.chosenVersion == NetworkingV1
 }