Merge pull request #1311 from inteon/cleanup_installation

Cleanup installation section

.spelling

@@ -261,6 +261,7 @@ Velero
 Venafi
 versioned
 WebhookConfiguration
+ControllerConfiguration
 WIP
 YAML
 YAMLs

content/docs/concepts/webhook.md

@@ -73,7 +73,7 @@ For these reasons, after installing cert-manager and when performing post-instal
 you will need to check for temporary API configuration errors and retry.
 
 You could also add a post-installation check which performs `kubectl --dry-run` operations on the cert-manager API.
-Or you could add a post-installation check which automatically retries the [Installation Verification](../installation/verify.md) steps until they succeed.
+Or you could add a post-installation check which automatically retries the [Installation Verification](../installation/kubectl.md#verify) steps until they succeed.
 
 ### Other Webhook Problems
 

content/docs/contributing/crds.md

@@ -56,7 +56,7 @@ While cert-manager doesn't fully use Kubebuilder, CRDs can make use of special K
 
 ## Making Changes to APIs
 
-Please see our [API compatibility promise](../installation/api-compatibility.md) for details on which types of changes to APIs are acceptable.
+Please see our [API compatibility promise](../contributing/api-compatibility.md) for details on which types of changes to APIs are acceptable.
 
 Generally, the gist is that new fields can be added but that existing fields cannot be removed.
 

content/docs/contributing/featuregates.md

@@ -1,31 +1,34 @@
 ---
-Title: Implementing feature gates
-description: 'cert-manager contributing guide: Implementing feature gates'
+title: cert-manager feature gates
+description: 'cert-manager contributing guide: Feature gates'
 ---
 
-As of v1 release cert-manager is considered stable. We aim to follow Kubernetes API compatibility policy when making API changes, see [API compatibility](../installation/api-compatibility.md) to avoid breaking users' existing cert-manager installations.
+As of v1 release cert-manager is considered stable. We aim to follow Kubernetes API compatibility policy when making API changes, see [API compatibility](../contributing/api-compatibility.md) to avoid breaking users' existing cert-manager installations.
 This means that as developers we are somewhat limited in regards to changing existing behavior, i.e renaming or removing API elements or changing their behavior.
 
 New functionality that is not yet stable[^1] can still be added, but it needs to be placed behind a feature gate.
 
+## Enabling/ disabling feature gates
+
+Feature gates can be enabled or disabled using CLI flags or config files, more info can be found in [configuring components](../installation/configuring-components.md).
+
 ## Feature gated API fields
 
-Feature gated API fields are implemented using `--feature-gates` flags of cert-manager [webhook](../cli/webhook.md) and [controller](../cli/controller.md).
+Feature gated API fields are implemented using `--feature-gates` flags of cert-manager [webhook](../cli/webhook.md), [cainjector](../cli/cainjector.md) and [controller](../cli/controller.md).
 
 A feature gated API field is always visible to the user (i.e when running `kubectl explain <some-resource>`), but is only functional if the relevant feature is explicitly enabled via feature flags for both the webhook and controller.
 
 If a user attempts to apply a resource with the feature gated field set to a non-nil value, but the feature gate is not enabled, the resource will get rejected by the webhook validation.
 This mechanism differs from [the one that Kubernetes uses for feature gated API field implementation](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#new-field-in-existing-api-version) where the field will be simply set to nil if the feature gate is disabled. We chose to use webhook validation instead to make debugging easier for users who are attempting to use the feature gated field, but have forgotten to enable the feature gate.
 
-
 ### Implementation
 
 - Implement the new field and document that it is feature gated and in order to use it the controller and webhook feature gates need enabling
-- Add a new [webhook feature gate](https://github.com/cert-manager/cert-manager/blob/3a055cc2f56c1c2874807af4a8f84d0a1c46ccb4/internal/webhook/feature/features.go#L25-L39) for the field
+- Add a new [webhook feature gate](https://github.com/cert-manager/cert-manager/blob/7c7e8f4ce6c1abba18025d3d00be368066801a63/internal/webhook/feature/features.go#L31-L64) for the field
 - Update webhook validation checks for the relevant resource kind to ensure that if the feature gated field is set, but the webhook feature gate is not enabled, the resource gets rejected
-- Add a new [controller feature gate](https://github.com/cert-manager/cert-manager/blob/2417132b3cd017b5f0974006e03c2b8a540efe3f/internal/controller/feature/features.go#L26-L54) for the field
+- Add a new [controller feature gate](https://github.com/cert-manager/cert-manager/blob/7c7e8f4ce6c1abba18025d3d00be368066801a63/internal/controller/feature/features.go#L32-L121) for the field
 - Ensure that any control loops that use the feature, check that the feature gate is actually enabled. (This is required to cover edge cases such as if the webhook runs a version of cert-manager where the feature is in GA whereas controller runs an older version where the feature is still in experimental state)
-- Ensure that the feature gate is added to cert-manager installation scripts for CI and local tests in [make](https://github.com/cert-manager/cert-manager/blob/134398e939bb2b1401697eaf589405ad469cd609/make/e2e-setup.mk#L165) and [bazel](https://github.com/cert-manager/cert-manager/blob/fd747b42b9ab4b6409b61b7946e8dc14d532e950/devel/addon/certmanager/install.sh#L26) scripts
+- Ensure that the feature gate is added to cert-manager installation scripts for CI and local tests in [make](https://github.com/cert-manager/cert-manager/blob/7c7e8f4ce6c1abba18025d3d00be368066801a63/make/e2e-setup.mk#L197) and [bash](https://github.com/cert-manager/cert-manager/blob/7c7e8f4ce6c1abba18025d3d00be368066801a63/make/e2e.sh#L80) scripts
 - Default cert-manger e2e CI tests run with all feature gates for all components enabled. There is an additional optional e2e test that runs with all feature gates disabled. You can trigger that for your PR with `/test pull-cert-manager-e2e-feature-gates-disabled` to verify that all works as expected both with and without the new feature gate.
 
 ### Potential issues
@@ -36,9 +39,7 @@ This mechanism differs from [the one that Kubernetes uses for feature gated API
 
 ### References
 
-- cert-manager's [API compatibility promise](../installation/api-compatibility.md)
-
-- An example implementation of an alpha field is [`AdditionalOutputFormats` field on `Certificate` spec](https://github.com/cert-manager/cert-manager/blob/dbad3d98f3d7d85cadb4bd2c2493faf8b666b313/internal/apis/certmanager/types_certificate.go#L169-L174)
+- cert-manager's [API compatibility promise](../contributing/api-compatibility.md)
 
 - [Kubernetes definition of feature stages](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages)
 

content/docs/installation/configuring-components.md

@@ -0,0 +1,89 @@
+---
+title: cert-manager component configuration
+description: 'Configure cert-manager components using CLI flags or a configuration file'
+---
+
+To configure the cert-manager components, you can use CLI flags or a configuration file.
+The CLI flags take precedence over the configuration file.
+
+## CLI flags
+
+An overview of the available CLI flags for each component can be found on the following pages:
+- cert-manager controller: [controller CLI flags](../cli/controller.md)
+- cert-manager webhook: [webhook CLI flags](../cli/webhook.md)
+- cert-manager cainjector: [cainjector CLI flags](../cli/cainjector.md)
+- cert-manager acmesolver: [acmesolver CLI flags](../cli/acmesolver.md)
+- cert-manager cmctl: [cmctl CLI flags](../cli/cmctl.md)
+
+When using the Helm chart, the CLI flags can be specified in the `controller.extraArgs`, `webhook.extraArgs`, `cainjector.extraArgs` and `acmesolver.extraArgs` values.
+
+## Configuration file
+
+The configuration file is a YAML file that contains the configuration for the cert-manager components.
+The configuration file can be specified using the `--config` CLI flag. When using the Helm chart, the
+configuration file can be specified in the `config` and `webhook.config` values.
+
+### Controller configuration file
+
+The webhook configuration API documentation can be found on the [ControllerConfiguration](../reference/api-docs.md#controller.config.cert-manager.io/v1alpha1.ControllerConfiguration) page.
+
+This is an example configuration file for the controller:
+```yaml
+apiVersion: controller.config.cert-manager.io/v1alpha1
+kind: ControllerConfiguration
+
+logging:
+  verbosity: 2
+  format: text
+
+leaderElectionConfig:
+  namespace: my-namespace
+
+kubernetesAPIQPS: 10
+kubernetesAPIBurst: 50
+
+numberOfConcurrentWorkers: 200
+
+featureGates:
+  additionalCertificateOutputFormats: true
+  experimentalCertificateSigningRequestControllers: true
+  experimentalGatewayAPISupport: true
+  serverSideApply: true
+  literalCertificateSubject: true
+  useCertificateRequestBasicConstraints: true
+```
+
+### Webhook configuration file
+
+The webhook configuration API documentation can be found on the [WebhookConfiguration](../reference/api-docs.md#webhook.config.cert-manager.io/v1alpha1.WebhookConfiguration) page.
+
+This is an example configuration file for the webhook:
+```yaml
+apiVersion: webhook.config.cert-manager.io/v1alpha1
+kind: WebhookConfiguration
+
+logging:
+  verbosity: 2
+  format: text
+
+securePort: 6443
+healthzPort: 6080
+
+featureGates:
+  additionalCertificateOutputFormats: true
+  literalCertificateSubject: true
+```
+
+## Feature gates
+
+Feature gates can be used to enable or disable experimental features in cert-manager. 
+
+There are 2 levels of feature gates (more details in [Kubernetes definition of feature stages](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages)):
+- **Alpha:** feature is not yet stable and might be removed or changed in the future. Alpha features are disabled by default and need to be explicitly enabled by the user (to test the feature).
+- **Beta:** feature is almost stable but might still change in the future. Beta features are enabled by default and can be disabled by the user (if any issues are encountered).
+
+Each cert-manager component has its own set of feature gates. They can be enabled/ disabled using the `--feature-gates` flag or the `featureGates` value in the config file. The available feature gates for each component can be found on the following pages:
+
+- cert-manager controller: [controller feature gates](https://github.com/cert-manager/cert-manager/blob/master/internal/controller/feature/features.go)
+- cert-manager webhook: [webhook feature gates](https://github.com/cert-manager/cert-manager/blob/master/internal/webhook/feature/features.go)
+- cert-manager cainjector: [cainjector feature gates](https://github.com/cert-manager/cert-manager/blob/master/internal/cainjector/feature/features.go)

content/docs/installation/helm.md

@@ -89,7 +89,7 @@ helm install \
   --set webhook.timeoutSeconds=4   # Example: changing the webhook timeout using a Helm parameter
 ```
 
-Once you have deployed cert-manager, you can [verify](./verify.md) the installation.
+Once you have deployed cert-manager, you can [verify](./kubectl.md#verify) the installation.
 
 ### Installing cert-manager as subchart