DEV Community: Juan Torchia

Certificate Policies, Path Validation and CRL: Three Layers RFC 5280 Doesn't Require You to Link

Juan Torchia — Fri, 18 Sep 2026 14:30:17 +0000

Two implementations that both claim "we comply with RFC 5280" can reach different conclusions about the same certification path, and neither one is violating the standard. This happens because the RFC defines three separate mechanisms — the certificate profile, the path validation algorithm, and CRL checking — and only one of them has a strict mandatory floor. The other two leave explicit room for MAY.

This piece separates those three layers using the RFC's own text, without assuming how any particular library or real-world verifier implements them.

Layer 1: Certificate Policies is data in the certificate, not a process

Section 4.2.1.4 of RFC 5280 defines the Certificate Policies extension within the X.509v3 certificate profile, in the same block as Policy Mappings (4.2.1.5) and Policy Constraints (4.2.1.11). It's information that travels inside the certificate: a set of OIDs declaring under which policy it was issued.

That extension, by itself, doesn't validate anything. It's data available for some other process to use or ignore. The document's own table of contents shows the structural separation:

4.2.1.4. Certificate Policies ......................32
4.2.1.5. Policy Mappings ...........................35
4.2.1.11. Policy Constraints .......................43
...
6.1. Basic Path Validation .....................72
6.3. CRL Validation .............................90

The certificate profile (Section 4) and path validation (Section 6) are different sections of the RFC. The fact that a certificate carries Certificate Policies doesn't imply the verifier will read them, let alone require them.

Layer 2: the path validation algorithm defines a minimum, not a maximum

Section 6.1 describes the basic certification path validation algorithm. The RFC is explicit about its scope:

"Thus, the path validation algorithm presented in Section 6.1 defines the minimum conditions for a path to be considered valid."

It's a floor. Any implementation can extend that floor, and the RFC says so using the same word it uses to mark anything optional: MAY.

"An implementation MAY augment the algorithm presented in Section 6.1 to further limit the set of valid certification paths that begin with a particular trust anchor."

The examples the text itself gives: applying a path length restriction to a specific trust anchor, requiring a particular form of alternative name in the target certificate, or imposing requirements on application-specific extensions. And there's one specific case that connects directly to layer 1: a trust anchor can be limited to trusting only paths associated with a particular certificate policy.

"...a trusted CA may only be trusted for a particular certificate policy. This restriction can be expressed through the inputs to the path validation procedure."

In other words: the Certificate Policies from layer 1 only matter if the algorithm from layer 2 receives them as input and decides to use them. An implementation can run the basic algorithm from Section 6.1, completely ignore those additional inputs, and still be RFC-compliant. The text is equally clear about self-signed trust anchors: they can carry a policy constraints extension stating that paths starting there should only be trusted for specific policies, but the basic algorithm "does not assume that this information is present" and "does not specify processing rules" for it. Whether to process it or ignore it is left to each implementation's discretion.

Layer 3: CRL checking is, literally, optional to implement as an algorithm

Section 6.3 describes how to determine whether a certificate is revoked when the revocation mechanism is a CRL. Here the RFC doesn't say MAY — it says something even stronger:

"Conforming implementations that support CRLs are not required to implement this algorithm, but they MUST be functionally equivalent to the external behavior resulting from this procedure when processing CRLs that are issued in conformance with this profile."

There's no need to implement the detailed step-by-step algorithm. It's enough to produce the same external result. This is a wide implementation freedom: two verifiers can reach the same revoked/not-revoked conclusion through completely different internal paths, and both are conformant.

There's also an operational detail the RFC flags that a basic implementation might overlook: when the CA signs certificates and CRLs with different private keys, verifying revocation requires building and validating a second, separate, full certification path for the certificate that signs the CRL.

"CRL checking in turn requires a separate certification path to be constructed and validated for the CA's CRL signature validation certificate."

The RFC even adjusts the level of obligation depending on the scenario:

"Applications that perform CRL checking MUST support certification path validation when certificates and CRLs are digitally signed with the same CA private key. These applications SHOULD support certification path validation when certificates and CRLs are digitally signed with different CA private keys."

With the same key, it's a MUST. With separate keys, it drops to SHOULD. An implementation that only covers the shared-key case isn't violating the RFC: it's covering the MUST and leaving out the SHOULD.

The three layers together

flowchart TD
  A[Certificado X.509v3] -->|contiene| B[Certificate Policies OIDs<br/>seccion 4.2.1.4]
  A --> C[Algoritmo de path validation<br/>seccion 6.1 - piso minimo]
  B -.->|input opcional MAY| C
  C --> D{Verificador soporta CRL?}
  D -->|si| E[CRL Validation<br/>seccion 6.3 - algoritmo no obligatorio]
  D -->|no| F[Ruta valida sin chequeo de revocacion]
  E --> G{Misma clave CA/CRL?}
  G -->|si, MUST| H[Path validation exigido]
  G -->|no, SHOULD| I[Path validation recomendado, no obligatorio]

The diagram shows where the leeway is: the dotted arrow between Certificate Policies and the Section 6.1 algorithm is an optional input, not an automatic link. A certificate can declare a policy, and that declaration might never end up influencing the validation result, because it depends on whether the verifier requests it as input.

Why this matters for interoperability

Two verifiers can both accept exactly the same certification path as valid, even though one of them ignores the certificate's Certificate Policies and skips revocation checking entirely, while the other applies additional policy restrictions and full CRL checking with path validation for the CRL signing key. Neither one violates RFC 5280: the first covered the minimum from Section 6.1; the second covered additional MAYs that the RFC permits but doesn't require.

This is an editorial reading, not a textual finding from the RFC itself: the document doesn't address legal interoperability or legally valid digital signatures. But the normative structure — a narrow mandatory floor, wide optional extensions — explains why "RFC 5280 compliant" is a necessary condition, not a sufficient one, for two verification systems to reach the same verdict on a signature.

Limits of this reading

The excerpt of RFC 5280 available for this piece is truncated and doesn't cover the full detail of the initialization steps in Section 6.1, nor the step-by-step policy mapping algorithm. There's also no data here about what browsers, TLS libraries, or actual electronic signature engines do in practice: the RFC describes the standard, not the behavior of real software, and there's no evidence in this document about how many implementations do or don't activate each optional layer.

The text also doesn't mention OCSP or other modern revocation mechanisms — everything said here about "the algorithm not being mandatory" applies specifically to CRL, Section 6.3, and can't be extended without additional evidence to other revocation protocols.

Original source: https://www.rfc-editor.org/rfc/rfc5280

This article was originally published on juanchi.dev

Certificate Policies, path validation y CRL: tres capas que RFC 5280 no obliga a unir

Juan Torchia — Fri, 18 Sep 2026 14:30:12 +0000

Dos implementaciones que dicen "cumplimos RFC 5280" pueden llegar a resultados distintos frente a la misma ruta de certificación, y ninguna de las dos está incumpliendo el estándar. Esto pasa porque el RFC define tres mecanismos separados —perfil del certificado, algoritmo de validación de ruta y verificación de CRL— y solo uno de ellos tiene piso obligatorio estricto. Los otros dos dejan margen explícito de MAY.

Esta nota separa esas tres capas usando el texto del RFC, sin asumir cómo las implementa cada librería o verificador real.

Capa 1: Certificate Policies es un dato en el certificado, no un proceso

La sección 4.2.1.4 de RFC 5280 define la extensión Certificate Policies dentro del perfil del certificado X.509v3, en el mismo bloque donde están Policy Mappings (4.2.1.5) y Policy Constraints (4.2.1.11). Es información que viaja en el certificado: un conjunto de OIDs que declaran bajo qué política se emitió.

Esa extensión, por sí sola, no valida nada. Es un dato disponible para que otro proceso lo use o lo ignore. El propio índice del documento muestra la separación estructural:

4.2.1.4. Certificate Policies ......................32
4.2.1.5. Policy Mappings ...........................35
4.2.1.11. Policy Constraints .......................43
...
6.1. Basic Path Validation .....................72
6.3. CRL Validation .............................90

El perfil de certificado (sección 4) y la validación de ruta (sección 6) son secciones distintas del RFC. Que un certificado tenga Certificate Policies no implica que el verificador vaya a leerlas ni a exigirlas.

Capa 2: el algoritmo de path validation define un mínimo, no un máximo

La sección 6.1 describe el algoritmo básico de validación de ruta de certificación. El RFC es explícito sobre su alcance:

"Thus, the path validation algorithm presented in Section 6.1 defines the minimum conditions for a path to be considered valid."

Es un piso. Cualquier implementación puede ampliar ese piso, y el RFC lo dice con la misma palabra que usa para marcar lo opcional: MAY.

"An implementation MAY augment the algorithm presented in Section 6.1 to further limit the set of valid certification paths that begin with a particular trust anchor."

Los ejemplos que da el propio texto: aplicar una restricción de longitud de ruta a un trust anchor específico, exigir una forma particular de nombre alternativo en el certificado destino, o imponer requisitos sobre extensiones específicas de la aplicación. Y hay un caso puntual que conecta directo con la capa 1: un trust anchor puede limitarse a confiar en rutas asociadas a una política de certificado particular.

"...a trusted CA may only be trusted for a particular certificate policy. This restriction can be expressed through the inputs to the path validation procedure."

Es decir: las Certificate Policies de la capa 1 solo importan si el algoritmo de la capa 2 las recibe como input y decide usarlas. Una implementación puede correr el algoritmo básico de la sección 6.1, ignorar por completo esos inputs adicionales, y seguir siendo conforme al RFC. El texto es igual de claro sobre trust anchors autofirmados: pueden llevar una extensión de policy constraints indicando que las rutas que arrancan ahí solo deben confiarse para políticas específicas, pero el algoritmo básico "no asume que esa información esté presente" y "no especifica reglas de procesamiento" para ella. Procesarla o ignorarla queda a discreción de cada implementación.

Capa 3: CRL checking es, literalmente, opcional de implementar como algoritmo

La sección 6.3 describe cómo determinar si un certificado está revocado cuando el mecanismo de revocación es una CRL. Acá el RFC no dice MAY, dice algo más fuerte todavía:

"Conforming implementations that support CRLs are not required to implement this algorithm, but they MUST be functionally equivalent to the external behavior resulting from this procedure when processing CRLs that are issued in conformance with this profile."

No hace falta implementar el algoritmo detallado paso a paso. Alcanza con producir el mismo resultado externo. Esto es una libertad de implementación amplia: dos verificadores pueden llegar a la misma conclusión de revocado/no-revocado por caminos internos completamente distintos, y ambos son conformes.

Hay además un detalle operativo que el RFC marca y que una implementación básica puede pasar por alto: cuando la CA firma certificados y CRLs con claves privadas distintas, verificar la revocación exige construir y validar una segunda ruta de certificación completa, separada, para el certificado que firma la CRL.

"CRL checking in turn requires a separate certification path to be constructed and validated for the CA's CRL signature validation certificate."

El RFC incluso ajusta el nivel de obligatoriedad según el escenario:

"Applications that perform CRL checking MUST support certification path validation when certificates and CRLs are digitally signed with the same CA private key. These applications SHOULD support certification path validation when certificates and CRLs are digitally signed with different CA private keys."

Con la misma clave, es MUST. Con claves separadas, baja a SHOULD. Una implementación que solo cubre el caso de clave compartida no está violando el RFC: está cubriendo el MUST y dejando afuera el SHOULD.

