feat(efs): replicating file systems

packages/@aws-cdk-testing/framework-integ/test/aws-efs/test/integ.efs-filesystem-replication.ts

@@ -0,0 +1,45 @@
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as cdk from 'aws-cdk-lib';
+import * as efs from 'aws-cdk-lib/aws-efs';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import * as integ from '@aws-cdk/integ-tests-alpha';
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'efsReplication');
+
+const vpc = new ec2.Vpc(stack, 'Vpc', {
+  natGateways: 0,
+});
+
+const kmsKey = new kms.Key(stack, 'Key', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+});
+
+new efs.FileSystem(stack, 'oneZoneReplicationFileSystem', {
+  vpc,
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  replicationConfiguration: [{
+    kmsKey,
+    region: 'us-east-1',
+    availabilityZone: 'us-east-1a',
+  }],
+});
+
+const destination = new efs.FileSystem(stack, 'destinationFileSystem', {
+  vpc,
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  replicationOverwriteProtection: efs.ReplicationOverwriteProtection.DISABLED,
+});
+
+new efs.FileSystem(stack, 'existFileSystemReplication', {
+  vpc,
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  replicationConfiguration: [{
+    destinationFileSystem: destination,
+  }],
+});
+
+new integ.IntegTest(app, 'efsReplicationIntegTest', {
+  testCases: [stack],
+});
+app.synth();

packages/aws-cdk-lib/aws-efs/README.md

@@ -76,6 +76,42 @@ This is to prevent deployment failures due to cross-AZ configurations.
 
 ⚠️ When `oneZone` is enabled, `vpcSubnets` cannot be specified.
 
+### [Replicating file systems](https://docs.aws.amazon.com/efs/latest/ug/efs-replication.html)
+
+You can create a replica of your EFS file system in the AWS Region of your preference.
+
+```ts
+import * as kms from 'aws-cdk-lib/aws-kms';
+
+declare const vpc: ec2.Vpc;
+declare const kmsKey: kms.Key;
+
+// auto generate a replication destination file system
+new efs.FileSystem(this, 'ReplicationSourceFileSystem1', {
+  vpc,
+  replicationConfiguration: [{
+    kmsKey,
+    region: 'us-east-1',
+    availabilityZone: 'us-east-1a', // Specifing the AZ means creating a One Zone file system as the replication destination
+  }]
+});
+
+// specify the replication destination file system
+const destinationFileSystem = new efs.FileSystem(this, 'DestinationFileSystem', {
+  vpc,
+  // set as the read-only file system for use as a replication destination
+  replicationOverwriteProtection: efs.ReplicationOverwriteProtection.DISABLED,
+});
+
+new efs.FileSystem(this, 'ReplicationSourceFileSystem2', {
+  vpc,
+  replicationConfiguration: [{
+    destinationFileSystem,
+    // cannot configure other properties when destinationFileSystem is specified
+  }]
+});
+```
+
 ### IAM to control file system data access
 
 You can use both IAM identity policies and resource policies to control client access to Amazon EFS resources in a way that is scalable and optimized for cloud environments. Using IAM, you can permit clients to perform specific actions on a file system, including read-only, write, and root access.

packages/aws-cdk-lib/aws-efs/lib/efs-file-system.ts

@@ -4,7 +4,7 @@ import { CfnFileSystem, CfnMountTarget } from './efs.generated';
 import * as ec2 from '../../aws-ec2';
 import * as iam from '../../aws-iam';
 import * as kms from '../../aws-kms';
-import { ArnFormat, FeatureFlags, Lazy, RemovalPolicy, Resource, Size, Stack, Tags } from '../../core';
+import { ArnFormat, FeatureFlags, Lazy, RemovalPolicy, Resource, Size, Stack, Tags, Token } from '../../core';
 import * as cxapi from '../../cx-api';
 
 /**
@@ -324,6 +324,13 @@ export interface FileSystemProps {
    * @default ReplicationOverwriteProtection.ENABLED
    */
   readonly replicationOverwriteProtection?: ReplicationOverwriteProtection;
