Merge pull request #2042 from guardian/aa/additional-riff-raff-deploy…

…ments

feat(riff-raff.yaml): Support user-added deployment types

src/experimental/riff-raff-yaml-file/README.md

@@ -14,6 +14,8 @@ Currently, it supports the following Riff-Raff deployment types:
 - `aws-lambda` (for each `GuLambdaFunction` used)
 - `autoscaling` (for each `GuAutoScalingGroup` used)
 
+To add additional deployment types for your stack, see [Advanced usage](#advanced-usage) below.
+
 ## Usage
 Usage should require minimal changes to a GuCDK project:
 
@@ -39,6 +41,46 @@ new MyStack(app, "my-stack-CODE", {});
 new MyStack(app, "my-stack-PROD", {});
 ```
 
+### Advanced usage
+As noted above, only specific deployment types are currently supported.
+
+If you want to add additional deployment types, you can do so by instantiating `RiffRaffYamlFileExperimental` directly:
+
+```ts
+import { App } from "aws-cdk-lib";
+import { RiffRaffYamlFileExperimental } from "@guardian/cdk/lib/experimental/riff-raff-yaml-file";
+
+const app = new App();
+
+const { stack, region } = new MyStack(app, "my-stack", {
+  stack: "playground",
+  stage: "PROD",
+  env: { region: "eu-west-1" },
+});
+
+const riffRaff = new RiffRaffYamlFileExperimental(app);
+const { riffRaffYaml: { deployments } } = riffRaff;
+
+deployments.set("upload-my-static-files", {
+  actions: ["uploadStaticFiles"],
+  app: "my-static-site",
+  contentDirectory: "my-static-site",
+  dependencies: [],
+  parameters: {
+    bucketSsmKey: `/${stack}/my-static-site-origin`,
+    publicReadAcl: false,
+    cacheControl: "public, max-age=315360000, immutable",
+  },
+  regions: new Set([region]),
+  stacks: new Set([stack]),
+  type: "aws-s3",
+});
+
+// Write the riff-raff.yaml file to the output directory.
+// Must be explicitly called.
+riffRaff.synth();
+```
+
 When the CDK stack is synthesized, a `riff-raff.yaml` file will be created in the output directory, typically `/<repo-root>/cdk/cdk.out`.
 
 ## Package layout

src/experimental/riff-raff-yaml-file/index.test.ts

@@ -1128,4 +1128,61 @@ describe("The RiffRaffYamlFileExperimental class", () => {
       "
     `);
   });
+
+  it("Should support user-added Riff-Raff deployments", () => {
+    const app = new App({ outdir: "/tmp/cdk.out" });
+    class MyApplicationStack extends GuStack {}
+    const { stack, region } = new MyApplicationStack(app, "App-PROD-deploy", {
+      stack: "deploy",
+      stage: "PROD",
+      env: { region: "eu-west-1" },
+    });
+
+    const riffraff = new RiffRaffYamlFileExperimental(app);
+
+    riffraff.riffRaffYaml.deployments.set("upload-my-static-files", {
+      app: "my-static-site",
+      contentDirectory: "my-static-site",
+      parameters: {
+        bucketSsmKey: `/${stack}/my-static-site-origin`,
+        publicReadAcl: false,
+        cacheControl: "public, max-age=315360000, immutable",
+      },
+      regions: new Set([region]),
+      stacks: new Set([stack]),
+      type: "aws-s3",
+    });
+
+    const actual = riffraff.toYAML();
+
+    expect(actual).toMatchInlineSnapshot(`
+      "allowedStages:
+        - PROD
+      deployments:
+        cfn-eu-west-1-deploy-my-application-stack:
+          type: cloud-formation
+          regions:
+            - eu-west-1
+          stacks:
+            - deploy
+          app: my-application-stack
+          contentDirectory: /tmp/cdk.out
+          parameters:
+            templateStagePaths:
+              PROD: App-PROD-deploy.template.json
+        upload-my-static-files:
+          app: my-static-site
+          contentDirectory: my-static-site
+          parameters:
+            bucketSsmKey: /deploy/my-static-site-origin
+            publicReadAcl: false
+            cacheControl: public, max-age=315360000, immutable
+          regions:
+            - eu-west-1
+          stacks:
+            - deploy
+          type: aws-s3
+      "
+    `);
+  });
 });

src/experimental/riff-raff-yaml-file/index.ts

@@ -69,10 +69,21 @@ export class RiffRaffYamlFileExperimental {
   private readonly allStackTags: StackTag[];
   private readonly allStageTags: StageTag[];
   private readonly allRegions: Region[];
-
-  private readonly riffRaffYaml: RiffRaffYaml;
   private readonly outdir: string;
 
+  /**
+   * The `riff-raff.yaml` file as an object.
+   *
+   * It is useful for specifying additional deployment types that GuCDK does not support.
+   * Consider raising an issue or pull request if you think it should be supported.
+   *
+   * In most cases, you shouldn't need to access this.
+   * No validation is performed on the parameters you provide, so you might get deployment errors.
+   *
+   * @see https://riffraff.gutools.co.uk/docs/magenta-lib/types
+   */
+  public readonly riffRaffYaml: RiffRaffYaml;
+
   private isCdkStackPresent(expectedStack: StackTag, expectedStage: StageTag): boolean {
     const matches = this.allCdkStacks.find((cdkStack) => {
       const { stack, stage } = cdkStack;