Las tres capas en conjunto

flowchart TD
  A[Certificado X.509v3] -->|contiene| B[Certificate Policies OIDs<br/>seccion 4.2.1.4]
  A --> C[Algoritmo de path validation<br/>seccion 6.1 - piso minimo]
  B -.->|input opcional MAY| C
  C --> D{Verificador soporta CRL?}
  D -->|si| E[CRL Validation<br/>seccion 6.3 - algoritmo no obligatorio]
  D -->|no| F[Ruta valida sin chequeo de revocacion]
  E --> G{Misma clave CA/CRL?}
  G -->|si, MUST| H[Path validation exigido]
  G -->|no, SHOULD| I[Path validation recomendado, no obligatorio]

El diagrama muestra dónde está el margen: la flecha punteada entre Certificate Policies y el algoritmo de la sección 6.1 es un input opcional, no un enlace automático. Un certificado puede declarar una política y esa declaración nunca llegar a influir en el resultado de la validación, porque depende de que el verificador la pida como input.

Por qué esto importa para interoperabilidad

Dos verificadores pueden aceptar como válida exactamente la misma ruta de certificación, aunque uno de ellos ignore las Certificate Policies del certificado y no chequee revocación, mientras el otro aplique restricciones de política adicionales y CRL checking completo con path validation para la clave de firma de CRL. Ninguno de los dos incumple RFC 5280: el primero cubrió el mínimo de la sección 6.1; el segundo, MAY adicionales que el RFC permite pero no exige.

Esto es una lectura editorial, no un hallazgo textual del RFC: el documento no habla de interoperabilidad legal ni de firma digital con validez jurídica. Pero la estructura normativa —piso obligatorio angosto, extensiones opcionales anchas— explica por qué "conforme a RFC 5280" es una condición necesaria y no suficiente para que dos sistemas de verificación lleguen al mismo veredicto sobre una firma.

Límites de esta lectura

El fragmento de RFC 5280 disponible para esta nota está truncado y no cubre el detalle completo de los pasos de inicialización de la sección 6.1 ni el algoritmo de policy mapping paso a paso. Tampoco hay acá datos sobre qué hacen en la práctica navegadores, librerías TLS o motores de firma electrónica concretos: el RFC describe el estándar, no el comportamiento de software real, y no hay evidencia en este documento sobre cuántas implementaciones activan o no cada capa opcional.

El texto tampoco menciona OCSP ni otros mecanismos de revocación modernos — todo lo dicho sobre "no obligatoriedad del algoritmo" aplica específicamente a CRL, sección 6.3, y no se puede extender sin evidencia adicional a otros protocolos de revocación.

Fuente original: https://www.rfc-editor.org/rfc/rfc5280

Este artículo fue publicado originalmente en juanchi.dev

Ollama v0.34.2 vs v0.34.1: a targeted MLX fix, not the same regression

Juan Torchia — Fri, 18 Sep 2026 12:00:19 +0000

Ollama published two releases back to back: v0.34.1 on September 14 and v0.34.2 on September 15. Both changelogs touch MLX and both mention memory. That invites reading them as an emergency fix for the same issue. The official text doesn't say that.

What changed in each version

v0.34.1 (September 14), per its official changelog:

ollama create with MLX safetensors is no longer experimental. Creating GGUF models now requires llama.cpp tools for conversion and quantization.
General improvement to MLX memory handling on Apple Silicon ("Improved MLX memory handling on Apple Silicon").
Token repetition detection now requires 100 repeated tokens before triggering, to reduce false positives in cases like OCR.
/api/tags reports a measured improvement on large model libraries: from 3.1 seconds down to 294 ms cold, according to the tests included in the changelog itself.
Deprecation of typical_p: it can't be set on new models, but existing GGUF models keep it.

v0.34.2 (September 15), one day later:

First-run setup when running ollama, with the option to sign in or continue locally. That state is shared with the desktop app on macOS and Windows.
ollama://apps link to open the Apps page of the desktop app directly on macOS and Windows.
Specific fix: "Fixed excessive memory growth during long generations with MLX speculative decoding".
llama.cpp update (no version detail given in the changelog).

Why these aren't the same fix

The friction point is the shared wording: "memory" and "MLX" show up in both entries. But the text of each changelog describes different mechanisms.

v0.34.1 talks about "Improved MLX memory handling" in general terms, without specifying under what condition the problem occurred or which part of the pipeline it touched.

v0.34.2 points to a precise case: memory growth during long generations when using MLX speculative decoding. That's a specific inference mechanism, not the general memory handling the previous version mentioned.

Neither changelog says one fixes what the other broke. There's no text linking the two entries as the same regression, and there's no confirmation either that they're fully independent. The documents simply don't clarify it.

flowchart TD
  A[v0.34.1 - Sep 14] --> B[Improved MLX memory handling, general]
  A --> C[MLX safetensors no longer experimental]
  D[v0.34.2 - Sep 15] --> E[Fix: memory in MLX speculative decoding, long generations]
  D --> F[First-run setup + ollama apps]
  B -.- G{No explicit textual link}
  E -.- G

Who the v0.34.2 fix matters to

The memory fix in v0.34.2 is scoped to one scenario: MLX speculative decoding on long generations. That runs on Apple Silicon with the MLX backend.

If the use case is GGUF models on llama.cpp, that fix doesn't apply according to what the changelog says: the described problem is specific to MLX speculative decoding, not the GGUF backend.

What can't be concluded from this evidence

There's no confirmation of whether the memory growth fixed in v0.34.2 was introduced by the v0.34.1 changes or already existed before that.
The internal mechanism isn't explained: the changelog says it was "fixed," not why memory grew during speculative decoding.
There's no detail on which llama.cpp version was bumped in v0.34.2 or what that bump brings.
The /api/tags numbers (3.1 s → 294 ms) come from the project's own changelog, with no described test methodology.

Who needs to update today

Based on the available information: those running MLX models on Apple Silicon with long generations and using speculative decoding have a concrete, documented fix in v0.34.2. For the rest of the changes — stable safetensors, the repetition threshold, typical_p deprecation, the /api/tags improvement — those were already in v0.34.1, and updating to v0.34.2 includes them by inheritance, not because v0.34.2 repeats or fixes them.

Original source:

This article was originally published on juanchi.dev

Ollama v0.34.2 vs v0.34.1: un fix puntual de MLX, no la misma regresión

Juan Torchia — Fri, 18 Sep 2026 12:00:15 +0000

Ollama publicó dos releases seguidos: v0.34.1 el 14 de septiembre y v0.34.2 el 15 de septiembre. Los dos changelogs tocan MLX y los dos mencionan memoria. Eso invita a leerlos como una corrección de emergencia sobre lo mismo. Los textos oficiales no dicen eso.

Qué cambió en cada versión

v0.34.1 (14 de septiembre), según su changelog oficial:

ollama create con MLX safetensors deja de ser experimental. La creación de modelos GGUF pasa a requerir herramientas de llama.cpp para la conversión y cuantización.
Mejora general de manejo de memoria MLX en Apple Silicon ("Improved MLX memory handling on Apple Silicon").
La detección de repetición de tokens ahora exige 100 tokens repetidos antes de activarse, para reducir falsos positivos en casos como OCR.
/api/tags reporta una mejora medida en librerías grandes de modelos: de 3.1 segundos a 294 ms en frío, según las pruebas incluidas en el propio changelog.
Deprecación de typical_p: no se puede setear en modelos nuevos, pero los modelos GGUF existentes lo conservan.

v0.34.2 (15 de septiembre), un día después:

Setup de primer uso al correr ollama, con opción de iniciar sesión o seguir localmente. Ese estado se comparte con la app de escritorio en macOS y Windows.
Enlace ollama://apps para abrir directamente la página de Apps de la app de escritorio en macOS y Windows.
Fix específico: "Fixed excessive memory growth during long generations with MLX speculative decoding".
Actualización de llama.cpp (sin detalle de versión en el changelog).

Por qué no son el mismo fix

El punto de fricción está en la palabra compartida: "memoria" y "MLX" aparecen en las dos entradas. Pero el texto de cada changelog describe mecanismos distintos.

v0.34.1 habla de "Improved MLX memory handling" en términos generales, sin especificar bajo qué condición ocurría el problema ni qué parte del pipeline tocaba.

v0.34.2 apunta a un caso preciso: crecimiento de memoria durante generaciones largas cuando se usa decodificación especulativa MLX (MLX speculative decoding). Es un mecanismo de inferencia específico, no el manejo de memoria general que mencionó la versión anterior.

Ningún changelog dice que uno corrija lo que dejó roto el otro. No hay texto que vincule las dos entradas como la misma regresión, y tampoco hay confirmación de que sean completamente independientes. Los documentos simplemente no lo aclaran.

flowchart TD
  A[v0.34.1 - 14 sep] --> B[Manejo de memoria MLX mejorado, general]
  A --> C[MLX safetensors ya no experimental]
  D[v0.34.2 - 15 sep] --> E[Fix: memoria en MLX speculative decoding, generaciones largas]
  D --> F[First-run setup + ollama apps]
  B -.- G{Sin vínculo textual explícito}
  E -.- G

A quién le importa el fix de v0.34.2

El fix de memoria de v0.34.2 está acotado a un escenario: decodificación especulativa MLX en generaciones largas. Eso corre en Apple Silicon con el backend MLX.

Si el uso es con modelos GGUF sobre llama.cpp, ese fix no aplica según lo que dice el changelog: el problema descripto es específico de MLX speculative decoding, no del backend GGUF.

Qué no se puede concluir con esta evidencia

No hay confirmación de si el crecimiento de memoria que corrige v0.34.2 fue introducido por los cambios de v0.34.1 o si ya existía antes.
No se explica el mecanismo interno: el changelog dice que se "fixed", no por qué crecía la memoria en decodificación especulativa.
No hay detalle de qué versión de llama.cpp se actualizó en v0.34.2 ni qué trae ese bump.
Los números de /api/tags (3.1 s → 294 ms) vienen del propio changelog del proyecto, sin metodología de prueba descripta.

Quién necesita actualizar hoy

Con la información disponible: quienes corren modelos MLX en Apple Silicon con generaciones largas y usan decodificación especulativa tienen un fix concreto y documentado en v0.34.2. Para el resto de los cambios —safetensors estables, umbral de repetición, deprecación de typical_p, mejora de /api/tags— ya estaban en v0.34.1, y actualizar a v0.34.2 los incluye por arrastre, no porque v0.34.2 los repita o los corrija.

Fuente original:

Este artículo fue publicado originalmente en juanchi.dev

CUDA Rust: two native tracks, not a wrapper over C++

Juan Torchia — Thu, 17 Sep 2026 12:00:19 +0000

Nvidia published an announcement with an ambitious name on its developer blog on September 8, 2026: CUDA Rust. The question I'm interested in isn't whether Rust on GPU sounds good — it does, it always does — but what's actually underneath the announcement. Is it a native frontend that compiles to PTX, as the text claims, or does it end up being a layer over the usual CUDA C++ toolchain? And what about wgpu, rust-gpu and rust-cuda, which were already solving part of this problem?

Hypothesis, scope and status

The hypothesis of this post is specific: "native" in Nvidia's blog means the kernel compiles from Rust down to PTX without going through CUDA C++ as an intermediary, but that doesn't imply the two announced projects replace the existing Rust-GPU ecosystem, nor that they're production-ready.

