environments

Creates, updates, deletes, gets or lists an environments resource.

Overview

Name	environments
Type	Resource
Id	aws.evs.environments

Fields

The following fields are returned by SELECT queries:

get_environment

Name	Datatype	Description
checks	array	A check on the environment to identify connector health.
connectivity_info	object	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 uplink VLAN for connectivity to the NSX overlay network.
created_at	string (date-time)	The date and time that the environment was created.
credentials	array	The VCF credentials that are stored as Amazon EVS managed secrets in Amazon Web Services Secrets Manager. Amazon EVS stores credentials that are needed to install vCenter Server, NSX, and SDDC Manager.
environment_arn	string	The Amazon Resource Name (ARN) that is associated with the environment. (pattern: <code>arn:aws:evs:[a-z]{2}-[a-z]+-[0-9]:[0-9]{12}:environment/[a-zA-Z0-9_-]+</code>)
environment_id	string	The unique ID for the environment. (pattern: <code>(env-[a-zA-Z0-9]{10})</code>)
environment_name	string	The name of the environment. (pattern: <code>[a-zA-Z0-9_-]+</code>)
environment_state	string	The state of an environment. (CREATING, CREATED, DELETING, DELETED, CREATE_FAILED)
environment_status	string	Reports impaired functionality that stems from issues internal to the environment, such as impaired reachability. (PASSED, FAILED, UNKNOWN)
kms_key_id	string	The Amazon Web Services KMS key ID that Amazon Web Services Secrets Manager uses to encrypt secrets that are associated with the environment. These secrets contain the VCF credentials that are needed to install vCenter Server, NSX, and SDDC Manager. By default, Amazon EVS use the Amazon Web Services Secrets Manager managed key aws/secretsmanager. You can also specify a customer managed key.
license_info	array	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 meet minimum core requirements, and the vSAN license key must meet minimum capacity requirements for your selected instance type. For information about minimum license requirements, see the VCF subscriptions section in the Amazon EVS User Guide.
modified_at	string (date-time)	The date and time that the environment was modified.
service_access_security_groups	object	The security groups that allow traffic between the Amazon EVS control plane and your VPC for service access. If a security group is not specified, Amazon EVS uses the default security group in your account for service access.
service_access_subnet_id	string	The subnet that is used to establish connectivity between the Amazon EVS control plane and VPC. Amazon EVS uses this subnet to perform validations and create the environment. (pattern: <code>subnet-[a-f0-9]{8}([a-f0-9]{9})?</code>)
site_id	string	The Broadcom Site ID that is associated with your Amazon EVS environment. Amazon EVS uses the Broadcom Site ID that you provide to meet Broadcom VCF license usage reporting requirements for Amazon EVS.
state_details	string	A detailed description of the environmentState of an environment.
terms_accepted	boolean	Customer confirmation that the customer has purchased and will continue to maintain the required number of VCF software licenses to cover all physical processor cores in the Amazon EVS environment. Information about your VCF software in Amazon EVS will be shared with Broadcom to verify license compliance. Amazon EVS does not validate license keys. To validate license keys, visit the Broadcom support portal.
vcf_hostnames	object	The DNS hostnames to be used by the VCF management appliances in your environment. For environment creation to be successful, each hostname entry must resolve to a domain name that you've registered in your DNS service of choice and configured in the DHCP option set of your VPC. DNS hostnames cannot be changed after environment creation has started.
vcf_version	string	The VCF version of the environment. (VCF-5.2.1, VCF-5.2.2, SELF_DEPLOYED)
vpc_id	string	The VPC associated with the environment. (pattern: <code>vpc-[a-f0-9]{8}([a-f0-9]{9})?</code>)

list_environments

