AWS Private CA Issuer

AWS ACM Private CA is a module of the AWS Certificate Manager that can setup and manage private CAs.

cert-manager is a Kubernetes add-on to automate the management and issuance of TLS certificates from various issuing sources. It will ensure certificates are valid and up to date periodically, and attempt to renew certificates at an appropriate time before expiry.

This project acts as an addon (see https://cert-manager.io/docs/configuration/external/) to cert-manager that signs off certificate requests using AWS PCA.

Known Issues

1. STS GetCallerIdentity failing because of a region not specified bug

   There is currently a known issue with the plugin that is preventing certificate issuance due to STS GetCallerIdentity failing because of a region not specified bug, regardless of whether a region was specified or not (cert-manager/aws-privateca-issuer#54). There is an existing pull request to fix this (cert-manager/aws-privateca-issuer#53), but we are holding off on accepting any pull requests until our testing is redesigned. To fix this issue until then, please checkout the cleanup branch by running

    git fetch -a
    git checkout cleanup
   

   Also, please be sure you are using the plugin with an IAM user, as that is the most reliable workflow https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey This user must have minimum permissions listed in the Configuration section.

    export AWS_SECRET_ACCESS_KEY=<Secret Access Key you generated>
    export AWS_ACCESS_KEY_ID=<Access Key you generated>
   

Setup

Install cert-manager first (https://cert-manager.io/docs/installation/kubernetes/).

Then install AWS PCA Issuer using Helm:

helm repo add awspca https://cert-manager.github.io/aws-privateca-issuer
helm install awspca/aws-privateca-issuer --generate-name

You can check the chart configuration in the default values file.

Configuration

As of now, the only configurable settings are access to AWS. So you can use AWS_REGION, AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY.

Alternatively, you can supply arbitrary secrets for the access and secret keys with the accessKeyIDSelector and secretAccessKeySelector fields in the clusterissuer and/or issuer manifests.

Access to AWS can also be configured using an EC2 instance role.

A minimal policy to use the issuer with an authority would look like follows:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "awspcaissuer",
      "Action": [
        "acm-pca:DescribeCertificateAuthority",
        "acm-pca:GetCertificate",
        "acm-pca:IssueCertificate"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:acm-pca:<region>:<account_id>:certificate-authority/<resource_id>"
    }
  ]
}

Usage

This operator provides two custom resources that you can use.

Examples can be found in the examples directory.

AWSPCAIssuer

This is a regular namespaced issuer that can be used as a reference in your Certificate CRs.

AWSPCAClusterIssuer

This CR is identical to the AWSPCAIssuer. The only difference being that it's not namespaced and can be referenced from anywhere.

Disable Approval Check

The AWSPCA Issuer will wait for CertificateRequests to have an approved condition set before signing. If using an older version of cert-manager (pre v1.3), you can disable this check by supplying the command line flag -disable-approved-check to the Issuer Deployment.

Authentication

Please note that if you are using KIAM for authentication, this plugin has been tested on KIAM v4.0. IRSA is also tested and supported.

There is a custom AWS authentication method we have coded into our plugin that allows a customer to define a Kubernetes secret with AWS Creds passed in, example here. The customer applies that file with their creds and then references the secret in their Issuer CRD when running the plugin, example here.

Running the tests

Running make test will run the written unit test

Running make runtests will take the current code artifacts and transform them into a Docker image that will run on a kind cluster and ensure that the current version of the code still enables EC/RSA certs to be issued by an AWS Private CA. It will also verify the unit tests pass.

Requirements for running the integration testing

NOTE: Running these tests will incur charges in your AWS Account. Please refer to AWS PCA pricing.

For running the integration tests you will need a few things:

• 2 AWS Private CAs - One Private CA that is backed by an RSA key and another Private CA that is backed by an EC key (Currently the PCA external issuer only supports issuing RSA certs from an RSA key backed CA and issuing EC certs from an EC key backed CA).
• Access to an AWS Account (Via an IAM User) where you will have permission to create, update, and delete the Private CAs needed to run the integration tests
• Git
• Golang v1.13+
• Docker v17.03+
• Kind v0.9.0+
• Kubectl v1.11.3+
• Kubebuilder v2.3.1+
• Kustomize v3.8.1+
• AWS CLI v2

How the integration tests work / How to run them

As mentioned before, running the tests is as easy as make runtests

The code for the integration tests live in test_utils/e2e_tests.sh. The test first begins by creating an RSA backed CA and an EC backed CA (If the Enviornment variables RSA_CM_CA_ARN and/or EC_CM_CA_ARN are set, the test will skip creating that kind of CA and just use the ARN supplied).

The tests will take your AWS CLI creds via the enviornment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and use those to not only create/update/delete the CAs used for the test, but also use these as the secret to pass to the AWSPCAClusterIssuer/AWSPCAIssuer for allowing the Issuers to issue certificates.

The tests will then spin up a kind cluster and create various Issuer/ClusterIssuer resources along with various certificate resources. The test will verify that using the Cluster or Namespace Issuer, the PCA external issuer is able to issue both EC and RSA certificates and the Cert Manager certificate resources reach a ready state.

After the test, the resources created with the kind cluster are cleaned up, the kind cluster is deleted, and the CAs used during the test are deleted.

The Private CAs created during this test run are cleaned up on a best-effort basis. To ensure no runaway costs, verify via the AWS CLI or Console that the Private CAs created during the test run are in a deleted state. If you need to delete the Private CAs created during the test run yourself you may use the script test_utils/delete_ca.sh or refer to the AWS Private CA documentation

If at any point, make runtests encounters an error, the integration tests should be considered a failure.

Supported workflows

AWS Private Certificate Authority(PCA) Issuer Plugin supports the following integrations and use cases:

• Integration with cert-manager 1.4+ and corresponding Kubernetes versions.

• Authentication methods:

  • KIAM v4.0
  • IRSA - IAM roles for service accounts
  • Kubernetes Secrets
  • EC2 Instance Profiles

• AWS Private CA features:

  • End-to-End TLS encryption on Amazon Elastic Kubernetes Service(Amazon EKS).
  • TLS-enabled Kubernetes clusters with AWS Private CA and Amazon EKS
  • Cross Account CA sharing with supported Cross Account templates
  • Supported PCA Certificate Templates: CodeSigningCertificate/V1; EndEntityClientAuthCertificate/V1; EndEntityServerAuthCertificate/V1; OCSPSigningCertificate/V1; EndEntityCertificate/V1; BlankEndEntityCertificate_CSRPassthrough/V1

Troubleshooting

1. Check the secret with the AWS credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY values have to be base64 encoded.

2. If the generated CertificateRequest shows no events, it is very likely that you're using an older version of cert-manager which doesn't support approval check. Disable approval check at the issuer deployment.

Help & Feedback

For help, please consider the following venues (in order):

• Check the Troubleshooting section
• Search open issues
• File an issue
• Please ask questions in the slack channel cert-manager-aws-privateca-issuer

Contributing

We welcome community contributions and pull requests.

See our contribution guide for more information on how to report issues, set up a development environment, and submit code.

We adhere to the Amazon Open Source Code of Conduct.