path: root/ansible_collections/community/general/plugins/modules/ocapi_command.py

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright (c) 2022 Western Digital Corporation
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = '''
---
module: ocapi_command
version_added: 6.3.0
short_description: Manages Out-Of-Band controllers using Open Composable API (OCAPI)
description:
  - Builds OCAPI URIs locally and sends them to remote OOB controllers to
    perform an action.
  - Manages OOB controller such as Indicator LED, Reboot, Power Mode, Firmware Update.
extends_documentation_fragment:
  - community.general.attributes
attributes:
  check_mode:
    support: full
  diff_mode:
    support: none
options:
  category:
    required: true
    description:
      - Category to execute on OOB controller.
    type: str
  command:
    required: true
    description:
      - Command to execute on OOB controller.
    type: str
  baseuri:
    required: true
    description:
      - Base URI of OOB controller.
    type: str
  proxy_slot_number:
    description: For proxied inband requests, the slot number of the IOM.  Only applies if O(baseuri) is a proxy server.
    type: int
  update_image_path:
    required: false
    description:
      - For O(command=FWUpload), the path on the local filesystem of the firmware update image.
    type: str
  job_name:
    required: false
    description:
      - For O(command=DeleteJob) command, the name of the job to delete.
    type: str
  username:
    required: true
    description:
      - Username for authenticating to OOB controller.
    type: str
  password:
    required: true
    description:
      - Password for authenticating to OOB controller.
    type: str
  timeout:
    description:
      - Timeout in seconds for URL requests to OOB controller.
    default: 10
    type: int

author: "Mike Moerk (@mikemoerk)"
'''

EXAMPLES = '''
  - name: Set the power state to low
    community.general.ocapi_command:
      category: Chassis
      command: PowerModeLow
      baseuri: "{{ baseuri }}"
      username: "{{ username }}"
      password: "{{ password }}"

  - name: Set the power state to normal
    community.general.ocapi_command:
      category: Chassis
      command: PowerModeNormal
      baseuri: "{{ baseuri }}"
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Set chassis indicator LED to on
    community.general.ocapi_command:
      category: Chassis
      command: IndicatorLedOn
      baseuri: "{{ baseuri }}"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Set chassis indicator LED to off
    community.general.ocapi_command:
      category: Chassis
      command: IndicatorLedOff
      baseuri: "{{ baseuri }}"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Reset Enclosure
    community.general.ocapi_command:
      category: Systems
      command: PowerGracefulRestart
      baseuri: "{{ baseuri }}"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Firmware Upload
    community.general.ocapi_command:
      category: Update
      command: FWUpload
      baseuri: "iom1.wdc.com"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
      update_image_path: "/path/to/firmware.tar.gz"
  - name: Firmware Update
    community.general.ocapi_command:
      category: Update
      command: FWUpdate
      baseuri: "iom1.wdc.com"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Firmware Activate
    community.general.ocapi_command:
      category: Update
      command: FWActivate
      baseuri: "iom1.wdc.com"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
  - name: Delete Job
    community.general.ocapi_command:
      category: Jobs
      command: DeleteJob
      job_name: FirmwareUpdate
      baseuri: "{{ baseuri }}"
      proxy_slot_number: 2
      username: "{{ username }}"
      password: "{{ password }}"
'''

RETURN = '''
msg:
    description: Message with action result or error description.
    returned: always
    type: str
    sample: "Action was successful"

jobUri:
    description: URI to use to monitor status of the operation.  Returned for async commands such as Firmware Update, Firmware Activate.
    returned: when supported
    type: str
    sample: "https://ioma.wdc.com/Storage/Devices/openflex-data24-usalp03020qb0003/Jobs/FirmwareUpdate/"

operationStatusId:
    description: OCAPI State ID (see OCAPI documentation for possible values).
    returned: when supported
    type: int
    sample: 2

'''

from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ocapi_utils import OcapiUtils
from ansible.module_utils.common.text.converters import to_native
from ansible.module_utils.six.moves.urllib.parse import urljoin

# More will be added as module features are expanded
CATEGORY_COMMANDS_ALL = {
    "Chassis": ["IndicatorLedOn", "IndicatorLedOff", "PowerModeLow", "PowerModeNormal"],
    "Systems": ["PowerGracefulRestart"],
    "Update": ["FWUpload", "FWUpdate", "FWActivate"],
    "Jobs": ["DeleteJob"]
}


def main():
    result = {}
    module = AnsibleModule(
        argument_spec=dict(
            category=dict(required=True),
            command=dict(required=True, type='str'),
            job_name=dict(type='str'),
            baseuri=dict(required=True, type='str'),
            proxy_slot_number=dict(type='int'),
            update_image_path=dict(type='str'),
            username=dict(required=True),
            password=dict(required=True, no_log=True),
            timeout=dict(type='int', default=10)
        ),
        supports_check_mode=True
    )

    category = module.params['category']
    command = module.params['command']

    # admin credentials used for authentication
    creds = {
        'user': module.params['username'],
        'pswd': module.params['password']
    }

    # timeout
    timeout = module.params['timeout']

    base_uri = "https://" + module.params["baseuri"]
    proxy_slot_number = module.params.get("proxy_slot_number")
    ocapi_utils = OcapiUtils(creds, base_uri, proxy_slot_number, timeout, module)

    # Check that Category is valid
    if category not in CATEGORY_COMMANDS_ALL:
        module.fail_json(msg=to_native("Invalid Category '%s'. Valid Categories = %s" % (category, list(CATEGORY_COMMANDS_ALL.keys()))))

    # Check that the command is valid
    if command not in CATEGORY_COMMANDS_ALL[category]:
        module.fail_json(msg=to_native("Invalid Command '%s'. Valid Commands = %s" % (command, CATEGORY_COMMANDS_ALL[category])))

    # Organize by Categories / Commands
    if category == "Chassis":
        if command.startswith("IndicatorLed"):
            result = ocapi_utils.manage_chassis_indicator_led(command)
        elif command.startswith("PowerMode"):
            result = ocapi_utils.manage_system_power(command)
    elif category == "Systems":
        if command.startswith("Power"):
            result = ocapi_utils.manage_system_power(command)
    elif category == "Update":
        if command == "FWUpload":
            update_image_path = module.params.get("update_image_path")
            if update_image_path is None:
                module.fail_json(msg=to_native("Missing update_image_path."))
            result = ocapi_utils.upload_firmware_image(update_image_path)
        elif command == "FWUpdate":
            result = ocapi_utils.update_firmware_image()
        elif command == "FWActivate":
            result = ocapi_utils.activate_firmware_image()
    elif category == "Jobs":
        if command == "DeleteJob":
            job_name = module.params.get("job_name")
            if job_name is None:
                module.fail_json("Missing job_name")
            job_uri = urljoin(base_uri, "Jobs/" + job_name)
            result = ocapi_utils.delete_job(job_uri)

    if result['ret'] is False:
        module.fail_json(msg=to_native(result['msg']))
    else:
        del result['ret']
        changed = result.get('changed', True)
        session = result.get('session', dict())
        kwargs = {
            "changed": changed,
            "session": session,
            "msg": "Action was successful." if not module.check_mode else result.get(
                "msg", "No action performed in check mode."
            )
        }
        result_keys = [result_key for result_key in result if result_key not in kwargs]
        for result_key in result_keys:
            kwargs[result_key] = result[result_key]
        module.exit_json(**kwargs)


if __name__ == '__main__':
    main()