Skip to content

Commit

Permalink
feat(client-cloudwatch-logs): Add CMK encryption support for CloudWat…
Browse files Browse the repository at this point in the history 
…ch Logs Insights query result data
  • Loading branch information
awstools committed Jul 7, 2023
1 parent c225679 commit c16a285
Show file tree
Hide file tree
Showing 8 changed files with 215 additions and 51 deletions.
45 changes: 38 additions & 7 deletions clients/client-cloudwatch-logs/src/commands/AssociateKmsKeyCommand.ts
View file
Expand Up @@ -36,17 +36,47 @@ export interface AssociateKmsKeyCommandOutput extends __MetadataBearer {}

/**
* @public
* <p>Associates the specified KMS key with the specified log
* group.</p>
* <p>Associating a KMS key with a log group overrides any existing
* <p>Associates the specified KMS key with either one log group in the account, or with all stored
* CloudWatch Logs query insights results in the account.</p>
* <p>When you use <code>AssociateKmsKey</code>, you specify either the <code>logGroupName</code> parameter
* or the <code>resourceIdentifier</code> parameter. You can't specify both of those parameters in the same operation.</p>
* <ul>
* <li>
* <p>Specify the <code>logGroupName</code> parameter to cause all log events stored in the log group to
* be encrypted with that key. Only the log events ingested after the key is associated are encrypted with that key.</p>
* <p>Associating a KMS key with a log group overrides any existing
* associations between the log group and a KMS key. After a KMS key is associated with a log group, all newly ingested data for the log group is encrypted
* using the KMS key. This association is stored as long as the data encrypted
* with the KMS keyis still within CloudWatch Logs. This enables CloudWatch Logs to decrypt this data whenever it is requested.</p>
* with the KMS key is still within CloudWatch Logs. This enables CloudWatch Logs to decrypt this data whenever it is requested.</p>
* <p>Associating
* a key with a log group does not cause the results of queries of that log group to be encrypted with that key. To have query
* results encrypted with a KMS key, you must use an <code>AssociateKmsKey</code> operation with the <code>resourceIdentifier</code>
* parameter that specifies a <code>query-result</code> resource. </p>
* </li>
* <li>
* <p>Specify the <code>resourceIdentifier</code> parameter with a <code>query-result</code> resource,
* to use that key to encrypt the stored results of all future
* <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html">StartQuery</a>
* operations in the account. The response from a
* <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetQueryResults.html">GetQueryResults</a>
* operation will still return
* the query results in plain text.</p>
* <p>Even if you have not associated a key with your query results, the query results are encrypted when stored,
* using the default CloudWatch Logs method.</p>
* <p>If you run a query from a monitoring account that queries logs in a source account, the
* query results key from the monitoring account, if any, is used.</p>
* </li>
* </ul>
* <important>
* <p>If you delete the key that is used to encrypt log events or log group query results,
* then all the associated stored log events or query results that were encrypted with that key
* will be unencryptable and unusable.</p>
* </important>
* <note>
* <p>CloudWatch Logs supports only symmetric KMS keys. Do not use an associate
* an asymmetric KMS key with your log group. For more information, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Using
* an asymmetric KMS key with your log group or query results. For more information, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Using
* Symmetric and Asymmetric Keys</a>.</p>
* </important>
* </note>
* <p>It can take up to 5 minutes for this operation to take effect.</p>
* <p>If you attempt to associate a KMS key with a log group but the KMS key does not exist or the KMS key is disabled, you receive an
* <code>InvalidParameterException</code> error. </p>
Expand All @@ -57,8 +87,9 @@ export interface AssociateKmsKeyCommandOutput extends __MetadataBearer {}
* // const { CloudWatchLogsClient, AssociateKmsKeyCommand } = require("@aws-sdk/client-cloudwatch-logs"); // CommonJS import
* const client = new CloudWatchLogsClient(config);
* const input = { // AssociateKmsKeyRequest
* logGroupName: "STRING_VALUE", // required
* logGroupName: "STRING_VALUE",
* kmsKeyId: "STRING_VALUE", // required
* resourceIdentifier: "STRING_VALUE",
* };
* const command = new AssociateKmsKeyCommand(input);
* const response = await client.send(command);
Expand Down
32 changes: 25 additions & 7 deletions clients/client-cloudwatch-logs/src/commands/DisassociateKmsKeyCommand.ts
View file
Expand Up @@ -36,20 +36,38 @@ export interface DisassociateKmsKeyCommandOutput extends __MetadataBearer {}

/**
* @public
* <p>Disassociates the associated KMS key from the specified log
* group.</p>
* <p>After the KMS key is disassociated from the log group, CloudWatch Logs stops encrypting newly ingested data for the log group. All previously ingested data
* remains encrypted, and CloudWatch Logs requires permissions for the KMS key
* whenever the encrypted data is requested.</p>
* <p>Note that it can take up to 5 minutes for this operation to take effect.</p>
* <p>Disassociates the specified KMS key from the specified log
* group or from all CloudWatch Logs Insights query results in the account.</p>
* <p>When you use <code>DisassociateKmsKey</code>, you specify either the <code>logGroupName</code> parameter
* or the <code>resourceIdentifier</code> parameter. You can't specify both of those parameters in the same operation.</p>
* <ul>
* <li>
* <p>Specify the <code>logGroupName</code> parameter to stop using the KMS key
* to encrypt future log events ingested and stored in the log group. Instead, they will be
* encrypted with the default CloudWatch Logs method. The log events that were ingested
* while the key was associated with the log group are still encrypted with that key.
* Therefore, CloudWatch Logs will need permissions for the key whenever that data is
* accessed.</p>
* </li>
* <li>
* <p>Specify the <code>resourceIdentifier</code> parameter with the <code>query-result</code>
* resource to stop using the KMS key to encrypt the results of all
* future <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html">StartQuery</a>
* operations in the account. They will instead be encrypted with the default CloudWatch Logs method. The results from queries that ran while the key was associated with
* the account are still encrypted with that key. Therefore, CloudWatch Logs will need
* permissions for the key whenever that data is accessed.</p>
* </li>
* </ul>
* <p>It can take up to 5 minutes for this operation to take effect.</p>
* @example
* Use a bare-bones client and the command you need to make an API call.
* ```javascript
* import { CloudWatchLogsClient, DisassociateKmsKeyCommand } from "@aws-sdk/client-cloudwatch-logs"; // ES Modules import
* // const { CloudWatchLogsClient, DisassociateKmsKeyCommand } = require("@aws-sdk/client-cloudwatch-logs"); // CommonJS import
* const client = new CloudWatchLogsClient(config);
* const input = { // DisassociateKmsKeyRequest
* logGroupName: "STRING_VALUE", // required
* logGroupName: "STRING_VALUE",
* resourceIdentifier: "STRING_VALUE",
* };
* const command = new DisassociateKmsKeyCommand(input);
* const response = await client.send(command);
Expand Down
1 change: 1 addition & 0 deletions clients/client-cloudwatch-logs/src/commands/GetQueryResultsCommand.ts
View file
Expand Up @@ -75,6 +75,7 @@ export interface GetQueryResultsCommandOutput extends GetQueryResultsResponse, _
* // bytesScanned: Number("double"),
* // },
* // status: "Scheduled" || "Running" || "Complete" || "Failed" || "Cancelled" || "Timeout" || "Unknown",
* // encryptionKey: "STRING_VALUE",
* // };
*
* ```
Expand Down
3 changes: 2 additions & 1 deletion clients/client-cloudwatch-logs/src/commands/PutSubscriptionFilterCommand.ts
View file
Expand Up @@ -48,7 +48,8 @@ export interface PutSubscriptionFilterCommandOutput extends __MetadataBearer {}
* filter, for same-account delivery.</p>
* </li>
* <li>
* <p>A logical destination that belongs to a different account, for cross-account delivery.</p>
* <p>A logical destination created with <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDestination.html">PutDestination</a> that belongs to a different account, for cross-account delivery.
* We currently support Kinesis Data Streams and Kinesis Data Firehose as logical destinations.</p>
* </li>
* <li>
* <p>An Amazon Kinesis Data Firehose delivery stream that belongs to the same account as
Expand Down
9 changes: 9 additions & 0 deletions clients/client-cloudwatch-logs/src/commands/StartQueryCommand.ts
View file
Expand Up @@ -39,6 +39,15 @@ export interface StartQueryCommandOutput extends StartQueryResponse, __MetadataB
* <p>Schedules a query of a log group using CloudWatch Logs Insights. You specify the log group
* and time range to query and the query string to use.</p>
* <p>For more information, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html">CloudWatch Logs Insights Query Syntax</a>.</p>
* <p>After you run a query using <code>StartQuery</code>, the query results are stored by CloudWatch Logs.
* You can use <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetQueryResults.html">GetQueryResults</a> to retrieve
* the results of a query, using the <code>queryId</code> that <code>StartQuery</code> returns.
* </p>
* <p>If you have associated a KMS key with the query results in this account,
* then
* <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html">StartQuery</a> uses that key to
* encrypt the results when it stores them. If no key is associated with query results, the query results are
* encrypted with the default CloudWatch Logs encryption method.</p>
* <p>Queries time out after 60 minutes of runtime. If your queries are timing out, reduce the
* time range being searched or partition your query into a number of queries.</p>
* <p>If you are using CloudWatch cross-account observability, you can use this operation in a
Expand Down
112 changes: 90 additions & 22 deletions clients/client-cloudwatch-logs/src/models/models_0.ts
View file
Expand Up @@ -72,15 +72,47 @@ export interface AccountPolicy {
export interface AssociateKmsKeyRequest {
/**
* <p>The name of the log group.</p>
* <p>In your <code>AssociateKmsKey</code> operation,
* you must specify either the <code>resourceIdentifier</code> parameter or the <code>logGroup</code> parameter,
* but you can't specify both.</p>
*/
logGroupName: string | undefined;
logGroupName?: string;

