`cloudflare_dns`: add support for `comment` and `tags` (#9132)

* `cloudflare_dns`: add support for `comment` and `tags`

* `cloudflare_dns`: add return values for `comment`/`tags` fields

* `cloudflare_dns`: fix return values samples

* `cloudflare_dns`: changelog fragment formatting

* `cloudflare_dns`: add missing `version_added`

* `cloudflare_dns`: remove explicit `required: false`

* `cloudflare_dns`: empty `comment` idempotency fix

changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - cloudflare_dns - add support for ``comment`` and ``tags`` (https://github.com/ansible-collections/community.general/pull/9132).

plugins/modules/cloudflare_dns.py

@@ -31,7 +31,6 @@ options:
     - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
     - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
     type: str
-    required: false
     version_added: '0.2.0'
   account_api_key:
     description:
@@ -39,13 +38,11 @@ options:
     - Required for api keys authentication.
     - "You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
     type: str
-    required: false
     aliases: [ account_api_token ]
   account_email:
     description:
     - Account email. Required for API keys authentication.
     type: str
-    required: false
   algorithm:
     description:
     - Algorithm number.
@@ -57,6 +54,11 @@ options:
     - Required for O(type=TLSA) when O(state=present).
     type: int
     choices: [ 0, 1, 2, 3 ]
+  comment:
+    description:
+    - Comments or notes about the DNS record.
+    type: str
+    version_added: 10.1.0
   flag:
     description:
     - Issuer Critical Flag.
@@ -134,6 +136,12 @@ options:
     type: str
     choices: [ absent, present ]
     default: present
+  tags:
+    description:
+    - Custom tags for the DNS record.
+    type: list
+    elements: str
+    version_added: 10.1.0
   timeout:
     description:
     - Timeout for Cloudflare API calls.
@@ -191,6 +199,18 @@ EXAMPLES = r'''
     value: 127.0.0.1
     api_token: dummyapitoken
 
+- name: Create a record with comment and tags
+  community.general.cloudflare_dns:
+    zone: example.net
+    record: test
+    type: A
+    value: 127.0.0.1
+    comment: Local test website
+    tags:
+    - test
+    - local
+    api_token: dummyapitoken
+
 - name: Create a example.net CNAME record to example.com
   community.general.cloudflare_dns:
     zone: example.net
@@ -299,6 +319,18 @@ record:
     returned: success, except on record deletion
     type: complex
     contains:
+        comment:
+            description: Comments or notes about the DNS record.
+            returned: success
+            type: str
+            sample: Domain verification record
+            version_added: 10.1.0
+        comment_modified_on:
+            description: When the record comment was last modified. Omitted if there is no comment.
+            returned: success
+            type: str
+            sample: "2024-01-01T05:20:00.12345Z"
+            version_added: 10.1.0
         content:
             description: The record content (details depend on record type).
             returned: success
@@ -333,7 +365,7 @@ record:
             type: bool
             sample: false
         meta:
-            description: No documentation available.
+            description: Extra Cloudflare-specific information about the record.
             returned: success
             type: dict
             sample: { auto_added: false }
@@ -362,6 +394,19 @@ record:
             returned: success
             type: bool
             sample: false
+        tags:
+            description: Custom tags for the DNS record.
+            returned: success
+            type: list
+            elements: str
+            sample: ['production', 'app']
+            version_added: 10.1.0
+        tags_modified_on:
+            description: When the record tags were last modified. Omitted if there are no tags.
+            returned: success
+            type: str
+            sample: "2025-01-01T05:20:00.12345Z"
+            version_added: 10.1.0
         ttl:
             description: The time-to-live for the record.
             returned: success
@@ -410,9 +455,11 @@ class CloudflareAPI(object):
         self.account_email = module.params['account_email']
         self.algorithm = module.params['algorithm']
         self.cert_usage = module.params['cert_usage']
+        self.comment = module.params['comment']
         self.hash_type = module.params['hash_type']
         self.flag = module.params['flag']
         self.tag = module.params['tag']
+        self.tags = module.params['tags']
         self.key_tag = module.params['key_tag']
         self.port = module.params['port']
         self.priority = module.params['priority']
@@ -662,7 +709,7 @@ class CloudflareAPI(object):
     def ensure_dns_record(self, **kwargs):
         params = {}
         for param in ['port', 'priority', 'proto', 'proxied', 'service', 'ttl', 'type', 'record', 'value', 'weight', 'zone',
-                      'algorithm', 'cert_usage', 'hash_type', 'selector', 'key_tag', 'flag', 'tag']:
+                      'algorithm', 'cert_usage', 'hash_type', 'selector', 'key_tag', 'flag', 'tag', 'tags', 'comment']:
             if param in kwargs:
                 params[param] = kwargs[param]
             else:
@@ -798,6 +845,9 @@ class CloudflareAPI(object):
             }
             search_value = None
 
+        new_record['comment'] = params['comment'] or None
+        new_record['tags'] = params['tags'] or []
+
         zone_id = self._get_zone_id(params['zone'])
         records = self.get_dns_records(params['zone'], params['type'], search_record, search_value)
         # in theory this should be impossible as cloudflare does not allow
@@ -826,6 +876,10 @@ class CloudflareAPI(object):
                     do_update = True
             if (params['type'] == 'CNAME') and (cur_record['content'] != new_record['content']):
                 do_update = True
+            if cur_record['comment'] != new_record['comment']:
+                do_update = True
+            if sorted(cur_record['tags']) != sorted(new_record['tags']):
+                do_update = True
             if do_update:
                 if self.module.check_mode:
                     result = new_record
@@ -856,11 +910,13 @@ def main():
             account_email=dict(type='str', required=False),
             algorithm=dict(type='int'),
             cert_usage=dict(type='int', choices=[0, 1, 2, 3]),
+            comment=dict(type='str'),
             hash_type=dict(type='int', choices=[1, 2]),
             key_tag=dict(type='int', no_log=False),
             port=dict(type='int'),
             flag=dict(type='int', choices=[0, 1]),
             tag=dict(type='str', choices=['issue', 'issuewild', 'iodef']),
+            tags=dict(type='list', elements='str'),
             priority=dict(type='int', default=1),
             proto=dict(type='str'),
             proxied=dict(type='bool', default=False),