feat(vsphere): add vCenter OpenAPI spec and Studio Project - #52
Merged
michaelelrom merged 12 commits intoAug 7, 2026
Conversation
Full, unmodified vCenter Automation API surface (137 operations) generated via vmware-openapi-generator against a live vCenter 9.1 instance. Security scheme, curated -latest spec, and README to follow.
- Fix OpenAPI 3.0 validation failure: the generator emitted a Swagger 2.0-style top-level `items` on the `features` query parameter instead of nesting it under `schema` — confirmed via Itential Platform's own ajv-based OpenAPI validator (core/integrations/OpenAPIUtils.js). - Add the `sessionIdAuth` apiKey securityScheme (vmware-api-session-id header) so the spec can drive Itential's dynamicRetrieval auth flow against vCenter's session-creation endpoint. - Verified end-to-end: passes ensureOA3 validation and the actual swaggerToPronghorn conversion (178 methods) used at model import time.
…ndex entry - vmware_vsphere_vcenter-latest.json: trimmed from 178 to 91 operations, dropping vCenter appliance self-administration (deployment/upgrade bootstrap, TLS/cert management, VCHA setup, SSO topology, internal services, CEIP/PSC config) and legacy peripheral hardware (floppy/ parallel/serial). Verified against Itential's OpenAPI validator and swaggerToPronghorn conversion (91 methods, matching the trim). - README.md documents the dynamicRetrieval session-auth setup and the curated spec's included/excluded resource categories. - Adds VMware to the root README vendor index.
The generator was run without vmware-openapi-generator's -uo/
--unique-operation-ids flag, so most operationIds were left as bare
vAPI action names (get, list, create, find, ...) that collide across
almost every resource. Itential Platform's model-import validation
(core/integrations/Gateway.js) rejects any spec with a duplicate
operationId, which is what surfaced on import ("duplicate operation
id: find").
Fixed by re-deriving operationIds using the generator's own
create_camelized_op_id/create_unique_op_ids algorithm (path_processing.py)
applied directly to the already-generated files, rather than requiring
a full regeneration against live vCenter. Re-verified against the
platform's actual OpenAPI validator, the exact duplicate-operationId
check from Gateway.js, and the swaggerToPronghorn conversion — all
178 (full) / 91 (latest) operationIds are now unique end to end.
…Retrieval config The sessionIdAuth scheme had the runtime dynamicRetrieval plumbing (x-itential-parameters) but not the schema/integrationSchema.js opt-in flag (x-itential-dynamic-retrieval: true) that tells Itential Platform's config-template generator to actually offer the dynamicRetrieval shape. Without it, getAuthSchema() falls back to a plain static apiKey scaffold (a required "value" field), which is what showed up in the Connection Properties UI instead of the documented dynamicRetrieval flow. Verified via schema/integrationSchema.js's getAuthSchema() directly: sessionIdAuth's generated schema now includes dynamicRetrieval and no longer requires a static "value".
Itential Platform's dynamicRetrieval default-value generation for apiKey schemes has a confirmed bug (Gateway.js getThisAuth(), reported to Itential's IPSO project) that assigns the x-itential-dynamic-retrieval flag's boolean value instead of a placeholder object, which fails schema validation and blocks creating any integration instance for a model using that flag. Until that's fixed, drop x-itential-dynamic-retrieval and its x-itential-parameters from sessionIdAuth and require a static value instead. Admins generate a vCenter session token via curl and paste it into the integration's Connection Properties, re-generating it when it expires (~30 min idle timeout by default). README updated to match.
… boolean flag
Root cause of the earlier "must be object" schema validation error was
not a platform bug: x-itential-dynamic-retrieval is meant to hold the
actual retrieval config object ({method, url, responsePointer}), not
a boolean opt-in flag. Gateway.js's getThisAuth() carries this
extension value through verbatim as the default authentication value
on integration creation -- setting it to `true` produced an invalid
boolean default, while setting it to the real object (with a
placeholder host) produces a valid, pre-filled default that passes
schema validation immediately.
Also moved the Authorization credential from a top-level `variables`
entry into the scheme's own `x-itential-parameters` (dropping
x-itential-variable so it surfaces under authentication.sessionIdAuth
.parameters.Authorization directly), matching a known-working sibling
spec.
Verified end-to-end: replicated Gateway.js's getThisAuth() logic
exactly and confirmed the generated default value validates against
schema/integrationSchema.js's getAuthSchema() output, in addition to
the existing OpenAPI 3.0, duplicate-operationId, and pronghorn
conversion checks.
…ask naming Itential Platform's task-input naming convention (@itential/itential-utils NamingConventions.validateVariableName) disallows dots, but vSphere's REST API uses dot-notation query parameter names for every list-operation filter (filter.names, filter.clusters, etc.). Confirmed by tracing IntegrationUtils.js's buildRequest/validateMethodParams that a parameter's OpenAPI `name` field is used as both the task input name and the literal wire query key, with no aliasing mechanism -- so renaming to a valid identifier would silently break the actual API call instead of just fixing the task-creation error. All affected filters are optional; list operations still return the full result set without them. Removed 53 params across 15 operations (2.0.0.json) / 49 params across 12 operations (latest.json). Verified zero remaining naming-convention violations via the platform's own validateVariableName, plus the existing ajv/duplicate-operationId/ pronghorn-conversion checks.
Adds a 22-workflow Studio Project (Inventory + Virtual Machines) covering the vCenter REST API operations most useful for infrastructure automation, so users don't have to dig through the full API surface to find them. CRUD is scoped to where the API actually supports it: inventory objects are read-only, virtual machines get full lifecycle coverage. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The full-spec section referenced a "described above" note that was removed during README cleanup, leaving a dangling reference. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…cts standard Only 2 of 22 existing Studio Project contributions (Meraki, Panorama) actually pair a Sample Use Case with an Automation + Trigger, so this read as a hard requirement the rest of the repo doesn't follow. Reworded to make it optional guidance instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…dard Not worth documenting as guidance either -- most Studio Project contributions don't include one, and there's no repo-wide expectation that they should. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
VMware/vSphere/OpenAPIs/: a full 178-operation vCenter REST API spec (vmware_vsphere_vcenter-2.0.0.json) generated from a live vCenter instance via VMware'svmware-openapi-generator(no vendor-published OpenAPI spec exists), plus a curated 91-operation-latest.jsoncovering common CRUD for infrastructure automation.VMware/vSphere/Studio Projects/VMware vSphere vCenter.project.json: a 22-workflow Studio Project (Inventory— read-only inventory lookups;Virtual Machines— full lifecycle: create, read, hardware update, power, delete), scoped to CRUD only where the vCenter REST API actually supports it. Every workflow tested against a live vCenter instance.README.mdcovering integration configuration (including vCenter's dynamic session-token auth viax-itential-dynamic-retrieval), the OpenAPI spec breakdown, the Studio Project's folder structure, and known limitations (no server-side list filtering, no cluster/host/resource-pool capacity data).README.mdvendor index entry for VMware.STANDARDS.mdcorrection: reworded the Studio Projects "Sample Use Case" requirement to optional guidance — only 2 of 22 existing Studio Project contributions actually follow it as written.Notes for reviewers
filter.names), which Itential Platform's naming convention doesn't allow. These optional filter parameters are omitted from everylistoperation in both spec files; alllistoperations still work and return the full unfiltered result set. Documented in the product README's Known Limitations section.Inventory,Virtual Machines) are meant to stand alone as atomic, reusable building blocks.Test plan