1<p align="center">
2 <img src="https://raw.githubusercontent.com/cert-manager/cert-manager/d53c0b9270f8cd90d908460d69502694e1838f5f/logo/logo-small.png" height="256" width="256" alt="cert-manager project logo" />
3</p>
4<p align="center">
5 <a href="https://godoc.org/github.com/cert-manager/issuer-lib"><img src="https://godoc.org/github.com/cert-manager/issuer-lib?status.svg" alt="cert-manager/issuer-lib godoc"></a>
6 <a href="https://goreportcard.com/report/github.com/cert-manager/issuer-lib"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/cert-manager/issuer-lib" /></a>
7</p>
8
9# cert-manager issuer-lib
10
11> issuer-lib is the Go library for building cert-manager issuers.
12
13## Stability disclaimer
14
15⚠️ Warning: This library's API is still subject to change. Developers using this library will have to update their
16code when updating to a newer version.
17
180. Currently, this library is used to build production Issuers, but no open-source Issuers/ examples are available yet. We advise to use this library only for experimentation.
191. Once we have an open-source Issuer
20that uses this library & we have an example project that shows how to use this library, we will start advising developers to build all new issuers on top of this library.
212. Once we have a 2nd or 3rd open-source Issuer that uses this library, we should be able to guarantee more stability.
22At this point, we will start advising developers to migrate their existing Issuers to this library.
233. At 5+ open-source Issuers, we plan to make a stable v1 release of this library.
24
25## Introduction
26
27cert-manager issuers are responsible for watching CertificateRequest resources and updating
28their status with the signed certificate data. An issuer must only respond to
29CertificateRequests that have an IssuerRef that matches the Name, Kind and group
30of one of its Issuer resources. Additionally, the CertificateRequest must have been approved.
31
32This library provides all the controllers necessary to implement a cert-manager
33issuer, these controllers contain all the common logic required to implement
34an issuer. The only thing you need to provide is the business logic for
35communicating with your CA, this is done by implementing the `Sign` and `Check`
36functions.
37
38## Goals
39
40This library makes it easy to create a cert-manager issuer that integrates with
41your CA.
42
43It takes care of:
44
45- Watching CertificateRequests and your custom Issuer resources
46- Updating the Issuer status with status of the CA
47- Updating the CertificateRequest status with the signed certificate data
48- Handling errors and retries
49- Handling CertificateRequest approval and denial
50- Handling issuance of Kubernetes CSR resources
51- [FUTURE] Provide a set of conformance tests for issuers
52
53## Usage
54
55An example issuer implementation can be found in the [`./examples/simple`](./examples/simple) subdirectory.
56
57## Log levels
58
59The library relies on the log levels defined in `logr`, i.e., numbers from 0 to
609\. You can use any logging library you like in your controller as long as the
61levels "match". The two only logr levels used in issuer-lib are 0 ("info") and 1
62("debug").
63
64For example, the message "Succeeded signing the CertificateRequest" is logged at
65the level 0 ("info"). To integrate well with issuer-lib, your controller should
66also use the level 0 when logging messages that inform the user about changes to
67the CertificateRequest.
68
69## How it works
70
71This repository provides a go libary that you can use for creating cert-manager controllers for your own Issuers.
72
73To use the libary, your Issuer API types have to implement the `v1alpha1.Issuer` interface.
74The business logic of the controllers can be provided to the libary through the `Check` and `Sign` functions.
75- The `Check` function is used by the Issuer controllers.
76If it returns a normal error, the controller will retry with backoff until the `Check` function succeeds.
77If the error is of type `signer.PermanentError`, the controller will not retry automatically. Instead, an increase in Generation is required to recheck the issuer.
78
79- The `Sign` function is used by the CertificateRequest controller.
80If it returns a normal error, the `Sign` function will be retried as long as we have not spent more than the configured `MaxRetryDuration` after the certificate request was created.
81If the error is of type `signer.IssuerError`, the error is an error that should be set on the issuer instead of the CertificateRequest.
82If the error is of type `signer.SetCertificateRequestConditionError`, the controller will, additional to setting the ready condition, also set the specified condition. This can be used in case we have to store some additional state in the status.
83If the error is of type `signer.PermanentError`, the controller will not retry automatically. Instead, a new CertificateRequest has to be created.
84
85## Reconciliation loops
86
87The reconciliation function of the CertificateRequest controller will:
881. wait for the request to be Approved/ Denied
892. only consider the configured Issuer API types
903. leave Ready/ Failed/ Denied CertificateRequests as-is
914. start by setting the Ready condition to Initializing
925. set the Ready condition to Denied if the CertificateRequest is denied
936. wait for the linked Issuer to exist and be in an up-to-date Ready state
947. call the `Sign` function and handle errors as described above
958. update the CertificateRequest with the returned Signed Certificate and set the state to Ready
96
97The reconciliation function of the Issuer controllers will:
981. only reconcile if the Ready condition is not "failed permanently" or the CertificateRequest controller notified that the Ready condition is no longer valid
992. if the issuer status is Ready and we received an issuer error from the CertificateRequest controller, set the Ready condition to false and set the error
1003. start by setting the Ready condition to Initializing
1014. call the `Check` function and handle errors as described above
1025. update the Issuer by setting the state to Ready
103
104Note that a reconciliation will only be triggered:
105- for CertificateRequests:
106 - on create
107 - on update when an annotation is changed/ added or removed
108 - on update when a condition is added or removed
109 - on update when a non-readiness condition is changed
110 - on update when the Ready condition of the linked Issuer is changed/ added or removed
111 - when triggered in the previous reconciliation
112
113- for Issuers:
114 - on create
115 - on update when an annotation is changed/ added or removed
116 - on update when the generation (.Spec) changes
117 - on update when the Ready condition was added/ removed
118 - when triggered in the previous reconciliation
View as plain text