Amazon Elastic Compute Cloud plugin

9 minute readExtensibilityDeveloper productivity

Amazon Elastic Compute Cloud (Amazon EC2) is a web service that provides resizable compute capacity in the cloud. It is designed to make web-scale computing easier for developers. EC2 allows users to rent virtual computers on which to run their computer applications.

It provides you with complete control of your computing resources and lets you run on the proven Amazon computing environment. Amazon EC2 reduces the time required to obtain and boot new server instances to minutes, allowing you to quickly scale capacity, both up and down, as your computing requirements change. You can create, launch, and terminate server instances as needed, paying by the hour for active servers. EC2 provides developers the tools to build failure resilient applications and isolate them from common failure scenarios.

Amazon EC2 presents a true virtual computing environment, allowing you to use web service interfaces to launch instances with a variety of operating systems, load them with your custom application environment, manage your network access permissions, and run your image using as many or few systems as you want.

  • For more information about Amazon EC2, go to the http://aws.amazon.com/ec2/.

  • You can view the documentation at http://aws.amazon.com/documentation/ec2/.

CloudBees CD/RO integration to EC2 implementations

This plugin uses the Amazon EC2 application programming interface (API) that lets developers choose where their applications physically run and that provides access to infrastructure resources. Using this secure API, your application is automatically scaled up and down as needed. This integration allows CloudBees CD/RO to manage EC2 resources.

The plugin interacts with EC2 data by using PERL to perform the following tasks:

  • Create configurations with connection information.

  • Query for virtual machine and configuration information.

  • Perform actions on instances.

  • Make API Requests.

  • Create CloudBees CD/RO resources.

The integration has two types of procedures to accomplish a specific task:

  • API procedures named API_xxx that directly wrap an EC2 API call

  • Higher-level procedures named EC2_xxx that combine many API calls

The procedure that you select determines which fields are available.

Plugin version 1.0.18.2023011467

Revised on January 14, 2023

Plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, complete the following steps:

  1. Navigate to DevOps Essentials  Plugin Management  Plugin configurations.

  2. Select Add plugin configuration to create a new configuration.

  3. In the New Configuration window, specify a Name for the configuration.

  4. Select the Project that the configuration belongs to.

  5. Optionally, add a Description for the configuration.

  6. Select the appropriate Plugin for the configuration.

  7. Configure the parameters per the descriptions below.

Configuration procedure parameters

Parameter Description

Configuration Name

Name of the created configuration

Description

Description for the configuration

Region

AWS Region to work with. Refer to the list of available regions here.

Authorization Type

Choose the authorization type:

  • basic - Requires Access Key ID and Key Secret

  • sts - Requires Access Key ID, Secret and the Role ARN

Role ARN

The Amazon Resource Name (ARN) of the role to assume. For example, arn:aws:iam::372416831963:role/my-role.

AWS Credentials

Basic AWS credentials: Access Key ID and Secret.

Session Token

Session token to use with Access Key ID and the Secret.

Check Connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Debug level

This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed. If Trace is selected, all requests and responses are displayed.

Plugin procedures

API_AllocateIP

Allocate an Elastic IP

API_AllocateIP parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Results Location

Where to put the result. If not specified, the result is only printed.

API_AssociateIP

Associate an Elastic IP to an instance

API_AssociateIP parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instance ID

Required. The instance to be associated with an IP.

IP

Required. The Elastic IP public address (for example, 52.71.234.249R) to release.

API_AttachVolumes

Attach a list of volumes to a list of instances.

API_AttachVolumes parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Device

Required. How the device is exposed to the instance.

List of Instances

Required. The instances to which the volumes are attached.

List of Volumes

Required. The volumes that are attached to the instances.

API_CreateImage

Creates a copy of an EBS instance.

API_CreateImage parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instance

Required. The instance to duplicate.

New Image Name

Required. The new name for the created image.

New Image Description

The description for the new image.

No Reboot

Required (false by default). By default, this parameter is set to false, and Amazon EC2 attempts to cleanly shut down the instance before image creation and reboots the instance afterwards. When the parameter is set to true, Amazon EC2 does not shut down the instance before creating the image. When this option is used, file system integrity on the created image cannot be guaranteed.

Results Location

Required. Where to put the result. If not specified, the result is only printed.

Wait for Image?

If selected, the procedure waits for the image to become available.

API_CreateTags

Adds or overwrites one or more tags for the specified Amazon EC2 resource or resources.

API_CreateTags parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Resources

Required. A space-separated list of resource IDs.

