diff --git a/README.md b/README.md index 6e37c03a..56f420c7 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,7 @@ Name | Description | [linode.cloud.monitor_services_alert_definition_info](./docs/modules/monitor_services_alert_definition_info.md)|Get info about a Linode Alert Definition.| [linode.cloud.nodebalancer_info](./docs/modules/nodebalancer_info.md)|Get info about a Linode Node Balancer.| [linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**| +[linode.cloud.object_storage_global_quota_info](./docs/modules/object_storage_global_quota_info.md)|Get info about a Linode Object Storage Global Quota.| [linode.cloud.object_storage_quota_info](./docs/modules/object_storage_quota_info.md)|Get info about a Linode Object Storage Quota.| [linode.cloud.placement_group_info](./docs/modules/placement_group_info.md)|Get info about a Linode Placement Group.| [linode.cloud.profile_info](./docs/modules/profile_info.md)|Get info about a Linode Profile.| @@ -150,6 +151,7 @@ Name | Description | [linode.cloud.nodebalancer_type_list](./docs/modules/nodebalancer_type_list.md)|List and filter on Node Balancer Types.| [linode.cloud.object_cluster_list](./docs/modules/object_cluster_list.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**| [linode.cloud.object_storage_endpoint_list](./docs/modules/object_storage_endpoint_list.md)|List and filter on Object Storage Endpoints.| +[linode.cloud.object_storage_global_quota_list](./docs/modules/object_storage_global_quota_list.md)|List Object Storage Global Quotas.| [linode.cloud.object_storage_quota_list](./docs/modules/object_storage_quota_list.md)|List and filter on Object Storage Quotas.| [linode.cloud.placement_group_list](./docs/modules/placement_group_list.md)|List and filter on Placement Groups.| [linode.cloud.region_list](./docs/modules/region_list.md)|List and filter on Regions.| diff --git a/docs/modules/object_storage_global_quota_info.md b/docs/modules/object_storage_global_quota_info.md new file mode 100644 index 00000000..330ffae8 --- /dev/null +++ b/docs/modules/object_storage_global_quota_info.md @@ -0,0 +1,60 @@ +# object_storage_global_quota_info + +Get info about a Linode Object Storage Global Quota. + +- [Minimum Required Fields](#minimum-required-fields) +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Minimum Required Fields +| Field | Type | Required | Description | +|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module.
It can be exposed by the environment variable `LINODE_API_TOKEN` instead.
See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). | + +## Examples + +```yaml +- name: Get info about an Object Storage global quota + linode.cloud.object_storage_global_quota_info: + quota_id: keys +``` + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `quota_id` |
`str`
|
**Required**
| The Quota ID of the Object Storage Global Quota to resolve. | + +## Return Values + +- `object_storage_global_quota` - The returned Object Storage Global Quota. + + - Sample Response: + ```json + { + "description": "Current number of access keys per account", + "has_usage": true, + "quota_id": "keys", + "quota_limit": 100, + "quota_name": "Number of Access Keys", + "quota_type": "keys", + "resource_metric": "key" + } + ``` + - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quota) for a list of returned fields + + +- `quota_usage` - The returned Quota Usage. + + - Sample Response: + ```json + { + "quota_limit": 100, + "usage": 47 + } + ``` + - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quota-usage) for a list of returned fields + + diff --git a/docs/modules/object_storage_global_quota_list.md b/docs/modules/object_storage_global_quota_list.md new file mode 100644 index 00000000..13deedd0 --- /dev/null +++ b/docs/modules/object_storage_global_quota_list.md @@ -0,0 +1,49 @@ +# object_storage_global_quota_list + +List Object Storage Global Quotas. + +- [Minimum Required Fields](#minimum-required-fields) +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Minimum Required Fields +| Field | Type | Required | Description | +|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module.
It can be exposed by the environment variable `LINODE_API_TOKEN` instead.
See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). | + +## Examples + +```yaml +- name: List all Object Storage global quotas for the current account + linode.cloud.object_storage_global_quota_list: +``` + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `count` |
`int`
|
Optional
| The number of Object Storage Global Quotas to return. If undefined, all results will be returned. | + +## Return Values + +- `object_storage_global_quotas` - The returned Object Storage Global Quotas. + + - Sample Response: + ```json + [ + { + "description": "Current number of access keys per account", + "has_usage": true, + "quota_id": "keys", + "quota_limit": 100, + "quota_name": "Number of Access Keys", + "quota_type": "keys", + "resource_metric": "key" + } + ] + ``` + - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quotas) for a list of returned fields + + diff --git a/plugins/module_utils/doc_fragments/object_storage_global_quota_info.py b/plugins/module_utils/doc_fragments/object_storage_global_quota_info.py new file mode 100644 index 00000000..c01eef3e --- /dev/null +++ b/plugins/module_utils/doc_fragments/object_storage_global_quota_info.py @@ -0,0 +1,22 @@ +"""Documentation fragments for the object_storage_global_quota_info module""" + +result_object_storage_global_quota_samples = ['''{ + "description": "Current number of access keys per account", + "has_usage": true, + "quota_id": "keys", + "quota_limit": 100, + "quota_name": "Number of Access Keys", + "quota_type": "keys", + "resource_metric": "key" +}'''] + +result_object_storage_global_quota_usage_samples = ['''{ + "quota_limit": 100, + "usage": 47 +}'''] + + +specdoc_examples = [''' +- name: Get info about an Object Storage global quota + linode.cloud.object_storage_global_quota_info: + quota_id: keys'''] diff --git a/plugins/module_utils/doc_fragments/object_storage_global_quota_list.py b/plugins/module_utils/doc_fragments/object_storage_global_quota_list.py new file mode 100644 index 00000000..30f9a02b --- /dev/null +++ b/plugins/module_utils/doc_fragments/object_storage_global_quota_list.py @@ -0,0 +1,17 @@ +"""Documentation fragments for the object_storage_global_quota_list module""" + +specdoc_examples = [''' +- name: List all Object Storage global quotas for the current account + linode.cloud.object_storage_global_quota_list:'''] + +result_object_storage_global_quotas_samples = ['''[ + { + "description": "Current number of access keys per account", + "has_usage": true, + "quota_id": "keys", + "quota_limit": 100, + "quota_name": "Number of Access Keys", + "quota_type": "keys", + "resource_metric": "key" + } +]'''] diff --git a/plugins/module_utils/linode_common_list.py b/plugins/module_utils/linode_common_list.py index d27b4286..314f29cb 100644 --- a/plugins/module_utils/linode_common_list.py +++ b/plugins/module_utils/linode_common_list.py @@ -81,7 +81,7 @@ def __init__( self.params = params or [] self.examples = examples or [] self.description = description or [ - f"List and filter on {self.result_display_name}." + f"List{' and filter on' if not disable_filters else ''} {self.result_display_name}." ] self.result_samples = result_samples or [] self.requires_beta = requires_beta diff --git a/plugins/modules/object_storage_global_quota_info.py b/plugins/modules/object_storage_global_quota_info.py new file mode 100644 index 00000000..093248c3 --- /dev/null +++ b/plugins/modules/object_storage_global_quota_info.py @@ -0,0 +1,82 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +"""This module contains all of the functionality for Linode Object Storage global quota info.""" + +from __future__ import absolute_import, division, print_function + +from typing import Any + +from ansible_collections.linode.cloud.plugins.module_utils.doc_fragments import ( + object_storage_global_quota_info as docs, +) +from ansible_collections.linode.cloud.plugins.module_utils.linode_common_info import ( + InfoModule, + InfoModuleAttr, + InfoModuleResult, +) +from ansible_specdoc.objects import FieldType +from linode_api4 import LinodeClient, ObjectStorageGlobalQuota + + +def get_quota_usage( + client: LinodeClient, + object_storage_global_quota: dict[str, Any], + params: dict | None, +) -> dict[str, Any] | None: + """Return quota usage details for a quota when usage is available.""" + if not object_storage_global_quota["has_usage"]: + return None + + return ( + ObjectStorageGlobalQuota( + client, object_storage_global_quota["quota_id"] + ) + .usage() + .dict + ) + + +module = InfoModule( + examples=docs.specdoc_examples, + primary_result=InfoModuleResult( + display_name="Object Storage Global Quota", + field_name="object_storage_global_quota", + field_type=FieldType.dict, + docs_url="https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quota", + samples=docs.result_object_storage_global_quota_samples, + ), + secondary_results=[ + InfoModuleResult( + display_name="Quota Usage", + field_name="quota_usage", + field_type=FieldType.dict, + docs_url="https://techdocs.akamai.com/linode-api/reference" + "/get-object-storage-global-quota-usage", + samples=docs.result_object_storage_global_quota_usage_samples, + get=get_quota_usage, + ), + ], + attributes=[ + InfoModuleAttr( + name="quota_id", + display_name="Quota ID", + type=FieldType.string, + get=lambda client, params: client.load( + ObjectStorageGlobalQuota, params.get("quota_id") + )._raw_json, + ), + ], +) + +SPECDOC_META = module.spec + +DOCUMENTATION = r""" +""" +EXAMPLES = r""" +""" +RETURN = r""" +""" + +if __name__ == "__main__": + module.run() diff --git a/plugins/modules/object_storage_global_quota_list.py b/plugins/modules/object_storage_global_quota_list.py new file mode 100644 index 00000000..819a80b2 --- /dev/null +++ b/plugins/modules/object_storage_global_quota_list.py @@ -0,0 +1,35 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +"""This module allows users to list Object Storage global quotas.""" + +from __future__ import absolute_import, division, print_function + +from ansible_collections.linode.cloud.plugins.module_utils.doc_fragments import ( + object_storage_global_quota_list as docs, +) +from ansible_collections.linode.cloud.plugins.module_utils.linode_common_list import ( + ListModule, +) + +module = ListModule( + result_display_name="Object Storage Global Quotas", + result_field_name="object_storage_global_quotas", + endpoint_template="/object-storage/global-quotas", + result_docs_url="https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quotas", # pylint: disable=line-too-long + result_samples=docs.result_object_storage_global_quotas_samples, + examples=docs.specdoc_examples, + disable_filters=True, +) + +SPECDOC_META = module.spec + +DOCUMENTATION = r""" +""" +EXAMPLES = r""" +""" +RETURN = r""" +""" + +if __name__ == "__main__": + module.run() diff --git a/pyproject.toml b/pyproject.toml index 849f7bda..d0a61466 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,6 +9,8 @@ target-version = [ "py310", "py311", "py312", + "py313", + "py314", ] exclude = "plugins/module_utils/doc_fragments" @@ -56,5 +58,5 @@ disable = [ "fixme", ] max-positional-arguments = 12 -py-version = "3.9" +py-version = "3.10" extension-pkg-whitelist = "math" diff --git a/tests/integration/targets/object_storage_global_quota_info/tasks/main.yaml b/tests/integration/targets/object_storage_global_quota_info/tasks/main.yaml new file mode 100644 index 00000000..e5bd6a0f --- /dev/null +++ b/tests/integration/targets/object_storage_global_quota_info/tasks/main.yaml @@ -0,0 +1,28 @@ +- name: object_storage_global_quota_info + block: + - name: List Object Storage global quotas + linode.cloud.object_storage_global_quota_list: + register: obj_global_quota_list + + - name: Assert at least one global quota returned for the following test + assert: + that: + - obj_global_quota_list.object_storage_global_quotas | length > 0 + + - name: Get info about an Object Storage global quota + linode.cloud.object_storage_global_quota_info: + quota_id: '{{ obj_global_quota_list.object_storage_global_quotas[0].quota_id }}' + register: obj_global_quota + + - name: Assert GET Object Storage global quota response + assert: + that: + - obj_global_quota.object_storage_global_quota.quota_id == obj_global_quota_list.object_storage_global_quotas[0].quota_id + - not (obj_global_quota.object_storage_global_quota.has_usage | bool) or (obj_global_quota.quota_usage.quota_limit is integer) + + environment: + LINODE_UA_PREFIX: '{{ ua_prefix }}' + LINODE_API_TOKEN: '{{ api_token }}' + LINODE_API_URL: '{{ api_url }}' + LINODE_API_VERSION: '{{ api_version }}' + LINODE_CA: '{{ ca_file or "" }}' diff --git a/tests/integration/targets/object_storage_global_quota_list/tasks/main.yaml b/tests/integration/targets/object_storage_global_quota_list/tasks/main.yaml new file mode 100644 index 00000000..5d3ffd42 --- /dev/null +++ b/tests/integration/targets/object_storage_global_quota_list/tasks/main.yaml @@ -0,0 +1,18 @@ +- name: object_storage_global_quota_list + block: + - name: List Object Storage global quotas + linode.cloud.object_storage_global_quota_list: + register: obj_global_quota_list + + - name: Assert global quotas are listed correctly + assert: + that: + - obj_global_quota_list.object_storage_global_quotas | length > 0 + - "(obj_global_quota_list.object_storage_global_quotas | selectattr('quota_id', 'equalto', 'keys') | list | length) > 0" + + environment: + LINODE_UA_PREFIX: '{{ ua_prefix }}' + LINODE_API_TOKEN: '{{ api_token }}' + LINODE_API_URL: '{{ api_url }}' + LINODE_API_VERSION: '{{ api_version }}' + LINODE_CA: '{{ ca_file or "" }}'