cert-manager / sample-external-issuer

A sample external Issuer for cert-manager

cert-manager

cert-manager adds certificates and certificate issuers as resource types in Kubernetes clusters, and simplifies the process of obtaining, renewing and using those certificates.

It supports issuing certificates from a variety of sources, including Let's Encrypt (ACME), HashiCorp Vault, and Venafi TPP / TLS Protect Cloud, as well as local in-cluster issuance.

cert-manager also ensures certificates remain valid and up to date, attempting to renew certificates at an appropriate time before expiry to reduce the risk of outages and remove toil.

Documentation

Documentation for cert-manager can be found at cert-manager.io.

For the common use-case of automatically issuing TLS certificates for Ingress resources, see the cert-manager nginx-ingress quick start guide.

For a more comprehensive guide to issuing your first certificate, see our getting started guide.

Installation

Installation is documented on the website, with a variety of supported methods.

Developing cert-manager

We actively welcome contributions and we support both Linux and macOS environments for development.

Different platforms have different requirements; we document everything on our Building cert-manager website page.

Note in particular that macOS has several extra requirements, to ensure that modern tools are installed and available. Read the page before getting started!

Troubleshooting

If you encounter any issues whilst using cert-manager, we have a number of ways to get help:

• A troubleshooting guide on our website.
• Our official Kubernetes Slack channel - the quickest way to ask! (#cert-manager and #cert-manager-dev)
• Searching for an existing issue.

If you believe you've found a bug and cannot find an existing issue, feel free to open a new issue! Be sure to include as much information as you can about your environment.

Community

The cert-manager-dev Google Group is used for project wide announcements and development coordination. Anybody can join the group by visiting here and clicking "Join Group". A Google account is required to join the group.

Meetings

We have several public meetings which any member of our Google Group is more than welcome to join!

Check out the details on our website. Feel free to drop in and ask questions, chat with us or just to say hi!

Contributing

We welcome pull requests with open arms! There's a lot of work to do here, and we're especially concerned with ensuring the longevity and reliability of the project. The contributing guide will help you get started.

Coding Conventions

Code style guidelines are documented on the coding conventions page of the cert-manager website. Please try to follow those guidelines if you're submitting a pull request for cert-manager.

Importing cert-manager as a Module

⚠️ Please note that cert-manager does not currently provide a Go module compatibility guarantee. That means that most code under pkg/ is subject to change in a breaking way, even between minor or patch releases and even if the code is currently publicly exported.

The lack of a Go module compatibility guarantee does not affect API version guarantees under the Kubernetes Deprecation Policy.

For more details see Importing cert-manager in Go on the cert-manager website.

The import path for cert-manager versions 1.8 and later is github.com/cert-manager/cert-manager.

For all versions of cert-manager before 1.8, including minor and patch releases, the import path is github.com/jetstack/cert-manager.

Security Reporting

Security is the number one priority for cert-manager. If you think you've found a security vulnerability, we'd love to hear from you.

Follow the instructions in SECURITY.md to make a report.

Changelog

Every release on GitHub has a changelog, and we also publish release notes on the website.

History

cert-manager is loosely based upon the work of kube-lego and has borrowed some wisdom from other similar projects such as kube-cert-manager.

_{^{Logo design by Zoe Paterson}}

sample-external-issuer's Issues

Create Kubernetes Events logging significant operations and errors

We should create Kubernetes Events linked to the Sample Issuer and ClusterIssuer resources,
and events linked to the CertificateRequests that the issuer operates on.

This will make it easier for an administrator to understand what the issuer is doing and it will make errors even easier to diagnose, because the warning events will show up in kubectl describe issuer and kubectl describe certificaterequest.

Add CI to run tests automatically on pull requests

Take a look at what @jakexks did in https://github.com/jetstack/google-cas-issuer/tree/main/.github/workflows and copy / adapt it

Controller process should run as non-root user

Controller Deployment should set runAsNonRoot and the Docker image should set the default user to a non-root user.

In cert-manager/cert-manager#4036 I have to work around this by configuring Kyverno to ignore the sample-external-issuer namespace.

Update CRDs to apiextensions.k8s.io/v1

Currently:

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.2.5

So it might just require a newer version of controller-tools which is currently at 0.5.0.
v1 CRDs were introduced in 0.4.0:

• https://github.com/kubernetes-sigs/controller-tools/releases/tag/v0.4.0

Question: figuring this out as I go, could use a little guidence on this step: add 'kubebuilder CRD Markers'

I have a very short bash and powershell script which I currently use to generate certificates in my kubernetes cluster, they are so small and simple that it seems like if I can just get the sample issuer customized I should be able to add what little code is needed to create a working issuer for my environment which I could then share and support for the community.

Could I get just a little more detail on this step? I see the comment it is specifying '// +kubebuilder:subresource:status' is already in the file its asking me to modify. Is that what I need to add? Has it already been added automatically and the documentation just needs to be updated? Do I need to add in multiple places? Just looking for a little guidence. Please don't just give me a link to https://book.kubebuilder.io/reference/markers/crd.html, I saw the link and have clicked on it, thank you ahead of time. Maybe the answer is I need to go off and learn go for a couple months. If so I let me know and I can move on till I have time. Was hoping I might be able to learn just enough to get things going for now.

api/v1alpha1/{cluster}issuer_types.go: Add Kubebuilder CRD Markers to allow modification of IssuerStatus as a Status Subresource: 
// +kubebuilder:subresource:status

Question: enable Server-Side Apply (SSA)

Hello,
we developed a custom issuer from the sample in this repository.

While testing our custom issuer, we encountered a bug which causes spurious reconcile loops in the RetryOnConflict function we use.
For some reason we still don't understand, the certificaterequest annotations changes are not always applied and the following Reconcile loop does not see them, causing a new API request to our backend.
This is a problem, since API requests must only be performed once per certificaterequest.

We posted the issue on the cert-manager issue tracker and we have been advised to enable Server-Side Apply.

Can it be enabled by changing a setting in the operator configuration (kubebuilder or client-go)?
In any case, could you please provide an example?

Thanks!

Publish a Docker image to a public cert-manager registry

The current image was uploaded manually by @wallrj to his own container registry.

It should be published to a cert-manager registry or to Github GCR in this repo.

Update controller-runtime

Use the latest version of controller-runtime