getting-started.md

Getting Started

It is extremely easy to get started with Certificate Validator.

1. Clone the certificate-validator repository or download the latest release.

2. Install Node.js and NPM:

brew install node

3. Install the Serverless Framework open-source CLI:

npm install -g serverless

4. Deploy Certificate Validator:

make deploy

Note: An optional STAGE variable can be used to specify the stage. Defaults to dev.

Example

make deploy STAGE=prod

To remove Certificate Validator, run make remove.

Note: An optional STAGE variable can be used to specify the stage. Defaults to dev.

Example

make remove STAGE=prod

5. Retrieve the Amazon Resource Name (ARN) of your newly created AWS Lambda function.

Example

arn:aws:lambda:<region>:<account-id>:function:<function-name>

The ARN of the AWS Lambda function serves as the service token (ServiceToken) for your Custom::Certificate and Custom::CertificateValidator custom resources.

Note: The service token must be in the same region as the CloudFormation stack.

6. Add the Custom::Certificate and Custom::CertificateValidator custom resources to your CloudFormation template:

Example

Certificate:
  Type: Custom::Certificate
  Properties:
    ServiceToken: !Ref ServiceToken
    DomainName: !Ref DomainName
    SubjectAlternativeNames:
      - !Sub 'www.${DomainName}'

CertificateValidator:
  Type: Custom::CertificateValidator
  Properties:
    ServiceToken: !Ref ServiceToken
    CertificateArn: !GetAtt Certificate.CertificateArn

The Custom::Certificate custom resource can now be used anywhere a AWS::CertificateManager::Certificate resource would be used by calling !GetAtt Certificate.CertificateArn.

Warning: Since the ARN of a AWS::CertificateManager::Certificate resource is returned when you pass the logical ID of this resource to the intrinsic Ref function, an implicit dependency is created when it is referenced by other resources in your CloudFormation template. This ensures that the resource that references the AWS::CertificateManager::Certificate resource is created only after the certificate has been created. This is not the case for a Custom::Certificate custom resource, since the ARN is retrieved using the intrinsic GetAtt function, which does not create an implicit dependency. Therefore, you must explicitly create the dependency using the DependsOn attribute for the Custom::CertificateValidator custom resource.

Example

CloudFrontDistribution:
  DependsOn: CertificateValidator
  Type: AWS::CloudFront::Distribution
  Properties:
    ...

The Custom::CertificateValidator uses a waiter, which polls for the status of the AWS::CertificateManager::Certificate resource created by the Custom::Certificate custom resource and only allows execution to proceed after the certificate has been issued.

For an example CloudFormation stack, see certificate-validator/example.