본문 바로가기

리눅스

AWS 동적 인벤토리를 사용하여 AWS 인스턴스 목록을 가져오는 방법

반응형

AWS 동적 인벤토리를 사용하여 AWS 인스턴스 목록을 가져오는 방법

AWS 동적 인벤토리는 AWS 인스턴스 목록을 관리하는 데 사용되는 Ansible 기능입니다. 동적 인벤토리를 사용하면 Ansible이 AWS API를 호출하여 인스턴스 목록을 가져와 인벤토리로 가져올 수 있습니다. 이렇게 하면 인스턴스 목록이 항상 최신 상태로 유지되며, 인벤토리를 수동으로 관리할 필요가 없습니다.

ansible-doc --type inventory amazon.aws.aws_ec2
더보기
> AMAZON.AWS.AWS_EC2    (/root/.ansible/collections/ansible_collections/amazon/aws/plugins/inventory/aws_ec2.py)

        Get inventory hosts from Amazon Web Services EC2. The inventory file is a YAML configuration file and must end
        with `aws_ec2.{yml|yaml}'. Example: `my_inventory.aws_ec2.yml'.

OPTIONS (= is mandatory):

- access_key
        AWS access key ID.
        See the AWS documentation for more information about access tokens
        https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.
        The `aws_access_key' and `profile' options are mutually exclusive.
        The `aws_access_key_id' alias was added in release 5.1.0 for consistency with the AWS botocore SDK.
        The `ec2_access_key' alias has been deprecated and will be removed in a release after 2024-12-01.
        set_via:
          env:
          - name: AWS_ACCESS_KEY_ID
          - name: AWS_ACCESS_KEY
          - deprecated:
              alternatives: AWS_ACCESS_KEY_ID
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: EC2 in the name implied it was limited to EC2 resources.  However, it is
                used for all connections.
            name: EC2_ACCESS_KEY
        aliases: [aws_access_key_id, aws_access_key, ec2_access_key]
        default: null
        type: str

- allow_duplicated_hosts
        By default, the first name that matches an entry of the `hostnames' list is returned.
        Turn this flag on if you don't mind having duplicated entries in the inventory and you want to get all the
        hostnames that match.
        default: false
        type: bool
        added in: version 5.0.0 of amazon.aws


- assume_role_arn
        The ARN of the IAM role to assume to perform the lookup.
        You should still provide AWS credentials with enough privilege to perform the AssumeRole action.
        aliases: [iam_role_arn]
        default: null

- cache
        Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
        set_via:
          env:
          - name: ANSIBLE_INVENTORY_CACHE
          ini:
          - key: cache
            section: inventory
        default: false
        type: bool

- cache_connection
        Cache connection data or path, read cache plugin documentation for specifics.
        set_via:
          env:
          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
          - name: ANSIBLE_INVENTORY_CACHE_CONNECTION
          ini:
          - key: fact_caching_connection
            section: defaults
          - key: cache_connection
            section: inventory
        default: null
        type: str

- cache_plugin
        Cache plugin to use for the inventory's source data.
        set_via:
          env:
          - name: ANSIBLE_CACHE_PLUGIN
          - name: ANSIBLE_INVENTORY_CACHE_PLUGIN
          ini:
          - key: fact_caching
            section: defaults
          - key: cache_plugin
            section: inventory
        default: memory
        type: str

- cache_prefix
        Prefix to use for cache plugin files/tables
        set_via:
          env:
          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
          - name: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
          ini:
          - deprecated:
              alternatives: Use the 'defaults' section instead
              collection_name: ansible.builtin
              version: '2.16'
              why: Fixes typing error in INI section name
            key: fact_caching_prefix
            section: default
          - key: fact_caching_prefix
            section: defaults
          - key: cache_prefix
            section: inventory
        default: ansible_inventory_

- cache_timeout
        Cache duration in seconds
        set_via:
          env:
          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
          - name: ANSIBLE_INVENTORY_CACHE_TIMEOUT
          ini:
          - key: fact_caching_timeout
            section: defaults
          - key: cache_timeout
            section: inventory
        default: 3600
        type: int

- compose
        Create vars from jinja2 expressions.
        default: {}
        type: dict

- endpoint_url
        URL to connect to instead of the default AWS endpoints.  While this can be used to connection to other AWS-
        compatible services the amazon.aws and community.aws collections are only tested against AWS.
        The `endpoint' alias has been deprecated and will be removed in a release after 2024-12-01.
        set_via:
          env:
          - name: AWS_URL
          - deprecated:
              alternatives: AWS_URL
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: EC2 in the name implied it was limited to EC2 resources.  However, it is
                used for all connections.
            name: EC2_URL
        aliases: [aws_endpoint_url, endpoint]
        default: null
        type: str

