~ / posts / oci-kubernetes / terraform-oci-estado-y-acceso.md
2026-11-18 · 14 min de lectura

P2 - Terraform en OCI desde cero: cuenta, identidad y un state que no se rompe

Antes del primer nodo: Pay As You Go, home region, service limits, compartments, un usuario para Terraform con API key, el provider con dos regiones y el state en el backend nativo de OCI. Con cada diferencia contra AWS.

tiendisterraformocikubernetesawsdevops

También en dev.to, para comentar y seguir la serie ahí.

Serie «Kubernetes en OCI al menor costo» — parte 2. En la parte 0 vimos por qué OCI y cuánto cuesta, y en la parte 1 el mapa de la plataforma. Acá empieza la construcción.

Soy Matías Galiano, arquitecto de plataforma: llevo 18 años escribiendo software y 7 diseñando y operando sistemas distribuidos sobre Kubernetes, con Terraform y GitOps.

Antes del primer terraform apply que creara un cluster tuve que resolver cuatro cosas que en AWS casi no se ven: qué región es tu casa, cuánta capacidad te deja usar Oracle, con qué identidad corre Terraform y dónde vive el state. Algunas, en OCI, después no se pueden cambiar.

Todo lo que sigue sale del Terraform que hoy maneja el cluster de producción de Tiendis. Donde veas algo entre < y >, como <tenancy_ocid>, va el valor de tu cuenta.

1. La cuenta: Pay As You Go y la home region#

La cuenta nueva arranca en Free Trial, con límites que no alcanzan para un cluster con varios nodos. Lo primero es pasarla a Pay As You Go (sigue sin costo fijo: pagás lo que uses) y esperar a que figure activa.

Después viene la decisión que no se puede deshacer: la home region. Es la región que elegiste al registrarte, y en OCI es donde viven todos los recursos de identidad (usuarios, grupos, policies, dynamic groups) y los budgets. Para trabajar en otra región hay que suscribirse:

oci iam region-subscription list --tenancy-id <tenancy_ocid>
oci iam region-subscription create --tenancy-id <tenancy_ocid> --region-key SCL   # Santiago

En mi caso la home region quedó en São Paulo y el cluster vive en Santiago. Funciona perfecto, pero obliga a tener dos providers en Terraform (lo vemos en el punto 5).

Diferencia con AWS: IAM es global y casi todas las regiones vienen habilitadas. Nadie piensa en una "home region" porque no existe. En OCI es un dato de diseño desde el día uno.

2. Service limits: pedirlos antes que nada#

Es el gotcha clásico: una cuenta nueva puede tener límite 0 o muy bajo para las shapes Ampere A1. Se mira así:

oci limits value list --compartment-id <tenancy_ocid> --service-name compute \
  --query "data[?contains(name, 'a1')]" --region sa-santiago-1

Si no alcanza, se pide el aumento desde la consola (Governance → Limits, Quotas and Usage → Request a limit increase). A mí me convino pedirlo primero, porque puede tardar horas o un día, y mientras tanto fui armando todo lo demás.

Diferencia con AWS: existen las service quotas (por ejemplo, vCPUs de instancias On-Demand), pero en una cuenta normal rara vez frenan un cluster chico. En OCI, con ARM, es frecuente.

3. Compartments: dónde vive cada cosa#

Un compartment es un contenedor lógico de recursos dentro del tenancy (la cuenta). Se anidan como carpetas, y las policies y los budgets se aplican por compartment. Todo lo de la plataforma vive en uno solo, proyectos:

oci iam compartment create --compartment-id <tenancy_ocid> \
  --name proyectos --description "Plataforma Kubernetes y productos"

Diferencia con AWS: lo más parecido es una cuenta dentro de AWS Organizations (aislamiento de permisos y de costos), pero un compartment es mucho más liviano: no tiene facturación aparte, no necesita su propio usuario raíz y se crea en un segundo. Para un proyecto chico, un compartment por plataforma alcanza; separar dev y prd en compartments distintos es una mejora natural.

4. Un usuario para Terraform, con su API key#

Terraform no corre con tu usuario personal. Se crea un usuario terraform, un grupo terraform-admins y una policy para ese grupo:

oci iam group create --name terraform-admins --description "Terraform del tenancy"
oci iam policy create --compartment-id <tenancy_ocid> --name terraform-admins \
  --description "Bootstrap de la plataforma" \
  --statements '["Allow group terraform-admins to manage all-resources in tenancy"]'

El usuario y su alta en el grupo se hacen desde la consola (Identity & Security → Domains → Default domain → Users). La policy arranca amplia a propósito: el bootstrap crea dynamic groups, policies y usuarios a nivel tenancy. Cuando la plataforma está estable, se acota.

