That is the moment I find the bonsai metaphor useful, with one important correction: the job is not to make code look pretty. The job is to preserve a living system while shaping it so the next change has somewhere safe to go.

The metaphor is useful because growth is the problem

Bonsai is not a miniature tree that happens by accident. Its shape comes from repeated, deliberate interventions: pruning, wiring, repotting, and deciding which growth to keep. The tree stays alive, but it does not stay untouched.

Software has the same tension. A healthy service keeps changing because product requirements, dependencies, traffic, and operators change. Left alone, the code can still compile and serve requests while its internal shape becomes costly to understand. The first symptom is not necessarily a defect. Often it is hesitation: the team starts treating a local edit as if it might wake something elsewhere.

Martin Fowler's definition adds the part that is easy to lose: refactoring changes internal structure to make software easier to understand and cheaper to modify, without changing observable behavior. That excludes feature work, a migration that changes a contract, and a rewrite dressed up as cleanup. Those can all be worthwhile. They simply need different planning and different evidence.

Calling everything “refactoring” is how a small maintenance task acquires an unlimited blast radius.

A bonsai is not a weekly haircut

The weak version of the metaphor produces cosmetic work: rename a few variables, reorder imports, split a long file, declare victory. Those changes can help, but they do not automatically make future changes safer.

A better question is: what recurring change does this shape make expensive?

If every new HTTP endpoint requires copying authorization checks, the useful work might be extracting an explicit policy boundary. If a feature flag has spread through handlers, workers, and templates, the issue is probably lifecycle ownership rather than the length of any one function. If an on-call engineer cannot identify the request path during an outage, improving observability or module boundaries may matter more than satisfying a linter.

Refactoring earns its keep when a real next change has exposed a structural constraint.

The shears are tests, not confidence

There is a dangerous part of the gardening analogy. Pruning a branch is visible. A behavior regression may be invisible until production traffic finds it.

That is why tests are not an optional polish step around refactoring. They are the evidence that the system still behaves as intended after an internal change. The refactoring literature repeatedly emphasizes small, safe mechanics. In a 2020 case study on an oversized class, Clare Sudbery describes keeping the code compiling and the tests running at every step, with coverage in place before the refactor starts.

For a service, I would want the narrowest test that protects the behavior being moved, plus the checks that make the deployment credible:

• a unit or component test for the rule being extracted;
• a contract or integration test where the code crosses a boundary; and
• where proportionate, a post-deployment synthetic probe or smoke check for the important path.

The exact stack differs. If the available evidence cannot support the claim that the intended behavior stayed stable, describe the change more modestly or add the missing check.

This also gives a useful stop condition. When a proposed cleanup cannot be protected by a reasonably scoped test, the first task may be characterization: document and test what the system does today, including the awkward behavior nobody wants to rediscover during an incident. Only then is the pruning safe.

AI makes overgrowth faster

AI-assisted coding changes the economics here. It can produce a working branch, a duplicate helper, or another configuration path in seconds. That is useful when the team is deliberate. It also means structural debt can arrive at a rate that manual coding rarely achieved.

A 2025 paper, The Shift from Writing to Pruning Software, proposes a bonsai-inspired interface for AI-generated code. Its core observation is sensible: when generation becomes cheap, the human task shifts toward navigating, evaluating, and reshaping a larger body of code. The paper proposes an interface; it is not evidence that the approach improves production reliability. Still, the direction matches a practical concern: generation can reduce the cost of adding code without reducing the cost of owning it.

The response should not be “never use AI.” It should be to give generated code the same ownership questions as handwritten code:

• What responsibility does this new code own?
• Which existing path does it duplicate or bypass?
• What behavior proves it belongs here?
• If it needs to change later, where would an engineer look first?

If those questions have no good answer, the code is not ready just because it passes the current build.

An infrastructure engineer prunes more than application code

For an infrastructure or platform engineer, the tree extends beyond a service repository: delivery pipelines; infrastructure definitions and environment overlays; identity, network, and secret boundaries; runtime configuration; observability; and the runbooks and recovery paths that connect them.

The same failure mode appears at every layer: a workaround becomes a pattern, a copied pipeline step diverges, an exception disappears into an overlay, or an alert keeps firing because no one owns the decision it is meant to support. Declarative infrastructure can accumulate structural debt just as application code can.

That makes refactoring part of the platform engineer's job, not a side activity reserved for developers. The target is not maximal abstraction. It is a platform whose next user, deploy, incident, and security change can be made with a clear owner, a small review surface, and evidence.

