---
title: AWS (SageMaker)
description: Create, inspect, and use SageMaker-backed stacks with S3 storage
---

A SageMaker stack runs each Kitaru execution as a managed SageMaker job and stores checkpoint outputs in S3.

Use this page when your team wants AWS-managed job execution instead of running an execution cluster yourself. If you want the broader stack model first, start with [Stacks](/stacks).

## Prerequisites

Before creating the stack, make sure these resources already exist:

- a Kitaru server you are connected to with `kitaru login ...`
- an S3 bucket or prefix for artifacts, for example `s3://my-bucket/kitaru`
- an ECR repository that can store the execution image, for example `123456789012.dkr.ecr.eu-west-1.amazonaws.com/kitaru`
- a SageMaker execution role ARN
- AWS credentials available to the Kitaru server / stack setup path
- an AWS region, for example `eu-west-1`

Kitaru creates the stack definition and component records. It does not create your S3 bucket, ECR repository, IAM role, or SageMaker account setup for you.

## Create the stack

```bash
kitaru stack create prod-sagemaker \
  --type sagemaker \
  --artifact-store s3://my-bucket/kitaru \
  --container-registry 123456789012.dkr.ecr.eu-west-1.amazonaws.com/kitaru \
  --region eu-west-1 \
  --execution-role arn:aws:iam::123456789012:role/SageMakerExecutionRole
```

The required SageMaker fields are:

| Field | Meaning |
|---|---|
| `--artifact-store` | S3 URI where Kitaru writes checkpoint outputs and saved artifacts |
| `--container-registry` | ECR repository where Kitaru pushes the run image |
| `--region` | AWS region for SageMaker jobs |
| `--execution-role` | IAM role used by SageMaker jobs at runtime |

You can add an optional credentials reference with `--credentials` when your server setup uses named cloud credentials.

## Set advanced SageMaker defaults

Named flags cover the common setup. Use `--extra` for lower-level component fields that Kitaru does not expose as first-class flags.

For example, write the asynchronous runner default explicitly with `--extra`:

```bash
kitaru stack create prod-sagemaker \
  --type sagemaker \
  --artifact-store s3://my-bucket/kitaru \
  --container-registry 123456789012.dkr.ecr.eu-west-1.amazonaws.com/kitaru \
  --region eu-west-1 \
  --execution-role arn:aws:iam::123456789012:role/SageMakerExecutionRole \
  --extra orchestrator.synchronous=false
```

`--async` is shorthand for that same `orchestrator.synchronous=false` setting. If you provide both, the explicit `--extra` value wins.

If you need provider-specific settings not shown here, keep them in a reviewed stack YAML template and pass them through `extra:` / `--extra`.

## Use YAML for repeatable setup

```yaml
name: prod-sagemaker
type: sagemaker
artifact_store: s3://my-bucket/kitaru
container_registry: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/kitaru
region: eu-west-1
execution_role: arn:aws:iam::123456789012:role/SageMakerExecutionRole
extra:
  orchestrator:
    synchronous: false
```

Create it with:

```bash
kitaru stack create -f stack.yaml
```

CLI flags override YAML values, and `--extra` values merge on top of the YAML `extra:` block.

## Inspect and use it

```bash
kitaru stack show prod-sagemaker
kitaru stack use prod-sagemaker
kitaru stack current
```

`kitaru stack show` reports the translated Kitaru view: runner, storage, image registry, region, execution role, active status, and whether the stack was created by Kitaru.

Once active, normal flow runs use the SageMaker stack unless a flow-level or run-level stack override is present.

## Delete it

```bash
kitaru stack delete prod-sagemaker
```

Use `--recursive` if you want Kitaru to remove Kitaru-managed component records too. Kitaru does not delete your cloud bucket, registry repository, IAM role, or other AWS resources.

## Related

<Cards>
  <Card title="Stacks" href="/stacks/" description="The shared stack model, precedence rules, YAML, --extra, and --async" />
  <Card title="Containerization" href="/guides/containerization/" description="How Kitaru builds and configures remote execution images" />
</Cards>
