amazonka-ssm-1.4.0: Amazon Simple Systems Management Service SDK.

Copyright(c) 2013-2016 Brendan Hay
LicenseMozilla Public License, v. 2.0.
MaintainerBrendan Hay <brendan.g.hay@gmail.com>
Stabilityauto-generated
Portabilitynon-portable (GHC extensions)
Safe HaskellNone
LanguageHaskell2010

Network.AWS.SSM

Contents

Description

Simple Systems Manager (SSM) enables you to remotely manage the configuration of your Amazon EC2 instance. Using SSM, you can run scripts or commands using either EC2 Run Command or SSM Config. (SSM Config is currently available only for Windows instances.)

Run Command

Run Command provides an on-demand experience for executing commands. You can use pre-defined Amazon SSM documents to perform the actions listed later in this section, or you can create your own documents. With these documents, you can remotely configure your instances by sending commands using the Commands page in the Amazon EC2 console, AWS Tools for Windows PowerShell, or the AWS CLI.

Run Command reports the status of the command execution for each instance targeted by a command. You can also audit the command execution to understand who executed commands, when, and what changes were made. By switching between different SSM documents, you can quickly configure your instances with different types of commands. To get started with Run Command, verify that your environment meets the prerequisites for remotely running commands on EC2 instances (Linux or Windows).

SSM Config

SSM Config is a lightweight instance configuration solution. SSM Config is currently only available for Windows instances. With SSM Config, you can specify a setup configuration for your instances. SSM Config is similar to EC2 User Data, which is another way of running one-time scripts or applying settings during instance launch. SSM Config is an extension of this capability. Using SSM documents, you can specify which actions the system should perform on your instances, including which applications to install, which AWS Directory Service directory to join, which Microsoft PowerShell modules to install, etc. If an instance is missing one or more of these configurations, the system makes those changes. By default, the system checks every five minutes to see if there is a new configuration to apply as defined in a new SSM document. If so, the system updates the instances accordingly. In this way, you can remotely maintain a consistent configuration baseline on your instances. SSM Config is available using the AWS CLI or the AWS Tools for Windows PowerShell. For more information, see Managing Windows Instance Configuration.

SSM Config and Run Command include the following pre-defined documents.

Amazon Pre-defined SSM Documents

Name Description Platform

AWS-RunShellScript

Run shell scripts

Linux

AWS-UpdateSSMAgent

Update the Amazon SSM agent

Linux

AWS-JoinDirectoryServiceDomain

Join an AWS Directory

Windows

AWS-RunPowerShellScript

Run PowerShell commands or scripts

Windows

AWS-UpdateEC2Config

Update the EC2Config service

Windows

AWS-ConfigureWindowsUpdate

Configure Windows Update settings

Windows

AWS-InstallApplication

Install, repair, or uninstall software using an MSI package

Windows

AWS-InstallPowerShellModule

Install PowerShell modules

Windows

AWS-ConfigureCloudWatch

Configure Amazon CloudWatch Logs to monitor applications and systems

Windows

The commands or scripts specified in SSM documents run with administrative privilege on your instances because the Amazon SSM agent runs as root on Linux and the EC2Config service runs in the Local System account on Windows. If a user has permission to execute any of the pre-defined SSM documents (any document that begins with AWS-*) then that user also has administrator access to the instance. Delegate access to SSM and Run Command judiciously. This becomes extremely important if you create your own SSM documents. Amazon Web Services does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command at your own risk. As a security best practice, we recommend that you assign access to "AWS-*" documents, especially the AWS-RunShellScript document on Linux and the AWS-RunPowerShellScript document on Windows, to trusted administrators only. You can create SSM documents for specific tasks and delegate access to non-administrators.

Synopsis

Service Configuration

ssm :: Service Source

API version '2014-11-06' of the Amazon Simple Systems Management Service SDK configuration.

Errors

Error matchers are designed for use with the functions provided by Control.Exception.Lens. This allows catching (and rethrowing) service specific errors returned by SSM.

