EVS CreateEnvironment API Reference

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.

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

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.

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.