- exclude_filters
        A list of filters. Any instances matching one of the filters are excluded from the result.
        The filters from `exclude_filters' take priority over the `include_filters' and `filters' keys
        Available filters are listed here http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-
        instances.html#options.
        Every entry in this list triggers a search query. As such, from a performance point of view, it's better to
        keep the list as short as possible.
        default: []
        elements: dict
        type: list
        added in: version 1.5.0 of amazon.aws


- filters
        A dictionary of filter value pairs.
        Available filters are listed here http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-
        instances.html#options.
        default: {}
        type: dict

- groups
        Add hosts to group based on Jinja2 conditionals.
        default: {}
        type: dict

- hostnames
        A list in order of precedence for hostname variables.
        The elements of the list can be a dict with the keys mentioned below or a string.
        Can be one of the options specified in http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-
        instances.html#options.
        If value provided does not exist in the above options, it will be used as a literal string.
        To use tags as hostnames use the syntax tag:Name=Value to use the hostname Name_Value, or tag:Name to use the
        value of the Name tag.
        default: []
        elements: raw
        type: list

        SUBOPTIONS:

        = name
            Name of the host.
            type: str

        - prefix
            Prefix to prepend to `name'. Same options as `name'.
            If `prefix' is specified, final hostname will be `prefix' +  `separator' + `name'.
            default: ''
            type: str

        - separator
            Value to separate `prefix' and `name' when `prefix' is specified.
            default: _
            type: str

- hostvars_prefix
        The prefix for host variables names coming from AWS.
        default: null
        type: str
        added in: version 3.1.0 of amazon.aws


- hostvars_suffix
        The suffix for host variables names coming from AWS.
        default: null
        type: str
        added in: version 3.1.0 of amazon.aws


- include_extra_api_calls
        Add two additional API calls for every instance to include 'persistent' and 'events' host variables.
        Spot instances may be persistent and instances may have associated events.
        The `include_extra_api_calls' option had been deprecated and will be removed in release 6.0.0.
        default: false
        type: bool

- include_filters
        A list of filters. Any instances matching at least one of the filters are included in the result.
        Available filters are listed here http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-
        instances.html#options.
        Every entry in this list triggers a search query. As such, from a performance point of view, it's better to
        keep the list as short as possible.
        default: []
        elements: dict
        type: list
        added in: version 1.5.0 of amazon.aws


- keyed_groups
        Add hosts to group based on the values of a variable.
        default: []
        elements: dict
        type: list

        SUBOPTIONS:

        - default_value
            The default value when the host variable's value is an empty string.
            This option is mutually exclusive with `trailing_separator'.
            default: null
            type: str
            added in: version 2.12 of ansible-core


        - key
            The key from input dictionary used to generate groups
            default: null
            type: str

        - parent_group
            parent group for keyed group
            default: null
            type: str

        - prefix
            A keyed group name will start with this prefix
            default: ''
            type: str

        - separator
            separator used to build the keyed group name
            default: _
            type: str

        - trailing_separator
            Set this option to `False' to omit the `separator' after the host variable when the value is an empty
            string.
            This option is mutually exclusive with `default_value'.
            default: true
            type: bool
            added in: version 2.12 of ansible-core


- leading_separator
        Use in conjunction with keyed_groups.
        By default, a keyed group that does not have a prefix or a separator provided will have a name that starts
        with an underscore.
        This is because the default prefix is "" and the default separator is "_".
        Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
        If the group name is derived from a mapping the separator is still used to concatenate the items.
        To not use a separator in the group name at all, set the separator for the keyed group to an empty string
        instead.
        default: true
        type: boolean
        added in: version 2.11 of ansible-core


- profile
        A named AWS profile to use for authentication.
        See the AWS documentation for more information about named profiles
        https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html.
        The `profile' option is mutually exclusive with the `aws_access_key', `aws_secret_key' and `security_token'
        options.
        The `boto_profile' alias has been deprecated and will be removed in a release after 2024-12-01.
        set_via:
          env:
          - name: AWS_PROFILE
          - name: AWS_DEFAULT_PROFILE
        aliases: [aws_profile, boto_profile]
        default: null
        type: str

- region
        The AWS region to use.
        See the Amazon AWS documentation for more information
        http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region.
        set_via:
          env:
          - name: AWS_REGION
          - deprecated:
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: EC2 in the name implied it was limited to EC2 resources, when it is used
                for all connections
            name: EC2_REGION
        aliases: [aws_region, ec2_region]
        default: null
        type: str

- regions
        A list of regions in which to describe EC2 instances.
        If empty (the default) default this will include all regions, except possibly restricted ones like us-gov-
        west-1 and cn-north-1.
        default: []
        elements: str
        type: list

- secret_key
        AWS secret access key.
        See the AWS documentation for more information about access tokens
        https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.
        The `secret_key' and `profile' options are mutually exclusive.
        The `aws_secret_access_key' alias was added in release 5.1.0 for consistency with the AWS botocore SDK.
        The `ec2_secret_key' alias has been deprecated and will be removed in a release after 2024-12-01.
        set_via:
          env:
          - name: AWS_SECRET_ACCESS_KEY
          - name: AWS_SECRET_KEY
          - deprecated:
              alternatives: AWS_SECRET_ACCESS_KEY
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: EC2 in the name implied it was limited to EC2 resources.  However, it is
                used for all connections.
            name: EC2_SECRET_KEY
        aliases: [aws_secret_access_key, aws_secret_key, ec2_secret_key]
        default: null
        type: str

