5.2.14 Create a virtual server
Function
This plugin can start instances from an AMI in an Amazon EC2 environment.
The required server is shown as follows:
- AWS control server (execution-target server)
This is a server where AWS Tools for Windows PowerShell (hereinafter referred to as "AWS Tools") is installed. This product can forward plugins to the server to be executed.
- Instance
This is a regular virtual server in an Amazon EC2 environment.
The scripts in this plugin execute the following AWS Tools commandlets:
(1) Starting an instance
- New-EC2Instance -ImageId AMI-ID (the value of the AWS.amiId property)
-InstanceType instance-type (the value of the AWS.instanceType property)
-AssociatePublicIp $false
-MinCount 1
-MaxCount 1
[-KeyName key-pair-name] (the value of the AWS.keyPairName property)
[-SecurityGroupId security-group-ID] (the value of the AWS.securityGroupId property)
[-SubnetId first-subnet-ID] (the value of the AWS.subnetId1 property)
[-PrivateIpAddress first-private-IP-address] (the value of the AWS.privateIpAddress1 property)
After executing the above commandlets, make sure that the status of the started instance is "running".
(2) Adding network interfaces to the started instance
This processing is performed only if a value is specified for the subnet ID for the second one (the AWS.subnetId2 property).
- New-EC2NetworkInterface -SubnetId second-subnet-ID] (the value of the AWS.subnetId2 property)
[-PrivateIpAddress second-private-IP-address] (the value of the AWS.privateIpAddress2 property)
[-Group security-group-ID] (the value of the AWS.securityGroupId property)
- Add-EC2NetworkInterface -InstanceId instance-ID-of-instance-started-by-New-EC2Instance-commandlet
- NetworkInterfaceId network-interface-ID-of-network-interface-created-by-New-EC2NetworkInterface-commandlet
- DeviceIndex 1
After executing the above commandlets, make sure that the status of the added network interface is "in-use".
For details about the AWS Tools commandlets, refer to "AWS Tools for Windows PowerShell Cmdlet Reference" in the AWS document.
Use situation
Use this plugin to start instances in an Amazon EC2 environment.
Prerequisites
For the most recent information about the prerequisite products on the execution-target server, supported OSs for the prerequisite products on the execution-target server, and prerequisite products on the execution-target system, see the Release Notes.
In addition, the following OS and products use abbreviations. For the abbreviations of OS and products, see the "Preface".
Prerequisite products on the execution-target server:
- AWS Tools for Windows PowerShell
- Microsoft .Net Framework 3.5 or later
Supported OSs for the prerequisite products on the execution-target server:
- Windows Server
Prerequisite products in the execution-target system:
None.
Conditions for using the prerequisite products in the execution-target system:
(1) Conditions for setting an Amazon EC2 environment
- The AMI used for starting instances must have been created.
Cautions
(1) Do not specify character strings that include a double quotation mark (") or a single quotation mark (') for the properties of this plugin.
(2) IP addresses in use or out of range cannot be used for the IP addresses below. If you make use of these, the task will abnormally end.
- Private IP address for the first one (the AWS.privateIpAddress1 property)
- Private IP address for the second one (the AWS.privateIpAddress2 property)
(3) For the security group ID (the AWS.securityGroupId property), specify only single-byte alphanumeric characters, hyphens (-), and commas (,). If you specify any other characters, the task will abnormally end.
(4) If this plugin abnormally ends with the return value of 1, the started instance will remain. If the plugin abnormally ends with the return value of 2, the created network interface will remain in addition to the started instance.
(5) For additional remarks, refer to "AWS Tools for Windows PowerShell Cmdlet Reference" in the AWS document.
Execution privilege
(1) The policy must be set to allow an IAM user to log in to AWS to perform the following actions:
- Starting instances and obtaining instance statuses
- Creating and connecting network interfaces, along with obtaining interface statuses
Version
02.00.00
Plug-in tags
Add VM,AWS
Plug-in name displayed in the task log
awsCreateVM
Return code
0: Normal
1: Error (error detected after starting the instance) Network interface creation error
2: Error (error detected after starting the instance) Network interface connection error
12: Error (mistake by user) Invalid property
23: Error (invalid environment) The environment requirements have not been met.
27: Error (Check with the task log regarding the error details.) Unidentified error
41: Error (error detected in the component) Property not entered (An error was detected in the component script.)
Property list
The following table lists the properties:
Property key |
Property name |
Description |
Default value |
I/O type |
Required |
---|---|---|---|---|---|
plugin.destinationHost |
Host name of the execution target server |
Specify the host name or IP address of the server on which this plugin will be executed. IPv6 addresses are not supported. |
-- |
Input |
R |
AWS.accessKeyId |
Access key ID |
Specify the access key ID for connecting to AWS. |
-- |
Input |
R |
AWS.secretAccessKey |
Secret access key |
Specify the secret access key for connecting to AWS. |
-- |
Input |
R |
AWS.region |
Region |
Specify an AWS region that is a connection destination. |
-- |
Input |
R |
AWS.amiId |
AMI ID |
Specify an AMI ID used for instance start. |
-- |
Input |
R |
AWS.instanceType |
Instance type |
Specify an instance type used for instance start. |
-- |
Input |
R |
AWS.keyPairName |
Key pair name |
Specify a key pair name used for the instance. If this property is omitted, no key pair name is set for the instance. |
-- |
Input |
O |
AWS.securityGroupId |
Security group ID |
Specify the ID of the security group to which the instance is assigned. If this value is omitted, the instance is used for a default security group. To specify multiple security groups, separate their IDs by using a comma. |
-- |
Input |
O |
AWS.subnetId1 |
Subnet ID 1 |
Specify the ID of the subnet that indicates the range of the first private IP address assigned to the instance. If this property is omitted, a default subnet is assigned. |
-- |
Input |
O |
AWS.privateIpAddress1 |
Private IP address 1 |
Specify the first private IP address assigned to the instance. IPv6 address is not supported. If this property is omitted, an IP address within the range determined by the subnet corresponding to the specified subnet ID 1 is automatically assigned. |
-- |
Input |
O |
AWS.subnetId2 |
Subnet ID 2 |
Specify the ID of the subnet that indicates the range of the second private IP address assigned to the instance. This property is required when the second IP address is set. If this property is omitted, the second IP address is not set. |
-- |
Input |
O |
AWS.privateIpAddress2 |
Private IP address 2 |
Specify the second private IP address assigned to the instance (IPv4 only). This property takes effect when subnet ID 2 is specified. By default, an IP address within the range determined by the specified subnet ID 2 is assigned to the instance. |
-- |
Input |
O |
AWS.checkInstanceEnabledCount |
Instance status (started) check count |
Specify the number of times to check whether the instance has started. The maximum waiting time is determined by this count and the instance status (started) check interval. This property is also used to check whether network interfaces have been added. |
-- |
Input |
R |
AWS.checkInstanceEnabledInterval |
Instance status (started) check interval |
Specifies an interval in seconds for checking the completion of starting an instance. This property is also used to check the completion of adding network interfaces. |
-- |
Input |
R |
AWS.instanceIdInheritance |
Instance ID (for passing on to subsequent steps) |
Stores the ID of the instance. This ID is used for passing on to subsequent steps. |
-- |
Output |
O |
AWS.instanceIdOutput |
Instance ID (for task output) |
Stores the ID of the instance. This ID is used for outputting a task. |
-- |
Output |
O |
AWS.instanceIPaddress |
Instance IP address |
Stores the instance IP address. If multiple IP addresses are set for the instance, the IP addresses are output in comma-separated format. |
-- |
Output |
O |
AWS.networkInterfaceId |
Network interface ID |
If subnet ID 2 is specified, the ID of the network interface added to the instance is stored. |
-- |
Output |
O |
common.returnValue |
Return value for the plugin |
The return value of this plugin stored. |
-- |
Output |
O |