/**
* <p>The Amazon Resource Name (ARN) of the KMS key to use when encrypting log
* data. This must be a symmetric KMS key. For more information, see <a href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arn-syntax-kms">Amazon Resource Names</a> and <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Using Symmetric and Asymmetric
* Keys</a>.</p>
*/
kmsKeyId: string | undefined;

/**
* <p>Specifies the target for this operation. You must specify one of the following:</p>
* <ul>
* <li>
* <p>Specify the following ARN to have future <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetQueryResults.html">GetQueryResults</a>
* operations in this account encrypt the results
* with the specified KMS key. Replace
* <i>REGION</i> and <i>ACCOUNT_ID</i> with your Region and account ID.</p>
* <p>
* <code>arn:aws:logs:<i>REGION</i>:<i>ACCOUNT_ID</i>:query-result:*</code>
* </p>
* </li>
* <li>
* <p>Specify the ARN of a log group to have CloudWatch Logs use the KMS key
* to encrypt log events that are ingested and stored by that log group. The log group ARN must be in
* the following format. Replace
* <i>REGION</i> and <i>ACCOUNT_ID</i> with your Region and account ID.</p>
* <p>
* <code>arn:aws:logs:<i>REGION</i>:<i>ACCOUNT_ID</i>:log-group:<i>LOG_GROUP_NAME</i>
* </code>
* </p>
* </li>
* </ul>
* <p>In your <code>AssociateKmsKey</code> operation,
* you must specify either the <code>resourceIdentifier</code> parameter or the <code>logGroup</code> parameter,
* but you can't specify both.</p>
*/
resourceIdentifier?: string;
}

