@pulumi/aws

import * as pulumi from "@pulumi/pulumi"; import * as inputs from "../types/input"; import * as outputs from "../types/output"; /** * Associates an SSM Document to an instance or EC2 tag. * * ## Example Usage * * ### Create an association for a specific instance * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * * const example = new aws.ssm.Association("example", { * name: exampleAwsSsmDocument.name, * targets: [{ * key: "InstanceIds", * values: [exampleAwsInstance.id], * }], * }); * ``` * * ### 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`. * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * * const example = new aws.ssm.Association("example", { * name: "AmazonCloudWatch-ManageAgent", * targets: [{ * key: "InstanceIds", * values: ["*"], * }], * }); * ``` * * ### 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`. * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * * const example = new aws.ssm.Association("example", { * name: "AmazonCloudWatch-ManageAgent", * targets: [{ * key: "tag:Environment", * values: ["Development"], * }], * }); * ``` * * ### Create an association with a specific schedule * * This example shows how to schedule an association in various ways. * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * * const example = new aws.ssm.Association("example", { * name: exampleAwsSsmDocument.name, * scheduleExpression: "cron(0 2 ? * SUN *)", * targets: [{ * key: "InstanceIds", * values: [exampleAwsInstance.id], * }], * }); * ``` * * ### Create an association with multiple instances with their instance ids * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * import * as std from "@pulumi/std"; * * // First EC2 instance * const webServer1 = new aws.ec2.Instance("web_server_1", { * ami: amazonLinux.id, * instanceType: aws.ec2.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 * `, * }); * // Second EC2 instance * const webServer2 = new aws.ec2.Instance("web_server_2", { * ami: amazonLinux.id, * instanceType: aws.ec2.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 * `, * }); * // Removed EC2 provisioning dependencies for brevity * const systemUpdate = new aws.ssm.Association("system_update", { * name: "AWS-RunShellScript", * targets: [{ * key: "InstanceIds", * values: [ * webServer1.id, * webServer2.id, * ], * }], * scheduleExpression: "cron(0 2 ? * SUN *)", * parameters: { * commands: std.join({ * separator: "\n", * 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", * ], * }).then(invoke => invoke.result), * workingDirectory: "/tmp", * executionTimeout: "3600", * }, * associationName: "weekly-system-update", * complianceSeverity: "MEDIUM", * maxConcurrency: "1", * maxErrors: "0", * tags: { * Name: "Weekly System Update", * Environment: "demo", * Purpose: "maintenance", * }, * }); * ``` * * ### Create an association with multiple instances with their values matching their tags * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as aws from "@pulumi/aws"; * import * as std from "@pulumi/std"; * * // SSM Association for Webbased Servers * const databaseAssociation = new aws.ssm.Association("database_association", { * name: systemUpdate.name, * targets: [{ * key: "tag:Role", * values: [ * "WebServer", * "Database", * ], * }], * parameters: { * restartServices: "true", * }, * scheduleExpression: "cron(0 3 ? * SUN *)", * }); * // EC2 Instance 1 - Web Server with "ServerType" tag * const webServer = new aws.ec2.Instance("web_server", { * ami: amazonLinux.id, * instanceType: aws.ec2.InstanceType.T3_Micro, * subnetId: _default.id, * vpcSecurityGroupIds: [ec2Sg.id], * iamInstanceProfile: ec2SsmProfile.name, * userData: std.base64encode({ * 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 - ${prefix}</h1>" > /var/www/html/index.html * `, * }).then(invoke => invoke.result), * tags: { * Name: `${prefix}-web-server`, * ServerType: "WebServer", * Role: "WebServer", * Environment: environment, * Owner: owner, * }, * }); * // EC2 Instance 2 - Database Server with "Role" tag * const databaseServer = new aws.ec2.Instance("database_server", { * ami: amazonLinux.id, * instanceType: aws.ec2.InstanceType.T3_Micro, * subnetId: _default.id, * vpcSecurityGroupIds: [ec2Sg.id], * iamInstanceProfile: ec2SsmProfile.name, * userData: std.base64encode({ * 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 * `, * }).then(invoke => invoke.result), * tags: { * Name: `${prefix}-database-server`, * Role: "Database", * Environment: environment, * Owner: owner, * }, * }); * ``` * * ## Import * * Using `pulumi import`, import SSM associations using the `association_id`. For example: * * ```sh * $ pulumi import aws:ssm/association:Association test-association 10abcdef-0abc-1234-5678-90abcdef123456 * ``` */ export declare class Association extends pulumi.CustomResource { /** * Get an existing Association resource's state with the given name, ID, and optional extra * properties used to qualify the lookup. * * @param name The _unique_ name of the resulting resource. * @param id The _unique_ provider ID of the resource to lookup. * @param state Any extra arguments used during the lookup. * @param opts Optional settings to control the behavior of the CustomResource. */ static get(name: string, id: pulumi.Input<pulumi.ID>, state?: AssociationState, opts?: pulumi.CustomResourceOptions): Association; /** * Returns true if the given object is an instance of Association. This is designed to work even * when multiple copies of the Pulumi SDK have been loaded into the same process. */ static isInstance(obj: any): obj is Association; /** * 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`. */ readonly applyOnlyAtCronInterval: pulumi.Output<boolean | undefined>; /** * The ARN of the SSM association */ readonly arn: pulumi.Output<string>; /** * The ID of the SSM association. */ readonly associationId: pulumi.Output<string>; /** * The descriptive name for the association. */ readonly associationName: pulumi.Output<string | undefined>; /** * 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. */ readonly automationTargetParameterName: pulumi.Output<string | undefined>; /** * The compliance severity for the association. Can be one of the following: `UNSPECIFIED`, `LOW`, `MEDIUM`, `HIGH` or `CRITICAL` */ readonly complianceSeverity: pulumi.Output<string | undefined>; /** * The document version you want to associate with the target(s). Can be a specific version or the default version. */ readonly documentVersion: pulumi.Output<string>; /** * 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%. */ readonly maxConcurrency: pulumi.Output<string | undefined>; /** * 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. */ readonly maxErrors: pulumi.Output<string | undefined>; /** * The name of the SSM document to apply. */ readonly name: pulumi.Output<string>; /** * An output location block. Output Location is documented below. */ readonly outputLocation: pulumi.Output<outputs.ssm.AssociationOutputLocation | undefined>; /** * A block of arbitrary string parameters to pass to the SSM document. */ readonly parameters: pulumi.Output<{ [key: string]: string; }>; /** * 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. */ readonly region: pulumi.Output<string>; /** * 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. */ readonly scheduleExpression: pulumi.Output<string | undefined>; /** * The mode for generating association compliance. You can specify `AUTO` or `MANUAL`. */ readonly syncCompliance: pulumi.Output<string | undefined>; /** * 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. */ readonly tags: pulumi.Output<{ [key: string]: string; } | undefined>; /** * A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block. */ readonly tagsAll: pulumi.Output<{ [key: string]: string; }>; /** * A block containing the targets of the SSM association. Targets are documented below. AWS currently supports a maximum of 5 targets. */ readonly targets: pulumi.Output<outputs.ssm.AssociationTarget[]>; /** * The number of seconds to wait for the association status to be `Success`. If `Success` status is not reached within the given time, create opration will fail. * * Output Location (`outputLocation`) is an S3 bucket where you want to store the results of this association: */ readonly waitForSuccessTimeoutSeconds: pulumi.Output<number | undefined>; /** * Create a Association resource with the given unique name, arguments, and options. * * @param name The _unique_ name of the resource. * @param args The arguments to use to populate this resource's properties. * @param opts A bag of options that control this resource's behavior. */ constructor(name: string, args?: AssociationArgs, opts?: pulumi.CustomResourceOptions); } /** * Input properties used for looking up and filtering Association resources. */ export interface AssociationState { /** * 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`. */ applyOnlyAtCronInterval?: pulumi.Input<boolean>; /** * The ARN of the SSM association */ arn?: pulumi.Input<string>; /** * The ID of the SSM association. */ associationId?: pulumi.Input<string>; /** * The descriptive name for the association. */ associationName?: pulumi.Input<string>; /** * 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. */ automationTargetParameterName?: pulumi.Input<string>; /** * The compliance severity for the association. Can be one of the following: `UNSPECIFIED`, `LOW`, `MEDIUM`, `HIGH` or `CRITICAL` */ complianceSeverity?: pulumi.Input<string>; /** * The document version you want to associate with the target(s). Can be a specific version or the default version. */ documentVersion?: pulumi.Input<string>; /** * 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%. */ maxConcurrency?: pulumi.Input<string>; /** * 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. */ maxErrors?: pulumi.Input<string>; /** * The name of the SSM document to apply. */ name?: pulumi.Input<string>; /** * An output location block. Output Location is documented below. */ outputLocation?: pulumi.Input<inputs.ssm.AssociationOutputLocation>; /** * A block of arbitrary string parameters to pass to the SSM document. */ parameters?: pulumi.Input<{ [key: string]: pulumi.Input<string>; }>; /** * 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. */ region?: pulumi.Input<string>; /** * 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. */ scheduleExpression?: pulumi.Input<string>; /** * The mode for generating association compliance. You can specify `AUTO` or `MANUAL`. */ syncCompliance?: pulumi.Input<string>; /** * 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. */ tags?: pulumi.Input<{ [key: string]: pulumi.Input<string>; }>; /** * A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block. */ tagsAll?: pulumi.Input<{ [key: string]: pulumi.Input<string>; }>; /** * A block containing the targets of the SSM association. Targets are documented below. AWS currently supports a maximum of 5 targets. */ targets?: pulumi.Input<pulumi.Input<inputs.ssm.AssociationTarget>[]>; /** * The number of seconds to wait for the association status to be `Success`. If `Success` status is not reached within the given time, create opration will fail. * * Output Location (`outputLocation`) is an S3 bucket where you want to store the results of this association: */ waitForSuccessTimeoutSeconds?: pulumi.Input<number>; } /** * The set of arguments for constructing a Association resource. */ export interface AssociationArgs { /** * 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`. */ applyOnlyAtCronInterval?: pulumi.Input<boolean>; /** * The descriptive name for the association. */ associationName?: pulumi.Input<string>; /** * 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. */ automationTargetParameterName?: pulumi.Input<string>; /** * The compliance severity for the association. Can be one of the following: `UNSPECIFIED`, `LOW`, `MEDIUM`, `HIGH` or `CRITICAL` */ complianceSeverity?: pulumi.Input<string>; /** * The document version you want to associate with the target(s). Can be a specific version or the default version. */ documentVersion?: pulumi.Input<string>; /** * 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%. */ maxConcurrency?: pulumi.Input<string>; /** * 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. */ maxErrors?: pulumi.Input<string>; /** * The name of the SSM document to apply. */ name?: pulumi.Input<string>; /** * An output location block. Output Location is documented below. */ outputLocation?: pulumi.Input<inputs.ssm.AssociationOutputLocation>; /** * A block of arbitrary string parameters to pass to the SSM document. */ parameters?: pulumi.Input<{ [key: string]: pulumi.Input<string>; }>; /** * 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. */ region?: pulumi.Input<string>; /** * 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. */ scheduleExpression?: pulumi.Input<string>; /** * The mode for generating association compliance. You can specify `AUTO` or `MANUAL`. */ syncCompliance?: pulumi.Input<string>; /** * 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. */ tags?: pulumi.Input<{ [key: string]: pulumi.Input<string>; }>; /** * A block containing the targets of the SSM association. Targets are documented below. AWS currently supports a maximum of 5 targets. */ targets?: pulumi.Input<pulumi.Input<inputs.ssm.AssociationTarget>[]>; /** * The number of seconds to wait for the association status to be `Success`. If `Success` status is not reached within the given time, create opration will fail. * * Output Location (`outputLocation`) is an S3 bucket where you want to store the results of this association: */ waitForSuccessTimeoutSeconds?: pulumi.Input<number>; }