UnsupportedPlatformType

_UnsupportedPlatformType :: AsError a => Getting (First ServiceError) a ServiceError Source

The document does not support the platform type of the given instance ID(s).

AssociatedInstances

_AssociatedInstances :: AsError a => Getting (First ServiceError) a ServiceError Source

You must disassociate an SSM document from all instances before you can delete it.

InvalidInstanceId

_InvalidInstanceId :: AsError a => Getting (First ServiceError) a ServiceError Source

The instance is not in valid state. Valid states are: Running, Pending, Stopped, Stopping. Invalid states are: Shutting-down and Terminated.

StatusUnchanged

_StatusUnchanged :: AsError a => Getting (First ServiceError) a ServiceError Source

The updated status is the same as the current status.

InvalidNextToken

_InvalidNextToken :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified token is not valid.

InvalidOutputFolder

_InvalidOutputFolder :: AsError a => Getting (First ServiceError) a ServiceError Source

The S3 bucket does not exist.

InvalidCommandId

_InvalidCommandId :: AsError a => Getting (First ServiceError) a ServiceError Source

Prism for InvalidCommandId' errors.

DuplicateInstanceId

_DuplicateInstanceId :: AsError a => Getting (First ServiceError) a ServiceError Source

You cannot specify an instance ID in more than one association.

InvalidDocument

_InvalidDocument :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified document does not exist.

InvalidFilterKey

_InvalidFilterKey :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified key is not valid.

InvalidInstanceInformationFilterValue

_InvalidInstanceInformationFilterValue :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified filter value is not valid.

AssociationAlreadyExists

_AssociationAlreadyExists :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified association already exists.

InvalidDocumentContent

_InvalidDocumentContent :: AsError a => Getting (First ServiceError) a ServiceError Source

The content for the SSM document is not valid.

AssociationLimitExceeded

_AssociationLimitExceeded :: AsError a => Getting (First ServiceError) a ServiceError Source

You can have at most 2,000 active associations.

AssociationDoesNotExist

_AssociationDoesNotExist :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified association does not exist.

InternalServerError

_InternalServerError :: AsError a => Getting (First ServiceError) a ServiceError Source

An error occurred on the server side.

TooManyUpdates

_TooManyUpdates :: AsError a => Getting (First ServiceError) a ServiceError Source

There are concurrent updates for a resource that supports one update at a time.

MaxDocumentSizeExceeded

_MaxDocumentSizeExceeded :: AsError a => Getting (First ServiceError) a ServiceError Source

The size limit of an SSM document is 64 KB.

InvalidParameters

_InvalidParameters :: AsError a => Getting (First ServiceError) a ServiceError Source

You must specify values for all required parameters in the SSM document. You can only supply values to parameters defined in the SSM document.

DocumentAlreadyExists

_DocumentAlreadyExists :: AsError a => Getting (First ServiceError) a ServiceError Source

The specified SSM document already exists.

DocumentLimitExceeded

_DocumentLimitExceeded :: AsError a => Getting (First ServiceError) a ServiceError Source

You can have at most 100 active SSM documents.

Waiters

Waiters poll by repeatedly sending a request until some remote success condition configured by the Wait specification is fulfilled. The Wait specification determines how many attempts should be made, in addition to delay and retry strategies.

Operations

Some AWS operations return results that are incomplete and require subsequent requests in order to obtain the entire result set. The process of sending subsequent requests to continue where a previous request left off is called pagination. For example, the ListObjects operation of Amazon S3 returns up to 1000 objects at a time, and you must send subsequent requests with the appropriate Marker in order to retrieve the next page of results.

Operations that have an AWSPager instance can transparently perform subsequent requests, correctly setting Markers and other request facets to iterate through the entire result set of a truncated API operation. Operations which support this have an additional note in the documentation.

Many operations have the ability to filter results on the server side. See the individual operation parameters for details.

