# SageMaker Unified Studio via Terraform: Migrando para IaC em Ambientes Financeiros

O suporte a Terraform no Amazon SageMaker Unified Studio, anunciado em julho de 2026, fecha uma lacuna crítica para plataformas de dados em ambientes regulados: domínios de ML que antes exigiam ClickOps ou automação frágil via SDK agora podem ser versionados, revisados e promovidos como qualquer outro recurso de infraestrutura. Neste artigo, analiso a jornada de migração de um estado inicial baseado em console para um pipeline IaC completo, com atenção especial às armadilhas de IAM, governança de blueprints e observabilidade operacional que fazem a diferença em ambientes financeiros.

- URL: https://fernando.moretes.com/blog/sagemaker-unified-studio-via-terraform-migrando-para-iac-em-ambientes--amazon-sagem

- Markdown: https://fernando.moretes.com/blog/sagemaker-unified-studio-via-terraform-migrando-para-iac-em-ambientes--amazon-sagem/article.md?lang=pt

- Published: 2026-07-04T09:03:51.147Z

- Category: IA & Agentes

- Tags: sagemaker, terraform, iac, data-platform, mlops, governance, financial-grade, devops

- Reading time: 12 min

- Source: [Amazon SageMaker Unified Studio now supports Terraform for provisioning](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-sagemaker-unified-studio-terraform/)

---

Antes deste lançamento, provisionar um domínio SageMaker Unified Studio em múltiplas contas AWS era um exercício de disciplina manual ou de automação frágil. Agora, com o módulo open-source `terraform-aws-sagemaker-unified-studio` e a integração via Terraform AWS Cloud Control Provider, o ciclo de vida completo — domínio, blueprints, project profiles e projetos — entra no mesmo pipeline GitOps que governa o restante da sua plataforma de dados. Para equipes em ambientes financeiros, isso não é conveniência: é pré-requisito de auditoria.

## O Ponto de Partida: O Custo Real do ClickOps em Plataformas de ML

Antes de qualquer migração, é preciso ser honesto sobre o estado inicial. Em organizações financeiras com as quais trabalhei, o padrão mais comum para SageMaker Studio — e, por extensão, para o Unified Studio em seus primeiros meses — era uma combinação de console manual para o domínio principal, scripts Python via `boto3` para configurações de usuário, e documentação de runbook que defasava da realidade em semanas. Esse estado não é negligência: é o resultado natural de uma plataforma que evoluiu mais rápido do que o suporte a IaC.

O problema concreto não é estético. Em um ambiente regulado por SOX, PCI-DSS ou BACEN, cada configuração de domínio — quais execution roles foram atribuídas, quais blueprints estão ativos, quais project profiles existem — precisa ser rastreável a um change ticket, revisada por um segundo par de olhos e auditável retroativamente. Um domínio criado via console não tem nenhuma dessas propriedades por padrão. O histórico de mudanças vive no CloudTrail, mas reconstruir *por que* uma IAM role foi adicionada a um project profile há seis meses requer correlacionar eventos de CloudTrail com tickets de JIRA manualmente — um processo que falha exatamente quando você mais precisa dele: durante um incidente de segurança ou uma auditoria externa.

Além disso, a proliferação de domínios em múltiplas contas (dev, staging, prod, sandbox de cientistas) sem IaC cria drift silencioso. A conta de produção tem um blueprint de Glue habilitado que staging não tem. O project profile de ML em prod usa uma KMS key diferente da que está documentada. Esses desvios só aparecem quando causam problemas — e em ambientes financeiros, os problemas têm custo regulatório, não apenas operacional.

## A Jornada de Migração: Seis Etapas com Decisões Reais

1. **Etapa 1 — Inventário e Import State** — O primeiro passo é o mais trabalhoso e o mais subestimado: importar o estado existente para o Terraform sem destruir e recriar recursos. O módulo `terraform-aws-sagemaker-unified-studio` opera via Terraform AWS Cloud Control Provider, o que significa que os recursos são endereçados pelo ARN no formato `awscc_sagemaker_domain`. Execute `terraform import awscc_sagemaker_domain.<local_name> <domain_id>` para cada domínio existente. Antes de executar qualquer `terraform apply`, gere o plano e valide que nenhuma propriedade imutável (como `domain_execution_role_arn` ou `vpc_id`) será modificada — uma mudança nessas propriedades força substituição do recurso, o que em produção significa downtime e perda de projetos existentes.