A practical sweep across the field looks like this:

• Platform and developer experience: turn tribal deployment knowledge into paved paths, understandable templates, and documented interfaces. Remove a platform abstraction when it only hides the system without removing work.
• CI/CD and GitOps: consolidate duplicated release logic, make promotion and rollback paths explicit, and keep generated or rendered configuration reviewable. A pipeline refactor is incomplete if an operator cannot tell what will reach production.
• Cloud and infrastructure as code: separate reusable modules from environment-specific intent, name ownership boundaries, and avoid copy-pasted resources that drift independently. Treat plans and policy checks as evidence, while remembering that they do not prove the live system is unchanged.
• Kubernetes and runtime operations: simplify workload, ingress, Gateway, policy, and configuration overlays while preserving the routing and rollout contract. Rendered manifests and a bounded runtime check are stronger evidence than a tidy directory tree.
• Security and identity: reduce broad permissions, clarify trust boundaries, remove obsolete access paths, and make secret rotation and break-glass procedures testable. A cleaner IAM policy is not safer unless the required workload still functions and the unwanted path is actually closed.
• Networking and reliability: replace undocumented routing exceptions with explicit contracts; preserve DNS, TLS, timeout, retry, and failover behavior as you simplify. For a customer-facing path, verification must extend beyond a syntax check.
• Observability and incident response: prune dashboards, alerts, and runbooks that no longer map to an operational decision. Keep the signals that let an engineer answer what changed, who is affected, and how to roll back.
• Cost and capacity: remove idle or duplicated resources only after measuring dependency and demand. Cost reduction is a production change, not janitorial work.

None of these areas needs a giant “platform cleanup” programme to improve. The valuable unit is still a small, explainable structural change backed by the evidence appropriate to that layer: an IaC plan, a rendered manifest diff, a policy evaluation, a synthetic request, a rollout observation, or a recovery exercise. The appropriate checks vary by layer, but each should support a specific preservation claim.

Prune on the path of work

A bonsai owner does not reshape the entire tree every time they notice one awkward branch. The same restraint matters in production code.

I prefer refactoring that is adjacent to a real change: improve a boundary before extending it, remove duplication when the second copy appears, name a concept when the team needs to discuss it, and leave unrelated cleanups alone. This keeps the diff reviewable and lets the pull request tell a coherent story.

It also makes verification more honest. A narrowly scoped refactor can state what it preserved, which tests exercised that claim, and what it deliberately did not touch. A broad “cleanup” commit usually cannot.

There are times to fund a larger structural effort. Repeated incidents, a blocked security upgrade, an untestable critical path, or a migration that keeps failing for the same architectural reason are all stronger signals than aesthetic discomfort. Even then, split the work into behavior-preserving slices where possible. The system does not care that the end state looked tidy in a diagram if the path there breaks customers.

A small operating loop

Before calling a change refactoring, I would write down four things:

1. The behavior to preserve. Describe it from the caller or user perspective, not from the internal class name.
2. The structural pressure. Name the repeated cost: duplicated policy, hidden dependency, impossible test setup, ambiguous ownership, or something equally concrete.
3. The evidence. Identify the test or probe that should remain green before and after the change.
4. The boundary. State what is not being redesigned in this pull request.

Then make one structural move, run the evidence, and review the diff as if you were the next person debugging it at an inconvenient hour.

That is less romantic than trimming a miniature tree. It is also more useful. Refactoring is routine maintenance of the structure through which future changes must travel.

Limits of the metaphor

Bonsai suggests a single careful owner and a stable aesthetic goal. Real systems have many owners, competing requirements, and behavior that must change. Refactoring will not replace migration planning, incident response, performance work, or product decisions. A green test suite also cannot prove every production property, especially across external dependencies and real traffic.

So use the image lightly. Keep the discipline.

Preserve the behavior you can state. Improve the structure that is making real work harder. Keep the change small enough to understand. And do not put the shears down until you have evidence that the tree still lives.

Sources and further reading

• Martin Fowler, Refactoring. Fowler defines refactoring as changing internal structure to make software easier to understand and cheaper to modify without changing observable behavior.
• Clare Sudbery, Refactoring: This class is too large (2020). A practical case study of incremental refactoring, covering tests, compiling at every step, and small commits.
• Ulam Labs, Why is refactoring your code important? (2020). A useful example of the bonsai analogy, though this article intentionally avoids treating cleanliness or security as automatic outcomes of refactoring.
• The Shift from Writing to Pruning Software: A Bonsai-Inspired IDE for Reshaping AI Generated Code, arXiv:2503.02833 (2025). A research proposal about navigating and reshaping generated code, not a production-effectiveness study.