Tags

Required. A comma-separated list of key-values (key ⇒ value, key2 ⇒ value2).

API_DescribeInstances

Describe one or more instances

API_DescribeInstances parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instances

A list of instances or reservations to list.

Results Location

Where to put the result. If not specified, the result is only printed and saved to the output parameter.

Output parameters

Parameter Description

instances

JSON representation of instances.

API_ReleaseIP

Release an Elastic IP address

API_ReleaseIP parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

IP

Required. The Elastic IP public address (for example, 52.71.234.249) to release.

API_RunInstances

This procedure provisions one or several EC2 instances and creates resources for them.

API_RunInstances parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

AMI

Required. The Amazon Image ID (AMI) of the image to deploy.

Availability Zone

The Availability Zone you want to launch the instance into.

Name

Name for the instance.

Instance Type

Required. The instance type. For more information, refer to Instance Types.

Subnet ID

For use with VPCs. The ID of the subnet to launch the instance(s) into.

Security Group

Key Name

The name of the keypair to use for the instance.

Initiated Shutdown Behaviour

Specify the instance behaviour when an OS-level shutdown is performed.Instance can be either terminated or shut down.

IAM Profile Name

If specified, a new instance is associated with given IAM profile.

Use Private IP?

If selected, the Private IP is used when creating the resource.

Private IP

The primary IP address. You must specify a value from the IP address range of the subnet. If no value is supplied then IP address from the IP address range of the subnet is selected. (For use with VPCs.)

Tenancy

Each instance that you launch into a VPC has a tenancy attribute. This attribute has the following values:

  • default - Your instance runs on shared hardware.

  • dedicated - Your instance runs on single-tenant hardware.

  • host - Your instance runs on a Dedicated Host, which is an isolated server with configurations that you can control.

User Data

Extra user data to pass into runInstance.

Number of Instances

The number of instances to start.

Resource Pool

If you would like to add CloudBees CD/RO resources for each instance created, enter the CloudBees CD/RO pool name for the new resource. If left blank, no resource is created.

Resource Port

If you specified a resource pool name in the Resource Pool field, this port is used when creating the resource. If you specified a resource pool name in the Resource Pool field and no value is specified here for the port, port 7800 is used by default.

Resource Workspace

If you specify a resource pool name in Resource Pool field, this is the workspace used when creating the resource.

Resource Zone Name

The created resource belongs to this specified zone. By default, zone default is used.

Ping Resource?

If selected, the resource is pinged after the creation.

Result Property Sheet

Property path to store results

API_StartInstance

Start instance

API_StartInstance parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instances IDs

Required. Instances IDs in a newline-separated list.

Wait for Instances?

If selected, the procedure polls the instances statuses and finishes when the instances are stopped.

Results Location

Where to put the result. If not specified, the result is only printed and saved to the output parameter.

Output parameters

Parameter Description

instances

JSON representation of the instances details.

API_StopInstance

Stops a single or multiple instances.

API_StopInstance parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instances IDs

Required. Instances IDs in a newline-separated list.

Wait for Instances?

If selected, the procedure polls the instances statuses and will finish when the instances are stopped.

API_TearDownResource

Terminates resources created with this plugin.

API_TearDownResource parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Resource Name

Required. Name of resource or resource pool to delete.

API_Terminate

Terminate an instances

API_Terminate parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instance IDs

Required. If this is an instance ID, the instance is terminated. If this is a reservation ID, all instances in the reservation are terminated. Multiple instance IDs are separated by a semicolon.

Resources

List of resources to be deleted.

Wait for Instances?

If selected, the procedure waits until the instances are terminated.

Execute API Request

This procedure executes a custom Query API request to the specified service that supports Query API (except S3).

Execute API Request parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Host

Host of the AWS Service to use, for example ec2.amazonaws.com. If a host is not provided, a host is derived from the service name.

Service Name

Required. Service name to use, for example ec2.

API Version

Required. API Version to use, for example 2016-11-15.

Action

Action to perform. For example, DescribeInstances. Refer to the list of actions in Operation List.

Headers

A set of headers in key=value pairs or JSON map.

Query

Query parameters in key=value pairs or JSON map.

Path

Path to use. Default is /.

Output parameters

Parameter Description

result

The returned response from the service in XML format.

Snap Attached Volume

This procedure creates a new snapshot from a volume attached to an instance. It only creates a snapshot from the first volume found.

Snap Attached Volume parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Instance

Required. Instance ID of a running EC2 instance.