El lenguaje de policies de OCI se lee como una frase: Allow group <grupo> to <verbo> <recurso> in <compartment|tenancy>, con verbos inspect < read < use < manage, y se puede acotar con where. Es mucho más corto que un JSON de IAM y se lee de una.

La autenticación es con una API signing key, un par de llaves RSA. La privada queda en tu máquina; la pública se sube al usuario:

oci setup keys                       # genera ~/.oci/oci_api_key.pem y la pública
oci iam user api-key upload --user-id <user_ocid> --key-file ~/.oci/oci_api_key_public.pem

Y el perfil queda en ~/.oci/config, que leen tanto la CLI como Terraform:

[DEFAULT]
user=<user_ocid>
fingerprint=<aa:bb:cc:...>
tenancy=<tenancy_ocid>
region=sa-santiago-1
key_file=~/.oci/oci_api_key.pem

Diferencia con AWS: el equivalente es un access key id + secret de IAM, o mejor, un perfil de IAM Identity Center con credenciales temporales. En OCI la API key no vence: rotarla es tarea tuya. Y la llave privada nunca viaja: OCI firma cada request con ella.

5. El provider: una región para trabajar y otra para identidad#

Como la identidad vive en la home region, el provider se declara dos veces: el normal apuntando a Santiago y un alias home para todo lo de IAM y budgets.

terraform {
  required_version = ">= 1.12.0"   # lo pide el backend nativo de OCI (punto 6)
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "9.13.0"           # pin exacto, ver abajo
    }
  }
}

provider "oci" {
  region              = "sa-santiago-1"
  config_file_profile = "DEFAULT"
}

provider "oci" {
  alias               = "home"
  region              = "sa-saopaulo-1"   # home region: Identity y budgets
  config_file_profile = "DEFAULT"
}

resource "oci_identity_dynamic_group" "oke_nodes" {
  provider       = oci.home
  compartment_id = var.tenancy_ocid
  name           = "oke-nodes"
  description    = "Worker nodes del cluster"
  matching_rule  = "ALL {instance.compartment.id = '${var.compartment_ocid}'}"
}

Si te olvidás del provider = oci.home en un recurso de identidad, el apply falla con un error de región. Pasa una vez y no se olvida más.

Sobre el pin exacto: una versión del provider (9.12.0) salió sin binario para darwin_arm64, así que terraform init fallaba en una Mac con Apple Silicon. Desde entonces el provider va fijado a una versión exacta, y el .terraform.lock.hcl se commitea. Es lo que conviene con cualquier provider, pero en este caso me lo enseñó un init roto.

6. El state: backend nativo oci, no el S3-compatible#

OCI Object Storage tiene un endpoint compatible con S3, así que la tentación es usar el backend s3 de Terraform apuntando ahí. No funciona para escribir el state: el SDK de AWS manda Content-Encoding: aws-chunked en el PutObject y OCI responde 501 NotImplemented: AWS chunked encoding not supported. Lo probé con AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED, AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED y skip_s3_checksum = true: nada.

Lo que me funcionó fue el backend nativo oci, disponible desde Terraform 1.12:

terraform {
  backend "oci" {
    bucket              = "<proyecto>-terraform-state"
    namespace           = "<os_namespace>"   # oci os ns get
    key                 = "oci/terraform.tfstate"
    region              = "sa-santiago-1"
    auth                = "APIKey"
    config_file_profile = "DEFAULT"
  }
}

Tres ventajas frente al S3-compat:

Hay un huevo y la gallina: el bucket tiene que existir antes del primer init. Se crea a mano, con versionado (la documentación lo recomienda explícitamente, y es lo que te salva de un state pisado):

oci os ns get                                   # el namespace del tenancy
oci os bucket create --compartment-id <compartment_ocid> \
  --name <proyecto>-terraform-state --versioning Enabled --region sa-santiago-1
# si ya existía sin versionado:
oci os bucket update --bucket-name <proyecto>-terraform-state --versioning Enabled --region sa-santiago-1

Una vez creado el bucket, preferí que lo manejara el mismo Terraform. Dos detalles con los que me encontré:

resource "oci_objectstorage_bucket" "state" {
  compartment_id = var.compartment_ocid
  namespace      = var.os_namespace
  name           = "<proyecto>-terraform-state"
  access_type    = "NoPublicAccess"
  versioning     = "Enabled"
}

# El que aplica el lifecycle es el servicio de Object Storage de la región
resource "oci_identity_policy" "objectstorage_lifecycle_state" {
  provider       = oci.home
  compartment_id = var.compartment_ocid
  name           = "objectstorage-lifecycle-tfstate"
  description    = "Object Storage aplica el lifecycle del bucket del state"
  statements = [
    "Allow service objectstorage-sa-santiago-1 to manage object-family in compartment id ${var.compartment_ocid} where target.bucket.name = '<proyecto>-terraform-state'",
  ]
}

