@deployfoundation/foundation-deploy 0.1.0

package/src/stacks/pipeline-stack.ts

@@ -0,0 +1,242 @@
+import { CUSTOMIZATION_ARTIFACT_NAME } from "@deployfoundation/foundation-core/instance";
+/**
+ * FoundationPipeline — the instance's own deployer, living in the instance's own AWS
+ * account.
+ *
+ * Why this exists rather than the GitHub Actions job that does the same work:
+ * a customer running Foundation should own its build, its logs and its
+ * credentials. A deploy through Actions depends on a workflow in someone
+ * else's repository and on an OIDC trust reaching into the customer's account;
+ * this depends on neither. One merge no longer deploys every instance in
+ * lock-step either — an instance can hold or pin without touching the others.
+ *
+ * The build runs `foundation-deploy deploy` and then `foundation-deploy
+ * post-deploy`: the first stages any reviewed tenant runtime config, builds
+ * the image, runs `cdk deploy --all`, refreshes the runtime secret and syncs
+ * config; the second smokes DEFAULT, probes the mount, promotes `live` and
+ * smokes `live`. `live` moves only after the probes pass.
+ *
+ * `cdk deploy --all` inside the build includes this stack, so a change to the
+ * pipeline definition applies on the pipeline's next run — self-updating,
+ * without CDK Pipelines' extra mutate stage. The first deploy is by hand, from
+ * a laptop with the instance's profile (`foundation-deploy setup`, or `cdk
+ * deploy <Prefix>Pipeline -c instanceFile=<path>`).
+ *
+ * The buildspec is read from the INSTANCE repository the pipeline sources, not
+ * from Foundation: the instance repo owns its own build, and step 8 shrinks
+ * that file to one `npx @deployfoundation/foundation-deploy@<version>` line.
+ * `pipeline/buildspec.yml` in this package is the reference it starts from.
+ *
+ * Only synthesized for instances whose `deploy.via` is `codepipeline`; see
+ * `bin/app.ts`. Exactly one deployer owns an instance.
+ */
+import * as cdk from "aws-cdk-lib";
+import * as codebuild from "aws-cdk-lib/aws-codebuild";
+import * as codepipeline from "aws-cdk-lib/aws-codepipeline";
+import * as actions from "aws-cdk-lib/aws-codepipeline-actions";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type * as kms from "aws-cdk-lib/aws-kms";
+import type * as s3 from "aws-cdk-lib/aws-s3";
+import * as sns from "aws-cdk-lib/aws-sns";
+import * as subscriptions from "aws-cdk-lib/aws-sns-subscriptions";
+import type { Construct } from "constructs";
+import { deployStatements } from "../deploy-permissions.ts";
+import { type Instance, namesFor } from "../names.ts";
+
+export interface FoundationPipelineProps extends cdk.StackProps {
+  /** The deployment this pipeline deploys; every name below comes from it. */
+  instance: Instance;
+  /** The data stack's bucket — config and skills are synced into it. */
+  bucket: s3.IBucket;
+  /** The CMK that bucket is encrypted with. */
+  dataKey: kms.IKey;
+  /**
+   * Where the instance file sits inside the instance repository the pipeline
+   * sources, so the build can name it. Relative to that checkout's root.
+   */
+  instanceFilePath: string;
+  /** Address told when a pipeline run fails. Defaults to the instance's own. */
+  alarmEmail?: string;
+  /**
+   * Where the buildspec sits inside the instance repository the pipeline
+   * sources. Overridable because an instance repo chooses its own layout.
+   */
+  buildspecPath?: string;
+}
+
+/**
+ * Default buildspec path inside the INSTANCE repository. `packages/infra/pipeline/buildspec.yml`
+ * is the reference version of this file; an instance repo copies it and owns it
+ * from then on.
+ */
+export const DEFAULT_BUILDSPEC_PATH = "buildspec.yml";
+
+/** A whole deploy is ~8 minutes warm; an hour is room for a cold image build. */
+export const BUILD_TIMEOUT = cdk.Duration.minutes(60);
+
+export class FoundationPipeline extends cdk.Stack {
+  public readonly pipeline: codepipeline.Pipeline;
+  public readonly buildRole: iam.Role;
+
+  constructor(scope: Construct, id: string, props: FoundationPipelineProps) {
+    super(scope, id, props);
+    const names = namesFor(props.instance);
+    const { deploy } = props.instance;
+    const customization = props.instance.customization;
+    if (deploy.connectionArn === undefined)
+      throw new Error(
+        `instance ${props.instance.name}: deploy.connectionArn is required for a pipeline`,
+      );
+    const [owner = "", repo = ""] = props.instance.github.repo.split("/");
+
+    // The deployer itself. Same statements as the GitHub Actions role, from
+    // one definition, so the two cannot drift; what may assume this role —
+    // CodeBuild in this account, reached only through the pipeline — is the
+    // boundary, exactly as the OIDC trust is there.
+    this.buildRole = new iam.Role(this, "BuildRole", {
+      description: `CodePipeline deployer for ${props.instance.name}`,
+      assumedBy: new iam.ServicePrincipal("codebuild.amazonaws.com"),
+      inlinePolicies: {
+        FoundationDeploy: new iam.PolicyDocument({
+          statements: deployStatements(
+            this,
+            names,
+            { bucket: props.bucket, dataKey: props.dataKey },
+            props.instance,
+          ),
+        }),
+      },
+    });
+
+    // One topic and subscription cover both failures and approval requests.
+    // Keeping it here gives the optional approval action the existing alarm
+    // path without creating a second email subscription.
+    const failureTopic = new sns.Topic(this, "FailureTopic", {
+      displayName: `${props.instance.displayName} deploy failures`,
+    });
+    const alarmEmail = props.alarmEmail ?? props.instance.aws.alarmEmail;
+    if (alarmEmail !== undefined && alarmEmail !== "")
+      failureTopic.addSubscription(new subscriptions.EmailSubscription(alarmEmail));
+
+    const project = new codebuild.PipelineProject(this, "Build", {
+      projectName: `${props.instance.naming.prefix}Deploy`,
+      description: `Build and deploy ${props.instance.name} from ${props.instance.github.repo}@${deploy.branch}`,
+      role: this.buildRole,
+      timeout: BUILD_TIMEOUT,
+      environment: {
+        // arm64 throughout: AgentCore runs arm64 only, and building natively
+        // beats qemu by minutes. `privileged` is what lets the build run a
+        // Docker daemon at all.
+        buildImage: codebuild.LinuxArmBuildImage.AMAZON_LINUX_2023_STANDARD_3_0,
+        computeType: codebuild.ComputeType.LARGE,
+        privileged: true,
+      },
+      // Best-effort and free: warm when the build lands on a host that ran a
+      // recent build, cold otherwise. `FOUNDATION_IMAGE_CACHE=local` is the deploy
+      // script's half of this — buildx with no cache export, because there is
+      // no Actions cache backend here to export to.
+      cache: codebuild.Cache.local(
+        codebuild.LocalCacheMode.DOCKER_LAYER,
+        codebuild.LocalCacheMode.SOURCE,
+      ),
+      environmentVariables: {
+        // The instance file is the tool's only input. The path is the instance
+        // repository's own layout, so the buildspec and this value agree.
+        FOUNDATION_INSTANCE_FILE: { value: props.instanceFilePath },
+        // No `--profile`: the build's credentials are the role above.
+        FOUNDATION_NO_PROFILE: { value: "1" },
+        FOUNDATION_IMAGE_CACHE: { value: "local" },
+        // The buildspec runs `post-deploy` as its own phase, so the deploy
+        // command must not also promote `live`.
+        FOUNDATION_SKIP_POST_DEPLOY: { value: "1" },
+      },
+      // From the instance repository's source, not inline: that repo reviews
+      // and versions its own build, and a change to it needs no stack deploy.
+      buildSpec: codebuild.BuildSpec.fromSourceFilename(
+        props.buildspecPath ?? DEFAULT_BUILDSPEC_PATH,
+      ),
+    });
+
+    const source = new codepipeline.Artifact("Source");
+    const sourceActions = [
+      new actions.CodeStarConnectionsSourceAction({
+        actionName: "GitHub",
+        connectionArn: deploy.connectionArn,
+        owner,
+        repo,
+        branch: deploy.branch,
+        output: source,
+        // Every merge to the tracked branch deploys, as merging to main has
+        // always done.
+        triggerOnPush: true,
+      }),
+    ];
+    let customizationSource: codepipeline.Artifact | undefined;
+    let customizationSourceAction: actions.CodeStarConnectionsSourceAction | undefined;
+    if (customization !== undefined) {
+      const [customizationOwner = "", customizationRepo = ""] = customization.repository.split("/");
+      const customizationArtifact = new codepipeline.Artifact(CUSTOMIZATION_ARTIFACT_NAME);
+      customizationSource = customizationArtifact;
+      customizationSourceAction = new actions.CodeStarConnectionsSourceAction({
+        actionName: CUSTOMIZATION_ARTIFACT_NAME,
+        connectionArn: deploy.connectionArn,
+        owner: customizationOwner,
+        repo: customizationRepo,
+        branch: customization.branch,
+        output: customizationArtifact,
+        triggerOnPush: true,
+      });
+      sourceActions.push(customizationSourceAction);
+    }
+
+    const stages: codepipeline.StageProps[] = [{ stageName: "Source", actions: sourceActions }];
+    if (customization !== undefined && customizationSourceAction !== undefined) {
+      const customizationLinkPath = customization.path
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+      stages.push({
+        stageName: "Approval",
+        actions: [
+          new actions.ManualApprovalAction({
+            actionName: "ReviewCustomization",
+            notificationTopic: failureTopic,
+            additionalInformation: `Review ${customization.path}: approve only intended runtime behavior; infrastructure and credentials stay deployment-owned.`,
+            externalEntityLink: `https://github.com/${customization.repository}/blob/${customizationSourceAction.variables.commitId}/${customizationLinkPath}`,
+          }),
+        ],
+      });
+    }
+    stages.push({
+      stageName: "Deploy",
+      actions: [
+        new actions.CodeBuildAction({
+          actionName: "BuildAndDeploy",
+          project,
+          input: source,
+          extraInputs: customizationSource === undefined ? undefined : [customizationSource],
+        }),
+      ],
+    });
+    this.pipeline = new codepipeline.Pipeline(this, "Pipeline", {
+      pipelineName: `${props.instance.naming.prefix}Deploy`,
+      // V2: cheaper for a pipeline that idles between merges, and the only
+      // type that takes triggers and variables.
+      pipelineType: codepipeline.PipelineType.V2,
+      restartExecutionOnUpdate: false,
+      stages,
+    });
+
+    // Nobody watches a pipeline that usually succeeds, so a failure has to
+    // come and find someone. The topic and its one email subscription above
+    // also notify the same human when a customization needs approval.
+    this.pipeline.onStateChange("OnFailure", {
+      description: `${props.instance.name} deploy failed`,
+      eventPattern: { detail: { state: ["FAILED"] } },
+      target: new cdk.aws_events_targets.SnsTopic(failureTopic),
+    });
+
+    new cdk.CfnOutput(this, "PipelineName", { value: this.pipeline.pipelineName });
+    new cdk.CfnOutput(this, "BuildRoleArn", { value: this.buildRole.roleArn });
+  }
+}

