feat: add module for setting LB backend member weight

kangasta · kangasta · commit a1672dcf59ac · 2025-11-21T18:16:09.000+02:00
diff --git a/.github/workflows/build-and-release.yml b/.github/workflows/build-and-release.yml
@@ -27,7 +27,11 @@ jobs:
         run: pip install https://github.com/ansible/ansible/archive/${{env.ANSIBLE_VERSION}}.tar.gz --disable-pip-version-check
 
       - name: Build project release
-        run: mkdir release && ansible-galaxy collection build --output-path release/
+        run: |
+          version=$(grep "version" galaxy.yml | sed -E "s/version:\s+//")
+          test "${{ github.ref_name }}" = "v$version"
+          sed -E "s/(VERSION\s+=\s+).*/\1\"$version\"/" -i plugins/module_utils/client.py
+          mkdir release && ansible-galaxy collection build --output-path release/
 
       - name: Create new release
         uses: ncipollo/release-action@v1.16.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Experimental support for managing load balancer backend member weights.
+
+### Changed
+
+- Use `upcloud-ansible-collection` as prefix in the User-Agent header.
+
 ## [0.8.1] - 2025-09-04
 
 ### Fixed
diff --git a/examples/inventory-rolling-update/.gitignore b/examples/inventory-rolling-update/.gitignore
@@ -0,0 +1 @@
+variables.yml
diff --git a/examples/inventory-rolling-update/README.md b/examples/inventory-rolling-update/README.md
@@ -22,10 +22,10 @@ Configure a NGINX server with static web page by running the [configure-webserve
 
 ```sh
 # For initial configuration, configure all targets in parallel
-ansible-playbook configure-webserver.yml --extra-vars "serial_override=0"
+ansible-playbook configure-webserver.yml --extra-vars "@variables.yml" --extra-vars "serial_override=0"
 
 # When updating the targets, specify which tag (cow, dog, hello, or tiger) to use
-ansible-playbook configure-webserver.yml --extra-vars "animal=tiger"
+ansible-playbook configure-webserver.yml --extra-vars "@variables.yml" --extra-vars "animal=tiger"
 ```
 
 To monitor how the rolling update proceeds, open another terminal window and curl the load-balancer URL. The URL is visible at the output of prevous `terraform apply` command and can be printed by running `terraform output`.
diff --git a/examples/inventory-rolling-update/configure-webserver.yml b/examples/inventory-rolling-update/configure-webserver.yml
@@ -6,6 +6,17 @@
   vars:
     animal: cow
   tasks:
+    - name: Remove from load balancing
+      upcloud.cloud.loadbalancer_backend_member:
+        loadbalancer_uuid: "{{ loadbalancer_uuid }}"
+        backend_name: main
+        member_name: "member_{{ ansible_facts.hostname[-1:] }}"
+        weight: 0
+      when:
+      - serial_override|default(1)|int != 0
+      - loadbalancer_uuid is defined
+      delegate_to: localhost
+      become: false
     - name: Install nginx
       apt:
         package: nginx
@@ -48,6 +59,17 @@
         replace: '80'
       notify:
         - Restart nginx
+    - name: Add back to load balancing
+      upcloud.cloud.loadbalancer_backend_member:
+        loadbalancer_uuid: "{{ loadbalancer_uuid }}"
+        backend_name: main
+        member_name: "member_{{ ansible_facts.hostname[-1:] }}"
+        weight: 100
+      when:
+      - serial_override|default(1)|int != 0
+      - loadbalancer_uuid is defined
+      delegate_to: localhost
+      become: false
   handlers:
     - name: Restart nginx
       service:
diff --git a/examples/inventory-rolling-update/resources/main.tf b/examples/inventory-rolling-update/resources/main.tf
@@ -93,3 +93,7 @@ module "load_balancer" {
 output "lb_url" {
   value = module.load_balancer.dns_name
 }
+
+output "lb_uuid" {
+  value = module.load_balancer.id
+}
diff --git a/plugins/inventory/servers.py b/plugins/inventory/servers.py
@@ -130,12 +130,11 @@
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
 from ansible.utils.display import Display
 
-from ..version import collection_version
+from ..module_utils.client import initialize_upcloud_client
 
 display = Display()
 
 try:
-    import upcloud_api
     from upcloud_api.errors import UpCloudAPIError
     UC_AVAILABLE = True
 except ImportError:
@@ -164,37 +163,7 @@ def _initialize_upcloud_client(self):
             self.token_env
         )
 
-        # Token support was added in upcloud-api 2.8.0, older versions will raise TypeError if token is provided.
-        # Ignore the error if token is not provided, in which case older version should work as well.
-        try:
-            credentials = upcloud_api.Credentials.parse(
-                username=self.username,
-                password=self.password,
-                token=self.token,
-            )
-            self.client = upcloud_api.CloudManager(**credentials.dict)
-        except (AttributeError, TypeError):
-            try:
-                self.client = upcloud_api.CloudManager(self.username, self.password)
-            except Exception:
-                raise AnsibleError(
-                    'Invalid or missing UpCloud API credentials. '
-                    'The version of upcloud-api you are using does not support token authentication or parsing credentials from the environment. '
-                    'Update upcloud-api to version 2.8.0 or later.'
-                ) from None
-
-        version = collection_version() or "dev"
-        self.client.api.user_agent = f"upcloud-ansible-inventory/{version}"
-
-        api_root_env = "UPCLOUD_API_ROOT"
-        if os.getenv(api_root_env):
-            self.client.api.api_root = os.getenv(api_root_env)
-
-    def _test_upcloud_credentials(self):
-        try:
-            self.client.authenticate()
-        except UpCloudAPIError:
-            raise AnsibleError("Invalid UpCloud API credentials.")
+        self.client = initialize_upcloud_client(self.username, self.password, self.token)
 
     def _fetch_servers(self):
         return self.client.get_servers()
@@ -386,7 +355,6 @@ def verify_file(self, path):
 
     def _populate(self):
         self._initialize_upcloud_client()
-        self._test_upcloud_credentials()
         self._get_servers()
         self._filter_servers()
 
diff --git a/plugins/module_utils/__init__.py b/plugins/module_utils/__init__.py
diff --git a/plugins/module_utils/client.py b/plugins/module_utils/client.py
@@ -0,0 +1,52 @@
+import os
+
+try:
+    import upcloud_api
+    from upcloud_api.errors import UpCloudAPIError
+    UC_AVAILABLE = True
+except ImportError:
+    UC_AVAILABLE = False
+
+
+# This value will be replaced in build-and-release workflow
+VERSION = "dev"
+
+
+def initialize_upcloud_client(username=None, password=None, token=None):
+    if not UC_AVAILABLE:
+        raise RuntimeError(
+            "UpCloud Ansible collection requires upcloud-api Python module, "
+            + "see https://pypi.org/project/upcloud-api/")
+
+    # Token support was added in upcloud-api 2.8.0, older versions will raise TypeError if token is provided.
+    # Ignore the error if token is not provided, in which case older version should work as well.
+    try:
+        credentials = upcloud_api.Credentials.parse(
+            username=username,
+            password=password,
+            token=token,
+        )
+        client = upcloud_api.CloudManager(**credentials.dict)
+    except (AttributeError, TypeError):
+        try:
+            client = upcloud_api.CloudManager(username, password)
+        except Exception:
+            raise RuntimeError(
+                'Invalid or missing UpCloud API credentials. '
+                'The version of upcloud-api you are using does not support token authentication or parsing credentials from the environment. '
+                'Update upcloud-api to version 2.8.0 or later.'
+            ) from None
+
+    version = VERSION
+    client.api.user_agent = f"upcloud-ansible-collection/{version}"
+
+    api_root_env = "UPCLOUD_API_ROOT"
+    if os.getenv(api_root_env):
+        client.api.api_root = os.getenv(api_root_env)
+
+    try:
+        client.authenticate()
+    except UpCloudAPIError:
+        raise RuntimeError("Invalid UpCloud API credentials.")
+
+    return client
diff --git a/plugins/modules/__init__.py b/plugins/modules/__init__.py
diff --git a/plugins/modules/loadbalancer_backend_member.py b/plugins/modules/loadbalancer_backend_member.py
@@ -0,0 +1,163 @@
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: loadbalancer_backend_member
+version_added: "0.9.0"
+short_description: Manage UpCloud load balancer backend members
+description:
+    - Modify UpCloud load balancer backend members.
+    - Currently only supports updating the weight of a existing backend member.
+options:
+    loadbalancer_uuid:
+        description:
+            - UUID of the load balancer.
+        required: true
+        type: str
+    backend_name:
+        description:
+            - Name of the backend.
+        required: true
+        type: str
+    member_name:
+        description:
+            - Name of the backend member.
+            - Either member_name or ip_address must be provided.
+        required: false
+        type: str
+    ip_address:
+        description:
+            - IP address of the backend member.
+            - Either member_name or ip_address must be provided.
+        required: false
+        type: str
+    weight:
+        description:
+            - Weight of the backend member (0-100) relative to other members.
+            - All members will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load.
+            - A value of 0 means the member will not participate in load balancing but will still accept persistent connections.
+        required: true
+        type: int
+
+author:
+    - UpCloud (@UpCloudLtd)
+'''
+
+EXAMPLES = '''
+- name: Disable new connections before starting maintenance
+  loadbalancer_backend_member:
+    loadbalancer_uuid: your-loadbalancer-uuid
+    backend_name: your-backend-name
+    member_name: your-member-name
+    weight: 0
+
+- name: Enable new connections after maintenance has been completed
+  loadbalancer_backend_member:
+    loadbalancer_uuid: your-loadbalancer-uuid
+    backend_name: your-backend-name
+    member_name: your-member-name
+    weight: 100
+'''
+
+RETURN = '''
+loadbalancer_backend_member:
+    description:
+        - Loadbalancer backend member details.
+    returned: always
+    type: dict
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.upcloud.cloud.plugins.module_utils.client import initialize_upcloud_client
+
+try:
+    from upcloud_api.errors import UpCloudAPIError
+except ImportError:
+    pass
+
+
+class LoadBalancerBackendMember:
+    def __init__(self, loadbalancer_uuid=None, backend_name=None, member_name=None, ip_address=None):
+        self.client = initialize_upcloud_client()
+
+        self.loadbalancer_uuid = loadbalancer_uuid
+        self.backend_name = backend_name
+        self.member_name = member_name
+        self.ip_address = ip_address
+        self.weight = None
+
+        if self.member_name is None and self.ip_address is None:
+            raise ValueError('Either member_name or ip_address must be provided.')
+
+        self.details = dict()
+
+    @property
+    def _url(self):
+        return f'/load-balancer/{self.loadbalancer_uuid}/backends/{self.backend_name}/members/{self.member_name}'
+
+    def _get_by_ip(self):
+        members = self.client.api.get_request(f'/load-balancer/{self.loadbalancer_uuid}/backends/{self.backend_name}/members')
+        for member in members:
+            if member.get('ip_address') == self.ip_address:
+                self.member_name = member.get('name')
+                return member
+        raise ValueError(f'Backend member with IP address {self.ip_address} not found.')
+
+    def read(self):
+        if self.member_name is None:
+            self.details = self._get_by_ip()
+        else:
+            self.details = self.client.api.get_request(self._url)
+        self.weight = int(self.details.get('weight'))
+
+    def update(self, weight):
+        payload = {
+            'weight': weight
+        }
+        self.details = self.client.api.patch_request(self._url, payload)
+        self.weight = weight
+
+
+def main():
+    argument_spec = dict(
+        loadbalancer_uuid=dict(type='str', required=True),
+        backend_name=dict(type='str', required=True),
+        member_name=dict(type='str', required=False),
+        ip_address=dict(type='str', required=False),
+        weight=dict(type='int', required=True),
+    )
+
+    result = dict(
+        changed=False,
+        loadbalancer_backend_member={},
+    )
+
+    module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True)
+
+    member = LoadBalancerBackendMember(
+        loadbalancer_uuid=module.params.get('loadbalancer_uuid'),
+        backend_name=module.params.get('backend_name'),
+        member_name=module.params.get('member_name'),
+        ip_address=module.params.get('ip_address'),
+    )
+    try:
+        result['loadbalancer_backend_member'] = member.read()
+    except (UpCloudAPIError, ValueError) as e:
+        module.fail_json(msg=str(e))
+
+    weight = module.params.get('weight')
+    if member.weight != weight:
+        try:
+            result['loadbalancer_backend_member'] = member.update(weight)
+        except UpCloudAPIError as e:
+            module.fail_json(msg=str(e))
+        result["changed"] = True
+    else:
+        result["changed"] = False
+
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/plugins/version.py b/plugins/version.py
diff --git a/tests/sanity/ignore-2.18.txt b/tests/sanity/ignore-2.18.txt
@@ -1 +1,2 @@
 plugins/inventory/servers.py validate-modules:missing-gplv3-license
+plugins/modules/loadbalancer_backend_member.py validate-modules:missing-gplv3-license
diff --git a/tests/sanity/ignore-2.19.txt b/tests/sanity/ignore-2.19.txt
@@ -1 +1,2 @@
 plugins/inventory/servers.py validate-modules:missing-gplv3-license
+plugins/modules/loadbalancer_backend_member.py validate-modules:missing-gplv3-license
diff --git a/tests/sanity/ignore-2.20.txt b/tests/sanity/ignore-2.20.txt
@@ -1 +1,2 @@
 plugins/inventory/servers.py validate-modules:missing-gplv3-license
+plugins/modules/loadbalancer_backend_member.py validate-modules:missing-gplv3-license

Original file line number	Diff line number	Diff line change
`@@ -93,3 +93,7 @@ module "load_balancer" {`
`93`	`93`	`output "lb_url" {`
`94`	`94`	`value = module.load_balancer.dns_name`
`95`	`95`	`}`
	`96`	`+`
	`97`	`+output "lb_uuid" {`
	`98`	`+ value = module.load_balancer.id`
	`99`	`+}`