Gateway API: Recommend the `config` approach rather than `extraArgs`

maelvls commented 2 months ago

The config approach is much more convenient than to have to concatenate flags in the extraFlags field. The config approach isn't immediately obvious to users, as seen in https://github.com/cert-manager/cert-manager/pull/7121 where we found that there was no need for adding an extra helm value: one could simply use config.enableGatewayAPI.

maelvls commented 2 months ago

@wallrj Can you take a look? Thanks!

netlify[bot] commented 2 months ago

Deploy Preview for cert-manager ready!

Built without sensitive environment variables

Name	Link
Latest commit	ff1e41aa03dcc831028a804419b3e31be3ca3d4a
Latest deploy log	https://app.netlify.com/sites/cert-manager/deploys/66b4899ac4bfdb00082d8699
Deploy Preview	https://deploy-preview-1517--cert-manager.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

hongbo-miao commented 2 months ago

Thanks @maelvls @wallrj for the info. It would be great to document the difference. Right now I noticed there are 3 methods in Helm chart:

featureGates: ExperimentalGatewayAPISupport=true

extraArgs:
- --feature-gates=ExperimentalGatewayAPISupport=true

This method current lists in Helm values.yaml

config:
  featureGates:
    ExperimentalGatewayAPISupport: true

maelvls commented 1 month ago

I'll clarify further why and what the recommended approaches are depending on the cert-manager version. Thanks for the feedback!

maelvls commented 1 month ago

Here would be my recommendation depending on whether you are using 1.14 or below, 1.15, or 1.16 and above:

If you are using 1.15 and above, you no longer have to set a feature flag, but you still need to enable the feature. The recommended way to turn on the Gateway API support in 1.15 is to use the file-based configuration using the config Helm value:

config:
  apiVersion: controller.config.cert-manager.io/v1alpha1
  kind: ControllerConfiguration
  enableGatewayAPI: true

If you are using 1.16 and above, it is even simpler:

config:
  enableGatewayAPI: true

Another less practical way is to rely on the command line flag --enable-gateway-api:

extraArgs:
  - --enable-gateway-api

If you are using 1.14 and below, you will have to use the feature flag to turn on the Gateway API support. The recommended way is to use the featureGates Helm value:

Another way is to use the config Helm value:

config:
  apiVersion: controller.config.cert-manager.io/v1alpha1
  kind: ControllerConfiguration
  featureGates:
    ExperimentalGatewayAPISupport: true

A less readable way (as it requires a comma-separated list of feature flags) is to use the featureGates Helm value:

featureGates: ExperimentalGatewayAPISupport=true

which is equivalent to:

extraArgs:
  - --feature-gates=ExperimentalGatewayAPISupport=true

I'm not sure how to put that into the documentation. Should I only talk about the latest version, or can I explain how to set up Gateway API depending on the version? @wallrj

maelvls commented 1 month ago

Discussed in this morning's open standup:

I will only keep the 1.15 instructions, and only show the config approach since it's the most sensible one (we think).
I will add a note that explains that the feature flag that existed in 1.14 no longer exists and was replaced with a configuration option enableGatewayAPI.

maelvls commented 1 month ago

I didn't test this, but I expect you have.

I had forgotten to test it... and found multiple typos in the commands. 🤦

I fixed them, it should be good to go now.

maelvls commented 1 month ago

/unhold

cert-manager-prow[bot] commented 1 month ago

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: wallrj

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files: - ~~[OWNERS](https://github.com/cert-manager/website/blob/master/OWNERS)~~ [wallrj] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment

cert-manager / website