AWS efs documentation change
Summary
Updated documentation for CreateMountTarget API with IPv6 support, clarified network interface behavior, added IpAddressType parameter, and expanded examples
Security assessment
The changes introduce IPv6 support and clarify security group defaults (using VPC's default SG if none specified), which improves security documentation but does not address a specific vulnerability. No evidence of patching a security issue is present.
Diff
diff --git a/efs/latest/ug/API_CreateMountTarget.md b/efs/latest/ug/API_CreateMountTarget.md index 41cf1fc56..a6615db00 100644 --- a//efs/latest/ug/API_CreateMountTarget.md +++ b//efs/latest/ug/API_CreateMountTarget.md @@ -9,32 +9 @@ Request SyntaxURI Request ParametersRequest BodyResponse SyntaxResponse Elements -Creates a mount target for a file system. You can then mount the file system on EC2 instances by using the mount target. - -You can create one mount target in each Availability Zone in your VPC. All EC2 instances in a VPC within a given Availability Zone share a single mount target for a given file system. If you have multiple subnets in an Availability Zone, you create a mount target in one of the subnets. EC2 instances do not need to be in the same subnet as the mount target in order to access their file system. - -You can create only one mount target for a One Zone file system. You must create that mount target in the same Availability Zone in which the file system is located. Use the `AvailabilityZoneName` and `AvailabiltyZoneId` properties in the [DescribeFileSystems](./API_DescribeFileSystems.html) response object to get this information. Use the `subnetId` associated with the file system's Availability Zone when creating the mount target. - -For more information, see [Amazon EFS: How it Works](https://docs.aws.amazon.com/efs/latest/ug/how-it-works.html). - -To create a mount target for a file system, the file system's lifecycle state must be `available`. For more information, see [DescribeFileSystems](./API_DescribeFileSystems.html). - -In the request, provide the following: - - * The file system ID for which you are creating the mount target. - - * A subnet ID, which determines the following: - - * The VPC in which Amazon EFS creates the mount target - - * The Availability Zone in which Amazon EFS creates the mount target - - * The IP address range from which Amazon EFS selects the IP address of the mount target (if you don't specify an IP address in the request) - - - - -After creating the mount target, Amazon EFS returns a response that includes, a `MountTargetId` and an `IpAddress`. You use this IP address when mounting the file system in an EC2 instance. You can also use the mount target's DNS name when mounting the file system. The EC2 instance on which you mount the file system by using the mount target can resolve the mount target's DNS name to its IP address. For more information, see [How it Works: Implementation Overview](https://docs.aws.amazon.com/efs/latest/ug/how-it-works.html#how-it-works-implementation). - -Note that you can create mount targets for a file system in only one VPC, and there can be only one mount target per Availability Zone. That is, if the file system already has one or more mount targets created for it, the subnet specified in the request to add another mount target must meet the following requirements: - - * Must belong to the same VPC as the subnets of the existing mount targets - - * Must not be in the same Availability Zone as any of the subnets of the existing mount targets +Creates a mount target for a file system. You can then mount the file system on EC2 instances by using the mount target. For more information about mount targets, see [Managing mount targets](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs.html). @@ -41,0 +11 @@ Note that you can create mount targets for a file system in only one VPC, and th +To create a mount target for an EFS file system, the file system's lifecycle state must be `available`. For more information, see [DescribeFileSystems](./API_DescribeFileSystems.html). @@ -42,0 +13 @@ Note that you can create mount targets for a file system in only one VPC, and th +After creating the mount target, Amazon EFS returns a response that includes a `MountTargetId` and an IP address (`IpAddress` or `Ipv6Address`). You use this IP address when mounting the file system in an EC2 instance. You can also use the mount target's DNS name when mounting the file system. The EC2 instance on which you mount the file system by using the mount target can resolve the mount target's DNS name to its IP address. For more information, see [How Amazon EFS works](https://docs.aws.amazon.com/efs/latest/ug/how-it-works.html). @@ -43,0 +15 @@ Note that you can create mount targets for a file system in only one VPC, and th +Note that you can create mount targets for a file system in only one VPC, and there can be only one mount target per Availability Zone. For more information, see [Creating mount targets](https://docs.aws.amazon.com/efs/latest/ug/manage-fs-access-create-delete-mount-targets.html). @@ -49,3 +21 @@ If the request satisfies the requirements, Amazon EFS does the following: - * Also creates a new network interface in the subnet as follows: - - * If the request provides an `IpAddress`, Amazon EFS assigns that IP address to the network interface. Otherwise, Amazon EFS assigns a free address in the subnet (in the same way that the Amazon EC2 `CreateNetworkInterface` call does when a request does not specify a primary private IP address). + * Creates a new network interface in the subnet with the folowing: @@ -53 +23 @@ If the request satisfies the requirements, Amazon EFS does the following: - * If the request provides `SecurityGroups`, this network interface is associated with those security groups. Otherwise, it belongs to the default security group for the subnet's VPC. + * The description `Mount target _fsmt-id_ for file system _fs-id_ ` where ` _fsmt-id_ ` is the mount target ID, and ` _fs-id_ ` is the `FileSystemId`. @@ -55 +25 @@ If the request satisfies the requirements, Amazon EFS does the following: - * Assigns the description `Mount target _fsmt-id_ for file system _fs-id_ ` where ` _fsmt-id_ ` is the mount target ID, and ` _fs-id_ ` is the `FileSystemId`. + * The `requesterManaged` property of the network interface set to `true`, and the `requesterId` value set to `EFS`. @@ -57,3 +27 @@ If the request satisfies the requirements, Amazon EFS does the following: - * Sets the `requesterManaged` property of the network interface to `true`, and the `requesterId` value to `EFS`. - -Each Amazon EFS mount target has one corresponding requester-managed EC2 network interface. After the network interface is created, Amazon EFS sets the `NetworkInterfaceId` field in the mount target's description to the network interface ID, and the `IpAddress` field to its address. If network interface creation fails, the entire `CreateMountTarget` operation fails. +Each mount target has one corresponding requester-managed EC2 network interface. After the network interface is created, Amazon EFS sets the `NetworkInterfaceId` field in the mount target's description to the network interface ID, and the IP address to its address. If network interface creation fails, the entire `CreateMountTarget` operation fails. @@ -68,2 +35,0 @@ The `CreateMountTarget` call returns only after creating the network interface, -We recommend that you create a mount target in each of the Availability Zones. There are cost considerations for using a file system in an Availability Zone through a mount target created in another Availability Zone. For more information, see [Amazon EFS pricing](http://aws.amazon.com/efs/pricing/). In addition, by always using a mount target local to the instance's Availability Zone, you eliminate a partial failure scenario. If the Availability Zone in which your mount target is created goes down, then you can't access your file system through that mount target. - @@ -96,0 +63,2 @@ This operation also requires permissions for the following Amazon EC2 actions: + "IpAddressType": "string", + "Ipv6Address": "string", @@ -125 +93 @@ Required: Yes -Valid IPv4 address within the address range of the specified subnet. +If the `IpAddressType` for the mount target is IPv4 ( `IPV4_ONLY` or `DUAL_STACK`), then specify the IPv4 address to use. If you do not specify an `IpAddress`, then Amazon EFS selects an unused IP address from the subnet specified for `SubnetId`. @@ -134,0 +103,26 @@ Required: No +**IpAddressType ** + + +The IP address type for the mount target. The possible values are `IPV4_ONLY` (only IPv4 addresses), `IPV6_ONLY` (only IPv6 addresses), and `DUAL_STACK` (dual-stack, both IPv4 and IPv6 addresses). If you don’t specify an `IpAddressType`, then `IPV4_ONLY` is used. + +###### Note + +The `IPAddressType` must match the IP type of the subnet. Additionally, the `IPAddressType` parameter overrides the value set as the default IP address for the subnet in the VPC. For example, if the `IPAddressType` is `IPV4_ONLY` and `AssignIpv6AddressOnCreation` is `true`, then IPv4 is used for the mount target. For more information, see [Modify the IP addressing attributes of your subnet](https://docs.aws.amazon.com/vpc/latest/userguide/subnet-public-ip.html). + +Type: String + +Valid Values: `IPV4_ONLY | IPV6_ONLY | DUAL_STACK` + +Required: No + +**Ipv6Address ** + + +If the `IPAddressType` for the mount target is IPv6 (`IPV6_ONLY` or `DUAL_STACK`), then specify the IPv6 address to use. If you do not specify an `Ipv6Address`, then Amazon EFS selects an unused IP address from the subnet specified for `SubnetId`. + +Type: String + +Length Constraints: Minimum length of 3. Maximum length of 39. + +Required: No + @@ -138 +132 @@ Required: No -VPC security group IDs, of the form `sg-xxxxxxxx`. These must be for the same VPC as the subnet specified. The maximum number of security groups depends on account quota. For more information, see [Amazon VPC Quotas](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html) in the _Amazon VPC User Guide_ (see the **Security Groups** table). +VPC security group IDs, of the form `sg-xxxxxxxx`. These must be for the same VPC as the subnet specified. The maximum number of security groups depends on account quota. For more information, see [Amazon VPC Quotas](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html) in the _Amazon VPC User Guide_ (see the **Security Groups** table). If you don't specify a security group, then Amazon EFS uses the default security group for the subnet's VPC. @@ -153 +147 @@ Required: No -The ID of the subnet to add the mount target in. For One Zone file systems, use the subnet that is associated with the file system's Availability Zone. +The ID of the subnet to add the mount target in. For One Zone file systems, use the subnet that is associated with the file system's Availability Zone. The subnet type must be the same type as the `IpAddressType`. @@ -173,0 +168 @@ Required: Yes + "Ipv6Address": "**_string_** ", @@ -220 +215 @@ Pattern: `^(arn:aws[-a-z]*:elasticfilesystem:[0-9a-z-:]+:file-system/fs-[0-9a-f] -Address at which the file system can be mounted by using the mount target. +The IPv4 address for the mount target. @@ -227,0 +223,9 @@ Pattern: `^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$` +**Ipv6Address ** + + +The IPv6 address for the mount target. + +Type: String + +Length Constraints: Minimum length of 3. Maximum length of 39. + @@ -289 +293 @@ Type: String -Returned if the Availability Zone that was specified for a mount target is different from the Availability Zone that was specified for One Zone storage. For more information, see [Regional and One Zone storage redundancy](https://docs.aws.amazon.com/efs/latest/ug/availability-durability.html). +Returned if the Availability Zone that was specified for the mount target is different from the file system's Availability Zone. For more information, see [Regional and One Zone storage redundancy](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs). @@ -324 +328 @@ HTTP Status Code: 500 -Returned if the request specified an `IpAddress` that is already in use in the subnet. +Returned if the request specified an IP address (`IpAddress` or `Ipv6Address`) that is already in use in the subnet. @@ -345 +349 @@ HTTP Status Code: 409 -Returned if `IpAddress` was not specified in the request and there are no free IP addresses in the subnet. +Returned no `IpAddress` or `Ipv6Address` was provided in the request and there are no free IP addresses in the specified subnet. @@ -379 +383 @@ HTTP Status Code: 400 -### Add a mount target to a file system +### Create a mount target at an available IPv4 address on a subnet @@ -381 +385 @@ HTTP Status Code: 400 -The following request creates a mount target for a file system. The request specifies values for only the required `FileSystemId` and `SubnetId` parameters. The request does not provide the optional `IpAddress` and `SecurityGroups` parameters. For `IpAddress`, the operation uses one of the available IP addresses in the specified subnet. And, the operation uses the default security group associated with the VPC for the `SecurityGroups`. +The following request specifies only the file system and subnet for the mount target. The target is created at an available IPv4 address on the specified subnet, with the default security group associated with the VPC. @@ -403,0 +408 @@ The following request creates a mount target for a file system. The request spec + "OwnerId": "231243201240", @@ -405 +409,0 @@ The following request creates a mount target for a file system. The request spec - "NetworkInterfaceId": "eni-01234567", @@ -407 +410,0 @@ The following request creates a mount target for a file system. The request spec - "LifeCycleState": "available", @@ -409 +412 @@ The following request creates a mount target for a file system. The request spec - "OwnerId": "231243201240", + "LifeCycleState": "available", @@ -410,0 +414,4 @@ The following request creates a mount target for a file system. The request spec + "NetworkInterfaceId":"eni-1bcb7772" + "AvailabilityZoneId": "eus1-az2", + "AvailabilityZoneName": "eu-south-1b", + "VpcId": "vpc-08d45b31fa009a15e" @@ -412,0 +420 @@ The following request creates a mount target for a file system. The request spec +### Create a mount target at a specific IPv4 address @@ -414,3 +422 @@ The following request creates a mount target for a file system. The request spec -### Add a mount target to a file system - -The following request specifies all the request parameters to create a mount target. +The following request specifies the file system, subnet, security group, and IPv4 address to use for the mount target. @@ -452,0 +459,133 @@ The following request specifies all the request parameters to create a mount tar + "AvailabilityZoneId": "eus1-az2", + "AvailabilityZoneName": "eu-south-1b", + "VpcId": "vpc-08d45b31fa009a15e" + } + +### Create a mount target at a specific IPv6 address + +The following request specifies the file system, subnet, security group, and IPv6 address to use for the mount target. + +#### Sample Request + + + POST /2015-02-01/mount-targets HTTP/1.1 + Host: elasticfilesystem.us-west-2.amazonaws.com + x-amz-date: 20140620T221118Z + Authorization: <...> + Content-Type: application/json + Content-Length: 160 + + { + "FileSystemId":"fs-01234567", + "SubnetId":"subnet-01234567", + "Ipv6Address":"2001:0db8:85a3:0000:0000:8a2e:0370:7334", + "IpAddressType": "IPV6_ONLY", + "SecurityGroups":[ + "sg-01234567" + ] + } + +#### Sample Response + + + HTTP/1.1 200 OK + x-amzn-RequestId: 01234567-89ab-cdef-0123-456789abcdef + Content-Type: application/json + Content-Length: 252 + + { + "OwnerId":"251839141158", + "MountTargetId":"fsmt-9a13661e", + "FileSystemId":"fs-01234567", + "SubnetId":"subnet-fd04ff94", + "LifeCycleState":"available", + "Ipv6Address":"2001:0db8:85a3:0000:0000:8a2e:0370:7334", + "NetworkInterfaceId":"eni-1bcb7772" + "AvailabilityZoneId": "eus1-az2",