ingress-nginx reached retirement in March 2026. The obvious response is to convert manifests to Gateway API and move on.

I do not think that is enough.

An ingress migration changes the way a public request reaches an application. The YAML is different, but the thing worth preserving is a routing contract: which hostnames exist, which paths match, which backend receives them, whether HTTP redirects, where TLS terminates, and which exceptions were carried by annotations.

The Kubernetes SIG Network project ingress2gateway is the right kind of starting point. It converts Ingress and supported provider resources into Gateway API resources, and it reports fields it cannot translate. Its current v1.2.0 release was published on July 7, 2026.

I wanted to see what that warning surface looks like in a small, bounded migration—not to test a live controller.

The fixture was deliberately awkward

I made one synthetic Ingress for shop.example.test:

• TLS with a named Secret;
• a / prefix route to a storefront service;
• an /api(/|$)(.*) regular-expression route to an API service;
• an HTTP-to-HTTPS redirect; and
• the common ingress-nginx rewrite annotation nginx.ingress.kubernetes.io/rewrite-target: /$2.

That last field is the important one. It changes the request URI forwarded to the application. Losing it can turn a migration that looks correct in a manifest review into an application-level break.

I built ingress2gateway from the signed v1.2.0 source tag in a disposable Docker build stage. The final run used a non-root UID, no network, a read-only filesystem, a small temporary filesystem, dropped Linux capabilities, no-new-privileges, one CPU, 256 MiB memory, and a PID limit of 64. The fixture was baked into the image, so the run did not mount a host directory.

Gateway/nginx
HTTPRoute/store-shop-example-test
HTTPRoute/store-shop-example-test-http

The generated Gateway preserved the hostname and produced separate HTTP and HTTPS listeners:

listeners:
- hostname: shop.example.test
  name: shop-example-test-http
  port: 80
  protocol: HTTP
- hostname: shop.example.test
  name: shop-example-test-https
  port: 443
  protocol: HTTPS
  tls:
    certificateRefs:
    - kind: Secret
      name: shop-tls

It also generated a port-80 HTTPRoute that returns a 308 redirect to HTTPS. That is a concrete routing behavior worth checking, not just a generated object worth counting.

The converter gave me the review list

The conversion did not silently declare success. It emitted these warnings:

INFO  Using case-insensitive regex path matches. You may want to change this.

WARN  Path rewrites with capture group references are not supported
      source: STANDARD_EMITTER
      object: HTTPRoute: demo/store-shop-example-test

WARN  Gateway API does not support configuring URL normalization
      Please check if this matters for your use case.

That is the most useful result of the experiment.

The generated HTTPS route still matched the API pattern:

matches:
- path:
    type: RegularExpression
    value: (?i)/api(/|$)(.*).*
backendRefs:
- name: api
  port: 8080

But the $2 rewrite was absent because the standard conversion cannot represent capture-group references. The route exists; the request URI semantics may not. A simple resource-by-resource diff would make that easy to miss.

Conversion is not equivalence

ingress2gateway documents an important boundary: it translates supported Ingress fields and provider-specific resources into Gateway API resources; it is not meant to copy annotations blindly. That is sensible. Many annotations are controller-specific behavior, not portable API.

The consequence is that every untranslatable annotation is a migration-review item. It should have an owner and a decision:

warning -> affected route -> expected behavior -> replacement or explicit acceptance

For this fixture, the follow-up would be to decide how the API should receive /api/... requests under the target Gateway implementation. That might require a supported rewrite mechanism, a backend change, or a decision to preserve controller-specific behavior outside the standard conversion. The converter cannot safely make that product decision.

The check I would put beside a migration PR

I would review an Ingress-to-Gateway change as a table of observable behavior, not as an object count:

Only the final column can establish that a controller accepts and serves the intended configuration. My Docker run did not install Gateway API CRDs, start a controller, contact a cluster, resolve DNS, or send an external request. It proved that the converter can surface an important portability gap in a repeatable synthetic input. It did not prove a production migration safe.

That distinction matters. A migration has passed the conversion stage when its generated resources parse and its warnings are understood. It has passed the routing stage only when the target controller reports accepted resources and the expected requests behave correctly.

What I would build next

The gap is not another converter. ingress2gateway already has a focused job, supports several providers and emitters, and reports unsupported behavior.

