mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-02-04 07:51:50 +00:00
ip2location_info: New Module - ip2location.io for IP geolocation lookup (#11170)
* Added ip2location.io for IP geolocation lookup. * Removed tab in last line. * Added "ip2location" as maintainer. * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2locationio_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Added "typing" library. * Updated import position. * Reformatted. * Added unit test. * Updated documentation to add "ip" parameter. * Renamed module from "ip2location_facts" to "ip2location_info". * Updated version number. Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2location_info.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2location_info.py Co-authored-by: Felix Fontein <felix@fontein.de> * Updated return definition. * Update BOTMETA.yml to latest module name. * Update plugins/modules/ip2location_info.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/ip2location_info.py Co-authored-by: Felix Fontein <felix@fontein.de> * Removed extra parameter from "fetch_url". * Fixed "test_ip2location_info.py" with formatter. --------- Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
IP2Location
GitHub
parent
a55884c921
commit
2c6746ffa0
3 changed files with 213 additions and 0 deletions
2
.github/BOTMETA.yml
vendored
2
.github/BOTMETA.yml
vendored
|
|
@ -745,6 +745,8 @@ files:
|
|||
maintainers: obourdon hryamzik
|
||||
$modules/ip_netns.py:
|
||||
maintainers: bregman-arie
|
||||
$modules/ip2location_info.py:
|
||||
maintainers: ip2location
|
||||
$modules/ipa_:
|
||||
maintainers: $team_ipa
|
||||
ignore: fxfitz
|
||||
|
|
|
|||
164
plugins/modules/ip2location_info.py
Normal file
164
plugins/modules/ip2location_info.py
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
#!/usr/bin/python
|
||||
|
||||
# Copyright (c) 2025, IP2Location <support@ip2location.com>
|
||||
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
# SPDX-License-Identifier: GPL-3.0-or-later
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
DOCUMENTATION = r"""
|
||||
module: ip2location_info
|
||||
short_description: Retrieve IP geolocation information of a host's IP address
|
||||
version_added: 12.2.0
|
||||
description:
|
||||
- Gather IP geolocation information of a host's IP address using the keyless U(api.ip2location.io) API.
|
||||
author: "IP2Location (@ip2location)"
|
||||
extends_documentation_fragment:
|
||||
- community.general.attributes
|
||||
- community.general.attributes.info_module
|
||||
options:
|
||||
ip:
|
||||
description:
|
||||
- IP address to retrieve geolocation information.
|
||||
type: str
|
||||
timeout:
|
||||
description:
|
||||
- HTTP connection timeout in seconds.
|
||||
default: 10
|
||||
type: int
|
||||
http_agent:
|
||||
description:
|
||||
- Set HTTP user agent.
|
||||
default: "ansible-ip2location-info-module/0.0.1"
|
||||
type: str
|
||||
notes:
|
||||
- This module uses the keyless endpoint which has usage limits.
|
||||
Check U(https://www.ip2location.io/ip2location-documentation) for more information.
|
||||
"""
|
||||
|
||||
EXAMPLES = r"""
|
||||
# Retrieve geolocation data of a host's IP address
|
||||
- name: Get IP geolocation data
|
||||
community.general.ip2location_info:
|
||||
register: result
|
||||
|
||||
- name: Show some information
|
||||
ansible.builtin.debug:
|
||||
msg: "{{ result.ip }} is located in {{ result.country_code }} ({{ result.country_name }})"
|
||||
"""
|
||||
|
||||
RETURN = r"""
|
||||
record:
|
||||
description: Dictionary of IP geolocation information for the IP address.
|
||||
returned: changed
|
||||
type: complex
|
||||
contains:
|
||||
ip:
|
||||
description: "Public IP address of a host."
|
||||
type: str
|
||||
sample: "8.8.8.8"
|
||||
country_code:
|
||||
description: ISO 3166-1 alpha-2 country code.
|
||||
type: str
|
||||
sample: "US"
|
||||
country_name:
|
||||
description: Country name based on ISO 3166.
|
||||
type: str
|
||||
sample: "United States of America"
|
||||
region_name:
|
||||
description: State or province name.
|
||||
type: str
|
||||
sample: "California"
|
||||
city_name:
|
||||
description: City name.
|
||||
type: str
|
||||
sample: "Mountain View"
|
||||
latitude:
|
||||
description: Latitude of the city.
|
||||
type: float
|
||||
sample: 37.3860
|
||||
longitude:
|
||||
description: Longitude of the city.
|
||||
type: float
|
||||
sample: -122.0838
|
||||
zip_code:
|
||||
description: ZIP/Postal code.
|
||||
type: str
|
||||
sample: "94035"
|
||||
time_zone:
|
||||
description: UTC time zone (with DST supported).
|
||||
type: str
|
||||
sample: "-08:00"
|
||||
asn:
|
||||
description: Autonomous system number (ASN).
|
||||
type: str
|
||||
sample: "15169"
|
||||
as:
|
||||
description: Autonomous system (AS) name.
|
||||
type: str
|
||||
sample: "Google LLC"
|
||||
is_proxy:
|
||||
description: Whether is a proxy or not.
|
||||
type: bool
|
||||
sample: false
|
||||
"""
|
||||
|
||||
import typing as t
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils.urls import fetch_url
|
||||
|
||||
USER_AGENT = "ansible-ip2location-info-module/0.0.1"
|
||||
|
||||
|
||||
class Ip2LocationInfo:
|
||||
def __init__(self, module: AnsibleModule) -> None:
|
||||
self.url = "https://api.ip2location.io/"
|
||||
self.timeout = module.params.get("timeout")
|
||||
self.ip = module.params.get("ip")
|
||||
self.module = module
|
||||
|
||||
def get_geo_data(self) -> dict[str, t.Any]:
|
||||
url = self.url
|
||||
if self.ip:
|
||||
url += f"?ip={self.ip}"
|
||||
|
||||
response, info = fetch_url(
|
||||
self.module,
|
||||
url,
|
||||
timeout=self.timeout,
|
||||
)
|
||||
if info["status"] != 200:
|
||||
self.module.fail_json(
|
||||
msg=f"Could not get {url} page, check for connectivity! HTTP Status: {info['status']}"
|
||||
)
|
||||
|
||||
try:
|
||||
content = response.read()
|
||||
result = self.module.from_json(content)
|
||||
except Exception as exc:
|
||||
self.module.fail_json(
|
||||
msg=f"Failed to parse the ip2location.io response from {url}: {exc}", read_content=content
|
||||
)
|
||||
else:
|
||||
return result
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(
|
||||
http_agent=dict(default=USER_AGENT),
|
||||
timeout=dict(type="int", default=10),
|
||||
ip=dict(type="str"),
|
||||
),
|
||||
supports_check_mode=True,
|
||||
)
|
||||
|
||||
ip2location_info = Ip2LocationInfo(module)
|
||||
ip2location_info_result = {"changed": False}
|
||||
ip2location_info_result.update(ip2location_info.get_geo_data())
|
||||
module.exit_json(**ip2location_info_result)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
47
tests/unit/plugins/modules/test_ip2location_info.py
Normal file
47
tests/unit/plugins/modules/test_ip2location_info.py
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Copyright (c) 2025, IP2Location <support@ip2location.com>
|
||||
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
# SPDX-License-Identifier: GPL-3.0-or-later
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import unittest
|
||||
from unittest.mock import Mock, patch
|
||||
|
||||
from ansible_collections.community.general.plugins.modules.ip2location_info import Ip2LocationInfo
|
||||
|
||||
|
||||
IP2LOCATION_DATA = {
|
||||
"ip": "8.8.8.8",
|
||||
"country_code": "US",
|
||||
"country_name": "United States of America",
|
||||
"region_name": "California",
|
||||
"city_name": "Mountain View",
|
||||
"latitude": 37.386051,
|
||||
"longitude": -122.083855,
|
||||
"zip_code": "94035",
|
||||
"time_zone": "-07:00",
|
||||
"asn": "15169",
|
||||
"as": "Google LLC",
|
||||
"is_proxy": False,
|
||||
}
|
||||
|
||||
|
||||
class TestIp2LocationInfo(unittest.TestCase):
|
||||
def test_get_geo_data_with_ip(self):
|
||||
module = Mock()
|
||||
module.params = {"timeout": 10, "ip": "8.8.8.8"}
|
||||
module.from_json.side_effect = json.loads
|
||||
|
||||
with patch(
|
||||
"ansible_collections.community.general.plugins.modules.ip2location_info.fetch_url"
|
||||
) as mock_fetch_url:
|
||||
mock_response = Mock()
|
||||
mock_response.read.return_value = json.dumps(IP2LOCATION_DATA)
|
||||
mock_fetch_url.return_value = (mock_response, {"status": 200})
|
||||
|
||||
ip2location_info = Ip2LocationInfo(module)
|
||||
result = ip2location_info.get_geo_data()
|
||||
|
||||
self.assertEqual(result["country_code"], "US")
|
||||
mock_fetch_url.assert_called_once_with(module, "https://api.ip2location.io/?ip=8.8.8.8", timeout=10)
|
||||
Loading…
Add table
Add a link
Reference in a new issue