deprecate configuring Contour with a Gateway controller name (project…

…contour#6144) Users should either statically configure Contour with a specific Gateway ref, or use the Gateway provisioner to dynamically provision Gateways. Updates projectcontour#5923. Signed-off-by: Steve Kriss <[email protected]>
projectsesame · Jan 31, 2024 · 62f81db · 62f81db
1 parent ac49aee
commit 62f81db
Show file tree

Hide file tree

Showing 15 changed files with 48 additions and 1 deletion.
diff --git a/apis/projectcontour/v1alpha1/contourconfig.go b/apis/projectcontour/v1alpha1/contourconfig.go
@@ -158,6 +158,9 @@ type GatewayConfig struct {
 	// GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
 	// If unset, the gatewayclass controller will not be started.
 	// Exactly one of ControllerName or GatewayRef must be set.
+	//
+	// Deprecated: users should use GatewayRef, or the Gateway provisioner,
+	// in place of this field. This field will be removed in a future release.
 	// +optional
 	ControllerName string `json:"controllerName,omitempty"`
 

diff --git a/changelogs/unreleased/6144-skriss-deprecation.md b/changelogs/unreleased/6144-skriss-deprecation.md
@@ -0,0 +1,5 @@
+## Configuring Contour with a GatewayClass controller name is deprecated
+
+Contour should no longer be configured with a GatewayClass controller name (`gateway.controllerName` in the config file or ContourConfiguration CRD).
+Instead, either use a specific Gateway reference (`gateway.gatewayRef`), or use the Gateway provisioner.
+`gateway.controllerName` will be removed in a future release.
diff --git a/cmd/contour/serve.go b/cmd/contour/serve.go
@@ -528,8 +528,13 @@ func (s *Server) doServe() error {
 	var gatewayRef *types.NamespacedName
 
 	if contourConfiguration.Gateway != nil {
+		// nolint:staticcheck
 		gatewayControllerName = contourConfiguration.Gateway.ControllerName
 
+		if len(gatewayControllerName) > 0 {
+			s.log.Warnf("DEPRECATED: gateway.controllerName is deprecated and will be removed in a future release. Use gateway.gatewayRef or the Gateway provisioner instead.")
+		}
+
 		if contourConfiguration.Gateway.GatewayRef != nil {
 			gatewayRef = &types.NamespacedName{
 				Namespace: contourConfiguration.Gateway.GatewayRef.Namespace,
@@ -1005,6 +1010,7 @@ func (s *Server) setupGatewayAPI(contourConfiguration contour_api_v1alpha1.Conto
 	needLeadershipNotification := []leadership.NeedLeaderElectionNotification{}
 
 	// Check if GatewayAPI is configured.
+	// nolint:staticcheck
 	if contourConfiguration.Gateway != nil && (contourConfiguration.Gateway.GatewayRef != nil || len(contourConfiguration.Gateway.ControllerName) > 0) {
 		switch {
 		// If a specific gateway was specified, we don't need to run the
@@ -1024,6 +1030,7 @@ func (s *Server) setupGatewayAPI(contourConfiguration contour_api_v1alpha1.Conto
 		// the appropriate gateway class and gateway to process.
 		default:
 			// Create and register the gatewayclass controller with the manager.
+			// nolint:staticcheck
 			gatewayClassControllerName := contourConfiguration.Gateway.ControllerName
 			gwClass, err := controller.RegisterGatewayClassController(
 				s.log.WithField("context", "gatewayclass-controller"),

diff --git a/cmd/contour/servecontext.go b/cmd/contour/servecontext.go
@@ -295,6 +295,7 @@ func (ctx *serveContext) convertToContourConfigurationSpec() contour_api_v1alpha
 	var gatewayConfig *contour_api_v1alpha1.GatewayConfig
 	if ctx.Config.GatewayConfig != nil {
 		gatewayConfig = &contour_api_v1alpha1.GatewayConfig{
+			// nolint:staticcheck
 			ControllerName: ctx.Config.GatewayConfig.ControllerName,
 		}
 

diff --git a/examples/contour/01-crds.yaml b/examples/contour/01-crds.yaml
@@ -617,6 +617,8 @@ spec:
                       GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                       If unset, the gatewayclass controller will not be started.
                       Exactly one of ControllerName or GatewayRef must be set.
+                      Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                      in place of this field. This field will be removed in a future release.
                     type: string
                   gatewayRef:
                     description: |-
@@ -4296,6 +4298,8 @@ spec:
                           GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                           If unset, the gatewayclass controller will not be started.
                           Exactly one of ControllerName or GatewayRef must be set.
+                          Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                          in place of this field. This field will be removed in a future release.
                         type: string
                       gatewayRef:
                         description: |-

diff --git a/examples/render/contour-deployment.yaml b/examples/render/contour-deployment.yaml
@@ -836,6 +836,8 @@ spec:
                       GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                       If unset, the gatewayclass controller will not be started.
                       Exactly one of ControllerName or GatewayRef must be set.
+                      Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                      in place of this field. This field will be removed in a future release.
                     type: string
                   gatewayRef:
                     description: |-
@@ -4515,6 +4517,8 @@ spec:
                           GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                           If unset, the gatewayclass controller will not be started.
                           Exactly one of ControllerName or GatewayRef must be set.
+                          Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                          in place of this field. This field will be removed in a future release.
                         type: string
                       gatewayRef:
                         description: |-

diff --git a/examples/render/contour-gateway-provisioner.yaml b/examples/render/contour-gateway-provisioner.yaml
@@ -628,6 +628,8 @@ spec:
                       GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                       If unset, the gatewayclass controller will not be started.
                       Exactly one of ControllerName or GatewayRef must be set.
+                      Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                      in place of this field. This field will be removed in a future release.
                     type: string
                   gatewayRef:
                     description: |-
@@ -4307,6 +4309,8 @@ spec:
                           GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                           If unset, the gatewayclass controller will not be started.
                           Exactly one of ControllerName or GatewayRef must be set.
+                          Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                          in place of this field. This field will be removed in a future release.
                         type: string
                       gatewayRef:
                         description: |-

diff --git a/examples/render/contour-gateway.yaml b/examples/render/contour-gateway.yaml
@@ -839,6 +839,8 @@ spec:
                       GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                       If unset, the gatewayclass controller will not be started.
                       Exactly one of ControllerName or GatewayRef must be set.
+                      Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                      in place of this field. This field will be removed in a future release.
                     type: string
                   gatewayRef:
                     description: |-
@@ -4518,6 +4520,8 @@ spec:
                           GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                           If unset, the gatewayclass controller will not be started.
                           Exactly one of ControllerName or GatewayRef must be set.
+                          Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                          in place of this field. This field will be removed in a future release.
                         type: string
                       gatewayRef:
                         description: |-

diff --git a/examples/render/contour.yaml b/examples/render/contour.yaml
@@ -836,6 +836,8 @@ spec:
                       GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                       If unset, the gatewayclass controller will not be started.
                       Exactly one of ControllerName or GatewayRef must be set.
+                      Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                      in place of this field. This field will be removed in a future release.
                     type: string
                   gatewayRef:
                     description: |-
@@ -4515,6 +4517,8 @@ spec:
                           GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
                           If unset, the gatewayclass controller will not be started.
                           Exactly one of ControllerName or GatewayRef must be set.
+                          Deprecated: users should use GatewayRef, or the Gateway provisioner,
+                          in place of this field. This field will be removed in a future release.
                         type: string
                       gatewayRef:
                         description: |-

diff --git a/pkg/config/parameters.go b/pkg/config/parameters.go
@@ -258,6 +258,9 @@ type GatewayParameters struct {
 	// GatewayClass. The string takes the form of "projectcontour.io/<namespace>/contour".
 	// If unset, the gatewayclass controller will not be started.
 	// Exactly one of ControllerName or GatewayRef must be set.
+	//
+	// Deprecated: users should use GatewayRef, or the Gateway provisioner,
+	// in place of this field. This field will be removed in a future release.
 	ControllerName string `yaml:"controllerName,omitempty"`
 
 	// GatewayRef defines a specific Gateway that this Contour

diff --git a/site/content/docs/main/config/api-reference.html b/site/content/docs/main/config/api-reference.html
@@ -7644,6 +7644,8 @@ <h3 id="projectcontour.io/v1alpha1.GatewayConfig">GatewayConfig
 GatewayClass. The string takes the form of &ldquo;projectcontour.io/<namespace>/contour&rdquo;.
 If unset, the gatewayclass controller will not be started.
 Exactly one of ControllerName or GatewayRef must be set.</p>
+<p>Deprecated: users should use GatewayRef, or the Gateway provisioner,
+in place of this field. This field will be removed in a future release.</p>
 </td>
 </tr>
 <tr>

diff --git a/site/content/docs/main/config/gateway-api.md b/site/content/docs/main/config/gateway-api.md
@@ -28,6 +28,8 @@ With static provisioning, Contour can be configured with either a [controller na
 If configured with a controller name, Contour will process the oldest `GatewayClass`, its oldest `Gateway`, and that `Gateway's` routes, for the given controller name.
 If configured with a specific gateway, Contour will process that `Gateway` and its routes.
 
+**Note:** configuring Contour with a controller name is deprecated and will be removed in a future release. Use a specific gateway reference or dynamic provisioning instead.
+
 In **dynamic** provisioning, the platform operator first deploys Contour's Gateway provisioner. Then, the platform operator defines a `Gateway` resource, and the provisioner automatically deploys a Contour instance that corresponds to the `Gateway's` configuration and will process that `Gateway` and its routes.
 
 Static provisioning makes sense for users who:

diff --git a/site/content/docs/main/configuration.md b/site/content/docs/main/configuration.md
@@ -214,7 +214,7 @@ The gateway configuration block is used to configure which gateway-api Gateway C
 
 | Field Name     | Type           | Default | Description                                                                    |
 | -------------- | -------------- | ------- | ------------------------------------------------------------------------------ |
-| controllerName | string         |         | Gateway Class controller name (i.e. projectcontour.io/gateway-controller). If set, Contour will reconcile the oldest GatewayClass, and its oldest Gateway, with this controller string. Only one of `controllerName` or `gatewayRef` must be set. |
+| controllerName | string         |         | **DEPRECATED**: Use `gatewayRef` or the Gateway provisioner instead. This field will be removed in a future release. Gateway Class controller name (i.e. projectcontour.io/gateway-controller). If set, Contour will reconcile the oldest GatewayClass, and its oldest Gateway, with this controller string. Only one of `controllerName` or `gatewayRef` must be set. |
 | gatewayRef     | NamespacedName |         | [Gateway namespace and name](#gateway-ref). If set, Contour will reconcile this specific Gateway. Only one of `controllerName` or `gatewayRef` must be set. |
 
 ### Gateway Ref

diff --git a/site/content/guides/gateway-api.md b/site/content/guides/gateway-api.md
@@ -47,6 +47,8 @@ With static provisioning, Contour can be configured with either a [controller na
 If configured with a controller name, Contour will process the oldest `GatewayClass`, its oldest `Gateway`, and that `Gateway's` routes, for the given controller name.
 If configured with a specific gateway, Contour will process that `Gateway` and its routes.
 
+**Note:** configuring Contour with a controller name is deprecated and will be removed in a future release. Use a specific gateway reference or dynamic provisioning instead.
+
 In **dynamic** provisioning, the platform operator first deploys Contour's Gateway provisioner. Then, the platform operator defines a `Gateway` resource, and the provisioner automatically deploys a Contour instance that corresponds to the `Gateway's` configuration and will process that `Gateway` and its routes.
 
 Static provisioning may be more appropriate for users who prefer the traditional model of deploying Contour, have just a single Contour instance, or have highly customized YAML for deploying Contour.

diff --git a/test/e2e/gateway/gateway_test.go b/test/e2e/gateway/gateway_test.go
@@ -102,6 +102,7 @@ var _ = Describe("Gateway API", func() {
 							Name:      gateway.Name,
 						}
 					} else {
+						// nolint:staticcheck
 						contourConfig.GatewayConfig.ControllerName = string(gatewayClass.Spec.ControllerName)
 					}
 
@@ -113,6 +114,7 @@ var _ = Describe("Gateway API", func() {
 							Name:      gateway.Name,
 						}
 					} else {
+						// nolint:staticcheck
 						contourConfiguration.Spec.Gateway.ControllerName = string(gatewayClass.Spec.ControllerName)
 					}