Library to compose and run AWS cli commands.
my @args = _aws_tag_specifications('vpc', { openqa_var_job_id => '123', openqa_created_date => '2026-01-01T00:00:00' });Private function. Convert a hashref of tags into a --tag-specifications argument pair for EC2 create commands. The resource_type is mandatory: "When you specify a tag, you must specify the resource type to tag, otherwise the request will fail." (AWS CLI reference). It must match the primary resource created by the command (e.g. 'vpc' for create-vpc). Keys are sorted for deterministic output. Return an empty list if the hashref is empty or undef.
Croak if any tag violates AWS tag restrictions: - Empty key - Undefined value - Key longer than 128 characters - Value longer than 256 characters - Key starting with the reserved prefix aws: - More than 50 tags
Croak also if a key or value contains characters outside the set [A-Za-z0-9+\-=_:.\/@]. This set is stricter than the AWS limits, because AWS also accepts spaces and Unicode letters. The tag list is inside double quotes in a shell command and uses the AWS CLI shorthand syntax. Characters such as $, backtick, space, ,, { or } can break the command or cause shell expansion. Do not add them to the set.
my $vpc_id = aws_vpc_create(
region => 'us-west',
cidr => '1.2.3/18',
tags => { openqa_var_job_id => '123' });Create a new AWS VPC with a specified CIDR block. If tags is given, those tags are applied to the VPC. Returns the VPC ID.
my $vpc_id = aws_vpc_get_id(
region => 'us-west',
job_id => 'abc123456');Retrieve the VPC ID associated with a specific OpenQA job Returns the VPC ID
my $ret = aws_vpc_delete(
region => 'us-west',
vpc_id => 'vpc-456');Delete the VPC, do not assert but return the exit code of the command.
my $sg_id = aws_security_group_create(
region => 'uswest',
group_name => 'something',
description => 'be or not to be',
vpc_id => 'vpc123456',
tags => { openqa_var_job_id => '123' });Create an AWS security group within a VPC. If tags is given, those tags are applied to the security group. Returns the security group ID.
my $ret = aws_security_group_delete(
region => 'uswest',
group_name => 'something',
description => 'be or not to be',
vpc_id => 'vpc123456',
job_is => '7890');Delete the security group, do not assert but return the exit code of the command.
my $sg_id = aws_security_group_get_id(region => 'europe', job_id => '12345');Retrieve the security group ID associated with a specific OpenQA job Returns the security group ID
aws_security_group_authorize_ingress(
sg_id => ,
protocol => ,
port =>,
cidr =>,
region => );Add an ingress rule to a security group allowing traffic from a specific CIDR block
my $subnet_id = aws_subnet_create(
region => 'us-west-1',
cidr => '10.0.1.0/24',
vpc_id => 'vpc-12345',
tags => { openqa_var_job_id => '123' }
);Create a subnet within a VPC with a specified CIDR block. If tags is given, those tags are applied to the subnet. Returns the subnet ID.
my @subnet_ids = aws_subnet_get_ids(
region => 'us-west-1',
job_id => '67890'
);Retrieve the list of subnet IDs associated with a specific OpenQA job Returns the list of subnet IDs
my $ret = aws_subnet_delete(
region => 'us-west-1',
job_id => '67890'
);Delete the subnets associated with the job, do not assert but return the exit code of the command.
my $igw_id = aws_internet_gateway_create
region => 'us-west-1',
tags => { openqa_var_job_id => '123' }
);Create an internet gateway. If tags is given, those tags are applied to the internet gateway. Returns the internet gateway ID.
my $igw_id = aws_internet_gateway_get_id(
region => 'us-west-1',
job_id => '67890'
);Retrieve the internet gateway ID associated with a specific OpenQA job Returns the internet gateway ID
aws_internet_gateway_attach(
vpc_id => 'vpc-12345',
igw_id => 'igw-abcde',
region => 'us-west-1'
);Attach an internet gateway to a VPC
my $ret = aws_internet_gateway_delete(
job_id => '6789',
vpc_id => 'vpc-12345',
region => 'us-west-1'
);Delete the internet gateway, do not assert but return the exit code of the command.
my $route_table_id = aws_route_table_create(
region => 'us-west-1',
vpc_id => 'vpc-12345'
);Create a route table within a VPC Returns the route table ID
aws_route_table_associate(
subnet_id => 'subnet-12345',
route_table_id => 'rtb-abcde',
region => 'us-west-1'
);Associate a route table with a subnet
my $ret = aws_route_table_delete(
vpc_id => 'subnet-12345',
region => 'us-west-1'
);Delete the route table(s), do not assert but return the first non-zero exit code of the commands, or 0 on success.
aws_route_create(
route_table_id => 'rtb-12345',
destination_cidr_block => '0.0.0.0/0',
igw_id => 'igw-abcde',
region => 'us-west-1'
);Create a route in a route table pointing to an internet gateway
my $instance_id = aws_vm_create(
instance_type => 't2.micro',
image_name => 'sles-15-sp3',
subnet_id => 'subnet-12345',
sg_id => 'sg-abcde',
ssh_key => 'my-key',
region => 'us-west-1',
tags => { openqa_var_job_id => '123' }
);Launch an EC2 instance with specified configuration. If tags is given, those tags are applied to the instance. Returns the instance ID.
my $data = _aws_ec2_describe_instances(
region => 'us-west-1',
filters => "'Name=instance-id,Values=i-12345'",
query => 'Reservations[0].Instances[0].State.Name');Internal function. Run aws ec2 describe-instances with JSON output. The timeout command stops aws before the script_output timeout. The function uses proceed_on_failure. Return the decoded JSON data structure. Return undef if the output is empty. Die if the output is not valid JSON.
--filters, already quoted for the shellmy @instance_ids = aws_vm_get_id(
region => 'us-west-1',
job_id => '67890'
);Retrieve the IDs of the EC2 instances associated with a specific OpenQA job. Terminated and shutting-down instances are ignored. Return a list of instance IDs. The list is empty if no instance is found or if the aws command fails. The caller must check how many elements the list has.
my $diag = aws_vm_get_diagnostics(
region => 'us-west-2',
instance_id => 'i-09dadefca25944818'
);Return a hash reference with diagnostic data about the instance: id, state, state_transition, state_reason, public_ip, private_ip, launch_time. Return undef if the instance is not found or if the aws command fails. Never dies at runtime.
my $out = aws_vm_describe_status(
region => 'us-west-2',
instance_id => 'i-09dadefca25944818'
);
Return the output of describe-instance-status: instance state and
system/instance status checks, also for not running instances.
Never dies: the aws command is killed by C<timeout> before the
script_output timeout, and a failure or a kill returns the command
output (proceed_on_failure).die 'VM not running' if aws_vm_wait_status_ok(
region => 'us-west-1',
instance_id => 'i-12345'
);Wait for an EC2 instance to reach the 'running' state. A failed aws command counts as "not running yet". Return 0 if the instance reaches 'running' in time. Die with the last known state if it does not.
my $ip = aws_pubip_get(
region => 'us-west-1',
instance_id => 'i-12345'
);Retrieve the public IP address of an EC2 instance. Return the public IP address, or undef if the instance has no public IP, is not found, or if the aws command fails.
my $ret = aws_vm_terminate(
region => 'us-west-1',
instance_id => 'i-12345'
);Terminate an EC2 instance and wait for it to be terminated, do not assert but return the exit code of the command.
aws_ssh_key_pair_import(
ssh_key => 'my-key',
pub_key_path => '/path/to/key.pub'
);Import an SSH public key pair into AWS EC2 for instance authentication
my $attach_id = aws_tgw_vpc_attachment_get_id(region => 'us-west-1', job_id => 'job-123');Retrieve the TGW attachment ID associated with a specific OpenQA job. Returns the TGW attachment ID as a string. Only the first element found is returned.
my $res = aws_filter_query(cmd => 'describe-instances', filter => 'Name=instance-id,Values=i-123', query => 'Reservations[*].Instances[*].InstanceId');Generic function to compose a aws cli command with filter and query. Returns the script output.
my $tgw_id = aws_tgw_get_id(mirror_tag => 'my-project');Return the Transit Gateway ID associated with a specific Project tag.
my @subnets = aws_vpc_get_subnets(vpc_id => 'vpc-123', region => 'us-east-1');Return a list of subnets for a VPC, one per Availability Zone.
my $rt_ids = aws_vpc_get_routing_tables(vpc_id => 'vpc-123', region => 'us-east-1');Get routing table IDs for a VPC that have external connections (non-local).
my $res = aws_tgw_attachment_get(name => 'my-attachment');Get a description of one or more transit-gateway-attachments. Returns an array reference of hash references (list of dicts). return value = [ {State => 'pending'} ...]
aws_tgw_attachment_create(
transit_gateway_id => 'tgw-123',
vpc_id => 'vpc-456',
subnet_id_list => ['subnet-1'],
name => 'my-attach'
);Create a Transit Gateway VPC attachment and wait until it is available. Returns true if the attachment becomes available within the timeout, false otherwise.
aws_tgw_attachment_delete(id => 'tgwa-123');Delete a Transit Gateway VPC attachment and wait until it is deleted. Returns true if the attachment is successfully deleted (or if wait is set to 0), false if it times out while waiting for the deleted state.
aws_route_create_tgw(rtable_id => 'rtb-1', target_ip_net => '10.0.0.0/8', trans_gw_id => 'tgw-1');Add a route to a Transit Gateway in a routing table.