/**
Expand Down Expand Up @@ -1579,8 +1611,40 @@ export interface DescribeSubscriptionFiltersResponse {
export interface DisassociateKmsKeyRequest {
/**
* <p>The name of the log group.</p>
* <p>In your <code>DisassociateKmsKey</code> operation,
* you must specify either the <code>resourceIdentifier</code> parameter or the <code>logGroup</code> parameter,
* but you can't specify both.</p>
*/
logGroupName: string | undefined;
logGroupName?: string;

/**
* <p>Specifies the target for this operation. You must specify one of the following:</p>
* <ul>
* <li>
* <p>Specify the ARN of a log group to stop having CloudWatch Logs use the KMS key
* to encrypt log events that are ingested and stored by that log group. After you run this operation, CloudWatch Logs
* encrypts ingested log events with the default CloudWatch Logs method. The log group ARN must be in
* the following format. Replace
* <i>REGION</i> and <i>ACCOUNT_ID</i> with your Region and account ID.</p>
* <p>
* <code>arn:aws:logs:<i>REGION</i>:<i>ACCOUNT_ID</i>:log-group:<i>LOG_GROUP_NAME</i>
* </code>
* </p>
* </li>
* <li>
* <p>Specify the following ARN to stop using this key to encrypt the results of future <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html">StartQuery</a>
* operations in this account. Replace
* <i>REGION</i> and <i>ACCOUNT_ID</i> with your Region and account ID.</p>
* <p>
* <code>arn:aws:logs:<i>REGION</i>:<i>ACCOUNT_ID</i>:query-result:*</code>
* </p>
* </li>
* </ul>
* <p>In your <code>DisssociateKmsKey</code> operation,
* you must specify either the <code>resourceIdentifier</code> parameter or the <code>logGroup</code> parameter,
* but you can't specify both.</p>
*/
resourceIdentifier?: string;
}

