system_instances

Creates, updates, deletes, gets or lists a system_instances resource.

Overview

Name	system_instances
Type	Resource
Id	aws.iotthingsgraph.system_instances

Fields

The following fields are returned by SELECT queries:

get_system_instance

Name	Datatype	Description
definition	object	A document that defines an entity.
flow_actions_role_arn	string	The AWS Identity and Access Management (IAM) role that AWS IoT Things Graph assumes during flow execution in a cloud deployment. This role must have read and write permissionss to AWS Lambda and AWS IoT and to any other AWS services that the flow uses.
metrics_configuration	object	An object that specifies whether cloud metrics are collected in a deployment and, if so, what role is used to collect metrics.
s_3_bucket_name	string	The Amazon Simple Storage Service bucket where information about a system instance is stored.
summary	object	An object that contains summary information about a system instance.
validated_dependency_revisions	array	A list of objects that contain all of the IDs and revision numbers of workflows and systems that are used in a system instance.
validated_namespace_version	integer (int64)	The version of the user's namespace against which the system instance was validated.

search_system_instances

Name	Datatype	Description
id	string	The ID of the system instance. (pattern: <code>^urn:tdm:(([a-z]{2}-(gov-)?[a-z]{4,9}-[0-9]{1,3}/[0-9]+/)[\p{Alnum}]+(/[\p{Alnum}]+)):([\p{Alpha}]):([\p{Alnum}]+(/[\p{Alnum}]+))$</code>)
arn	string	The ARN of the system instance.
created_at	string (date-time)	The date when the system instance was created.
greengrass_group_id	string	The ID of the Greengrass group where the system instance is deployed.
greengrass_group_name	string	The ID of the Greengrass group where the system instance is deployed.
greengrass_group_version_id	string	The version of the Greengrass group where the system instance is deployed.
status	string	The status of the system instance. (NOT_DEPLOYED, BOOTSTRAP, DEPLOY_IN_PROGRESS, DEPLOYED_IN_TARGET, UNDEPLOY_IN_PROGRESS, FAILED, PENDING_DELETE, DELETED_IN_TARGET)
target	string	The target of the system instance. (GREENGRASS, CLOUD)
updated_at	string (date-time)	The date and time when the system instance was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_system_instance	select	region		Gets a system instance.
search_system_instances	select	region		Searches for system instances in the user's account.
create_system_instance	insert	region, definition, target		Creates a system instance. This action validates the system instance, prepares the deployment-related resources. For Greengrass deployments, it updates the Greengrass group that is specified by the greengrassGroupName parameter. It also adds a file to the S3 bucket specified by the s3BucketName parameter. You need to call DeploySystemInstance after running this action. For Greengrass deployments, since this action modifies and adds resources to a Greengrass group and an S3 bucket on the caller's behalf, the calling identity must have write permissions to both the specified Greengrass group and S3 bucket. Otherwise, the call will fail with an authorization error. For cloud deployments, this action requires a flowActionsRoleArn value. This is an IAM role that has permissions to access AWS services, such as AWS Lambda and AWS IoT, that the flow uses when it executes. If the definition document doesn't specify a version of the user's namespace, the latest version will be used by default.
delete_system_instance	delete	region		Deletes a system instance. Only system instances that have never been deployed, or that have been undeployed can be deleted. Users can create a new system instance that has the same ID as a deleted system instance.

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_system_instance

Gets a system instance.

SELECT
definition,
flow_actions_role_arn,
metrics_configuration,
s_3_bucket_name,
summary,
validated_dependency_revisions,
validated_namespace_version
FROM aws.iotthingsgraph.system_instances
WHERE region = '{{ region }}' -- required
;

search_system_instances

Searches for system instances in the user's account.

SELECT
id,
arn,
created_at,
greengrass_group_id,
greengrass_group_name,
greengrass_group_version_id,
status,
target,
updated_at
FROM aws.iotthingsgraph.system_instances
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_system_instance

Creates a system instance. This action validates the system instance, prepares the deployment-related resources. For Greengrass deployments, it updates the Greengrass group that is specified by the greengrassGroupName parameter. It also adds a file to the S3 bucket specified by the s3BucketName parameter. You need to call DeploySystemInstance after running this action. For Greengrass deployments, since this action modifies and adds resources to a Greengrass group and an S3 bucket on the caller's behalf, the calling identity must have write permissions to both the specified Greengrass group and S3 bucket. Otherwise, the call will fail with an authorization error. For cloud deployments, this action requires a flowActionsRoleArn value. This is an IAM role that has permissions to access AWS services, such as AWS Lambda and AWS IoT, that the flow uses when it executes. If the definition document doesn't specify a version of the user's namespace, the latest version will be used by default.

INSERT INTO aws.iotthingsgraph.system_instances (
tags,
definition,
target,
greengrassGroupName,
s3BucketName,
metricsConfiguration,
flowActionsRoleArn,
region
)
SELECT 
'{{ tags }}',
'{{ definition }}' /* required */,
'{{ target }}' /* required */,
'{{ greengrassGroupName }}',
'{{ s3BucketName }}',
'{{ metricsConfiguration }}',
'{{ flowActionsRoleArn }}',
'{{ region }}'
RETURNING
summary
;

Manifest

# Description fields are for documentation purposes
- name: system_instances
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the system_instances resource.
  - name: tags
    description: |
      Metadata, consisting of key-value pairs, that can be used to categorize your system instances.
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
  - name: definition
    description: |
      A document that defines an entity.
    value:
      language: "{{ language }}"
      text: "{{ text }}"
  - name: target
    value: "{{ target }}"
    description: |
      The target type of the deployment. Valid values are GREENGRASS and CLOUD.
    valid_values: ['GREENGRASS', 'CLOUD']
  - name: greengrassGroupName
    value: "{{ greengrassGroupName }}"
    description: |
      The name of the Greengrass group where the system instance will be deployed. This value is required if the value of the target parameter is GREENGRASS.
  - name: s3BucketName
    value: "{{ s3BucketName }}"
    description: |
      The name of the Amazon Simple Storage Service bucket that will be used to store and deploy the system instance's resource file. This value is required if the value of the target parameter is GREENGRASS.
  - name: metricsConfiguration
    description: |
      An object that specifies whether cloud metrics are collected in a deployment and, if so, what role is used to collect metrics.
    value:
      cloudMetricEnabled: {{ cloudMetricEnabled }}
      metricRuleRoleArn: "{{ metricRuleRoleArn }}"
  - name: flowActionsRoleArn
    value: "{{ flowActionsRoleArn }}"
    description: |
      The ARN of the IAM role that AWS IoT Things Graph will assume when it executes the flow. This role must have read and write access to AWS Lambda and AWS IoT and any other AWS services that the flow uses when it executes. This value is required if the value of the target parameter is CLOUD.

DELETE examples

delete_system_instance

Deletes a system instance. Only system instances that have never been deployed, or that have been undeployed can be deleted. Users can create a new system instance that has the same ID as a deleted system instance.

DELETE FROM aws.iotthingsgraph.system_instances
WHERE region = '{{ region }}' --required
;