# ali_instance_info – Gather information on instances of Alibaba Cloud ECS

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- This module fetches data from the Open API in Alicloud. The module must be called from within the ECS instance itself.
- This module was called `ali_instance_facts` before Ansible 2.9. The usage did not change.

Aliases: ali_instance_facts

## Requirements

The below requirements are needed on the host that executes this module.

- footmark >= 1.1.16
- python >= 2.6

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
alicloud_access_key string |  | Aliyun Cloud access key. If not set then the value of environment variable `ALICLOUD_ACCESS_KEY`, `ALICLOUD_ACCESS_KEY_ID` will be used instead. aliases: access_key_id, access_key
alicloud_region string |  | The Aliyun Cloud region to use. If not specified then the value of environment variable `ALICLOUD_REGION`, `ALICLOUD_REGION_ID` will be used instead. aliases: region, region_id
alicloud_secret_key string |  | Aliyun Cloud secret key. If not set then the value of environment variable `ALICLOUD_SECRET_KEY`, `ALICLOUD_SECRET_ACCESS_KEY` will be used instead. aliases: secret_access_key, secret_key
alicloud_security_token string |  | The Aliyun Cloud security token. If not specified then the value of environment variable `ALICLOUD_SECURITY_TOKEN` will be used instead. aliases: security_token
availability_zone - |  | Aliyun availability zone ID in which to launch the instance aliases: alicloud_zone
instance_ids - |  | A list of ECS instance ids. aliases: ids
instance_names - |  | A list of ECS instance names. aliases: names
instance_tags - |  | A hash/dictionaries of instance tags. `{"key":"value"}` aliases: tags

## Notes

Note

- If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence `ALICLOUD_ACCESS_KEY` or `ALICLOUD_ACCESS_KEY_ID`, `ALICLOUD_SECRET_KEY` or `ALICLOUD_SECRET_ACCESS_KEY`, `ALICLOUD_REGION` or `ALICLOUD_REGION_ID`, `ALICLOUD_SECURITY_TOKEN`
- `ALICLOUD_REGION` or `ALICLOUD_REGION_ID` can be typically be used to specify the ALICLOUD region, when required, but this can also be configured in the footmark config file

## Examples

    # Fetch instances details according to setting different filters
    - name: fetch instances details example
      hosts: localhost
      vars:
        alicloud_access_key: <your-alicloud-access-key>
        alicloud_secret_key: <your-alicloud-secret-key>
        alicloud_region: cn-beijing
        availability_zone: cn-beijing-a

      tasks:
        - name: Find all instances in the specified region
          ali_instance_info:
            alicloud_access_key: '{{ alicloud_access_key }}'
            alicloud_secret_key: '{{ alicloud_secret_key }}'
            alicloud_region: '{{ alicloud_region }}'
          register: all_instances

        - name: Find all instances based on the specified ids
          ali_instance_info:
            alicloud_access_key: '{{ alicloud_access_key }}'
            alicloud_secret_key: '{{ alicloud_secret_key }}'
            alicloud_region: '{{ alicloud_region }}'
            instance_ids:
              - "i-35b333d9"
              - "i-ddav43kd"
          register: instances_by_ids

        - name: Find all instances based on the specified names/name-prefixes
          ali_instance_info:
            alicloud_access_key: '{{ alicloud_access_key }}'
            alicloud_secret_key: '{{ alicloud_secret_key }}'
            alicloud_region: '{{ alicloud_region }}'
            instance_names:
              - "ecs_instance-1"
              - "ecs_instance_2"
          register: instances_by_ids

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
ids list | always | List of ECS instance IDs Sample: ['i-12345er', 'i-3245fs']
instances complex | always | List of ECS instances
| availability_zone string | always | The availability zone of the instance is in. Sample: cn-beijing-a
| block_device_mappings complex | always | Any block device mapping entries for the instance.
|  | attach_time string | always | The time stamp when the attachment initiated. Sample: 2018-06-25T04:08:26Z
|  | delete_on_termination boolean | always | Indicates whether the volume is deleted on instance termination. Sample: True
|  | device_name string | always | The device name exposed to the instance (for example, /dev/xvda). Sample: /dev/xvda
|  | status string | always | The attachment state. Sample: in_use
|  | volume_id string | always | The ID of the cloud disk. Sample: d-2zei53pjsi117y6gf9t6
| cpu integer | always | The CPU core count of the instance. Sample: 4
| creation_time string | always | The time the instance was created. Sample: 2018-06-25T04:08Z
| description string | always | The instance description. Sample: my ansible instance
| eip complex | always | The attribution of EIP associated with the instance.
|  | allocation_id string | always | The ID of the EIP. Sample: eip-12345
|  | internet_charge_type string | always | The internet charge type of the EIP. Sample: paybybandwidth
|  | ip_address string | always | EIP address. Sample: 42.10.2.2
| expired_time string | always | The time the instance will expire. Sample: 2099-12-31T15:59Z
| gpu complex | always | The attribution of instance GPU.
|  | amount integer | always | The count of the GPU.
|  | spec string | always | The specification of the GPU.
| host_name string | always | The host name of the instance. Sample: iZ2zewaoZ
| id string | always | Alias of instance_id. Sample: i-abc12345
| image_id string | always | The ID of the image used to launch the instance. Sample: m-0011223344
| inner_ip_address string | always | The inner IPv4 address of the classic instance. Sample: 10.0.0.2
| instance_charge_type string | always | The instance charge type. Sample: PostPaid
| instance_id string | always | ECS instance resource ID. Sample: i-abc12345
| instance_name string | always | The name of the instance. Sample: my-ecs
| instance_type string | always | The instance type of the running instance. Sample: ecs.sn1ne.xlarge
| internet_charge_type string | always | The billing method of the network bandwidth. Sample: PayByBandwidth
| internet_max_bandwidth_in integer | always | Maximum incoming bandwidth from the internet network. Sample: 200
| internet_max_bandwidth_out integer | always | Maximum incoming bandwidth from the internet network. Sample: 20
| io_optimized boolean | always | Indicates whether the instance is optimized for EBS I/O.
| memory integer | always | Memory size of the instance. Sample: 8192
| network_interfaces complex | always | One or more network interfaces for the instance.
|  | mac_address string | always | The MAC address. Sample: 00:11:22:33:44:55
|  | network_interface_id string | always | The ID of the network interface. Sample: eni-01234567
|  | primary_ip_address string | always | The primary IPv4 address of the network interface within the vswitch. Sample: 10.0.0.1
| osname string | always | The operation system name of the instance owned. Sample: CentOS
| ostype string | always | The operation system type of the instance owned. Sample: linux
| private_ip_address string | always | The IPv4 address of the network interface within the subnet. Sample: 10.0.0.1
| public_ip_address string | always | The public IPv4 address assigned to the instance Sample: 43.0.0.1
| resource_group_id string | always | The id of the resource group to which the instance belongs. Sample: my-ecs-group
| security_groups list of complex | always | One or more security groups for the instance.
|  | group_id string | always | The ID of the security group. Sample: sg-0123456
|  | group_name string | always | The name of the security group. Sample: my-security-group
| status string | always | The current status of the instance. Sample: running
| tags dictionary | always | Any tags assigned to the instance.
| vpc_id dictionary | always | The ID of the VPC the instance is in. Sample: vpc-0011223344
| vswitch_id string | always | The ID of the vswitch in which the instance is running. Sample: vsw-dew00abcdef

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- He Guimin (@xiaozhu36)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.