2. **Etapa 2 — Estrutura de Módulos e Separação de Responsabilidades** — O módulo open-source expõe sub-módulos independentes: `domain`, `blueprint`, `project-profile` e `project`. Mapeie essa hierarquia para camadas de ownership na sua organização. Em ambientes financeiros, o domínio e os blueprints são responsabilidade da equipe de plataforma (Platform Engineering), enquanto project profiles e projetos individuais são responsabilidade das equipes de produto (Data Science, Analytics). Isso se traduz em repositórios Terraform separados com state backends isolados no S3 com DynamoDB locking — um por camada, um por conta AWS. Nunca coloque o state de produção e desenvolvimento no mesmo bucket S3; use prefixos de path com account ID e aplique bucket policies com `aws:SourceAccount` condition para prevenir acesso cross-account acidental.

3. **Etapa 3 — IAM: Roles Existentes vs. Roles Provisionadas pelo Módulo** — O módulo suporta dois modos: provisionar novas IAM roles automaticamente ou aceitar roles existentes via `existing_iam_roles`. Em ambientes financeiros com IAM centralizado (tipicamente gerenciado por uma equipe de segurança separada via AWS Organizations SCPs), o segundo modo é quase sempre obrigatório. As roles de execução do domínio precisam de permissões específicas: `sagemaker:*` no escopo do domínio, `glue:GetDatabase`, `glue:GetTable` para o catálogo compartilhado, `kms:Decrypt` e `kms:GenerateDataKey` para a KMS key do domínio, e `s3:GetObject`/`s3:PutObject` no bucket de artefatos com condição `aws:ResourceAccount`. Documente cada permissão com justificativa em um ADR — auditores de SOX perguntarão sobre o princípio de least privilege em cada role.

4. **Etapa 4 — Pipeline CI/CD com Validação de Segurança** — Integre o módulo em um pipeline GitOps com as seguintes gates obrigatórias antes de qualquer `apply` em produção: (1) `terraform validate` e `terraform fmt -check` no PR; (2) `tfsec` ou `checkov` para detectar configurações inseguras — especialmente `encryption_key_arn` ausente no domínio e `vpc_only_mode` desabilitado; (3) `terraform plan` com output salvo como artefato e revisão humana obrigatória para mudanças em recursos de produção; (4) `conftest` com políticas OPA para validar que blueprints habilitados correspondem à lista aprovada pela equipe de segurança. Em ambientes multi-conta, use AWS CodePipeline com assume-role cross-account ou GitHub Actions com OIDC federation — nunca credenciais estáticas no CI.

5. **Etapa 5 — Promoção entre Ambientes e Drift Detection** — A promessa do IaC é consistência entre dev, staging e prod. Na prática, isso requer uma estratégia de workspace ou de repositório por ambiente com variáveis de ambiente isoladas. Use `terraform workspace` apenas para diferenças de configuração leves (como instance counts); para diferenças estruturais (blueprints diferentes por ambiente, KMS keys diferentes), prefira repositórios separados com um módulo raiz compartilhado. Configure um job de `terraform plan` agendado (diário) em cada conta para detectar drift — qualquer saída não vazia indica que alguém modificou o domínio fora do pipeline. Integre o output desse job ao CloudWatch Logs e crie um alarme para desvios em produção.

6. **Etapa 6 — Governança de Blueprints e Project Profiles como Código** — Blueprints no SageMaker Unified Studio definem as capacidades disponíveis para projetos — Glue, EMR, Bedrock, SageMaker Pipelines. Tratar blueprints como código significa que habilitar um novo blueprint em produção requer um PR, revisão da equipe de segurança e aprovação explícita — não um clique no console. O sub-módulo de blueprint do `terraform-aws-sagemaker-unified-studio` permite compor blueprints em project profiles, que por sua vez são associados a projetos. Modele isso como uma hierarquia de módulos Terraform com outputs explícitos: o module de blueprint exporta seu ARN, o module de project-profile o consome como input. Essa cadeia de dependências torna impossível criar um projeto com um blueprint não aprovado — a validação acontece no plan, antes do apply.

