...
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Introduction
This Universal Task allows customers to create an EC2 instance with parameters, either in task form, or by simply creating an EC2 instance from the existing AWS launch template. This task also offers the option to additionally install a Linux/UNIX Universal Agent in the newly provisioned EC2 Instance.
Overview
The task interacts with the AWS platform via a Python boto3 module.
All AWS credentials remain encrypted.
Customers can also install/configure a Linux Universal Agent for each EC2 instance, enabling the Universal Controller to instantly communicate with the newly created instance. (NOTE: only Linux Universal Agent is supported at the moment.)
This task also lets customers create multiple EC2 instances with the same configuration. New instances can also be tagged.
It allows customers to create a new keypair or use an existing one for the new EC2 instance.
This task also enables options for additional EBS volume and encryption, as well as detailed monitoring.
AWS EC2 Task High-Level Overview
Overview
AWS Lambda is a serverless compute service that runs your code in response to events and automatically manages the underlying compute resources for you. You can use AWS Lambda to extend other AWS services with custom logic, or create your own back-end services that operate at AWS scale, performance, and security.
This Universal Extension provides the capability to execute a AWS Lambda function and return the result of that execution.
Version Information
Template Name | Extension Name | Extension Version |
---|---|---|
AWS Lambda | ue-aws-lambda | 1.2.0 |
Refer to Changelog for version history information.
Software Requirements
This integration requires an a Universal Agent and a Python runtime to execute the Universal Task against AWS EC2 Instance.
Software Requirements for /wiki/spaces/UC71x/pages/5178050 and /wiki/spaces/UC71x/pages/5180675 Universal Template and Universal Task
Requires Python
...
3.7
...
(The Universal Agent bundled Python distribution) or 3.11.
...
Python modules required:
requests
Boto3
Software Requirements for Universal Agent
Both Windows and Linux agents are supported:
- Universal Agent for Windows x64 Version
...
- >= 7.
...
- 2.0.0
...
- .
- Universal Agent for Linux
...
- Version >= 7.2.0.0
...
- .
Software Requirements for Universal Controller
- Universal Controller Version
...
- 7.
...
- 2.0.0 and later.
Software Requirements for the Application to be Scheduled
The Server Running the Universal Agent needs to have Python 2.7.x or 3.6.x installed
AWS IAM Credentials -Access Key, Secret Access key and Region with EC2 set of permissions
This universal task for the AWS EC2-start-stop-terminate has been tested with the agent bundled with python 3.6 and boto3 module
Technical Considerations
Consider using this universal task either with universal agent bundled with python(uapy) and also having boto3 module within this environment or a python environment (py) in a host where universal agent is installed with boto3 module in it.
AWS IAM credentials (Access Key, Secret Access key and Region) should be with the Appropriate access for handling AWS EC2 instances.
With the current version of this Universal Task, Universal Agent can be installed only in Linux EC2 Instance.
AWS Create EC2 Instance (with Universal Agent) Key Features
...
Feature
...
Description
...
Create New EC2 Instance
...
Creates a EC2 Instance based on the parameters that are provided in the form
...
Launch EC2 from template
...
Create a EC2 Instance based on a template in AWS
Import AWS Create EC2 Instance (with Universal Agent) Downloadable Universal Template
...
Network and Connectivity Requirements
Extension's Universal Agent host should be able to reach AWS Lambda REST endpoints.
Key Features
This Universal Extension provides the following key features:
- Trigger Lambda function Synchronously or Asynchronously.
- Support authorization via IAM Role-Based Access Control (RBAC) strategy.
- Support Proxy communication via HTTP/HTTPS protocol.
Import Universal Template
To use the Universal Template, you first must perform the following steps:.
This Universal Task requires
...
the Resolvable Credentials feature. Check that the
...
Resolvable Credentials Permitted system property has been set to true.
...
To import the Universal Template
...
In the Universal Controller UI, select Configuration > Universal Templates to display the current list of /wiki/spaces/UC71x/pages/5178054.
...
Right-click any column header on the list to display an Action menu.
...
Select Import from the menu, enter the directory containing the Universal Template file(s) that you want to import, and click OK.
into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Configure
...
Universal
...
Task
For the new Universal Task type AWS Lambda, create a new task, and enter the task-specific details that were created in the Universal Template.
Field Descriptions for AWS Create EC2 Instance (with Universal Agent) Universal Task
...
Field
...
Description
...
AWS-DEFAULT-REGION
...
AWS Region kept as credential
...
AWS-SECRET-ACCESS-KEY
...
AWS Secret Key
...
AWS-ACCESS-KEY-ID
...
AWS Access Key
...
Launch Instance Option
...
Select either launch from template or create a brand new ec2 instance with the parameter supplied in the form
...
LaunchTemplateName
...
Mandatory if launch_instance_option=” Launch from template”
...
AWS_IMAGE_ID
...
Provide the AWS machine ID ,Mandatory if launch_instance_option=” new_instance”
...
Keypair option
...
PEM file creation choice , Select either existing Key pair or New Key pair
...
EC2-KEYPAIR-Path & Name
...
Provide Keypair file name and the path (Do not give the extension) for new and for existing keypair just the name
...
EC2 Instance Type
...
provide ec2-instance type like t2. Micro , if Launch from template = “Create New Instance”
...
Minimum Count
...
Minimum Count of instance that need to be created, if Launch from template = “Create New Instance”
...
Max Count
...
Max count of instance that needs to be created, if Launch from template = “Create New Instance”
...
associate_public_ip
...
If a public IP needs to be created when a instance is created
...
SubnetId
...
Provide subnetID where the instance to be associated within AWS
...
Availability Zone
...
Provide Availability Zone where the instance to be associated within AWS
...
Security Group ID
...
provide security group ids, if multiple ID's then separate by comma
...
Instance Tag name
...
EC2 Instance Tag Name
...
iam_instance_profile_name
...
If applicable provide the IAM Instance Profile Name
...
device_name
...
Provide the device name; for example, /dev/sda1
...
ebs_volume_size
...
Provide EBS Volume size
...
EBS Vol. Type
...
Select either standard or io1 or gp2 or sc1 or st1
...
EBS Vol. Encyption
...
Check if encryption needs needed
...
EC2 Monitoring
...
Check this box if detailed monitoring required
...
Install Universal Agent
...
Check this box if you would need to install universal agent with this new EC2 instance created
...
Agent Download URL
...
Provide the path to download the agent URL, if install universal agent option is selected
...
Universal Agent Install OS
...
select the OS where universal agent needs to be installed
...
Agent OMS IP
...
Provide the OMS server IP for the universal agent to be connected after installation , if install universal agent option is selected
...
Use Public IP for SSH
...
Select if you would need to use the public or provide IP for SSH
...
os_user_id
...
Provide the OS user ID that will be used to make SSH connection
Examples for AWS Create EC2 Instance (with Universal Agent) Universal Tasks
New EC2 Instance Creation
Launch Instance with Launch Template
Input Fields
The input fields for this Universal Extension are described below.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | Trigger Lambda function | Choice | The action performed upon the task execution. Available action:
|
AWS Region Optional since version 1.1.0 | Optional | - | Text | Region for the Amazon Web Service. Find more information about the AWS Service endpoints and quotas here. When AWS Region is not populated as part of the task definition, during task execution the integration will look for credentials on the task execution environment. Refer to configuration options for more information. |
AWS Credentials Optional since version 1.1.0 | Optional | - | Credentials | The Credentials definition should be as follows.
When AWS Credentials are not populated as part of the task definition, during task execution the integration will look for AWS Credentials on the task execution environment. Refer to configuration options for more information. |
Role Based Access | Optional | False | Boolean | Special type of authorization is provided by Role Assumption where the client sends his own credentials and the role he wants to assume from another user. If allowed, the client receives temporary credentials with limited time access to some resources. |
Role ARN | Optional | - | Text | Role Arn: Amazon Role, which is applied for the connection. Role ARN format: Required when Role Based Access="True". |
Function Name | Required | - | Text | Name of the Lambda function, which will be triggered. For example, my-function (name-only) or my-function:v1 (with alias). |
Invocation Type | Required | Request Response | Choice | Type of execution for the function being triggered. Available choices are:
|
Log Type | Optional | None | Choice | Can be set to Tail to include the execution log in the response. Available choices are:
Visible only when Invocation Type="Request Response". |
Payload Source | Optional | None | Choice | Source of payload to be sent.
|
Payload Script | Optional | - | Script Field | Script field where the payload can be entered. The scripts must evaluate to a proper JSON format. Required when Payload Source = "Script". |
Client Context Source | Optional | None | Choice | Client context that's provided to Lambda function by the client application.
|
Client Context Script | Optional | - | Script | Script passing parameters using the ClientContext object. The scripts must evaluate to a proper JSON format. Required when Client Context Source= "Script". |
Use Proxy | Optional | False | Boolean | Flag to indicate whether Proxy shall be used in the communication with AWS. |
Proxy Type | Optional | HTTP | Choice | Type of proxy connection to be used. Available options are the following.
Visible only when Use Proxy = "True". |
Proxy | Optional | - | Text | Comma separated list of Proxy servers. Valid formats are the following. Required when Use Proxy is checked. |
Proxy CA Bundle File | Optional | - | Text | The path to a custom certificate bundle to use when establishing SSL/TLS connections with proxy. Used when Proxy Type is configured for "HTTPS" or "HTTPS With Credentials". |
Proxy Credentials | Optional | - | Credentials | Credentials to be used for the proxy communication. The credential definition should be as follows.
Required when "Proxy Type" is configured for "HTTPS With Credentials". |
Qualifier | Optional | - | Text | Version or alias to invoke a published version of the function. Example for version 1 Qualifier = "1". If empty, default value is the latest version. |
Wait For Completion Timeout Introduced in version 1.1.1 | Required | 60 | Integer | The time in seconds that the task will wait for a server response until it throws a timeout exception. This is linked with the read_timeout config value that is passed to the AWS client. |
Endpoint URL Introduced in version 1.2.0 | Optional | - | Text | The URL of the custom endpoint to use. The URL must contain a scheme which is either HTTP or HTTPS. |
Task Examples
Trigger Lambda Synchronously with Log
Triggering a Lambda function Synchronously with Log Type equals "Tail".
Synchronicity is set by Invocation Type equals "Request_Response".
Trigger Lambda Asynchronously with Role Based Access and HTTPS Proxy
Triggering Lambda function Asynchronously with:
- Role Based Access
- HTTPS Proxy connection
- Payload Source
- Client Context Source
Trigger Lambda Synchronously with HTTPS with Credentials Proxy
Triggering a Lambda function Synchronously with "HTTPS with Credentials" Proxy connection.
Trigger Lambda Synchronously with Log
Triggering a Lambda function Synchronously with "Region" provided as environment variables and without AWS Credentials. Please refer to AWS Credentials input field for more information.
Task Output
Exit Codes
The exit codes for AWS Lambda Extension are described in the following table.
Exit Code | Status Classification Code | Status Classification Description | Status Description |
---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Successful Task execution |
0 | SUCCESS | Successful Execution, but could not decode AWS log message | DECODE_WARNING: AWS Lambda function invoked successfully, but log message could not be decoded |
1 | FAIL | Failed Execution | FAIL: < Error Description > |
2 | AUTHENTICATION_ERROR | Bad credentials | AUTHENTICATION_ERROR: Account cannot be authenticated. |
3 | AUTHORIZATION_ERROR | Insufficient Permissions | AUTHORIZATION_ERROR: Account is not authorized to perform the requested action. |
10 | CONNECTION_ERROR | Bad connection data or connection timed out | CONNECTION_ERROR: < Error Description > |
11 | CONNECTION_ERROR | Extension specific connection error | CONNECTION_ERROR: ProxyConnectionError: Failed to connect to proxy URL <url> |
20 | DATA_VALIDATION_ERROR | Input fields validation error | DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDOUT for more details. |
21 | READ_TIMEOUT_ERROR | Lambda function completion timeout error | READ_TIMEOUT_ERROR: Did not receive a server response within the allotted time frame (wait_for_completion_timeout). |
Extension Output
In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.
Attribute changed
is populated as follows.
- true in case the job is triggered successfully
- false otherwise
result
section includes the following attributes.
Attribute | Type | Description |
---|---|---|
status_code | integer | The HTTP status code is in the 200 range for a successful request. For the RequestResponse invocation type, this status code is 200. For the Event invocation type, this status code is 202. For the DryRun invocation type, the status code is 204. |
log_result | string | The last 4 KB of the execution log, which is base64 encoded. |
payload | string | The response from the function, or an error object. |
executed_version | string | The version of the function that was executed. When you invoke a function with an alias, this indicates which version the alias is resolved to. |
function_error | string | If present, indicates that an error occurred during function execution. Details about the error are included in the response payload. |
An example of the Extension Output for a successful triggering job is presented below.
Code Block | ||
---|---|---|
| ||
{
"exit_code": 0,
"status_description": "SUCCESS: AWS Lambda function invoked successfully",
"changed": true,
"invocation": {
"extension": "ue-aws-lambda",
"version": "1.2.0",
"fields": {
"action": "Trigger Lambda Function",
"credentials_user": "****",
"credentials_password": "****",
"region": "us-east-1",
"role_based_access": false,
"role_arn": null,
"function_name": "test-function",
"invocation_type": "Event",
"payload_source": null,
"payload_script": null,
"client_context_source": null,
"client_context_script": null,
"log_type": "None",
"qualifier": null,
"use_proxy": false,
"proxy_type": null,
"proxy": null,
"proxy_credentials_user": null,
"proxy_credentials_password": null,
"proxy_ca_bundle_file": null,
"wait_for_completion_timeout": 60,
"endpoint_url": null
}
},
"result": {
"status_code": 202,
"log_result": null,
"payload": null,
"executed_version": null,
"function_error": null
}
} |
STDOUT and STDERR
STDOUT and STDERR provide additional information to the User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.
Document References
This document references the following documents:
...
Name
...
.
Document Link | Description | |||
---|---|---|---|---|
Universal Templates | https://docs.stonebranch.com/confluence/display/UC71x/Universal+Templates | User documentation for creating, working with and understanding Universal Templates in the Universal Controller user interface. | Universal Tasks | https://docs.stonebranch.com/confluence/display/UC71x/Universal+and Integrations. |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. | |||
AWS Lambda | Documentation for AWS Lambda. | |||
IAM RBAC authorization model | User Documentation for Comparing ABAC to the traditional RBAC model. |
Changelog
ue-aws-lambda-1.2.0 (2024-01-04)
Enhancements
Added
: Provide the capability to specify a custom endpoint URL to call instead of the default one. (#33020)
ue-aws-lambda-1.1.2 (2023-09-01)
Fixes
Fixed
: Provide a fix on the decoding of AWS Log Message. (#34100)
ue-aws-lambda-1.1.1 (2023-02-24)
Fixes
Fixed
: Provide the capability to define the completion timeout of the lambda function and avoid lambda function re-execution if the completion timeout is exceeded. (#31671)
ue-aws-lambda-1.1.0 (2022-06-30)
Enhancements
Added
: Provide the capability to rely on AWS credentials set-up on the environment where the extension is running and therefore it is not mandatory to be passed on the task definition as input fields. The same applies to AWS Region. (#29115)
ue-aws-lambda-1.0.1 (2022-03-14)
Fixes
Fixed:
Change of template SysId. (#27744)