feat(aws-fsx): L2 construct for FSx for Lustre

packages/@aws-cdk/aws-fsx/README.md

@@ -17,8 +17,188 @@
 ---
 <!--END STABILITY BANNER-->
 
-This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+[Amazon FSx](https://docs.aws.amazon.com/fsx/?id=docs_gateway) provides fully managed third-party file systems with the
+native compatibility and feature sets for workloads such as Microsoft Windows–based storage, high-performance computing,
+machine learning, and electronic design automation.
+
+Amazon FSx supports two file system types: [Lustre](https://docs.aws.amazon.com/fsx/latest/LustreGuide/index.html) and
+[Windows](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/index.html) File Server.
+
+## FSx for Lustre
+
+Amazon FSx for Lustre makes it easy and cost-effective to launch and run the popular, high-performance Lustre file
+system. You use Lustre for workloads where speed matters, such as machine learning, high performance computing (HPC),
+video processing, and financial modeling.
+
+The open-source Lustre file system is designed for applications that require fast storage—where you want your storage
+to keep up with your compute. Lustre was built to solve the problem of quickly and cheaply processing the world's
+ever-growing datasets. It's a widely used file system designed for the fastest computers in the world. It provides
+submillisecond latencies, up to hundreds of GBps of throughput, and up to millions of IOPS. For more information on
+Lustre, see the [Lustre website](http://lustre.org/).
+
+As a fully managed service, Amazon FSx makes it easier for you to use Lustre for workloads where storage speed matters.
+Amazon FSx for Lustre eliminates the traditional complexity of setting up and managing Lustre file systems, enabling
+you to spin up and run a battle-tested high-performance file system in minutes. It also provides multiple deployment
+options so you can optimize cost for your needs.
+
+Amazon FSx for Lustre is POSIX-compliant, so you can use your current Linux-based applications without having to make
+any changes. Amazon FSx for Lustre provides a native file system interface and works as any file system does with your
+Linux operating system. It also provides read-after-write consistency and supports file locking.
+
+### Installation
+
+Import to your project:
 
 ```ts
 import fsx = require('@aws-cdk/aws-fsx');
 ```
+
+### Basic Usage
+
+Setup required properties and create:
+
+```ts
+const stack = new Stack(app, 'Stack');
+const vpc = new Vpc(stack, 'VPC');
+const storageCapacity = 1200;
+const lustreConfiguration = {
+  deploymentType: FsxLustreDeploymentType.SCRATCH_2
+};
+
+const fileSystem = new FsxLustreFileSystem(stack, 'FsxLustreFileSystem', {
+  lustreConfiguration,
+  storageCapacity,
+  vpc,
+  vpcSubnet: vpc.privateSubnets[0]});
+```
+
+### Connecting
+
+To control who can access the file system, use the `.connections` attribute. FSx has a fixed default port, so you don't
+need to specify the port. This example allows an EC2 instance to connect to a file system:
+
+```ts
+fileSystem.connections.allowDefaultPortFrom(instance);
+```
+
+### Mounting
+
+To mount an FSx for Lustre file system programmatically, the mount name of the file system needs to be determined. The
+easiest way to do that is with the AWS CLI, which can be written into a User Data script to be run on start-up of your
+instance. The following example can be used for reference on how to bring up a file system and EC2 instance with the
+file system mounted on the instance at start-up:
+
+```ts
+const app = new App();
+const stack = new Stack(app, 'AwsCdkFsxLustre');
+const vpc = new Vpc(stack, 'VPC');
+
+// Create a security group to share across the file system and ec2 instance and open the FSx ports.
+const securityGroup = new SecurityGroup(stack, 'FsxLustreSecurityGroup', {
+  vpc
+});
+securityGroup.addIngressRule(Peer.anyIpv4(), Port.tcp(988), 'Default FSx port ingress');
+securityGroup.addEgressRule(Peer.anyIpv4(), Port.tcp(988), 'Default FSx port egress');
+
+const lustreConfiguration = {
+  deploymentType: FsxLustreDeploymentType.SCRATCH_2,
+};
+const fs = new FsxLustreFileSystem(stack, 'FsxLustreFileSystem', {
+  lustreConfiguration,
+  securityGroup,
+  storageCapacity: 1200,
+  vpc,
+  vpcSubnet: vpc.privateSubnets[0]});
+
+const inst = new Instance(stack, 'Ec2Instance', {
+  instanceType: InstanceType.of(InstanceClass.T2, InstanceSize.LARGE),
+  machineImage: new AmazonLinuxImage({
+    generation: AmazonLinuxGeneration.AMAZON_LINUX_2
+  }),
+  securityGroup,
+  vpc,
+  vpcSubnets: {
+    subnetType: SubnetType.PUBLIC,
+  }
+});
+
+// Need to give the instance access to read information about FSx to determine the file system's mount name.
+inst.role.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("AmazonFSxReadOnlyAccess"));
+
+// Add a dependency on the file system to the instance so that we can be sure the file system is instantiated before querying
+// for its mount name.
+inst.node.addDependency(fs);
+
+const mountPath = '/mnt/fsx';
+const dnsName = `${fs.fileSystemId}.fsx.${stack.region}.amazonaws.com`;
+
+inst.userData.addCommands(
+  'set -eux',
+  'yum update -y',
+  'amazon-linux-extras install -y lustre2.10',
+
+  // The version of the AWS CLI currently on AL2 doesn't surface the required MountName field, so install the latest version.
+  'curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"',
+  'unzip awscliv2.zip',
+  './aws/install',
+
+  // Write a python script to parse the json response from the AWS CLI and determine the mount name for the file system.
+  'mountScript=$(mktemp --suffix=".py")',
+  `echo 'import json,sys' >> $mountScript`,
+  `echo 'obj=json.load(sys.stdin)' >> $mountScript`,
+  `echo 'for fs in obj["FileSystems"]:' >> $mountScript`,
+  `echo '  if fs["DNSName"] == "${dnsName}":' >> $mountScript`,
+  `echo '    print(fs["LustreConfiguration"]["MountName"])' >> $mountScript`,
+  `chmod +x $mountScript`,
+
+  // Call the AWS CLI and pipe it into the python script.
+  `mountName=$(/usr/local/bin/aws fsx describe-file-systems --output json --region ${stack.region} | python $mountScript)`,
+
+  // Set up the directory to mount the file system to and mounting it.
+  `mkdir -p ${mountPath}`,
+  `chmod 777 ${mountPath}`,
+  `echo "${dnsName}@tcp:/$mountName ${mountPath} lustre defaults,noatime,flock,_netdev 0 0" | tee -a /etc/fstab`,
+  `mount -t lustre ${dnsName}@tcp:/$mountName ${mountPath}`,
+  'rm $mountScript');
+```
+
+### Importing
+
+An FSx for Lustre file system can be imported with `fromFsxLustreFileSystemAttributes(stack, id, attributes)`. The
+following example lays out how you could import the SecurityGroup a file system belongs to, use that to import the file
+system, and then also import the VPC the file system is in and add an EC2 instance to it, giving it access to the file
+system.
+
+```ts
+const app = new App();
+const stack = new Stack(app, 'AwsCdkFsxLustreImport');
+
+const sg = SecurityGroup.fromSecurityGroupId(stack, 'FsxSecurityGroup', '{SECURITY-GROUP-ID}');
+const fs = FsxLustreFileSystem.fromFsxLustreFileSystemAttributes(stack, 'FsxLustreFileSystem', {
+    fileSystemId: '{FILE-SYSTEM-ID}',
+    securityGroup: sg
+});
+
+const vpc = Vpc.fromVpcAttributes(stack, 'Vpc', {
+    availabilityZones: ['us-west-2a', 'us-west-2b'],
+    publicSubnetIds: ['{US-WEST-2A-SUBNET-ID}', '{US-WEST-2B-SUBNET-ID}'],
+    vpcId: '{VPC-ID}'
+});
+const inst = new Instance(stack, 'inst', {
+  instanceType: InstanceType.of(InstanceClass.T2, InstanceSize.LARGE),
+  machineImage: new AmazonLinuxImage({
+    generation: AmazonLinuxGeneration.AMAZON_LINUX_2
+  }),
+  vpc,
+  vpcSubnets: {
+    subnetType: SubnetType.PUBLIC,
+  }
+});
+
+fs.connections.allowDefaultPortFrom(inst);
+```
+
+## FSx for Windows
+
+The L2 construct for the FSx for Windows file system has not yet been implemented. To instantiate an FSx for Windows
+file system, the L1 constructs can be used as defined by CloudFormation.

packages/@aws-cdk/aws-fsx/lib/file-system.ts

@@ -0,0 +1,87 @@
+import {Connections, IConnectable, ISecurityGroup,  IVpc} from "@aws-cdk/aws-ec2";
+import {IKey} from "@aws-cdk/aws-kms";
+import {Resource} from "@aws-cdk/core";
+
+/**
+ * Interface to implement FSx File Systems.
+ */
+export interface IFsxFileSystem extends IConnectable {
+    /**
+     * The ID of the file system, assigned by Amazon FSx.
+     * @attribute
+     */
+    readonly fileSystemId: string;
+}
+
+/**
+ * Properties for the FSx file system
+ *
+ * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-fsx-filesystem.html
+ */
+export interface FsxFileSystemProps {
+  /**
+   * The VPC to launch the file system in.
+   */
+  readonly vpc: IVpc;
+
+  /**
+   * The ID of the backup. Specifies the backup to use if you're creating a file system from an existing backup.
+   *
+   * @default - no backup will be used.
+   */
+  readonly backupId?: string;
+
+  /**
+   * The KMS key used for encryption to protect your data at rest.
+   *
+   * @default - the aws/fsx default KMS key for the AWS account being deployed into.
+   */
+  readonly kmsKey?: IKey;
+
+  /**
+   * Security Group to assign to this file system.
+   *
+   * @default - creates new security group which allows all outbound traffic.
+   */
+  readonly securityGroup?: ISecurityGroup;
+
+  /**
+   * The storage capacity of the file system being created.
+   * For Windows file systems, valid values are 32 GiB to 65,536 GiB.
+   * For SCRATCH_1 deployment types, valid values are 1,200, 2,400, 3,600, then continuing in increments of 3,600 GiB.
+   * For SCRATCH_2 and PERSISTENT_1 types, valid values are 1,200, 2,400, then continuing in increments of 2,400 GiB.
+   */
+  readonly storageCapacity: number;
+}
+
+/**
+ * A new or imported FSx file system.
+ */
+export abstract class FsxFileSystemBase extends Resource implements IFsxFileSystem {
+  /**
+   * The security groups/rules used to allow network connections to the file system.
+   * @attribute
+   */
+  public abstract readonly connections: Connections;
+
+  /**
+   * The ID of the file system, assigned by Amazon FSx.
+   * @attribute
+   */
+  public abstract readonly fileSystemId: string;
+}
+
+/**
+ * Properties that describe an existing FSx file system.
+ */
+export interface FsxFileSystemAttributes {
+  /**
+   * The ID of the file system, assigned by Amazon FSx.
+   */
+  readonly fileSystemId: string;
+
+  /**
+   * The security group of the file system.
+   */
+  readonly securityGroup: ISecurityGroup;
+}

packages/@aws-cdk/aws-fsx/lib/index.ts

@@ -1,2 +1,3 @@
-// AWS::FSx CloudFormation Resources:
+export * from './file-system';
 export * from './fsx.generated';
+export * from './lustre-file-system';