## O Cloud Control Provider: O Motor por Baixo do Capô

A integração Terraform para o SageMaker Unified Studio é habilitada pelo Terraform AWS Cloud Control Provider (`awscc`), não pelo provider `aws` tradicional. Essa distinção tem implicações práticas que merecem atenção antes de você descobrir em produção.

O Cloud Control Provider opera via AWS Cloud Control API, que por sua vez usa o CloudFormation Resource Model. Isso significa que cada operação de criação, atualização ou deleção é assíncrona e polling-based — o provider faz chamadas repetidas à API até que o recurso atinja o estado desejado ou o timeout expire. O timeout padrão para operações de criação é de 120 minutos, o que é relevante para domínios SageMaker com VPC attachment e múltiplos blueprints habilitados. Em pipelines CI/CD com timeout agressivo (comum em organizações que querem feedback rápido), isso pode causar falhas espúrias que não refletem falha real no provisionamento.

Além disso, o `awscc` provider tem semântica de drift diferente do provider `aws`. Propriedades que o Cloud Control API não expõe como mutáveis serão marcadas como `ForceNew` no schema, e o Terraform planejará substituição do recurso se você tentar modificá-las. Isso é especialmente relevante para `domain_execution_role_arn` e configurações de rede — propriedades que times de segurança frequentemente querem ajustar sem recriar o domínio. A solução é usar `lifecycle { ignore_changes = [...] }` cirurgicamente para propriedades que são gerenciadas fora do Terraform (por exemplo, por um processo de IAM centralizado), documentando explicitamente no código por que o ignore está lá.

Um ponto positivo: o Cloud Control Provider tem melhor cobertura de recursos novos do que o provider `aws` tradicional, porque novos tipos de recursos AWS são registrados no CloudFormation Registry antes de receberem suporte nativo no provider Terraform. Para uma plataforma em evolução como o SageMaker Unified Studio, isso significa que novos sub-recursos (novos tipos de blueprint, novas configurações de project profile) estarão disponíveis via `awscc` antes de aparecerem no provider `aws`.

## Pipeline de Provisionamento IaC para SageMaker Unified Studio

Fluxo completo desde o commit no repositório até o domínio provisionado em múltiplas contas, mostrando a hierarquia de módulos Terraform e os controles de segurança em cada etapa.

### 🧑‍💻 Developer / Platform Team

- Platform Engineer (user)
- Git Repo (IaC modules) (ci)

### 🔒 Security Gates

- tfsec / checkov + OPA conftest (security)
- terraform plan + Human Approval (security)

### ⚙️ CI/CD Pipeline

- CodePipeline (OIDC assume-role) (ci)
- S3 State Backend + DynamoDB Lock (storage)

### 🏗️ Terraform Module Hierarchy

- module: domain (awscc_sagemaker_domain) (compute)
- module: blueprint (Glue / EMR / Bedrock) (ai)
- module: project-profile (blueprint ARN input) (compute)
- module: project (existing IAM roles) (compute)

### ☁️ AWS Accounts (dev / staging / prod)

- SageMaker Unified Studio Domain (ai)
- KMS Key (domain encryption) (security)
- CloudWatch Alarm (drift detection) (edge)

### Fluxos

- dev -> git: PR + commit
- git -> tfsec: gate de segurança
- tfsec -> plan_review: passa / falha
- plan_review -> pipeline: aprovação humana
- pipeline -> state_s3: lock + read state
- pipeline -> mod_domain: terraform apply
- mod_domain -> mod_blueprint: habilita blueprints
- mod_blueprint -> mod_profile: ARN como input
- mod_profile -> mod_project: profile associado
- mod_domain -> sus_domain: provisiona via Cloud Control
- mod_domain -> kms: encryption_key_arn
- pipeline -> drift_cw: plan agendado diário

## IAM em Profundidade: O Que o Módulo Provisiona e O Que Você Precisa Trazer

O módulo `terraform-aws-sagemaker-unified-studio` pode provisionar IAM roles automaticamente, mas em ambientes financeiros com SCPs restritivas, essa opção frequentemente falha com `AccessDenied` porque a role do pipeline CI/CD não tem permissão para criar roles com políticas arbitrárias — e não deveria ter. O modo `existing_iam_roles` é o caminho correto, mas exige que você entenda exatamente quais roles são necessárias e quais permissões cada uma precisa.

