Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.

Overview

The AWS Command Line Interface (AWS CLI) is an open source tool that enables you to interact with AWS services using commands in your command-line shell. With minimal configuration, the AWS CLI enables you to start running commands that implement functionality equivalent to that provided by the browser-based AWS Management Console from the command prompt in your terminal program.

This integration provides an interface to call the AWS CLI and enables users to execute AWS CLI tasks in UAC.

Version Information

Template Name	Extension Name	Version	Status
AWS CLI	ue-aws-cli	1.0.0	Fixes and new Features are introduced.

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area	Details
Python Version	Requires Python of version 3.7 or 3.11. Tested with the Universal Agent bundled Python distribution.
Universal Agent	Both Windows and Linux agents are supported: Universal Agent for Windows x64 Version >= 7.4.0.0 Universal Agent for Linux Version >= 7.4.0.0
Universal Controller	Universal Controller Version >= 7.4.0.0
Network and Connectivity	There needs to be network connectivity between the Universal Agent host and AWS Services.
AWS CLI tool	This integration is tested against AWS CLI tool 2. AWS CLI needs to be installed manually on the host of Universal Agent. The Universal Agent process needs to have access to the AWS CLI

Key Features

Feature	Description
Manage AWS Services	Invoke AWS services via the AWS CLI tool. A single CLI execution is currently supported.

Supported Actions

Action: Execute Command

This action is used to execute a single AWS CLI command towards AWS. The authentication is done for the chosen profile that is configured in the configuration and credentials files.

The Credentials File is intended for storing just credential information for the configured profiles. The Config File is intended for storing non-sensitive configuration options for the configured profiles. Those input parameters are mapped directly to the Configuration and Credential files of AWS CLI and provide a way to pass those files from UAC as UAC Scripts, removing the need for having them pre-configured on the Agent Host. For more information on the syntax and definition of those files, users are encouraged to consult the official AWS CLI documentation.

AWS Environment variables can be passed through the Environment Variables task definition section. Note that AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE are set automatically in case Fields Credentials File and Config File fields are configured.

Configuration examples

Execute an AWS CLI command by passing Credentials and Config file as UAC Scripts	Execute an AWS CLI command by using the AWS configuration that exists on the Agent
Execute an AWS CLI command by passing Credentials and Config file as UAC Scripts. AWS Environment variables provide another way to specify configuration options and credentials. For the list of AWS CLI applicable environment variables, users are encouraged to consult the AWS CLI official documentation.	AWS Sample Credential File modeled as UAC Script. UAC Credentials can be used to store sensitive information and UAC Credential Functions can be used for this purpose. It is also possible not to use credential functions, however this is not suggested as the credentials appear as clear text (as above for the case of "aws_access_key" and "aws_secret_access_key".
AWS Sample Configuration File modeled as UAC Script

Output Type

Description

Example

EXTENSION

The extension output follows the standard Extension Output format, providing:

“exit_code“, “status“, “status_description“: General info regarding the task execution.
“invocation” > “fields”: The task configuration used for this task execution.
“result“ fields:
- “metadata.commands”:
  - “command”: The aws cli command line that is executed
  - “exit_code”: Is the aws cli command exit code
- aws_json_output: The AWS JSON result, in case the command is executed with enabled JSON output.

Extension output without AWS JSON Output

{
  "exit_code": 0,
  "status_description": "Task executed successfully.",
  "invocation": {
    "extension": "ue-aws-cli",
    "version": "1.0.0",
    "fields": {}
  },
  "result": {
    "metadata": {
      "commands": [
        {
          "command": "aws configure list-profiles",
          "exit_code": 0
        }
      ]
    }
  }
}

Extension output with AWS JSON Output

{
  "exit_code": 0,
  "status_description": "Task executed successfully.",
  "invocation": {
    "extension": "ue-aws-cli",
    "version": "1.0.0",
    "fields": {}
  },
  "result": {
    "metadata": {
      "commands": [
        {
          "command": "aws stepfunctions start-execution <some parameters>",
          "exit_code": 0
        }
      ],
      "aws_json_output": {
        "executionArn": "some data",
        "startDate": "2024-03-05T17:21:10.454000+02:00"
      }
    }
  }
}

STDOUT

The standard AWS CLI command STDOUT appears on the STDOUT of the Universal Task Instance when the output is not in JSON format.

Output In Case of "aws configure list" command

  Name                    Value             Type          Location
  ----                    -----             ----           --------
  profile                <not set>          None           None
  access_key     ****************CFE2       env
  secret_key     ****************kEBF       env
  region                us-east-1           config-file    /home/config

Input Fields

Field	Type	Description
Action	Choice	The action performed upon the task execution. Available options: Execute Command (Default)
Credentials File	Script	A UAC script that allows to set a Credentials File as expected by the AWS CLI
Config File	Script	A UAC script that allows to set Config File as expected by the AWS CLI
Command Line	Large Text	The full command line starting with “aws”. A single command is supported and needs to be in one line.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	“Task executed successfully.“	Exit code that Successful Execution.
1	Failure	““Execution Failed: <<Error Description>>”	This exit code is used in case of failure and in case no other failure exit code is applicable.
20	Failure	“Data Validation Error: <<Error Description>>“	Input fields validation error.

STDOUT and STDERR

STDOUT and STDERR provide additional information to the user. STDOUT includes the output of the executed command if it is not in JSON format.

Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.

Chnagelog

ue-aws-cli-1.0.0 (2024-04-11)

Initial release