DescribeDocument

module Network.AWS.SSM.DescribeDocument

CreateAssociation

module Network.AWS.SSM.CreateAssociation

CreateDocument

module Network.AWS.SSM.CreateDocument

ListCommandInvocations (Paginated)

module Network.AWS.SSM.ListCommandInvocations

ListDocuments (Paginated)

module Network.AWS.SSM.ListDocuments

GetDocument

module Network.AWS.SSM.GetDocument

CancelCommand

module Network.AWS.SSM.CancelCommand

DescribeAssociation

module Network.AWS.SSM.DescribeAssociation

UpdateAssociationStatus

module Network.AWS.SSM.UpdateAssociationStatus

DescribeInstanceInformation

module Network.AWS.SSM.DescribeInstanceInformation

ListAssociations (Paginated)

module Network.AWS.SSM.ListAssociations

DeleteAssociation

module Network.AWS.SSM.DeleteAssociation

SendCommand

module Network.AWS.SSM.SendCommand

ListCommands (Paginated)

module Network.AWS.SSM.ListCommands

DeleteDocument

module Network.AWS.SSM.DeleteDocument

CreateAssociationBatch

module Network.AWS.SSM.CreateAssociationBatch

Types

AssociationFilterKey

data AssociationFilterKey Source

Constructors

AFKInstanceId 
AFKName 

Instances

AssociationStatusName

data AssociationStatusName Source

Constructors

ASNFailed 
ASNPending 
ASNSuccess 

Instances

CommandFilterKey

data CommandFilterKey Source

Constructors

CommandInvokedAfter 
CommandInvokedBefore 
CommandStatus 

Instances

CommandInvocationStatus

data CommandInvocationStatus Source

Constructors

CISCancelled 
CISCancelling 
CISFailed 
CISInProgress 
CISPending 
CISSuccess 
CISTimedOut 

Instances

CommandPluginStatus

data CommandPluginStatus Source

Constructors

CPSCancelled 
CPSFailed 
CPSInProgress 
CPSPending 
CPSSuccess 
CPSTimedOut 

Instances

CommandStatus

data CommandStatus Source

Constructors

Cancelled 
Cancelling 
Failed 
InProgress 
Pending 
Success 
TimedOut 

Instances

DocumentFilterKey

data DocumentFilterKey Source

Constructors

Name 
Owner 
PlatformTypes 

Instances

DocumentParameterType

data DocumentParameterType Source

Constructors

String 
StringList 

Instances

DocumentStatus

data DocumentStatus Source

Constructors

Active 
Creating 
Deleting 

Instances

Fault

data Fault Source

Constructors

Client 
Server 
Unknown 

Instances

InstanceInformationFilterKey

data InstanceInformationFilterKey Source

Constructors

IIFKAgentVersion 
IIFKInstanceIds 
IIFKPingStatus 
IIFKPlatformTypes 

Instances

PingStatus

data PingStatus Source

Constructors

ConnectionLost 
Inactive 
Online 

Instances

PlatformType

data PlatformType Source

Constructors

Linux 
Windows 

Instances

Association

data Association Source

Describes an association of an SSM document and an instance.

See: association smart constructor.

Instances

association :: Association Source

Creates a value of Association with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

aInstanceId :: Lens' Association (Maybe Text) Source

The ID of the instance.

aName :: Lens' Association (Maybe Text) Source

The name of the SSM document.

AssociationDescription

data AssociationDescription Source

Describes the parameters for a document.

See: associationDescription smart constructor.

Instances

associationDescription :: AssociationDescription Source

Creates a value of AssociationDescription with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

adInstanceId :: Lens' AssociationDescription (Maybe Text) Source

The ID of the instance.

adStatus :: Lens' AssociationDescription (Maybe AssociationStatus) Source

The association status.

adDate :: Lens' AssociationDescription (Maybe UTCTime) Source

The date when the association was made.

adName :: Lens' AssociationDescription (Maybe Text) Source