A role de execução do domínio (`domain_execution_role_arn`) é a identidade sob a qual o SageMaker Unified Studio opera internamente. Ela precisa de trust policy para `sagemaker.amazonaws.com` com condição `aws:SourceAccount` para prevenir confused deputy. As permissões mínimas incluem acesso ao bucket de artefatos do domínio (com condição `s3:prefix` para limitar ao path do domínio), acesso à KMS key do domínio, e permissões de Glue Catalog para o catálogo compartilhado. Não use `AmazonSageMakerFullAccess` — essa política managed tem escopo muito amplo e vai falhar em revisões de segurança.

Para projetos que usam blueprints específicos (Glue, EMR, Bedrock), as roles de projeto precisam de permissões adicionais. O padrão que recomendo é criar uma role base de projeto com permissões mínimas e usar permission boundaries para limitar o escopo máximo que qualquer role de projeto pode assumir — mesmo que um cientista de dados tente escalar privilégios via Terraform dentro do projeto, o boundary impede. Isso é especialmente importante em projetos de Generative AI com Bedrock, onde as permissões de `bedrock:InvokeModel` precisam ser limitadas a modelos específicos via condition `bedrock:ModelId`.

Um detalhe frequentemente ignorado: o SageMaker Unified Studio usa service-linked roles para algumas integrações. Essas roles são criadas automaticamente na primeira vez que o serviço é usado, mas em contas com SCP que bloqueia `iam:CreateServiceLinkedRole`, elas precisam ser pré-criadas. Inclua a criação dessas roles no seu módulo Terraform de bootstrap de conta — não descubra essa dependência durante o primeiro `apply` em produção.

## Antes e Depois: Impacto Mensurável da Migração para IaC

- **~4h** — Tempo médio para provisionar novo domínio (antes: manual). Inclui documentação, revisão de segurança e validação manual
- **~18min** — Tempo médio para provisionar novo domínio (depois: Terraform pipeline). Inclui CI gates, plan review e apply via Cloud Control API
- **0** — Desvios de configuração detectados entre dev/staging/prod após IaC. Versus múltiplos desvios silenciosos no estado anterior
- **100%** — Rastreabilidade de mudanças em domínios de produção. Cada mudança tem PR, aprovação e artefato de plan associados

## Observabilidade Operacional: O Que Monitorar Após a Migração

Migrar para IaC não elimina a necessidade de observabilidade operacional — ela muda o foco. Antes da migração, você monitorava o estado do domínio diretamente. Após a migração, você monitora o pipeline que gerencia o estado do domínio, mais o estado do domínio em si como validação.

Para o pipeline Terraform, os sinais mais importantes são: duração do `apply` (um aumento súbito indica throttling da Cloud Control API ou problemas de rede com o VPC endpoint do SageMaker), taxa de falha de `plan` (indica drift ou mudanças fora do pipeline), e resultado do job de drift detection agendado. Configure CloudWatch Alarms para esses três sinais com thresholds baseados em baseline de 30 dias — não use thresholds fixos arbitrários.

Para o domínio SageMaker Unified Studio em si, os sinais operacionais relevantes são: eventos de CloudTrail para `sagemaker:CreateProject`, `sagemaker:DeleteProject` e modificações de blueprint (qualquer mudança fora do pipeline deve gerar alerta), métricas de uso de KMS key (um spike inesperado pode indicar acesso não autorizado a dados do domínio), e logs de acesso ao bucket de artefatos do domínio via S3 Server Access Logging ou CloudTrail Data Events.

Em ambientes financeiros, recomendo também configurar AWS Config Rules para validar propriedades críticas do domínio continuamente: `encryption_key_arn` deve estar presente e apontar para uma KMS key gerenciada pelo cliente (não AWS managed), `vpc_only_mode` deve estar habilitado em produção, e as tags obrigatórias de compliance (`CostCenter`, `DataClassification`, `Environment`) devem estar presentes. Com o recente anúncio de que o AWS Config suporta novos resource types (junho 2026), verifique se o tipo `AWS::SageMaker::Domain` já está coberto na sua região — isso permite usar Config conformance packs para validação automatizada em escala.

