Skip to main content

associations

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

Overview​

Nameassociations
TypeResource
Idaws.ssm.associations

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
alarm_configurationobjectThe details for the CloudWatch alarm you want to apply to an automation or command.
apply_only_at_cron_intervalbooleanBy default, when you create a new associations, the system runs it immediately after it is created and then according to the schedule you specified. Specify this option if you don't want an association to run immediately after you create it. This parameter isn't supported for rate expressions.
association_dispatch_assume_rolestringA role used by association to take actions on your behalf. State Manager will assume this role and call required APIs when dispatching configurations to nodes. If not specified, service-linked role for Systems Manager will be used by default. (pattern: <code>arn:aws(-[^:]+)?:iam::[0-9]{12}:role/.+</code>)
association_idstringThe association ID. (pattern: <code>[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}</code>)
association_namestringThe association name. (pattern: <code>^[a-zA-Z0-9_-.]{3,128}$</code>)
association_versionstringThe association version. (pattern: <code>([$]LATEST)|([1-9][0-9]*)</code>)
automation_target_parameter_namestringChoose the parameter that will define how your automation will branch out. This target is required for associations that use an Automation runbook and target resources by using rate controls. Automation is a tool in Amazon Web Services Systems Manager.
calendar_namesarrayThe names or Amazon Resource Names (ARNs) of the Change Calendar type documents your associations are gated under. The associations only run when that change calendar is open. For more information, see Amazon Web Services Systems Manager Change Calendar in the Amazon Web Services Systems Manager User Guide.
compliance_severitystringThe severity level that is assigned to the association. (CRITICAL, HIGH, MEDIUM, LOW, UNSPECIFIED)
datestring (date-time)The date when the association was made.
document_versionstringThe document version. (pattern: <code>([$]LATEST|[$]DEFAULT|^[1-9][0-9]*$)</code>)
durationintegerThe number of hours that an association can run on specified targets. After the resulting cutoff time passes, associations that are currently running are cancelled, and no pending executions are started on remaining targets.
instance_idstringThe managed node ID. (pattern: <code>(^i-(\w{8}|\w{17})$)|(^mi-\w{17}$)</code>)
last_execution_datestring (date-time)The date on which the association was last run.
last_successful_execution_datestring (date-time)The last date on which the association was successfully run.
last_update_association_datestring (date-time)The date when the association was last updated.
max_concurrencystringThe maximum number of targets allowed to run the association at the same time. You can specify a number, for example 10, or a percentage of the target set, for example 10%. The default value is 100%, which means all targets run the association at the same time. If a new managed node starts and attempts to run an association while Systems Manager is running MaxConcurrency associations, the association is allowed to run. During the next association interval, the new managed node will process its association within the limit specified for MaxConcurrency. (pattern: <code>^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$</code>)
max_errorsstringThe number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops sending requests when the fourth error is received. If you specify 0, then the system stops sending requests after the first error is returned. If you run an association on 50 managed nodes and set MaxError to 10%, then the system stops sending the request when the sixth error is received. Executions that are already running an association when MaxErrors is reached are allowed to complete, but some of these executions may fail as well. If you need to ensure that there won't be more than max-errors failed executions, set MaxConcurrency to 1 so that executions proceed one at a time. (pattern: <code>^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$</code>)
namestringThe name of the SSM document. (pattern: <code>^[a-zA-Z0-9_-.:/]{3,128}$</code>)
output_locationobjectAn S3 bucket where you want to store the output details of the request.
overviewobjectInformation about the association.
parametersobjectA description of the parameters for a document.
schedule_expressionstringA cron expression that specifies a schedule when the association runs.
schedule_offsetintegerNumber of days to wait after the scheduled day to run an association.
statusobjectThe association status.
sync_compliancestringThe mode for generating association compliance. You can specify AUTO or MANUAL. In AUTO mode, the system uses the status of the association execution to determine the compliance status. If the association execution runs successfully, then the association is COMPLIANT. If the association execution doesn't run successfully, the association is NON-COMPLIANT. In MANUAL mode, you must specify the AssociationId as a parameter for the PutComplianceItems API operation. In this case, compliance data isn't managed by State Manager, a tool in Amazon Web Services Systems Manager. It is managed by your direct call to the PutComplianceItems API operation. By default, all associations use AUTO mode. (AUTO, MANUAL)
target_locationsarrayThe combination of Amazon Web Services Regions and Amazon Web Services accounts where you want to run the association.
target_mapsarrayA key-value mapping of document parameters to target resources. Both Targets and TargetMaps can't be specified together.
targetsarrayThe managed nodes targeted by the request.
triggered_alarmsarrayThe CloudWatch alarm that was invoked during the association.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_associationselectregionDescribes the association for the specified target or managed node. If you created the association by using the Targets parameter, then you must retrieve the association by using the association ID.
list_associationsselectregionReturns all State Manager associations in the current Amazon Web Services account and Amazon Web Services Region. You can limit the results to a specific State Manager association document or managed node by specifying a filter. State Manager is a tool in Amazon Web Services Systems Manager.
create_association_batchinsertregion, EntriesAssociates the specified Amazon Web Services Systems Manager document (SSM document) with the specified managed nodes or targets. When you associate a document with one or more managed nodes using IDs or tags, Amazon Web Services Systems Manager Agent (SSM Agent) running on the managed node processes the document and configures the node as specified. If you associate a document with a managed node that already has an associated document, the system returns the AssociationAlreadyExists exception.
create_associationinsertregionA State Manager association defines the state that you want to maintain on your managed nodes. For example, an association can specify that anti-virus software must be installed and running on your managed nodes, or that certain ports must be closed. For static targets, the association specifies a schedule for when the configuration is reapplied. For dynamic targets, such as an Amazon Web Services resource group or an Amazon Web Services autoscaling group, State Manager, a tool in Amazon Web Services Systems Manager applies the configuration when new managed nodes are added to the group. The association also specifies actions to take when applying the configuration. For example, an association for anti-virus software might run once a day. If the software isn't installed, then State Manager installs it. If the software is installed, but the service isn't running, then the association might instruct State Manager to start the service.
update_association_statusupdateregion, InstanceId, AssociationStatusUpdates the status of the Amazon Web Services Systems Manager document (SSM document) associated with the specified managed node. UpdateAssociationStatus is primarily used by the Amazon Web Services Systems Manager Agent (SSM Agent) to report status updates about your associations and is only used for associations created with the InstanceId legacy parameter.
update_associationupdateregion, AssociationIdUpdates an association. You can update the association name and version, the document version, schedule, parameters, and Amazon Simple Storage Service (Amazon S3) output. When you call UpdateAssociation, the system removes all optional parameters from the request and overwrites the association with null values for those parameters. This is by design. You must specify all optional parameters in the call, even if you are not changing the parameters. This includes the Name parameter. Before calling this API action, we recommend that you call the DescribeAssociation API operation and make a note of all optional parameters required for your UpdateAssociation call. In order to call this API operation, a user, group, or role must be granted permission to call the DescribeAssociation API operation. If you don't have permission to call DescribeAssociation, then you receive the following error: An error occurred (AccessDeniedException) when calling the UpdateAssociation operation: User: <user_arn> isn't authorized to perform: ssm:DescribeAssociation on resource: <resource_arn> When you update an association, the association immediately runs against the specified targets. You can add the ApplyOnlyAtCronInterval parameter to run the association during the next schedule run.
delete_associationdeleteregionDisassociates the specified Amazon Web Services Systems Manager document (SSM document) from the specified managed node. If you created the association by using the Targets parameter, then you must delete the association by using the association ID. When you disassociate a document from a managed node, it doesn't change the configuration of the node. To change the configuration state of a managed node after you disassociate a document, you must create a new document with the desired configuration and associate it with the node.
start_associations_onceexecregion, AssociationIdsRuns an association immediately and only one time. This operation can be helpful when troubleshooting associations.

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​

