Skip to main content

environments

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

Overview​

Nameenvironments
TypeResource
Idaws.proton.environments

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
namestringThe name of the environment. (pattern: <code>^[0-9A-Za-z]+[0-9A-Za-z_-]*$</code>)
arnstringThe Amazon Resource Name (ARN) of the environment.
codebuild_role_arnstringThe Amazon Resource Name (ARN) of the IAM service role that allows Proton to provision infrastructure using CodeBuild-based provisioning on your behalf. (pattern: <code>^arn:(aws|aws-cn|aws-us-gov):iam::\d{12}:role/([\w+=,.@-]{1,512}[/:])*([\w+=,.@-]{1,64})$</code>)
component_role_arnstringThe Amazon Resource Name (ARN) of the IAM service role that Proton uses when provisioning directly defined components in this environment. It determines the scope of infrastructure that a component can provision. The environment must have a componentRoleArn to allow directly defined components to be associated with the environment. For more information about components, see Proton components in the Proton User Guide. (pattern: <code>^arn:(aws|aws-cn|aws-us-gov):iam::\d{12}:role/([\w+=,.@-]{1,512}[/:])*([\w+=,.@-]{1,64})$</code>)
created_atstring (date-time)The time when the environment was created.
deployment_statusstringThe environment deployment status. (IN_PROGRESS, FAILED, SUCCEEDED, DELETE_IN_PROGRESS, DELETE_FAILED, DELETE_COMPLETE, CANCELLING, CANCELLED)
deployment_status_messagestringAn environment deployment status message.
descriptionstringThe description of the environment.
environment_account_connection_idstringThe ID of the environment account connection that's used to provision infrastructure resources in an environment account. (pattern: <code>^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$</code>)
environment_account_idstringThe ID of the environment account that the environment infrastructure resources are provisioned in. (pattern: <code>^\d{12}$</code>)
last_attempted_deployment_idstringThe ID of the last attempted deployment of this environment. (pattern: <code>^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$</code>)
last_deployment_attempted_atstring (date-time)The time when a deployment of the environment was last attempted.
last_deployment_succeeded_atstring (date-time)The time when the environment was last deployed successfully.
last_succeeded_deployment_idstringThe ID of the last successful deployment of this environment. (pattern: <code>^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$</code>)
proton_service_role_arnstringThe Amazon Resource Name (ARN) of the Proton service role that allows Proton to make calls to other services on your behalf. (pattern: <code>^arn:(aws|aws-cn|aws-us-gov):[a-zA-Z0-9-]+:[a-zA-Z0-9-]:\d{12}:([\w+=,.@-]+[/:])[\w+=,.@-]+$</code>)
provisioningstringWhen included, indicates that the environment template is for customer provisioned and managed infrastructure. (CUSTOMER_MANAGED)
provisioning_repositoryobjectThe linked repository that you use to host your rendered infrastructure templates for self-managed provisioning. A linked repository is a repository that has been registered with Proton. For more information, see CreateRepository.
specstringThe environment spec.
template_major_versionstringThe major version of the environment template. (pattern: <code>^(0|([1-9]{1}\d*))$</code>)
template_minor_versionstringThe minor version of the environment template. (pattern: <code>^(0|([1-9]{1}\d*))$</code>)
template_namestringThe Amazon Resource Name (ARN) of the environment template. (pattern: <code>^[0-9A-Za-z]+[0-9A-Za-z_-]*$</code>)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_environmentselectregionGet detailed data for an environment.
list_environmentsselectregionList environments with detail data summaries.
create_environmentinsertregion, name, spec, templateMajorVersion, templateNameDeploy a new environment. An Proton environment is created from an environment template that defines infrastructure and resources that can be shared across services. You can provision environments using the following methods: Amazon Web Services-managed provisioning: Proton makes direct calls to provision your resources. Self-managed provisioning: Proton makes pull requests on your repository to provide compiled infrastructure as code (IaC) files that your IaC engine uses to provision resources. For more information, see Environments and Provisioning methods in the Proton User Guide.
update_environmentupdateregion, deploymentType, nameUpdate an environment. If the environment is associated with an environment account connection, don't update or include the protonServiceRoleArn and provisioningRepository parameter to update or connect to an environment account connection. You can only update to a new environment account connection if that connection was created in the same environment account that the current environment account connection was created in. The account connection must also be associated with the current environment. If the environment isn't associated with an environment account connection, don't update or include the environmentAccountConnectionId parameter. You can't update or connect the environment to an environment account connection if it isn't already associated with an environment connection. You can update either the environmentAccountConnectionId or protonServiceRoleArn parameter and value. You can’t update both. If the environment was configured for Amazon Web Services-managed provisioning, omit the provisioningRepository parameter. If the environment was configured for self-managed provisioning, specify the provisioningRepository parameter and omit the protonServiceRoleArn and environmentAccountConnectionId parameters. For more information, see Environments and Provisioning methods in the Proton User Guide. There are four modes for updating an environment. The deploymentType field defines the mode. NONE In this mode, a deployment doesn't occur. Only the requested metadata parameters are updated. CURRENT_VERSION In this mode, the environment is deployed and updated with the new spec that you provide. Only requested parameters are updated. Don’t include minor or major version parameters when you use this deployment-type. MINOR_VERSION In this mode, the environment is deployed and updated with the published, recommended (latest) minor version of the current major version in use, by default. You can also specify a different minor version of the current major version in use. MAJOR_VERSION In this mode, the environment is deployed and updated with the published, recommended (latest) major and minor version of the current template, by default. You can also specify a different major version that's higher than the major version in use and a minor version.
delete_environmentdeleteregionDelete an environment.
accept_environment_account_connectionexecregion, idIn a management account, an environment account connection request is accepted. When the environment account connection request is accepted, Proton can use the associated IAM role to provision environment infrastructure resources in the associated environment account. For more information, see Environment account connections in the Proton User guide.
cancel_environment_deploymentexecregion, environmentNameAttempts to cancel an environment deployment on an UpdateEnvironment action, if the deployment is IN_PROGRESS. For more information, see Update an environment in the Proton User guide. The following list includes potential cancellation scenarios. If the cancellation attempt succeeds, the resulting deployment state is CANCELLED. If the cancellation attempt fails, the resulting deployment state is FAILED. If the current UpdateEnvironment action succeeds before the cancellation attempt starts, the resulting deployment state is SUCCEEDED and the cancellation attempt has no effect.
reject_environment_account_connectionexecregion, idIn a management account, reject an environment account connection from another environment account. After you reject an environment account connection request, you can't accept or use the rejected environment account connection. You can’t reject an environment account connection that's connected to an environment. For more information, see Environment account connections in the Proton User guide.

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.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Get detailed data for an environment.

