import * as aiops from "@distilled.cloud/aws/aiops";
import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { PolicyStatement } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
export interface InvestigationGroupEncryptionConfiguration {
/**
* How investigation data is encrypted — `"AWS_OWNED_KEY"` (the default,
* an AWS owned key) or `"CUSTOMER_MANAGED_KMS_KEY"`.
* @default "AWS_OWNED_KEY"
*/
type?: aiops.EncryptionConfigurationType;
/**
* ID or ARN of the customer managed KMS key to encrypt investigation data
* with. Required when `type` is `"CUSTOMER_MANAGED_KMS_KEY"`.
*/
kmsKeyId?: string;
}
export interface InvestigationGroupCrossAccountConfiguration {
/**
* ARN of an IAM role in a source account that CloudWatch investigations
* assumes to retrieve telemetry during cross-account investigations.
*/
sourceRoleArn: string;
}
export interface InvestigationGroupProps {
/**
* Name of the investigation group. If omitted, a deterministic physical
* name is generated from the app, stage, and logical ID.
*
* Changing the name replaces the investigation group.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* ARN of the IAM role that CloudWatch investigations assumes to access
* telemetry (CloudWatch, X-Ray, CloudTrail, ...) during investigations.
* The role's trust policy must allow the `aiops.amazonaws.com` service
* principal to assume it.
*/
roleArn: string;
/**
* How long investigations and their data are retained (e.g. `"7 days"`
* or `Duration.days(7)`). Rounded to whole days on the wire
* (`retentionInDays`).
* The retention period cannot be updated in place — changing it replaces
* the investigation group.
* @default 90 days
*/
retention?: Duration.Input;
/**
* Encryption configuration for investigation data. Omit to use an AWS
* owned key.
* @default AWS owned key
*/
encryptionConfiguration?: InvestigationGroupEncryptionConfiguration;
/**
* Tag keys whose values CloudWatch investigations uses as boundaries to
* narrow the search for related telemetry (useful when resource names
* repeat across applications).
*/
tagKeyBoundaries?: string[];
/**
* Map of Amazon Q Developer in chat applications configuration ARNs to
* SNS topic ARNs, used to send investigation updates to chat channels.
*/
chatbotNotificationChannel?: Record<string, string[]>;
/**
* Whether investigations can query CloudTrail event history for the past
* seven days of events.
* @default true
*/
isCloudTrailEventHistoryEnabled?: boolean;
/**
* Source-account role configurations for cross-account investigations.
*/
crossAccountConfigurations?: InvestigationGroupCrossAccountConfiguration[];
/**
* IAM resource-policy statements attached to the investigation group,
* granting other principals or AWS services (for example
* `aiops.alarms.cloudwatch.amazonaws.com`, so CloudWatch alarms can start
* investigations) access to it. Serialized as a `2012-10-17` policy
* document via `PutInvestigationGroupPolicy`.
*
* Omit to leave any existing policy unmanaged; pass `[]` to delete a
* previously attached policy.
*/
policy?: PolicyStatement[];
/**
* Tags to apply to the investigation group. Merged with internal Alchemy
* tags.
*/
tags?: Record<string, string>;
}
export interface InvestigationGroup extends Resource<
"AWS.AIOps.InvestigationGroup",
InvestigationGroupProps,
{
/** Name of the investigation group. */
name: string;
/** ARN of the investigation group. */
arn: string;
/** ARN of the IAM role investigations assume to access telemetry. */
roleArn: string | undefined;
/**
* How long investigations and their data are retained, in whole days
* (the AWS wire unit for the `retention` prop).
*/
retentionInDays: number | undefined;
},
never,
Providers
> {}
/**
* A CloudWatch investigations *investigation group* — the one-time,
* per-Region container that configures who can run AI-assisted operational
* investigations, which IAM role is used to access telemetry, how long
* investigation data is retained, and how it is encrypted.
*
* You can have at most one investigation group per Region in an account, so
* replacements are performed delete-first.
* ### Creating an Investigation Group
* **Example:** Basic Investigation Group
* ```typescript
* import * as AIOps from "@alchemy.run/aws/AIOps";
* import * as IAM from "@alchemy.run/aws/IAM";
*
* const role = yield* IAM.Role("InvestigationsRole", {
* assumeRolePolicyDocument: {
* Version: "2012-10-17",
* Statement: [{
* Effect: "Allow",
* Principal: { Service: "aiops.amazonaws.com" },
* Action: ["sts:AssumeRole"],
* }],
* },
* managedPolicyArns: ["arn:aws:iam::aws:policy/AIOpsAssistantPolicy"],
* });
*
* const group = yield* AIOps.InvestigationGroup("Investigations", {
* roleArn: role.roleArn,
* });
* ```
*
* **Example:** Short Retention and Tag Boundaries
* ```typescript
* const group = yield* AIOps.InvestigationGroup("Investigations", {
* roleArn: role.roleArn,
* retention: "7 days",
* tagKeyBoundaries: ["Application"],
* tags: { Environment: "test" },
* });
* ```
*
* ### Resource Policy
* **Example:** Let CloudWatch Alarms Start Investigations
* ```typescript
* const group = yield* AIOps.InvestigationGroup("Investigations", {
* roleArn: role.roleArn,
* policy: [{
* Effect: "Allow",
* Principal: { Service: "aiops.alarms.cloudwatch.amazonaws.com" },
* Action: ["aiops:CreateInvestigation", "aiops:CreateInvestigationEvent"],
* Resource: "*",
* Condition: {
* StringEquals: { "aws:SourceAccount": "111122223333" },
* ArnLike: { "aws:SourceArn": "arn:aws:cloudwatch:us-east-1:111122223333:alarm:*" },
* },
* }],
* });
* ```
*
* @resource
*/
export const InvestigationGroup = Resource<InvestigationGroup>("AWS.AIOps.InvestigationGroup");
/**
* Bounded retry for `createInvestigationGroup` while the freshly created IAM
* role propagates — AIOps validates that it can assume the role at create
* time, which surfaces as a ValidationException/AccessDeniedException that
* mentions the role for the first seconds of the role's life.
*
* Explicitly annotated so the conditional `Retry.Return` type never leaks
* into declaration emit (it would widen `AWS.providers()` for consumers).
*/
const retryWhileRolePropagates = <A, R>(
self: Effect.Effect<A, aiops.CreateInvestigationGroupError, R>,
): Effect.Effect<A, aiops.CreateInvestigationGroupError, R> =>
Effect.retry(self, {
while: (e) =>
(e._tag === "ValidationException" || e._tag === "AccessDeniedException") &&
/role/i.test(e.message ?? ""),
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(8)]),
});
const sameStringArray = (l: readonly string[], r: readonly string[]) =>
l.length === r.length && l.every((v, i) => v === r[i]);
export const InvestigationGroupProvider = () =>
Provider.effect(
InvestigationGroup,
Effect.gen(function* () {
const createName = Effect.fn(function* (
id: string,
props: Pick<InvestigationGroupProps, "name">,
) {
return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
});
const observeByArn = (arn: string) =>
aiops
.getInvestigationGroup({ identifier: arn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
// At most one investigation group exists per Region, so scanning the
// list for our name is a single cheap call.
const findArnByName = (name: string) =>
aiops.listInvestigationGroups.items({}).pipe(
Stream.runCollect,
Effect.map((items) => Array.from(items).find((g) => g.name === name)?.arn),
);
const observe = Effect.fn(function* (name: string, arnHint: string | undefined) {
if (arnHint !== undefined) {
const found = yield* observeByArn(arnHint);
if (found !== undefined) return found;
}
const arn = yield* findArnByName(name);
return arn === undefined ? undefined : yield* observeByArn(arn);
});
const observedTags = (arn: string) =>
aiops.listTagsForResource({ resourceArn: arn }).pipe(
Effect.map((r) => {
const tags: Record<string, string> = {};
for (const [key, value] of Object.entries(r.tags ?? {})) {
if (value !== undefined) tags[key] = value;
}
return tags;
}),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({} as Record<string, string>),
),
);
const toAttributes = (live: aiops.GetInvestigationGroupResponse) => ({
name: live.name!,
arn: live.arn!,
roleArn: live.roleArn,
retentionInDays: live.retentionInDays,
});
return InvestigationGroup.Provider.of({
stables: ["name", "arn"],
list: () =>
Effect.gen(function* () {
const items = yield* aiops.listInvestigationGroups.items({}).pipe(Stream.runCollect);
const groups: {
name: string;
arn: string;
roleArn: string | undefined;
retentionInDays: number | undefined;
}[] = [];
for (const item of Array.from(items)) {
if (item.arn === undefined) continue;
const live = yield* observeByArn(item.arn);
if (live?.arn !== undefined && live.name !== undefined) {
groups.push(toAttributes(live));
}
}
return groups;
}),
read: Effect.fn(function* ({ id, olds, output, previous }) {
const name = output?.name ?? (yield* createName(id, olds ?? {}));
const live = yield* observe(name, output?.arn);
if (live?.arn === undefined || live.name === undefined) {
return undefined;
}
const attrs = toAttributes(live);
const tags = yield* observedTags(live.arn);
return (yield* hasAlchemyTags(id, tags))
? attrs
: unownedUnlessPrevious(attrs, previous, "name");
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds ?? {});
const newName = yield* createName(id, news ?? {});
// Only one investigation group may exist per Region, so a
// replacement must delete the old group before creating the new.
if (oldName !== newName) {
return { action: "replace", deleteFirst: true } as const;
}
// The retention period has no update API — replace to change it.
if (toWireDays(olds?.retention) !== toWireDays(news?.retention)) {
return { action: "replace", deleteFirst: true } as const;
}
// fall through: engine default update logic for mutable fields
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = output?.name ?? (yield* createName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// 1. OBSERVE — cloud state is authoritative; output.arn is only a
// cache of the identifier.
let live = yield* observe(name, output?.arn);
// 2. ENSURE — create when missing. A ConflictException here means
// a concurrent create raced us (one group per Region): if a
// group with OUR name now exists we converge on it, otherwise
// the conflict is a real error (a foreign group occupies the
// Region's single slot) and is propagated.
if (live === undefined) {
live = yield* aiops
.createInvestigationGroup({
name,
roleArn: news.roleArn,
retentionInDays: toWireDays(news.retention),
encryptionConfiguration: news.encryptionConfiguration,
tagKeyBoundaries: news.tagKeyBoundaries,
chatbotNotificationChannel: news.chatbotNotificationChannel,
isCloudTrailEventHistoryEnabled: news.isCloudTrailEventHistoryEnabled,
crossAccountConfigurations: news.crossAccountConfigurations,
tags: desiredTags,
})
.pipe(
retryWhileRolePropagates,
Effect.flatMap((created) =>
created.arn === undefined ? observe(name, undefined) : observeByArn(created.arn),
),
Effect.catchTag("ConflictException", (error) =>
observe(name, undefined).pipe(
Effect.flatMap((existing) =>
existing === undefined ? Effect.fail(error) : Effect.succeed(existing),
),
),
),
);
}
const arn = live?.arn ?? output?.arn;
// 3. SYNC — diff each OBSERVED mutable aspect against the desired
// state and PATCH only on drift. Aspects the user leaves
// undefined are unmanaged (left as observed).
if (live !== undefined && arn !== undefined) {
const update: Omit<aiops.UpdateInvestigationGroupRequest, "identifier"> = {};
if (live.roleArn !== news.roleArn) {
update.roleArn = news.roleArn;
}
if (
news.encryptionConfiguration !== undefined &&
((live.encryptionConfiguration?.type ?? "AWS_OWNED_KEY") !==
(news.encryptionConfiguration.type ?? "AWS_OWNED_KEY") ||
live.encryptionConfiguration?.kmsKeyId !== news.encryptionConfiguration.kmsKeyId)
) {
update.encryptionConfiguration = news.encryptionConfiguration;
}
if (
news.tagKeyBoundaries !== undefined &&
!sameStringArray(live.tagKeyBoundaries ?? [], news.tagKeyBoundaries)
) {
update.tagKeyBoundaries = news.tagKeyBoundaries;
}
if (
news.isCloudTrailEventHistoryEnabled !== undefined &&
live.isCloudTrailEventHistoryEnabled !== news.isCloudTrailEventHistoryEnabled
) {
update.isCloudTrailEventHistoryEnabled = news.isCloudTrailEventHistoryEnabled;
}
if (
news.chatbotNotificationChannel !== undefined &&
JSON.stringify(live.chatbotNotificationChannel ?? {}) !==
JSON.stringify(news.chatbotNotificationChannel)
) {
update.chatbotNotificationChannel = news.chatbotNotificationChannel;
}
if (
news.crossAccountConfigurations !== undefined &&
JSON.stringify(live.crossAccountConfigurations ?? []) !==
JSON.stringify(news.crossAccountConfigurations)
) {
update.crossAccountConfigurations = news.crossAccountConfigurations;
}
if (Object.keys(update).length > 0) {
yield* aiops.updateInvestigationGroup({
identifier: arn,
...update,
});
live = (yield* observeByArn(arn)) ?? live;
}
}
// 3b. SYNC POLICY — diff the OBSERVED resource policy against the
// desired policy document and put/delete only on drift.
// `policy: undefined` leaves any existing policy unmanaged;
// `policy: []` deletes it.
if (arn !== undefined && news.policy !== undefined) {
const observedPolicy = yield* aiops
.getInvestigationGroupPolicy({ identifier: arn })
.pipe(
Effect.map((r) => r.policy),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
if (news.policy.length === 0) {
if (observedPolicy !== undefined) {
yield* aiops
.deleteInvestigationGroupPolicy({ identifier: arn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
} else {
const desiredPolicy = JSON.stringify({
Version: "2012-10-17",
Statement: news.policy,
});
const inSync = yield* Effect.sync(() => {
if (observedPolicy === undefined) return false;
try {
return JSON.stringify(JSON.parse(observedPolicy)) === desiredPolicy;
} catch {
return false;
}
});
if (!inSync) {
yield* aiops.putInvestigationGroupPolicy({
identifier: arn,
policy: desiredPolicy,
});
}
}
}
// 3c. SYNC TAGS — diff against OBSERVED cloud tags so adoption
// converges (create-time tags only apply on first create).
if (arn !== undefined) {
const currentTags = yield* observedTags(arn);
const { upsert, removed } = diffTags(currentTags, desiredTags);
if (upsert.length > 0) {
yield* aiops.tagResource({
resourceArn: arn,
tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
if (removed.length > 0) {
yield* aiops.untagResource({
resourceArn: arn,
tagKeys: removed,
});
}
}
yield* session.note(name);
return {
name: live?.name ?? name,
arn: arn!,
roleArn: live?.roleArn ?? news.roleArn,
retentionInDays: live?.retentionInDays ?? toWireDays(news.retention),
};
}),
delete: Effect.fn(function* ({ output }) {
yield* aiops
.deleteInvestigationGroup({ identifier: output.arn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
});
}),
);