diff --git a/plugins/modules/gcp_compute_instance_labels.py b/plugins/modules/gcp_compute_instance_labels.py
new file mode 100644
index 0000000..eed3873
--- /dev/null
+++ b/plugins/modules/gcp_compute_instance_labels.py
@@ -0,0 +1,329 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+#######################################################
+# Documentation
+#######################################################
+
+DOCUMENTATION = '''
+---
+module: gcp_compute_instance_labels
+short_description: Manages labels on a GCP Compute Instance in Google Cloud.
+version_added: "1.0"
+description:
+ - Manages labels of instances in GCP. It supports creating, updating,
+ merging, replacing, and purging labels based on the specified state.
+requirements:
+ - python >= 2.6
+ - google-auth >= 1.3.0
+ - requests >= 2.18.4
+options:
+ name:
+ description:
+ - The name of the compute instance to manage labels for.
+ required: true
+ type: str
+ labels:
+ description:
+ - A dictionary containing the labels to add or update on the instance.
+ Ignored if state is absent.
+ required: false
+ default: {}
+ type: dict
+ state:
+ description:
+ - Desired state of the labels. Use present (default one) to add or update
+ labels, absent to remove them.Also add state absent when purging.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ purge_labels:
+ description:
+ - Whether to remove all labels from the instance. Only effective when
+ state is 'absent'.
+ required: false
+ default: false
+ type: bool
+ mode:
+ description:
+ - Determines how labels are applied. merge will add or update labels
+ while keeping existing ones, replace will remove all existing
+ labels and add the new ones specified in labels.
+ choices: ['merge', 'replace']
+ default: 'merge'
+ type: str
+ project:
+ description:
+ - The GCP project ID where the compute instance is located.
+ required: true
+ type: str
+ zone:
+ description:
+ - The zone where the compute instance is located.
+ required: true
+ type: str
+author:
+ - Fernando Mendieta Ovejero (@valkiriaaquatica)
+notes:
+- for authentication, you can set service_account_file using
+ the C(GCP_SERVICE_ACCOUNT_FILE) env variable.
+- for authentication, you can set service_account_contents using
+ the C(GCP_SERVICE_ACCOUNT_CONTENTS) env variable.
+- For authentication, you can set service_account_email using
+ the C(GCP_SERVICE_ACCOUNT_EMAIL) env variable.
+- For authentication, you can set access_token using
+ the C(GCP_ACCESS_TOKEN) env variable.
+- For authentication, you can set auth_kind using
+ the C(GCP_AUTH_KIND) env variable.
+- For authentication, you can set scopes using
+ the C(GCP_SCOPES) env variable.
+- Environment variables values will only be used if
+ the playbook values are not set.
+- The I(service_account_email) and I(service_account_file)
+ options are mutually exclusive.
+'''
+
+EXAMPLES = '''
+ - name: Add new labels to a compute instance
+ gcp_compute_instance_label:
+ name: name_of_the_instance
+ labels:
+ env: production
+ department: marketing
+ state: present
+ project: your_project_name_or_id
+ zone: "europe-southwest1-a"
+ - name: Add new labels to a compute instance and remove the older labels
+ gcp_compute_instance_label:
+ name: name_of_the_instance
+ labels:
+ use: dev
+ department: finance
+ mode: "replace"
+ project: "123456789"
+ auth_kind: "serviceaccount"
+ state: present
+ project: your_project_name_or_id
+ zone: "europe-southwest1-a"
+ - name: Purge all labels from a compute instance
+ gcp_compute_instance_label:
+ name: name_of_the_instance
+ purge_labels: true
+ state: absent
+ project: your_project_name_or_id
+ zone: us-central1-a
+'''
+
+RETURN = '''
+instance:
+ description: Contains details about the compute engine instance
+ after the operation.
+ returned: on success
+ type: complex
+ contains:
+ id:
+ description: The unique ID of the operation.
+ type: str
+ sample: "12345678910"
+ insertTime:
+ description: The time when the instance operation was inserted.
+ type: str
+ sample: "2024-03-22T14:06:04.976-07:00"
+ kind:
+ description: The type of resource for the instance.
+ type: str
+ sample: "compute#operation"
+ name:
+ description: The name of the operation.
+ type: str
+ sample: "operation-1565615616-877585782-527852-7852"
+ operationType:
+ description: The type of operation performed on the instance.
+ type: str
+ sample: "compute.instance.setLabels"
+ progress:
+ description: The progress of the operation on the instance.
+ type: int
+ sample: 0
+ selfLink:
+ description: The link to the instance resource in the GCP API.
+ type: str
+ sample: "https://googleapis.com/compute/v1/../../zones/../operations/.."
+ startTime:
+ description: The start time of the operation on the instance.
+ type: str
+ sample: "2024-03-22T14:06:06.709-07:00"
+ status:
+ description: The current status of the compute instance.
+ type: str
+ sample: "RUNNING"
+ targetId:
+ description: The ID of the compute instance.
+ type: str
+ sample: "012345678910111213"
+ targetLink:
+ description: The link to the target resource of the operation on the
+ instance in GCP.
+ type: str
+ sample: "https://googleapis.com/compute/v1/../../zones/../instances/.."
+ user:
+ description: The user who initiated the operation on the instance.
+ type: str
+ sample: "email@email.com"
+ zone:
+ description: The zone of the Compute Engine instance where the operation
+ was performed.
+ type: str
+ sample: "https://googleapis.com/compute/v1/projects/../zones/.."
+'''
+
+from ansible_collections.google.cloud.plugins.module_utils.gcp_utils import (
+ GcpModule,
+ GcpSession,
+ remove_nones_from_dict,
+)
+
+################################################################################
+# Main
+################################################################################
+
+
+def main():
+ argument_spec = dict(
+ name=dict(required=True, type="str"),
+ labels=dict(required=False, type="dict", default={}),
+ state=dict(choices=["present", "absent"], default="present"),
+ purge_labels=dict(required=False, type="bool", default=False),
+ mode=dict(choices=["merge", "replace"], default="merge"),
+ project=dict(required=True, type="str"),
+ zone=dict(required=True, type="str"),
+ )
+
+ module = GcpModule(argument_spec=argument_spec, supports_check_mode=True)
+ validate_module_params(module)
+
+ session = GcpSession(module, "compute")
+ instance_details = fetch_instance_details(session, module.params["name"], module)
+
+ if module.params["state"] == "present":
+ result = manage_labels(
+ session,
+ instance_details,
+ module.params["labels"],
+ module,
+ is_purge=False,
+ mode=module.params["mode"],
+ )
+ elif module.params["purge_labels"]:
+ result = manage_labels(session, instance_details, {}, module, is_purge=True)
+ else: # state is absent
+ result = manage_labels(
+ session,
+ instance_details,
+ module.params["labels"],
+ module,
+ is_purge=False,
+ remove=True,
+ )
+
+ module.exit_json(**result)
+
+
+def validate_module_params(module):
+ if (
+ module.params["state"] == "present"
+ and not module.params.get("purge_labels")
+ and not module.params.get("labels")
+ ):
+ module.fail_json(
+ msg="'labels' is required when 'state' is present and 'purge_labels' if False."
+ )
+ if not module.params["scopes"]:
+ module.params["scopes"] = ["https://www.googleapis.com/auth/compute"]
+
+# gets details of the instance, mainly the labels
+def fetch_instance_details(session, instance_name, module):
+ url = (
+ f"https://compute.googleapis.com/compute/v1/projects/"
+ f"{module.params['project']}/zones/{module.params['zone']}/"
+ f"instances/{instance_name}"
+ )
+ response = session.get(url)
+ return (
+ response.json()
+ if response.ok
+ else module.fail_json(
+ msg=f"No se encontró la instancia con nombre {instance_name}"
+ )
+ )
+
+
+def manage_labels(
+ session,
+ instance_details,
+ labels,
+ module,
+ is_purge=False,
+ remove=False,
+ mode="merge",
+):
+ current_labels = instance_details.get("labels", {})
+ updated_labels = {}
+ msg = ""
+
+ # handles the mode logic when replace or purgeed
+ if mode == "replace" and not is_purge:
+ updated_labels = labels
+ msg = "Labels have been replaced."
+ elif is_purge:
+ if current_labels:
+ updated_labels = {}
+ msg = "All labels have been purged."
+ else:
+ return {"changed": False, "msg": "There were no labels to purge."}
+ elif remove:
+ updated_labels = {k: v for k, v in current_labels.items() if k not in labels}
+ if current_labels == updated_labels:
+ return {"changed": False, "msg": "The labels to be removed do not exist."}
+ else:
+ msg = "Specified labels have been removed."
+ else: # default to merge with the rest of labels
+ updated_labels = {**current_labels, **labels} if mode == "merge" else labels
+ if current_labels == updated_labels:
+ return {"changed": False, "msg": "The labels to be added already exist."}
+ else:
+ msg = "Specified labels have been added."
+
+ body = {
+ "labels": remove_nones_from_dict(updated_labels),
+ "labelFingerprint": instance_details["labelFingerprint"],
+ }
+ url = (
+ f"https://compute.googleapis.com/compute/v1/projects/"
+ f"{module.params['project']}/zones/{module.params['zone']}/"
+ f"instances/{instance_details['name']}/setLabels"
+ )
+ response = session.post(url, body=body)
+ return handle_response(
+ response, module, updated_labels=updated_labels, is_purge=is_purge
+ )
+
+# handles purge, add or delete actions
+def handle_response(response, module, updated_labels=None, is_purge=False):
+ if response.ok:
+ changed = (
+ True
+ if (is_purge and updated_labels == {})
+ else not response.json().get("labels") == updated_labels
+ )
+ return {"changed": changed, "instance": response.json()}
+ else:
+ module.fail_json(msg=f"Failed to modify labels: {response.text}")
+
+
+if __name__ == "__main__":
+ main()