import * as grafana from "@distilled.cloud/aws/grafana";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { syncGrafanaTags, toTagRecord, unredact } from "./internal.ts";
export class GrafanaWorkspaceNotReady extends Data.TaggedError("GrafanaWorkspaceNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface WorkspaceProps {
/**
* A name for the workspace. If omitted, a deterministic physical name is
* generated.
*/
name?: string;
/**
* A description for the workspace.
*/
description?: string;
/**
* Whether the workspace can access AWS resources in only the current
* account (`CURRENT_ACCOUNT`) or throughout an organization
* (`ORGANIZATION`). Changing this replaces the workspace.
* @default "CURRENT_ACCOUNT"
*/
accountAccessType?: "CURRENT_ACCOUNT" | "ORGANIZATION";
/**
* The user authentication providers for the workspace. `AWS_SSO` requires
* IAM Identity Center to be enabled in the account; `SAML` configures an
* external IdP after creation. Changing this replaces the workspace.
*/
authenticationProviders: Array<"AWS_SSO" | "SAML">;
/**
* Whether AWS manages the workspace's IAM role and permissions
* (`SERVICE_MANAGED`) or you supply `workspaceRoleArn`
* (`CUSTOMER_MANAGED`). Changing this replaces the workspace.
* @default "SERVICE_MANAGED"
*/
permissionType?: "SERVICE_MANAGED" | "CUSTOMER_MANAGED";
/**
* ARN of an IAM role the workspace uses to access AWS data sources and
* notification channels. Required when `permissionType` is
* `CUSTOMER_MANAGED`.
*/
workspaceRoleArn?: string;
/**
* AWS services the workspace can query as data sources (e.g.
* `PROMETHEUS`, `CLOUDWATCH`, `XRAY`).
*/
dataSources?: string[];
/**
* The Grafana version for the workspace (e.g. `"10.4"`). If omitted, AWS
* chooses the current default.
*/
grafanaVersion?: string;
/**
* User-defined tags for the workspace.
*/
tags?: Record<string, string>;
}
export interface Workspace extends Resource<
"AWS.Grafana.Workspace",
WorkspaceProps,
{
/** The unique ID of the workspace. */
workspaceId: string;
/** The ARN of the workspace. */
workspaceArn: string;
/** The URL of the workspace's Grafana console. */
endpoint: string;
/** The Grafana version the workspace runs. */
grafanaVersion: string;
/** The current status of the workspace (`ACTIVE`, `CREATING`, ...). */
status: string;
},
never,
Providers
> {}
/**
* An Amazon Managed Grafana workspace — a fully-managed Grafana server for
* visualizing operational metrics, logs, and traces.
*
* Grafana workspaces require IAM Identity Center (AWS SSO) to be enabled in
* the account when `authenticationProviders` includes `AWS_SSO`. Workspace
* provisioning is asynchronous and can take a few minutes.
*
* ### Creating a Workspace
* **Example:** SSO-Authenticated Workspace
* ```typescript
* const workspace = yield* Grafana.Workspace("Dashboards", {
* accountAccessType: "CURRENT_ACCOUNT",
* authenticationProviders: ["AWS_SSO"],
* permissionType: "SERVICE_MANAGED",
* dataSources: ["PROMETHEUS", "CLOUDWATCH"],
* });
* ```
*
* @resource
*/
export const Workspace = Resource<Workspace>("AWS.Grafana.Workspace");
export const WorkspaceProvider = () =>
Provider.effect(
Workspace,
Effect.gen(function* () {
const arnFor = (accountId: string, region: string, id: string) =>
`arn:aws:grafana:${region}:${accountId}:/workspaces/${id}`;
const toAttrs = (accountId: string, region: string, ws: grafana.WorkspaceDescription) => ({
workspaceId: ws.id,
workspaceArn: arnFor(accountId, region, ws.id),
endpoint: ws.endpoint,
grafanaVersion: ws.grafanaVersion,
status: ws.status,
});
/** Describe a workspace by id; typed not-found → undefined. */
const describe = Effect.fn(function* (id: string) {
const response = yield* grafana
.describeWorkspace({ workspaceId: id })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
return response?.workspace;
});
/** Poll until the workspace reaches ACTIVE; fail fast on *FAILED*. */
const waitActive = Effect.fn(function* (id: string) {
const ws = yield* grafana.describeWorkspace({ workspaceId: id }).pipe(
Effect.map((r) => r.workspace),
Effect.repeat({
schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
until: (w) => w.status === "ACTIVE" || w.status.endsWith("FAILED"),
}),
);
if (ws.status !== "ACTIVE") {
return yield* new GrafanaWorkspaceNotReady({
message: `Grafana workspace ${id} did not become ACTIVE (status: ${ws.status})`,
});
}
return ws;
});
return {
stables: ["workspaceId", "workspaceArn", "endpoint"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return undefined;
const authChanged =
JSON.stringify([...(olds?.authenticationProviders ?? [])].sort()) !==
JSON.stringify([...news.authenticationProviders].sort());
if (
authChanged ||
(olds?.accountAccessType ?? "CURRENT_ACCOUNT") !==
(news.accountAccessType ?? "CURRENT_ACCOUNT") ||
(olds?.permissionType ?? "SERVICE_MANAGED") !==
(news.permissionType ?? "SERVICE_MANAGED")
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, output }) {
if (!output?.workspaceId) return undefined;
const { accountId, region } = yield* AWSEnvironment.current;
const ws = yield* describe(output.workspaceId);
if (ws === undefined) return undefined;
const attrs = toAttrs(accountId, region, ws);
const tags = toTagRecord(ws.tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news!.tags };
// 1. Observe — cloud state is authoritative; output is an id cache.
let ws =
output?.workspaceId !== undefined ? yield* describe(output.workspaceId) : undefined;
// 2. Ensure — create if missing, then wait for ACTIVE.
if (ws === undefined) {
const created = yield* grafana.createWorkspace({
accountAccessType: news!.accountAccessType ?? "CURRENT_ACCOUNT",
permissionType: news!.permissionType ?? "SERVICE_MANAGED",
authenticationProviders: news!.authenticationProviders,
workspaceName: news!.name,
workspaceDescription: news!.description,
workspaceRoleArn: news!.workspaceRoleArn,
workspaceDataSources: news!.dataSources,
grafanaVersion: news!.grafanaVersion,
tags: desiredTags,
});
ws = yield* waitActive(created.workspace.id);
} else {
// 3. Sync mutable settings via updateWorkspace when drifted.
const drifted =
(news!.name ?? undefined) !== unredact(ws.name) ||
(news!.description ?? undefined) !== unredact(ws.description) ||
JSON.stringify([...(news!.dataSources ?? [])].sort()) !==
JSON.stringify([...(ws.dataSources ?? [])].sort());
if (drifted) {
yield* grafana.updateWorkspace({
workspaceId: ws.id,
workspaceName: news!.name,
workspaceDescription: news!.description,
workspaceDataSources: news!.dataSources,
workspaceRoleArn: news!.workspaceRoleArn,
});
ws = yield* waitActive(ws.id);
}
}
// 3b. Sync tags — diff against OBSERVED cloud tags.
const arn = arnFor(accountId, region, ws.id);
yield* syncGrafanaTags(arn, desiredTags);
yield* session.note(ws.id);
return toAttrs(accountId, region, ws);
}),
delete: Effect.fn(function* ({ output }) {
yield* grafana.deleteWorkspace({ workspaceId: output.workspaceId }).pipe(
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
Effect.retry({
while: (e) => e._tag === "ConflictException",
schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(24)]),
}),
);
}),
list: () =>
grafana.listWorkspaces.pages({}).pipe(
Stream.runCollect,
Effect.flatMap((chunk) =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
return Array.from(chunk).flatMap((page) =>
page.workspaces.map((summary) => ({
workspaceId: summary.id,
workspaceArn: arnFor(accountId, region, summary.id),
endpoint: summary.endpoint,
grafanaVersion: summary.grafanaVersion,
status: summary.status,
})),
);
}),
),
),
};
}),
);