Package com.pulumi.aws.ssm

Class Association

  • public class Association
extends com.pulumi.resources.CustomResource
    Associates an SSM Document to an instance or EC2 tag. ## Example Usage ### Create an association for a specific instance 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new Association("example", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("InstanceIds")
                 .values(exampleAwsInstance.id())
                 .build())
             .name(exampleAwsSsmDocument.name())
             .build());
 
     }
 }
    ### Create an association for all managed instances in an AWS account To target all managed instances in an AWS account, set the `key` as `"InstanceIds"` with `values` set as `["*"]`. This example also illustrates how to use an Amazon owned SSM document named `AmazonCloudWatch-ManageAgent`. 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new Association("example", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("InstanceIds")
                 .values("*")
                 .build())
             .name("AmazonCloudWatch-ManageAgent")
             .build());
 
     }
 }
    ### Create an association for a specific tag This example shows how to target all managed instances that are assigned a tag key of `Environment` and value of `Development`. 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new Association("example", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("tag:Environment")
                 .values("Development")
                 .build())
             .name("AmazonCloudWatch-ManageAgent")
             .build());
 
     }
 }
    ### Create an association with a specific schedule This example shows how to schedule an association in various ways. 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new Association("example", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("InstanceIds")
                 .values(exampleAwsInstance.id())
                 .build())
             .name(exampleAwsSsmDocument.name())
             .scheduleExpression("cron(0 2 ? * SUN *)")
             .build());
 
     }
 }
    ### Create an association with multiple instances with their instance IDs 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ec2.Instance;
 import com.pulumi.aws.ec2.InstanceArgs;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import com.pulumi.std.StdFunctions;
 import com.pulumi.std.inputs.JoinArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         // First EC2 instance
         var webServer1 = new Instance("webServer1", InstanceArgs.builder()
             .ami(amazonLinux.id())
             .instanceType("t3.micro")
             .subnetId(public_.id())
             .vpcSecurityGroupIds(ec2Sg.id())
             .iamInstanceProfile(ec2SsmProfile.name())
             .userData("""
 #!/bin/bash
 yum update -y
 yum install -y amazon-ssm-agent
 systemctl enable amazon-ssm-agent
 systemctl start amazon-ssm-agent
             """)
             .build());
 
         // Second EC2 instance
         var webServer2 = new Instance("webServer2", InstanceArgs.builder()
             .ami(amazonLinux.id())
             .instanceType("t3.micro")
             .subnetId(public_.id())
             .vpcSecurityGroupIds(ec2Sg.id())
             .iamInstanceProfile(ec2SsmProfile.name())
             .userData("""
 #!/bin/bash
 yum update -y
 yum install -y amazon-ssm-agent
 systemctl enable amazon-ssm-agent
 systemctl start amazon-ssm-agent
             """)
             .build());
 
         // Removed EC2 provisioning dependencies for brevity
         var systemUpdate = new Association("systemUpdate", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("InstanceIds")
                 .values(                
                     webServer1.id(),
                     webServer2.id())
                 .build())
             .name("AWS-RunShellScript")
             .scheduleExpression("cron(0 2 ? * SUN *)")
             .parameters(Map.ofEntries(
                 Map.entry("commands", StdFunctions.join(JoinArgs.builder()
                     .separator("""
 
                     """)
                     .input(                    
                         "#!/bin/bash",
                         "echo 'Starting system update on $(hostname)'",
                         "echo 'Instance ID: $(curl -s http://169.254.169.254/latest/meta-data/instance-id)'",
                         "yum update -y",
                         "echo 'System update completed successfully'",
                         "systemctl status httpd",
                         "df -h",
                         "free -m")
                     .build()).result()),
                 Map.entry("workingDirectory", "/tmp"),
                 Map.entry("executionTimeout", "3600")
             ))
             .associationName("weekly-system-update")
             .complianceSeverity("MEDIUM")
             .maxConcurrency("1")
             .maxErrors("0")
             .tags(Map.ofEntries(
                 Map.entry("Name", "Weekly System Update"),
                 Map.entry("Environment", "demo"),
                 Map.entry("Purpose", "maintenance")
             ))
             .build());
 
     }
 }
    ### Create an association with multiple instances with their values matching their tags 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.ssm.Association;
 import com.pulumi.aws.ssm.AssociationArgs;
 import com.pulumi.aws.ssm.inputs.AssociationTargetArgs;
 import com.pulumi.aws.ec2.Instance;
 import com.pulumi.aws.ec2.InstanceArgs;
 import com.pulumi.std.StdFunctions;
 import com.pulumi.std.inputs.Base64encodeArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         // SSM Association for Webbased Servers
         var databaseAssociation = new Association("databaseAssociation", AssociationArgs.builder()
             .targets(AssociationTargetArgs.builder()
                 .key("tag:Role")
                 .values(                
                     "WebServer",
                     "Database")
                 .build())
             .name(systemUpdate.name())
             .parameters(Map.of("restartServices", "true"))
             .scheduleExpression("cron(0 3 ? * SUN *)")
             .build());
 
         // EC2 Instance 1 - Web Server with "ServerType" tag
         var webServer = new Instance("webServer", InstanceArgs.builder()
             .ami(amazonLinux.id())
             .instanceType("t3.micro")
             .subnetId(default_.id())
             .vpcSecurityGroupIds(ec2Sg.id())
             .iamInstanceProfile(ec2SsmProfile.name())
             .userData(StdFunctions.base64encode(Base64encodeArgs.builder()
                 .input("""
 #!/bin/bash
 yum update -y
 yum install -y amazon-ssm-agent
 systemctl enable amazon-ssm-agent
 systemctl start amazon-ssm-agent
     
 # Install Apache web server
 yum install -y httpd
 systemctl enable httpd
 systemctl start httpd
 echo \"<h1>Web Server - %s</h1>\" > /var/www/html/index.html
 ", prefix))
                 .build()).result())
             .tags(Map.ofEntries(
                 Map.entry("Name", String.format("%s-web-server", prefix)),
                 Map.entry("ServerType", "WebServer"),
                 Map.entry("Role", "WebServer"),
                 Map.entry("Environment", environment),
                 Map.entry("Owner", owner)
             ))
             .build());
 
         // EC2 Instance 2 - Database Server with "Role" tag
         var databaseServer = new Instance("databaseServer", InstanceArgs.builder()
             .ami(amazonLinux.id())
             .instanceType("t3.micro")
             .subnetId(default_.id())
             .vpcSecurityGroupIds(ec2Sg.id())
             .iamInstanceProfile(ec2SsmProfile.name())
             .userData(StdFunctions.base64encode(Base64encodeArgs.builder()
                 .input("""
 #!/bin/bash
 yum update -y
 yum install -y amazon-ssm-agent
 systemctl enable amazon-ssm-agent
 systemctl start amazon-ssm-agent
     
 # Install MySQL
 yum install -y mysql-server
 systemctl enable mysqld
 systemctl start mysqld
                 """)
                 .build()).result())
             .tags(Map.ofEntries(
                 Map.entry("Name", String.format("%s-database-server", prefix)),
                 Map.entry("Role", "Database"),
                 Map.entry("Environment", environment),
                 Map.entry("Owner", owner)
             ))
             .build());
 
     }
 }
    ## Import ### Identity Schema #### Required * `associationId` - (String) ID of the SSM association. #### Optional * `accountId` (String) AWS Account where this resource is managed. * `region` (String) Region where this resource is managed. Using `pulumi import`, import SSM associations using the `associationId`. For example: ```sh $ pulumi import aws:ssm/association:Association example 10abcdef-0abc-1234-5678-90abcdef123456 ```

    • Nested Class Summary

      • Nested classes/interfaces inherited from class com.pulumi.resources.CustomResource

        com.pulumi.resources.CustomResource.CustomResourceInternal

      • Nested classes/interfaces inherited from class com.pulumi.resources.Resource

        com.pulumi.resources.Resource.LazyField<T extends java.lang.Object>, com.pulumi.resources.Resource.LazyFields, com.pulumi.resources.Resource.ResourceInternal

    • Field Summary

      • Fields inherited from class com.pulumi.resources.Resource

        childResources, remote

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> applyOnlyAtCronInterval()  
      com.pulumi.core.Output<java.lang.String> arn()  
      com.pulumi.core.Output<java.lang.String> associationId()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> associationName()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> automationTargetParameterName()  
      com.pulumi.core.Output<java.util.Optional<java.util.List<java.lang.String>>> calendarNames()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> complianceSeverity()  
      com.pulumi.core.Output<java.lang.String> documentVersion()  
      static Association get​(java.lang.String name, com.pulumi.core.Output<java.lang.String> id, AssociationState state, com.pulumi.resources.CustomResourceOptions options)
      Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> maxConcurrency()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> maxErrors()  
      com.pulumi.core.Output<java.lang.String> name()  
      com.pulumi.core.Output<java.util.Optional<AssociationOutputLocation>> outputLocation()  
      com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> parameters()  
      com.pulumi.core.Output<java.lang.String> region()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> scheduleExpression()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> syncCompliance()  
      com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()  
      com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()  
      com.pulumi.core.Output<java.util.List<AssociationTarget>> targets()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> waitForSuccessTimeoutSeconds()  

      • Methods inherited from class com.pulumi.resources.CustomResource

        getId, id, idFuture

      • Methods inherited from class com.pulumi.resources.Resource

        getChildResources, getResourceName, getResourceType, getUrn, pulumiChildResources, pulumiResourceName, pulumiResourceType, urn

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Association

        public Association​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.

      • Association

        public Association​(java.lang.String name,
                   @Nullable
                   AssociationArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.

      • Association

        public Association​(java.lang.String name,
                   @Nullable
                   AssociationArgs args,
                   @Nullable
                   com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.

    • Method Detail

      • applyOnlyAtCronInterval

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> applyOnlyAtCronInterval()
        Returns:
        By default, when you create a new or update associations, the system runs it immediately and then according to the schedule you specified. Enable this option if you do not want an association to run immediately after you create or update it. This parameter is not supported for rate expressions. Default: `false`.

      • arn

        public com.pulumi.core.Output<java.lang.String> arn()
        Returns:
        The ARN of the SSM association

      • associationId

        public com.pulumi.core.Output<java.lang.String> associationId()
        Returns:
        The ID of the SSM association.

      • associationName

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> associationName()
        Returns:
        The descriptive name for the association.

      • automationTargetParameterName

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> automationTargetParameterName()
        Returns:
        Specify the target for the association. This target is required for associations that use an `Automation` document and target resources by using rate controls. This should be set to the SSM document `parameter` that will define how your automation will branch out.

      • calendarNames

        public com.pulumi.core.Output<java.util.Optional<java.util.List<java.lang.String>>> calendarNames()
        Returns:
        One or more Systems Manager Change Calendar names. The association runs only when the Change Calendar is open.

      • complianceSeverity

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> complianceSeverity()
        Returns:
        The compliance severity for the association. Can be one of the following: `UNSPECIFIED`, `LOW`, `MEDIUM`, `HIGH` or `CRITICAL`

      • documentVersion

        public com.pulumi.core.Output<java.lang.String> documentVersion()
        Returns:
        The document version you want to associate with the target(s). Can be a specific version or the default version.

      • maxConcurrency

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> maxConcurrency()
        Returns:
        The 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%.

      • maxErrors

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> maxErrors()
        Returns:
        The number of errors that are allowed before the system stops sending requests to run the association on additional targets. You can specify a number, for example 10, or a percentage of the target set, for example 10%. If you specify a threshold of 3, the stop command is sent when the fourth error is returned. If you specify a threshold of 10% for 50 associations, the stop command is sent when the sixth error is returned.

      • name

        public com.pulumi.core.Output<java.lang.String> name()
        Returns:
        The name of the SSM document to apply.

      • outputLocation

        public com.pulumi.core.Output<java.util.Optional<AssociationOutputLocation>> outputLocation()
        Returns:
        An output location block. Output Location is documented below.

      • parameters

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> parameters()
        Returns:
        A block of arbitrary string parameters to pass to the SSM document.

      • region

        public com.pulumi.core.Output<java.lang.String> region()
        Returns:
        Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.

      • scheduleExpression

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> scheduleExpression()
        Returns:
        A [cron or rate expression](https://docs.aws.amazon.com/systems-manager/latest/userguide/reference-cron-and-rate-expressions.html) that specifies when the association runs.

      • syncCompliance

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> syncCompliance()
        Returns:
        The mode for generating association compliance. You can specify `AUTO` or `MANUAL`.

      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()
        Returns:
        A map of tags to assign to the object. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.

      • tagsAll

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()
        Returns:
        A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.

      • targets

        public com.pulumi.core.Output<java.util.List<AssociationTarget>> targets()
        Returns:
        A block containing the targets of the SSM association. Targets are documented below. AWS currently supports a maximum of 5 targets.

      • waitForSuccessTimeoutSeconds

        public com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> waitForSuccessTimeoutSeconds()
        Returns:
        The number of seconds to wait for the association status to be `Success`. If `Success` status is not reached within the given time, create operation will fail. Output Location (`outputLocation`) is an S3 bucket where you want to store the results of this association:

      • get

        public static Association get​(java.lang.String name,
                              com.pulumi.core.Output<java.lang.String> id,
                              @Nullable
                              AssociationState state,
                              @Nullable
                              com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.