Create redirects for cert-manager annotations by jsoref · Pull Request #1696 · cert-manager/website

jsoref · 2025-05-16T19:54:16Z

closes Create redirects for cert-manager annotations #1695

netlify · 2025-05-16T19:56:16Z

✅ Deploy Preview for cert-manager ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`994b6d0`
🔍 Latest deploy log	https://app.netlify.com/projects/cert-manager/deploys/684acd5879588100080e9ccc
😎 Deploy Preview	https://deploy-preview-1696--cert-manager.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

jsoref · 2025-05-16T21:40:47Z

The items I'm adding in https://github.com/cert-manager/website/compare/760f9a2acd142c1769b3b0abb2f6836de0d9eacc..0df5e31ae1be5665f4031951264453529e4b845e don't appear to be documented in the places I'd expect...

https://cert-manager.io/docs/usage/certificaterequest/ mentions annotations but doesn't document any
https://cert-manager.io/docs/usage/certificate/#inner-workings-diagram-for-developers mentions annotations but doesn't actually document them

jsoref · 2025-05-16T21:45:19Z

content/docs/configuration/annotations.md

+## cert-manager.io/inject-apiserver-ca
+
+cause the `cainjector` to inject the **CA certificate** for the Kubernetes apiserver into the resource.
+
+## cert-manager.io/inject-ca-from
+
+cause the `cainjector` to inject a certificate with **CA certificate**. ??
+
+## cert-manager.io/inject-ca-from-secret
+
+cause the `cainjector` to inject a **CA Certificate** from a secret.


I guess this stuff is documented in content/docs/concepts/ca-injector.md and I'll have to copy some content over and add cross links

jsoref · 2025-05-16T21:45:51Z

content/docs/configuration/annotations.md

+## cert-manager.io/next-private-key
+- `Secret`
+
+indicates the secret contains the private key for a certificate request issuance.


This is undocumented

content/docs/configuration/annotations.md

inteon · 2025-06-11T13:06:19Z