The name of the SSM document.

adParameters :: Lens' AssociationDescription (HashMap Text [Text]) Source

A description of the parameters for a document.

AssociationFilter

data AssociationFilter Source

Describes a filter.

See: associationFilter smart constructor.

Instances

associationFilter Source

Arguments

:: AssociationFilterKey

afKey

-> Text

afValue

-> AssociationFilter 

Creates a value of AssociationFilter with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

afKey :: Lens' AssociationFilter AssociationFilterKey Source

The name of the filter.

afValue :: Lens' AssociationFilter Text Source

The filter value.

AssociationStatus

data AssociationStatus Source

Describes an association status.

See: associationStatus smart constructor.

Instances

associationStatus Source

Arguments

:: UTCTime

asDate

-> AssociationStatusName

asName

-> Text

asMessage

-> AssociationStatus 

Creates a value of AssociationStatus with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

asAdditionalInfo :: Lens' AssociationStatus (Maybe Text) Source

A user-defined string.

asDate :: Lens' AssociationStatus UTCTime Source

The date when the status changed.

asName :: Lens' AssociationStatus AssociationStatusName Source

The status.

asMessage :: Lens' AssociationStatus Text Source

The reason for the status.

Command

data Command Source

Describes a command request.

See: command smart constructor.

Instances

command :: Command Source

Creates a value of Command with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

cStatus :: Lens' Command (Maybe CommandStatus) Source

The status of the command.

cExpiresAfter :: Lens' Command (Maybe UTCTime) Source

If this time is reached and the command has not already started executing, it will not execute. Calculated based on the ExpiresAfter user input provided as part of the SendCommand API.

cOutputS3KeyPrefix :: Lens' Command (Maybe Text) Source

The S3 directory path inside the bucket where the responses to the command executions should be stored. This was requested when issuing the command.

cDocumentName :: Lens' Command (Maybe Text) Source

The name of the SSM document requested for execution.

cInstanceIds :: Lens' Command (Maybe (NonEmpty Text)) Source

The instance IDs against which this command was requested.

cCommandId :: Lens' Command (Maybe Text) Source

A unique identifier for this command.

cParameters :: Lens' Command (HashMap Text [Text]) Source

The parameter values to be inserted in the SSM document when executing the command.

cComment :: Lens' Command (Maybe Text) Source

User-specified information about the command, such as a brief description of what the command should do.

cOutputS3BucketName :: Lens' Command (Maybe Text) Source

The S3 bucket where the responses to the command executions should be stored. This was requested when issuing the command.

cRequestedDateTime :: Lens' Command (Maybe UTCTime) Source

The date and time the command was requested.

CommandFilter

data CommandFilter Source

Describes a command filter.

See: commandFilter smart constructor.

Instances

commandFilter Source

Arguments

:: CommandFilterKey

cfKey

-> Text

cfValue

-> CommandFilter 

Creates a value of CommandFilter with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

cfKey :: Lens' CommandFilter CommandFilterKey Source

The name of the filter. For example, requested date and time.

cfValue :: Lens' CommandFilter Text Source

The filter value. For example: June 30, 2015.

CommandInvocation

data CommandInvocation Source

An invocation is copy of a command sent to a specific instance. A command can apply to one or more instances. A command invocation applies to one instance. For example, if a user executes SendCommand against three instances, then a command invocation is created for each requested instance ID. A command invocation returns status and detail information about a command you executed.

See: commandInvocation smart constructor.

Instances

commandInvocation :: CommandInvocation Source

Creates a value of CommandInvocation with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

ciInstanceId :: Lens' CommandInvocation (Maybe Text) Source

The instance ID in which this invocation was requested.

ciStatus :: Lens' CommandInvocation (Maybe CommandInvocationStatus) Source

Whether or not the invocation succeeded, failed, or is pending.

ciCommandPlugins :: Lens' CommandInvocation [CommandPlugin] Source

Undocumented member.

