AliDNS Webhook for cert-manager

A cert-manager webhook solver for Alibaba Cloud DNS (AliDNS)

Introduction

This webhook enables cert-manager to solve DNS-01 challenges using Alibaba Cloud DNS (AliDNS).

Unlike traditional solutions, this project adopts an Infrastructure as Identity design philosophy. By decoupling authentication from application configuration, the webhook server authenticates using its runtime environment identity (such as RRSA in ACK or ECS Instance Roles), supporting the standard default credential chain of the Alibaba Cloud SDK.

Core Features

Security First - Native RRSA (OIDC) support, eliminates hardcoded AK/SK risks
Simple Configuration - Zero authentication config required in Issuers
Multiple Authentication Methods - RRSA, environment variables, Kubernetes Secret, ECS instance role
Idempotent Operations - DNS record operations are safely retryable
Production Ready - Complete Helm Chart, RBAC, and health checks
Latest Tech Stack - Based on latest Alibaba Cloud Tea SDK and cert-manager v1.19+

Why This Project?

Design Philosophy Comparison

Traditional cert-manager webhook solutions often require explicit configuration of AccessKey/SecretKey in the Issuer or ClusterIssuer resource. This approach has several issues:

Feature	Traditional Solutions	This Project
Auth Config Location	In Issuer/ClusterIssuer	In Webhook Server itself
AK/SK Hardcoding	Yes (even with Secret)	Completely Eliminated
RRSA Support	❌	✅ Native Support
Configuration Complexity	High (per Issuer)	Low (one-time setup)
Multi-Account	Supported	Single account (most common case)
Credential Rotation	Update all Issuers required	Automatic

Advantages

Enhanced Security
- Eliminates static AK/SK hardcoding risks
- Native support for RRSA (OIDC) short-term tokens
- Follows cloud-native security best practices
Extreme Simplicity
- No need to configure credentials for each Issuer
- Relies on Alibaba Cloud SDK's standard Default Credential Chain
- Issuer configuration becomes minimal
Flexible Authentication
- Development: Use environment variables
- Testing: Use Kubernetes Secret
- Production: Use RRSA (recommended)

Note: This mode means all DNS challenges handled by this Webhook instance belong to the same Alibaba Cloud account. This design simplifies operations while perfectly matching the vast majority of single-tenant or single-account Kubernetes cluster scenarios.

Want to learn more about the architecture? See DEVELOPMENT.md for RRSA authentication flow and DNS-01 challenge flow.

Authentication

This webhook uses Alibaba Cloud credentials-go default credential chain, automatically finding credentials in the following priority order:

