Running AWS CLI commands from chat channels

You can run commands using AWS CLI syntax directly in chat channels. AWS Chatbot enables you to retrieve diagnostic information, configure AWS resources, and run workflows.

When you interact with AWS Chatbot in your chat channels, it prompts you for any missing parameters before it runs the command.

Required permissions

To perform actions in your chat channels, you must first have the appropriate permissions. For more information about AWS Chatbot's permissions, see Understanding permissions.

Non-supported operations

AWS Chatbot doesn't support running commands for operations in the following JSON policy:

{
  "Statement": [
    {
      "Action": [
        "appsync:ListApiKeys",
        "chatbot:*",
        "codecommit:GetFile",
        "codecommit:GetCommit",
        "codecommit:GetDifferences",
        "cognito-idp:*",
        "cognito-identity:*",
        "connect:GetFederationToken",
        "dynamodb:BatchGetItem",
        "dynamodb:GetItem",
        "ec2:GetPasswordData",
        "ecr:GetAuthorizationToken",
        "ecr:GetLogin",
        "gamelift:RequestUploadCredentials",
        "gamelift:GetInstanceAccess",
        "identitystore:*",
        "lightsail:DownloadDefaultKeyPair",
        "lightsail:GetInstanceAccessDetail",
        "lightsail:GetKeyPair",
        "lightsail:GetKeyPairs",
        "lightsail:UpdateRelationalDatabase",
        "iam:*",
        "kms:*",
        "redshift:GetClusterCredentials",
        "sdb:*",
        "secretsmanager:*",
        "sso:*",
        "sso-admin:*",
        "sso-oidc:*",
        "storagegateway:DescribeChapCredentials",
        "sts:*",
        "s3:GetObject",
        "s3:HeadObject",
        "s3:PutObject",
        "s3:GetBucketPolicy",
        "snowball:GetJobUnlockCode"
      ],
      "Effect": "Deny",
      "Resource": "*"
    }
  ],
  "Version": "2012-10-17"
}

Using commands

After you set up the AWS Chatbot, you run commands with the following prefix:

@aws

The AWS Chatbot command syntax is the same as you would use in a terminal:

@aws service command --options

For example, enter the following read-only command to view a list of your Lambda functions:

@aws lambda list-functions

Enter the following commands to list and chart CloudWatch alarms:

@aws cloudwatch describe-alarms --state ALARM

You can also use CLI commands to change you AWS resources. For example, enter the following command to change your Kinesis shards:

@aws kinesis update-shard-count --stream-name samplestream --scaling-type UNIFORM_SCALING --target-shard-count 6

You can enter a complete AWS CLI command with all the parameters, or you can enter the command without parameters and AWS Chatbot prompts you for missing parameters.

For more information on commonly used CLI commands, see Using CLI commands with AWS Chatbot - Common use cases. For an exhaustive list of CLI commands, see the AWS CLI Command Reference.

The following limitations apply to running AWS CLI commands in your chat rooms:

Running commands

AWS Chatbot tracks your use of command options and prompts you for any missing parameters before it runs the command you want.

For example, if you enter @aws lambda get-function with no further arguments, the Chatbot requests the function name. Then, run the @aws lambda list-functions command, find the function name you need, and re-run the first command with the corrected option. Add more parameters for the initial command with @aws function-name name. AWS Chatbot parses your commands and helps you complete the correct syntax so it can run the complete AWS CLI command.

Getting help for AWS services

To get help about commands for any AWS service, enter @aws followed by the service name, as shown following:

@aws lambda --help

@aws cloudwatch describe-alarms --help

Formatting data and viewing logs

To ensure data from Amazon CloudWatch alarms is correctly formatted, attach the Lambda-Invoke Command Permissions and ReadOnly Commands Permissions IAM policies to the role in the AWS Chatbot console for users in the chat channel.

Run the cloudwatch describe-alarms command to show CloudWatch alarms in chart form as follows:

@aws cloudwatch describe-alarms

You can change the command to only include notifications in the alarm state, filtering out other notifications, by adding the following option:

@aws cloudwatch describe-alarms --state ALARM

To see alarms from a different AWS Region, include that Region in the command:

@aws cloudwatch describe-alarms --state ALARM --region us-east-1

You can also filter AWS CLI output by using the optional query parameter. A query uses JMESPath syntax to create an expression to filter your output to your specifications. For more information about filtering, see Filtering AWS CLI output in the AWS Command Line Interface User Guide. For more information about JMESPath syntax, see their website. The following example shows how to limit AWS CLI output for the cloudwatch describe-alarms command to just the alarm name, description, state, and reason attributes.

@AWS cloudwatch describe-alarms --query 
 @.{MetricAlarms:MetricAlarms[*].
 {AlarmName:AlarmName, AlarmDescription:AlarmDescription, StateValue:StateValue, 
 StateReason:StateReason, Namespace:Namespace, MetricName:MetricName, 
 Dimensions:Dimensions, ComparisonOperator:ComparisonOperator, Threshold:Threshold, 
 Period:Period, EvaluationPeriods:EvaluationPeriods, Statistic:Statistic}} 
 --region us-east-2   
    

Displaying Amazon CloudWatch Logs information

CloudWatch alarm notifications show buttons in chat client notifications to view logs related to the alarm. These notifications use the CloudWatch Log Insights feature. There may be service charges for using this feature to query and show logs.

You can view CloudWatch logs, including error logs, that are associated with the CloudWatch alarm by choosing Show logs at the bottom of the alarm notification. AWS Chatbot displays the first 30 log entries from the start of the alarm evaluation period. AWS Chatbot uses CloudWatch Log Insights to query for logs. The query results contain a link to the CloudWatch Log Insights console, where a user can dive deeper into logs details.

Choose Show error logs to filter search results to log entries containing Error, Exception, or Fail terms.

The log shows a command that a user can copy, paste, and edit to re-run the query for viewing logs.

Creating an AWS Support case

The AWS Support Command Permissions policy appears in the AWS Chatbot console when you configure resources. It's provided in the AWS Chatbot console so that you can set up new roles for users in your chat client to create AWS support tickets through their chat channels.

You can quickly create a new AWS support case by entering the following:

@aws support create-case

Follow the prompts from AWS Chatbot to fill out the support case with its needed parameters. When you complete the case information entry, AWS Chatbot asks for confirmation. You will not be able to use file attachments.

For any AWS Chatbot role that creates AWS Support cases, you need to attach the AWS Support command permissions policy to the role. For existing roles, you will need to attach the policy in the IAM console.

In the IAM console, this policy appears as AWSSupportAccess.

It is an AWS managed policy. Attach this policy in IAM to any role for AWS Chatbot usage. You can define your own policy with greater restrictions, using this policy as a template.

The Support Command Permissions policy applies only to the AWS Support service.

The policy's JSON code is shown following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "support:*"
            ],
            "Resource": "*"
        }
    ]
}

Configuring commands support on an existing chat channel

If you have existing chat channels using the AWS Chatbot, you can reconfigure them in a few steps to support the AWS CLI.

Enabling multiple accounts to use commands

You can configure AWS Chatbot for multiple AWS accounts in the same chat channel. When you work with AWS Chatbot for the first time in that channel, it will ask you which account you want to use. AWS Chatbot will remember the account selection for 7 days.

To change the default account in the channel, enter @aws set default-account and select the account from the list.