Guides

Getting Started

This guide takes you from zero to your first savings projection. Total hands-on time is about 15 minutes; the first optimization run follows a learning period (typically 14 days, or immediately if you have existing server access logs to backfill from).

Prerequisites

  • An AWS account with permission to create IAM roles and CloudFormation stacks.
  • One or more S3 buckets you'd like to optimize.
  • A TierPilot account (created during your onboarding call).

Step 1 — Deploy the connector stack

From the TierPilot console, click Connect AWS account. This opens the CloudFormation quick-create page in your AWS console with our template pre-loaded:

aws cloudformation create-stack \
  --stack-name tierpilot-connector \
  --template-url https://cf.tierpilot.io/connector/latest.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=ExternalId,ParameterValue=<your-external-id>

The stack creates three things:

  • The TierPilot Collector — a Lambda + Athena pipeline that aggregates and anonymizes access logs inside your account.
  • The TierPilot Operator — a Lambda that executes storage-class transitions, invokable only through its own API with your account's signing key.
  • A cross-account IAM role scoped to the minimum permissions listed in the security model. It cannot read object data.

Step 2 — Select buckets

Back in the TierPilot console, connected buckets appear within a minute. Toggle on the buckets you want to optimize. For each bucket TierPilot will:

  1. Enable S3 server access logging to a dedicated, lifecycle-managed log bucket in your account (created by the stack), unless logging is already enabled — in which case we use your existing target.
  2. Take a metadata inventory (sizes, storage classes, ages) via S3 Inventory.
  3. Begin the access-pattern learning period.
Already have months of server access logs? Point the collector at your existing log bucket during setup and TierPilot backfills history, often making the first optimization run available within hours.

Step 3 — Review your optimization policy

Before anything moves, configure guardrails per bucket:

  • Excluded prefixes — paths TierPilot must never touch.
  • Tier floor — e.g. “never below Glacier Instant Retrieval” to guarantee millisecond reads.
  • Approval mode — fully automatic, or hold each run for one-click approval.

Step 4 — Review the projection, go live

After the learning period you'll receive a savings projection: current monthly cost, optimized monthly cost, and the transition plan behind it. Approve it (or let automatic mode proceed) and the operator begins executing transitions, rate-limited and spread over hours to stay clear of your API limits. Progress and the running savings ledger are visible in the console from that point on.

Uninstalling

Delete the CloudFormation stack. This removes the collector, the operator, and the IAM role. Your objects stay exactly where they are — in whatever storage class they occupy at that moment — and nothing about your buckets depends on TierPilot continuing to exist.