Implemented database_postgresql_v2 module (#650)

* Implemented database_postgresql_v2 modules * Addressed PR comments
linode · Feb 25, 2025 · 5610d0b · 5610d0b
1 parent 156d281
commit 5610d0b
Show file tree

Hide file tree

Showing 12 changed files with 929 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -25,6 +25,7 @@ Name | Description |
 [linode.cloud.database_mysql](./docs/modules/database_mysql.md)|Manage a Linode MySQL database.|
 [linode.cloud.database_mysql_v2](./docs/modules/database_mysql_v2.md)|Create, read, and update a Linode MySQL database.|
 [linode.cloud.database_postgresql](./docs/modules/database_postgresql.md)|Manage a Linode PostgreSQL database.|
+[linode.cloud.database_postgresql_v2](./docs/modules/database_postgresql_v2.md)|Create, read, and update a Linode PostgreSQL database.|
 [linode.cloud.domain](./docs/modules/domain.md)|Manage Linode Domains.|
 [linode.cloud.domain_record](./docs/modules/domain_record.md)|Manage Linode Domain Records.|
 [linode.cloud.firewall](./docs/modules/firewall.md)|Manage Linode Firewalls.|

diff --git a/docs/modules/database_mysql_v2.md b/docs/modules/database_mysql_v2.md
@@ -103,7 +103,7 @@ Create, read, and update a Linode MySQL database.
 | `day_of_week` | <center>`int`</center> | <center>**Required**</center> | The day to perform maintenance. 1=Monday, 2=Tuesday, etc.  **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** |
 | `duration` | <center>`int`</center> | <center>**Required**</center> | The maximum maintenance window time in hours.   |
 | `hour_of_day` | <center>`int`</center> | <center>**Required**</center> | The hour to begin maintenance based in UTC time.   |
-| `frequency` | <center>`str`</center> | <center>Optional</center> | Whether maintenance occurs on a weekly or monthly basis.  **(Choices: `weekly`, `monthly`; Default: `weekly`)** |
+| `frequency` | <center>`str`</center> | <center>Optional</center> | The frequency at which maintenance occurs.  **(Choices: `weekly`; Default: `weekly`)** |
 
 ## Return Values
 

diff --git a/docs/modules/database_postgresql_v2.md b/docs/modules/database_postgresql_v2.md
@@ -0,0 +1,178 @@
+# database_postgresql_v2
+
+Create, read, and update a Linode PostgreSQL database.
+
+- [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. <br/>It can be exposed by the environment variable `LINODE_API_TOKEN` instead. <br/>See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). |
+
+## Examples
+
+```yaml
+- name: Create a basic PostgreSQL database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    allow_list:
+      - 0.0.0.0/0
+    state: present
+```
+
+```yaml
+- name: Create a PostgreSQL database with three nodes
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-standard-1
+    cluster_size: 3
+    allow_list:
+      - 0.0.0.0/0
+    state: present
+```
+
+```yaml
+- name: Create a PostgreSQL database with an explicit maintenance schedule
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    updates:
+        duration: 4
+        frequency: weekly
+        hour_of_day: 16
+        day_of_week: 4
+    state: present
+```
+
+```yaml
+- name: Create a PostgreSQL database forked from another database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    fork:
+        source: 12345
+    state: present
+```
+
+```yaml
+- name: Delete a PostgreSQL database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    state: absent
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `state` | <center>`str`</center> | <center>**Required**</center> | The desired state of the Managed Database.  **(Choices: `present`, `absent`)** |
+| `allow_list` | <center>`list`</center> | <center>Optional</center> | A list of IP addresses and CIDR ranges that can access the Managed Database.  **(Updatable)** |
+| `cluster_size` | <center>`int`</center> | <center>Optional</center> | The number of Linode instance nodes deployed to the Managed Database.  **(Updatable)** |
+| `engine` | <center>`str`</center> | <center>Optional</center> | The Managed Database engine in engine/version format.  **(Updatable)** |
+| `label` | <center>`str`</center> | <center>Optional</center> | The label of the Managed Database.   |
+| `region` | <center>`str`</center> | <center>Optional</center> | The region of the Managed Database.   |
+| `type` | <center>`str`</center> | <center>Optional</center> | The Linode Instance type used by the Managed Database for its nodes.  **(Updatable)** |
+| [`fork` (sub-options)](#fork) | <center>`dict`</center> | <center>Optional</center> | Information about a database to fork from.   |
+| [`updates` (sub-options)](#updates) | <center>`dict`</center> | <center>Optional</center> | Configuration settings for automated patch update maintenance for the Managed Database.  **(Updatable)** |
+| `wait_timeout` | <center>`int`</center> | <center>Optional</center> | The maximum number of seconds a poll operation can take before raising an error.  **(Default: `2700`)** |
+
+### fork
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `restore_time` | <center>`str`</center> | <center>Optional</center> | The database timestamp from which it was restored.   |
+| `source` | <center>`int`</center> | <center>Optional</center> | The instance id of the database that was forked from.   |
+
+### updates
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `day_of_week` | <center>`int`</center> | <center>**Required**</center> | The day to perform maintenance. 1=Monday, 2=Tuesday, etc.  **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** |
+| `duration` | <center>`int`</center> | <center>**Required**</center> | The maximum maintenance window time in hours.   |
+| `hour_of_day` | <center>`int`</center> | <center>**Required**</center> | The hour to begin maintenance based in UTC time.   |
+| `frequency` | <center>`str`</center> | <center>Optional</center> | The frequency at which maintenance occurs.  **(Choices: `weekly`; Default: `weekly`)** |
+
+## Return Values
+
+- `database` - The database in JSON serialized form.
+
+    - Sample Response:
+        ```json
+        {
+            "allow_list": [
+                "10.0.0.3/32"
+            ],
+            "cluster_size": 3,
+            "created": "2025-02-10T20:10:20",
+            "encrypted": true,
+            "engine": "postgresql",
+            "hosts": {
+                "primary": "a225891-akamai-prod-1798333-default.g2a.akamaidb.net",
+                "standby": "replica-a225891-akamai-prod-1798333-default.g2a.akamaidb.net"
+            },
+            "id": 12345,
+            "label": "my-db",
+            "members": {
+                "172.104.207.136": "primary",
+                "194.195.112.177": "failover",
+                "45.79.126.72": "failover"
+            },
+            "oldest_restore_time": "2025-02-10T20:15:07",
+            "platform": "rdbms-default",
+            "port": 11876,
+            "region": "ap-west",
+            "ssl_connection": true,
+            "status": "active",
+            "total_disk_size_gb": 30,
+            "type": "g6-standard-1",
+            "updated": "2025-02-10T20:25:55",
+            "updates": {
+                "day_of_week": 4,
+                "duration": 4,
+                "frequency": "weekly",
+                "hour_of_day": 16,
+                "pending": []
+            },
+            "used_disk_size_gb": 0,
+            "version": "8.0.35"
+        }
+        ```
+    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-databases-postgre-sql-instance) for a list of returned fields
+
+
+- `ssl_cert` - The SSL CA certificate for an accessible Managed PostgreSQL Database.
+
+    - Sample Response:
+        ```json
+        {
+          "ca_certificate": "LS0tLS1CRUdJ...=="
+        }
+        ```
+    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-databases-postgresql-instance-ssl) for a list of returned fields
+
+
+- `credentials` - The root username and password for an accessible Managed PostgreSQL Database.
+
+    - Sample Response:
+        ```json
+        {
+          "password": "s3cur3P@ssw0rd",
+          "username": "akmadmin"
+        }
+        ```
+    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-databases-postgre-sql-instance-credentials) for a list of returned fields
+
+
diff --git a/plugins/module_utils/doc_fragments/database_postgresql_v2.py b/plugins/module_utils/doc_fragments/database_postgresql_v2.py
@@ -0,0 +1,95 @@
+"""Documentation fragments for the database_postgresql_v2 module"""
+
+specdoc_examples = ['''
+- name: Create a basic PostgreSQL database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    allow_list:
+      - 0.0.0.0/0
+    state: present''', '''
+- name: Create a PostgreSQL database with three nodes
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-standard-1
+    cluster_size: 3
+    allow_list:
+      - 0.0.0.0/0
+    state: present''', '''
+- name: Create a PostgreSQL database with an explicit maintenance schedule
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    updates:
+        duration: 4
+        frequency: weekly
+        hour_of_day: 16
+        day_of_week: 4
+    state: present''', '''
+- name: Create a PostgreSQL database forked from another database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    region: us-mia
+    engine: postgresql/16
+    type: g6-nanode-1
+    fork:
+        source: 12345
+    state: present''', '''
+- name: Delete a PostgreSQL database
+  linode.cloud.database_postgresql_v2:
+    label: my-db
+    state: absent''']
+
+result_database_samples = ['''{
+    "allow_list": [
+        "10.0.0.3/32"
+    ],
+    "cluster_size": 3,
+    "created": "2025-02-10T20:10:20",
+    "encrypted": true,
+    "engine": "postgresql",
+    "hosts": {
+        "primary": "a225891-akamai-prod-1798333-default.g2a.akamaidb.net",
+        "standby": "replica-a225891-akamai-prod-1798333-default.g2a.akamaidb.net"
+    },
+    "id": 12345,
+    "label": "my-db",
+    "members": {
+        "172.104.207.136": "primary",
+        "194.195.112.177": "failover",
+        "45.79.126.72": "failover"
+    },
+    "oldest_restore_time": "2025-02-10T20:15:07",
+    "platform": "rdbms-default",
+    "port": 11876,
+    "region": "ap-west",
+    "ssl_connection": true,
+    "status": "active",
+    "total_disk_size_gb": 30,
+    "type": "g6-standard-1",
+    "updated": "2025-02-10T20:25:55",
+    "updates": {
+        "day_of_week": 4,
+        "duration": 4,
+        "frequency": "weekly",
+        "hour_of_day": 16,
+        "pending": []
+    },
+    "used_disk_size_gb": 0,
+    "version": "8.0.35"
+}''']
+
+result_credentials_samples = ['''{
+  "password": "s3cur3P@ssw0rd",
+  "username": "akmadmin"
+}''']
+
+result_ssl_cert_samples = ['''{
+  "ca_certificate": "LS0tLS1CRUdJ...=="
+}''']
diff --git a/plugins/module_utils/linode_database_shared.py b/plugins/module_utils/linode_database_shared.py
@@ -77,11 +77,9 @@
     ),
     "frequency": SpecField(
         type=FieldType.string,
-        choices=["weekly", "monthly"],
+        choices=["weekly"],
         default="weekly",
-        description=[
-            "Whether maintenance occurs on a weekly or monthly basis."
-        ],
+        description=["The frequency at which maintenance occurs."],
     ),
     "hour_of_day": SpecField(
         type=FieldType.integer,

diff --git a/plugins/modules/database_mysql.py b/plugins/modules/database_mysql.py
@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-"""This module contains all of the functionality for Linode Images."""
+"""This module contains all of the functionality for Linode MySQL Database Clusters."""
 
 from __future__ import absolute_import, division, print_function
 

diff --git a/plugins/modules/database_mysql_info.py b/plugins/modules/database_mysql_info.py
@@ -1,7 +1,10 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-"""This module allows users to retrieve information about a Linode MySQL Managed Database."""
+"""
+This module allows users to retrieve information about a Linode MySQL Managed Database.
+NOTE: This module is compatible with Aiven-backed clusters.
+"""
 
 from __future__ import absolute_import, division, print_function
 

diff --git a/plugins/modules/database_postgresql.py b/plugins/modules/database_postgresql.py
@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-"""This module contains all of the functionality for Linode Images."""
+"""This module contains all of the functionality for Linode PostgreSQL Database Clusters."""
 
 from __future__ import absolute_import, division, print_function
 

diff --git a/plugins/modules/database_postgresql_info.py b/plugins/modules/database_postgresql_info.py
@@ -1,7 +1,10 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-"""This module allows users to retrieve information about a Linode PostgreSQL Managed Database."""
+"""
+This module allows users to retrieve information about a Linode PostgreSQL Managed Database.
+NOTE: This module is compatible with Aiven-backed clusters.
+"""
 
 from __future__ import absolute_import, division, print_function