# EVS CreateEnvironment API Reference > API reference for Amazon EVS CreateEnvironment. Parameter constraints, validation rules, and error responses, each example verified against the live API. Sample PDF: Download API reference sample (PDF) — https://codyanthony.dev/Cody_Anthony_Sample_2_API_Reference_CreateEnvironment.pdf Rendered version: https://codyanthony.dev/case-studies/api-documentation/evs-createenvironment/ Author: Cody Anthony (https://codyanthony.dev/about/) --- This API reference for Amazon Elastic VMware Service demonstrates my approach to developer-focused API documentation. The infrastructure-as-code path for the same parameters is covered in the [Amazon EVS CloudFormation Reference](/case-studies/api-documentation/evs-cloudformation/). ## Project context `CreateEnvironment` is the core deployment API for Amazon EVS. It requires customers to supply networking, licensing, host, DNS, security, and VCF configuration in one operation, with several constraints that must be correct before provisioning begins. ## My role and ownership I authored the Amazon EVS API Reference for public preview and general availability, covering every public operation in the guide: operation descriptions, request and response structures, parameter descriptions, data type descriptions, validation guidance, and exception documentation. This sample focuses on `CreateEnvironment` because it is the most complex and customer-critical operation in the API. It is the point where a customer creates an EVS environment and connects it to the customer-owned VPC that contains the networking, DNS, host, licensing, and security resources EVS requires. I participated in the API design phase for EVS, contributing to parameter naming, validation rules, error messaging, and constraint placement before writing the public reference documentation. I also validated request patterns, parameter behavior, and error responses against the live API so the published reference matched real product behavior. ## What the work solved - Reduced trial-and-error by documenting constraints before developers submitted deployment requests. - Made parameter dependencies and mutual exclusivity explicit, including cases such as `dedicatedHostId` and `placementGroupId`. - Gave developers clearer recovery paths by documenting validation behavior and error responses alongside the request model. ## Validation approach I validated the API reference against live behavior using the AWS CLI, test deployments, and supporting scripts for complex resource creation. That validation covered parameter inputs, response outputs, constraint behavior, and error messages, so the published reference described what the API actually did rather than only what the model implied. Because the API reference fed the downstream SDK documentation handoff required for deployment, accuracy in the reference was part of launch readiness, not just documentation polish. ## What this sample demonstrates - Developer-focused API reference for a complex, multi-parameter deployment operation - Constraint and validation-rule documentation for networking, licensing, DNS, hosts, and security configuration - Parameter-dependency documentation that makes mutual exclusivity and required relationships explicit - Request and error behavior validated against the live API - Production API reference documentation that served as the source for downstream SDK documentation through the required API deployment handoff ## Live documentation - [Amazon EVS API Reference — full API reference guide authored for public preview and GA](https://docs.aws.amazon.com/evs/latest/APIReference/Welcome.html) - [CreateEnvironment API Reference — curated sample focus](https://docs.aws.amazon.com/evs/latest/APIReference/API_CreateEnvironment.html) - [PDF snapshot — EVS API Reference sample](/Cody_Anthony_Sample_2_API_Reference_CreateEnvironment.pdf) --- **Note on authorship and excerpt selection:** Response syntax and administrative parameters (e.g., tags, names, site IDs) have been omitted to focus on the service-specific network, compute, and security configuration inputs. --- ## Documentation excerpt (curated) ## CreateEnvironment Creates an Amazon EVS environment that runs VCF software, such as SDDC Manager, NSX Manager, and vCenter Server. During environment creation, Amazon EVS performs validations on DNS settings, provisions VLAN subnets and hosts, and deploys the supplied version of VCF. **Note:** You cannot use the `dedicatedHostId` and `placementGroupId` parameters together in the same `CreateEnvironment` action. This results in a `ValidationException` response. --- ## Request Syntax ```json { "connectivityInfo": { "privateRouteServerPeerings": [ "string" ] }, "hosts": [ { "dedicatedHostId": "string", "hostName": "string", "instanceType": "string", "keyName": "string", "placementGroupId": "string" } ], "initialVlans": { "edgeVTep": { "cidr": "string" }, "expansionVlan1": { "cidr": "string" }, "expansionVlan2": { "cidr": "string" }, "hcx": { "cidr": "string" }, "hcxNetworkAclId": "string", "isHcxPublic": boolean, "nsxUplink": { "cidr": "string" }, "vmkManagement": { "cidr": "string" }, "vmManagement": { "cidr": "string" }, "vMotion": { "cidr": "string" }, "vSan": { "cidr": "string" }, "vTep": { "cidr": "string" } }, "licenseInfo": [ { "solutionKey": "string", "vsanKey": "string" } ], "serviceAccessSecurityGroups": { "securityGroups": [ "string" ] }, "serviceAccessSubnetId": "string", "vcfHostnames": { "cloudBuilder": "string", "nsx": "string", "nsxEdge1": "string", "nsxEdge2": "string", "nsxManager1": "string", "nsxManager2": "string", "nsxManager3": "string", "sddcManager": "string", "vCenter": "string" }, "vcfVersion": "string", "vpcId": "string" } ``` --- ## Request Parameters For information about the parameters that are common to all actions, see [Common Parameters](https://docs.aws.amazon.com/evs/latest/APIReference/CommonParameters.html). The request accepts the following data in JSON format. **Note:** In the following list, the required parameters are described first. ### connectivityInfo **Type:** ConnectivityInfo object **Required:** Yes The connectivity configuration for the environment. Amazon EVS requires that you specify two route server peer IDs. During environment creation, the route server endpoints peer with the NSX edges over the NSX uplink subnet, providing BGP-based dynamic routing for overlay networks. --- ### hosts **Type:** Array of HostInfoForCreate objects **Array Members:** Fixed number of 4 items. **Required:** Yes The ESXi hosts to add to the environment. Amazon EVS requires that you provide details for a minimum of 4 hosts during environment creation. For each host, you must provide the desired hostname, EC2 SSH keypair name, and EC2 instance type. Optionally, you can also provide a partition or cluster placement group to use, or use Amazon EC2 Dedicated Hosts. --- ### initialVlans **Type:** InitialVlans object **Required:** Yes The initial VLAN subnets for the Amazon EVS environment. **Note:** For each Amazon EVS VLAN subnet, you must specify a non-overlapping CIDR block. Amazon EVS VLAN subnets have a minimum CIDR block size of `/28` and a maximum size of `/24`. --- ### licenseInfo **Type:** Array of LicenseInfo objects **Array Members:** Fixed number of 1 item. **Required:** Yes The license information that Amazon EVS requires to create an environment. Amazon EVS requires two license keys: a VCF solution key and a vSAN license key. The VCF solution key must cover a minimum of 256 cores. The vSAN license key must provide at least 110 TiB of vSAN capacity. VCF licenses can be used for only one Amazon EVS environment. Amazon EVS does not support reuse of VCF licenses for multiple environments. VCF license information can be retrieved from the Broadcom portal. --- ### serviceAccessSubnetId **Type:** String **Length Constraints:** Minimum length of 15. Maximum length of 24. **Pattern:** `subnet-[a-f0-9]{8}([a-f0-9]{9})?` **Required:** Yes The subnet that is used to establish connectivity between the Amazon EVS control plane and VPC. Amazon EVS uses this subnet to validate mandatory DNS records for your VCF appliances and hosts and create the environment. --- ### vcfHostnames **Type:** VcfHostnames object **Required:** Yes The DNS hostnames for the virtual machines that host the VCF management appliances. Amazon EVS requires that you provide DNS hostnames for the following appliances: vCenter, NSX Manager, SDDC Manager, and Cloud Builder. --- ### vcfVersion **Type:** String **Valid Values:** `VCF-5.2.1` **Required:** Yes The VCF version to use for the environment. Amazon EVS only supports VCF version 5.2.1 at this time. --- ### vpcId **Type:** String **Length Constraints:** Minimum length of 12. Maximum length of 21. **Pattern:** `vpc-[a-f0-9]{8}([a-f0-9]{9})?` **Required:** Yes A unique ID for the VPC that the environment is deployed inside. Amazon EVS requires that all VPC subnets exist in a single Availability Zone in a Region where the service is available. The VPC that you specify must have a valid DHCP option set with domain name, at least two DNS servers, and an NTP server. These settings are used to configure your VCF appliances and hosts. The VPC cannot be used with any other deployed Amazon EVS environment. Amazon EVS does not provide multi-VPC support for environments at this time. Amazon EVS does not support the following AWS networking options for NSX overlay connectivity: cross-Region VPC peering, Amazon S3 gateway endpoints, or AWS Direct Connect virtual private gateway associations. --- ### serviceAccessSecurityGroups **Type:** ServiceAccessSecurityGroups object **Required:** No The security group that controls communication between the Amazon EVS control plane and VPC. The default security group is used if a custom security group isn't specified. The security group should allow access to the following: - TCP/UDP access to the DNS servers - HTTPS/SSH access to the host management VLAN subnet - HTTPS/SSH access to the Management VM VLAN subnet You should avoid modifying the security group rules after deployment, as this can break the persistent connection between the Amazon EVS control plane and VPC. This can cause future environment actions like adding or removing hosts to fail. --- ## Errors For information about the errors that are common to all actions, see [Common Errors](https://docs.aws.amazon.com/evs/latest/APIReference/CommonErrors.html). ### ValidationException The input fails to satisfy the specified constraints. You will see this exception if invalid inputs are provided for any of the Amazon EVS environment operations, or if a list operation is performed on an environment resource that is still initializing. **HTTP Status Code:** 400 **Response Elements:** - **fieldList** - A list of fields that didn't validate. - **message** - Describes the error encountered. - **reason** - The reason for the exception.