feat(s3-deployment): create DeployTimeSubstitutedFile to allow substitutions in file

[sumupitchayan]

Closes #1461

The DeployTimeSubstitutedFile construct allows you to upload a file and specify substitutions to be made in it, which will be resolved during deployment.

For example, if you wanted to create a REST API from a Swagger file spec but want to reference other CDK resources in your API spec, you can now do so in-line:

const bucket: Bucket;
const myLambdaFunction: lambda.Function;

const deployment = new s3deploy.DeployTimeSubstitutedFile(this, 'MyApiFile', {
  source: 'my-swagger-spec.yaml',
  destinationBucket: bucket,
  substitutions: {
    xxxx: myLambdaFunction.functionArn,
    yyyy: 'mySubstitution',
  },
});

const api = new apigateway.SpecRestApi(this, 'books-api', {
  apiDefinition: apigateway.ApiDefinition.fromBucket(deployment.bucket, deployment.objectKey),
});

Where 'xxxx' and 'yyyy' are the examples of placeholder text you can add in your local file spec to be substituted by surrounding the placeholder with double curly braces, for example writing: {{ xxxx }} in your file where you want a substitution.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[gitpod-io]

[aws-cdk-automation]

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 75aeab6
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[ChrisLane]

This is great. Could the same be done for an aws_s3.Asset?

My use-case is that I have a third-party construct that accepts an S3 path for a script to run.
I have an Asset that deploys the script and I pass the S3 path from that to the third-party construct but then within the script I need to download a file that itself is deployed to S3 via CDK. This is why I need the replacement in the asset, to maintain the dependency to replace the construct when either of the files change.

[alex-cook-finres]

Does this actually work as-is or does it need other changes? If I actually substitute any parameters I end up getting an "Invalid OAS input" failure error. If I hard-code values with the same code (just no substitutions in the file) it works fine. Any help would be great as this seems like a nice way to actually use my API spec compared to other options I've seen out there.

    const deployment = new s3deploy.DeployTimeSubstitutedFile(
      this,
      "MyApiFile",
      {
        source: path.join(__dirname, "../../openapi-spec/api-definition.yaml"),
        destinationBucket: bucket,
        destinationKey: "api-definition.yaml",
        substitutions: {
          LAMBDA_ARN: lambdaFunction.functionArn,
          AWS_REGION: this.region,
        },
      }
    );

    const api = new apigateway.SpecRestApi(this, "CdkApi", {
      apiDefinition: apigateway.ApiDefinition.fromBucket(
        deployment.deployedBucket, // also tried with deployment.bucket
        deployment.objectKey
      ),
    });