Initial commit: VMware vSphere API simulator scaffold.
Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API contracts, docs, client examples, and the unit/integration/compatibility test suite for local client and tooling labs without a real vCenter.
This commit is contained in:
@@ -0,0 +1,23 @@
|
||||
**Language / Язык:** [English](ansible.md) | [Русский](../ru/examples/ansible.md)
|
||||
|
||||
# Ansible
|
||||
|
||||
The playbook uses the `uri` module against the HTTPS gateway
|
||||
(`https://localhost`), with Basic-auth session login followed by
|
||||
`vmware-api-session-id`-header calls for the rest of the lifecycle.
|
||||
|
||||
```bash
|
||||
cd examples/ansible
|
||||
ansible-playbook -i inventory.ini vsphere_playbook.yml
|
||||
```
|
||||
|
||||
[`vsphere_playbook.yml`](../../examples/ansible/vsphere_playbook.yml) covers:
|
||||
session login, list VMs, create, power on, poll the CIS task
|
||||
(`/api/cis/tasks/{task}`), write a file to the lab guest virtual filesystem,
|
||||
power off, delete, and session logout.
|
||||
|
||||
Reseed the simulator (`make seed`) before relying on fixed VM names/MOIDs
|
||||
from a previous run.
|
||||
|
||||
For the official `pulumi-vsphere` lab suite (nonempty exports, HTML report),
|
||||
see [`pulumi-tests/`](../../pulumi-tests/README.md) or `make pulumi-tests`.
|
||||
@@ -0,0 +1,21 @@
|
||||
**Language / Язык:** [English](go.md) | [Русский](../ru/examples/go.md)
|
||||
|
||||
# Go
|
||||
|
||||
Uses the Go standard library (`net/http`) against
|
||||
`https://localhost` with a Basic-auth session
|
||||
(`vmware-api-session-id`).
|
||||
|
||||
```bash
|
||||
cd examples/go
|
||||
go run .
|
||||
```
|
||||
|
||||
Override defaults with `VSPHERE_BASE`, `VSPHERE_USER`, `VSPHERE_PASSWORD`,
|
||||
`VSPHERE_VM_NAME`. See [`main.go`](../../examples/go/main.go) for the
|
||||
session → list → create → power → wait-task → delete flow and the
|
||||
`waitTask` helper that polls `GET /api/cis/tasks/{task}`.
|
||||
|
||||
TLS verification is disabled in the HTTP client for the local self-signed
|
||||
development gateway certificate only — do not reuse that transport against a
|
||||
real vCenter.
|
||||
@@ -0,0 +1,22 @@
|
||||
**Language / Язык:** [English](java.md) | [Русский](../ru/examples/java.md)
|
||||
|
||||
# Java
|
||||
|
||||
Java 11+ `HttpClient` cookbook using a Basic-auth session
|
||||
(`vmware-api-session-id`) against `https://localhost`. No third-party
|
||||
JSON library — responses are inspected with a small string-based field
|
||||
extractor suitable for a lab smoke.
|
||||
|
||||
```bash
|
||||
cd examples/java
|
||||
javac Cookbook.java && java Cookbook
|
||||
```
|
||||
|
||||
Override defaults with `VSPHERE_BASE`, `VSPHERE_USER`, `VSPHERE_PASSWORD`,
|
||||
`VSPHERE_VM_NAME` environment variables. See
|
||||
[`Cookbook.java`](../../examples/java/Cookbook.java) for the session →
|
||||
create → power → wait-task → delete flow.
|
||||
|
||||
The client installs a trust-all `SSLContext` for the local self-signed
|
||||
development gateway certificate only — do not reuse it against a real
|
||||
vCenter.
|
||||
@@ -0,0 +1,53 @@
|
||||
**Language / Язык:** [English](overview.md) | [Русский](../ru/examples/overview.md)
|
||||
|
||||
# Client examples overview
|
||||
|
||||
## Bring-up checklist
|
||||
|
||||
```bash
|
||||
make up
|
||||
curl -skf https://localhost/health/ready
|
||||
make seed
|
||||
curl -sk https://localhost/api/appliance/system/version
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
| URL | When |
|
||||
|---|---|
|
||||
| `https://localhost` | curl, pyvmomi, govmomi, Terraform, Pulumi, Ansible, Go, Java, Perl — everything in `examples/` |
|
||||
| `http://localhost` | Plain-HTTP lab face (no TLS handshake needed) |
|
||||
|
||||
## Auth quick reference
|
||||
|
||||
**Session (REST)**
|
||||
|
||||
```bash
|
||||
SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' \
|
||||
-X POST https://localhost/api/session | tr -d '"')
|
||||
curl -sk -H "vmware-api-session-id: $SID" https://localhost/api/vcenter/vm
|
||||
```
|
||||
|
||||
**SOAP Login**
|
||||
|
||||
```bash
|
||||
python examples/python/vsphere_soap_smoke.py https://localhost
|
||||
```
|
||||
|
||||
## Task waiting
|
||||
|
||||
Never treat the mutation HTTP response alone as "VM running". Power, clone,
|
||||
relocate, snapshot, and OVF-deploy calls return `{ "task": "task-…" }`; poll
|
||||
`GET /api/cis/tasks/{task}` until `status` is `SUCCEEDED` or `FAILED`. See
|
||||
[Tasks](../domains/tasks.md).
|
||||
|
||||
## Reseed warning
|
||||
|
||||
`make seed` replaces the PostgreSQL inventory. Refresh Terraform/Pulumi/Ansible
|
||||
state afterwards — see [Seed profiles](../seed-profiles.md).
|
||||
|
||||
## Runnable tree
|
||||
|
||||
See [`examples/README.md`](../../examples/README.md). The official
|
||||
`pulumi-vsphere` lab suite lives under
|
||||
[`pulumi-tests/`](../../pulumi-tests/README.md) (`make pulumi-tests`).
|
||||
@@ -0,0 +1,20 @@
|
||||
**Language / Язык:** [English](perl.md) | [Русский](../ru/examples/perl.md)
|
||||
|
||||
# Perl
|
||||
|
||||
`HTTP::Tiny` + `JSON` cookbook using a Basic-auth session
|
||||
(`vmware-api-session-id`) against `https://localhost`.
|
||||
|
||||
```bash
|
||||
cd examples/perl
|
||||
cpanm --installdeps . # or install HTTP::Tiny, JSON, IO::Socket::SSL manually
|
||||
perl cookbook.pl
|
||||
```
|
||||
|
||||
Override defaults with `VSPHERE_BASE`, `VSPHERE_USER`, `VSPHERE_PASSWORD`,
|
||||
`VSPHERE_VM_NAME` environment variables. See
|
||||
[`cookbook.pl`](../../examples/perl/cookbook.pl) for the session → list →
|
||||
create → power → wait-task → delete flow.
|
||||
|
||||
`HTTP::Tiny` is constructed with `verify_SSL => 0` for the local self-signed
|
||||
development gateway certificate only.
|
||||
@@ -0,0 +1,31 @@
|
||||
**Language / Язык:** [English](pulumi.md) | [Русский](../ru/examples/pulumi.md)
|
||||
|
||||
# Pulumi
|
||||
|
||||
[`examples/pulumi/`](../../examples/pulumi/) is a Python Pulumi program that uses
|
||||
the official [`pulumi-vsphere`](https://www.pulumi.com/registry/packages/vsphere/)
|
||||
provider (SOAP/VIM) against the simulator — the same provider path as Terraform
|
||||
`hashicorp/vsphere`.
|
||||
|
||||
```bash
|
||||
cd examples/pulumi
|
||||
pip install -r requirements.txt
|
||||
pulumi plugin install resource vsphere 4.17.0
|
||||
pulumi stack init dev # once
|
||||
pulumi config set server localhost # or your gateway host
|
||||
pulumi config set --secret password 'VMware1!'
|
||||
pulumi up
|
||||
```
|
||||
|
||||
Configuration (`pulumi config set`): `server` (default `localhost`), `user`
|
||||
(default `administrator@vsphere.local`), `password` (secret), `datacenter`,
|
||||
`datastore`, `cluster`, `network`, `vm_name` (default `pulumi-lab-01`).
|
||||
|
||||
Same reseed caution as Terraform: simulator PostgreSQL state and Pulumi state
|
||||
are independent. Pin the catalog major for reproducible CI if your workflow
|
||||
depends on Web UI/evidence output (see [API versions](../api-versions.md)) —
|
||||
runtime routes themselves are always available regardless of the major.
|
||||
|
||||
For the lab suite (inventory + folder + VM + tags, nonempty output checks, HTML
|
||||
report), see [`pulumi-tests/`](../../pulumi-tests/README.md) or run
|
||||
`make pulumi-tests` from the repo root.
|
||||
@@ -0,0 +1,33 @@
|
||||
**Language / Язык:** [English](python-requests.md) | [Русский](../ru/examples/python-requests.md)
|
||||
|
||||
# Python — REST (requests / stdlib)
|
||||
|
||||
Raw HTTP against the vSphere REST gateway, no vendor SDK required.
|
||||
|
||||
```bash
|
||||
pip install -r examples/python/requirements.txt
|
||||
python examples/python/requests_cookbook.py
|
||||
```
|
||||
|
||||
[`requests_cookbook.py`](../../examples/python/requests_cookbook.py)
|
||||
demonstrates the shared session → create → wait-for-task → power on → wait →
|
||||
power off → delete flow using `requests`, with the session id carried as the
|
||||
`vmware-api-session-id` header.
|
||||
|
||||
For a dependency-free variant using only the standard library (`urllib`),
|
||||
see [`vsphere_rest_smoke.py`](../../examples/python/vsphere_rest_smoke.py):
|
||||
|
||||
```bash
|
||||
python examples/python/vsphere_rest_smoke.py https://localhost
|
||||
```
|
||||
|
||||
For a combined REST-create + SOAP-`CreateVM_Task` + guest-filesystem smoke,
|
||||
see [`vsphere_lifecycle.py`](../../examples/python/vsphere_lifecycle.py):
|
||||
|
||||
```bash
|
||||
VSPHERE_BASE=https://localhost python examples/python/vsphere_lifecycle.py
|
||||
```
|
||||
|
||||
All three scripts default to `administrator@vsphere.local` / `VMware1!` and
|
||||
disable TLS verification for the local self-signed development gateway
|
||||
certificate only.
|
||||
@@ -0,0 +1,32 @@
|
||||
**Language / Язык:** [English](terraform.md) | [Русский](../ru/examples/terraform.md)
|
||||
|
||||
# Terraform
|
||||
|
||||
[`examples/terraform/vsphere/`](../../examples/terraform/vsphere/) uses the
|
||||
official `hashicorp/vsphere` provider (SOAP `/sdk` under the hood) pointed at
|
||||
the local HTTPS gateway (`https://localhost`) with
|
||||
`allow_unverified_ssl = true` for the development certificate.
|
||||
|
||||
```bash
|
||||
cd examples/terraform/vsphere
|
||||
terraform init
|
||||
TF_VAR_create_lab_vm=false terraform plan # data sources only (datacenter/cluster/datastore/network/VM)
|
||||
TF_VAR_create_lab_vm=true terraform apply # also creates a lab VM (SOAP CreateVM_Task)
|
||||
```
|
||||
|
||||
Defaults (`variables.tf`): `vsphere_server = "localhost"`,
|
||||
`vsphere_user = "administrator@vsphere.local"`,
|
||||
`vsphere_password = "VMware1!"`, `datacenter = "Datacenter"`,
|
||||
`cluster = "Cluster"`, `datastore = "datastore1"`,
|
||||
`network = "VM Network"`, `vm_name = "web-01"` (a `small`/`large` seeded VM).
|
||||
|
||||
Provider plugin versions move quickly — pin versions in a `required_providers`
|
||||
block to what you have tested. After `make seed`, refresh or recreate state
|
||||
so VM name/MOID assumptions stay aligned.
|
||||
|
||||
This cookbook is a starting point for lab CI, not a certification of every
|
||||
`hashicorp/vsphere` resource/data source against the full route registry. See
|
||||
[SOAP / VIM](../domains/soap.md) for the exact operations backing the
|
||||
provider's create/read paths, and
|
||||
[`pulumi-tests/`](../../pulumi-tests/README.md) for the `pulumi-vsphere` lab
|
||||
suite (`make pulumi-tests`).
|
||||
@@ -0,0 +1,15 @@
|
||||
**Language / Язык:** [English](troubleshooting-clients.md) | [Русский](../ru/examples/troubleshooting-clients.md)
|
||||
|
||||
# Troubleshooting clients
|
||||
|
||||
| Symptom | Fix |
|
||||
|---|---|
|
||||
| TLS certificate errors | Use `:443` with `verify=False` / `insecure`/`allow_unverified_ssl=true` **only** locally, or use plain HTTP `:80` |
|
||||
| 401 on first call | Send `Authorization: Basic …` only to `/api/session` (or SOAP `Login`); every other call needs `vmware-api-session-id` |
|
||||
| 403 on power/create | You may be using `readonly@vsphere.local` — switch to `administrator@vsphere.local` or `operator@vsphere.local` |
|
||||
| VM not found | `small` seed VM names are `web-01`, `web-02`, `db-01`, `app-01`, `jumpbox` — not Proxmox-style numeric VMIDs |
|
||||
| Create returns a MOID, not a task | REST `POST /api/vcenter/vm` returns the new VM's MOID synchronously; only **power/clone/relocate/snapshot/OVF-deploy** return `{ "task": "…" }` |
|
||||
| Provider create vs task | Poll `/api/cis/tasks/{task}`; many providers (Terraform, Pulumi) already wait internally — raw HTTP/Go/Java/Perl clients often forget to |
|
||||
| Drift after reseed | Refresh/recreate Terraform/Pulumi/Ansible state after `make seed` |
|
||||
| Session expired mid-run | Sessions have a 2-hour sliding TTL; re-login if a long-running script idles past that |
|
||||
| SOAP `Login` fails | Confirm the envelope targets `/sdk` with `SOAPAction` set (empty string is fine) and `Content-Type: text/xml` |
|
||||
Reference in New Issue
Block a user