Results Location

Required. Where to put the result. If not specified, the result is only printed.

Volume Id

Required. The volume ID to be snapped. Separate list of volume IDs with semicolons.

To work correctly, this plugin requires CloudBees CD/RO agents with version 10.1+ because of library upgrades. However, at least interface-wise, this plugin should be backward compatible with previous versions of the EC-EC2 plugin, which was deprecated. To migrate an existing automation to use this plugin, you can change the plugin name in the DSL of the existing declaration, for example:

resourceTemplate 'amazonEC2-ResourceTemplate', {
    cloudProviderParameter = [
        'config': 'ec2config',
        'count': '1',
        'group': 'PROVIDE SECURITY GROUP',
        'image': 'PROVIDE IMAGE NAME',
        'instanceInitiatedShutdownBehavior': '',
        'instanceType': 'PROVIDE INSTANCE TYPE',
        'keyname': 'PROVIDE KEY NAME',
        'privateIp': '',
        'propResult': '',
        'res_poolName': '',
        'res_port': '',
        'res_workspace': '',
        'resource_zone': 'default',
        'subnet_id': 'PROVIDE SUBNET ID',
        'use_private_ip': '0',
        'userData': '',
        'zone': 'PROVIDE AVAILABILITY ZONE',
    ]
    cloudProviderPluginKey = 'EC-EC2' // replace with 'EC-AWS-EC2'
    cloudProviderProcedure = 'API_RunInstances'
  // Custom properties

  property 'ec_cloud_plugin_parameter', {

    // Custom properties
    config = 'ec2config'
    count = '1'
    group = 'PROVIDE SECURITY GROUP'
    image = 'PROVIDE IMAGE NAME'
    instanceInitiatedShutdownBehavior = ''
    instanceType = 'PROVIDE INSTANCE TYPE'
    keyname = 'PROVIDE KEY NAME'
    privateIp = ''
    propResult = ''
    res_poolName = ''
    res_port = ''
    res_workspace = ''
    resource_zone = 'default'
    subnet_id = 'PROVIDE SUBNET ID'
    use_private_ip = '0'
    userData = ''

    property 'zone', value: 'PROVIDE AVAILABILITY ZONE', {
      expandable = '1'
      suppressValueTracking = '0'
    }
  }
}

Third-party dependencies

Module License

io.netty:netty-buffer:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-codec:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-codec-http:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-codec-http2:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-common:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-handler:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-resolver:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-transport:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-transport-classes-epoll:4.1.87.Final

Apache License, Version 2.0

io.netty:netty-transport-native-unix-common:4.1.87.Final

Apache License, Version 2.0

org.reactivestreams:reactive-streams:1.0.4

MIT-0

org.slf4j:slf4j-api:1.8.0-beta4

MIT License

software.amazon.awssdk:annotations:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:apache-client:2.17.276

Apache License, Version 2.0

software.amazon.awssdk:auth:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:aws-core:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:aws-query-protocol:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:ec2:2.17.276

Apache License, Version 2.0

software.amazon.awssdk:endpoints-spi:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:http-client-spi:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:json-utils:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:metrics-spi:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:netty-nio-client:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:profiles:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:protocol-core:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:regions:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:sdk-core:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:sts:2.17.276

Apache License, Version 2.0

software.amazon.awssdk:third-party-jackson-core:2.19.16

Apache License, Version 2.0

software.amazon.awssdk:utils:2.19.16

Apache License, Version 2.0

software.amazon.eventstream:eventstream:1.0.1

Apache License, Version 2.0

Release notes

EC-AWS-EC2 1.0.18

  • Upgraded third-party dependencies.

EC-AWS-EC2 1.0.17

  • Upgraded third-party dependencies.

  • Added support for the new plugin configurations.

EC-AWS-EC2 1.0.16

  • Fixed an issue where run instances always used a public IP for creating a resource.

EC-AWS-EC2 1.0.10

  • Upgraded netty-codec to 4.1.76. Final version.

EC-AWS-EC2 1.0.6

  • Improved documentation.

EC-AWS-EC2 1.0.5

  • Upgraded third-party dependencies.

EC-AWS-EC2 1.0.4

  • Upgraded third-party dependencies.

EC-AWS-EC2 1.0.3

  • Upgraded third-party dependencies.

EC-AWS-EC2 1.0.2

  • Upgraded third-party dependencies.

EC-AWS-EC2 1.0.1

  • Added a Known Issues section to the documentation.

EC-AWS-EC2 1.0.0

  • First release.