EVS CreateEnvironment API Reference

This API reference for Amazon Elastic VMware Service demonstrates my approach to developer-focused API documentation. I participated in the API design phase, shaping parameter names, validation rules, and error messages before writing the reference documentation. The CreateEnvironment operation is the core deployment API for EVS, requiring comprehensive documentation of complex networking, licensing, and infrastructure parameters.

Deliverables & Impact

Documentation produced:

Complete API reference with all required and optional parameters
Request syntax with validated JSON structures
Constraint documentation (CIDR blocks, license requirements, host minimums)
Error response documentation with resolution guidance
Parameter relationship documentation (mutual exclusivity, dependencies)

Tools & formats used:

AWS documentation platform (DocBook XML)
JSON syntax validation
Tested against development environments
Collaborated with Engineering on parameter descriptions used in SDKs

Developer experience impact:

Prevented trial-and-error through upfront constraint documentation
Documented parameter relationships to avoid validation errors
Clear validation requirements reducing support tickets
Actionable error messages helping developers self-serve

Documentation Sample

PDF Snapshot: Download EVS API Reference Sample

Live Documentation: CreateEnvironment API Reference on docs.aws.amazon.com

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.

Request Syntax

{
   "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.

The request accepts the following data in JSON format.

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.

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.

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.