Skip to content
This repository has been archived by the owner on Jun 10, 2024. It is now read-only.

VMware: HTTPAPI connection plugin

Jump to bottom
n3pjk edited this page Jun 18, 2019 · 97 revisions

VMware ReST HTTPAPI Design Specification

Overview

This document describes the design philosophy, milestones and objectives to create a VMware ecosystem based on the new ReST API introduced in vSphere 6.x, using the HTTPAPI connection plugin, developed by Ansible's Networking Team. We will be listing all ReST API related requirements. Feel free to edit this page.

Requirements

  • Develop a REST API infrastructure in Ansible for dealing with VMware infrastructure
  • Develop guidelines, design specifications with community to drive this effort
  • Write documentation for installation and user scenarios for httpapi plugin
  • Try to target modules related to Content library, tagging etc. as part of this effort
  • Develop a role like network-engine for Ansible VMware
  • Unit testing for VMware REST API infrastructure.
  • Create a Mock server in Flask or something as GOVCSIM does not support REST APIs

General

  1. GET or queries will default to retrieve multiple objects if the filter specs warrant it.
  2. Any other command, such as PUT, POST, PATCH or DELETE, or any state other than query, such as 'present' or 'absent', will default to assert a single object.
  3. Should filter specs result in an operand of more objects than asserted, the command will fail.
  4. Setting 'allow_multiples' to True will force that command to allow processing of multiple objects.
  5. The new module library will be divided into sections loosely based on VMware's PowerCLI library, originally laid out in Vmware Vsphere Powercli Reference: Automating Vsphere Administration, second edition, January 2016, by Luc Dekens, Alan Renouf, Jonathan Medd, et al.
  6. Each section will be maintained in its own directory.
  7. Variables with an 'id' suffix, [OBJECT]_id, contain VMware's internal object id name, e.g. cluster_id. The value of these variables can be used directly in an API request.
  8. Variables with a 'name' suffix, [OBJECT]_name, contain the display name of the object, e.g. cluster_name. The value of these variables will usually require a lookup to obtain VMware's corresponding internal object id. Such look ups returning multiple ids is where the 'allow_multiples' assert comes into play.
  9. Filters are specified as filter.[OBJECT][SUFFIX], e.g. filter.cluster_id filters on VMware's internal object id, while filter.cluster_name filters on the cluster's display name.
  10. Filters by name will have to make additional calls to convert name to one or more internal id's.

Library

Core

