Menu
Amazon CloudWatch Logs
User Guide

Create a Destination

The following example creates a destination using an Amazon Kinesis stream called RootAccess, and a role that enables CloudWatch Logs to write data to it. Lambda cross-account processing is similar, except you create a Lambda function and use the Amazon Resource Name (ARN) for that function in place of the Amazon Kinesis stream ARN.

To create a destination

  1. Create a destination stream in Amazon Kinesis. At a command prompt, type:

    aws kinesis create-stream --stream-name "RootAccess" --shard-count 1
  2. Wait until the Amazon Kinesis stream becomes active. You can use the aws kinesis describe-stream command to check the StreamDescription.StreamStatus property. In addition, take note of the StreamDescription.StreamARN value because it will be passed to CloudWatch Logs later:

    aws kinesis describe-stream --stream-name "RootAccess"
    {
      "StreamDescription": {
        "StreamStatus": "ACTIVE",
        "StreamName": "RootAccess",
        "StreamARN": "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess",
        "Shards": [
          {
            "ShardId": "shardId-000000000000",
            "HashKeyRange": {
              "EndingHashKey": "34028236692093846346337460743176EXAMPLE",
              "StartingHashKey": "0"
            },
            "SequenceNumberRange": {
              "StartingSequenceNumber": "4955113521868881845667950383198145878459135270218EXAMPLE"
            }
          }
        ]
      }
    }

    It might take a minute or two for your stream to show up in the active state.

  3. Create the IAM role that will grant CloudWatch Logs the permission to put data into your Amazon Kinesis stream. First, you'll need to create a trust policy in a file ~/TrustPolicyForCWL.json:

    {
      "Statement": {
        "Effect": "Allow",
        "Principal": { "Service": "logs.us-east-1.amazonaws.com" },
        "Action": "sts:AssumeRole"
      }
    }
  4. Use the aws iam create-role command to create the IAM role, specifying the trust policy file. Take note of the returned Role.Arn value because that will also be passed to CloudWatch Logs later:

    aws iam create-role \
          --role-name CWLtoKinesisRole \
          --assume-role-policy-document file://~/TrustPolicyForCWL.json
    
    {
        "Role": {
            "AssumeRolePolicyDocument": {
                "Statement": {
                    "Action": "sts:AssumeRole",
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "logs.us-east-1.amazonaws.com"
                    }
                }
            },
            "RoleId": "AAOIIAH450GAB4HC5F431",
            "CreateDate": "2015-05-29T13:46:29.431Z",
            "RoleName": "CWLtoKinesisRole",
            "Path": "/",
            "Arn": "arn:aws:iam::123456789012:role/CWLtoKinesisRole"
        }
    }
  5. Create a permissions policy to define which actions CloudWatch Logs can perform on your account. First, you'll create a permissions policy in a file ~/PermissionsForCWL.json:

    {
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "kinesis:PutRecord",
          "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess"
        },
        {
          "Effect": "Allow",
          "Action": "iam:PassRole",
          "Resource": "arn:aws:iam::123456789012:role/CWLtoKinesisRole"
        }
      ]
    }
  6. Associate the permissions policy with the role using the aws iam put-role-policy command:

    aws iam put-role-policy --role-name CWLtoKinesisRole --policy-name Permissions-Policy-For-CWL --policy-document file://~/PermissionsForCWL.json
  7. After the Amazon Kinesis stream is in the active state and you have created the IAM role, you can create the CloudWatch Logs destination.

    1. This step will not associate an access policy with your destination and is only the first step out of two that completes a destination creation. Make a note of the DestinationArn that is returned in the payload:

      aws logs put-destination \
          --destination-name "testDestination" \
          --target-arn "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess" \
          --role-arn "arn:aws:iam::123456789012:role/CWLtoKinesisRole"
      
      {
        "DestinationName" : "testDestination",
        "RoleArn" : "arn:aws:iam::123456789012:role/CWLtoKinesisRole",
        "DestinationArn" : "arn:aws:logs:us-east-1:123456789012:destination:testDestination",
        "TargetArn" : "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess"
      }
    2. After step 7a is complete, associate an access policy with the destination. You can put this policy in the ~/AccessPolicy.json file:

      {
        "Version" : "2012-10-17",
        "Statement" : [
          {
            "Sid" : "",
            "Effect" : "Allow",
            "Principal" : {
              "AWS" : "234567890123"
            },
            "Action" : "logs:PutSubscriptionFilter",
            "Resource" : "arn:aws:logs:us-east-1:123456789012:destination:testDestination"
          }
        ]
      }
    3. This creates a policy that defines who has write access to the destination. This policy must specify the logs:PutSubscriptionFilter action to access the destination. Cross-account users will use the PutSubscriptionFilter action to send log events to the destination:

      aws logs put-destination-policy \
          --destination-name "testDestination" \
          --access-policy file://~/AccessPolicy.json

      This access policy allows the root user of the AWS Account with ID 234567890123 to call PutSubscriptionFilter against the destination with ARN arn:aws:logs:us-east-1:123456789012:destination:testDestination. Any other user's attempt to call PutSubscriptionFilter against this destination will be rejected.

      To validate a user's privileges against an access policy, see Using Policy Validator in the IAM User Guide.