# SageMaker Stacks

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](/kitaru/agent-runtime-stacks/stacks.md).

## 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

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Stacks</strong></td><td>The shared stack model, precedence rules, YAML, --extra, and --async</td><td><a href="/pages/Md0YgNiF5z5NwLEvQ5aR">/pages/Md0YgNiF5z5NwLEvQ5aR</a></td></tr><tr><td><strong>Containerization</strong></td><td>How Kitaru builds and configures remote execution images</td><td><a href="/pages/9JL1jz8yokIPcq1wr5RE">/pages/9JL1jz8yokIPcq1wr5RE</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zenml.io/kitaru/agent-runtime-stacks/sagemaker-stacks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.