The useful companion would be a small, offline routing-contract diff: read the source Ingress plus the generated Gateway and Routes, then list hosts, path matching, backends, redirects, TLS references, and converter warnings side by side. It should flag a missing rewrite or a changed match mode as review required, never claim behavioral equivalence.

That would make the handoff from conversion output to migration review explicit—the same way a good GitOps diff turns a subtle configuration change into a question someone can answer deliberately.

Test notes: This was a smoke test in a disposable Docker image built from the ingress2gateway v1.2.0 source tag. The final container ran as UID 65532 with --network none, a read-only filesystem, /tmp as a limited tmpfs, all capabilities dropped, no-new-privileges, --pids-limit 64, --memory 256m, and --cpus 1. It used one sanitized synthetic Ingress. No Kubernetes cluster, kubeconfig, DNS provider, Secret value, or live hostname was accessed. The output YAML SHA-256 was 11aa5ed72087027043e299a6b78e9f1efd944f26b3883127cdcc375e469dbaa5.

Sources: Kubernetes on the retirement of ingress-nginx · Ingress2Gateway 1.0 announcement · ingress2gateway documentation

Related work: I built a security-impact diff for GitOps · A rollout needs a return address

Original diagram for this Docker-only build note. It shows a configuration disagreement, not a production incident.

I kept tripping over the same sentence while writing about health checks: “we gate the rollout on readiness.”

It sounds reassuring. Then you open the deployment file and find a healthcheck that calls /healthz, because that endpoint was easy to add and it returns 200 as long as the process is alive.

Neither file is necessarily wrong on its own. Together, they can tell two different stories.

So I made a small CLI called probe-contract. It compares a declared health contract with a Docker Compose file and reports the disagreements that are easy to miss in review.

The first release is deliberately small. It does not call a live endpoint. It does not attempt to infer whether a checkout flow, queue, or database is truly healthy. It reads configuration and asks a narrower question: does the probe in the deployment file support the health assumption you wrote down?

The smallest useful contract

The tool takes a tiny YAML file alongside Compose:

services:
  api:
    liveness: /healthz
    readiness: /readyz
    user_path: /checkout
    rollout_gate: readiness

Then it compares that declaration with the Compose healthcheck.

For the mismatch case, the contract said readiness should gate the rollout, while the Compose probe called only /healthz:

WARNING  api: rollout_gate is readiness, but Compose healthcheck does not reference /readyz (READINESS_NOT_PROBED)

That warning is the whole point of the first version. It does not prove /readyz is a good readiness endpoint. It makes the disagreement visible before somebody treats a green container as proof that a rollout is safe.

I tested the tool in a container too

I ran the released CLI against its fixtures inside a Docker container with a read-only filesystem, a non-root user, dropped capabilities, and no-new-privileges.

The valid fixture produced empty JSON:

{
  "diagnostics": []
}

A Compose file with its healthcheck explicitly disabled produced an error and exit code 1:

ERROR  api: service has no Compose healthcheck (HEALTHCHECK_MISSING)

That second case mattered. An early review of the tool found that healthcheck: { disable: true } could look like an active healthcheck to a naive YAML parser. The release now treats both disable: true and Docker’s test: [NONE] form as missing checks.

The review also caught a less obvious false pass: /ready should not match /readyz just because one string contains the other. That is fixed too. A health contract is already an approximation; the checker should not add accidental ambiguity on top.

What it checks today

probe-contract v0.1.0 checks a few things and stops there:

• a service declared in the contract is present in Compose;
• that service has an active healthcheck;
• a readiness rollout gate actually probes the declared readiness path;
• liveness and readiness are not declared as the same endpoint by accident;
• interval, timeout, and retries are present on the healthcheck.

It emits human-readable text by default and JSON with --format json, which is enough to start using it in CI without making every warning a release blocker.

What it intentionally does not do

I do not want this to become another linter that promises too much.

It does not inspect Kubernetes manifests yet. It does not send traffic to a live service. It does not infer a business transaction from a URL. And it cannot tell whether a dependency should be part of readiness for a particular application.

Those choices belong to the team running the service. The tool only asks them to make the choice explicit, then checks whether the Compose file agrees.

That scope is small enough to be useful. It is also small enough that a reviewer can understand what a warning means without trusting a black box.

Release and next steps

The project is public under MIT and includes a Linux amd64 binary with a checksum:

• Source and README
• v0.1.0 release

The next likely steps are Kubernetes manifest support, SARIF output, and a GitHub Action. I am deliberately not calling those features until the Compose contract is useful enough to earn them.