- session_token
        AWS STS session token for use with temporary credentials.
        See the AWS documentation for more information about access tokens
        https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.
        The `security_token' and `profile' options are mutually exclusive.
        Aliases `aws_session_token' and `session_token' were added in release 3.2.0, with the parameter being renamed
        from `security_token' to `session_token' in release 6.0.0.
        The `security_token', `aws_security_token', and `access_token' aliases have been deprecated and will be
        removed in a release after 2024-12-01.
        set_via:
          env:
          - name: AWS_SESSION_TOKEN
          - deprecated:
              alternatives: AWS_SESSION_TOKEN
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: AWS_SECURITY_TOKEN was used for compatibility with the original boto SDK,
                support for which has been dropped
            name: AWS_SECURITY_TOKEN
          - deprecated:
              alternatives: AWS_SESSION_TOKEN
              collection_name: amazon.aws
              removed_at_date: '2024-12-01'
              why: EC2 in the name implied it was limited to EC2 resources.  However, it is
                used for all connections.
            name: EC2_SECURITY_TOKEN
        aliases: [aws_session_token, security_token, aws_security_token, access_token]
        default: null
        type: str

- strict
        If `yes' make invalid entries a fatal error, otherwise skip and continue.
        Since it is possible to use facts in the expressions they might not always be available and we ignore those
        errors by default.
        default: false
        type: bool

- strict_permissions
        By default if a 403 (Forbidden) error code is encountered this plugin will fail.
        You can set this option to False in the inventory config file which will allow 403 errors to be gracefully
        skipped.
        default: true
        type: bool

- use_contrib_script_compatible_ec2_tag_keys
        Expose the host tags with ec2_tag_TAGNAME keys like the old ec2.py inventory script.
        The use of this feature is discouraged and we advise to migrate to the new ``tags`` structure.
        default: false
        type: bool
        added in: version 1.5.0 of amazon.aws


- use_contrib_script_compatible_sanitization
        By default this plugin is using a general group name sanitization to create safe and usable group names for
        use in Ansible. This option allows you to override that, in efforts to allow migration from the old inventory
        script and matches the sanitization of groups when the script's ``replace_dash_in_groups`` option is set to
        ``False``. To replicate behavior of ``replace_dash_in_groups = True`` with constructed groups, you will need
        to replace hyphens with underscores via the regex_replace filter for those entries.
        For this to work you should also turn off the TRANSFORM_INVALID_GROUP_CHARS setting, otherwise the core engine
        will just use the standard sanitization on top.
        This is not the default as such names break certain functionality as not all characters are valid Python
        identifiers which group names end up being used as.
        default: false
        type: bool

- use_extra_vars
        Merge extra vars into the available variables for composition (highest precedence).
        set_via:
          env:
          - name: ANSIBLE_INVENTORY_USE_EXTRA_VARS
          ini:
          - key: use_extra_vars
            section: inventory_plugins
        default: false
        type: bool
        added in: version 2.11 of ansible-core


- use_ssm_inventory
        Enables fetching additional EC2 instance information from the AWS Systems Manager (SSM) inventory service into
        hostvars.
        By leveraging the SSM inventory data, the `use_ssm_inventory' option provides additional details and
        attributes about the EC2 instances in your inventory. These details can include operating system information,
        installed software, network configurations, and custom inventory attributes defined in SSM.
        default: false
        type: bool
        added in: version 6.0.0 of amazon.aws