Name	Datatype	Description
created_at	string (date-time)	The date and time that the environment was created.
environment_arn	string	The Amazon Resource Name (ARN) that is associated with the environment. (pattern: <code>arn:aws:evs:[a-z]{2}-[a-z]+-[0-9]:[0-9]{12}:environment/[a-zA-Z0-9_-]+</code>)
environment_id	string	A unique ID for the environment. (pattern: <code>(env-[a-zA-Z0-9]{10})</code>)
environment_name	string	The name of the environment. (pattern: <code>[a-zA-Z0-9_-]+</code>)
environment_state	string	The state of an environment. (CREATING, CREATED, DELETING, DELETED, CREATE_FAILED)
environment_status	string	Reports impaired functionality that stems from issues internal to the environment, such as impaired reachability. (PASSED, FAILED, UNKNOWN)
modified_at	string (date-time)	The date and time that the environment was modified.
vcf_version	string	The VCF version of the environment. (VCF-5.2.1, VCF-5.2.2, SELF_DEPLOYED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_environment	select	region		Returns a description of the specified environment.
list_environments	select	region		Lists the Amazon EVS environments in your Amazon Web Services account in the specified Amazon Web Services Region.
create_environment	insert	region, vpcId, serviceAccessSubnetId, vcfVersion, termsAccepted, initialVlans		Creates an Amazon EVS environment that runs VCF software, such as SDDC Manager, NSX Manager, and vCenter Server. When you specify SELF_DEPLOYED for vcfVersion, Amazon EVS provisions only the VLAN subnets; no hosts are added and no VCF installation is performed. After the environment is created, you can add hosts with CreateEnvironmentHost and install VCF yourself. The licenseInfo, hosts, vcfHostnames, siteId, and connectivityInfo parameters are not supported in this mode. When you specify any other VCF version, Amazon EVS installs and configures VCF for you. For more information, see Self-deployed mode in the Amazon EVS User Guide. When Amazon EVS installs VCF, the default ESX version for the selected VCF version will be used. After a host is added with a specific ESX version, it can only be upgraded using vCenter Lifecycle Manager. You cannot use the dedicatedHostId and placementGroupId parameters together in the same CreateEnvironment action. This results in a ValidationException response.
create_entitlement	insert	region, environmentId, connectorId, entitlementType, vmIds		Creates a Windows Server License entitlement for virtual machines in an Amazon EVS environment using the provided vCenter Server connector. This is an asynchronous operation. Amazon EVS validates the specified virtual machines before starting usage tracking.
associate_eip_to_vlan	update	region, environmentId, vlanName, allocationId		Associates an Elastic IP address with a public HCX VLAN. This operation is only allowed for public HCX VLANs at this time.
disassociate_eip_from_vlan	update	region, environmentId, vlanName, associationId		Disassociates an Elastic IP address from a public HCX VLAN. This operation is only allowed for public HCX VLANs at this time.
delete_entitlement	delete	region		Deletes a Windows Server License entitlement for virtual machines in an Amazon EVS environment. Deleting an entitlement stops usage tracking for the specified virtual machines.
delete_environment	delete	region		Deletes an Amazon EVS environment. Amazon EVS environments will only be enabled for deletion once the hosts are deleted. You can delete hosts using the DeleteEnvironmentHost action. Environment deletion also deletes the associated Amazon EVS VLAN subnets and Amazon Web Services Secrets Manager secrets that Amazon EVS created. Amazon Web Services resources that you create are not deleted. These resources may continue to incur costs.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_environment

Returns a description of the specified environment.

SELECT
checks,
connectivity_info,
created_at,
credentials,
environment_arn,
environment_id,
environment_name,
environment_state,
environment_status,
kms_key_id,
license_info,
modified_at,
service_access_security_groups,
service_access_subnet_id,
site_id,
state_details,
terms_accepted,
vcf_hostnames,
vcf_version,
vpc_id
FROM aws.evs.environments
WHERE region = '{{ region }}' -- required
;

list_environments

Lists the Amazon EVS environments in your Amazon Web Services account in the specified Amazon Web Services Region.

SELECT
created_at,
environment_arn,
environment_id,
environment_name,
environment_state,
environment_status,
modified_at,
vcf_version
FROM aws.evs.environments
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_environment

Creates an Amazon EVS environment that runs VCF software, such as SDDC Manager, NSX Manager, and vCenter Server. When you specify SELF_DEPLOYED for vcfVersion, Amazon EVS provisions only the VLAN subnets; no hosts are added and no VCF installation is performed. After the environment is created, you can add hosts with CreateEnvironmentHost and install VCF yourself. The licenseInfo, hosts, vcfHostnames, siteId, and connectivityInfo parameters are not supported in this mode. When you specify any other VCF version, Amazon EVS installs and configures VCF for you. For more information, see Self-deployed mode in the Amazon EVS User Guide. When Amazon EVS installs VCF, the default ESX version for the selected VCF version will be used. After a host is added with a specific ESX version, it can only be upgraded using vCenter Lifecycle Manager. You cannot use the dedicatedHostId and placementGroupId parameters together in the same CreateEnvironment action. This results in a ValidationException response.

INSERT INTO aws.evs.environments (
clientToken,
environmentName,
kmsKeyId,
tags,
serviceAccessSecurityGroups,
vpcId,
serviceAccessSubnetId,
vcfVersion,
termsAccepted,
initialVlans,
connectivityInfo,
licenseInfo,
hosts,
vcfHostnames,
siteId,
region
)
SELECT 
'{{ clientToken }}',
'{{ environmentName }}',
'{{ kmsKeyId }}',
'{{ tags }}',
'{{ serviceAccessSecurityGroups }}',
'{{ vpcId }}' /* required */,
'{{ serviceAccessSubnetId }}' /* required */,
'{{ vcfVersion }}' /* required */,
{{ termsAccepted }} /* required */,
'{{ initialVlans }}' /* required */,
'{{ connectivityInfo }}',
'{{ licenseInfo }}',
'{{ hosts }}',
'{{ vcfHostnames }}',
'{{ siteId }}',
'{{ region }}'
RETURNING
environment
;

create_entitlement

Creates a Windows Server License entitlement for virtual machines in an Amazon EVS environment using the provided vCenter Server connector. This is an asynchronous operation. Amazon EVS validates the specified virtual machines before starting usage tracking.

INSERT INTO aws.evs.environments (
clientToken,
environmentId,
connectorId,
entitlementType,
vmIds,
region
)
SELECT 
'{{ clientToken }}',
'{{ environmentId }}' /* required */,
'{{ connectorId }}' /* required */,
'{{ entitlementType }}' /* required */,
'{{ vmIds }}' /* required */,
'{{ region }}'
RETURNING
entitlements
;

Manifest

# Description fields are for documentation purposes
- name: environments
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the environments resource.
  - name: clientToken
    value: "{{ clientToken }}"
    description: |
      This parameter is not used in Amazon EVS currently. If you supply input for this parameter, it will have no effect. A unique, case-sensitive identifier that you provide to ensure the idempotency of the entitlement creation request. If you do not specify a client token, a randomly generated token is used for the request to ensure idempotency.
  - name: environmentName
    value: "{{ environmentName }}"
    description: |
      The name to give to your environment. The name can contain only alphanumeric characters (case-sensitive), hyphens, and underscores. It must start with an alphanumeric character, and can't be longer than 100 characters. The name must be unique within the Amazon Web Services Region and Amazon Web Services account that you're creating the environment in.
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
    description: |
      A unique ID for the customer-managed KMS key that is used to encrypt the VCF credential pairs for SDDC Manager, NSX Manager, and vCenter appliances. These credentials are stored in Amazon Web Services Secrets Manager.
  - name: tags
    value: "{{ tags }}"
    description: |
      Metadata that assists with categorization and organization. Each tag consists of a key and an optional value. You define both. Tags don't propagate to any other cluster or Amazon Web Services resources.
  - name: serviceAccessSecurityGroups
    description: |
      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.
    value:
      securityGroups:
        - "{{ securityGroups }}"
  - name: vpcId
    value: "{{ vpcId }}"
    description: |
      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 Amazon Web Services networking options for NSX overlay connectivity: cross-Region VPC peering, Amazon S3 gateway endpoints, or Amazon Web Services Direct Connect virtual private gateway associations. Ensure that you specify a VPC that is adequately sized to accommodate the Amazon EVS subnets.
  - name: serviceAccessSubnetId
    value: "{{ serviceAccessSubnetId }}"
    description: |
      The subnet that is used to establish connectivity between the Amazon EVS control plane and VPC. The Amazon EVS control plane uses this subnet to interface with your environment. This includes validating DNS records and enabling Amazon EVS Connectors.
  - name: vcfVersion
    value: "{{ vcfVersion }}"
    description: |
      The VCF version to use for the environment. SELF_DEPLOYED: You install VCF yourself. The licenseInfo, hosts, vcfHostnames, siteId, and connectivityInfo parameters are not supported. Any other valid value: Amazon EVS installs and configures VCF for you in the version you specify.
    valid_values: ['VCF-5.2.1', 'VCF-5.2.2', 'SELF_DEPLOYED']
  - name: termsAccepted
    value: {{ termsAccepted }}
    description: |
      Confirmation that the customer has purchased and will continue to maintain the required number of VCF software licenses to cover all physical processor cores in the Amazon EVS environment. Information about your VCF software in Amazon EVS will be shared with Broadcom to verify license compliance. Amazon EVS does not validate license keys. To validate license keys, visit the Broadcom support portal.
  - name: initialVlans
    description: |
      The initial VLAN subnets for the Amazon EVS environment. 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.
    value:
      vmkManagement:
        cidr: "{{ cidr }}"
      vmManagement:
        cidr: "{{ cidr }}"
      vMotion:
        cidr: "{{ cidr }}"
      vSan:
        cidr: "{{ cidr }}"
      vTep:
        cidr: "{{ cidr }}"
      edgeVTep:
        cidr: "{{ cidr }}"
      nsxUplink:
        cidr: "{{ cidr }}"
      hcx:
        cidr: "{{ cidr }}"
      expansionVlan1:
        cidr: "{{ cidr }}"
      expansionVlan2:
        cidr: "{{ cidr }}"
      isHcxPublic: {{ isHcxPublic }}
      hcxNetworkAclId: "{{ hcxNetworkAclId }}"
  - name: connectivityInfo
    description: |
      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. Not supported when vcfVersion is SELF_DEPLOYED.
    value:
      privateRouteServerPeerings:
        - "{{ privateRouteServerPeerings }}"
  - name: licenseInfo
    description: |
      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 meet minimum core requirements, and the vSAN license key must meet minimum capacity requirements for your selected instance type. For information about minimum license requirements, see the VCF subscriptions section in the Amazon EVS User Guide. 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. Not supported when vcfVersion is SELF_DEPLOYED.
    value:
      - solutionKey: "{{ solutionKey }}"
        vsanKey: "{{ vsanKey }}"
  - name: hosts
    description: |
      The ESX hosts to add to the environment. For each host, provide the desired hostname, EC2 SSH keypair name, and EC2 instance type. Optionally, provide a partition or cluster placement group, or use Amazon EC2 Dedicated Hosts. Not supported when vcfVersion is SELF_DEPLOYED. In that case, you can add hosts using CreateEnvironmentHost after the environment is created.
    value:
      - hostName: "{{ hostName }}"
        keyName: "{{ keyName }}"
        instanceType: "{{ instanceType }}"
        placementGroupId: "{{ placementGroupId }}"
        dedicatedHostId: "{{ dedicatedHostId }}"
  - name: vcfHostnames
    description: |
      The DNS hostnames for the virtual machines that host the VCF management appliances. Provide hostnames for vCenter, NSX Manager, SDDC Manager, and Cloud Builder. Not supported when vcfVersion is SELF_DEPLOYED.
    value:
      vCenter: "{{ vCenter }}"
      nsx: "{{ nsx }}"
      nsxManager1: "{{ nsxManager1 }}"
      nsxManager2: "{{ nsxManager2 }}"
      nsxManager3: "{{ nsxManager3 }}"
      nsxEdge1: "{{ nsxEdge1 }}"
      nsxEdge2: "{{ nsxEdge2 }}"
      sddcManager: "{{ sddcManager }}"
      cloudBuilder: "{{ cloudBuilder }}"
  - name: siteId
    value: "{{ siteId }}"
    description: |
      The Broadcom Site ID that is allocated to you as part of your electronic software delivery. This ID allows customer access to the Broadcom portal, and is provided to you by Broadcom at the close of your software contract or contract renewal. Amazon EVS uses the Broadcom Site ID that you provide to meet Broadcom VCF license usage reporting requirements for Amazon EVS. Not supported when vcfVersion is SELF_DEPLOYED.
  - name: environmentId
    value: "{{ environmentId }}"
    description: |
      A unique ID for the environment to create the entitlement in.
  - name: connectorId
    value: "{{ connectorId }}"
    description: |
      A unique ID for the connector associated with the entitlement.
  - name: entitlementType
    value: "{{ entitlementType }}"
    description: |
      The type of entitlement to create.
    valid_values: ['WINDOWS_SERVER']
  - name: vmIds
    value:
      - "{{ vmIds }}"
    description: |
      The list of VMware vSphere virtual machine managed object IDs to create entitlements for.

UPDATE examples

associate_eip_to_vlan

Associates an Elastic IP address with a public HCX VLAN. This operation is only allowed for public HCX VLANs at this time.

UPDATE aws.evs.environments
SET 
clientToken = '{{ clientToken }}',
environmentId = '{{ environmentId }}',
vlanName = '{{ vlanName }}',
allocationId = '{{ allocationId }}'
WHERE 
region = '{{ region }}' --required
AND environmentId = '{{ environmentId }}' --required
AND vlanName = '{{ vlanName }}' --required
AND allocationId = '{{ allocationId }}' --required
RETURNING
vlan;

disassociate_eip_from_vlan

Disassociates an Elastic IP address from a public HCX VLAN. This operation is only allowed for public HCX VLANs at this time.

UPDATE aws.evs.environments
SET 
clientToken = '{{ clientToken }}',
environmentId = '{{ environmentId }}',
vlanName = '{{ vlanName }}',
associationId = '{{ associationId }}'
WHERE 
region = '{{ region }}' --required
AND environmentId = '{{ environmentId }}' --required
AND vlanName = '{{ vlanName }}' --required
AND associationId = '{{ associationId }}' --required
RETURNING
vlan;

DELETE examples

delete_entitlement

Deletes a Windows Server License entitlement for virtual machines in an Amazon EVS environment. Deleting an entitlement stops usage tracking for the specified virtual machines.

DELETE FROM aws.evs.environments
WHERE region = '{{ region }}' --required
;

delete_environment

Deletes an Amazon EVS environment. Amazon EVS environments will only be enabled for deletion once the hosts are deleted. You can delete hosts using the DeleteEnvironmentHost action. Environment deletion also deletes the associated Amazon EVS VLAN subnets and Amazon Web Services Secrets Manager secrets that Amazon EVS created. Amazon Web Services resources that you create are not deleted. These resources may continue to incur costs.

DELETE FROM aws.evs.environments
WHERE region = '{{ region }}' --required
;