Describes the association for the specified target or managed node. If you created the association by using the Targets parameter, then you must retrieve the association by using the association ID.

SELECT
alarm_configuration,
apply_only_at_cron_interval,
association_dispatch_assume_role,
association_id,
association_name,
association_version,
automation_target_parameter_name,
calendar_names,
compliance_severity,
date,
document_version,
duration,
instance_id,
last_execution_date,
last_successful_execution_date,
last_update_association_date,
max_concurrency,
max_errors,
name,
output_location,
overview,
parameters,
schedule_expression,
schedule_offset,
status,
sync_compliance,
target_locations,
target_maps,
targets,
triggered_alarms
FROM aws.ssm.associations
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Associates the specified Amazon Web Services Systems Manager document (SSM document) with the specified managed nodes or targets. When you associate a document with one or more managed nodes using IDs or tags, Amazon Web Services Systems Manager Agent (SSM Agent) running on the managed node processes the document and configures the node as specified. If you associate a document with a managed node that already has an associated document, the system returns the AssociationAlreadyExists exception.

INSERT INTO aws.ssm.associations (
Entries,
AssociationDispatchAssumeRole,
region
)
SELECT 
'{{ Entries }}' /* required */,
'{{ AssociationDispatchAssumeRole }}',
'{{ region }}'
RETURNING
failed,
successful
;

UPDATE examples​

Updates the status of the Amazon Web Services Systems Manager document (SSM document) associated with the specified managed node. UpdateAssociationStatus is primarily used by the Amazon Web Services Systems Manager Agent (SSM Agent) to report status updates about your associations and is only used for associations created with the InstanceId legacy parameter.

UPDATE aws.ssm.associations
SET 
Name = '{{ Name }}',
InstanceId = '{{ InstanceId }}',
AssociationStatus = '{{ AssociationStatus }}'
WHERE 
region = '{{ region }}' --required
AND InstanceId = '{{ InstanceId }}' --required
AND AssociationStatus = '{{ AssociationStatus }}' --required
RETURNING
association_description;

DELETE examples​

Disassociates the specified Amazon Web Services Systems Manager document (SSM document) from the specified managed node. If you created the association by using the Targets parameter, then you must delete the association by using the association ID. When you disassociate a document from a managed node, it doesn't change the configuration of the node. To change the configuration state of a managed node after you disassociate a document, you must create a new document with the desired configuration and associate it with the node.

DELETE FROM aws.ssm.associations
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Runs an association immediately and only one time. This operation can be helpful when troubleshooting associations.

EXEC aws.ssm.associations.start_associations_once 
@region='{{ region }}' --required 
@@json=
'{
"AssociationIds": "{{ AssociationIds }}"
}'
;
Last updated on