# Versiones anteriores del state: se borran a los 90 días (la vigente nunca se toca)
resource "oci_objectstorage_object_lifecycle_policy" "state" {
  namespace = var.os_namespace
  bucket    = oci_objectstorage_bucket.state.name
  rules {
    name        = "borrar-versiones-viejas"
    action      = "DELETE"
    target      = "previous-object-versions"
    is_enabled  = true
    time_amount = 90
    time_unit   = "DAYS"
  }
  depends_on = [oci_identity_policy.objectstorage_lifecycle_state]
}

Aun con el depends_on, el primer apply puede fallar por permisos: las policies se crean en la home region y tardan unos minutos en verse en la región de trabajo. Se espera y se vuelve a correr.

Si arrancaste con state local (es lo normal en el bootstrap), la migración es un comando. Antes, una copia por las dudas, y después una verificación de que no se perdió nada:

cp terraform.tfstate ~/tfstate-backup-$(date +%Y%m%d-%H%M%S).json
terraform init -migrate-state
terraform state list | wc -l      # mismo número de recursos que antes
terraform plan                    # tiene que dar el mismo plan que con el state local

Diferencia con AWS: allá el backend s3 es el estándar, y desde Terraform 1.10 tiene locking nativo con use_lockfile = true (antes hacía falta una tabla de DynamoDB). En OCI el camino equivalente es el backend oci, no el s3.

7. El state tiene secretos: tratalo como tal#

Los secretos de las aplicaciones (claves de cifrado, credenciales de MercadoPago, tokens) entran a OCI Vault desde Terraform, con valores en un terraform.tfvars que está en .gitignore. Eso deja los secretos fuera de git, pero no fuera del state: Terraform guarda los valores en claro en el .tfstate.

Por eso el bucket del state es NoPublicAccess, lo leen solo el usuario de Terraform y el dueño, y conviene cifrarlo con una llave propia de Vault (kms_key_id en el backend). Y nunca un terraform.tfstate en el repo: en el .gitignore van *.tfstate, *.tfstate.backup y *.tfvars (salvo el .example).

Diferencia con AWS: es el mismo problema, con la misma solución (S3 privado + KMS). Lo que cambia es que en AWS es común que los secretos ni pasen por Terraform (se cargan en Secrets Manager por otro lado). Cargarlos por Terraform es cómodo para reconstruir todo desde cero, a cambio de proteger el state como si fuera la caja fuerte.

8. Customer secret keys: las "access keys" de S3, pero para las apps#

Que Terraform no use el endpoint S3-compat no significa que nadie lo use. Mimir, Loki, Tempo y los backups de CloudNativePG hablan S3, y para eso OCI tiene las customer secret keys: un par access key / secret key asociado a un usuario.

La tentación es crear un usuario con acceso a todo el compartment y repartir esa llave. Es lo que tuve al principio, y con el tiempo lo cambié por dos motivos:

Lo que terminé haciendo es un usuario, un grupo y una llave por componente, cada uno con permiso solo sobre su bucket. Prefiero declararlos uno por uno, en un archivo por componente (s3-loki.tf, s3-mimir.tf…), en vez de un for_each: se leen de un vistazo, un plan muestra exactamente qué cambia y sacar uno es borrar un archivo, sin tocar las claves del mapa de los demás. Este es el de Loki:

# s3-loki.tf: Loki solo puede tocar su bucket
resource "oci_identity_user" "s3_loki" {
  provider       = oci.home
  compartment_id = var.tenancy_ocid
  name           = "s3-loki"
  description    = "S3-compat de Loki: solo el bucket loki"
  email          = "<mail>"
}

resource "oci_identity_group" "s3_loki" {
  provider       = oci.home
  compartment_id = var.tenancy_ocid
  name           = "s3-loki"
  description    = "Acceso al bucket loki"
}

resource "oci_identity_user_group_membership" "s3_loki" {
  provider = oci.home
  user_id  = oci_identity_user.s3_loki.id
  group_id = oci_identity_group.s3_loki.id
}

resource "oci_identity_policy" "s3_loki" {
  provider       = oci.home
  compartment_id = var.compartment_ocid
  name           = "s3-loki"
  description    = "Objetos del bucket loki, y nada más"
  statements = [
    "Allow group ${oci_identity_group.s3_loki.name} to manage objects in compartment id ${var.compartment_ocid} where target.bucket.name = 'loki'",
    "Allow group ${oci_identity_group.s3_loki.name} to read buckets in compartment id ${var.compartment_ocid} where target.bucket.name = 'loki'",
  ]
}

resource "oci_identity_customer_secret_key" "s3_loki" {
  provider     = oci.home
  user_id      = oci_identity_user.s3_loki.id
  display_name = "s3-loki"
}

