Enable audit log streaming to AWS Cloudwatch

This page describes how to stream an organization’s HCP audit logs to AWS Cloudwatch, where you can review them. Enable audit log streaming from the HCP portal or use the HCP Terraform provider's hcp_log_streaming_destination resource.

Requirements

Whether you use the HCP UI or the Terraform provider, enabling audit log streaming requires an HCP user account with owner or admin permissions for an organization. For more information, refer to users.

Terraform provider method

To configure and enable audit logging streaming with Terraform instead of the HCP UI, the following software and provider versions are required.

Terraform v1.1.5 or later. For the best experience, we recommend using the latest release.
HashiCorp Cloud Platform (HCP) Provider version 0.83.0 or higher.

You must also configure the HCP provider to authenticate using an organizational-level service principal and service principal key. Refer to the Authenticate with HCP guide in the Terraform registry for more information.

Workflow

You can enable audit log streaming from HCP to AWS Cloudwatch using the dedicated HCP workflow. You also have the option to create and manage your organization's infrastructure using the HCP provider in the Terraform Registry.

Complete the following steps to enable audit log streaming.

Outside of HCP, create an AWS IAM role with an attached policy for the audit logs.
Enable audit log streaming for the organization in HCP.
View the audit logs.

Create an AWS IAM role with an attached policy for the audit logs

To enable audit log streaming to AWS Cloudwatch, you must create an AWS IAM role in your AWS account that allows HashiCorp to stream audit logs to your account’s AWS Cloudwatch service. You can create a role and attach a policy manually in the AWS Console, or you can create the resources with Terraform.

When you create an audit log streaming destination from the HCP Portal, you are provided values for the AWS ID and External ID that you need for your AWS environment. To use these values to create the role from the AWS console, refer to the instructions in the AWS documentation.

To create the role and policy using Terraform, add the following AWS Terraform provider resources to your configuration.

resource "aws_iam_role" "cloudwatch_hcp_audit_logs" {
  name = "cloudwatch-hcp-audit-logs"
 assume_role_policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::711430482607:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "hcp-log-stream"
        }
      }
    }
  ]
}
EOF
}

resource "aws_iam_role_policy" "hcp_log_streaming_policy" {
  name = "hcp_log_streaming_policy"
  role = aws_iam_role.cloudwatch_hcp_audit_logs.id

  policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "HCPLogStreaming",
      "Effect": "Allow",
      "Action": [
        "logs:PutLogEvents",
        "logs:DescribeLogStreams",
        "logs:DescribeLogGroups",
        "logs:CreateLogStream",
        "logs:CreateLogGroup"
      ],
      "Resource": "*"
    }
  ]
}
EOF
}

These configuration examples use hcp-log-stream as the External ID. To keep your audit logs secure in production environments, we recommend using a custom string for the external ID instead of "hcp-log-stream". When creating the audit log stream from the HCP UI, use the provided value of External ID in your Terraform configuration.

Run the following command to target these resources and apply them to your infrastructure with Terraform:

$ terraform apply -target "aws_iam_role.cloudwatch_hcp_audit_logs" -target "aws_iam_role_policy.hcp_log_streaming_policy"

Enable audit log streaming

To enable audit log streaming to AWS Cloudwatch, complete the following steps.

Sign in to the HCP Portal.
Select the organization you want to stream audit logs from.
Click Audit log streaming.
Click Create streaming destination.
Select AWS Cloudwatch.
Create the AWS role and policy if you did not already do so.
Complete the required configuration fields:
- Destination name. This label appears in list of audit log streams for the HCP organization.
- Role ARN. The AWS resource identifier for the IAM role that authorizes HCP to stream audit logs to your Cloudwatch environment.
- Region. The AWS region where you store your Cloudwatch data.
Note the Log group name. Logs appear in AWS Cloudwatch under this name. You cannot edit this value.
Click Test connection to generate a test log that HCP sends to AWS Cloudwatch.
Click Save.

You can also enable audit log streaming using Terraform and the HCP provider in the Terraform Registry.

Configure the `hcp_log_streaming_destination` resource

For your HCP organization, configure the hcp_log_streaming_destination resource with the ARN of the role you created and your external ID. If the log group you specify does not exist, Terraform will create it when the first log streams to Cloudwatch.

The following example provides a typical configuration for this resource:

resource "hcp_log_streaming_destination" "aws_cloudwatch" {
  name = "<cloudwatch-prod>"
  cloudwatch = {
    external_id       = "hcp-log-stream"
    region            = "us-east-1"
    role_arn          = "arn:aws:iam::111111111:role/cloudwatch-hcp-audit-logs"
    log_group_name    = "/hashicorp/hcp/audit-logs/"
  }
}

For more information about how to use role ARNs and log groups, refer to IAM identifiers and Working with log groups and streams in the AWS documentation.

Update your infrastructure with Terraform

After you configure the resource, run terraform apply to update your deployment. To target the resource you just created, run the following command:

$ terraform apply -target "aws_iam_role.cloudwatch_hcp_audit_logs" -target "aws_iam_role_policy.hcp_log_streaming_policy" -target "hcp_log_streaming_destination.aws_cloudwatch"

To view the audit logs, go to the Cloudwatch AWS service page. Click Log groups. Click /hashicorp/hcp/audit-logs/, and then click the log stream. Logs appear after you generate them.

View the audit logs

To view the audit logs in AWS, go to the Cloudwatch service page. Click Log groups and then select /hashicorp/hcp/audit-logs/. Audit log entries appear in Cloudwatch after they occur on the HCP platform.