Document certificate template selection logic based on certificate usages #460

Problem

When using aws-privateca-issuer with AWS RAM (Resource Access Manager) cross-account PCA sharing, changing the usages field in a cert-manager Certificate resource can cause unexpected AccessDeniedException errors.

This happens because aws-privateca-issuer implicitly selects different ACM PCA certificate templates based on the usages field:

• usages: [server auth, client auth] → EndEntityClientAuthCertificate template
• usages: [server auth] → EndEntityServerAuthCertificate template

When the PCA is shared via RAM, the managed permission attached to the RAM share may only allow specific templates (e.g., EndEntityClientAuthCertificate). Removing client auth from usages silently switches the template, which can result in:

AccessDeniedException: User is not authorized to perform: acm-pca:IssueCertificate
because no resource-based policy allows the acm-pca:IssueCertificate action

Impact

This is particularly problematic because:

1. The template selection logic is not documented — users have no way to know that changing usages affects the PCA template
2. The error message does not mention the template mismatch — it only says "not authorized"
3. It only affects cross-account (RAM-shared) PCA setups, making it hard to reproduce in single-account environments

Suggestion

1. Document the template selection logic — clearly state which usages combinations map to which PCA templates
2. Consider adding an explicit template override option — allow users to specify the PCA template directly in the AWSPCAClusterIssuer or Certificate annotation, rather than relying on implicit selection from usages
3. Improve error messaging — when IssueCertificate fails, include the template ARN that was used in the error log

Environment

• aws-privateca-issuer version: v1.6.0
• cert-manager version: v1.17.4
• Setup: Cross-account PCA shared via AWS RAM

References

• Template selection logic: pkg/aws/pca.go
• AWS ACM PCA Certificate Templates
• AWS RAM Managed Permissions for ACM PCA