@guardian/cdk 63.3.1 → 63.5.0

package/lib/experimental/patterns/gu-load-balanced-app.d.ts

@@ -0,0 +1,351 @@
+import { Duration } from "aws-cdk-lib";
+import type { BlockDevice, UpdatePolicy } from "aws-cdk-lib/aws-autoscaling";
+import type { InstanceType, ISubnet, IVpc } from "aws-cdk-lib/aws-ec2";
+import { UserData } from "aws-cdk-lib/aws-ec2";
+import { FargateService } from "aws-cdk-lib/aws-ecs";
+import type { HealthCheck as ALBHealthCheck } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { Construct } from "constructs";
+import { GuCertificate } from "../../constructs/acm";
+import type { GuUserDataProps } from "../../constructs/autoscaling";
+import { GuAutoScalingGroup } from "../../constructs/autoscaling";
+import type { NoMonitoring } from "../../constructs/cloudwatch";
+import type { GuStack } from "../../constructs/core";
+import { AppIdentity } from "../../constructs/core";
+import type { GuInstanceRoleProps } from "../../constructs/iam";
+import { GuApplicationLoadBalancer, GuApplicationTargetGroup, GuHttpsApplicationListener, type WafProps } from "../../constructs/loadbalancing";
+import type { Alarms, ApplicationLoggingProps } from "../../patterns";
+import { AppAccess } from "../../types";
+import type { GuAsgCapacity, GuDomainName } from "../../types";
+import type { AmigoProps } from "../../types/amigo";
+export interface GuLoadBalancedAppExperimentalProps extends AppIdentity {
+    /**
+     * Network access restrictions for your load balancer.
+     *
+     * Note, this merely provides defence in depth; you should NOT rely on network access restrictions alone for
+     * restricting access. Use Google Auth for human access, or a suitable machine auth mechanism.
+     */
+    access: AppAccess;
+    /**
+     * The port your application runs on.
+     */
+    applicationPort: number;
+    /**
+     * Enable access logging for this load balancer.
+     * Access logs are written to an S3 bucket within your AWS account.
+     * The bucket is created by {@link https://github.com/guardian/aws-account-setup}.
+     * The logs are queryable via the `gucdk_access_logs` Athena database.
+     *
+     * @defaultValue true
+     */
+    withAccessLogging?: boolean;
+    /**
+     * Enable and configure alarms.
+     */
+    monitoringConfiguration: Alarms | NoMonitoring;
+    /**
+     * Specify certificate for the load balancer.
+     */
+    certificateProps?: GuDomainName;
+    /**
+     * Specify the VPC to use.
+     *
+     * @see https://github.com/guardian/aws-account-setup
+     */
+    vpc?: IVpc;
+    /**
+     * Specify private subnets if using a non-default VPC or (generally
+     * discouraged) to limit to a subset of the available subnets.
+     */
+    privateSubnets?: ISubnet[];
+    /**
+     * Specify public subnets if using a non-default VPC or (generally
+     * discouraged) to limit to a subset of the available subnets.
+     */
+    publicSubnets?: ISubnet[];
+    /**
+     * Configure Google Auth.
+     */
+    googleAuth?: {
+        /**
+         * Enables Google Auth (via Cognito). **Additional MANUAL steps required -
+         * see below.**
+         *
+         * Limits access to members of the allowed Google groups.
+         *
+         * Note, this does not currently support simultaneous machine access, so
+         * only set to true if you only require staff access to your service, or are
+         * supporting machine access in some other way.
+         *
+         * MANUAL STEPS: to get this to work, we need a Google Project and
+         * associated credentials. Full instructions can be found here:
+         *
+         * https://docs.google.com/document/d/1_k1FSE52AZHXufWLTiKTI3xy5cGpziyHazSHTKrYfco/edit?usp=sharing
+         *
+         * DevX hope to automate this process in the near future.
+         */
+        enabled: true;
+        /**
+         * The domain users will access your service.
+         *
+         * Set this to the same as for certificateProps.
+         */
+        domain: string;
+        /**
+         * Groups used for membership checks.
+         *
+         * If specified, cannot be empty. Users must be a member of at least one
+         * group to gain access.
+         *
+         * WARNING: groups must be specified with the `guardian.co.uk` domain, even
+         * if that is the non-idiomatic choice for daily use.
+         *
+         * @defaultValue [`engineering@guardian.co.uk`]
+         */
+        allowedGroups?: string[];
+        /**
+         * The number of minutes before the session expires.
+         *
+         * Set this value to a safe period of time that revoked users
+         * sessions will continue to function.
+         *
+         * NOTE: This value cannot be larger than 60 minutes.
+         *
+         * @defaultValue 15
+         */
+        sessionTimeoutInMinutes?: number;
+        /**
+         * Secrets Manager path containing Google OAuth2 Client credentials.
+         *
+         * NOTE: you do not need to set this value, but you DO need to generate and
+         * store the associated credentials in Secrets Manager.
+         *
+         * Credentials should be stored in Secrets Manager as JSON:
+         *
+         * ```json
+         * {
+         *   "clientId": "my-client-id",
+         *   "clientSecret": "my-client-secret"
+         * }
+         * ```
+         *
+         * @see `googleAuth.enabled` for how to generate.
+         *
+         * @defaultValue /:STAGE/:stack/:app/google-auth-credentials
+         */
+        credentialsSecretsManagerPath?: string;
+        /**
+         * When using Auth in the ALB, which stage of cognito-lambda to use.
+         *
+         * For most applications this should always be PROD, even in the CODE environments.
+         *
+         * @defaultValue PROD
+         */
+        cognitoAuthStage?: string;
+    };
+    /**
+     * Specify custom healthcheck
+     */
+    healthcheck?: ALBHealthCheck;
+    /**
+     * You can specify if the arn of this load balancer should be exposed for protection via WAF
+     *
+     * If this value changes, it is only picked up on WAF configuration redeploy.
+     *
+     * NB this parameter setting _alone_ is not sufficient to protect the application.
+     * You must also ensure that the application and stage combination is present in the WAF
+     * configuration.
+     *
+     * See https://github.com/guardian/waf/tree/main/lib
+     *
+     * There is a "gotcha" when migrating to this functionality.  You may not change only the Logical
+     * ID of an SSM Parameter (see https://docs.aws.amazon.com/cdk/v2/guide/identifiers.html) and the
+     * parameter name must be of the required form, meaning you cannot have an alternate name.
+     *
+     * You can either:
+     *
+     * Remove the old param and immediately redeploy with the new param (this does not affect
+     * protection unless and until the WAF configuration is redeployed)
+     *
+     *   OR
+     *
+     * Create an escape hatch by overriding the logical id (see "ssm param escape hatch" test for example)
+     **/
+    waf?: WafProps;
+    /**
+     * If you want to use an AutoScaling Group with EC2 instances to serve requests, then pass in relevant props here.
+     *
+     * If you are setting both `ec2Props` and `ecsProps` (i.e. if you are migrating from EC2 to ECS) then you must also
+     * specify weights for each compute type using `targetGroupWeights`.
+     */
+    ec2Props?: {
+        /**
+         * User data for the autoscaling group.
+         */
+        userData: GuUserDataProps | UserData;
+        /**
+         * EC2 instance type. Note, ensure your code is built for the same
+         * architecture family (arm64 - 'Graviton' instances - or x64).
+         */
+        instanceType: InstanceType;
+        /**
+         * Enable and configures application logs.
+         */
+        applicationLogging?: ApplicationLoggingProps;
+        /**
+         * Configure IAM roles for autoscaling group EC2 instances.
+         */
+        roleConfiguration?: GuInstanceRoleProps;
+        /**
+         * Add block devices (additional storage).
+         */
+        blockDevices?: BlockDevice[];
+        /**
+         * Autoscaling group min and max sizes.
+         */
+        scaling: GuAsgCapacity;
+        /**
+         * Configure AMIgo image recipe. This is only necessary if you are using GuCDK to generate your riff-raff.yaml file.
+         */
+        imageRecipe?: string | AmigoProps;
+        /**
+         * Set http put response hop limit for the launch template.
+         * It can be necessary to raise this value from the default of 1
+         * for example when sharing the instance profile with a docker container running on the instance.
+         */
+        instanceMetadataHopLimit?: number;
+        /**
+         * Specify an update policy for the ASG created by this pattern.
+         *
+         * @see https://docs.aws.amazon.com/cdk/api/latest/docs/aws-autoscaling-readme.html#update-policy
+         *
+         * @defaultValue UpdatePolicy.none() - Cloudformation does not attempt to rotate instances in the ASG
+         * and must rely on riffraff to do so.
+         */
+        updatePolicy?: UpdatePolicy;
+        /**
+         * Enable CloudFormation-only deployments for EC2.
+         *
+         * In order to use this feature you must include the build number in the name of the artifact that you upload to
+         * Riff-Raff. Your userData should also refer to this versioned artifact.
+         *
+         * Users migrating from the `GuEc2AppExperimental` pattern can keep existing deployment behaviour by configuring
+         * these props.
+         */
+        versionedDeployments?: {
+            enabled: boolean;
+            buildIdentifier: string;
+            slowStartDuration?: Duration;
+        };
+        /**
+         * You can specify how long after an instance reaches the InService state it waits before contributing
+         * usage data to the aggregated metrics. This specified time is called the default instance warmup.
+         * This keeps dynamic scaling from being affected by metrics for individual instances that aren't yet
+         * handling application traffic and that might be experiencing temporarily high usage of compute resources.
+         *
+         * @see https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-default-instance-warmup.html
+         */
+        defaultInstanceWarmup?: Duration;
+        /**
+         * How often to send EC2 metrics, such as CPU usage.
+         * By default, AWS will produce `5Minute` granular metrics.
+         *
+         * It is recommended to produce `1Minute` granular metrics in production,
+         * especially when using ASG metrics to trigger horizontal scaling as it allows for earlier scaling.
+         *
+         * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html
+         */
+        instanceMetricGranularity: "1Minute" | "5Minute";
+    };
+    /**
+     * If you want to use an ECS service and ECS tasks to serve requests, then pass in relevant props here.
+     *
+     * If you are setting both `ecsProps` and `ec2Props` (i.e. if you are migrating from EC2 to ECS) then you must also
+     * specify weights for each compute type using `targetGroupWeights`.
+     */
+    ecsProps?: {
+        /**
+         * Which image to run.
+         * This should be the image digest (e.g. 'sha256:abc123') to ensure immutable deployments.
+         *
+         * @see https://docs.docker.com/dhi/core-concepts/digests
+         */
+        imageIdentifier: string;
+        cpu: number;
+        memoryLimitMiB: number;
+        /**
+         * ECR repository name which contains your images. This defaults to the name of your GitHub repository as we
+         * expect there to be a one-to-one mapping between GitHub repositories and ECR repositories.
+         */
+        repositoryName?: string;
+        /**
+         * The number of tasks that you want to run. We recommend running 3 tasks for production services which need a high
+         * level of availability so that all 3 Availability Zones are utilised.
+         */
+        scaling: {
+            /**
+             * Scaling actions will never scale down below this threshold. This also controls the number of tasks that
+             * your ECS service will launch when it is first created.
+             */
+            minimumTasks: number;
+            /**
+             * Scaling actions will never scale up above this threshold.
+             *
+             * Note that this max can be exceeded when a deployment runs (unlike the ASG max size). E.g. if maximumTasks is 6,
+             * the service is running 6 tasks and a deployment starts, the ECS service will briefly run with 12 tasks to get
+             * the deployment through.
+             */
+            maximumTasks: number;
+        };
+    };
+    /**
+     * If you are specifying `ec2Props` and `ecsProps` use these weights to distribute traffic across the different compute
+     * types. The weights must sum to 999.
+     */
+    targetGroupWeights?: {
+        ecs: number;
+        ec2: number;
+    };
+}
+interface TargetGroups {
+    ec2?: GuApplicationTargetGroup;
+    ecs?: GuApplicationTargetGroup;
+}
+export declare class GuLoadBalancedAppExperimental extends Construct {
+    /**
+     * The VPC that the pattern's load balancer, EC2 instances and/or ECS tasks are running in.
+     */
+    readonly vpc: IVpc;
+    /**
+     * The certificate associated with your load balancer. This will only be available if `certificateProps` were
+     * passed in.
+     */
+    readonly certificate?: GuCertificate;
+    /**
+     * The application load balancer that this pattern creates.
+     */
+    readonly loadBalancer: GuApplicationLoadBalancer;
+    /**
+     * The AutoScaling Group that this pattern creates. This will only be available if `ec2Props` are specified.
+     */
+    readonly autoScalingGroup?: GuAutoScalingGroup;
+    /**
+     * The ECS Service that this pattern creates. This will only be available if `ecsProps` are specified.
+     */
+    readonly ecsService?: FargateService;
+    /**
+     * The load balancer listener that this pattern creates.
+     */
+    readonly listener: GuHttpsApplicationListener;
+    /**
+     * The target groups capable of serving traffic routed to this pattern.
+     *
+     * If `ec2Props` were passed in but `ecsProps` were not, there will be a single EC2 target group.
+     * Similarly, if `ecsProps` were passed in but `ec2Props` were not, there will be a single ECS target group.
+     * If both `ec2Props` and `ecsProps` were passed in (e.g. during a migration) then both target groups will be
+     * available.
+     */
+    readonly targetGroups: TargetGroups;
+    constructor(scope: GuStack, props: GuLoadBalancedAppExperimentalProps);
+}
+export {};
+//# sourceMappingURL=gu-load-balanced-app.d.ts.map

package/lib/experimental/patterns/gu-load-balanced-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gu-load-balanced-app.d.ts","sourceRoot":"","sources":["../../../src/experimental/patterns/gu-load-balanced-app.ts"],"names":[],"mappings":"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"}