README.md

CFN-LogRetentionPolicy

This package creates a CloudFormation custom resource for CloudWatch Logs log retention policies.

Topics

• Syntax
• Permissions
• Properties
• Return Values
• Examples
• More Info

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
    "Type" : "Custom::LogRetentionPolicy",
    "Properties" : {
        "Version": "1.0",
        "ServiceToken": String,
        "LogGroup": String,
        "RetentionInDays": Integer
    }
}

YAML

Type: Custom::LogRetentionPolicy
Properties:
    Version: '1.0'
    ServiceToken: String
    LogGroup: String
    RetentionInDays: Integer

Permissions

logs:DescribeLogGroups

The resource handler searches existing log groups to ensure it exists before it can set a retention policy.

Resource access: all CloudWatch Logs ARNs

Lifecycle events: Create, Update

logs:CreateLogGroup

Note

This permission is only required if you are setting retention policies for log groups that do not already exist.

The resource handler needs an existing log group to apply a retention policy. It creates one if it doesn't exist.

Resource access: The ARN for the log group specified in the LogGroup property.

Lifecycle events: Create, Update Only if the group doesn't exist

logs:PutRetentionPolicy

This is the primary purpose of this resource. It is required for the resource to work.

Resource access: The ARN for the log group specified in the LogGroup property.

Lifecycle events: Create, Update

logs:DeleteRetentionPolicy

This permission is required when removing the resource.

Resource access: The ARN for the log group specified in the LogGroup property.

Lifecycle events: Delete

Properties

ServiceToken

The service token is the ARN to the Lambda function for the custom resource. It is exported for convenience as the function name with an optional prefix configured in the template.

Required: Yes

Type: String

Update requires: Updates are not supported.

LogGroup

The name of the log group. Creates a new log group if one does not already exist.

Note

Changing the name requires replacement and will not delete the old log group. Use the AWS::Logs::LogGroup instead if you are in need of managing log groups.

Required: Yes

Type: String

Update requires: Replacement

RetentionInDays

The number of days log events are kept in CloudWatch Logs. When a log event expires, CloudWatch Logs automatically deletes it. For valid values, see PutRetentionPolicy in the Amazon CloudWatch Logs API Reference.

Required: Yes

Type: Integer

Update requires: No Interruption

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the resource name.

For more information about using the Ref function, see Ref.

Examples

The following example sets a CloudWatch Logs retention policy for a lambda function that retains events for 7 days.

{
    "MyFunctionRetentionPolicy": {
        "Type": "Custom::LogRetentionPolicy",
        "Properties": {
            "Version": "1.0",
            "ServiceToken": {"Fn::ImportValue": "CFN-LogRetentionPolicy"},
            "LogGroup": {"Fn::Sub": "/aws/lambda/${MyFunction}"},
            "RetentionInDays": 7
        }
    }
}

MyFunctionRetentionPolicy:
    Type: Custom::LogRetentionPolicy
    Properties:
        Version: '1.0'
        ServiceToken: !ImportValue 'CFN-LogRetentionPolicy'
        LogGroup: !Sub '/aws/lambda/${MyFunction}'
        RetentionInDays: 7

More Info

• For more about custom resources see the AWS::CloudFormation::CustomResource documentation.

• See the CloudWatch Logs API Reference for more information on CloudWatch Logs.

• In many cases the official AWS::Logs::LogGroup may be sufficient.