package/src/stacks/release-account-stack.ts

@@ -0,0 +1,229 @@
+/**
+ * The Foundry 41 release account: where a Foundation release is published
+ * FROM, and what customers are allowed to read.
+ *
+ * This is the only stack in this package that is not an instance's. It is
+ * deployed once, by hand, into Foundry 41's own account, and it holds four
+ * things:
+ *
+ *   - the release **bucket** — `releases/vX.Y.Z/{manifest.json,lambda/*.zip,
+ *     skills.tar.gz}` — readable by the registered customer accounts;
+ *   - the agent **image repository**, `foundation/agent`, pullable by the same
+ *     accounts (the adopted decision: a private repository plus a policy
+ *     listing customers, not ECR Public);
+ *   - the **signing key**, asymmetric and sign/verify only, which the release
+ *     workflow signs the manifest with and every deployer verifies against;
+ *   - the **OIDC role** the release workflow assumes, trusted only for tag
+ *     pushes on the Foundation repository.
+ *
+ * The customer account list is the customer list. Adding a customer is a
+ * parameter change and a redeploy of this stack — deliberately a Foundry 41
+ * action, and the only one in a customer's install path.
+ *
+ * Nothing here is deployed by `foundation-deploy`, and no instance stack
+ * depends on it. `bin/release-account.ts` is its entry point.
+ */
+import * as cdk from "aws-cdk-lib";
+import * as ecr from "aws-cdk-lib/aws-ecr";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as kms from "aws-cdk-lib/aws-kms";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import type { Construct } from "constructs";
+
+export interface ReleaseAccountStackProps extends cdk.StackProps {
+  /** The release bucket's name. Global, so it is an input rather than derived. */
+  bucketName: string;
+  /** The agent image repository, without a registry. */
+  repositoryName?: string;
+  /**
+   * Customer AWS account ids allowed to read releases and pull the image.
+   * May be empty before the first customer is registered.
+   */
+  customerAccountIds: readonly string[];
+  /** `owner/repo` whose TAG pushes may publish a release. */
+  githubRepository: string;
+  /**
+   * The repository's immutable numeric ids.
+   *
+   * GitHub can issue the OIDC `sub` claim in two shapes, and which one it
+   * sends is the repository's setting, not ours: a repository with immutable
+   * subject claims on sends
+   * `repo:<owner>@<ownerId>/<repo>@<repoId>:ref:refs/tags/vX`, and the plain
+   * `repo:<owner>/<repo>:...` form never appears. Trusting only the plain form
+   * is why the first `v0.1.0` tag could not assume this role. `ci-stack` had
+   * always trusted both; this stack had not.
+   */
+  githubRepositoryIds: { owner: number; repo: number };
+  /** Alias for the signing key, without the `alias/` prefix. */
+  signingKeyAlias?: string;
+  /** The role the release workflow assumes through OIDC. */
+  releaseRoleName?: string;
+}
+
+export class ReleaseAccountStack extends cdk.Stack {
+  public readonly bucket: s3.Bucket;
+  public readonly repository: ecr.Repository;
+  public readonly signingKey: kms.Key;
+  public readonly releaseRole: iam.Role;
+
+  constructor(scope: Construct, id: string, props: ReleaseAccountStackProps) {
+    super(scope, id, props);
+
+    const repositoryName = props.repositoryName ?? "foundation/agent";
+    const customers = [...props.customerAccountIds];
+    // An empty list must not become a policy that names nobody and therefore
+    // grants nothing to everybody by accident; each grant below is omitted
+    // entirely until there is an account to name.
+    const customerPrincipals = customers.map((account) => new iam.AccountPrincipal(account));
+
+    this.bucket = new s3.Bucket(this, "ReleaseBucket", {
+      bucketName: props.bucketName,
+      // Every release is immutable, and versioning is what makes deleting one
+      // by accident recoverable rather than terminal.
+      versioned: true,
+      encryption: s3.BucketEncryption.S3_MANAGED,
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      enforceSSL: true,
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+    });
+    if (customerPrincipals.length > 0)
+      this.bucket.addToResourcePolicy(
+        new iam.PolicyStatement({
+          sid: "CustomersReadReleases",
+          principals: customerPrincipals,
+          actions: ["s3:GetObject", "s3:GetObjectVersion"],
+          // Only under `releases/`: nothing else in this bucket is published.
+          resources: [this.bucket.arnForObjects("releases/*")],
+        }),
+      );
+
+    this.repository = new ecr.Repository(this, "AgentRepository", {
+      repositoryName,
+      imageScanOnPush: true,
+      // A release tag is written once and referenced by digest thereafter.
+      imageTagMutability: ecr.TagMutability.IMMUTABLE,
+      encryption: ecr.RepositoryEncryption.AES_256,
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+    });
+    if (customerPrincipals.length > 0)
+      this.repository.addToResourcePolicy(
+        new iam.PolicyStatement({
+          sid: "CustomersPullAgentImage",
+          principals: customerPrincipals,
+          actions: [
+            "ecr:BatchGetImage",
+            "ecr:GetDownloadUrlForLayer",
+            "ecr:BatchCheckLayerAvailability",
+            "ecr:DescribeImages",
+          ],
+        }),
+      );
+
+    // Asymmetric and SIGN_VERIFY: the private half never leaves KMS, and a
+    // deployer needs only `kms:Verify`, which the policy below grants
+    // cross-account. RSA_4096 with RSASSA_PSS_SHA_256 is what
+    // `src/release/kms.ts` signs with.
+    this.signingKey = new kms.Key(this, "ReleaseSigningKey", {
+      alias: props.signingKeyAlias ?? "foundation-release",
+      description: "Signs Foundation release manifests. Customers verify against it.",
+      keySpec: kms.KeySpec.RSA_4096,
+      keyUsage: kms.KeyUsage.SIGN_VERIFY,
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+    });
+    if (customerPrincipals.length > 0)
+      this.signingKey.addToResourcePolicy(
+        new iam.PolicyStatement({
+          sid: "CustomersVerifyManifests",
+          principals: customerPrincipals,
+          // Verify and GetPublicKey only. Nothing here can sign.
+          actions: ["kms:Verify", "kms:GetPublicKey", "kms:DescribeKey"],
+          resources: ["*"],
+        }),
+      );
+
+    // Imported, not created: an account may hold only one provider per url, and
+    // a `cdk destroy` of a created one would take it from every other
+    // repository that trusts GitHub.
+    //
+    // A DEDICATED release account starts with no provider at all, though, and
+    // then this import silently yields an ARN that does not resolve: the role
+    // is created, and every assume fails with "the web identity token provided
+    // could not be validated". That is what happened to this account. Create it
+    // once, before deploying this stack:
+    //
+    //   aws iam create-open-id-connect-provider \
+    //     --url https://token.actions.githubusercontent.com \
+    //     --client-id-list sts.amazonaws.com \
+    //     --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1
+    const provider = iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn(
+      this,
+      "GitHubOidc",
+      `arn:${this.partition}:iam::${this.account}:oidc-provider/token.actions.githubusercontent.com`,
+    );
+
+    const [owner, repo] = props.githubRepository.split("/");
+    const ids = props.githubRepositoryIds;
+    const tagSubjects = [
+      `repo:${props.githubRepository}:ref:refs/tags/v*`,
+      `repo:${owner}@${ids.owner}/${repo}@${ids.repo}:ref:refs/tags/v*`,
+    ];
+
+    this.releaseRole = new iam.Role(this, "ReleaseRole", {
+      roleName: props.releaseRoleName ?? "FoundationRelease",
+      description: `Publishes Foundation releases from tag pushes on ${props.githubRepository}`,
+      maxSessionDuration: cdk.Duration.hours(1),
+      assumedBy: new iam.WebIdentityPrincipal(provider.openIdConnectProviderArn, {
+        StringEquals: { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
+        // TAGS ONLY. A branch push, a pull request and a workflow_dispatch all
+        // carry a different subject, so none of them can publish a release.
+        // Both shapes GitHub can issue, for the reason on
+        // {@link ReleaseAccountStackProps.githubRepositoryIds}.
+        StringLike: { "token.actions.githubusercontent.com:sub": tagSubjects },
+      }),
+      inlinePolicies: {
+        PublishRelease: new iam.PolicyDocument({
+          statements: [
+            new iam.PolicyStatement({
+              sid: "UploadRelease",
+              // No delete: a release is written once. Overwriting one is a
+              // separate, deliberate act by a human with other credentials.
+              actions: ["s3:PutObject", "s3:GetObject", "s3:ListBucket"],
+              resources: [this.bucket.bucketArn, this.bucket.arnForObjects("releases/*")],
+            }),
+            new iam.PolicyStatement({
+              sid: "PushAgentImage",
+              actions: [
+                "ecr:BatchCheckLayerAvailability",
+                "ecr:CompleteLayerUpload",
+                "ecr:InitiateLayerUpload",
+                "ecr:PutImage",
+                "ecr:UploadLayerPart",
+                "ecr:BatchGetImage",
+                "ecr:DescribeImages",
+              ],
+              resources: [this.repository.repositoryArn],
+            }),
+            new iam.PolicyStatement({
+              sid: "EcrLogin",
+              actions: ["ecr:GetAuthorizationToken"],
+              resources: ["*"],
+            }),
+            new iam.PolicyStatement({
+              sid: "SignManifest",
+              actions: ["kms:Sign", "kms:GetPublicKey", "kms:DescribeKey"],
+              resources: [this.signingKey.keyArn],
+            }),
+          ],
+        }),
+      },
+    });
+
+    // The three values a release needs: the workflow's variables, and the key
+    // ARN customers verify against.
+    new cdk.CfnOutput(this, "ReleaseBucketName", { value: this.bucket.bucketName });
+    new cdk.CfnOutput(this, "AgentRepositoryUri", { value: this.repository.repositoryUri });
+    new cdk.CfnOutput(this, "SigningKeyArn", { value: this.signingKey.keyArn });
+    new cdk.CfnOutput(this, "ReleaseRoleArn", { value: this.releaseRole.roleArn });
+    new cdk.CfnOutput(this, "CustomerAccountIds", { value: customers.join(",") });
+  }
+}