This section provides direct implementation of VMware ReST API commands. Consists of a single module that implements all APIs, and multiple modules that each implement all relevant commands for a single API entity, as specified by VMware's Swagger document. Multiple related API entities may be combined into a single module if deemed more efficient. It is recommended that the individual modules simply parse their params and pass to vmware_commands for execution to minimize redundant coding. The modules are

  • vmware_commands
    • implements all VMware ReSTful APIs
    • commands can be placed into a list to be executed in order
    • commands are of the form [COMMAND] [API] [OBJECT] [ACTION] [param:value]...
      • COMMAND is one of GET, PATCH, POST, PUT, or DELETE
      • API is one of APPLIANCE, CIS, CONTENT, VAPI, or VCENTER
      • OBJECT is a valid API entity defined in VMware's Swagger document
      • ACTION is an optional field usually required for a PATCH, POST or PUT
      • Optional parameters can be specified as colon-separated name-value pairs
    • relevant filters and modifiers can be specified per command
    • supports all command filters and modifiers
  • vmware_appliance_access
    • implements
      • /appliance/access/consolecli
      • /appliance/access/dcui
      • /appliance/access/shell
      • /appliance/access/ssh
    • commands
      • PUT
    • params
      • consolecli: bool
      • dcui: bool
      • shell: bool
      • ssh: bool
  • vmware_appliance_access_facts
    • implements
      • /appliance/access/consolecli
      • /appliance/access/dcui
      • /appliance/access/shell
      • /appliance/access/ssh
    • commands
      • GET
  • vmware_appliance_health_facts
    • implements
      • /appliance/health
      • /appliance/health/applmgmt
      • /appliance/health/databasestorage
      • /appliance/health/load
      • /appliance/health/mem
      • /appliance/health/softwarepackages
      • /appliance/health/storage
      • /appliance/health/swap
      • /appliance/health/system
      • /appliance/health/system/lastcheck
    • commands
      • GET
  • vmware_appliance_accounts
    • implements /appliance/local-accounts
    • commands
      • PATCH
      • PUT
      • POST
      • DELETE
    • params
      • config:
        • max_days_between_password_change: int
        • inactive_after_password_expiration: bool
        • days_after_password_expiration: int
        • password_expires: bool
        • full_name: string
        • email: string
        • enabled: bool
        • roles: [ string ]
        • password: string
        • password_expires_at: datetime
        • old_password: string
        • warn_days_before_password_expiration: int
        • min_days_between_password_change: int
      • username: string
      • state: one of ['present', 'absent']
  • vmware_appliance_accounts_facts
    • implements /appliance/local-accounts
    • commands
      • GET
    • params
      • username: string
  • vmware_appliance_accounts_policy
    • implements /appliance/local-accounts/global-policy
    • commands
      • PUT
    • params
      • policy:
        • max_days: int
        • warn_days: int
        • min_days: int
  • vmware_appliance_accounts_policy_facts
    • implements /appliance/local-accounts/global-policy
    • commands
      • GET
  • vmware_appliance_logging
    • implements /appliance/logging/forwarding
    • commands
      • PUT
      • POST
    • actions
      • test
    • params
      • cfg_list: array of
        • hostname: string
        • port: int
        • protocol: one of ['TLS']
      • send_test_message: string
  • vmware_appliance_logging_facts
    • implements /appliance/logging/forwarding
    • commands
      • GET
  • vmware_appliance_monitoring_facts
    • implements
      • /appliance/monitoring
      • /appliance/monitoring/query
    • commands
      • GET
    • params
      • stat_id or stat_name: string
      • query: bool
  • vmware_appliance_networking
    • implements
      • /appliance/networking
      • /appliance/networking/dns/domains
      • /appliance/networking/dns/hostname
      • /appliance/networking/dns/hostname/test
      • /appliance/networking/dns/servers
      • /appliance/networking/dns/servers/test
      • /appliance/networking/firewall/inbound
      • /appliance/networking/interfaces
      • /appliance/networking/interfaces/ipv4
      • /appliance/networking/interfaces/ipv6
      • /appliance/networking/noproxy
      • /appliance/networking/proxy
    • commands
      • PATCH
      • PUT
      • POST
      • DELETE
    • actions
      • reset
      • test
    • params
      • ipv6_enabled: bool
      • dns_test: bool
        • sets both hostname_test and servers_test
      • domain: string
      • domains: [ string ]
      • hostname: string
      • hostname_test: bool
      • interface_name: string
        • prefix: int
        • address: string
        • default_gateway: string
        • mode: one of ['DHCP', 'STATIC']
      • interface_name: string
        • addresses: array of
          • prefix: int
          • address: string
        • dhcp: bool
        • default_gateway: string
        • autoconf: bool
      • protocol: string
        • server: string
        • enabled: bool
        • port: int
        • password: string
        • username: string
      • proxy_test: bool
      • reset: bool
      • rules: array of
        • policy: one of ['accept', 'deny', 'ignore']
        • prefix: int
        • address: string
        • interface_name: string
      • server: string
      • servers: [ string ]
      • servers_config:
        • servers: [ string ]
        • mode: 'dhcp'
      • servers_test: bool
  • vmware_appliance_networking_facts
    • implements
      • /appliance/networking
      • /appliance/networking/dns/domains
      • /appliance/networking/dns/hostname
      • /appliance/networking/dns/servers
      • /appliance/networking/firewall/inbound
      • /appliance/networking/interfaces
      • /appliance/networking/interfaces/ipv4
      • /appliance/networking/interfaces/ipv6
      • /appliance/networking/noproxy
      • /appliance/networking/proxy
    • commands
      • GET
    • params
      • protocol: string
  • vmware_appliance_ntp
    • implements
      • /appliance/ntp
      • /appliance/ntp/test
    • commands
      • PUT
      • POST
    • params
      • servers: [ string ]
  • vmware_appliance_ntp_facts
    • implements /appliance/ntp
    • commands
      • GET
  • vmware_appliance_recovery
    • implements
      • /appliance/recovery/backup/job
      • /appliance/recovery/backup/schedules
      • /appliance/recovery/backup/schedules/update
      • /appliance/recovery/reconciliation/job
      • /appliance/recovery/restore/job
    • commands
      • PUT
      • POST
      • DELETE
    • actions
      • run
    • params
      • job_id: string
      • backup_piece:
        • location: string
        • parts: [ string ]
        • location_password: string
        • comment: string
        • location_type: one of ['FTP']
        • backup_password: string
        • location_user: string
      • reconciliation_job:
        • ignore_warning: bool
        • sso_admin_user_password: string
        • sso_admin_user_name: string
      • restore_piece:
        • ignore_warnings: bool
        • sso_admin_user_password: string
        • location: string
        • location_password: string
        • sso_admin_user_name: string
        • location_type: one of ['FTP']
        • backup_password: string
        • location_user: string
      • schedule: string
        • location: string
        • parts: [ string ]
        • location_password: string
        • max_count: int
        • enable: bool
        • recurrence_info:
          • days: ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']
          • minute: int[0:59]
          • hour: int[0:23]
        • location_user: string
      • state: one of ['present', 'absent']
  • vmware_appliance_recovery_facts
    • implements
      • /appliance/recovery
      • /appliance/recovery/backup/validate
      • /appliance/recovery/backup/job
      • /appliance/recovery/backup/job/details
      • /appliance/recovery/backup/parts
      • /appliance/recovery/backup/schedules
      • /appliance/recovery/backup/system-name
      • /appliance/recovery/backup/reconciliation/job
      • /appliance/recovery/restore/validate
      • /appliance/recovery/restore/job
    • commands
      • GET
      • POST
    • params
      • job_id: string
      • parts_id: string
      • schedule: string
      • system_name: string
      • archive: string
  • vmware_appliance_services
    • implements /appliance/services
    • commands
      • POST
    • params
      • service_id or service_name: string
      • state: one of ['present', 'absent']
    • if service is running and state is 'present', then restart
    • alternatively, always restart when state is 'present'
  • vmware_appliance_services_facts
    • implements /appliance/services
    • commands
      • GET
    • params
      • service_id or service_name: string
  • vmware_appliance_shutdown
    • implements
      • /appliance/shutdown/cancel
      • /appliance/shutdown/poweroff
      • /appliance/shutdown/reboot
    • commands
      • POST
  • vmware_appliance_shutdown_facts
    • implements /appliance/shutdown
    • commands
      • GET
  • vmware_appliance_system
    • implements
      • /appliance/system/storage
      • /appliance/system/storage/resize
      • /appliance/system/time/timezone
      • /appliance/timesync
    • commands
      • POST
      • PUT
    • actions
      • resize-ex
    • params
      • timezone_name: string
      • timesync_mode: one of ['ENABLED', 'DISABLED']
  • vmware_appliance_system_facts
    • implements
      • /appliance/system/storage
      • /appliance/system/time
      • /appliance/system/time/timezone
      • /appliance/system/uptime
      • /appliance/system/version
      • /appliance/timesync
    • commands
      • GET
  • vmware_appliance_techpreview
    • implements
      • /appliance/techpreview/monitoring/snmp
      • /appliance/techpreview/monitoring/snmp/disable
      • /appliance/techpreview/monitoring/snmp/enable
      • /appliance/techpreview/monitoring/snmp/hash
      • /appliance/techpreview/monitoring/snmp/reset
      • /appliance/techpreview/monitoring/snmp/test
    • commands
      • PUT
      • POST
    • params
      • snmp: one of ['DISABLE', 'ENABLE', 'HASH', 'RESET', 'TEST']
  • vmware_appliance_techpreview_facts
    • implements
      • /appliance/techpreview/monitoring/snmp
      • /appliance/techpreview/monitoring/snmp/limits
      • /appliance/techpreview/monitoring/snmp/stats
      • /appliance/techpreview/services/status/get
    • commands
      • GET
      • POST
  • vmware_appliance_update
    • implements
      • /appliance/update
      • /appliance/update/pending
    • commands
      • POST
      • PUT
      • DELETE
    • actions
      • cancel
      • install
      • precheck
      • stage
      • stage-and-install
      • validate
    • params
      • version: string
      • user_data: [ [key]: [value] ] for 'install' action
      • policy:
        • custom_url: string
        • auto_storage: bool
        • check_schedule:
          • day: ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']
          • hour: int
          • minute: int
        • password: string
        • username: string
  • vmware_appliance_update_facts
    • implements
      • /appliance/update
      • /appliance/update/pending
      • /appliance/update/policy
      • /appliance/update/staged
    • commands
      • GET
    • params
      • version: string
  • vmware_appliance_vmon
    • implements /appliance/vmon/service
    • commands
      • PATCH
      • POST
    • params
      • service_id or service_name: string
      • startup_type: one of ['AUTOMATIC', 'MANUAL']
      • state: one of ['present', 'absent']
      • if service is running, send restart on 'present' or always send 'restart'
  • vmware_appliance_vmon_facts
    • implements /appliance/vmon/service
    • commands
      • GET
    • params
      • service_id or service_name: string
  • vmware_cis_category
    • implements /com/vmware/cis/tagging/category
    • commands
      • PATCH
      • POST
      • DELETE
    • actions
      • add-to-used-by
      • remove-from-used-by
      • revoke-propagating-permissions
    • params
      • category_id or category_name: string
      • description: string
      • cardinality: one of ['SINGLE', 'MULTIPLE']
      • associable_types: ['All', 'Clusters', 'Content Libraries', 'Datacenters', 'Datastores', 'Datastore Clusters', 'Distributed Port Groups', 'Distributed Switches', 'Folders', 'Hosts', 'Library Items', 'Networks', 'Resource Pools', 'vApps', 'Virtual Machines']
      • used_by_entity_id or used_by_entity_name: string
      • state: one of ['present', 'absent']
  • vmware_cis_category_facts
    • implements /com/vmware/cis/tagging/category
    • commands
      • GET
      • POST
    • actions
      • list-used-categories
    • params
      • category_id or category_name: string
      • used_by_entity_id or used_by_entity_name: string
  • vmware_cis_session
    • implements /com/vmware/cis/session
    • commands
      • POST
      • DELETE
    • params
      • state: one of ['present', 'absent']
    • this is primarily what the VMware plugin to HTTPAPI uses to log in and out
  • vmware_cis_session_facts
    • implements /com/vmware/cis/session
    • commands
      • POST
    • actions
      • get
    • the only relevant action may be to retrieve the current session information
  • vmware_cis_tag
    • implements /com/vmware/cis/tagging/tag
    • commands
      • PATCH
      • POST
      • DELETE
    • actions
      • add-to-used-by
      • remove-from-used-by
      • revoke-propagating-permissions
    • params
      • tag_id or tag_name: string
      • name: string
      • category_id or category_name: string
      • description: string
      • used_by_entity_id or used_by_entity_name: string
      • state: one of ['present', 'absent', 'revoked']
  • vmware_cis_tag_facts
    • implements /com/vmware/cis/tagging/tag
    • commands
      • GET
      • POST
    • actions
      • list-used-tags
      • list-tags-for-category
    • params
      • tag_id or tag_name: string
      • used_by_entity_id or used_by_entity_name: string
  • vmware_cis_tag_association
    • implements /com/vmware/cis/tagging/tag_association
    • commands
      • POST
    • actions
      • attach-multiple-tags-to-object
      • detach-multiple-tags-from-object
      • attach
      • attach-tag-to-multiple-objects
      • detach
      • detach-tag-from-multiple-objects
    • params
      • tag_id or tag_name: string
      • object_id:
        • id: string
        • type: string
      • object_name: string
  • vmware_cis_tag_association_facts
    • implements /com/vmware/cis/tagging/tag_association
    • commands
      • POST
    • actions
      • list-attachable-tags
      • list-attached-objects-on-tags
      • list-attached-tags
      • list-attached-tags-on-objects
      • list-attached-objects
    • params
      • tag_id or tag_name: string
      • tag_ids: [ string ]
      • object_id:
        • id: string
        • type: string
      • object_name: string
  • vmware_cis_tasks
    • implements /cis/tasks
    • commands
      • POST
    • actions
      • cancel
    • params
      • task_id: string
  • vmware_cis_tasks_facts
    • implements /cis/tasks
    • commands
      • GET
    • params
      • task_id: string
  • vmware_content_configuration
  • vmware_content_library
  • vmware_content_item
  • vmware_content_download_session
  • vmware_content_download_file
  • vmware_content_item_file
  • vmware_content_item_storage
  • vmware_content_update_session
  • vmware_content_update_file
  • vmware_content_subscribed_item
  • vmware_content_subscriptions
  • vmware_content_local_library
  • vmware_content_subscribed_library
  • vmware_vapi_metadata_authentication_component
  • vmware_vapi_metadata_authentication_package
  • vmware_vapi_metadata_authentication_service
  • vmware_vapi_metadata_authentication_service_operation
  • vmware_vapi_metadata_cli_command
  • vmware_vapi_metadata_cli_namespace
  • vmware_vapi_metadata_metamodel_component
  • vmware_vapi_metadata_metamodel_enumeration
  • vmware_vapi_metadata_metamodel_package
  • vmware_vapi_metadata_metamodel_resource
  • vmware_vapi_metadata_metamodel_resource_model
  • vmware_vapi_metadata_metamodel_service
  • vmware_vapi_metadata_metamodel_service_operation
  • vmware_vapi_metadata_metamodel_structure
  • vmware_vapi_metadata_privilege_package
  • vmware_vapi_metadata_privilege_service
  • vmware_vapi_metadata_privilege_service_operation
  • vmware_vapi_rest_navigation_component
  • vmware_vapi_rest_navigation_options
  • vmware_vapi_vcenter_activation
  • vmware_vcenter_certificate_tls
  • vmware_vcenter_certificate_tls_csr
  • vmware_vcenter_certificate_trusted_root_chains
  • vmware_vcenter_cluster
  • vmware_vcenter_datacenter
  • vmware_vcenter_datastore
  • vmware_vcenter_datastore_default_policy
  • vmware_vcenter_deployment
  • vmware_vcenter_deployment_import_history
  • vmware_vcenter_deployment_install
  • vmware_vcenter_deployment_install_remote_psc_thumbprint
  • vmware_vcenter_deployment_install_psc_replicated
  • vmware_vcenter_deployment_install_psc_standalone
  • vmware_vcenter_deployment_install_remote_psc
  • vmware_vcenter_deployment_question
  • vmware_vcenter_deployment_upgrade
  • vmware_vcenter_folder
  • vmware_vcenter_guest_customization_specs
  • vmware_vcenter_host
  • vmware_vcenter_inventory_datastore
  • vmware_vcenter_inventory_network
  • vmware_vcenter_iso_image
  • vmware_vcenter_network
  • vmware_vcenter_ovf_capability
  • vmware_vcenter_ovf_export_flag
  • vmware_vcenter_ovf_import_flag
  • vmware_vcenter_ovf_library_item
  • vmware_vcenter_resource_pool
  • vmware_vcenter_service
  • vmware_vcenter_storage_policies
  • vmware_vcenter_storage_policies_compliance
  • vmware_vcenter_storage_policies_compliance_vm
  • vmware_vcenter_system_config_deployment_type
  • vmware_vcenter_system_config_psc_registration
  • vmware_vcenter_topology_pscs
  • vmware_vcenter_vcha_capabilities
  • vmware_vcenter_vcha_cluster
  • vmware_vcenter_vcha_cluster_active
  • vmware_vcenter_vcha_cluster_deployment_type
  • vmware_vcenter_vcha_cluster_mode
  • vmware_vcenter_vcha_cluster_passive
  • vmware_vcenter_vcha_cluster_witness
  • vmware_vcenter_vcha_operations
  • vmware_vcenter_vcha_vc_credentials
  • vmware_vcenter_vm
  • vmware_vcenter_vm_template_library_items
  • vmware_vcenter_vm_guest_identity
  • vmware_vcenter_vm_guest_local_filesystem
  • vmware_vcenter_vm_guest_power
  • vmware_vcenter_vm_hardware
  • vmware_vcenter_vm_hardware_adapter_sata
  • vmware_vcenter_vm_hardware_adapter_scsi
  • vmware_vcenter_vm_hardware_boot
  • vmware_vcenter_vm_hardware_boot_device
  • vmware_vcenter_vm_hardware_cdrom
  • vmware_vcenter_vm_hardware_cpu
  • vmware_vcenter_vm_hardware_disk
  • vmware_vcenter_vm_hardware_ethernet
  • vmware_vcenter_vm_hardware_floppy
  • vmware_vcenter_vm_hardware_memory
  • vmware_vcenter_vm_hardware_parallel
  • vmware_vcenter_vm_hardware_serial
  • vmware_vcenter_vm_power
  • vmware_vcenter_vm_storage_policy
  • vmware_vcenter_vm_storage_policy_compliance

