import * as sagemaker from "@distilled.cloud/aws/sagemaker";
import { Unowned } 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, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export class ClusterSchedulerConfigInvalidProps extends Data.TaggedError(
"ClusterSchedulerConfigInvalidProps",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class ClusterSchedulerConfigUnexpectedResponse extends Data.TaggedError(
"ClusterSchedulerConfigUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type SchedulerResourceStatus = sagemaker.SchedulerResourceStatus;
export interface ClusterSchedulerConfigProps {
/**
* Name of the cluster policy. Maximum 63 characters, alphanumeric and
* hyphens.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* ARN of the EKS-orchestrated HyperPod cluster the policy applies to.
* Changing the cluster replaces the policy. AWS allows ONE cluster
* policy per cluster — creating a second fails with the typed
* `ClusterSchedulerConfigAlreadyExists` error.
*/
clusterArn: string;
/**
* The policy itself: task priority classes, fair-share allocation, and
* idle-resource sharing.
*/
schedulerConfig?: sagemaker.SchedulerConfig;
/**
* A description of the cluster policy.
*/
description?: string;
/**
* Tags to associate with the cluster policy. Merged with internal Alchemy
* tags.
*/
tags?: Record<string, string>;
}
export interface ClusterSchedulerConfig extends Resource<
"AWS.SageMaker.ClusterSchedulerConfig",
ClusterSchedulerConfigProps,
{
/**
* The cluster policy's ID.
*/
clusterSchedulerConfigId: string;
/**
* ARN of the cluster policy.
*/
clusterSchedulerConfigArn: string;
/**
* The cluster policy's name.
*/
name: string;
/**
* ARN of the HyperPod cluster the policy applies to.
*/
clusterArn: string;
/**
* The policy's current version (incremented on every update).
*/
clusterSchedulerConfigVersion: number;
},
never,
Providers
> {}
/**
* A SageMaker HyperPod cluster policy (task governance) — configures how an
* EKS-orchestrated HyperPod cluster prioritizes tasks and allocates idle
* compute across teams via priority classes and fair-share weights.
* ### Creating Cluster Policies
* **Example:** Priority Classes with Fair-Share
* ```typescript
* import * as AWS from "@alchemy.run/aws";
*
* const policy = yield* AWS.SageMaker.ClusterSchedulerConfig("Scheduler", {
* clusterArn: hyperpod.clusterArn,
* schedulerConfig: {
* PriorityClasses: [
* { Name: "inference", Weight: 100 },
* { Name: "training", Weight: 75 },
* ],
* FairShare: "Enabled",
* },
* description: "Prioritize inference over training",
* });
* ```
*
* @resource
*/
export const ClusterSchedulerConfig = Resource<ClusterSchedulerConfig>(
"AWS.SageMaker.ClusterSchedulerConfig",
);
const createConfigName = (id: string, props: { name?: string | undefined }) =>
props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 63 });
const describeConfigOrUndefined = (configId: string) =>
sagemaker
.describeClusterSchedulerConfig({ ClusterSchedulerConfigId: configId })
.pipe(Effect.catchTag("ResourceNotFound", () => Effect.undefined));
/**
* Look a cluster policy up by exact name — used when state was lost (read
* without output) or a create raced.
*/
const findConfigByName = Effect.fn(function* (name: string) {
const summaries = yield* sagemaker.listClusterSchedulerConfigs.pages({ NameContains: name }).pipe(
EffectStream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) => page.ClusterSchedulerConfigSummaries ?? []),
),
);
return summaries.find((s) => s.Name === name && s.Status !== "Deleted");
});
const fetchConfigTags = Effect.fn(function* (arn: string) {
const response = yield* sagemaker
.listTags({ ResourceArn: arn })
.pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
return Object.fromEntries(
(response?.Tags ?? []).flatMap((tag) =>
tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
),
);
});
const toAttrs = (
described: sagemaker.DescribeClusterSchedulerConfigResponse,
): ClusterSchedulerConfig["Attributes"] => ({
clusterSchedulerConfigId: described.ClusterSchedulerConfigId,
clusterSchedulerConfigArn: described.ClusterSchedulerConfigArn,
name: described.Name,
clusterArn: described.ClusterArn ?? "",
clusterSchedulerConfigVersion: described.ClusterSchedulerConfigVersion,
});
/**
* The cluster policy is still transitioning toward the awaited state —
* retried by the bounded wait schedule.
*/
class SchedulerConfigNotReady extends Data.TaggedError("SchedulerConfigNotReady")<{
readonly configId: string;
readonly status: string | undefined;
}> {}
/**
* The cluster policy converged to a terminal failed status.
*/
export class SchedulerConfigFailed extends Data.TaggedError("SchedulerConfigFailed")<{
readonly configId: string;
readonly status: string | undefined;
readonly message: string | undefined;
}> {}
const FAILED_STATUSES: string[] = [
"CreateFailed",
"CreateRollbackFailed",
"UpdateFailed",
"UpdateRollbackFailed",
"DeleteFailed",
"DeleteRollbackFailed",
];
// Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
// lifecycle code leaks `Retry.Return`'s conditional type into declaration
// emit and widens the provider layer to `unknown` for every consumer of
// `AWS.providers()`.
const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "SchedulerConfigNotReady",
schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(60)]),
});
const waitForConfig = (configId: string, target: "Ready" | "Gone") =>
retryWhileNotReady(
Effect.gen(function* () {
const described = yield* describeConfigOrUndefined(configId);
if (target === "Gone") {
if (described === undefined || described.Status === "Deleted") return;
if (FAILED_STATUSES.includes(described.Status)) {
return yield* new SchedulerConfigFailed({
configId,
status: described.Status,
message: described.FailureReason,
});
}
return yield* new SchedulerConfigNotReady({ configId, status: described.Status });
}
if (described?.Status === "Created" || described?.Status === "Updated") {
return;
}
if (described !== undefined && FAILED_STATUSES.includes(described.Status)) {
return yield* new SchedulerConfigFailed({
configId,
status: described.Status,
message: described.FailureReason,
});
}
return yield* new SchedulerConfigNotReady({ configId, status: described?.Status });
}),
);
export const ClusterSchedulerConfigProvider = () =>
Provider.effect(
ClusterSchedulerConfig,
Effect.gen(function* () {
return {
stables: ["clusterSchedulerConfigId", "clusterSchedulerConfigArn", "name", "clusterArn"],
list: () =>
Effect.gen(function* () {
const summaries = yield* sagemaker.listClusterSchedulerConfigs.pages({}).pipe(
EffectStream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) => page.ClusterSchedulerConfigSummaries ?? []),
),
);
return summaries.flatMap((s) =>
s.ClusterSchedulerConfigId !== undefined && s.Status !== "Deleted"
? [
{
clusterSchedulerConfigId: s.ClusterSchedulerConfigId,
clusterSchedulerConfigArn: s.ClusterSchedulerConfigArn ?? "",
name: s.Name ?? "",
clusterArn: s.ClusterArn ?? "",
clusterSchedulerConfigVersion: s.ClusterSchedulerConfigVersion ?? 1,
},
]
: [],
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const configId =
output?.clusterSchedulerConfigId ??
(yield* findConfigByName(yield* createConfigName(id, olds ?? {})))
?.ClusterSchedulerConfigId;
if (configId === undefined) return undefined;
const described = yield* describeConfigOrUndefined(configId);
if (!described || described.Status === "Deleting" || described.Status === "Deleted") {
return undefined;
}
const attrs = toAttrs(described);
const tags = yield* fetchConfigTags(attrs.clusterSchedulerConfigArn);
return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
const oldName = yield* createConfigName(id, olds);
const newName = yield* createConfigName(id, news);
// The name and target cluster are fixed at creation.
if (oldName !== newName || olds.clusterArn !== news.clusterArn) {
return { action: "replace" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
if (!news) {
return yield* new ClusterSchedulerConfigInvalidProps({
message: "SageMaker ClusterSchedulerConfig requires props",
});
}
const name = yield* createConfigName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
// Observe — by cached id first, then by name (lost state or race).
let configId = output?.clusterSchedulerConfigId;
let described =
configId !== undefined ? yield* describeConfigOrUndefined(configId) : undefined;
if (described === undefined) {
const found = yield* findConfigByName(name);
described =
found?.ClusterSchedulerConfigId !== undefined
? yield* describeConfigOrUndefined(found.ClusterSchedulerConfigId)
: undefined;
}
// Ensure — create if missing; a Conflict means a concurrent
// create won the race, so re-observe by name.
if (described === undefined) {
const created = yield* sagemaker
.createClusterSchedulerConfig({
Name: name,
ClusterArn: news.clusterArn,
SchedulerConfig: news.schedulerConfig,
Description: news.description,
Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
Key,
Value,
})),
})
.pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
configId =
created?.ClusterSchedulerConfigId ??
(yield* findConfigByName(name))?.ClusterSchedulerConfigId;
if (configId === undefined) {
return yield* new ClusterSchedulerConfigUnexpectedResponse({
message: `failed to create cluster scheduler config ${name}`,
});
}
yield* session.note(`Creating cluster policy ${name}...`);
yield* waitForConfig(configId, "Ready");
} else {
configId = described.ClusterSchedulerConfigId;
// Wait out any in-flight transition before diffing.
yield* waitForConfig(configId, "Ready");
described = yield* describeConfigOrUndefined(configId);
// Sync — diff observed policy against desired.
if (
described !== undefined &&
(JSON.stringify(described.SchedulerConfig) !== JSON.stringify(news.schedulerConfig) ||
(described.Description ?? undefined) !== (news.description ?? undefined))
) {
yield* sagemaker.updateClusterSchedulerConfig({
ClusterSchedulerConfigId: configId,
TargetVersion: described.ClusterSchedulerConfigVersion,
SchedulerConfig: news.schedulerConfig,
Description: news.description,
});
yield* session.note(`Updating cluster policy ${name}...`);
yield* waitForConfig(configId, "Ready");
}
}
described = yield* describeConfigOrUndefined(configId);
if (described === undefined) {
return yield* new ClusterSchedulerConfigUnexpectedResponse({
message: `failed to read reconciled cluster scheduler config ${name}`,
});
}
const attrs = toAttrs(described);
// Sync tags — diff against OBSERVED cloud tags.
const currentTags = yield* fetchConfigTags(attrs.clusterSchedulerConfigArn);
const { removed, upsert } = diffTags(currentTags, desiredTags);
if (removed.length > 0) {
yield* sagemaker.deleteTags({
ResourceArn: attrs.clusterSchedulerConfigArn,
TagKeys: removed,
});
}
if (upsert.length > 0) {
yield* sagemaker.addTags({
ResourceArn: attrs.clusterSchedulerConfigArn,
Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
});
}
yield* session.note(attrs.clusterSchedulerConfigArn);
return attrs;
}),
delete: Effect.fn(function* ({ output }) {
yield* sagemaker
.deleteClusterSchedulerConfig({
ClusterSchedulerConfigId: output.clusterSchedulerConfigId,
})
.pipe(Effect.catchTag("ResourceNotFound", () => Effect.void));
yield* waitForConfig(output.clusterSchedulerConfigId, "Gone");
}),
};
}),
);