{"id":26293753,"url":"https://github.com/veksh/ansible-esxi","last_synced_at":"2025-07-22T21:05:51.433Z","repository":{"id":51674515,"uuid":"128686763","full_name":"veksh/ansible-esxi","owner":"veksh","description":"Ansible management for stand-alone vmware esxi host","archived":false,"fork":false,"pushed_at":"2021-06-02T14:15:58.000Z","size":67,"stargazers_count":98,"open_issues_count":0,"forks_count":35,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-05T01:39:13.319Z","etag":null,"topics":["ansible","deployment","module","playbook","vm","vmware","vmware-esxi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veksh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-08T22:22:52.000Z","updated_at":"2025-02-02T19:43:36.000Z","dependencies_parsed_at":"2022-08-22T19:51:02.387Z","dependency_job_id":null,"html_url":"https://github.com/veksh/ansible-esxi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/veksh/ansible-esxi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veksh%2Fansible-esxi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veksh%2Fansible-esxi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veksh%2Fansible-esxi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veksh%2Fansible-esxi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veksh","download_url":"https://codeload.github.com/veksh/ansible-esxi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veksh%2Fansible-esxi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266572501,"owners_count":23950031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","deployment","module","playbook","vm","vmware","vmware-esxi"],"created_at":"2025-03-15T02:30:20.377Z","updated_at":"2025-07-22T21:05:51.410Z","avatar_url":"https://github.com/veksh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nAnsible has some great modules for VMware vCenter (especially in 2.5), but none for\nmanaging standalone ESXi hosts. There are many cases when full vCenter infrastructure\nis not required and web-based Host UI is quite enough for routine administrative tasks.\n\nModules, roles and playbooks presented here allow to manage standalone ESXi hosts\n(although hosts under vCenter are ok too) with direct SSH connection, usually with\ntransparent key-based authentication.\n\n# Contents of repository\n\n- role to configure ESXi host (`roles/hostconf_esxi`)\n- playbooks to deploy new VMs to ESXi host (in `vm_deploy/`)\n    - by uploading (template) VM from some other host (`upload_clone`)\n    - or by cloning local VM (`clone_local`)\n- modules used by role and deployment playbook\n    - to gather VM facts from ESXi host (`esxi_vm_info`)\n    - to manage autostart of VMs (`esxi_autostart`)\n    - to install or update custom VIBs (`esxi_vib`)\n- some helper filter plugins to simplify working with ESXi shell commands output\n    - `split`: split string into a list\n    - `todict`: convert a list of records into a dictionary, using specified field as a key\n- example playbook to update ESXi host with offline bundle (`update_esxi.yaml`)\n- helper script to get vault pass from macOS keychain (`get_vault_pass.esxi.sh`)\n\n# `hostconf-esxi` role\n\nThis role takes care of many aspects of standalone ESXi server configuration like\n\n- ESXi license key (if set)\n- host name, DNS servers\n- NTP servers, enable NTP client, set time\n- users\n    - create missed, remove extra ones\n    - assign random passwords to new users (and store in `creds/`)\n    - make SSH keys persist across reboots\n    - grant DCUI rights\n- portgroups\n    - create missed, remove extra\n    - assign specified tags\n- block BPDUs from guests\n- create vMotion interface (off by default, see `create_vmotion_iface` in role defaults)\n- datastores\n    - partition specified devices if required\n    - create missed datastores\n    - rename empty ones with wrong names\n- autostart for specified VMs (optionally disabling it for all others)\n- logging to syslog server; lower `vpxa` and other noisy components logging level from\n  default `verbose` to `info`\n- certificates for Host UI and SSL communication (if present)\n- install or update specified VIBs\n- [disable SLP](https://kb.vmware.com/s/article/76372), dangerous and mostly useless in smaller \n  deployments (set `disable_slpd: true` in host vars to turn it off)\n\nOnly requirement is correctly configured network (especially uplinks) and reachability\nover ssh with root password. ESXi must be reasonably recent (6.0+, although some\nnewer versions of 5.5 have working python 2.7 too).\n\n## General configuration\n- `ansible.cfg`: specify remote user, inventory path etc; specify vault pass method\n  if using one for certificate private key encryption.\n- `group_vars/all.yaml`: specify global parameters like NTP and syslog servers there\n- `group_vars/\u003csite\u003e.yaml`: set specific params for each `\u003csite\u003e` in inventory\n- `host_vars/\u003chost\u003e.yaml`: override global and group values with e.g. host-specific\n  users list or datastore config\n- put public keys for users into `roles/hostconf-esxi/files/id_rsa.\u003cuser\u003e@\u003ckeyname\u003e.pub`\n  for referencing them later in user list `host_vars` or `group_vars`\n\n## Typical variables for `(group|host)_vars`\n- serial number to assign, usually set in global `group_vars/all.yaml`; does not get\n  changed if not set\n\n        esxi_serial: \"XXXXX-XXXXX-XXXX-XXXXX-XXXXX\"\n\n- general network environment, usually set in `group_vars/\u003csite\u003e.yaml`\n\n        dns_domain: \"m0.maxidom.ru\"\n\n        name_servers:\n          - 10.0.128.1\n          - 10.0.128.2\n\n        ntp_servers:\n          - 10.1.131.1\n          - 10.1.131.2\n\n        # defaults: \"log.\" + dns_domain\n        # syslog_host: log.m0.maxidom.ru\n\n- user configuration: those users are created (if not present) and assigned random\n  passwords (printed out and stored in `creds/\u003cuser\u003e.\u003chost\u003e.pass.out`), have ssh keys assigned to them (persistently) and restricted to specified hosts (plus global list\n  in `permit_ssh_from`), are granted administrative rights and access to the console\n\n        esxi_local_users:\n        \"\u003cuser\u003e\":\n          desc: \"\u003cuser description\u003e\"\"\n          pubkeys:\n            - name:  \"\u003ckeyname\u003e\"\n              hosts: \"1.2.3.4,some-host.com\"\n\n    users that are not in this list (except root) are removed from host, so be careful.\n- network configuration: portgroups list in `esxi_portgroups` are exhaustive, i.e. those\n  and only those portgroups (with exactly matched tags) should be present oh host after\n  playbook run (missed are created, wrong names are fixed, extra are removed if not used)\n\n        esxi_portgroups:\n          all-tagged: { tag: 4095 }\n          adm-srv:    { tag:  210 }\n          srv-netinf: { tag:  131 }\n          pvt-netinf: { tag:  199 }\n          # could also specify vSwitch (default is vSwitch0)\n          adm-stor:   { tag:   21, vswitch: vSwitch1 }\n\n- datastore configuration: datastores would be created on those devices if missed and\n  `create_datastores` is set; existent datastores would be renamed to match specified\n  name if `rename_datastores` is set and they are empty\n\n        local_datastores:\n          \"vmhba0:C0:T0:L1\": \"nest-test-sys\"\n          \"vmhba0:C0:T0:L2\": \"nest-test-apps\"\n\n- VIBs to install or update (like latest esx-ui host client fling)\n\n        vib_list:\n          - name: esx-ui\n            url: \"http://www-distr.m1.maxidom.ru/suse_distr/iso/esxui-signed-6360286.vib\"\n\n- autostart configuration: listed VMs are added to esxi auto-start list, in specified order\n  if order is present, else just randomly; if `autostart_only_listed` is set, only those VMs\n  will be autostarted on host with extra VMs removed from autostart\n\n        vms_to_autostart:\n          eagle-m0:\n            order: 1\n          hawk-m0:\n            order: 2\n          falcon-u1:\n\n## Host-specific configuration\n- add host into corresponding group in `inventory.esxi`\n- set custom certificate for host\n    - put certificate into `files/\u003chost\u003e.rui.crt`,\n    - put key into `files/\u003chost\u003e.key.vault` (and encrypt vault)\n- override any group vars in `host_vars/hostname.yaml`\n\n## Initial host setup and later convergence runs\n\nFor the initial config only the \"root\" user is available, so run playbook like this:\n\n      ansible-playbook all.yaml -l new-host -u root -k --tags hostconf --diff\n\nAfter local users are configured (and ssh key auth is in place), just use `remote_user`\nfrom `ansible.cfg` and run it like\n\n      ansible-playbook all.yaml -l host-or-group --tags hostconf --diff\n\n## Notes\n- only one vSwitch (`vSwitch0`) is currently supported\n- password policy checks (introduced in 6.5) are turned off to allow for truly random\n  passwords (those are sometimes miss one of the character classes).\n\n# VM deployment playbooks\n\nThere are two playbooks in `vm_deploy/` subdir\n\n- first (`upload_clone`) is for copying template VM from source host to new target\n- second (`clone_local`) is for making custom clones of local template VM\n\nSee playbook source and comments at the top for a list if parameters, some are\nmentioned below.\n\n## Assumptions about environment\n\n- ansible 2.3+ (2.2 \"replace\" is not compatible with python 3 on ESXi)\n- local modules `netaddr` and `dnspython`\n- clone source must be powered off\n- for VM customization like setting IPs etc, [ovfconf](https://github.com/veksh/ovfconf)\n  must be configured on clone source VM (to take advantage of passing OVF params to VM)\n\n## `upload_clone`\n\nThis playbooks is mostly used to upload initial \"template\" VM to target host (to be,\nin turn, template for further local cloning). Source of template VM is usually at\nanother ESXi host, and there are 3 modes of copy:\n\n- direct \"pull\" SCP: destination host is SCP'ing VM files from source; authorization\n  is key-based with agent forwarding, so both hosts must have current Ansible user\n  configured and destination host must be in allowed hosts list for this user\n- direct \"push\" SCP: source host is SCP'ing VM files to destination, exactly as above\n  (if e.g. firewall is more permissive in that direction)\n- slow copy via current hosts: download VM files from source to temp dir first (with\n  Ansible \"copy\" module; rather fast if file is already staged there), then upload it\n  to destination hosts (must have enough space in \"tmp\" for that, see `ansible-deploy.cfg`\n  for tmp configuration)\n\nThere are no options for customization there, only for src and dst params like datastore,\nand usual invocation looks like\n\n      ansible-playbook upload_clone.yaml -l nest2-k1 \\\n        -e 'src_vm_name=phoenix11-1-k1 src_vm_vol=nest1-sys src_vm_server=nest1-k1' \\\n        -e 'dst_vm_name=phoenix11-2-k1' \\\n        -e 'direct_scp=true'\n\n## `clone_local`\n\nThis playbook is used to produce new VM from local template source, optionally customize\nparameters like datastore, network and disks, and optionally power it on. Invocation\nto create new machine (with additional network card and disk) and power it on looks like\n\n    ansible-playbook clone_local.yaml -l nest1-mf1 -e 'vm_name=files-mf1-vm \\\n      vm_desc=\"samba file server\" vm_net2=srv-smb vm_disk2=100G' \\\n      -e 'do_power_on=true'\n\nTo simplify cloning, it is better to\n\n- specify local clone source vm in ESXi host `host_vars` (as `src_vm_name`)\n- already have new machine's name in DNS (so IP is determined automatically)\n- have [ovfconf](https://github.com/veksh/ovfconf) configured in source (template)\n  VM, as OVF is used to pass network config there (DHCP server would be ok too)\n\n# Modules\n\nModules (`library/`) are documented with usual Ansible docs. They could be used\nstand-alone, like\n\n      ansible -m esxi_vm_list -a 'get_power_state=true get_start_state=true' esxi-name\n\nto get a list of host VMs together with autostart state and current run state\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveksh%2Fansible-esxi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveksh%2Fansible-esxi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveksh%2Fansible-esxi/lists"}