Access

  • Administer permissions or grant access to areas of vSphere or vCenter

Alarm

  • Manipulate vCenter Alarms

Cluster

  • Perform cluster-wide operations, such as capacity checking or rolling reboots

Event

  • Manipulate vCenter tasks and events

Inventory

  • Manipulate vCenter inventory, including metadata such as tags

Library

  • Manipulate and process content libraries and their items
  • This may not be needed depending on Core coverage

Licensing

  • Manage VMware licensing in vCenter

Network

  • Generic networking tasks

Network.NSX

  • Networking tasks specific to NSX and NSX-T

PCloud

Session

  • Manage vCenter sessions

Stat

  • Manage statistics from vCenter

SRM

  • Interface with Site Recovery Manager

Storage

  • Generic storage tasks, working with datastores and datastore clusters

Storage.ISCSI

  • Storage tasks specific to ISCSI

Storage.VSAN

  • Storage tasks specific to VSAN

vApp

  • Managing vApps and their contents

vCD

  • Interfacing with vCloud Director

VM

  • Management of VMs, individually or in groups

VMHost

  • Management of ESXi hosts, individually or in groups

vRO

  • Interfacing with vRealize Orchestrator

Action Items

  • [Akasurde]: Create a wiki page for collaboration
  • [Akasurde]: Push VMware httpapi plugin upstream for review
  • [Paul Knight]: Start design specification document for VMware httpapi plugin - IN PROGRESS
  • [Paul Knight]: Review this doc and add comments

This Wiki is used for quick notes, not for support or documentation.

(ARchived) Working groups

Working groups are now in the Ansible forum

Ansible project:
Community, Contributor Experience, Docs, News, Outreach, RelEng, Testing

Cloud:
AWS, Azure, CloudStack, Container, DigitalOcean, Docker, hcloud, Kubernetes, Linode, OpenStack, oVirt, Virt, VMware

Networking:
ACI, AVI, F5, Meraki, Network, NXOS

Ansible Developer Tools:
Ansible-developer-tools

Software:
Crypto, Foreman, GDrive, GitLab, Grafana, IPA, JBoss, MongoDB, MySQL, PostgreSQL, RabbitMQ, Zabbix

System:
AIX, BSD, HP-UX, macOS, Remote Management, Solaris, Windows

Security:
Security-Automation, Lockdown

Tooling:
AWX, Galaxy, Molecule

Communities

Modules:
unarchive, xml

Plugins:
httpapi

Wiki

Roles, Communication, Reviewing, Checklist, TODO

Clone this wiki locally