ciDocumentName :: Lens' CommandInvocation (Maybe Text) Source

The document name that was requested for execution.

ciCommandId :: Lens' CommandInvocation (Maybe Text) Source

The command against which this invocation was requested.

ciComment :: Lens' CommandInvocation (Maybe Text) Source

User-specified information about the command, such as a brief description of what the command should do.

ciTraceOutput :: Lens' CommandInvocation (Maybe Text) Source

Gets the trace output sent by the agent.

ciRequestedDateTime :: Lens' CommandInvocation (Maybe UTCTime) Source

The time and date the request was sent to this instance.

CommandPlugin

data CommandPlugin Source

Describes plugin details.

See: commandPlugin smart constructor.

Instances

commandPlugin :: CommandPlugin Source

Creates a value of CommandPlugin with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

cpStatus :: Lens' CommandPlugin (Maybe CommandPluginStatus) Source

The status of this plugin. You can execute a document with multiple plugins.

cpResponseStartDateTime :: Lens' CommandPlugin (Maybe UTCTime) Source

The time the plugin started executing.

cpOutputS3KeyPrefix :: Lens' CommandPlugin (Maybe Text) Source

The S3 directory path inside the bucket where the responses to the command executions should be stored. This was requested when issuing the command.

cpResponseCode :: Lens' CommandPlugin (Maybe Int) Source

A numeric response code generated after executing the plugin.

cpOutput :: Lens' CommandPlugin (Maybe Text) Source

Output of the plugin execution.

cpName :: Lens' CommandPlugin (Maybe Text) Source

The name of the plugin. Must be one of the following: aws:updateAgent, aws:domainjoin, aws:applications, aws:runPowerShellScript, aws:psmodule, aws:cloudWatch, aws:runShellScript, or aws:updateSSMAgent.

cpOutputS3BucketName :: Lens' CommandPlugin (Maybe Text) Source

The S3 bucket where the responses to the command executions should be stored. This was requested when issuing the command.

cpResponseFinishDateTime :: Lens' CommandPlugin (Maybe UTCTime) Source

The time the plugin stopped executing. Could stop prematurely if, for example, a cancel command was sent.

CreateAssociationBatchRequestEntry

data CreateAssociationBatchRequestEntry Source

Describes the association of an SSM document and an instance.

See: createAssociationBatchRequestEntry smart constructor.

Instances

createAssociationBatchRequestEntry :: CreateAssociationBatchRequestEntry Source

Creates a value of CreateAssociationBatchRequestEntry with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

cabreInstanceId :: Lens' CreateAssociationBatchRequestEntry (Maybe Text) Source

The ID of the instance.

cabreName :: Lens' CreateAssociationBatchRequestEntry (Maybe Text) Source

The name of the configuration document.

cabreParameters :: Lens' CreateAssociationBatchRequestEntry (HashMap Text [Text]) Source

A description of the parameters for a document.

DocumentDescription

data DocumentDescription Source

Describes an SSM document.

See: documentDescription smart constructor.

Instances

documentDescription :: DocumentDescription Source

Creates a value of DocumentDescription with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

dStatus :: Lens' DocumentDescription (Maybe DocumentStatus) Source

The status of the SSM document.

dSha1 :: Lens' DocumentDescription (Maybe Text) Source

The SHA1 hash of the document, which you can use for verification purposes.

dPlatformTypes :: Lens' DocumentDescription [PlatformType] Source

The list of OS platforms compatible with this SSM document.

dCreatedDate :: Lens' DocumentDescription (Maybe UTCTime) Source

The date when the SSM document was created.

dName :: Lens' DocumentDescription (Maybe Text) Source

The name of the SSM document.

dParameters :: Lens' DocumentDescription [DocumentParameter] Source

A description of the parameters for a document.

dDescription :: Lens' DocumentDescription (Maybe Text) Source

A description of the document.

DocumentFilter

data DocumentFilter Source

Describes a filter.

