Skip to main content
Version: v2.x

Certificates for CloudFormation-deployed sidecars

You can use Cyral's default sidecar-created certificate or use a custom certificate to secure the communications between the Cyral control plane and the sidecar.

In this page we provide you two ways of deploying a custom certificate (signed by Let's Encrypt in a Route53 domain or signed by the certificate authority of your choice) to your sidecar. Both are CloudFormation stacks that can be deployed to AWS after you set the values of a few parameters.

Let's Encrypt signed certificate​

The stack we provide will manage the creation and automatic renewal of Let's Encrypt certificates.

Once the stack is created, provide the secret ARN found in the output parameter SecretId to the control plane so that the sidecar can use the certificate. See how to do it here.

Follow the steps below to deploy it:

  1. Check which region you are deploying to

    • If you are deploying to us-east-1, us-east-2, us-west-1 or us-west-2, then follow these steps:

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Amazon S3 URL

      • For Amazon S3 URL, specify the Cyral sidecar custom certificate for Let's Encrypt template download URL as follows:

        https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-letsencrypt-cft-latest.yaml

        where region is one of us-east-1, us-east-2, us-west-1 or us-west-2

    • If you are deploying to any other region, follow these steps:

      • Download the CloudFormation template from the following URL:

        https://cyral-public-assets-us-east-1.s3.us-east-1.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-letsencrypt-cft-latest.yaml

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Upload a template file and provide the downloaded file.

      note

      You also have the option to use a versioned path for the custom certificate template. Form the versioned URL according to the following general format:

      https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/<version>/sidecar-custom-certificate-letsencrypt-cft-<version>.yaml

      where version is your desired version as discussed with Cyral support, for example, v0.2.6

      For example, to get version v0.1.0 for running in us-east-2, you would use the URL,

      https://cyral-public-assets-us-east-2.s3.us-east-2.amazonaws.com/sidecar-custom-certificate/v0.1.0/sidecar-custom-certificate-letsencrypt-cft-v0.1.0.yaml

Parameters for certificate creation​

  1. Use the following parameters to define how the stack will create the certificate:

    • SidecarDomain: The domain to generate a certificate for. For example, my-snowflake-sidecar.mydomain.com

    • Provide a value for one of the following:

      • SidecarSubdomains: Specify the list of subdomains to generate a certificate for, delimited by comma. (Note! Use the SnowflakeAccountRegion setting instead, if you're configuring a Snowflake sidecar); or

      • SnowflakeAccountRegion: Use this parameter for Snowflake deployments. Specify the AWS region your Snowflake account is running on. For example, us-east-1. If SnowflakeAccountRegion is set, the program will automatically append a set of default subdomains to SidecarSubdomains. For example, given the configuration

        SidecarDomains="snowflake.foo.com"
        SidecarSubdomains=""
        SnowflakeAccountRegion="us-east-1"

        the list of subdomains will be defined as:

        *.snowflake.foo.com
        *.s3.snowflake.foo.com
        *.s3.us-east-1.snowflake.foo.com
        *.s3-us-east-1.snowflake.foo.com

    • StagingCertificate: Enter true to use a staging (test) certificate. Default is false. Use this only for testing; staging certificates are not valid for production use.

Parameters for certificate renewal​

  1. Use the following parameters to define how the stack will perform the certificate renewal:

    • RegistrationEmail: (Optional) Administrative email to use for registration and recovery contact with Let's Encrypt.

      This parameter is optional, but we recommend you don't leave it empty. Enter one or more emails (delimited by comma) that will be used to send alerts that the certificate is close to its expiry date. Let's Encrypt will take care of sending the notification emails.

      Note that the application should automatically renew the certificate. However, if the application is failing to do that for whatever reason, this is the means by which you will be alerted.

    • RenewalIntervalChecks: How often to check if certificate should be renewed, in days. Default is 1 day.

    • RenewalIntervalWindowStart: Number of days before expiry date to renew the certificate. Default is 35 days.

Parameters for cross-account deployment​

If you have a scenario in which you have two different accounts that you will deploy the sidecar and another account that will manage the DNS using Route53, then you need to use parameters SidecarCustomCertificateSecretARN and SidecarCustomCertificateRoleARN. Suppose you have the following configuration:

  • Account 111111111111 used to manage DNS using Route53
  • Account 222222222222 used to deploy the sidecar

  1. You must first deploy the sidecar in account 222222222222, specifying the account 111111111111 in parameter SidecarCustomCertificateAccountID.

  2. Once the sidecar is deployed, it will output parameters SidecarCustomCertificateRoleARN and SidecarCustomCertificateSecretARN. These parameters must be used to feed the parameters with same names in this stack, as follows:

    • SidecarCustomCertificateSecretARN: (Optional) ARN of the secret to store the certificate in. Use this parameter if the sidecar is hosted in a different account.
    • SidecarCustomCertificateRoleARN: (Optional) Role to assume when accessing secrets manager. Use this paramenter if the sidecar is hosted in a different account.

Parameters for lambda configuration​

  1. If you want to deploy a lambda from a different bucket or with a different version, use the following parameters:
    • LambdaCodeS3Bucket: (Optional) S3 bucket that contains the Lambda deployment package. LEAVE EMPTY UNLESS YOU WANT TO OVERRIDE THE DEFAULT.
    • LambdaCodeS3Key: (Optional) Object key for the Lambda deployment package on the S3 bucket. LEAVE EMPTY UNLESS YOU WANT TO OVERRIDE THE DEFAULT.

Use your own certificate​

We also provide a solution for those willing to use their own certificate emmited by the Certificate Authority of their choice. Before choosing to use your own certificate, be sure to understand the limitations of this solution:

  • The template provided by Cyral must be deployed to the same account where the sidecar is hosted.

  • The certificate and private key must be base64-encoded so it can be used by our template.

  • CloudFormation templates have a maximum size of 4096 characters for parameter values. Therefore, if your base64-encoded certificate or private key have more than 4096 characters, you must split it into parts of no more than 4096 characters each, and provide the parts in order to the template. The template allows a maximum of three parts.

  • It is your responsibility to manage the validity and renewal of the provided certificate and private key. None of the templates will renew or control the validity of the certificate.

Once the stack is created, provide the secret ARN found in the output parameter SecretId to the control plane so that the sidecar can use the certificate. See how to do it here.

Follow the steps below to deploy it:

  1. Check which region you are deploying to

    • If you are deploying to us-east-1, us-east-2, us-west-1 or us-west-2, then follow these steps:

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Amazon S3 URL

      • For Amazon S3 URL, specify the Cyral sidecar custom certificate template download URL as follows:

        https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-cft-latest.yaml

        where region is one of us-east-1, us-east-2, us-west-1 or us-west-2

    • If you are deploying to any other region, follow these steps:

      • Download the CloudFormation template from the following URL:

        https://cyral-public-assets-us-east-1.s3.us-east-1.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-cft-latest.yaml

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Upload a template file and provide the downloaded file.

      note

      You also have the option to use a versioned path for the custom certificate template. Form the versioned URL according to the following general format:

      https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/<version>/sidecar-custom-certificate-cft-<version>.yaml

      where version is your desired version as discussed with Cyral support, for example, v0.2.6

      For example, to get version v0.1.0 for running in us-east-2, you would use the URL,

      https://cyral-public-assets-us-east-2.s3.us-east-2.amazonaws.com/sidecar-custom-certificate/v0.1.0/sidecar-custom-certificate-cft-v0.1.0.yaml

  2. Use the following parameters to provide the certificate details:

    • CustomCertificateBase64PartX: Base64-encoded full certificate chain.

    • CustomPrivateKeyBase64PartX: Base64-encoded private key.

    Where PartX can be Part1, Part2 or Part3. Each part can contain at most 4096 characters. For example, if your base64-encoded certificate has 8000 characters, you can divide it into two parts of 4000 characters each. In this case, provide the first part to CustomCertificateBase64Part1, and the second part to CustomCertificateBase64Part2.