Skip to content

Commit

Permalink
reorganise 'Certificate resource' page
Browse files Browse the repository at this point in the history 
Signed-off-by: Tim Ramlot <[email protected]>
  • Loading branch information
@inteon
inteon committed Oct 17, 2023
1 parent 2d1d51c commit a28df9e
Showing 1 changed file with 147 additions and 137 deletions.
284 changes: 147 additions & 137 deletions content/docs/usage/certificate.md
View file
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,141 @@ 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>
### Renewal-triggered reissuance

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>
### Non-renewal-triggered reissuance

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>

## Issuance behavior

<a id="temporary-certificates-whilst-issuing"></a>
## Temporary Certificates while Issuing
### 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 +298,12 @@ Adding the following annotation on an ingress will automatically set "issue-temp
```

<a id="rotation-private-key"></a>
## Rotation of the private key
### 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 +343,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 +384,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

0 comments on commit a28df9e

Please sign in to comment.