SELECT
name,
arn,
codebuild_role_arn,
component_role_arn,
created_at,
deployment_status,
deployment_status_message,
description,
environment_account_connection_id,
environment_account_id,
last_attempted_deployment_id,
last_deployment_attempted_at,
last_deployment_succeeded_at,
last_succeeded_deployment_id,
proton_service_role_arn,
provisioning,
provisioning_repository,
spec,
template_major_version,
template_minor_version,
template_name
FROM aws.proton.environments
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Deploy a new environment. An Proton environment is created from an environment template that defines infrastructure and resources that can be shared across services. You can provision environments using the following methods: Amazon Web Services-managed provisioning: Proton makes direct calls to provision your resources. Self-managed provisioning: Proton makes pull requests on your repository to provide compiled infrastructure as code (IaC) files that your IaC engine uses to provision resources. For more information, see Environments and Provisioning methods in the Proton User Guide.

INSERT INTO aws.proton.environments (
codebuildRoleArn,
componentRoleArn,
description,
environmentAccountConnectionId,
name,
protonServiceRoleArn,
provisioningRepository,
spec,
tags,
templateMajorVersion,
templateMinorVersion,
templateName,
region
)
SELECT 
'{{ codebuildRoleArn }}',
'{{ componentRoleArn }}',
'{{ description }}',
'{{ environmentAccountConnectionId }}',
'{{ name }}' /* required */,
'{{ protonServiceRoleArn }}',
'{{ provisioningRepository }}',
'{{ spec }}' /* required */,
'{{ tags }}',
'{{ templateMajorVersion }}' /* required */,
'{{ templateMinorVersion }}',
'{{ templateName }}' /* required */,
'{{ region }}'
RETURNING
environment
;

UPDATE examples​

Update an environment. If the environment is associated with an environment account connection, don't update or include the protonServiceRoleArn and provisioningRepository parameter to update or connect to an environment account connection. You can only update to a new environment account connection if that connection was created in the same environment account that the current environment account connection was created in. The account connection must also be associated with the current environment. If the environment isn't associated with an environment account connection, don't update or include the environmentAccountConnectionId parameter. You can't update or connect the environment to an environment account connection if it isn't already associated with an environment connection. You can update either the environmentAccountConnectionId or protonServiceRoleArn parameter and value. You can’t update both. If the environment was configured for Amazon Web Services-managed provisioning, omit the provisioningRepository parameter. If the environment was configured for self-managed provisioning, specify the provisioningRepository parameter and omit the protonServiceRoleArn and environmentAccountConnectionId parameters. For more information, see Environments and Provisioning methods in the Proton User Guide. There are four modes for updating an environment. The deploymentType field defines the mode. NONE In this mode, a deployment doesn't occur. Only the requested metadata parameters are updated. CURRENT_VERSION In this mode, the environment is deployed and updated with the new spec that you provide. Only requested parameters are updated. Don’t include minor or major version parameters when you use this deployment-type. MINOR_VERSION In this mode, the environment is deployed and updated with the published, recommended (latest) minor version of the current major version in use, by default. You can also specify a different minor version of the current major version in use. MAJOR_VERSION In this mode, the environment is deployed and updated with the published, recommended (latest) major and minor version of the current template, by default. You can also specify a different major version that's higher than the major version in use and a minor version.

UPDATE aws.proton.environments
SET 
codebuildRoleArn = '{{ codebuildRoleArn }}',
componentRoleArn = '{{ componentRoleArn }}',
deploymentType = '{{ deploymentType }}',
description = '{{ description }}',
environmentAccountConnectionId = '{{ environmentAccountConnectionId }}',
name = '{{ name }}',
protonServiceRoleArn = '{{ protonServiceRoleArn }}',
provisioningRepository = '{{ provisioningRepository }}',
spec = '{{ spec }}',
templateMajorVersion = '{{ templateMajorVersion }}',
templateMinorVersion = '{{ templateMinorVersion }}'
WHERE 
region = '{{ region }}' --required
AND deploymentType = '{{ deploymentType }}' --required
AND name = '{{ name }}' --required
RETURNING
environment;

DELETE examples​

Delete an environment.

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

Lifecycle Methods​

In a management account, an environment account connection request is accepted. When the environment account connection request is accepted, Proton can use the associated IAM role to provision environment infrastructure resources in the associated environment account. For more information, see Environment account connections in the Proton User guide.

EXEC aws.proton.environments.accept_environment_account_connection 
@region='{{ region }}' --required 
@@json=
'{
"id": "{{ id }}"
}'
;
Last updated on