Priority	Method	Configuration	Best For
1	Env Vars AK/SK	`ALIBABA_CLOUD_ACCESS_KEY_ID` + `ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Development/Testing
2	RRSA (OIDC)	`ALIBABA_CLOUD_ROLE_ARN` + OIDC Token	Production (ACK)
3	config.json	`~/.aliyun/config.json`	Local Development
4	ECS Instance RAM Role	Metadata service (automatic)	ACK ECS Nodes
5	Credentials URI	`ALIBABA_CLOUD_CREDENTIALS_URI`	Special Scenarios

Installation

Prerequisites

Kubernetes 1.34+
Helm 3.0+
cert-manager v1.19.0+ installed
Alibaba Cloud DNS account
Domain hosted on Alibaba Cloud DNS

Method 1: Using RRSA (Recommended for Production)

RRSA (RAM Roles for Service Accounts) is the recommended authentication method for production deployments on ACK (Alibaba Cloud Kubernetes).

Prerequisites:

RRSA feature enabled in your ACK cluster
ack-pod-identity-webhook component installed
Namespace labeled with pod-identity.alibabacloud.com/injection: on

If you're unsure whether these conditions are met, refer to the documentation to check and configure step by step:

Use RRSA to Authorize Pods to Access Different Cloud Services

# Install webhook using Helm
helm install cert-manager-alidns-webhook oci://ghcr.io/crazygit/helm-charts/cert-manager-alidns-webhook \
  --set aliyunAuth.rrsa.enabled=true \
  --set aliyunAuth.rrsa.roleName=<YOUR_ROLE_NAME>

Authorize RRSA Role

Please replace <YOUR_ROLE_NAME> with your RAM role name. Ensure the role has AliDNS operation permissions:

{
  "Version": "1",
  "Statement": [
    {
      "Action": "alidns:AddDomainRecord",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "alidns:DeleteDomainRecord",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "alidns:DescribeDomainRecords",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

Method 2: Using AccessKey

# Method 1: Direct values
helm install cert-manager-alidns-webhook oci://ghcr.io/crazygit/helm-charts/cert-manager-alidns-webhook \
  --set aliyunAuth.accessKeyID=<YOUR_ACCESS_KEY_ID> \
  --set aliyunAuth.accessKeySecret=<YOUR_ACCESS_KEY_SECRET>

# Method 2: Using existing Secret (more secure)
kubectl create secret generic alidns-credentials \
  --from-literal=accessKeyID=<YOUR_ACCESS_KEY_ID> \
  --from-literal=accessKeySecret=<YOUR_ACCESS_KEY_SECRET>

helm install cert-manager-alidns-webhook oci://ghcr.io/crazygit/helm-charts/cert-manager-alidns-webhook \
  --set aliyunAuth.existingSecret=alidns-credentials

Method 3: On ACK ECS with Instance RAM Role

If your Kubernetes cluster runs on Alibaba Cloud ECS with an instance RAM role assigned and the required permissions bound to that role, no additional authentication configuration is needed:

helm install cert-manager-alidns-webhook oci://ghcr.io/crazygit/helm-charts/cert-manager-alidns-webhook

Method 4: Using config.json File

For local development or special scenarios, mount the Alibaba Cloud configuration file via ConfigMap:

# 1. Create ConfigMap with config.json
kubectl create configmap aliyun-config \
  --from-file=config.json=/path/to/.aliyun/config.json

# 2. Install webhook using Helm
helm install cert-manager-alidns-webhook oci://ghcr.io/crazygit/helm-charts/cert-manager-alidns-webhook \
  --set aliyunAuth.configJSON.enabled=true \
  --set aliyunAuth.configJSON.configMapName=aliyun-config

Usage Guide

Create a ClusterIssuer

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-dns01
spec:
  acme:
    privateKeySecretRef:
      name: letsencrypt-prod-dns01-key
    server: https://acme-v02.api.letsencrypt.org/directory
    solvers:
      - dns01:
          webhook:
            groupName: alidns.crazygit.github.io # Must match the groupName used during Helm installation
            solverName: alidns

Create an Issuer

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-prod-dns01
  namespace: default
spec:
  acme:
    privateKeySecretRef:
      name: letsencrypt-prod-dns01-key
    server: https://acme-v02.api.letsencrypt.org/directory
    solvers:
      - dns01:
          webhook:
            groupName: alidns.crazygit.github.io # Must match the groupName used during Helm installation
            solverName: alidns

Uninstall

# Uninstall webhook
helm uninstall cert-manager-alidns-webhook

# If Secret was used, delete it
kubectl delete secret alidns-credentials

# If ConfigMap was used, delete it
kubectl delete configmap aliyun-config

# Delete created Issuer or ClusterIssuer

Configuration Reference

Helm Values

Parameter	Description	Default
`groupName`	API group name	`alidns.crazygit.github.io`
`image.repository`	Image repository	`crazygit/cert-manager-alidns-webhook`
`image.tag`	Image tag	`latest`
`replicaCount`	Replica count	`1`
`aliyunAuth.regionID`	Alibaba Cloud region ID	`""`
`aliyunAuth.accessKeyID`	AccessKey ID	`""`
`aliyunAuth.accessKeySecret`	AccessKey Secret	`""`
`aliyunAuth.existingSecret`	Existing Secret name	`""`
`aliyunAuth.rrsa.enabled`	Enable RRSA	`false`
`aliyunAuth.rrsa.roleName`	RRSA role name	`""`
`aliyunAuth.configJSON.enabled`	Enable config.json	`false`
`aliyunAuth.configJSON.configMapName`	config.json ConfigMap name	`""`

For complete configuration, see deploy/cert-manager-alidns-webhook/values.yaml.

Development Guide

For development details, see DEVELOPMENT.md.

Troubleshooting

Common Issues

1. Certificate issuance fails with "dry run" error

This is expected during the first attempt. cert-manager performs a dry run before creating the actual challenge. Check logs for the real error.

kubectl logs deployment/cert-manager-alidns-webhook

2. "failed to add TXT record" error

Check the following:

Verify your Alibaba Cloud credentials are correct
Ensure your domain is hosted on Alibaba Cloud DNS
Check that the AccessKey has DNS management permissions
Confirm the RRSA role is properly authorized

3. RRSA authentication not working

Check the following:

Verify OIDC provider is configured in your ACK cluster
Check that the RAM role has required permissions
Ensure ServiceAccount annotations are correctly set
Check webhook logs to confirm OIDC token is obtained

# View ServiceAccount configuration
kubectl get sa cert-manager-alidns-webhook -o yaml

# View webhook logs
kubectl logs deployment/cert-manager-alidns-webhook

Viewing Logs

# View webhook logs
kubectl logs deployment/cert-manager-alidns-webhook

# View cert-manager logs
kubectl logs deployment/cert-manager

Security Best Practices

Use RRSA in Production Avoid hardcoded AccessKeys, prioritize RRSA for authentication.
Limit RAM Role Permissions Only grant DNS management permissions, follow the principle of least privilege.
Rotate Credentials Regularly Follow Alibaba Cloud security best practices for AccessKey rotation.
Network Policies Restrict webhook access to cert-manager only.
Use Private Image Registry In production, use a private image registry for the webhook image.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Before submitting a PR, please ensure:

Code passes all tests
Necessary unit tests are added
Related documentation is updated

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

This project is based on the cert-manager/webhook-example template repository.

_{Built with ❤️ by the open source community}

Name		Name	Last commit message	Last commit date
Latest commit History 95 Commits
.github/workflows		.github/workflows
deploy/cert-manager-alidns-webhook		deploy/cert-manager-alidns-webhook
pkg/alidns		pkg/alidns
testdata/my-custom-solver		testdata/my-custom-solver
.dockerignore		.dockerignore
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md
artifacthub-repo.yml		artifacthub-repo.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_test.go		main_test.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

AliDNS Webhook for cert-manager

Introduction

Core Features

Why This Project?

Design Philosophy Comparison

Advantages

Authentication

Installation

Prerequisites

Method 1: Using RRSA (Recommended for Production)

Authorize RRSA Role

Method 2: Using AccessKey

Method 3: On ACK ECS with Instance RAM Role

Method 4: Using config.json File

Usage Guide

Create a ClusterIssuer

Create an Issuer

Uninstall

Configuration Reference

Helm Values

Development Guide

Troubleshooting

Common Issues

Viewing Logs

Security Best Practices

Contributing

License

Acknowledgments

About

Uh oh!

Releases 3

Packages

Uh oh!

Languages

License

crazygit/cert-manager-alidns-webhook

Folders and files

Latest commit

History

Repository files navigation

AliDNS Webhook for cert-manager

Introduction

Core Features

Why This Project?

Design Philosophy Comparison

Advantages

Authentication

Installation

Prerequisites

Method 1: Using RRSA (Recommended for Production)

Authorize RRSA Role

Method 2: Using AccessKey

Method 3: On ACK ECS with Instance RAM Role

Method 4: Using config.json File

Usage Guide

Create a ClusterIssuer

Create an Issuer

Uninstall

Configuration Reference

Helm Values

Development Guide

Troubleshooting

Common Issues

Viewing Logs

Security Best Practices

Contributing

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Languages

Packages