/**
Expand Down Expand Up @@ -1918,9 +1982,9 @@ export interface GetLogGroupFieldsRequest {
logGroupName?: string;

/**
* <p>The time to set as the center of the query. If you specify <code>time</code>, the 15
* minutes before this time are queries. If you omit <code>time</code>, the 8 minutes before and
* 8 minutes after this time are searched.</p>
* <p>The time to set as the center of the query. If you specify <code>time</code>, the 8 minutes before and
* 8 minutes after this time are searched. If you omit <code>time</code>, the most recent 15 minutes
* up to the current time are searched.</p>
* <p>The <code>time</code> value is specified as epoch time, which is the number of seconds
* since <code>January 1, 1970, 00:00:00 UTC</code>.</p>
*/
Expand Down Expand Up @@ -2063,9 +2127,9 @@ export interface GetQueryResultsResponse {
results?: ResultField[][];

/**
* <p>Includes the number of log events scanned by the query, the number of log events that matched the
* query criteria, and the total number of bytes in the log events that were scanned. These values
* reflect the full raw results of the query.</p>
* <p>Includes the number of log events scanned by the query, the number of log events that
* matched the query criteria, and the total number of bytes in the scanned log events. These
* values reflect the full raw results of the query.</p>
*/
statistics?: QueryStatistics;

Expand All @@ -2077,6 +2141,14 @@ export interface GetQueryResultsResponse {
* reduce the time range being searched or partition your query into a number of queries.</p>
*/
status?: QueryStatus | string;

/**
* <p>If you associated an KMS key with the CloudWatch Logs Insights
* query results in this account, this field displays the ARN of the key that's used to encrypt
* the query results when <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html">StartQuery</a> stores
* them.</p>
*/
encryptionKey?: string;
}

/**
Expand Down Expand Up @@ -2231,9 +2303,9 @@ export interface PutAccountPolicyRequest {
policyType: PolicyType | string | undefined;

/**
* <p>Currently the only valid value for this parameter is <code>GLOBAL</code>, which specifies that the data
* <p>Currently the only valid value for this parameter is <code>ALL</code>, which specifies that the data
* protection policy applies to all log groups in the account. If you omit this parameter, the default
* of <code>GLOBAL</code> is used.</p>
* of <code>ALL</code> is used.</p>
*/
scope?: Scope | string;
}
Expand Down Expand Up @@ -2766,21 +2838,19 @@ export interface StartQueryRequest {
/**
* <p>The log group on which to perform the query.</p>
* <note>
* <p>A <code>StartQuery</code> operation must include exactly one
* of the following parameters:
* <code>logGroupName</code>, <code>logGroupNames</code> or <code>logGroupIdentifiers</code>.
* </p>
* <p>A <code>StartQuery</code> operation must include exactly one of the following
* parameters: <code>logGroupName</code>, <code>logGroupNames</code>, or
* <code>logGroupIdentifiers</code>. </p>
* </note>
*/
logGroupName?: string;

/**
* <p>The list of log groups to be queried. You can include up to 50 log groups.</p>
* <note>
* <p>A <code>StartQuery</code> operation must include exactly one
* of the following parameters:
* <code>logGroupName</code>, <code>logGroupNames</code> or <code>logGroupIdentifiers</code>.
* </p>
* <p>A <code>StartQuery</code> operation must include exactly one of the following
* parameters: <code>logGroupName</code>, <code>logGroupNames</code>, or
* <code>logGroupIdentifiers</code>. </p>
* </note>
*/
logGroupNames?: string[];
Expand All @@ -2791,10 +2861,8 @@ export interface StartQueryRequest {
* in a source account and you're using a monitoring account, you must specify the ARN of the log
* group here. The query definition must also be defined in the monitoring account.</p>
* <p>If you specify an ARN, the ARN can't end with an asterisk (*).</p>
* <p>A <code>StartQuery</code> operation must include exactly one
* of the following parameters:
* <code>logGroupName</code>, <code>logGroupNames</code> or <code>logGroupIdentifiers</code>.
* </p>
* <p>A <code>StartQuery</code> operation must include exactly one of the following parameters:
* <code>logGroupName</code>, <code>logGroupNames</code>, or <code>logGroupIdentifiers</code>. </p>
*/
logGroupIdentifiers?: string[];

Expand Down

0 comments on commit c16a285

Please sign in to comment.