Cert-manager中为ACME挑战Ingress资源添加自定义注解的实践

在Kubernetes环境中使用cert-manager进行证书管理时，经常会遇到需要为ACME挑战相关的Ingress资源添加特定注解的场景。本文将深入探讨这一需求的背景、解决方案以及最佳实践。

背景与需求分析

当我们在Kubernetes集群中使用Ingress控制器（如Nginx Ingress）并配合OAuth2代理进行身份验证时，通常会在Ingress资源上配置全局认证。然而，这种配置会导致ACME HTTP-01挑战请求也被拦截，从而无法完成证书签发流程。

cert-manager创建的临时Ingress资源（名称通常以"cm-acme-http-solver-"开头）需要绕过全局认证机制，以确保Let's Encrypt等ACME服务能够成功验证域名所有权。

解决方案比较

方案一：利用Ingress-Nginx的专用配置

Nginx Ingress控制器提供了专门的no-auth-locations配置选项，默认已经包含了/.well-known/acme-challenge路径。这是最简洁的解决方案，无需额外配置即可让ACME挑战请求绕过认证。

方案二：通过Kyverno动态添加注解

对于需要更精细控制的场景，可以使用Kyverno策略引擎动态为cert-manager创建的Ingress资源添加特定注解：

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-ingress-annotation
spec:
  rules:
    - name: annotate-ingress
      match:
        resources:
          kinds:
            - Ingress
          name: "cm-acme-http-solver-*"
      mutate:
        patchStrategicMerge:
          metadata:
            annotations:
              nginx.ingress.kubernetes.io/enable-global-auth: "false"

方案三：cert-manager控制器参数

cert-manager控制器提供了--auto-certificate-annotations参数，理论上可以用于指定需要自动添加的注解。不过经过验证，此参数主要用于标识哪些Ingress资源应该自动获取证书，而非用于添加其他类型的注解。

最佳实践建议

1. 优先使用Ingress控制器的内置功能：如Nginx Ingress的no-auth-locations配置，这是最稳定可靠的解决方案。

2. 考虑集群策略管理工具：当内置功能无法满足需求时，Kyverno或Gatekeeper等策略引擎可以提供灵活的解决方案。

3. 了解控制器参数的实际用途：虽然cert-manager提供了丰富的配置参数，但需要准确理解每个参数的设计用途，避免误用。

实现原理

cert-manager在创建ACME挑战相关的Ingress资源时，会为其添加特定的标签和注解。这些资源通常具有以下特征：

• 名称前缀为"cm-acme-http-solver-"
• 包含cert-manager特定的注解如"cert-manager.io/issuer-name"

理解这些特征有助于我们精确地识别和修改这些临时资源。

总结

在Kubernetes环境中管理证书时，确保ACME挑战流程不受干扰至关重要。通过合理利用Ingress控制器的内置功能或集群策略工具，可以优雅地解决全局认证与证书签发之间的冲突问题。建议管理员根据实际环境选择最适合的解决方案，并充分理解各组件的工作原理。