From cc19d081ce940994796d1eadd556979c39816e0e Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Wed, 11 Oct 2023 14:27:27 +0200 Subject: [PATCH] cleanup installation section Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- .spelling | 1 + content/docs/concepts/webhook.md | 2 +- .../api-compatibility.md | 0 content/docs/contributing/crds.md | 2 +- content/docs/contributing/featuregates.md | 23 ++-- .../installation/configuring-components.md | 89 +++++++++++++ content/docs/installation/featureflags.md | 76 ----------- content/docs/installation/helm.md | 2 +- content/docs/installation/kubectl.md | 125 ++++++++++++++++-- content/docs/installation/other-tools.md | 23 ---- content/docs/installation/reinstall.md | 33 +++++ content/docs/installation/uninstall.md | 2 +- content/docs/installation/upgrade.md | 28 +--- content/docs/installation/verify.md | 122 ----------------- content/docs/manifest.json | 43 +++--- content/docs/reference/cmctl.md | 2 +- public/_redirects | 6 + 17 files changed, 282 insertions(+), 297 deletions(-) rename content/docs/{installation => contributing}/api-compatibility.md (100%) create mode 100644 content/docs/installation/configuring-components.md delete mode 100644 content/docs/installation/featureflags.md delete mode 100644 content/docs/installation/other-tools.md create mode 100644 content/docs/installation/reinstall.md delete mode 100644 content/docs/installation/verify.md diff --git a/.spelling b/.spelling index 6a2e900f0f4..dfe98730153 100644 --- a/.spelling +++ b/.spelling @@ -261,6 +261,7 @@ Velero Venafi versioned WebhookConfiguration +ControllerConfiguration WIP YAML YAMLs diff --git a/content/docs/concepts/webhook.md b/content/docs/concepts/webhook.md index 1bcbbee7695..884e92d7c81 100644 --- a/content/docs/concepts/webhook.md +++ b/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 diff --git a/content/docs/installation/api-compatibility.md b/content/docs/contributing/api-compatibility.md similarity index 100% rename from content/docs/installation/api-compatibility.md rename to content/docs/contributing/api-compatibility.md diff --git a/content/docs/contributing/crds.md b/content/docs/contributing/crds.md index 1cce203032c..586a68d2183 100644 --- a/content/docs/contributing/crds.md +++ b/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. diff --git a/content/docs/contributing/featuregates.md b/content/docs/contributing/featuregates.md index 4e6f3329674..50e3e1bb8b0 100644 --- a/content/docs/contributing/featuregates.md +++ b/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 `), 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) diff --git a/content/docs/installation/configuring-components.md b/content/docs/installation/configuring-components.md new file mode 100644 index 00000000000..061c982b74a --- /dev/null +++ b/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) diff --git a/content/docs/installation/featureflags.md b/content/docs/installation/featureflags.md deleted file mode 100644 index a3381d1f2a8..00000000000 --- a/content/docs/installation/featureflags.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Feature flags -description: Using feature gated functionality ---- - -New cert-manager features and functionality are often initially implemented behind a feature gate. This is so as to not break users with functionality that has not yet been tested in production as well as to give us a chance to remove or modify API fields and functionality following user feedback. - -We have alpha and beta features. We do not aim to keep any of the features in alpha or beta stage indefinitely. Feature gating should only be used for functionality that can eventually be turned on by default for all users (or, if it is opt-in, can be safely toggled on by any user with a supported cert-manager installation). - -A feature gate can be toggled on/off using `--feature-gates` flags on cert-manager controller. For feature gated functionality that comes with new API fields there is also a corresponding feature gate on webhook that also needs to be enabled using a `--feature-gates` flag if you want to use it. - -**Alpha** - -All alpha features are off by default. We retain the right to change or remove -alpha features without warning. An API field that is part of an alpha feature -and requires a webhook feature flag to be used also can also be removed from the -API without warning. An alpha feature might not work for all cert-manager's -supported Kubernetes versions. If you want to disable a previously enabled alpha -feature gate, you should make sure that you have updated any resources that have API -fields set that are only valid if the feature gate is enabled, else the resources -will end up in an invalid state. - -**Beta** - -All beta features are off by default. Beta features will not be removed, but may -be changed. If the feature gets changed in incompatible ways, we will provide -migration instructions. A beta feature will work with all cert-manager's -supported Kubernetes versions. If you want to disable a previously enabled beta -feature gate, you should make sure that you have updated any resources that have API -fields set that are only valid if the beta feature gate is on, else the resources -will end up in invalid state. - -**GA** - -A feature that is GA is on by default and cannot be disabled (unless it's opt in and toggled on/off by another mechanism, such as a flag). -With regards to API fields and their functionality, we keep Kubernetes API compatibility promise, see [API compatibility](./api-compatibility.md). -The feature flag for a GA feature might be left in place to avoid breaking folks, but will be non-functional. - -## Graduation - -The graduation criteria can be different for each feature. -Generally, we find user feedback most valuable when determining if a feature is sufficiently mature to graduate. If you are using an alpha or beta feature and would like to see it graduate, it would be great if you could give us some feedback about how you use it and whether you find the API useful to initiate graduation process. Feel free to [open a GitHub issue](https://github.com/cert-manager/cert-manager/issues/new/choose) or [join one of our meetings](../contributing/#meetings) to talk about this. - -## List of current feature gates - -### Alpha - -See `--feature-gates` flags on cert-manager controller and webhook to enable any of these features. - -- `AdditionalCertificateOutputFormats`. Added in cert-manager 1.7.0. Allows to specify additional formats in which cert-manager will store issued certificates and keys. See [release note](../releases/release-notes/release-notes-1.7.md#additional-certificate-output-formats). Requires the feature to be enabled on both cert-manager controller and webhook - -- `ExperimentalCertificateSigningRequestControllers`. Added in cert-manager - 1.4.0. Allows to use Kubernetes - [CertificateSigningRequest](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/) - resources with cert-manager. See [release notes](../releases/release-notes/release-notes-1.4.md#experimental-support-for-kubernetes-certificatesigningrequests) - -- `ExperimentalGatewayAPISupport`. Added in cert-manager 1.5.0. Allows to use cert-manager to automatically issue certificates for `Gateway` resources as well as use `Gateway`s and `HTTPRoute`s to solve ACME HTTP-01 challenges. See [Securing Gateway resources](../usage/gateway.md) - -- `LiteralCertificateSubject`. Added in cert-manager 1.9.0. Allows to specify certificate subject in a form that can be used to define a location in LDAP directory tree. See [release notes](../releases/release-notes/release-notes-1.9.md#literal-certificate-subjects) - -- `ServerSideApply`. Added in cert-manager 1.8.0. If this feature is enabled, cert-manager uses [Server side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/) when creating or updating API resources. This will speed cert-manager operations and prevent the resource version conflict errors. See [release notes](../releases/release-notes/release-notes-1.8.md#server-side-apply) - -- `UseCertificateRequestBasicConstraints`. Added in cert-manager 1.12.0. Makes cert-manager add a basic constraints section to certificate signing requests with the CA constraint set to the correct value. See [`cert-manager#5552`](https://github.com/cert-manager/cert-manager/pull/5552) - -- `ValidateCAA`. Added in cert-manager 0.7.2. CAA checking when issuing a certificate. - - -### Beta - -These features are enabled by default. See `--feature-gates` flags on cert-manager controller and webhook to disable any of these features. - -- `StableCertificateRequestName`. Alpha in v1.10 and Beta in v1.13. Enables generation of `CertificateRequest` resources with a fixed name. See [`cert-manager#5487`](https://github.com/cert-manager/cert-manager/pull/5487) - -- `SecretsFilteredCaching`. Alpha in v1.12 and Beta in v1.13. Reduces controller's memory consumption by filtering which Secrets are cached in full using `controller.cert-manager.io/fao` label. By default all Certificate Secrets are labelled with `controller.cert-manager.io/fao` label. Users can also label other Secrets, such as issuer credentials Secrets that they know cert-manager will need access to to speed up issuance. See [`20221205-memory-management.md`](https://github.com/cert-manager/cert-manager/blob/master/design/20221205-memory-management.md) - -- `DisallowInsecureCSRUsageDefinition`. Beta in v1.13. Prevents the webhook from allowing CertificateRequest's usages to be only defined in the CSR, while leaving the usages field empty. diff --git a/content/docs/installation/helm.md b/content/docs/installation/helm.md index 015c9aa875d..02a324bacfc 100644 --- a/content/docs/installation/helm.md +++ b/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 diff --git a/content/docs/installation/kubectl.md b/content/docs/installation/kubectl.md index 5f4caf8d7cf..405ece3db89 100644 --- a/content/docs/installation/kubectl.md +++ b/content/docs/installation/kubectl.md @@ -13,7 +13,9 @@ Learn how to install cert-manager using kubectl and static manifests. ## Steps -All resources (the [`CustomResourceDefinitions`](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) and the cert-manager, cainjector and webhook components) +### 1. Install from the cert-manager release manifest + +All resources (the CustomResourceDefinitions and the cert-manager, cainjector and webhook components) are included in a single YAML manifest file: Install all cert-manager components: @@ -26,23 +28,124 @@ By default, cert-manager will be installed into the `cert-manager` namespace. It is possible to run cert-manager in a different namespace, although you'll need to make modifications to the deployment manifests. -Once you have deployed cert-manager, you can [verify the installation](./verify.md). +Once you've installed cert-manager, you can verify it is deployed correctly by +checking the `cert-manager` namespace for running pods: + +```bash +$ kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +You should see the `cert-manager`, `cert-manager-cainjector`, and +`cert-manager-webhook` pods in a `Running` state. The webhook might take a +little longer to successfully provision than the others. + +If you experience problems, first check the [FAQ](../faq/README.md). + +### 2. (optional) Wait for cert-manager webhook to be ready + +The webhook component can take some time to start, and make the Kubernetes API server trust the webhook's certificate. + +First, make sure that [cmctl is installed](../reference/cmctl.md#installation). + +cmctl performs a dry-run certificate creation check against the Kubernetes cluster. +If successful, the message `The cert-manager API is ready` is displayed. + +```bash +$ cmctl check api +The cert-manager API is ready +``` + +The command can also be used to wait for the check to be successful. +Here is an output example of running the command at the same time that cert-manager is being installed: -## Permissions Errors on Google Kubernetes Engine +```bash +$ cmctl check api --wait=2m +Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server +Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server +Not ready: the cert-manager webhook deployment is not ready yet +Not ready: the cert-manager webhook deployment is not ready yet +Not ready: the cert-manager webhook deployment is not ready yet +Not ready: the cert-manager webhook deployment is not ready yet +The cert-manager API is ready +``` + + +### 2. (optional) End-to-end verify the installation + +Best way to fully verify the installation is to issue a test certificate. For this, we will create a self-signed issuer and a certificate resource in a test namespace. -When running on GKE (Google Kubernetes Engine), you might encounter a 'permission denied' error when creating some -of the required resources. This is a nuance of the way GKE handles RBAC and IAM permissions, -and as such you might need to elevate your own privileges to that of a "cluster-admin" **before** -running `kubectl apply`. -If you have already run `kubectl apply`, you should run it again after elevating your permissions: +```bash +$ cat < test-resources.yaml +apiVersion: v1 +kind: Namespace +metadata: + name: cert-manager-test +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: test-selfsigned + namespace: cert-manager-test +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: selfsigned-cert + namespace: cert-manager-test +spec: + dnsNames: + - example.com + secretName: selfsigned-cert-tls + issuerRef: + name: test-selfsigned +EOF +``` +Create the test resources. ```bash -kubectl create clusterrolebinding cluster-admin-binding \ - --clusterrole=cluster-admin \ - --user=$(gcloud config get-value core/account) +$ kubectl apply -f test-resources.yaml ``` +Check the status of the newly created certificate. You may need to wait a few +seconds before cert-manager processes the certificate request. +```bash +$ kubectl describe certificate -n cert-manager-test + +... +Spec: + Common Name: example.com + Issuer Ref: + Name: test-selfsigned + Secret Name: selfsigned-cert-tls +Status: + Conditions: + Last Transition Time: 2019-01-29T17:34:30Z + Message: Certificate is up to date and has not expired + Reason: Ready + Status: True + Type: Ready + Not After: 2019-04-29T17:34:29Z +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal CertIssued 4s cert-manager Certificate issued successfully +``` + +Clean up the test resources. +```bash +$ kubectl delete -f test-resources.yaml +``` + +If all the above steps have completed without error, you're good to go! + ## Uninstalling > **Warning**: To uninstall cert-manager you should always use the same process for > installing but in reverse. Deviating from the following process whether diff --git a/content/docs/installation/other-tools.md b/content/docs/installation/other-tools.md deleted file mode 100644 index 6d7b0b7044c..00000000000 --- a/content/docs/installation/other-tools.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Alternative installation methods -description: 'cert-manager installation: Other tools' ---- - -### kubeprod - -[Bitnami Kubernetes Production -Runtime](https://github.com/bitnami/kube-prod-runtime) (`BKPR`, `kubeprod`) is a -curated collection of the services you would need to deploy on top of your -Kubernetes cluster to enable logging, monitoring, certificate management, -automatic discovery of Kubernetes resources via public DNS servers and other -common infrastructure needs. - -It depends on `cert-manager` for certificate management, and it is [regularly -tested](https://github.com/bitnami/kube-prod-runtime/blob/master/Jenkinsfile) so -the components are known to work together for GKE, AKS, and EKS clusters. For -its ingress stack it creates a DNS entry in the configured DNS zone and requests -a TLS certificate from the Let's Encrypt staging server. - -BKPR can be deployed using the `kubeprod install` command, which will deploy -`cert-manager` as part of it. Details available in the [BKPR installation -guide](https://github.com/bitnami/kube-prod-runtime/blob/master/docs/install.md). \ No newline at end of file diff --git a/content/docs/installation/reinstall.md b/content/docs/installation/reinstall.md new file mode 100644 index 00000000000..9c544b37234 --- /dev/null +++ b/content/docs/installation/reinstall.md @@ -0,0 +1,33 @@ +--- +title: Reinstalling cert-manager +description: 'cert-manager installation: Reinstalling cert-manager overview' +--- + +In some cases there may be a need to do a full uninstall and re-install of +cert-manager. An example could be when a very old cert-manager version needs to +be brought up to date and it isn't feasible to upgrade one minor version at a +time, which is our default recommended upgrade strategy. + +If cert-manager `CustomResourceDefinition`s are also uninstalled, this will mean +loss of associated cert-manager custom resources such as `Certificate`s. The +main concern associated with this is application downtime and unnecessary +certificate reissuance, that could happen if `Secret`s with the X.509 +certificates get deleted. You can use [`--enable-certificate-owner-ref` +flag](https://cert-manager.io/docs/cli/controller/) +on the cert-manager controller to configure whether the `Secret`s should be deleted. +If this flag is set to true, each `Secret` will have an owner reference to the +`Certificate` for which it was created and when the `Certificate` is deleted, +the `Secret` will be garbage collected. The default value for this flag is +false. If the `Certificate`s get deleted and re-applied, but the `Secret`s remain +in the cluster, the newly applied `Certificate`s should be able to pick up the +same `Secret`s and should not unnecessarily reissue the X.509 certs. + +When uninstalling and re-installing in order to upgrade, you should still read +through the release notes for each skipped version. + +Some things to look out for when considering uninstalling and re-installing +cert-manager _including the CRDs_: + +- Is `--enable-certificate-owner-ref` flag currently set to true or could it have been set to true at some point previously? Due to an earlier bug, the owner reference that gets added to `Secret`s is _not_ removed when the value of `--enable-certificate-owner-ref` is changed from true to false, see [`cert-manager#4788`](https://github.com/cert-manager/cert-manager/issues/4788) +- Are there currently any certificate issuances in progress? If so, with the custom resources deleted, the progress will be lost. This could potentially cause duplicated issuances. +- Is there a need to convert cert-manager custom resource manifests to v1 API? You can use [`cmctl convert` command](../reference/cmctl.md#convert) to do that. diff --git a/content/docs/installation/uninstall.md b/content/docs/installation/uninstall.md index 404fb4b8e64..3ffc30772ca 100644 --- a/content/docs/installation/uninstall.md +++ b/content/docs/installation/uninstall.md @@ -1,5 +1,5 @@ --- -title: Uninstall +title: Uninstalling cert-manager description: 'cert-manager installation: Uninstalling cert-manager' --- diff --git a/content/docs/installation/upgrade.md b/content/docs/installation/upgrade.md index bff4e6cba6c..cc02cd1056b 100644 --- a/content/docs/installation/upgrade.md +++ b/content/docs/installation/upgrade.md @@ -1,5 +1,5 @@ --- -title: Upgrading +title: Upgrading cert-manager description: 'cert-manager installation: Upgrading cert-manager overview' --- @@ -87,7 +87,7 @@ number you want to install: kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.yaml ``` -Once you have deployed the new version of cert-manager, you can [verify](verify.md) the installation. +Once you have deployed the new version of cert-manager, you can [verify](kubectl.md#verify) the installation. ## Reinstalling cert-manager @@ -96,26 +96,4 @@ cert-manager. An example could be when a very old cert-manager version needs to be brought up to date and it isn't feasible to upgrade one minor version at a time, which is our default recommended upgrade strategy. -If cert-manager `CustomResourceDefinition`s are also uninstalled, this will mean -loss of associated cert-manager custom resources such as `Certificate`s. The -main concern associated with this is application downtime and unnecessary -certificate reissuance, that could happen if `Secret`s with the X.509 -certificates get deleted. You can use [`--enable-certificate-owner-ref` -flag](https://cert-manager.io/docs/cli/controller/) -on the cert-manager controller to configure whether the `Secret`s should be deleted. -If this flag is set to true, each `Secret` will have an owner reference to the -`Certificate` for which it was created and when the `Certificate` is deleted, -the `Secret` will be garbage collected. The default value for this flag is -false. If the `Certificate`s get deleted and re-applied, but the `Secret`s remain -in the cluster, the newly applied `Certificate`s should be able to pick up the -same `Secret`s and should not unnecessarily reissue the X.509 certs. - -When uninstalling and re-installing in order to upgrade, you should still read -through the release notes for each skipped version. - -Some things to look out for when considering uninstalling and re-installing -cert-manager _including the CRDs_: - -- Is `--enable-certificate-owner-ref` flag currently set to true or could it have been set to true at some point previously? Due to an earlier bug, the owner reference that gets added to `Secret`s is _not_ removed when the value of `--enable-certificate-owner-ref` is changed from true to false, see [`cert-manager#4788`](https://github.com/cert-manager/cert-manager/issues/4788) -- Are there currently any certificate issuances in progress? If so, with the custom resources deleted, the progress will be lost. This could potentially cause duplicated issuances. -- Is there a need to convert cert-manager custom resource manifests to v1 API? You can use [`cmctl convert` command](../reference/cmctl.md#convert) to do that. +See [Reinstalling cert-manager](reinstall.md) for a full guide on how to do this without any issues. diff --git a/content/docs/installation/verify.md b/content/docs/installation/verify.md deleted file mode 100644 index 4a169f1c953..00000000000 --- a/content/docs/installation/verify.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Verifying the Installation -description: 'cert-manager installation: Verifying an upgrade was successful' ---- - -## Check cert-manager API - -First, make sure that [cmctl is installed](../reference/cmctl.md#installation). - -cmctl performs a dry-run certificate creation check against the Kubernetes cluster. -If successful, the message `The cert-manager API is ready` is displayed. - -```bash -$ cmctl check api -The cert-manager API is ready -``` - -The command can also be used to wait for the check to be successful. -Here is an output example of running the command at the same time that cert-manager is being installed: - -```bash -$ cmctl check api --wait=2m -Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server -Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server -Not ready: the cert-manager webhook deployment is not ready yet -Not ready: the cert-manager webhook deployment is not ready yet -Not ready: the cert-manager webhook deployment is not ready yet -Not ready: the cert-manager webhook deployment is not ready yet -The cert-manager API is ready -``` - -## Manual verification - -Once you've installed cert-manager, you can verify it is deployed correctly by -checking the `cert-manager` namespace for running pods: - -```bash -$ kubectl get pods --namespace cert-manager - -NAME READY STATUS RESTARTS AGE -cert-manager-5c6866597-zw7kh 1/1 Running 0 2m -cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m -cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m -``` - -You should see the `cert-manager`, `cert-manager-cainjector`, and -`cert-manager-webhook` pods in a `Running` state. The webhook might take a -little longer to successfully provision than the others. - -If you experience problems, first check the [FAQ](../faq/README.md). - -Create an `Issuer` to test the webhook works okay. -```bash -$ cat < test-resources.yaml -apiVersion: v1 -kind: Namespace -metadata: - name: cert-manager-test ---- -apiVersion: cert-manager.io/v1 -kind: Issuer -metadata: - name: test-selfsigned - namespace: cert-manager-test -spec: - selfSigned: {} ---- -apiVersion: cert-manager.io/v1 -kind: Certificate -metadata: - name: selfsigned-cert - namespace: cert-manager-test -spec: - dnsNames: - - example.com - secretName: selfsigned-cert-tls - issuerRef: - name: test-selfsigned -EOF -``` - -Create the test resources. -```bash -$ kubectl apply -f test-resources.yaml -``` - -Check the status of the newly created certificate. You may need to wait a few -seconds before cert-manager processes the certificate request. -```bash -$ kubectl describe certificate -n cert-manager-test - -... -Spec: - Common Name: example.com - Issuer Ref: - Name: test-selfsigned - Secret Name: selfsigned-cert-tls -Status: - Conditions: - Last Transition Time: 2019-01-29T17:34:30Z - Message: Certificate is up to date and has not expired - Reason: Ready - Status: True - Type: Ready - Not After: 2019-04-29T17:34:29Z -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal CertIssued 4s cert-manager Certificate issued successfully -``` - -Clean up the test resources. -```bash -$ kubectl delete -f test-resources.yaml -``` - -If all the above steps have completed without error, you're good to go! - -## Community-maintained tool - -Alternatively, to automatically check if cert-manager is correctly configured, -you can run the community-maintained [cert-manager-verifier](https://github.com/alenkacz/cert-manager-verifier) tool. diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 4cacaff1465..75afe171c44 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -266,7 +266,6 @@ } ] }, - { "title": "0. Installation", "routes": [ @@ -274,10 +273,6 @@ "title": "Introduction", "path": "/docs/installation/README.md" }, - { - "title": "Cloud Compatibility", - "path": "/docs/installation/compatibility.md" - }, { "title": "a. kubectl apply", "path": "/docs/installation/kubectl.md" @@ -291,32 +286,20 @@ "path": "/docs/installation/operator-lifecycle-manager.md" }, { - "title": "d. Other tools", - "path": "/docs/installation/other-tools.md" - }, - { - "title": "Feature flags", - "path": "/docs/installation/featureflags.md" - }, - { - "title": "Best Practice", - "path": "/docs/installation/best-practice.md" - }, - { - "title": "Verify installation", - "path": "/docs/installation/verify.md" + "title": "Configuring Components", + "path": "/docs/installation/configuring-components.md" }, { "title": "Upgrade", "path": "/docs/installation/upgrade.md" }, { - "title": "Uninstall", - "path": "/docs/installation/uninstall.md" + "title": "Reinstall", + "path": "/docs/installation/reinstall.md" }, { - "title": "API compatibility", - "path": "/docs/installation/api-compatibility.md" + "title": "Uninstall", + "path": "/docs/installation/uninstall.md" }, { "title": "Signature Verification", @@ -588,6 +571,10 @@ { "title": "DevOps Tips", "routes": [ + { + "title": "Installing on a Cloud Provider", + "path": "/docs/installation/compatibility.md" + }, { "title": "Prometheus Metrics", "path": "/docs/devops-tips/prometheus-metrics.md" @@ -599,6 +586,10 @@ { "title": "Syncing Secrets Across Namespaces", "path": "/docs/devops-tips/syncing-secrets-across-namespaces.md" + }, + { + "title": "Best Practice Installation Options", + "path": "/docs/installation/best-practice.md" } ] }, @@ -675,7 +666,7 @@ "path": "/docs/contributing/kind.md" }, { - "title": "Implementing Feature Gates", + "title": "Feature gates", "path": "/docs/contributing/featuregates.md" }, { @@ -716,6 +707,10 @@ "title": "Signing Keys", "path": "/docs/contributing/signing-keys.md" }, + { + "title": "API compatibility", + "path": "/docs/contributing/api-compatibility.md" + }, { "title": "Importing cert-manager in Go", "path": "/docs/contributing/importing.md" diff --git a/content/docs/reference/cmctl.md b/content/docs/reference/cmctl.md index 0b3bfc957b5..3b795614274 100644 --- a/content/docs/reference/cmctl.md +++ b/content/docs/reference/cmctl.md @@ -282,7 +282,7 @@ cmctl x install \ ``` You can find [a full list of the install parameters on cert-manager's ArtifactHub page](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration). These are the same parameters that are available when using the Helm chart. -Once you have deployed cert-manager, you can [verify](../installation/verify.md) the installation. +Once you have deployed cert-manager, you can [verify](../installation/kubectl.md#verify) the installation. The CLI also allows the user to output the templated manifest to `stdout`, instead of installing the manifest on the cluster. diff --git a/public/_redirects b/public/_redirects index aedf467951d..8a893e2de4a 100644 --- a/public/_redirects +++ b/public/_redirects @@ -205,6 +205,12 @@ https://docs.cert-manager.io/* https://cert-manager.io/docs/:splat 302! /docs/projects/approver-policy/ /docs/policy/approval/approver-policy/ 301! /docs/projects/approver-policy/api-reference/ /docs/policy/approval/approver-policy/api-reference/ 301! +# Installation section cleanup +/docs/installation/other-tools/ /docs/installation/helm/ 301! +/docs/installation/verify/ /docs/installation/kubectl/ 301! +/docs/installation/featureflags/ /docs/installation/configuring-components/ 301! +/docs/installation/api-compatibility/ /docs/contributing/api-compatibility/ 301! + # Moved the "upgrading" and "release-notes" pages to the release section /docs/installation/upgrading/* /docs/releases/upgrading/:splat 301! /docs/release-notes/* /docs/releases/release-notes/:splat 301!