AWS Private CA Issuer

[!TIP] Amazon Elastic Kubernetes Service (EKS) supports AWS Private CA Issuer as an EKS Add-on named aws-privateca-connector-for-kubernetes. This simplifies installation and configuration for Amazon EKS users. See AWS add-ons for more information.

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.

AWS PCA Issuer supports ARM starting at version 1.3.0

Accessing the test ECR

AWS PCA Issuer maintains a test ECR that contains versions that correspond to each commit on the main branch. These images can be accessed by setting the image repo to public.ecr.aws/cert-manager-aws-privateca-issuer/cert-manager-aws-privateca-issuer-test and the image tag to latest. An example of how this is done is shown below:

helm repo add awspca https://cert-manager.github.io/aws-privateca-issuer
helm install awspca/aws-privateca-issuer --generate-name \
--set image.repository=public.ecr.aws/cert-manager-aws-privateca-issuer/cert-manager-aws-privateca-issuer-test \
--set image.tag=latest

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 or [IAM Roles for Service Accounts] (https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).

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 and samples directories.

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.

Usage with cert-manager Ingress Annotations

The cert-manager.io/cluster-issuer annotation cannot be used to point at a AWSPCAClusterIssuer. Instead, use cert-manager.io/issuer:. Please see this issue for more information.

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.

Disable Kubernetes Client-Side Rate Limiting

The AWSPCA Issuer will throttle the rate of requests to the kubernetes API server to 5 queries per second by default. This is not necessary for newer versions of Kubernetes that have implemented API Priority and Fairness. If using a newer version of Kubernetes, you can disable this client-side rate limiting by supplying the command line flag -disable-client-side-rate-limiting 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 user to define a Kubernetes secret with AWS Creds passed in, example here. The user applies that file with their creds and then references the secret in their Issuer CRD when running the plugin, example here.

IAM Roles Anywhere

For use cases where the AWS Private CA issuer needs to run outside of AWS, IAM Roles Anywhere can be used as an alternative to IAM Users.

The helm chart supports extraContainers which can be used to deploy the aws_signing_helper in "serve" mode. Then, we can set AWS_EC2_METADATA_SERVICE_ENDPOINT="http://127.0.0.1:9911" on the aws-privateca-issuer itself.

A simplified example of what to set for your helm values is as follows:

env:
  AWS_EC2_METADATA_SERVICE_ENDPOINT: "http://127.0.0.1:9911"
extraContainers:
  - name: "rolesanywhere-credential-helper"
    image: "public.ecr.aws/rolesanywhere/credential-helper:latest"
    command: ["aws_signing_helper"]
    args:
      - "serve"
      - "--private-key"
      - "/etc/cert/tls.key"
      - "--certificate"
      - "/etc/cert/tls.crt"
      - "--role-arn"
      - "$ROLE_ARN"
      - "--profile-arn"
      - "$PROFILE_ARN"
      - "--trust-anchor-arn"
      - "$TRUST_ANCHOR_ARN"
    volumeMounts:
      - name: cert
        mountPath: /etc/cert/
        readOnly: true
volumes:
  - name: cert
    secret:
      secretName: cert

Cross Account Assume Role

You can configure the AWS Private CA issuer to assume an IAM role before making AWS Private CA API calls. This method provides flexibility for various authentication scenarios and is an alternative to AWS Resource Access Manager (RAM) sharing for cross-account use cases.

When you specify a role in the role field, the issuer assumes that role using AWS Security Token Service (STS) before making AWS Private CA API calls.

Example:

apiVersion: awspca.cert-manager.io/v1beta1
kind: AWSPCAClusterIssuer
metadata:
  name: example
spec:
  arn: <some-pca-arn>
  role: <some-role-arn>
  region: <some-region>

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
  • IAM Roles Anywhere

• 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
  • Full support for all PCA Certificate Templates

Using AWS PCA Template ARNs

When creating an AWSPCAIssuer or AWSPCAClusterIssuer, you can set a default template under spec.pcaTemplate.defaultTemplateName from the list of PCA Certificate Templates. When specifying an ARN, omit the part up to, and including :::template/. For example, suppose you wanted to use arn:aws:acm-pca:::template/SubordinateCACertificate_PathLen1/V1, then specify SubordinateCACertificate_PathLen1/V1 in the issuer. See /config/examples/config/issuer-with-template.yaml.

This will lock all certificate requests made to that issuer into using the specified template, overriding other fields in your certificate requests. This is particularly useful if you wish to only allow certain namespaces to access a subset of all PCA templates. Some of the Usages types map to templates as well. Note that if you specify a UsageType here that conflicts with the template of the issuer, the UsageType in your request will be ignored.

The code for the translation can be found here.

Depending on which UsageTypes are set in the Cert-Manager certificate, different AWS PCA templates will be used. This table shows how the UsageTypes are being translated into which template to use when making an IssueCertificate request:

Understanding/Running the tests

Running the Unit Tests

Running make test will run the written unit test

If you run into an issue like

/home/linuxbrew/.linuxbrew/Cellar/go/1.17/libexec/src/net/cgo_linux.go:13:8: no such package located

This can be fixed with a

brew install gcc@5

Running the End-To-End Tests

NOTE: Running these tests will incur charges in your AWS Account.

Running make e2etest 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 works with the Supported Workflows

The easiest way to get the test to run would be to use the follow make targets: make cluster && make install-eks-webhook && make e2etest

Getting make cluster to run

make cluster will create a kind cluster on your machine that has Cert-Manager installed as well as the aws-pca-issuer plugin (using the HEAD of the current branch)

Before running make cluster we will need to do the following:

- Have the following tools on your machine: * Git * Golang v1.17+ * Docker v17.03+ * Kind v0.9.0+ -> This will be installed via running the test * Kubectl v1.13+ * AWS CLI v2 * Helm * Make Need to have version 3.82+

- (Optional) You will need a AWS IAM User to test authentication via K8 secrets. You can provide an already existing user into the test via export PLUGIN_USER_NAME_OVERRIDE=<IAM User Name>. This IAM User should have a policy attached to it that follows with the policy listed in Configuration. This user will be used to test authentication in the plugin via K8 secrets.

- An S3 Bucket with BPA disabled in us-east-1. After creating the bucket run export OIDC_S3_BUCKET_NAME=<Name of bucket you just created>

- You will need AWS credentials loaded into your terminal that, via the CLI, minimally allow the following actions via an IAM policy: - acm-pca:* : This is so that Private CA's maybe be created and deleted via the