+
+  /**
+   * Replication configuration for the file system.
+   *
+   * @default - no replication
+   */
+  readonly replicationConfiguration?: ReplicationConfiguration[];
 }
 
 /**
@@ -350,6 +357,44 @@ export interface FileSystemAttributes {
   readonly fileSystemArn?: string;
 }
 
+/**
+ * Replication configuration for the file system.
+ */
+export interface ReplicationConfiguration {
+  /**
+   * The existing destination file system for the replication.
+   *
+   * You cannot configure `kmsKey`, `region` and `az` when `destinationFileSystem` is set.
+   *
+   * @default - create a new file system for the replication destination
+   */
+  readonly destinationFileSystem?: IFileSystem;
+
+  /**
+   * AWS KMS key used to protect the encrypted file system.
+   *
+   * @default - service-managed KMS key for Amazon EFS is used
+   */
+  readonly kmsKey?: kms.IKey;
+
+  /**
+   * The AWS Region in which the destination file system is located.
+   *
+   * @default - the region of the stack
+   */
+  readonly region?: string;
+
+  /**
+   * The availability zone name of the destination file system.
+   * One zone file system is used as the destination file system when this property is set.
+   *
+   * You have to specify the `region` property for the region that the specified availability zone belongs to.
+   *
+   * @default - create regional file system for the replication destination
+   */
+  readonly availabilityZone?: string;
+}
+
 enum ClientAction {
   MOUNT = 'elasticfilesystem:ClientMount',
   WRITE = 'elasticfilesystem:ClientWrite',
@@ -553,6 +598,30 @@ export class FileSystem extends FileSystemBase {
     if (props.throughputMode === ThroughputMode.ELASTIC && props.performanceMode === PerformanceMode.MAX_IO) {
       throw new Error('ThroughputMode ELASTIC is not supported for file systems with performanceMode MAX_IO');
     }
+
+    if (props.replicationConfiguration) {
+      if (props.replicationOverwriteProtection === ReplicationOverwriteProtection.DISABLED) {
+        throw new Error('Cannot configure `replicationConfiguration` when `replicationOverwriteProtection` is set to `DISABLED`');
+      }
+      if (props.replicationConfiguration.length !== 1) {
+        throw new Error('`replicationConfiguration` must contain exactly one destination');
+      }
+
+      props.replicationConfiguration.forEach((config) => {
+        const { destinationFileSystem, region, availabilityZone, kmsKey } = config;
+
+        if (destinationFileSystem && (region || availabilityZone || kmsKey)) {
+          throw new Error('Cannot configure `replicationConfiguration.region`, `replicationConfiguration.az` or `replicationConfiguration.kmsKey` when `replicationConfiguration.destinationFileSystem` is set');
+        }
+        if (region && !Token.isUnresolved(region) && !/^[a-z]{2}-((iso[a-z]{0,1}-)|(gov-)){0,1}[a-z]+-{0,1}[0-9]{0,1}$/.test(region)) {
+          throw new Error('`replicationConfiguration.region` is invalid.');
+        }
+        if (availabilityZone && !Token.isUnresolved(availabilityZone) && !region) {
+          throw new Error('`replicationConfiguration.availabilityZone` cannot be specified without `replicationConfiguration.region`');
+        }
+      });
+    }
+
     // we explictly use 'undefined' to represent 'false' to maintain backwards compatibility since
     // its considered an actual change in CloudFormations eyes, even though they have the same meaning.
     const encrypted = props.encrypted ?? (FeatureFlags.of(this).isEnabled(
@@ -579,6 +648,16 @@ export class FileSystem extends FileSystemBase {
       replicationOverwriteProtection: props.replicationOverwriteProtection,
     } : undefined;
 
+    const replicationConfiguration = props.replicationConfiguration ? {
+      destinations: props.replicationConfiguration.map(
+        (config) => ({
+          fileSystemId: config.destinationFileSystem?.fileSystemId,
+          kmsKeyId: config.kmsKey?.keyArn,
+          region: config.destinationFileSystem ? config.destinationFileSystem.env.region : (config.region ?? Stack.of(this).region),
+          availabilityZoneName: config.availabilityZone,
+        })),
+    } : undefined;
+
     this._resource = new CfnFileSystem(this, 'Resource', {
       encrypted: encrypted,
       kmsKeyId: props.kmsKey?.keyArn,
@@ -611,6 +690,7 @@ export class FileSystem extends FileSystemBase {
       }),
       fileSystemProtection,
       availabilityZoneName: props.oneZone ? oneZoneAzName : undefined,
+      replicationConfiguration,
     });
     this._resource.applyRemovalPolicy(props.removalPolicy);
 

packages/aws-cdk-lib/aws-efs/test/efs-file-system.test.ts

@@ -4,7 +4,7 @@ import * as iam from '../../aws-iam';
 import * as kms from '../../aws-kms';
 import { App, RemovalPolicy, Size, Stack, Tags } from '../../core';
 import * as cxapi from '../../cx-api';
-import { FileSystem, LifecyclePolicy, PerformanceMode, ThroughputMode, OutOfInfrequentAccessPolicy, ReplicationOverwriteProtection } from '../lib';
+import { FileSystem, LifecyclePolicy, PerformanceMode, ThroughputMode, OutOfInfrequentAccessPolicy, ReplicationOverwriteProtection, ReplicationConfiguration } from '../lib';
 
 let stack = new Stack();
 let vpc = new ec2.Vpc(stack, 'VPC');
@@ -958,3 +958,173 @@ test.each([
     },
   });
 });
