Get AWS CloudWatch Log Group with PowerShell Core

• Download source code from GitHub

Introduction

To manipulate AWS resources, we use PowerShell Core with AWS CLI v2. The post describes several functions which get information about CloudWatch log group. Log group is a group of log streams that share the same retention, monitoring, and access control settings. You can define log groups and specify which streams to put into each group. There is no limit on the number of log streams that can belong to one log group. Considered functions are used to get existent log group or create a new one.

Background

Solution uses AWS CLI v2, CloudWatch log groups and PowerShell Core v.7.2.

Function Get-CloudWatchLogGroupARN

Function Get-CloudWatchLogGroupARN seeks CloudWatch log group by its name and return ARN or $null if a log group is not found.

Code

Function Get-CloudWatchLogGroupARN {
    <#
    .SYNOPSIS
    Get-CloudWatchLogGroupARN Function seek log group by its name and
    return ARN or $null if a log group is not found.
    .DESCRIPTION
    Get-CloudWatchLogGroupARN Function seek log group by its name and
    return ARN or $null if a log group is not found.
    .PARAMETER LogGroupName
    Name of CloudWatch log group which is searched
    .PARAMETER RegionName
    Name of AWS Region where log group is searched
    .PARAMETER AwsProfile
    Name of user AWS profile name from .aws config file
    .INPUTS
    None. You cannot pipe objects to Get-CloudWatchLogGroupARN.
    .OUTPUTS
    Get-CloudWatchLogGroupARN returns $null or ARN of found CloudWatch log group
    .EXAMPLE
    PS> Get-CloudWatchLogGroupARN "blog-log-group"
    Returns ARN of log group "blog-log-group" in the us-west-1 region 
    using default credentials
    .EXAMPLE
    PS> Get-CloudWatchLogGroupARN "blog-log-group" -RegionName "eu-west-1"
    Returns ARN of log group "blog-log-group" in the eu-west-1 region 
    using default credentials
    .EXAMPLE
    PS> Get-CloudWatchLogGroupARN "blog-log-group" -AWSProfile "BlogAuthor"
    Returns ARN of log group "blog-log-group" in the us-west-1 region 
    using credentials defined by BlogAuthor profile
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    Param (
        # log group name
        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Default')]
        [ValidateNotNullOrEmpty()]
        [string]$LogGroupName,

        # region name
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [string]$RegionName = "us-west-1",

        # AWS profile name from User .aws config file
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [string]$AwsProfile = "default"
    )

    #region Initialization
    $functionName = $($myInvocation.MyCommand.Name);
    Write-Host "$($functionName)(LogGroup=$LogGroupName, 
    region=$RegionName, profile=$AwsProfile) starts." -ForegroundColor Blue;

    $jsonObjects = $null;
    $strJsonObjects = $null;
    $awsObjects = $null;
    $existObject = $false;
    #endregion

    #region List log groups with the provided name
    $queryRequest = "logGroups[?logGroupName==``$logGroupName``]";
    $jsonObjects = aws --output json --profile $AwsProfile 
                       --region $RegionName --color on `
        logs describe-log-groups `
        --log-group-name-prefix $logGroupName `
        --query $queryRequest;
    
    if (-not $?) {
        Write-Host "Listing CloudWatch log groups failed" -ForegroundColor Red;
        return $null;
    }
    if ($jsonObjects) {
        $strJsonObjects = [string]$jsonObjects;
        $awsObjects = ConvertFrom-Json -InputObject $strJsonObjects;
        $existObject = ($awsObjects.Count -gt 0);
    }
    if ($existObject) {
        $logGroupARN = $awsObjects.ARN;
        Write-Verbose "Log group '$LogGroupName' is found, ARN=$logGroupARN";
        return $logGroupARN;
    }
    else {
        Write-Verbose "Log group '$LogGroupName' doesn't exist";
        return $null;
    }
    #endregion
}

Parameters

Functions has the following parameters:

• string $LogGroupName – the name of CloudWatch log group which is searched. Mandatory parameter with not empty value;
• string $RegionName – the name of AWS Region where log group is searched. Optional parameter with default value us-west-1;
• string $AwsProfile – the name of user AWS profile name from .aws config file. Optional parameter with default value default.

Return Value

Function returns ARN of found CloudWatch log group or $null.

Workflow

Function is a wrapper to AWS CLI method aws logs describe-log-groups with query parameter.

$queryRequest = "logGroups[?logGroupName==``$logGroupName``]";

which limits output to the required log group.

At lines 68-72, output is convert to the array of objects. At lines 73-81, result is checked and ARN of found CloudWatch log group or $null is returned.

Function New-CloudWatchLogGroup

Function New-CloudWatchLogGroup checks for the existent log group. If it already exists, its ARN is returned. If the log group doesn’t exist, the function creates new CloudWatch log group and returns its ARN. If the creation of CloudWatch log group failed, $null is returned.

Code

Function New-CloudWatchLogGroup {
    <#
    .SYNOPSIS
    New-CloudWatchLogGroup Function create new CloudWatch log group and
    return its ARN.
    .DESCRIPTION
    New-CloudWatchLogGroup Function check for the existent log group. If it
    exists, its ARN is returned. If the log group doesn't exist, Function
    create new CloudWatch log group and return its ARN. If the creation of
    CloudWatch log group failed, $null is returned.
    .PARAMETER LogGroupName
    Name of CloudWatch log group which is searched
    .PARAMETER RetentionDays
    Retention in days of log group's streams
    .PARAMETER Tags
    Tags of log group. Could be $null.
    .PARAMETER RegionName
    Name of AWS Region where log group is searched
    .PARAMETER AwsProfile
    Name of user AWS profile name from .aws config file
    .INPUTS
    None. You cannot pipe objects to New-CloudWatchLogGroup.
    .OUTPUTS
    New-CloudWatchLogGroup returns $null or ARN of CloudWatch log group
    .EXAMPLE
    PS> New-CloudWatchLogGroup "blog-log-group"
    Returns ARN of log group "blog-log-group" in the us-west-1 region 
    using default credentials
    .EXAMPLE
    PS> New-CloudWatchLogGroup "blog-log-group"
    Returns ARN of log group "blog-log-group" in the us-west-1 region 
    using default credentials
    .EXAMPLE
    PS> New-CloudWatchLogGroup -LogGroupName "blog-log-group" 
        -RetentionDays 90 -Tags "Key1=Value1,Key2=Value2" 
        -RegionName "eu-west-1" -AwsProfile "BlogAuthor"
    Returns ARN of new or existent log group "blog-log-group" with retention
    period 6 months in the eu-west-1 region using credentials defined
    by BlogAuthor profile
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    Param (
        # log group name
        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Default')]
        [ValidateNotNullOrEmpty()]
        [string]$LogGroupName,

        # log retention in days
        [Parameter(Mandatory = $false, Position = 1, ParameterSetName = 'Default')]
        [ValidateRange(1, 360)]
        [int]$RetentionDays = 180,

        # tags of log group
        [Parameter(Mandatory = $false, Position = 2, ParameterSetName = 'Default')]
        [string]$Tags = $null,

        # region name
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [string]$RegionName = "us-west-1",

        # AWS profile name from User .aws config file
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [string]$AwsProfile = "default"
    )

    #region Initialization
    $functionName = $($myInvocation.MyCommand.Name);
    Write-Host "$($functionName)(LogGroup=$LogGroupName, 
region=$RegionName, profile=$AwsProfile) starts." -ForegroundColor Blue;
    #endregion

    #region Create CloudWatch log group
    $logGroupARN = Get-CloudWatchLogGroupARN `
        $logGroupName `
        -regionname $RegionName -awsprofile $AwsProfile `
        -verbose:$Verbose;

    if (-not $?) {
        Write-Host "Getting log group failed" -ForegroundColor Red;
        return $null;
    }
    if (-not $logGroupARN) {
        Write-Verbose "Log group '$logGroupName' doesn't exist, let's create it";

        # no output
        aws --output json --profile $AwsProfile --region $RegionName --color on `
            logs create-log-group `
            --log-group-name $logGroupName `
            --tags $Tags;
        
        if (-not $?) {
            Write-Host "Creating CloudWatch log group failed" -ForegroundColor Red;
            return $null;
        }
    }
    # no output
    aws --output json --profile $AwsProfile --region $RegionName --color on `
        logs put-retention-policy `
        --log-group-name $logGroupName `
        --retention-in-days $RetentionDays;
        
    if (-not $?) {
        Write-Host "Updating CloudWatch log group failed" -ForegroundColor Red;
        return $null;
    }

    $logGroupARN = Get-CloudWatchLogGroupARN `
        $logGroupName `
        -regionname $RegionName -awsprofile $AwsProfile `
        -verbose:$Verbose;

    if (-not $?) {
        Write-Host "Getting log group failed" -ForegroundColor Red;
        return $null;
    }
    else {
        return $logGroupARN;
    }

    #endregion
}

Parameters

Functions has the following parameters:

• string $LogGroupName – the name of CloudWatch log group which is created. Mandatory parameter with not empty value;
• integer $RetentionDays – retention in days of log group’s streams. Optional parameter with default value 6 months or 180 days;
• string $Tags – tags of log group. Optional parameter, could be $null;
• string $RegionName – the name of AWS Region where log group is created. Optional parameter with default value us-west-1;
• string $AwsProfile – the name of user AWS profile name from .aws config file. Optional parameter with default value default.

Return Value

Function returns ARN of created CloudWatch log group or $null if the function failed.

Workflow

At lines 70-73, function seeks CloudWatch log group with provided name $logGroupName. If log group doesn’t exist, AWS CLI method aws logs create-log-group is called at lines 83-86. This method doesn’t provide output, so later function needs to get CloudWatch log group once again.

At lines 94-97, retention in days is set to $RetentionDays value. AWS CLI method aws logs put-retention-policy is called for either new created log group or existent one to set retention period to the desired value.

Finally, the method Get-CloudWatchLogGroupARN is called to return ARN of CloudWatch log group to the caller.

1. All used IP-addresses, names of servers, workstations, domains, are fictional and are used exclusively as a demonstration only.
2. Information is provided «AS IS».