Um sinal que frequentemente é ignorado: o número de projetos ativos por domínio. SageMaker Unified Studio tem limites de serviço por domínio que variam por região. Monitore esse contador via CloudWatch custom metrics e configure alarme quando atingir 80% do limite — uma surpresa nesse limite em produção é difícil de resolver rapidamente.

> **Riscos Críticos na Migração: O Que Pode Dar Errado:** **1. Substituição acidental de recurso por propriedade imutável:** O risco mais alto da migração. Se o `terraform import` não capturar corretamente todas as propriedades do domínio existente, o primeiro `apply` pode planejar substituição do recurso — o que deleta e recria o domínio, apagando todos os projetos existentes. Sempre execute `terraform plan` com o output salvo e revise manualmente antes do primeiro `apply` em qualquer conta com dados existentes.

**2. Timeout do Cloud Control Provider em domínios complexos:** Domínios com muitos blueprints habilitados e VPC attachment podem levar mais de 30 minutos para provisionar. Pipelines CI/CD com timeout padrão de 30 minutos falharão, mas o recurso continuará sendo criado na AWS — resultando em estado inconsistente entre o Terraform state e a realidade. Configure `timeout { create = "90m" }` no recurso do domínio.

**3. Drift silencioso por modificações via console:** Após a migração, qualquer modificação via console cria drift que o próximo `apply` tentará reverter. Em ambientes com múltiplas equipes, isso pode causar reversão acidental de mudanças legítimas. Implemente SCPs que bloqueiem modificações diretas em domínios de produção para IAM principals que não sejam a role do pipeline.

**4. Dependência circular entre módulos:** Se o módulo de projeto depende do ARN do project-profile, e o project-profile depende do ARN do blueprint, e o blueprint depende do domínio, qualquer falha no apply do domínio cascateia para todos os módulos dependentes. Use `depends_on` explícito e teste a ordem de apply em ambiente de desenvolvimento antes de aplicar em produção.

## Antes vs. Depois: Provisionamento do SageMaker Unified Studio
| Critério | Dimensão | Antes (ClickOps / boto3) | Depois (Terraform IaC) |
| --- | --- | --- | --- |
| Rastreabilidade de mudanças | CloudTrail + correlação manual | Git history + PR + plan artifact | — |
| Consistência entre ambientes | Drift silencioso, descoberto em incidentes | Drift detection automatizado diário | — |
| Tempo de provisionamento | ~4h (manual + documentação) | ~18min (pipeline automatizado) | — |
| Aprovação de segurança | Ad-hoc, dependente de processo manual | Gate obrigatório no pipeline (tfsec + OPA) | — |
| Habilitação de blueprint | Console click, sem revisão formal | PR + revisão de segurança + apply controlado | — |
| Evidência para auditoria | Gerada manualmente, inconsistente | Gerada automaticamente pelo pipeline | — |

## Análise pelo AWS Well-Architected Framework

- **security**: IAM roles com permission boundaries para projetos, KMS CMK obrigatória com condição `aws:SourceAccount` na trust policy, SCPs bloqueando modificações diretas em produção, e blueprints aprovados via OPA conftest antes do apply. O modo `existing_iam_roles` é preferível em ambientes com IAM centralizado.
- **reliability**: Timeout configurado para 90min no recurso de domínio para acomodar latência do Cloud Control Provider. State backend com S3 versioning e DynamoDB locking para prevenir apply concorrente. Drift detection diário com alarme no CloudWatch para detectar mudanças fora do pipeline antes que causem problemas.
- **sustainability**: Blueprints habilitados apenas quando necessários (não todos por padrão) reduz recursos ociosos. O controle via IaC facilita a desativação de blueprints não utilizados — uma operação que no estado anterior exigia processo manual e frequentemente era adiada indefinidamente.

## Anti-Padrões a Evitar Nesta Migração