+
+describe('replication configuration', () => {
+  test('default settings', () => {
+    // WHEN
+    new FileSystem(stack, 'EfsFileSystem', {
+      vpc,
+      replicationConfiguration: [{}],
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EFS::FileSystem', {
+      ReplicationConfiguration: {
+        Destinations: [
+          {
+            Region: {
+              Ref: 'AWS::Region',
+            },
+          },
+        ],
+      },
+    });
+  });
+
+  test('with destination file system', () => {
+    // WHEN
+    const destination = new FileSystem(stack, 'DestinationFileSystem', {
+      vpc,
+      replicationOverwriteProtection: ReplicationOverwriteProtection.DISABLED,
+    });
+    new FileSystem(stack, 'EfsFileSystem', {
+      vpc,
+      replicationConfiguration: [{
+        destinationFileSystem: destination,
+      }],
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EFS::FileSystem', {
+      ReplicationConfiguration: {
+        Destinations: [
+          {
+            FileSystemId: {
+              Ref: 'DestinationFileSystem12545967',
+            },
+          },
+        ],
+      },
+    });
+  });
+
+  test('with full settings', () => {
+    // WHEN
+    new FileSystem(stack, 'EfsFileSystem', {
+      vpc,
+      replicationConfiguration: [{
+        kmsKey: new kms.Key(stack, 'customKey'),
+        region: 'us-east-1',
+        availabilityZone: 'us-east-1a',
+      }],
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EFS::FileSystem', {
+      ReplicationConfiguration: {
+        Destinations: [
+          {
+            Region: 'us-east-1',
+            AvailabilityZoneName: 'us-east-1a',
+            KmsKeyId: {
+              'Fn::GetAtt': [
+                'customKeyFEB2B57F',
+                'Arn',
+              ],
+            },
+          },
+        ],
+      },
+    });
+  });
+
+  test('throw error for read-only file system', () => {
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration: [{
+          region: 'us-east-1',
+        }],
+        replicationOverwriteProtection: ReplicationOverwriteProtection.DISABLED,
+      });
+    }).toThrow('Cannot configure `replicationConfiguration` when `replicationOverwriteProtection` is set to `DISABLED`');
+  });
+
+  test.each([
+    { region: 'us-east-1' },
+    { availabilityZone: 'us-east-1a' },
+  ])('throw error for specifing both destinationFileSystem and other parameters', (config) => {
+    // WHEN
+    const destination = new FileSystem(stack, 'DestinationFileSystem', {
+      vpc,
+      replicationOverwriteProtection: ReplicationOverwriteProtection.DISABLED,
+    });
+
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration: [{
+          destinationFileSystem: destination,
+          ...config,
+        }],
+      });
+    }).toThrow('Cannot configure `replicationConfiguration.region`, `replicationConfiguration.az` or `replicationConfiguration.kmsKey` when `replicationConfiguration.destinationFileSystem` is set');
+  });
+
+  test('throw error for specifing both destinationFileSystem and kmsKey', () => {
+    // WHEN
+    const destination = new FileSystem(stack, 'DestinationFileSystem', {
+      vpc,
+      replicationOverwriteProtection: ReplicationOverwriteProtection.DISABLED,
+    });
+
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration: [{
+          destinationFileSystem: destination,
+          kmsKey: new kms.Key(stack, 'customKey'),
+        }],
+      });
+    }).toThrow('Cannot configure `replicationConfiguration.region`, `replicationConfiguration.az` or `replicationConfiguration.kmsKey` when `replicationConfiguration.destinationFileSystem` is set');
+  });
+
+  test('throw error for invalid region', () => {
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration: [{
+          region: 'invalid-region',
+        }],
+      });
+    }).toThrow('`replicationConfiguration.region` is invalid.');
+  });
+
+  test('throw error for specifying availabilityZone without region', () => {
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration: [{
+          availabilityZone: 'us-east-1a',
+        }],
+      });
+    }).toThrow('`replicationConfiguration.availabilityZone` cannot be specified without `replicationConfiguration.region`');
+  });
+
+  test.each([
+    [[]], [[{ region: 'us-east-1' }, { region: 'ap-northeast-1' }]],
+  ])('throw error for invalid length of replicationConfiguration', (replicationConfiguration) => {
+    // THEN
+    expect(() => {
+      new FileSystem(stack, 'EfsFileSystem', {
+        vpc,
+        replicationConfiguration,
+      });
+    }).toThrow('`replicationConfiguration` must contain exactly one destination');
+  });
+});