See: documentFilter smart constructor.

Instances

documentFilter Source

Arguments

:: DocumentFilterKey

dfKey

-> Text

dfValue

-> DocumentFilter 

Creates a value of DocumentFilter with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

dfKey :: Lens' DocumentFilter DocumentFilterKey Source

The name of the filter.

dfValue :: Lens' DocumentFilter Text Source

The value of the filter.

DocumentIdentifier

data DocumentIdentifier Source

Describes the name of an SSM document.

See: documentIdentifier smart constructor.

Instances

documentIdentifier :: DocumentIdentifier Source

Creates a value of DocumentIdentifier with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

diPlatformTypes :: Lens' DocumentIdentifier [PlatformType] Source

The operating system platform.

diName :: Lens' DocumentIdentifier (Maybe Text) Source

The name of the SSM document.

DocumentParameter

data DocumentParameter Source

See: documentParameter smart constructor.

Instances

documentParameter :: DocumentParameter Source

Creates a value of DocumentParameter with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

dpName :: Lens' DocumentParameter (Maybe Text) Source

The name of the parameter.

dpDefaultValue :: Lens' DocumentParameter (Maybe Text) Source

If specified, the default values for the parameters. Parameters without a default value are required. Parameters with a default value are optional.

dpType :: Lens' DocumentParameter (Maybe DocumentParameterType) Source

The type of parameter. The type can be either “String” or “StringList”.

dpDescription :: Lens' DocumentParameter (Maybe Text) Source

A description of what the parameter does, how to use it, the default value, and whether or not the parameter is optional.

FailedCreateAssociation

data FailedCreateAssociation Source

Describes a failed association.

See: failedCreateAssociation smart constructor.

Instances

failedCreateAssociation :: FailedCreateAssociation Source

Creates a value of FailedCreateAssociation with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

fcaEntry :: Lens' FailedCreateAssociation (Maybe CreateAssociationBatchRequestEntry) Source

The association.

fcaFault :: Lens' FailedCreateAssociation (Maybe Fault) Source

The source of the failure.

fcaMessage :: Lens' FailedCreateAssociation (Maybe Text) Source

A description of the failure.

InstanceInformation

data InstanceInformation Source

Describes a filter for a specific list of instances.

See: instanceInformation smart constructor.

Instances

instanceInformation :: InstanceInformation Source

Creates a value of InstanceInformation with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

iiInstanceId :: Lens' InstanceInformation (Maybe Text) Source

The instance ID.

iiPingStatus :: Lens' InstanceInformation (Maybe PingStatus) Source

Connection status of the SSM agent.

iiPlatformVersion :: Lens' InstanceInformation (Maybe Text) Source

The version of the OS platform running on your instance.

iiIsLatestVersion :: Lens' InstanceInformation (Maybe Bool) Source

Indicates whether latest version of the SSM agent is running on your instance.

iiAgentVersion :: Lens' InstanceInformation (Maybe Text) Source

The version of the SSM agent running on your instance.

iiLastPingDateTime :: Lens' InstanceInformation (Maybe UTCTime) Source

The date and time when agent last pinged SSM service.

iiPlatformType :: Lens' InstanceInformation (Maybe PlatformType) Source

The operating system platform type.

iiPlatformName :: Lens' InstanceInformation (Maybe Text) Source

The name of the operating system platform running on your instance.

InstanceInformationFilter

data InstanceInformationFilter Source

Describes a filter for a specific list of instances.

See: instanceInformationFilter smart constructor.

Instances

instanceInformationFilter Source

Arguments

:: InstanceInformationFilterKey

iifKey

-> NonEmpty Text

iifValueSet

-> InstanceInformationFilter 

Creates a value of InstanceInformationFilter with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

iifKey :: Lens' InstanceInformationFilter InstanceInformationFilterKey Source

The name of the filter.

iifValueSet :: Lens' InstanceInformationFilter (NonEmpty Text) Source

The filter values.