Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganise 'Certificate resource' page #1327

Merged
merged 3 commits into from
Nov 5, 2023
+142 −137
Merged

Reorganise 'Certificate resource' page #1327

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a28df9e
reorganise 'Certificate resource' page
inteon Oct 13, 2023
5c342f4
improve reissuance titles & content
inteon Oct 18, 2023
beca288
link to details about reissuance & flatten title structure
inteon Oct 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 142 additions & 137 deletions content/docs/usage/certificate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,14 @@ description: 'cert-manager usage: Certificates'
> **apiVersion:** cert-manager.io/v1
> **kind:** Certificate

In cert-manager, the [`Certificate`](../concepts/certificate.md) resource
represents a human readable definition of a certificate request that is to be
honored by an issuer which is to be kept up-to-date. This is the usual way that
you will interact with cert-manager to request signed certificates.
In cert-manager, the `Certificate` resource represents a human readable definition
of a certificate request. cert-manager uses this input to generate a private key
and [`CertificateRequest`](./certificaterequest.md) resource in order to obtain
a signed certificate from an [`Issuer`](../configuration/README.md) or
[`ClusterIssuer`](../configuration/README.md). The signed certificate and private
key are then stored in the specified `Secret` resource. cert-manager will ensure
that the certificate is [auto-renewed before it expires](#renewal-reissuance) and
[re-issued if requested](#non-renewal-reissuance).

In order to issue any certificates, you'll need to configure an
[`Issuer`](../configuration/README.md) or [`ClusterIssuer`](../configuration/README.md)
Expand Down Expand Up @@ -121,7 +125,7 @@ A full list of the fields supported on the Certificate resource can be found in
the [API reference documentation](../reference/api-docs.md#cert-manager.io/v1.CertificateSpec).

<a id="key-usages"></a>
## X.509 key usages and extended key usages
### X.509 key usages and extended key usages

cert-manager supports requesting certificates that have a number of [custom key
usages](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) and [extended key
Expand All @@ -138,8 +142,136 @@ certificate does not match the current key usage set.
An exhaustive list of supported key usages can be found in the [API reference
documentation](../reference/api-docs.md#cert-manager.io/v1.KeyUsage).


### Additional Certificate Output Formats

<div className="warning">

⛔️ The additional certificate output formats feature is currently in an
_experimental_ alpha state, and is subject to breaking changes or complete
removal in future releases. This feature is only enabled by adding it to the
`--feature-gates` flag on the cert-manager controller and webhook components:

```bash
--feature-gates=AdditionalCertificateOutputFormats=true
```

</div>

`additionalOutputFormats` is a field on the Certificate `spec` that allows
specifying additional supplementary formats of issued certificates and their
private key. There are currently two supported additional output formats:
`CombinedPEM` and `DER`. Both output formats can be specified on the same
Certificate.

```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
spec:
...
secretName: my-cert-tls
additionalOutputFormats:
- type: CombinedPEM
- type: DER

# Results in:

apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
ca.crt: <PEM CA certificate>
tls.key: <PEM private key>
tls.crt: <PEM signed certificate chain>
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
key.der: <DER binary format of private key>
```

#### `CombinedPEM`

The `CombinedPEM` type will create a new key entry in the resulting
Certificate's Secret `tls-combined.pem`. This entry will contain the PEM encoded
private key, followed by at least one new line character, followed by the PEM
encoded signed certificate chain-

```text
<private key> + "\n" + <signed certificate chain>
```

```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
...
```

#### `DER`

The `DER` type will create a new key entry in the resulting Certificate's Secret
`key.der`. This entry will contain the DER binary format of the private key.

```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
key.der: <DER binary format of private key>
...
```

## Issuance triggers

<a id="renewal-reissuance"></a>
### Reissuance triggered by expiry (renewal)

cert-manager will automatically renew `Certificate`s. It will calculate _when_ to renew a `Certificate` based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed.

`spec.duration` and `spec.renewBefore` fields on a `Certificate` can be used to specify an X.509 certificate's duration and a 'renewBefore' value. Default value for `spec.duration` is 90 days. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different.
Minimum value for `spec.duration` is 1 hour and minimum value for `spec.renewBefore` is 5 minutes.
It is also required that `spec.duration` > `spec.renewBefore`.

Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the `Certificate`. By default this will be 2/3 through the X.509 certificate's duration. If `spec.renewBefore` has been set, it will be `spec.renewBefore` amount of time before expiry. cert-manager will set `Certificate`'s `status.RenewalTime` to the time when the renewal will be attempted.

<a id="non-renewal-reissuance"></a>
<a id="actions-triggering-private-key-rotation"></a>
### Reissuance triggered by user actions

A certificate object is reissued under the following circumstances:

- when a change is made to one of the following fields on the Certificate's
spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`,
`subject`, `isCA`, `usages`, `duration` or `issuerRef`;
A more detailed explanation can be found on the [FAQ page](../faq/README.md#when-do-certs-get-re-issued).
- when a reissuance is manually triggered with the following:
```sh
cmctl renew cert-1
```
Note that the above command requires [cmctl](../reference/cmctl.md#renew).

<div className="warning">

**❌** Deleting the Secret resource associated with a Certificate resource is
**not a recommended solution** for manually rotating the private key. The
recommended way to manually rotate the private key is to trigger the reissuance
of the Certificate resource with the following command (requires
[`cmctl`](../reference/cmctl.md#renew)):

```sh
cmctl renew cert-1
```

</div>

<a id="temporary-certificates-whilst-issuing"></a>
## Temporary Certificates while Issuing
## Issuance behavior: Temporary Certificates while Issuing

When requesting certificates [using the ingress-shim](./ingress.md), the
component `ingress-gce`, if used, requires that a temporary certificate is
Expand All @@ -161,13 +293,12 @@ Adding the following annotation on an ingress will automatically set "issue-temp
```

<a id="rotation-private-key"></a>
## Rotation of the private key
## Issuance behavior: Rotation of the private key

By default, the private key won't be rotated automatically. Using the setting
`rotationPolicy: Always`, the private key Secret associated with a Certificate
object can be configured to be rotated as soon as an action triggers the
reissuance of the Certificate object (see
[Actions that will trigger a rotation of the private key](#actions-triggering-private-key-rotation) below).
object can be configured to be rotated as soon as an the Certificate is reissued (see
[Issuance triggers](#issuance-triggers)).

With `rotationPolicy: Always`, cert-manager waits until the Certificate
object is correctly signed before overwriting the `tls.key` file in the
Expand Down Expand Up @@ -207,39 +338,7 @@ spec:
rotationPolicy: Always # 🔰 Here.
```

<a id="actions-triggering-private-key-rotation"></a>
### Actions that will trigger a rotation of the private key

Setting the `rotationPolicy: Always` won't rotate the private key immediately.
In order to rotate the private key, the certificate objects must be reissued. A
certificate object is reissued under the following circumstances:

- when the X.509 certificate is nearing expiry, which is when the Certificate's
`status.renewalTime` is reached;
- when a change is made to one of the following fields on the Certificate's
spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`,
`subject`, `isCA`, `usages`, `duration` or `issuerRef`;
- when a reissuance is manually triggered with the following:
```sh
cmctl renew cert-1
```
Note that the above command requires [cmctl](../reference/cmctl.md#renew).

<div className="warning">

**❌** Deleting the Secret resource associated with a Certificate resource is
**not a recommended solution** for manually rotating the private key. The
recommended way to manually rotate the private key is to trigger the reissuance
of the Certificate resource with the following command (requires
[`cmctl`](../reference/cmctl.md#renew)):

```sh
cmctl renew cert-1
```

</div>

### The `rotationPolicy` setting
#### The `rotationPolicy` setting

The possible values for `rotationPolicy` are:

Expand Down Expand Up @@ -280,100 +379,6 @@ The `Secret` needs to be manually deleted if it is no longer needed.

If you would prefer the `Secret` to be deleted automatically when the `Certificate` is deleted, you need to configure your installation to pass the `--enable-certificate-owner-ref` flag to the controller.

## Renewal

cert-manager will automatically renew `Certificate`s. It will calculate _when_ to renew a `Certificate` based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed.

`spec.duration` and `spec.renewBefore` fields on a `Certificate` can be used to specify an X.509 certificate's duration and a 'renewBefore' value. Default value for `spec.duration` is 90 days. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different.
Minimum value for `spec.duration` is 1 hour and minimum value for `spec.renewBefore` is 5 minutes.
It is also required that `spec.duration` > `spec.renewBefore`.

Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the `Certificate`. By default this will be 2/3 through the X.509 certificate's duration. If `spec.renewBefore` has been set, it will be `spec.renewBefore` amount of time before expiry. cert-manager will set `Certificate`'s `status.RenewalTime` to the time when the renewal will be attempted.

## Additional Certificate Output Formats

<div className="warning">

⛔️ The additional certificate output formats feature is currently in an
_experimental_ alpha state, and is subject to breaking changes or complete
removal in future releases. This feature is only enabled by adding it to the
`--feature-gates` flag on the cert-manager controller and webhook components:

```bash
--feature-gates=AdditionalCertificateOutputFormats=true
```

</div>

`additionalOutputFormats` is a field on the Certificate `spec` that allows
specifying additional supplementary formats of issued certificates and their
private key. There are currently two supported additional output formats:
`CombinedPEM` and `DER`. Both output formats can be specified on the same
Certificate.

```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
spec:
...
secretName: my-cert-tls
additionalOutputFormats:
- type: CombinedPEM
- type: DER

# Results in:

apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
ca.crt: <PEM CA certificate>
tls.key: <PEM private key>
tls.crt: <PEM signed certificate chain>
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
key.der: <DER binary format of private key>
```

#### `CombinedPEM`

The `CombinedPEM` type will create a new key entry in the resulting
Certificate's Secret `tls-combined.pem`. This entry will contain the PEM encoded
private key, followed by at least one new line character, followed by the PEM
encoded signed certificate chain-

```text
<private key> + "\n" + <signed certificate chain>
```

```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
...
```

#### `DER`

The `DER` type will create a new key entry in the resulting Certificate's Secret
`key.der`. This entry will contain the DER binary format of the private key.

```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
key.der: <DER binary format of private key>
...
```

## Inner workings diagram for developers

<object data="/images/request-certificate-debug/certificate-flow.svg"></object>
Expand Down