Status of this note: it's a reading of the primary source, not my own bench test. I didn't run the examples. What follows separates what the blog claims from what still needs verifying with code.

What the primary source says

According to Nvidia's official blog, published September 8, 2026, there are two distinct projects, not one:

cuda-oxide (SIMT track). It's a custom codegen backend for rustc. It intercepts compilation, routes functions marked with #[kernel] through Rust MIR, the Pliron community IR framework, and from there to LLVM IR down to PTX. The rest of the program is handled by the standard Rust backend. It requires Linux, a GPU with compute capability 8.0+, CUDA toolkit 12.x or higher, clang with libclang headers, and a pinned nightly toolchain (nightly-2026-04-03 in the blog's example).

cutile-rs (Tile track). This one works a level higher: instead of programming per thread, you program per tile. The #[cutile::module] macro embeds the kernel's AST in the host binary and JIT-compiles it via CUDA Tile IR when the kernel is first needed. It runs on stable Rust 1.89+, with CUDA 13.3, no nightly and no custom LLVM. It's already published on crates.io, and the blog mentions it's used outside Nvidia in HuggingFace's Grout inference engine and in mistral.rs.

The sentence that answers the first part of the reader's question is right there in the text: "GPU kernels can be written in Rust, compiled natively to PTX, rather than a wrapper around code from somewhere else." That's a claim from the source, not a measurement of mine. Given that, the stated mechanism is native compilation to PTX via MIR/Pliron/LLVM (for cuda-oxide) or via CUDA Tile IR (for cutile-rs), not a bindings layer over already-compiled CUDA C++ binaries.

What the blog doesn't settle about replacement vs. complement

Here's the real limit of the evidence. The blog is explicit that it does not present itself as a replacement:

"Rust on GPUs is not new. There is good work in this space that predates ours and continues alongside it. [...] we have been working with the rust-cuda maintainers as both projects mature."

And it also names the goal of cross-language coexistence:

"NVIDIA plans to support inter-language interoperability between CUDA Rust, CUDA C++, and CUDA Python so the choice of frontend does not lock developers out of other ecosystems."

Two things remain unresolved with this single source:

How mature the actual interoperability is. The blog says "plans to support," future tense. There's no code example showing that interop working today. Treating it as available would be inflating the claim.
Technical relationship with wgpu. The text compares cuda-oxide and cutile-rs against Rust-GPU, rust-cuda and CubeCL (via an appendix in the cuda-oxide book that I didn't read), but doesn't mention wgpu in the available fragment. wgpu targets multi-backend portability (Vulkan, Metal, DX12, WebGPU); CUDA Rust targets Nvidia's stack purely. These are different goals, so "replaces" probably doesn't apply there — but this is my own inference from what I know about wgpu, not something the source explicitly confirms.

Environment and commands to verify the hypothesis (protocol, not execution)

This is a verification plan, not a result. I didn't run these commands.

For cuda-oxide (SIMT track), the blog documents:

# Requires Linux, GPU compute capability 8.0+, CUDA toolkit 12.x+,
# clang with libclang, pinned nightly toolchain
cargo +nightly-2026-04-03 install --git https://github.com/NVlabs/cuda-oxide.git cargo-oxide

cargo oxide new vecadd_demo
cd vecadd_demo
cargo oxide doctor
cargo oxide run

The example program does vector addition (1024 floats) and verifies the result with PASSED: all 1024 elements correct. The technical detail that marks the difference from a wrapper: the DisjointSlice<f32> type replaces &mut [f32] for the output buffer, because Rust's borrow checker doesn't allow thousands of threads to share the same &mut. DisjointSlice splits that single borrow into exclusive per-thread fragments, checked at compile time. That's the kind of guarantee a thin wrapper over CUDA C++ couldn't provide, because the Rust compiler needs to see the type to reason about aliasing.

For cutile-rs (Tile track), the blog documents:

# Requires GPU compute capability 8.0+, CUDA 13.3, stable Rust 1.89+, Linux
# No nightly, no custom LLVM
cargo new vecadd_demo
cd vecadd_demo
cargo add cutile

With the hello_world example from the cutile-rs repo running via cargo run -p cutile-examples --example hello_world.

Criterion for accepting or rejecting the hypothesis: if someone runs both examples and confirms that the final binary doesn't depend on nvcc or a CUDA C++ compiler anywhere in the kernel's compilation path, the "native, not wrapper" hypothesis is empirically supported. If a hidden C++ dependency shows up in the build chain, the hypothesis falls.

Limits of this note

I didn't run cargo oxide run or the cutile-rs example. Everything I describe about compiler behavior comes from the blog text, not from a run of my own.
The fragment of the source I have is truncated at several points (marked [fragment] in the original), so there may be nuances about cross-language interoperability or about the comparison appendix with Rust-GPU/CubeCL that I didn't get to read in full.
Both projects explicitly declare themselves unfit for production: cuda-oxide is in early alpha, cutile-rs is "further along" but with incomplete coverage and APIs that will still move, according to the blog's own words.
There's no performance benchmark in the source or in this note. Any speed comparison between these tracks and traditional CUDA C++ would need a separate experiment, with fixed hardware and versions.

Where this stands

With the evidence I have, I don't take it for granted that "native compilation to PTX" equals "ready to replace CUDA C++ in a real system." The blog is careful not to promise that — it talks about early-stage projects, with heavy requirements (pinned nightly, system LLVM) on the track that most resembles traditional CUDA C++. If I had to decide today whether to adopt this in an inference system, I wouldn't do it without first running the two official examples and comparing the build pipeline against what rust-cuda or CubeCL already offer — both of which have been in the ecosystem longer and don't depend on a freshly published compiler backend preview.

Original source

Nvidia Developer Blog — Introducing CUDA Rust: Two Tracks for Writing GPU Kernels: https://developer.nvidia.com/blog/introducing-cuda-rust-two-tracks-for-writing-gpu-kernels

This article was originally published on juanchi.dev

CUDA Rust: dos tracks nativos, no un wrapper sobre C++

Juan Torchia — Thu, 17 Sep 2026 12:00:14 +0000

Nvidia publicó el 8 de septiembre de 2026 en su blog de desarrolladores un anuncio con nombre ambicioso: CUDA Rust. La pregunta que me interesa no es si Rust en GPU suena bien —suena bien, siempre suena bien— sino qué hay debajo del anuncio. ¿Es un frontend nativo que compila a PTX, como dice el texto, o termina siendo una capa sobre el toolchain de CUDA C++ de siempre? ¿Y qué pasa con wgpu, rust-gpu y rust-cuda, que ya venían resolviendo parte de este problema?

Hipótesis, alcance y estado

La hipótesis de este post es específica: "nativo" en el blog de Nvidia significa que el kernel se compila desde Rust hasta PTX sin pasar por CUDA C++ como intermediario, pero eso no implica que los dos proyectos anunciados reemplacen el ecosistema Rust-GPU existente ni que estén listos para producción.

Estado de esta nota: es una lectura de la fuente primaria, no una prueba de banco propia. No corrí los ejemplos. Lo que sigue separa lo que el blog afirma de lo que falta verificar con código.

Qué dice la fuente primaria

Según el blog oficial de Nvidia, publicado el 8 de septiembre de 2026, hay dos proyectos distintos, no uno:

cuda-oxide (track SIMT). Es un codegen backend custom para rustc. Intercepta la compilación, enruta las funciones marcadas con #[kernel] a través de Rust MIR, el framework de IR de la comunidad Pliron, y de ahí a LLVM IR hasta PTX. El resto del programa lo maneja el backend estándar de Rust. Requiere Linux, GPU con compute capability 8.0+, CUDA toolkit 12.x o superior, clang con headers de libclang, y un toolchain nightly pinned (nightly-2026-04-03 en el ejemplo del blog).

cutile-rs (track Tile). Trabaja un nivel más arriba: en vez de programar por thread, programás por tile. El macro #[cutile::module] embebe el AST del kernel en el binario del host y lo compila JIT vía CUDA Tile IR cuando el kernel se necesita por primera vez. Corre en Rust estable 1.89+, con CUDA 13.3, sin nightly y sin LLVM propio. Ya está publicado en crates.io y el blog menciona que se usa fuera de Nvidia en el motor de inferencia Grout de HuggingFace y en mistral.rs.

La frase que responde la primera parte de la pregunta del lector está en el propio texto: "GPU kernels can be written in Rust, compiled natively to PTX, rather than a wrapper around code from somewhere else." Es una afirmación de la fuente, no una medición mía. Con eso, el mecanismo declarado es compilación nativa a PTX vía MIR/Pliron/LLVM (para cuda-oxide) o vía CUDA Tile IR (para cutile-rs), no una capa de bindings sobre binarios de CUDA C++ ya compilados.

Lo que el blog no resuelve sobre reemplazo vs. complemento

Acá está el límite real de la evidencia. El blog es explícito en que no se presenta como reemplazo:

"Rust on GPUs is not new. There is good work in this space that predates ours and continues alongside it. [...] we have been working with the rust-cuda maintainers as both projects mature."

Y también nombra el objetivo de convivencia entre lenguajes:

"NVIDIA plans to support inter-language interoperability between CUDA Rust, CUDA C++, and CUDA Python so the choice of frontend does not lock developers out of other ecosystems."

Dos cosas quedan sin resolver con esta única fuente:

Estado de madurez real de la interoperabilidad. El blog dice "plans to support", tiempo futuro. No hay ejemplo de código mostrando esa interop funcionando hoy. Tratarlo como disponible sería inflar el claim.
Relación técnica con wgpu. El texto compara cuda-oxide y cutile-rs contra Rust-GPU, rust-cuda y CubeCL (via un apéndice del libro de cuda-oxide que no leí), pero no menciona wgpu en el fragmento disponible. wgpu apunta a portabilidad multi-backend (Vulkan, Metal, DX12, WebGPU); CUDA Rust apunta puramente al stack de Nvidia. Son objetivos distintos, así que "reemplaza" probablemente no aplica ahí — pero esto es una inferencia mía a partir de lo que sé de wgpu, no algo que la fuente confirme explícitamente.

Entorno y comandos para verificar la hipótesis (protocolo, no ejecución)

Esto es un plan de verificación, no un resultado. No corrí estos comandos.

Para cuda-oxide (track SIMT), el blog documenta:

# Requiere Linux, GPU compute capability 8.0+, CUDA toolkit 12.x+,
# clang con libclang, toolchain nightly pinned
cargo +nightly-2026-04-03 install --git https://github.com/NVlabs/cuda-oxide.git cargo-oxide

cargo oxide new vecadd_demo
cd vecadd_demo
cargo oxide doctor
cargo oxide run

El programa de ejemplo hace suma de vectores (1024 floats) y verifica el resultado con PASSED: all 1024 elements correct. El detalle técnico que marca la diferencia frente a un wrapper: el tipo DisjointSlice<f32> reemplaza &mut [f32] para el buffer de salida, porque el borrow checker de Rust no permite que miles de threads compartan el mismo &mut. DisjointSlice divide ese borrow único en fragmentos exclusivos por thread, verificados en compile time. Esa es la clase de garantía que un wrapper delgado sobre CUDA C++ no podría dar, porque el compilador de Rust necesita ver el tipo para razonar sobre aliasing.

Para cutile-rs (track Tile), el blog documenta:

# Requiere GPU compute capability 8.0+, CUDA 13.3, Rust estable 1.89+, Linux
# Sin nightly, sin LLVM propio
cargo new vecadd_demo
cd vecadd_demo
cargo add cutile

Con el ejemplo hello_world del repo cutile-rs corriendo vía cargo run -p cutile-examples --example hello_world.

Criterio para aceptar o descartar la hipótesis: si alguien corre ambos ejemplos y confirma que el binario final no depende de nvcc ni de un compilador de CUDA C++ en el camino de compilación del kernel, la hipótesis de "nativo, no wrapper" queda soportada empíricamente. Si aparece una dependencia oculta de C++ en la cadena de build, la hipótesis cae.

Límites de esta nota

No ejecuté cargo oxide run ni el ejemplo de cutile-rs. Todo lo que describo sobre comportamiento del compilador viene del texto del blog, no de una corrida propia.
El fragmento de la fuente que tengo está truncado en varios puntos (marcado [fragment] en el original), así que puede haber matices sobre la interoperabilidad entre lenguajes o sobre el apéndice de comparación con Rust-GPU/CubeCL que no llegué a leer completos.
Ambos proyectos se declaran explícitamente no aptos para producción: cuda-oxide está en alpha temprana, cutile-rs "está más avanzado" pero con cobertura incompleta y APIs que van a moverse, según palabras del propio blog.
No hay benchmark de performance en la fuente ni en esta nota. Cualquier comparación de velocidad entre estos tracks y CUDA C++ tradicional necesitaría un experimento aparte, con hardware y versiones fijadas.

Postura

Con la evidencia que tengo, no doy por sentado que "compilación nativa a PTX" equivalga a "listo para reemplazar CUDA C++ en un sistema real". El blog es cuidadoso en no prometer eso — habla de proyectos tempranos, con requisitos pesados (nightly pinned, LLVM del sistema) en el track que más se parece al CUDA C++ tradicional. Si tuviera que decidir hoy si adoptar esto en un sistema de inferencia, no lo haría sin antes correr los dos ejemplos oficiales y comparar el pipeline de build contra lo que ya usa rust-cuda o CubeCL, que llevan más tiempo en el ecosistema y no dependen de una preview de compiler backend recién publicada.

Fuente original

Nvidia Developer Blog — Introducing CUDA Rust: Two Tracks for Writing GPU Kernels: https://developer.nvidia.com/blog/introducing-cuda-rust-two-tracks-for-writing-gpu-kernels

Este artículo fue publicado originalmente en juanchi.dev

XGBoost Doesn't Beat scikit-learn, It Solves a Different Problem

Juan Torchia — Wed, 16 Sep 2026 12:00:19 +0000

You open a notebook, train a scikit-learn RandomForestClassifier on a small tabular dataset, and the result is decent. Someone on the team says "try XGBoost, it'll do better." You swap two lines, run it again, and the number ticks up a bit. The question almost nobody asks at that point is why it improved — and whether that improvement justifies the cost of having six new hyperparameters to tune instead of two.

My take is this: XGBoost isn't "better" than scikit-learn in general. It's the right tool when you need to squeeze performance out of tabular data using boosting, at the cost of a bigger configuration surface. If you're not in that specific scenario, you're paying complexity for nothing.

What XGBoost Is (and Isn't)

XGBoost stands for Extreme Gradient Boosting. It's an implementation of gradient boosting on decision trees, optimized for speed and for squeezing out every bit of signal the dataset has to give. The official documentation describes it as a gradient boosting library optimized to be "efficient, flexible and portable" — not a new algorithm, but a particular implementation of an idea that already existed.

The underlying idea, gradient boosting, is simple to explain even though it's not simple to implement well:

Train a weak model (typically a small tree).
Measure the error that model makes.
Train a second model focused on correcting that error.
Repeat, stacking models, each one fixing what the previous one got wrong.

A scikit-learn RandomForestClassifier does something different: it trains many trees in parallel, each on a different sample of the data, and averages their votes. There's no sequential error correction — there's voting. That design difference is exactly what explains why, on certain tabular datasets, boosting pulls ahead: each new tree is literally trained to patch the hole the previous one left, instead of just contributing another independent point of view.

What the XGBoost docs don't say is that this will always happen. They document the algorithm, the parameters, the API. They don't document "what percentage of datasets it wins on" — that depends on the dataset, and any generic figure floating around about that has no citable source.

The Reproducible Example: Same Dataset, Two Libraries

To see the difference without inventing a use case, use the toy dataset load_breast_cancer that ships with scikit-learn — 569 rows, 30 numeric features, binary classification. It's small on purpose: the point isn't to prove who "wins," it's to show the workflow and where the new hyperparameters show up.

# comparacion_basica.py
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from xgboost import XGBClassifier

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

rf = RandomForestClassifier(random_state=42)
rf.fit(X_train, y_train)

xgb = XGBClassifier(eval_metric="logloss", random_state=42)
xgb.fit(X_train, y_train)

print("RandomForest score:", rf.score(X_test, y_test))
print("XGBoost score:", xgb.score(X_test, y_test))

Run this in a Jupyter notebook and you'll get two accuracy numbers on the same split. I'm not going to invent here what number you'll get — it depends on library versions, the seed, the hardware. What you can claim from this experiment is something else: both models ran on the same dataset, with the same split, and one of the two has a smaller API surface to tune. RandomForestClassifier has n_estimators, max_depth, min_samples_split as its core knobs. XGBClassifier adds learning_rate, subsample, colsample_bytree, gamma, reg_alpha, reg_lambda — and each one interacts with the others.

That's the real cost of XGBoost. It's not that training is slower (for small datasets, you won't even notice) or harder to install. It's that the hyperparameter space is bigger, and a badly done search in that space can give you a worse result than a RandomForest with defaults.

flowchart LR
  A[Tabular dataset] --> B{Do I need to squeeze every point of performance?}
  B -->|No, I want a quick baseline| C[scikit-learn RandomForest]
  B -->|Yes, and I have time to tune| D[XGBoost]
  D --> E{Did you tune learning_rate, subsample, reg_lambda?}
  E -->|No| F[Result probably worse than baseline]
  E -->|Yes, with cross-validation| G[Result potentially better]

Where People Screw Up: The Copy-Pasted Recipe

The common recipe going around is: "use XGBoost because it wins Kaggle competitions." It's true that XGBoost played a starring role in a lot of tabular data competitions — that's documented history. The problem is the logical leap that follows: it doesn't follow from that that it'll win on your dataset, with your features, at your row count.

The hidden cost of copying that recipe without thinking is twofold:

Silent overfitting. XGBoost with lots of estimators and no regularization (reg_alpha, reg_lambda at zero) memorizes the training dataset more easily than a RandomForest, because each new tree fits itself specifically to the residual error — including the noise.
Tuning time nobody budgeted for. If you're going to use XGBoost seriously, you need a hyperparameter search (grid search, random search, or something like Optuna) with cross-validation. That's compute time and human time that a RandomForest with reasonable defaults doesn't ask of you.

The simplest counterexample: a tabular dataset with few rows (say, a few hundred) and high-dimensional noise. There, a RandomForest with its implicit bagging regularization can behave more stably than a badly-tuned XGBoost, which is going to learn to explain the noise instead of the signal. I don't have a public benchmark to cite for this specific case — it's an expected behavior pattern based on how each algorithm works, not a measurement I ran.

Decision Matrix: When to Look at XGBoost First

Situation	What to check first	Why
Tabular data, need a quick baseline	scikit-learn (RandomForest or GradientBoosting)	Fewer hyperparameters, decent result with no tuning
Competition or problem where every performance point counts	XGBoost, with a time budget for tuning	This is where sequential boosting pays off, if paired with cross-validation
Dataset with lots of unencoded categorical columns	Check native categorical support in the XGBoost version you're using	The official docs detail support per version — don't assume "it just works" without checking
Tight team time for tuning, short deadline	scikit-learn first	A badly-tuned XGBoost can perform worse than a RandomForest with defaults
Need to explain the model to a non-technical person	Either one, but check interpretability tools (feature importance, SHAP) before choosing on performance alone	Interpretability doesn't depend on the library, it depends on what you instrument on top

This table isn't a closed conclusion about which algorithm "wins." It's a starting point for deciding what to try first based on your actual constraint: time, data volume, need to explain the model.

The Limits of This (and Why I Won't Close With a Number)

Watch out for the claim I almost wrote before pulling it back: "XGBoost wins in most tabular data cases." That sentence has no citable source I can point to here, and it's exactly the kind of evidence-free claim that got flagged in an earlier post about scikit-learn. I'm not going to repeat it in different words.

What I can say at the level of certainty the evidence allows:

The official XGBoost documentation explains the algorithm, the parameters, and feature support. It doesn't document performance comparisons against scikit-learn on general datasets — you have to run that yourself, with your data.
The snippet experiment above is reproducible: anyone running it will get two comparable numbers, but those numbers will vary by library version and seed. It's not a fixed measurement you can cite as "XGBoost scored X% better."
Without a cross-validation experiment with hyperparameter search on your specific dataset, any accuracy comparison between the two models is anecdotal.

If you need a reproducible, measurable decision, the concrete next step is to run GridSearchCV or RandomizedSearchCV on both models, with the same cross-validation scheme, and compare the distribution of scores — not a single number from a single split.

FAQ

Does XGBoost work for non-tabular data, like images or text?
Not its strength. For images and text, neural network architectures (CNNs, transformers) tend to dominate the state of the art. XGBoost shines on data structured in rows and columns.

Do I need a GPU to use XGBoost?
No. XGBoost runs fine on CPU for small and medium datasets. It has GPU support to speed up training on large datasets, documented on the official page, but it's not a requirement.

Are XGBoost and LightGBM the same thing?
Both implement gradient boosting on trees, but with different design decisions (for example, how they split trees). If you're evaluating which one to use, the same criteria from this matrix apply: it depends on the dataset and how much time you have to tune each one.

Can I use XGBoost directly with the scikit-learn API?
Yes. XGBClassifier and XGBRegressor implement scikit-learn's fit/predict interface, so they plug into Pipeline, GridSearchCV and the rest of the ecosystem without friction.

Which hyperparameter has the most impact in XGBoost?
According to the docs, learning_rate and n_estimators interact directly: a low learning_rate needs more estimators to converge. max_depth controls how much each individual tree can memorize. There's no single "magic" parameter — the interaction between them is the whole point.

Does XGBoost replace the need for feature engineering?
No. It's still a tree-based model: it benefits from well-built features just like scikit-learn does. No boosting algorithm fixes a poorly-prepared data problem.

Final Take

If you're starting a tabular classification or regression problem and you don't have evidence that you need to squeeze every point of performance, start with scikit-learn. It's less surface area to break, fewer hyperparameters to explain in a code review, and a reliable baseline in minutes. Move to XGBoost when you have the tuning time budgeted and a concrete reason — a competition, a product requirement that justifies the effort — not because "that's what the Kaggle winners use."

The question you need to ask yourself before switching libraries isn't "which one is better?" It's "do I have the time to tune six hyperparameters instead of two, and will that time pay off with the improvement I actually need?" If the answer is no, stick with the RandomForest and keep iterating somewhere else in the pipeline — probably the features, not the algorithm.

If this got you thinking about how you structure the rest of your data stack, it might be worth checking out how Docker Compose handles healthcheck and depends_on when training runs in a separate container from the service that serves the model, or how to sanitize sensitive values in Actuator if your ML pipeline exposes metrics over HTTP.

Original source:

XGBoost Documentation — https://xgboost.readthedocs.io/en/stable/

This article was originally published on juanchi.dev

XGBoost no le gana a scikit-learn, resuelve otro problema

Juan Torchia — Wed, 16 Sep 2026 12:00:14 +0000

Abrís un notebook, entrenás un RandomForestClassifier de scikit-learn sobre un dataset tabular chico, y el resultado es razonable. Alguien en el equipo te dice "probá con XGBoost, te va a andar mejor". Cambiás dos líneas, corrés de nuevo, y el número mejora un poco. La pregunta que casi nadie se hace en ese momento es por qué mejoró — y si esa mejora justifica el costo de tener seis hiperparámetros nuevos que tunear en lugar de dos.

Mi tesis es esta: XGBoost no es "mejor" que scikit-learn en general. Es la herramienta correcta cuando necesitás exprimir performance en datos tabulares con boosting, al costo de más superficie de configuración. Si no estás en ese escenario específico, estás pagando complejidad por nada.

Qué es XGBoost (y qué no es)

XGBoost significa Extreme Gradient Boosting. Es una implementación de gradient boosting sobre árboles de decisión, optimizada para velocidad y para exprimir cada punto de señal que el dataset tiene para dar. La documentación oficial lo describe como una librería de boosting de gradiente optimizada para ser "eficiente, flexible y portable" — no como un algoritmo nuevo, sino como una implementación particular de una idea que ya existía.

La idea de fondo, gradient boosting, es simple de explicar aunque no sea simple de implementar bien:

Entrenás un modelo débil (típicamente un árbol chico).
Medís el error que ese modelo comete.
Entrenás un segundo modelo que se enfoca en corregir ese error.
Repetís, sumando modelos, cada uno corrigiendo lo que el anterior se equivocó.

Un RandomForestClassifier de scikit-learn hace algo distinto: entrena muchos árboles en paralelo, cada uno sobre una muestra distinta de los datos, y promedia sus votos. No hay corrección secuencial de errores — hay votación. Esa diferencia de diseño es la que explica por qué, en ciertos datasets tabulares, boosting saca ventaja: cada árbol nuevo está literalmente entrenado para tapar el agujero que dejó el anterior, en lugar de simplemente aportar otro punto de vista independiente.

Lo que la documentación de XGBoost no dice es que esto vaya a pasar siempre. Documenta el algoritmo, los parámetros y la API. No documenta "en qué porcentaje de datasets gana" — eso depende del dataset, y cualquier cifra genérica que circule sobre eso no tiene fuente citable.

El ejemplo reproducible: mismo dataset, dos librerías

Para ver la diferencia sin inventar un caso de uso, usá el dataset de juguete load_breast_cancer que trae scikit-learn — 569 filas, 30 features numéricas, clasificación binaria. Es chico a propósito: no busca demostrar quién "gana", busca mostrar el flujo de trabajo y dónde aparecen los hiperparámetros nuevos.

# comparacion_basica.py
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from xgboost import XGBClassifier

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

rf = RandomForestClassifier(random_state=42)
rf.fit(X_train, y_train)

xgb = XGBClassifier(eval_metric="logloss", random_state=42)
xgb.fit(X_train, y_train)

print("RandomForest score:", rf.score(X_test, y_test))
print("XGBoost score:", xgb.score(X_test, y_test))

Corré esto en un notebook de Jupyter y vas a tener dos números de accuracy sobre el mismo split. No voy a inventar acá qué número te va a salir a vos — depende de la versión de las librerías, del seed, del hardware. Lo que sí podés afirmar con este experimento es algo distinto: ambos modelos corrieron sobre el mismo dataset, con el mismo split, y uno de los dos tiene una API más chica para tunear. RandomForestClassifier tiene n_estimators, max_depth, min_samples_split como parámetros centrales. XGBClassifier suma learning_rate, subsample, colsample_bytree, gamma, reg_alpha, reg_lambda — y cada uno interactúa con los demás.

Eso es el costo real de XGBoost. No es que sea más lento entrenar (para datasets chicos, no lo vas a notar) ni que sea más difícil de instalar. Es que el espacio de hiperparámetros es más grande, y una búsqueda mal hecha en ese espacio te puede dar un resultado peor que el RandomForest con defaults.

flowchart LR
  A[Dataset tabular] --> B{¿Necesito exprimir cada punto de performance?}
  B -->|No, quiero un baseline rápido| C[RandomForest de scikit-learn]
  B -->|Sí, y tengo tiempo para tunear| D[XGBoost]
  D --> E{¿Tuneaste learning_rate, subsample, reg_lambda?}
  E -->|No| F[Resultado probablemente peor que el baseline]
  E -->|Sí, con validación cruzada| G[Resultado potencialmente mejor]

Dónde se equivoca la gente: la receta copiada sin criterio

La receta común que circula es: "usá XGBoost porque gana las competencias de Kaggle". Es cierto que XGBoost tuvo un rol protagónico en muchas competencias de datos tabulares — eso es historia documentada. El problema es el salto lógico siguiente: de ahí no se sigue que gane en tu dataset, con tus features, en tu volumen de filas.

El costo oculto de copiar esa receta sin pensarlo es doble:

Overfitting silencioso. XGBoost con muchos estimadores y sin regularización (reg_alpha, reg_lambda en cero) memoriza el dataset de entrenamiento más fácil que un RandomForest, porque cada árbol nuevo se ajusta específicamente al error residual — incluido el ruido.
Tiempo de tuneo que nadie presupuestó. Si vas a usar XGBoost en serio, necesitás una búsqueda de hiperparámetros (grid search, random search, o algo tipo Optuna) con validación cruzada. Eso es tiempo de cómputo y tiempo de persona que un RandomForest con defaults razonables no te pide.

El contraejemplo más simple: un dataset tabular con pocas filas (digamos, unos pocos cientos) y alta dimensionalidad de ruido. Ahí un RandomForest con su regularización implícita por bagging puede comportarse de forma más estable que un XGBoost mal tuneado, que va a aprender a explicar el ruido en lugar de la señal. No tengo un benchmark público para citar ese caso puntual — es un patrón de comportamiento esperado según cómo funciona cada algoritmo, no una medición que hice.

Matriz de decisión: cuándo mirar XGBoost primero

Situación	Qué mirar primero	Por qué
Datos tabulares, necesitás un baseline rápido	scikit-learn (RandomForest o GradientBoosting)	Menos hiperparámetros, resultado razonable sin tuneo
Competencia o problema donde cada punto de performance cuenta	XGBoost, con presupuesto de tiempo para tunear	Ahí es donde el boosting secuencial rinde, si lo acompañás con validación cruzada
Dataset con muchas columnas categóricas sin encodear	Revisar soporte nativo de categóricas en la versión de XGBoost que uses	La documentación oficial detalla el soporte por versión — no asumas que "simplemente funciona" sin chequear
Poco tiempo de equipo para tuneo, plazo corto	scikit-learn primero	Un XGBoost mal tuneado puede rendir peor que un RandomForest con defaults
Necesitás explicar el modelo a alguien no técnico	Cualquiera de los dos, pero revisá herramientas de interpretabilidad (feature importance, SHAP) antes de elegir por performance sola	La interpretabilidad no depende de la librería, depende de qué instrumentés encima

Esta tabla no es una conclusión cerrada sobre cuál algoritmo "gana". Es un punto de partida para decidir qué probar primero según la restricción real que tengas: tiempo, volumen de datos, necesidad de explicar el modelo.

Los límites de esto (y por qué no cierro con un número)

Ojo con la afirmación que casi escribí antes de sacarla: "XGBoost gana en la mayoría de los casos de datos tabulares". Esa frase no tiene una fuente citable que yo pueda poner acá, y es exactamente el tipo de claim sin evidencia que terminó bloqueado en un post anterior sobre scikit-learn. No la voy a repetir con otras palabras.

Lo que sí puedo decir con el nivel de certeza que la evidencia permite:

La documentación oficial de XGBoost explica el algoritmo, los parámetros y el soporte de features. No documenta comparativas de performance contra scikit-learn en datasets generales — eso lo tenés que correr vos, con los datos.
El experimento del snippet de arriba es reproducible: cualquiera que lo corra va a tener dos números comparables, pero esos números van a variar según versión de librería y seed. No es una medición fija que puedas citar como "XGBoost dio X% mejor".
Sin un experimento de validación cruzada con búsqueda de hiperparámetros sobre el dataset específico que tengas, cualquier comparación de accuracy entre ambos modelos es anecdótica.

Si necesitás una decisión reproducible y medible, el próximo paso concreto es correr GridSearchCV o RandomizedSearchCV sobre ambos modelos, con el mismo esquema de validación cruzada, y comparar la distribución de scores — no un solo número de un solo split.

FAQ

¿XGBoost sirve para datos que no son tabulares, como imágenes o texto?
No es su fuerte. Para imágenes y texto, arquitecturas de redes neuronales (CNNs, transformers) suelen dominar el estado del arte. XGBoost brilla en datos estructurados en filas y columnas.

¿Necesito GPU para usar XGBoost?
No. XGBoost corre en CPU sin problema para datasets chicos y medianos. Tiene soporte de GPU para acelerar entrenamiento en datasets grandes, documentado en la página oficial, pero no es un requisito.

¿XGBoost y LightGBM son lo mismo?
Ambos implementan gradient boosting sobre árboles, pero con decisiones de diseño distintas (por ejemplo, cómo hacen el split de los árboles). Si estás evaluando cuál usar, valen los mismos criterios de esta matriz: depende del dataset y del tiempo que tengas para tunear cada uno.

¿Puedo usar XGBoost directamente con la API de scikit-learn?
Sí. XGBClassifier y XGBRegressor implementan la interfaz fit/predict de scikit-learn, así que se integran con Pipeline, GridSearchCV y el resto del ecosistema sin fricción.

¿Cuál es el hiperparámetro que más impacto tiene en XGBoost?
Según la documentación, learning_rate y n_estimators interactúan directamente: un learning_rate bajo necesita más estimadores para converger. max_depth controla cuánto puede memorizar cada árbol individual. No hay un único parámetro "mágico" — la interacción entre ellos es el punto.

¿XGBoost reemplaza la necesidad de feature engineering?
No. Sigue siendo un modelo sobre árboles: se beneficia de features bien construidas igual que scikit-learn. Ningún algoritmo de boosting resuelve un problema de datos mal preparados.

Postura final

Si estás arrancando un problema de clasificación o regresión tabular y no tenés evidencia de que necesitás exprimir cada punto de performance, arrancá con scikit-learn. Es menos superficie para romper, menos hiperparámetros para explicar en un code review, y un baseline confiable en minutos. Movete a XGBoost cuando tengas el tiempo de tuneo presupuestado y una razón concreta — una competencia, un requisito de producto que justifique el esfuerzo — no porque "es lo que usan los que ganan Kaggle".

La pregunta que te tenés que hacer antes de cambiar de librería no es "¿cuál es mejor?". Es "¿tengo el tiempo para tunear seis hiperparámetros en lugar de dos, y ese tiempo me lo van a pagar con la mejora que necesito?". Si la respuesta es no, quedate con el RandomForest y seguí iterando en otra parte del pipeline — probablemente en las features, no en el algoritmo.

Si esto te hizo pensar en cómo estructurás el resto del stack de datos, capaz te sirve repasar cómo Docker Compose maneja el healthcheck y el depends_on cuando el entrenamiento corre en un contenedor separado del servicio que sirve el modelo, o cómo sanitizar valores sensibles en Actuator si el pipeline de ML expone métricas por HTTP.

Fuente original:

XGBoost Documentation — https://xgboost.readthedocs.io/en/stable/

Este artículo fue publicado originalmente en juanchi.dev

The /actuator/env Sanitizer Doesn't Know Your Naming Conventions

Juan Torchia — Fri, 11 Sep 2026 12:00:20 +0000

I recently wrote about allowlisting actuator endpoints: what to expose and what not to. One question stayed open and kept nagging at me: if you decide to leave /actuator/env enabled — because you need it for debugging in staging, because infra is asking for it — what actually guarantees you won't show a secret in plain text the first time someone hits it with curl?

Short answer: nothing, if you blindly trust the default sanitizer.

The problem with actuator env show values

Spring Boot ships with a sanitizer that automatically masks certain values before showing them in /actuator/env. It works by property name: if the key contains password, secret, key, token or credentials, the value comes out as ******. It's a reasonable defense for the generic case.

The problem is exactly that: it's generic. It covers the words some Spring developer imagined you'd use. It doesn't cover the ones your team actually uses.

Think about how environment variables get named in a real project: DB_PASS instead of DB_PASSWORD, API_AUTH instead of API_TOKEN, WEBHOOK_SIGNING, PARTNER_SHARED_VALUE, INTERNAL_CIPHER. None of those contain the keywords the sanitizer looks for. All of them end up in the /actuator/env JSON response without a single asterisk.

My tesis here: the default sanitizer covers the obvious names, but that's not where the real leaks happen. The real leaks happen through the naming convention someone improvised in a sprint under deadline pressure, and nobody circled back to add it to the pattern list. I've seen this exact gap in code review — a variable named PARTNER_SHARED_VALUE sitting in a staging config, fully visible, because nobody thought a shared-secret-style value needed the word "secret" in it to deserve masking.

What the official source says — and what it doesn't

The official Spring Boot Actuator documentation confirms the behavior: the /env endpoint applies sanitization to values before exposing them, and that behavior is configurable through the SanitizingFunction interface, which replaced the keyword-based Sanitizer mechanism in more recent versions of the framework.

What the docs don't say — because it's not their job to say it — is what specific names you're going to use in your project. That's on you to audit. The docs give you the extension mechanism; the catalog of what to sanitize is the responsibility of whoever configures the project, not the framework.

That gap between "mechanism available" and "correct configuration for this case" is exactly where most exposure incidents on default, unreviewed configurations slip through.

Where people get it wrong

The common recipe I see repeated on forums and in inherited configs is: "turn on management.endpoint.env.show-values=when-authorized and you're covered." That solves who can see the values, not what values show up unmasked to whoever has authorization. They're two different problems, and they get treated as one all the time.

The hidden cost shows up when the endpoint stays accessible to an internal role — a monitoring service, an ops dashboard — and that role ends up seeing credentials nobody thought to mask because the variable name didn't match the default pattern.

Typical counterexample: a project that uses Vault or AWS Secrets Manager for production, but leaves variables named something like THIRD_PARTY_SHARED_SECRET_VALUE in application-staging.yml. The default sanitizer doesn't reliably catch SHARED_SECRET_VALUE as a unit if the matching logic is stricter than a plain substring check for "secret" — and in a lot of custom configs it ends up not covering variants with underscores or mixed case if someone overwrote the sanitizer without reviewing the inherited regex.

Here's how to extend the sanitizer with your own pattern, using SanitizingFunction:

// Custom sanitizer configuration for /actuator/env
@Bean
public SanitizingFunction customSanitizingFunction() {
    // Pattern covering the team's own naming conventions
    Pattern patronCustom = Pattern.compile(
        "(?i).*(pass|auth|signing|shared|cipher).*"
    );
    return data -> {
        String nombre = data.getSanitizableData().getKey();
        if (patronCustom.matcher(nombre).matches()) {
            return data.withValue("******");
        }
        // if it doesn't match, let the default sanitizer keep the chain going
        return data;
    };
}

This bean gets added to the existing chain of sanitizers; it doesn't replace it. Spring Boot runs every registered SanitizingFunction in order and applies masking if any of them decides it's warranted.

flowchart LR
  A[Request a /actuator/env] --> B{Sanitizer default}
  B -->|nombre matchea password/secret/token| C[Enmascarado con ******]
  B -->|no matchea| D{SanitizingFunction custom}
  D -->|nombre matchea patron propio| C
  D -->|no matchea nada| E[Valor expuesto en texto plano]

That last path, the one on the right, is the one you have to actively close. It doesn't close itself.

Decision matrix for /actuator/env

Situation	What to check first	What to do
Endpoint exposed only on localhost/debug	Confirm there's no tunneling or proxy exposing it outward	Default sanitizer may be enough, but audit variable names anyway
Endpoint accessible in staging with monitoring roles	What custom variables the team uses, not just Spring's	Add a `SanitizingFunction` with your own pattern before enabling access
Variables with unconventional names (`DB_PASS`, `API_AUTH`)	List every key in `application.yml` and `.env` for each environment	Extend the regex pattern, don't trust the default list
Integrations with external providers (webhooks, partners)	Names the partner defines, not the ones you define	Custom sanitizer by provider prefix or suffix
Deciding whether to disable the whole endpoint	Whether anyone on the team regularly audits property names	Disabling it is safer than an unmaintained sanitizer

That last row is the one I most want to point out: if nobody's periodically reviewing which property names show up in the code, a poorly maintained custom sanitizer gives a false sense of security — arguably worse than no sanitizer at all, because it looks like coverage. The allowlist criterion I laid out in the previous post is preferable to a sanitizer nobody updates.

Common mistakes and gotchas

Confusing authorization with sanitization. show-values=when-authorized controls access, not content. They're independent settings that both need reviewing.
Copying the regex from a previous project without adapting it. Naming conventions change between teams and even between projects within the same team.
Not testing the sanitizer against a negative case. Common gap: nobody writes a test that verifies a "weird"-named variable actually comes out masked.
Thinking this is only a production problem. Staging and shared dev environments also expose /actuator/env, and that's often exactly where real third-party credentials live for integration testing.
Assuming a Spring Boot version bump updates your pattern list for you. It doesn't. The framework maintains its own default keywords; your team's naming conventions are always your own responsibility, version after version.

FAQ

Does Spring Boot's sanitizer mask all sensitive values by default?
No. It masks values whose property name contains specific words like password, secret, key, token or credentials. Any naming convention different from that stays uncovered unless explicitly configured.

What's the difference between Sanitizer and SanitizingFunction?
SanitizingFunction is the recommended interface in recent Spring Boot versions for extending sanitization behavior programmatically, replacing the earlier approach based solely on a fixed keyword list.

Can I have multiple SanitizingFunction instances registered at once?
Yes. Spring Boot runs them in a chain; if any of them decides to mask a value, that value stays masked in the final response.

Is disabling /actuator/env safer than sanitizing it?
Depends on the use case. If the team has no process to keep the custom sanitizer updated, disabling the endpoint or restricting it with a strict allowlist reduces risk with less ongoing maintenance.

Does show-values=when-authorized solve the exposed-secrets problem?
Not by itself. It controls who can see the values, not what values show up unmasked to those authorized users. They're two separate settings that need to be combined.

How do I test that my custom sanitizer works before deploying?
With a unit test that invokes the SanitizingFunction bean directly against real property names from the project, including cases with underscores, mixed case, and external provider prefixes.

Where I land

Spring Boot's default sanitizer isn't a placebo: it covers the generic case reasonably well, per what the official reference itself documents. What I can't claim without production evidence is exactly how much it reduces risk in any specific project — that depends entirely on how far that project's naming conventions drift from the default list.

What I can say with technical confidence: if nobody's audited the project's custom property names against the sanitizer's pattern list, there's an unclosed gap sitting there. That's not a remote possibility, it's a direct consequence of how the mechanism works — a name-matching filter only catches the names it was told to look for.

My practical recommendation follows the same logic I used to think through endpoint allowlisting in the previous post about actuator: treat sanitization as a living list that gets reviewed every time a new integration gets added, not as a configuration you set once and forget. Today's regex won't cover the variable name someone's going to invent next sprint. The uncomfortable question worth asking your team right now: when was the last time anyone actually opened application.yml and checked every key against the sanitizer, instead of assuming Spring already handled it?

If you're into how I think about architecture decisions with this same "what does the tool cover versus what do I have to cover" lens, I've got related posts on JWT vs stateful sessions and on what the path to Java Champion actually means that touch the same tension from other angles.

Original source:

Spring Boot Actuator Docs: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html

This article was originally published on juanchi.dev

El sanitizer de /actuator/env no conoce tus convenciones

Juan Torchia — Fri, 11 Sep 2026 12:00:15 +0000

Hace poco escribí sobre allowlist en actuator endpoints: qué exponer y qué no. Quedó una pregunta abierta que me siguió picando: si decidís dejar /actuator/env habilitado —porque lo necesitás para debug en staging, porque el equipo de infra lo pide— ¿qué te asegura que no vas a mostrar un secreto en texto plano la primera vez que alguien le pegue un curl?

La respuesta corta es: nada, si confiás ciegamente en el sanitizer default.

El problema con actuator env show values

Spring Boot trae un sanitizer que enmascara automáticamente ciertos valores antes de mostrarlos en /actuator/env. Funciona por nombre de propiedad: si la clave contiene password, secret, key, token o credentials, el valor sale como ******. Es una defensa razonable para el caso genérico.

El problema es justamente eso: es genérica. Cubre las palabras que un desarrollador de Spring imaginó que ibas a usar. No cubre las que tu equipo realmente usa.

Pensá en cómo se nombran las variables de entorno en un proyecto real: DB_PASS en vez de DB_PASSWORD, API_AUTH en vez de API_TOKEN, WEBHOOK_SIGNING, PARTNER_SHARED_VALUE, INTERNAL_CIPHER. Ninguna de esas contiene las palabras clave que el sanitizer busca. Todas terminan en la respuesta JSON de /actuator/env sin ningún asterisco.

Mi tesis es esta: el sanitizer default no falla porque esté mal escrito, falla porque asume que todo el mundo nombra igual. Y en la práctica cada equipo tiene su propio dialecto de variables de entorno. Las fugas reales casi nunca pasan por password mal escrito — pasan por la convención custom que alguien inventó en un sprint y que nadie agregó a la lista de patrones.

Qué dice la fuente oficial y qué no dice

La documentación oficial de Spring Boot Actuator confirma el comportamiento: el endpoint /env aplica sanitización sobre los valores antes de exponerlos, y ese comportamiento es configurable mediante la interfaz SanitizingFunction, que reemplazó al mecanismo de Sanitizer basado en keywords en versiones más recientes del framework.

Lo que la doc no dice —porque no es su trabajo decirlo— es qué nombres específicos vas a usar en tu proyecto. Eso lo tenés que auditar vos. La doc te da el mecanismo de extensión; el catálogo de qué sanitizar es responsabilidad de quien configura el proyecto, no del framework.

Esa diferencia entre "mecanismo disponible" y "configuración correcta para este caso puntual" es exactamente donde se cuelan la mayoría de los incidentes de exposición que se reportan en configuraciones default sin revisión.

Dónde se equivoca la gente

La receta común que veo repetida en foros y en configuraciones heredadas es: "activá management.endpoint.env.show-values=when-authorized y ya estás cubierto". Eso resuelve quién puede ver los valores, no qué valores se muestran sin máscara a quien tiene autorización. Son dos problemas distintos y se los trata como uno solo todo el tiempo.

El costo oculto aparece cuando el endpoint queda accesible para un rol interno —un servicio de monitoreo, un dashboard de operaciones— y ese rol termina viendo credenciales que nadie pensó en enmascarar porque el nombre de la variable no calzaba con el patrón default.

Caso tipico que uso para explicar esto: un proyecto que usa Vault o AWS Secrets Manager para producción, pero en application-staging.yml deja variables con nombres tipo THIRD_PARTY_SHARED_SECRET_VALUE. El sanitizer default no necesariamente matchea SHARED_SECRET_VALUE como unidad reconocible si el patrón de búsqueda es más rígido que una simple substring de "secret" — y en configuraciones custom heredadas, es común que las variantes con guiones bajos o mayúsculas mixtas queden afuera si alguien sobreescribió el regex sin revisarlo a fondo.

Acá va la forma de extender el sanitizer con un patrón propio, usando SanitizingFunction:

// Configuracion custom del sanitizer para /actuator/env
@Bean
public SanitizingFunction customSanitizingFunction() {
    // Patron que cubre convenciones propias del equipo
    Pattern patronCustom = Pattern.compile(
        "(?i).*(pass|auth|signing|shared|cipher).*"
    );
    return data -> {
        String nombre = data.getSanitizableData().getKey();
        if (patronCustom.matcher(nombre).matches()) {
            return data.withValue("******");
        }
        // si no matchea, dejamos que el sanitizer default siga la cadena
        return data;
    };
}

Este bean se agrega a la cadena existente de sanitizers; no la reemplaza. Spring Boot ejecuta todos los SanitizingFunction registrados en orden y aplica el enmascarado si alguno de ellos decide que corresponde.

flowchart LR
  A[Request a /actuator/env] --> B{Sanitizer default}
  B -->|nombre matchea password/secret/token| C[Enmascarado con ******]
  B -->|no matchea| D{SanitizingFunction custom}
  D -->|nombre matchea patron propio| C
  D -->|no matchea nada| E[Valor expuesto en texto plano]

Ese último camino, el de la derecha, es el que hay que cerrar activamente. No se cierra solo.

Matriz de decisión para /actuator/env

Situación	Qué mirar primero	Qué hacer
Endpoint expuesto solo en localhost/debug	Confirmar que no hay tunneling ni proxy hacia afuera	Sanitizer default puede alcanzar, pero auditá nombres de variables igual
Endpoint accesible en staging con roles de monitoreo	Qué variables custom usa tu equipo, no solo las de Spring	Agregar `SanitizingFunction` con el patrón propio antes de habilitar acceso
Variables con nombres no convencionales (`DB_PASS`, `API_AUTH`)	Listar todas las claves de `application.yml` y `.env` de cada ambiente	Extender el patrón regex, no confiar en la lista default
Integraciones con proveedores externos (webhooks, partners)	Nombres que el partner define, no los que definís vos	Sanitizer custom por prefijo o sufijo del proveedor
Necesitás decidir si deshabilitar el endpoint entero	Si nadie en el equipo audita nombres de propiedades regularmente	Deshabilitarlo es más seguro que un sanitizer sin mantenimiento

La última fila es la que más me interesa señalar: si no hay alguien revisando periódicamente qué nombres de propiedad aparecen en el código, un sanitizer custom mal mantenido da una falsa sensación de seguridad — peor que no tener nada, porque genera confianza donde no debería haberla. Prefiero el criterio de allowlist que ya planteé en el post anterior antes que un sanitizer que nadie actualiza.

Errores comunes y gotchas

Confundir autorización con sanitización. show-values=when-authorized controla acceso, no contenido. Son configuraciones independientes que hay que revisar las dos.
Copiar el regex de un proyecto anterior sin adaptarlo. Las convenciones de nombres cambian entre equipos y entre proyectos dentro del mismo equipo.
No testear el sanitizer con un caso negativo. Falta común: nadie escribe un test que verifique que una variable con nombre "raro" efectivamente sale enmascarada.
Pensar que el problema es solo de producción. Staging y entornos de desarrollo compartidos también exponen /actuator/env, y ahí suelen vivir credenciales reales de servicios de terceros para pruebas de integración.
Asumir que el framework te cubre las espaldas para siempre. Spring Boot mantiene actualizados sus propios keywords default con cada release; la lista de convenciones custom de tu equipo no forma parte de esa actualización — ese mantenimiento es tuyo, siempre.

FAQ

¿El sanitizer de Spring Boot enmascara todos los valores sensibles por default?
No. Enmascara valores cuyo nombre de propiedad contiene palabras específicas como password, secret, key, token o credentials. Cualquier convención de nombres distinta a esa queda sin cubrir salvo que se configure explícitamente.

¿Qué diferencia hay entre Sanitizer y SanitizingFunction?
SanitizingFunction es la interfaz recomendada en versiones recientes de Spring Boot para extender el comportamiento de sanitización de forma programática, reemplazando el enfoque anterior basado únicamente en una lista de keywords fija.

¿Puedo tener varios SanitizingFunction registrados a la vez?
Sí. Spring Boot los ejecuta en cadena; si cualquiera de ellos decide enmascarar un valor, ese valor queda enmascarado en la respuesta final.

¿Deshabilitar /actuator/env es más seguro que sanitizarlo?
Depende del caso de uso. Si tu equipo no tiene proceso para mantener actualizado el sanitizer custom, deshabilitar el endpoint o restringirlo con una allowlist estricta reduce el riesgo con menos mantenimiento continuo.

¿show-values=when-authorized resuelve el problema de los secretos expuestos?
No por sí solo. Controla quién puede ver los valores, no qué valores se muestran sin máscara a esos usuarios autorizados. Son dos configuraciones distintas que hay que combinar.

¿Cómo pruebo que mi sanitizer custom funciona antes de deployar?
Con un test unitario que invoque el bean SanitizingFunction directamente contra nombres de propiedad reales de tu proyecto, incluyendo casos con guiones bajos, mayúsculas mixtas y prefijos de proveedores externos.

Mi postura

El sanitizer default de Spring Boot no es un placebo: cubre el caso genérico razonablemente bien, según lo que documenta la propia referencia oficial. Lo que no puedo sostener sin evidencia productiva es cuánto exactamente reduce el riesgo en un proyecto específico — eso depende enteramente de qué tan alejadas estén las convenciones de nombres de ese proyecto respecto de la lista default.

Lo que sí puedo afirmar con criterio técnico: si nadie auditó los nombres de propiedad custom del proyecto contra la lista de patrones del sanitizer, hay una brecha sin cerrar. No es una posibilidad remota, es una consecuencia directa de cómo funciona el mecanismo.

Mi recomendación práctica es la misma lógica que usé para pensar allowlist de endpoints en el post anterior sobre actuator: tratá la sanitización como una lista viva que se revisa cada vez que se agrega una integración nueva, no como una configuración que se pone una vez y se olvida. El regex de hoy no cubre el nombre de variable que alguien va a inventar en el próximo sprint.

Lo incómodo de todo esto es que no hay checklist que te salve si nadie mira. Podés tener el SanitizingFunction más prolijo del mundo y seguir filtrando un secreto porque el pasante que armó la integración con el partner nuevo usó PARTNER_KEY_RAW y a nadie se le ocurrió actualizar el regex esa semana. La pregunta que me hago antes de habilitar cualquier endpoint de actuator no es "¿tiene sanitizer?" sino "¿quién es responsable de actualizar esta lista cuando cambie algo?". Si no hay respuesta clara, prefiero apagarlo.

Si te interesa cómo pienso decisiones de arquitectura con este mismo criterio de "qué cubre la herramienta versus qué tengo que cubrir yo", tengo posts relacionados sobre JWT vs sesiones con estado y sobre qué significa el camino a Java Champion que tocan la misma tensión desde otros ángulos.

Fuente original:

Spring Boot Actuator Docs: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html

Este artículo fue publicado originalmente en juanchi.dev

depends_on Isn't Enough: service_healthy in Compose

Juan Torchia — Wed, 09 Sep 2026 14:30:19 +0000

I lost probably forty minutes on this one the first time, and I still see it happen to other people. You spin up docker-compose up with a backend and a Postgres database. The backend has depends_on: [db]. Everything starts, the backend throws ECONNREFUSED two seconds in, the Postgres container is sitting there alive and well, and you start googling the error convinced it's a networking issue between services. It isn't. depends_on on its own did exactly what it promises: it waited for the db container to exist and be running. It never promised that Postgres inside it would be accepting connections.

I wrote about this same misunderstanding recently from another angle — the gap between what a healthcheck tells Docker and what it tells an orchestrator like Kubernetes. This post goes one level deeper: into the docker-compose.yml that anyone edits daily, no cluster, no readiness probes involved.

Docker Compose healthcheck: what it solves and what it doesn't

My thesis is simple: depends_on without condition is an illusion of order. It gives you container startup sequencing, not service availability sequencing. Only with condition: service_healthy do you get something verifiable — Compose won't start the second service until the first one's healthcheck reports healthy.

The source is the official Compose specification. It makes clear that healthcheck defines a command Docker runs periodically inside the container, and that depends_on accepts an object with condition instead of just a list of service names. The valid conditions are service_started, service_healthy, and service_completed_successfully. Without an explicit condition, the default is service_started — which is exactly the behavior that breaks expectations: container up, not necessarily the process inside responding.

Where people get it wrong

The common recipe I see in repos and tutorials — and, if I'm honest, the one I copy-pasted myself before it bit me — is this:

services:
  db:
    image: postgres:16
  api:
    build: .
    depends_on:
      - db

It compiles, it starts, it "works" in the demo because Postgres usually boots fast on a laptop with an SSD. The hidden cost shows up in CI, on a slower machine, or when someone adds an entrypoint.sh to the Postgres image that runs migrations before accepting connections. That's when the margin that "worked by luck" disappears and api fails its first connection. It's not dramatic, it's just annoying: a flaky pipeline that passes eight times out of ten and makes you doubt your own code before you doubt the compose file.

The counter-example that fixes this:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy

Now api doesn't start until pg_isready returns success multiple times per interval and retries. That's the difference between "the container exists" and "the container is ready," and it's exactly the same concept as the readiness probe Kubernetes formalizes with readinessProbe — but solved here at the local Compose level, no cluster needed.

flowchart LR
  A[db starts] --> B{db healthcheck}
  B -->|starting/unhealthy| B
  B -->|healthy| C[api starts]
  C --> D{api healthcheck}
  D -->|healthy| E[stack ready]

Decision matrix: when to condition and when not to

Not every service needs this rigidity, and slapping healthcheck on everything is its own kind of cargo cult. Here's the check I actually run before adding one:

Situation	What to do	Why
Stateful service (DB, cache, broker) that another service connects to on boot	`healthcheck` + `condition: service_healthy`	Early connection failure is predictable and cheap to avoid
Stateless service that only exposes HTTP and tolerates client-side retries	Simple `depends_on` or none	The cost of waiting can be higher than the cost of retrying in the app
One-shot migration job that runs and terminates	`condition: service_completed_successfully`	What matters isn't "healthy," it's that it finished successfully
CI environment with shared resources and slow startups	`healthcheck` with generous `retries`	A short timeout in CI produces false negatives you won't see locally
Microservice that already handles reconnection with backoff in its own code	Simple `depends_on`, let the app retry	Duplicating wait logic in Compose and in the code is redundant

What you CAN'T conclude from this

The Compose documentation doesn't tell you how long a healthcheck with specific interval, timeout, and retries values takes to converge in real production, because that depends on the image, the host, and the load — there's no universal number that fits every case. It also doesn't solve the problem of "service healthy but still can't handle real traffic" under load, which is different from "started up fine cold." And depends_on with condition, while it orders startup, isn't a continuous retry mechanism throughout the container's lifetime: if db goes down after api already started healthy, Compose doesn't go back to blocking anything. For that you need reconnection logic in the app's code, not in the docker-compose.yml.

Nor is it a substitute for Kubernetes's readinessProbe and livenessProbe if the final destination is a cluster: Compose solves the problem in local development or a staging docker-compose up, but the production orchestration guarantee lives at another level, with other tools and other restart semantics. What I don't buy is treating a green docker-compose up as proof that the same stack will behave in production — it proves ordering, nothing about load.

FAQ

Is depends_on without condition good for anything?
It's good for startup order and for making Compose stop containers in reverse order when you bring the stack down. It doesn't guarantee that the dependent service is ready to receive traffic.

What happens if the healthcheck never reaches healthy?
The service depending on it with condition: service_healthy never starts, and Compose reports it as a dependency failure. That's preferable to a silent startup that fails at runtime.

Does service_healthy work with any image?
Only if the image defines a healthcheck — either baked into the Dockerfile or declared in the docker-compose.yml. Without a defined healthcheck, Compose has no way to evaluate the condition.

Does this replace Kubernetes readiness probes?
No. They're analogous concepts but they live at different layers. Compose's healthcheck is for the world of local or simple self-hosted docker-compose up; readinessProbe is the equivalent piece when the destination is a Kubernetes cluster.

How many retries or what interval should I set?
There's no number that works for every case: it depends on the image and the environment. The sensible move is to start with conservative values, measure in your own CI pipeline or staging environment, and adjust based on what you observe there — not copy a value from a generic example.

Is condition: service_completed_successfully the same as service_healthy?
No. service_completed_successfully waits for the container to exit with a zero exit code, useful for one-shot migration jobs. service_healthy waits for a healthcheck that keeps running while the container is alive.

Bottom line

If a project's docker-compose.yml has depends_on as a plain list against a stateful service, there's a design flaw waiting for the worst possible moment to show up — probably in CI, with tighter resources than your dev laptop. The fix isn't complex: a well-defined healthcheck and condition: service_healthy. What I do ask is that you don't confuse this with a guarantee of continuous availability, nor with the equivalent of a production Kubernetes readiness probe. It's a guarantee of ordered startup in a local or simple staging environment, and that's how I treat it: useful, verifiable against the official source, and with limits worth knowing before you assume more than it delivers. The uncomfortable question worth asking your own repo today: does your compose file order containers, or does it order services actually being ready?

If the stack is already using TanStack Query against Server Actions, it's worth checking how cache invalidation is handled in that post about setQueryData. And if the next step is Next.js with layered caching, the difference between revalidatePath and revalidateTag is covered in this other analysis.

Original source: Docker Compose Spec — healthcheck

This article was originally published on juanchi.dev

depends_on no basta: el service_healthy en Compose

Juan Torchia — Wed, 09 Sep 2026 14:30:14 +0000

Levantás un docker-compose up con un backend y una base Postgres. El backend tiene depends_on: [db]. Arranca todo, el backend tira ECONNREFUSED a los dos segundos, el contenedor de Postgres sigue vivo, y googleás el error pensando que es un problema de red entre servicios. No lo es. Me pasó armando un stack chico para probar una migración: el contenedor de db estaba "up" en el docker ps, pero Postgres todavía estaba corriendo su inicialización interna y no aceptaba conexiones. depends_on sin más hizo exactamente lo que promete: esperó a que el contenedor de db existiera y estuviera corriendo. Nunca prometió que Postgres adentro estuviera aceptando conexiones.

Ese malentendido es viejo y lo escribí hace poco desde otro ángulo — la diferencia entre lo que un healthcheck le dice a Docker y lo que le dice a un orquestador como Kubernetes. Este post baja un nivel más: al docker-compose.yml que cualquiera edita a diario, sin cluster, sin readiness probes de Kubernetes de por medio.

Docker Compose healthcheck: qué resuelve y qué no

Mi tesis es simple: depends_on sin condition es una ilusión de orden. Te da secuencia de arranque de contenedores, no secuencia de disponibilidad de servicio. Con condition: service_healthy recién ahí tenés algo verificable — Compose no arranca el segundo servicio hasta que el healthcheck del primero reporte healthy.

Lo incómodo es que esta confusión no es un error de configuración raro: es el comportamiento default de Compose, y por eso aparece en tantos repos que "andan bien" hasta que dejan de andar.

La fuente es la especificación oficial de Compose. Ahí queda claro que healthcheck define un comando que Docker ejecuta periódicamente dentro del contenedor, y que depends_on acepta un objeto con condition en vez de solo una lista de nombres de servicios. Las condiciones válidas son service_started, service_healthy y service_completed_successfully. Sin condition explícita, el default es service_started, que es exactamente el comportamiento que rompe expectativas: contenedor arriba, no necesariamente el proceso adentro respondiendo.

Dónde se equivoca la gente

La receta común que veo en repos y en tutoriales es esta:

services:
  db:
    image: postgres:16
  api:
    build: .
    depends_on:
      - db

Compila, arranca, "funciona" en la demo porque Postgres suele levantar rápido en una laptop con SSD. El costo oculto aparece en CI, en una máquina más lenta, o cuando alguien le agrega un entrypoint.sh a la imagen de Postgres que corre migraciones antes de aceptar conexiones. Ahí el margen que "funcionaba por suerte" desaparece y el api falla la primera conexión.

El contraejemplo que corrige esto:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy

Ahora api no arranca hasta que pg_isready devuelva éxito varias veces según interval y retries. Es la diferencia entre "el contenedor existe" y "el contenedor está listo", y es exactamente el mismo concepto de readiness probe que Kubernetes formaliza con readinessProbe — pero acá resuelto a nivel de Compose local, sin necesidad de un cluster.

flowchart LR
  A[db arranca] --> B{healthcheck de db}
  B -->|starting/unhealthy| B
  B -->|healthy| C[api arranca]
  C --> D{healthcheck de api}
  D -->|healthy| E[stack listo]

Matriz de decisión: cuándo condicionar y cuándo no

No todo servicio necesita esta rigidez. Antes de agregar healthcheck y condition: service_healthy en cada línea, conviene mirar esto:

Situación	Qué hacer	Por qué
Servicio con estado (DB, cache, broker) al que otro se conecta al boot	`healthcheck` + `condition: service_healthy`	El fallo de conexión temprana es predecible y barato de evitar
Servicio sin estado que solo expone HTTP y tolera reintentos en el cliente	`depends_on` simple o ninguno	El costo de esperar puede ser mayor que el de reintentar en la app
Job de migración que corre una vez y termina	`condition: service_completed_successfully`	No es "healthy" lo que importa, es que terminó bien
Entorno de CI con recursos compartidos y arranques lentos	`healthcheck` con `retries` generosos	Un timeout corto en CI genera falsos negativos que no ves en local
Microservicio que ya maneja reconexión con backoff en su propio código	`depends_on` simple, dejar que la app reintente	Duplicar la lógica de espera en Compose y en el código es redundante

Qué NO se puede concluir de esto

La documentación de Compose no dice cuánto tarda en converger un healthcheck con valores específicos de interval, timeout y retries en producción real, porque eso depende de la imagen, del host y de la carga — no hay un número universal que valga para todos los casos. Tampoco resuelve el problema de "servicio healthy pero todavía no puede atender tráfico real" bajo carga, que es distinto de "arrancó bien en frío". Y depends_on con condition, aunque ordena el arranque, no es un mecanismo de reintento continuo durante la vida del contenedor: si db se cae después de que api ya arrancó healthy, Compose no vuelve a bloquear nada. Para eso hace falta la lógica de reconexión en el código de la app, no en el docker-compose.yml.

Tampoco es un sustituto de readinessProbe y livenessProbe de Kubernetes si el destino final es un cluster: Compose resuelve el problema en desarrollo local o en un docker-compose up de staging, pero la garantía de orquestación productiva vive en otro nivel, con otras herramientas y otras semánticas de reinicio.

FAQ

¿depends_on sin condition sirve para algo?
Sirve para el orden de arranque y para que Compose pare los contenedores en el orden inverso al bajar el stack. No sirve para garantizar que el servicio dependido esté listo para recibir tráfico.

¿Qué pasa si el healthcheck nunca llega a healthy?
El servicio que depende de él con condition: service_healthy no arranca, y Compose lo reporta como fallo de dependencia. Prefiero eso mil veces a un arranque silencioso que falla en runtime y te hace perder media hora googleando un ECONNREFUSED.

¿service_healthy funciona con cualquier imagen?
Solo si la imagen define un healthcheck — propio en el Dockerfile o declarado en el docker-compose.yml. Sin healthcheck definido, Compose no tiene manera de evaluar la condición.

¿Esto reemplaza los readiness probes de Kubernetes?
No. Son conceptos análogos pero viven en capas distintas. healthcheck de Compose es para el mundo de docker-compose up local o self-hosted simple; readinessProbe es la pieza equivalente cuando el destino es un cluster de Kubernetes.

¿Cuántos retries o qué interval conviene poner?
No hay un número que sirva para todos los casos: depende de la imagen y el entorno. Lo prudente es arrancar con valores conservadores, medir en el propio pipeline de CI o entorno de staging, y ajustar según lo que se observe ahí — no copiar un valor de un ejemplo genérico.

¿condition: service_completed_successfully es lo mismo que service_healthy?
No. service_completed_successfully espera a que el contenedor termine con código de salida cero, útil para jobs de migración one-shot. service_healthy espera a un healthcheck que sigue corriendo mientras el contenedor vive.

Postura final

Si tu docker-compose.yml tiene depends_on como lista simple contra un servicio con estado, hay una falla de diseño esperando el momento menos oportuno para aparecer — probablemente en CI, con recursos más ajustados que en tu laptop. La corrección no es compleja: un healthcheck bien definido y condition: service_healthy. Lo que sí pido es que no lo confundas con una garantía de disponibilidad continua ni con el equivalente de un readiness probe de Kubernetes en producción. Es una garantía de arranque ordenado en un entorno local o de staging simple, y como tal hay que tratarla: útil, verificable contra la fuente oficial, y con límites que conviene conocer antes de asumir más de lo que da. Mi límite personal: si el proyecto ya tiene un cluster de verdad, dejo de pelear con Compose y muevo la garantía de readiness a donde corresponde.

Si el stack ya usa TanStack Query contra Server Actions, vale la pena revisar cómo se maneja la invalidación de cache en ese post sobre setQueryData. Y si el próximo paso es Next.js con cache en capas, la diferencia entre revalidatePath y revalidateTag está detallada en este otro análisis.

Fuente original: Docker Compose Spec — healthcheck

Este artículo fue publicado originalmente en juanchi.dev