Mimir, Tempo y los backups de CloudNativePG llevan su propio archivo, igual a este, cambiando el nombre y el bucket.

Cada llave va a su propio secreto en Vault, y External Secrets se la entrega solo al namespace del componente que la usa. El costo es cero: usuarios, grupos y policies no se cobran.

Si ya tenés la llave compartida en producción, el cambio se hace sin cortar nada: primero se crean las cuatro llaves nuevas, sin tocar la vieja; después se muda cada componente de a uno (Tempo, Loki, Mimir y, al final, los backups, que son lo más delicado), verificando que siga escribiendo antes de pasar al siguiente; y recién cuando nadie usa la llave vieja, se borra. Dos cosas que aprendí en el camino:

AWS_ACCESS_KEY_ID=<access_key_de_loki> AWS_SECRET_ACCESS_KEY=<secret_de_loki> \
  aws s3 ls s3://<proyecto>-terraform-state \
  --endpoint-url https://<os_namespace>.compat.objectstorage.sa-santiago-1.oraclecloud.com \
  --region sa-santiago-1
# An error occurred (AccessDenied) ...  ← es lo que querés ver

Por qué manage y no algo más chico. Mimir, Loki y Tempo compactan y aplican retención, y barman borra los backups viejos: los cuatro necesitan borrar objetos, y eso en OCI es manage. El límite que importa acá no es el verbo, es sobre qué bucket.

El endpoint es https://<os_namespace>.compat.objectstorage.<region>.oraclecloud.com. Y el mismo síntoma del punto 6 aparece en las apps que usan boto3, como barman (los backups de CloudNativePG): ahí sí lo resuelven AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED y AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED. Mismo error, distinta solución según el SDK.

Diferencia con AWS: en EKS esto se resuelve con IRSA o Pod Identity, sin llaves fijas. OKE Basic no tiene workload identity, así que las apps que hablan S3 usan llaves de verdad, guardadas en Vault y entregadas por External Secrets. Es la diferencia de seguridad más grande de la serie, y le voy a dedicar un post propio más adelante.

9. Un presupuesto con alertas, antes del primer nodo#

Lo último del bootstrap, y lo que más tranquilidad da: un budget sobre el compartment, con alertas por gasto real acumulado en montos fijos. Como los budgets viven en el tenancy, también van con el provider home:

resource "oci_budget_budget" "monthly" {
  provider       = oci.home
  compartment_id = var.tenancy_ocid
  target_type    = "COMPARTMENT"
  targets        = [var.compartment_ocid]
  amount         = 250
  reset_period   = "MONTHLY"
  display_name   = "presupuesto-mensual"
}

resource "oci_budget_alert_rule" "threshold" {
  provider       = oci.home
  for_each       = toset(["100", "200", "250"])
  budget_id      = oci_budget_budget.monthly.id
  display_name   = "alerta-${each.key}-usd"
  type           = "ACTUAL"
  threshold      = tonumber(each.key)
  threshold_type = "ABSOLUTE"
  recipients     = "<mail>"
}

Los umbrales van en dólares y no en porcentaje a propósito: el aviso temprano salta a mitad del gasto normal, y el último, cuando algo se fue de las manos (un autoscaler que no baja, un disco que quedó colgado).

Diferencia con AWS: es el equivalente directo de AWS Budgets. La diferencia práctica es que en OCI hay menos sorpresas de facturación (el NAT, el load balancer y el tráfico entre fault domains no se cobran), pero un nodo de más sí, y el budget es el que te avisa.

Resumen: lo mismo en AWS y en OCI#

Tema AWS OCI
Regiones Casi todas habilitadas; IAM global Home region fija; las demás se suscriben; IAM solo en la home
Capacidad Service quotas, rara vez frenan Service limits de A1, pedirlos primero
Aislamiento Cuentas en Organizations Compartments dentro del tenancy
Identidad de Terraform Access keys o Identity Center Usuario + API signing key RSA (no vence)
Policies Documentos JSON Frases Allow group … to <verbo> … in …
Provider Uno por región, IAM sin alias Dos: la región de trabajo y home
State Backend s3 + use_lockfile Backend nativo oci (el s3 no escribe)
Llaves para apps S3 IRSA / Pod Identity Customer secret keys en Vault
Presupuesto AWS Budgets Budgets por compartment, desde la home

Checklist antes de la parte 3#

Lo que viene#

En la parte 3 armamos la red: VCN, subnets pública y privada, Internet Gateway, NAT Gateway, Service Gateway y NSGs, y por qué en OCI la red de un cluster sale gratis cuando en AWS es una de las partes más caras de la factura.

Si te sirvió, el RSS es la mejor forma de enterarte del próximo post.