@jsoref There are also annotations that we add on the Secrets that we create (see https://github.com/cert-manager/cert-manager/blob/b80ca21f7e3b08c83b5cb546bfe4bff7a52c4975/pkg/apis/certmanager/v1/types.go)

jsoref · 2025-06-11T14:18:03Z

@inteon I have at least:

did I miss some others?

inteon · 2025-06-11T14:40:49Z

@inteon I have at least:

https://github.com/cert-manager/website/blob/0650e7cc99ae8b32aabfaf42e4eb0703c8ae92ba/content/docs/configuration/annotations.md#cert-managerioallow-direct-injection

https://github.com/cert-manager/website/blob/0650e7cc99ae8b32aabfaf42e4eb0703c8ae92ba/content/docs/configuration/annotations.md#cert-managerionext-private-key

did I miss some others?

These are two that I found are missing:

controller.cert-manager.io/fao
cert-manager.io/issuer-name
But there might be others.

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

public/_redirects

content/docs/configuration/annotations.md

content/docs/manifest.json

content/docs/configuration/annotations.md

* cert-manager.io * acme.cert-manager.io * experimental.cert-manager.io * venafi.cert-manager.io Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

SgtCoDFish

/lgtm
/approve

I think this is an improvement as-is and I recognise this has been open for a while. I have a few suggestions, but none are blockers and one of them (the redirect domain) might need this to be merged so it can be tested.

My instinct is to merge this and then if there are any tweaks needed to fix it after merging, so I'm going to approve this now with a hold - feel free to unhold so we can merge for testing!

SgtCoDFish · 2025-08-12T10:46:03Z

public/_redirects

+# There should be cnames to cert-manager.io (as well as configuration in netlify) for each of these
+# to enable these to work in the same manner.


suggestion: We could link here to where the CNAMEs are defined: https://github.com/cert-manager/infrastructure/blob/2d77f6b97249f4d41cd5547ad90f0e2f4ffd6c58/gcp/general_dns_cert-manager.tf

Not a blocker, but it makes sense to me to link the two.

SgtCoDFish · 2025-08-12T10:53:37Z

public/_redirects

+# note that the kubernetes.io entries will not have real CNAMEs and are merely for consistency, but if someone does talk to this netifly instance, it should work.
+https://kubernetes.io/ingress.class /docs/configuration/annotations#kubernetesio/ingressclass 301!
+https://kubernetes.io/tls-acme /docs/configuration/annotations#kubernetesio/tls-acme 301!


suggestion: I don't think we should list these kubernetes ones as entries here, since we can never make these work for our domain. I'm OK with them being here as comments, but I find this more confusing to have actual redirect rules listed for a domain we don't control.

SgtCoDFish · 2025-08-12T10:57:01Z

public/_redirects

+https://acme.cert-manager.io/http01-edit-in-place /docs/configuration/annotations#acmecert-managerio/http01-edit-in-place 301!
+https://acme.cert-manager.io/http01-ingress-class /docs/configuration/annotations#acmecert-managerio/http01-ingress-class 301!
+
+https://experimental.cert-manager.io/request-duration /docs/configuration/annotations#experimentalcert-managerio/request-duration 301!
+https://experimental.cert-manager.io/request-is-ca /docs/configuration/annotations#experimentalcert-managerio/request-is-ca 301!
+https://experimental.cert-manager.io/private-key-secret-name /docs/configuration/annotations#experimentalcert-managerio/private-key-secret-name 301!
+
+https://venafi.cert-manager.io/custom-fields /docs/configuration/annotations#venaficert-managerio/custom-fields 301!
+https://venafi.cert-manager.io/pickup-id /docs/configuration/annotations#venaficert-managerio/pickup-id 301!


suggestion: I'm pretty sure that as written these rules will still keep the subdomain in the address; e.g. https://venafi.cert-manager.io/pickup-id will redirect to https://venafi.cert-manager.io/docs/configuration/annotations#venaficert-managerio/pickup-id. We might need to add https://cert-manager.io as a prefix to the targets - but I'm not 100% sure and maybe the best thing to do is merge and fix if it's wrong.

Now this is live I tried https://experimental.cert-manager.io/request-duration which redirected me to https://experimental.cert-manager.io/docs/configuration/annotations#experimentalcert-managerio/request-duration and the path is wrong as well as the domain (it 404s)

SgtCoDFish · 2025-08-12T10:58:13Z

public/_redirects

+https://acme.cert-manager.io/http01-edit-in-place /docs/configuration/annotations#acmecert-managerio/http01-edit-in-place 301!
+https://acme.cert-manager.io/http01-ingress-class /docs/configuration/annotations#acmecert-managerio/http01-ingress-class 301!
+
+https://experimental.cert-manager.io/request-duration /docs/configuration/annotations#experimentalcert-managerio/request-duration 301!
+https://experimental.cert-manager.io/request-is-ca /docs/configuration/annotations#experimentalcert-managerio/request-is-ca 301!
+https://experimental.cert-manager.io/private-key-secret-name /docs/configuration/annotations#experimentalcert-managerio/private-key-secret-name 301!
+
+https://venafi.cert-manager.io/custom-fields /docs/configuration/annotations#venaficert-managerio/custom-fields 301!
+https://venafi.cert-manager.io/pickup-id /docs/configuration/annotations#venaficert-managerio/pickup-id 301!


suggestion: For the subdomain redirects, should we have a catch-all redirect for unknown paths to https://cert-manager.io/docs ? Does that make sense?

cert-manager-prow · 2025-08-12T11:02:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: SgtCoDFish

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [SgtCoDFish]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

SgtCoDFish · 2025-08-12T11:03:55Z

I... didn't add the hold. So I guess we can just fix anything we find :D

inteon · 2025-08-12T12:48:52Z

public/_redirects

+
+# There should be cnames to cert-manager.io (as well as configuration in netlify) for each of these
+# to enable these to work in the same manner.
+https://acme.cert-manager.io/http01-edit-in-place /docs/configuration/annotations#acmecert-managerio/http01-edit-in-place 301!


Suggested change

https://acme.cert-manager.io/http01-edit-in-place /docs/configuration/annotations#acmecert-managerio/http01-edit-in-place 301!

https://acme.cert-manager.io/http01-edit-in-place https://cert-manager.io/docs/reference/annotations#acmecert-manageriohttp01-edit-in-place 301!

maelvls · 2026-02-27T13:13:02Z

content/docs/reference/annotations.md

+## cert-manager.io/alt-names
+- [Certificate](../usage/certificate.md)
+
+this annotation allows you to configure `spec.dnsNames` field for
+the Certificate to be generated.
+Supports comma-separated values e.g. "example.com,example.org"


I came across this today, I'm not sure I understand this annotation.

Doesn't cert-manager.io/alt-names belong to the Secret resource?

Looking at internal/controller/certificates/secrets.go, the only place this annotation is ever used is when the "secret" controller creates a Secret out of a given Certificate.

This annotation can't be used in the Issuer's secretTemplate, either.

I think the description should be:

Suggested change

## cert-manager.io/alt-names

- [Certificate](../usage/certificate.md)

this annotation allows you to configure `spec.dnsNames` field for

the Certificate to be generated.

Supports comma-separated values e.g. "example.com,example.org"

## cert-manager.io/alt-names

- Secret

This annotation is managed by cert-manager and appears on the Secret resource. It is copied by cert-manager from the Certificate's `spec.dnsNames`.

I've seen people looking for ways to add extra SANs in cert-manager/cert-manager#5897 and cert-manager/cert-manager#6190, but this feature hasn't landed yet.

WDYT? @jsoref

@maelvls: Yes, I think that's right. Although I wish spec.dnsNames was a link to something.

cert-manager-prow bot added dco-signoff: yes Indicates that all commits in the pull request have the valid DCO sign-off message. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 16, 2025

jsoref force-pushed the annotations branch 5 times, most recently from 760f9a2 to 0df5e31 Compare May 16, 2025 21:36

jsoref force-pushed the annotations branch from 0df5e31 to 0650e7c Compare May 16, 2025 21:43

cert-manager-prow bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 16, 2025

jsoref commented May 16, 2025

View reviewed changes

inteon reviewed Jun 11, 2025

View reviewed changes

content/docs/configuration/annotations.md Show resolved Hide resolved

inteon reviewed Jun 11, 2025

View reviewed changes

content/docs/configuration/annotations.md Show resolved Hide resolved

jsoref force-pushed the annotations branch from 0650e7c to a32ffb6 Compare June 11, 2025 14:43

jsoref mentioned this pull request Jun 11, 2025

Add cnames for domains used by annotations cert-manager/infrastructure#58

Merged

jsoref force-pushed the annotations branch 2 times, most recently from 3a5a3d9 to d37764f Compare June 11, 2025 20:21

jsoref added 6 commits June 11, 2025 16:24

chore(docs): Remove leading space in backticks

2095df4

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

docs: Fix typo in gateway docs

d32b1db

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

docs: Harmonize Ingress+Gateway docs

3b6b531

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

chore(docs): Add backticks

2e170bb

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

chore(docs): Fix punctuation

d0cac09

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

spelling: certificate

036c7df

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

jsoref force-pushed the annotations branch from d37764f to 0e2a51c Compare June 11, 2025 20:26

jsoref requested a review from inteon June 11, 2025 22:55

inteon reviewed Jun 12, 2025

View reviewed changes

public/_redirects Outdated Show resolved Hide resolved

inteon reviewed Jun 12, 2025

View reviewed changes

content/docs/configuration/annotations.md Outdated Show resolved Hide resolved

inteon reviewed Jun 12, 2025

View reviewed changes

content/docs/manifest.json Outdated Show resolved Hide resolved

inteon reviewed Jun 12, 2025

View reviewed changes

content/docs/configuration/annotations.md Outdated Show resolved Hide resolved

jsoref force-pushed the annotations branch from 0e2a51c to 1892e38 Compare June 12, 2025 12:39

jsoref added 2 commits June 12, 2025 08:51

Document resource annotations

b3ff70d

* cert-manager.io * acme.cert-manager.io * experimental.cert-manager.io * venafi.cert-manager.io Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

Let netlify try to answer questions about kubernetes.io annotations

994b6d0

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

jsoref force-pushed the annotations branch from 1892e38 to 994b6d0 Compare June 12, 2025 12:51

jsoref mentioned this pull request Jun 12, 2025

The ingress annotation cert-manager.io/secret-template is not documented #1715

Open

jsoref requested a review from inteon June 12, 2025 16:12

SgtCoDFish approved these changes Aug 12, 2025

View reviewed changes

cert-manager-prow bot added the lgtm Indicates that a PR is ready to be merged. label Aug 12, 2025

cert-manager-prow bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 12, 2025

cert-manager-prow bot merged commit d694058 into cert-manager:master Aug 12, 2025
7 checks passed

inteon reviewed Aug 12, 2025

View reviewed changes

jsoref mentioned this pull request Aug 12, 2025

Redirect followup #1737

Merged

jsoref deleted the annotations branch August 13, 2025 13:04

maelvls reviewed Feb 27, 2026

View reviewed changes

		# There should be cnames to cert-manager.io (as well as configuration in netlify) for each of these
		# to enable these to work in the same manner.

	https://acme.cert-manager.io/http01-edit-in-place /docs/configuration/annotations#acmecert-managerio/http01-edit-in-place 301!
	https://acme.cert-manager.io/http01-edit-in-place https://cert-manager.io/docs/reference/annotations#acmecert-manageriohttp01-edit-in-place 301!

Conversation

jsoref commented May 16, 2025

Uh oh!

netlify bot commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cert-manager ready!

Uh oh!

jsoref commented May 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

inteon commented Jun 11, 2025

Uh oh!

jsoref commented Jun 11, 2025

Uh oh!

inteon commented Jun 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SgtCoDFish left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cert-manager-prow bot commented Aug 12, 2025

Uh oh!

Uh oh!

SgtCoDFish commented Aug 12, 2025

Uh oh!

inteon Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maelvls Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented May 16, 2025 •

edited

Loading

inteon Aug 12, 2025 •

edited

Loading

maelvls Feb 27, 2026 •

edited

Loading