NOTES:
      * If no credentials are provided and the control node has an associated IAM instance profile then the role
        will be used for authentication.
      * *Caution:* For modules, environment variables and configuration files are read from the Ansible 'host'
        context and not the 'controller' context. As such, files may need to be explicitly copied to the 'host'.
        For lookup and connection plugins, environment variables and configuration files are read from the
        Ansible 'controller' context and not the 'host' context.
      * The AWS SDK (boto3) that Ansible uses may also read defaults for credentials and other settings, such as
        the region, from its configuration files in the Ansible 'host' context (typically `~/.aws/credentials').
        See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.


REQUIREMENTS:  python >= 3.6, boto3 >= 1.22.0, botocore >= 1.25.0

AUTHOR: Sloane Hertel (@s-hertel)

NAME: aws_ec2

EXAMPLES:

# Minimal example using environment vars or instance role credentials
# Fetch all hosts in us-east-1, the hostname is the public DNS if it exists, otherwise the private IP address
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1

# Example using filters, ignoring permission errors, and specifying the hostname precedence
plugin: amazon.aws.aws_ec2
# The values for profile, access key, secret key and token can be hardcoded like:
boto_profile: aws_profile
# or you could use Jinja as:
# boto_profile: "{{ lookup('env', 'AWS_PROFILE') | default('aws_profile', true) }}"
# Populate inventory with instances in these regions
regions:
  - us-east-1
  - us-east-2
filters:
  # All instances with their `Environment` tag set to `dev`
  tag:Environment: dev
  # All dev and QA hosts
  tag:Environment:
    - dev
    - qa
  instance.group-id: sg-xxxxxxxx
# Ignores 403 errors rather than failing
strict_permissions: False
# Note: I(hostnames) sets the inventory_hostname. To modify ansible_host without modifying
# inventory_hostname use compose (see example below).
hostnames:
  - tag:Name=Tag1,Name=Tag2  # Return specific hosts only
  - tag:CustomDNSName
  - dns-name
  - name: 'tag:Name=Tag1,Name=Tag2'
  - name: 'private-ip-address'
    separator: '_'
    prefix: 'tag:Name'
  - name: 'test_literal' # Using literal values for hostname
    separator: '-'       # Hostname will be aws-test_literal
    prefix: 'aws'

# Returns all the hostnames for a given instance
allow_duplicated_hosts: False

# Example using constructed features to create groups and set ansible_host
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-west-1
# keyed_groups may be used to create custom groups
strict: False
keyed_groups:
  # Add e.g. x86_64 hosts to an arch_x86_64 group
  - prefix: arch
    key: 'architecture'
  # Add hosts to tag_Name_Value groups for each Name/Value tag pair
  - prefix: tag
    key: tags
  # Add hosts to e.g. instance_type_z3_tiny
  - prefix: instance_type
    key: instance_type
  # Create security_groups_sg_abcd1234 group for each SG
  - key: 'security_groups|json_query("[].group_id")'
    prefix: 'security_groups'
  # Create a group for each value of the Application tag
  - key: tags.Application
    separator: ''
  # Create a group per region e.g. aws_region_us_east_2
  - key: placement.region
    prefix: aws_region
  # Create a group (or groups) based on the value of a custom tag "Role" and add them to a metagroup called "project"
  - key: tags['Role']
    prefix: foo
    parent_group: "project"
# Set individual variables with compose
compose:
  # Use the private IP address to connect to the host
  # (note: this does not modify inventory_hostname, which is set via I(hostnames))
  ansible_host: private_ip_address

# Example using include_filters and exclude_filters to compose the inventory.
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-west-1
include_filters:
- tag:Name:
  - 'my_second_tag'
- tag:Name:
  - 'my_third_tag'
exclude_filters:
- tag:Name:
  - 'my_first_tag'

# Example using groups to assign the running hosts to a group based on vpc_id
plugin: amazon.aws.aws_ec2
boto_profile: aws_profile
# Populate inventory with instances in these regions
regions:
  - us-east-2
filters:
  # All instances with their state as `running`
  instance-state-name: running
keyed_groups:
  - prefix: tag
    key: tags
compose:
  ansible_host: public_dns_name
groups:
  libvpc: vpc_id == 'vpc-####'
# Define prefix and suffix for host variables coming from AWS.
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
hostvars_prefix: 'aws_'
hostvars_suffix: '_ec2'

 

AWS 동적 인벤토리

 

  1. Ansible에 AWS 동적 인벤토리 플러그인을 설치합니다.
  2. AWS 인벤토리 파일을 생성합니다.
  3. Ansible 구성 파일에 AWS 인벤토리 파일을 지정합니다.
  4. Ansible 플레이북을 실행합니다.

1. Ansible에 AWS 동적 인벤토리 플러그인을 설치합니다.

Ansible에 AWS 동적 인벤토리 플러그인을 설치하려면 다음 명령을 사용합니다.

ansible-galaxy collection install amazon.aws

2. AWS 인벤토리 파일을 생성합니다.
AWS 인벤토리 파일은 Ansible이 AWS 인스턴스를 인벤토리로 가져오는 데 사용하는 YAML 파일입니다. 인벤토리 파일에는 다음과 같은 정보가 포함되어 있습니다.

  • 인스턴스 ID
  • 인스턴스 이름
  • 인스턴스 태그
  • 인스턴스 위치

AWS 인벤토리 파일의 예는 다음과 같습니다.

vim inventory_aws_ec2.yaml
plugin: aws_ec2

regions:
  - us-east-1
  - ap-northeast-2  # 서울 리전 추가
  - ap-southeast-1  # 싱가포르 리전 추가

cache: true

cache_max_age: 3600

filters:
  instance-state-name: running

groups:
  ### Production
  Production: "'prod' in (tags.Env)"
  ### Web Server
  Web_Server: "'prod' in (tags.Env|default([])) and 'web' in (tags.Services|default([]))"
  Web_Seoul: "'ap-northeast-2' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'web' in (tags.Services|default([]))"
  Web_Singapore: "'us-east-1' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'web' in (tags.Services|default([]))"
  Web_Virginia: "'ap-southeast-1' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'web' in (tags.Services|default([]))"
  ### Redis Server
  Redis_Server: "'prod' in (tags.Env|default([])) and 'redis' in (tags.Services|default([]))"
  Redis_Seoul: "'ap-northeast-2' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'redis' in (tags.Services|default([]))"
  Redis_Singapore: "'us-east-1' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'redis' in (tags.Services|default([]))"
  Redis_Virginia: "'ap-southeast-1' in (placement.region|default([])) and 'prod' in (tags.Env|default([])) and 'redis' in (tags.Services|default([]))"

# keyed_groups:
#   - key: placement.region
#     prefix: aws_region
#   - prefix: distro
#     key: ansible_distribution
#   - prefix: arch
#     key: architecture
#   - prefix: tag
#     key: tags.Services
#   - prefix: tag
#     key: tags.Env
      #compose:
      #  ansible_host: private_ip_address

3. Ansible 구성 파일에 AWS 인벤토리 파일을 지정합니다.
Ansible 구성 파일은 Ansible이 인벤토리를 가져오는 데 사용하는 YAML 파일입니다. 구성 파일에는 다음과 같은 정보가 포함되어 있습니다.

  • 인벤토리 파일의 경로
  • 인벤토리 파일의 이름

Ansible 구성 파일의 예는 다음과 같습니다.

vim ansible.cfg
[defaults]
inventory = inventory_aws_ec2.yaml
host_key_checking = False

4. Ansible 플레이북을 실행합니다.
Ansible 플레이북은 Ansible이 실행하는 명령 목록입니다. 플레이북을 실행하려면 다음 명령을 사용합니다.

ansible-inventory -i inventory_aws_ec2.yaml --graph

playbook.yml은 Ansible 플레이북의 이름입니다.

이제 Ansible은 AWS 동적 인벤토리를 사용하여 AWS 인스턴스를 인벤토리로 가져오고 플레이북을 실행합니다.

AWS 동적 인벤토리는 Ansible을 사용하여 AWS 인스턴스를 관리하는 데 유용한 도구입니다. 인스턴스 목록을 항상 최신 상태로 유지하고, 인벤토리를 수동으로 관리할 필요가 없습니다.

 

참고URL

- 인벤토리 플러그인 사용 : https://docs.ansible.com/ansible/latest/plugins/inventory.html

 

728x90
반응형