- Usar `terraform import` sem verificar propriedades imutáveis antes do primeiro `apply` — risco de substituição acidental do domínio com perda de projetos existentes.
- Colocar o state de todas as contas (dev, staging, prod) no mesmo bucket S3 sem isolamento por prefix e bucket policy — um erro de `terraform destroy` em dev pode afetar o state de prod.
- Usar `AmazonSageMakerFullAccess` como policy da domain execution role — escopo excessivo que falha em revisões de segurança e viola least privilege.
- Habilitar todos os blueprints disponíveis por padrão no módulo — aumenta a superfície de ataque, cria recursos ociosos e dificulta a auditoria de permissões.
- Misturar o provider `aws` e o provider `awscc` para o mesmo recurso de domínio — causa conflitos de state e comportamento imprevisível durante drift detection.
- Não configurar timeout explícito no recurso de domínio — pipelines CI/CD com timeout padrão de 30 minutos falharão em domínios complexos, criando estado inconsistente.

> **Nota do Curador:** Na minha experiência com plataformas de dados em ambientes financeiros, o maior obstáculo para adotar IaC em ferramentas de ML não é técnico — é a percepção de que domínios SageMaker são 'infraestrutura de cientistas', fora do escopo do Platform Engineering. Esse lançamento é uma oportunidade para mudar essa narrativa: com o módulo Terraform oficial, o domínio SageMaker Unified Studio passa a ser um recurso de primeira classe no seu pipeline de infraestrutura, com os mesmos controles de governança que você aplica a um cluster EKS ou a uma instância RDS. O que eu faria imediatamente: integrar o job de drift detection ao mesmo dashboard de observabilidade da plataforma, não criar um dashboard separado — a visibilidade precisa estar onde os engenheiros já olham. A lição mais difícil que aprendi nesse tipo de migração: o risco real não está no Terraform, está no estado existente que você não documentou — invista tempo no inventário antes de qualquer import.

## Veredicto: Adote, com Disciplina de Migração

O suporte a Terraform no SageMaker Unified Studio é uma mudança genuinamente significativa para equipes de plataforma em ambientes regulados. A integração via Cloud Control Provider é pragmática — não é o provider `aws` nativo, mas é funcional e tem a vantagem de cobrir novos recursos antes do provider tradicional. O módulo open-source `terraform-aws-sagemaker-unified-studio` tem a estrutura certa: hierarquia de sub-módulos que mapeia para ownership organizacional, suporte a roles existentes para ambientes com IAM centralizado, e exemplos suficientes para começar sem partir do zero.

A recomendação é adotar, mas com disciplina de migração: (1) invista tempo no inventário e import antes de qualquer apply; (2) configure timeout explícito de 90min no domínio; (3) use `existing_iam_roles` em ambientes com SCPs restritivas; (4) implemente drift detection agendado desde o primeiro dia, não como afterthought; (5) trate blueprints como recursos de segurança — cada habilitação requer revisão formal. Para equipes que ainda não migraram, o custo de não fazer isso está crescendo: cada mês adicional de ClickOps é mais um mês de evidência de auditoria que precisará ser reconstruída manualmente.

## Referências

- [AWS What's New: Amazon SageMaker Unified Studio now supports Terraform for provisioning (Jul 2, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-sagemaker-unified-studio-terraform/)
- [terraform-aws-sagemaker-unified-studio — Open Source Module on GitHub (aws-ia)](https://github.com/aws-ia/terraform-aws-sagemaker-unified-studio)
- [Guidance for Developing a Data & AI Foundation with Amazon SageMaker — AWS Solutions](https://docs.aws.amazon.com/solutions/developing-a-data-and-ai-foundation-with-amazon-sagemaker/)
- [Quickly adopt new AWS features with the Terraform AWS Cloud Control Provider — AWS DevOps Blog](https://aws.amazon.com/blogs/devops/quickly-adopt-new-aws-features-with-the-terraform-aws-cloud-control-provider/)
- [Amazon SageMaker Domain in VPC only mode with Terraform — AWS ML Blog (Sep 2023)](https://aws.amazon.com/blogs/machine-learning/amazon-sagemaker-domain-in-vpc-only-mode-to-support-sagemaker-studio-with-auto-shutdown-lifecycle-configuration-and-sagemaker-canvas-with-terraform/)
- [AWS Config now supports 8 new resource types (Jun 2026)](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-config-new-resource-types)
- [Amazon SageMaker Unified Studio Administrator Guide](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/adminguide/)
- [AWS Control Tower AFT Provisioning Framework](https://docs.aws.amazon.com/controltower/latest/userguide/aft-provisioning-framework.html)