Test notes: I built and ran probe-contract v0.1.0 only in Docker for this note. The demonstration container used a read-only filesystem, non-root UID 65532, dropped Linux capabilities, no-new-privileges, and read-only mounted fixture files. The results are configuration checks against local fixtures, not a benchmark or a production deployment.

Related work: Delivery systems case study · I made a healthy service page on purpose

Original diagram for a Docker-only experiment in this note. It models a failed dependency, not a production system.

I made a service look healthy on purpose.

Not healthy to a user. Healthy to the one check that only cared whether the process was still running.

It is an easy trap. A container is up, the liveness endpoint returns 200, the dashboard stays green, and everyone gets to feel better for a few minutes. Meanwhile the dependency the service needs has gone away, requests are timing out, and the thing users came for is unavailable.

I built a tiny version of that failure in a disposable Docker container. The service had three endpoints:

/healthz   process liveness
/readyz    dependency-aware readiness
/checkout  a small user-facing path

With the simulated dependency available, all three were fine:

/healthz   http=200 body=process=up
/readyz    http=200 body=dependency=reachable
/checkout  http=200 body=checkout=accepted

Then I restarted the same demo with one environment flag that simulated a dependency failure. The Python process did not crash. That is important.

/healthz   http=200 body=process=up
/readyz    http=503 body=dependency=unavailable
/checkout  http=503 body=checkout=unavailable: dependency timeout

The liveness check was not lying. It answered the question it was given: is the process alive? The problem is that it was the wrong question for deciding whether to send a user more traffic, or whether a rollout was safe to keep.

Three questions that should not share one endpoint

I find it useful to separate health checks by the decision they support.

/healthz asks whether restarting the process is likely to help. A process that cannot accept a TCP connection, is deadlocked, or has stopped responding belongs here. This check should be narrow. If every temporary dependency wobble makes it fail, an orchestrator can turn a recoverable outage into a restart loop.

/readyz asks whether the instance should receive work. In the experiment, it included the dependency state. That made it a reasonable signal for traffic admission and rollout progress. A failing readiness check can take an instance out of rotation without pretending that the process needs to be killed.

/checkout asks the least convenient question: can someone complete the thing they actually came to do? It is usually more expensive to measure and should not become a noisy probe that hits every dependency every second. But some form of user-path signal belongs in monitoring. Otherwise a green fleet can hide a useless product.

A green container is a weak promise

Container state is still useful. It tells you whether a workload exists and whether the runtime can keep it alive. It does not tell you that the application has a connection pool, that the queue is moving, or that an important request succeeds.

That distinction matters most during a deployment. If a new version starts successfully but cannot talk to its required dependency, a liveness-only check may let the rollout continue. The failure then moves from deployment time to user time, where it is noisier and harder to unwind.

This is also why I do not like treating readiness as a cosmetic endpoint added late in a project. It is part of the contract between the application and the platform. The platform needs an honest answer before it decides to route traffic or declare a revision ready.

Do not turn readiness into a dependency census

There is a bad version of this pattern too: make /readyz call every downstream service, every time, and fail on any brief hiccup.

That can create its own outage. If a shared dependency has a short blip, hundreds of instances may all become unready at once. A probe that was meant to reduce risk becomes a traffic switch with no damping.

The useful questions are smaller:

• Which dependency makes this instance incapable of doing its primary job?
• How long must that dependency be unavailable before traffic should stop?
• Can the check use a bounded timeout and cached result instead of adding load during an incident?
• What signal tells us the user path is degraded even if the process remains alive?

The answers will differ by service. A worker may be alive and intentionally disconnected while a queue is paused. A checkout API with no database connection is not in the same situation.

What I would wire into a real rollout

For a non-critical environment, I would start with a deliberately boring drill:

1. deploy a candidate revision;
2. make one required dependency unavailable in a controlled way;
3. confirm that readiness fails while liveness stays stable;
4. confirm that the traffic or rollout controller reacts to readiness, not just process survival;
5. restore the dependency and verify the user-facing path, not only the pod state.

That drill has a nice side effect: it makes the rollback criteria concrete. In my previous note, I argued that a rollout needs a return address. This is part of the address book. If the only evidence after a rollback is “the pods are running,” there is still a lot left to guess.

Test notes: I ran this in two disposable Docker containers using Python 3.12. Each container used a read-only root filesystem, dropped Linux capabilities, no-new-privileges, a PID limit of 64, 0.25 CPU, and 128 MiB memory. The dependency failure was a local simulation. No host service, production endpoint, cluster, or external dependency was accessed.

Related reading: A rollout needs a return address · Delivery systems case study