<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Razvan Mareș</title>
    <description>The latest articles on DEV Community by Razvan Mareș (@razvanm4).</description>
    <link>https://dev.to/razvanm4</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254773%2F3a18b599-3198-4865-86bc-5eb478b0bb28.jpg</url>
      <title>DEV Community: Razvan Mareș</title>
      <link>https://dev.to/razvanm4</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/razvanm4"/>
    <language>en</language>
    <item>
      <title>Use Claude Opus 4.8 as a Red Team for Pull Request Reviews</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:55:22 +0000</pubDate>
      <link>https://dev.to/razvanm4/use-claude-opus-48-as-a-red-team-for-pull-request-reviews-29k8</link>
      <guid>https://dev.to/razvanm4/use-claude-opus-48-as-a-red-team-for-pull-request-reviews-29k8</guid>
      <description>&lt;p&gt;Most AI-assisted code review fails for a simple reason: it is asked to behave like a faster linter.&lt;/p&gt;

&lt;p&gt;A pull request arrives. The model reads the diff. It identifies an unchecked null, suggests a clearer variable name, and points out that a method could be extracted. Those observations may be correct, but they are rarely the issues that create expensive incidents.&lt;/p&gt;

&lt;p&gt;The higher-value role for Claude Opus 4.8 is not &lt;em&gt;diff scanner&lt;/em&gt;. It is &lt;em&gt;review red team&lt;/em&gt;: a second engineering voice that assumes the proposed change is plausible, then actively searches for the conditions under which it becomes unsafe, inconsistent, or operationally costly.&lt;/p&gt;

&lt;p&gt;That framing changes the inputs, the prompt, the automation, and—most importantly—the standard for what counts as useful feedback.&lt;/p&gt;

&lt;h2&gt;
  
  
  Review the change as a system, not a patch
&lt;/h2&gt;

&lt;p&gt;A code diff is evidence of a change, not the complete change itself. A few edited lines can alter authorization behavior, break retry safety, change database load characteristics, or create a migration path with no rollback story.&lt;/p&gt;

&lt;p&gt;A red-team review starts by reconstructing the system boundary around the patch. Claude Opus 4.8 should receive more than changed files when the risk justifies it. Useful context includes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The pull request description and acceptance criteria&lt;/li&gt;
&lt;li&gt;Related API contracts or OpenAPI definitions&lt;/li&gt;
&lt;li&gt;Relevant database schema and migrations&lt;/li&gt;
&lt;li&gt;Existing tests, especially integration and authorization tests&lt;/li&gt;
&lt;li&gt;Repository conventions from &lt;code&gt;CONTRIBUTING.md&lt;/code&gt; or architecture documents&lt;/li&gt;
&lt;li&gt;Error-handling, logging, and observability patterns&lt;/li&gt;
&lt;li&gt;The deployment environment and feature-flag behavior&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The goal is not to load the entire repository into context by default. That creates noise and makes review slower. Instead, construct a compact evidence packet around the changed capability.&lt;/p&gt;

&lt;p&gt;For example, a change that adds &lt;code&gt;POST /orders/{id}/cancel&lt;/code&gt; should not be reviewed only as a controller and service diff. Include the order state model, payment-provider integration, event publishing code, and tests for existing state transitions. The most serious defect may be that cancellation publishes an event before the transaction commits, not that the endpoint lacks a guard clause.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give the model an adversarial mission
&lt;/h2&gt;

&lt;p&gt;Generic prompts produce generic reviews. Asking “review this code” delegates too much judgment to the model and gives it no definition of success.&lt;/p&gt;

&lt;p&gt;A stronger instruction defines the review posture, the evidence threshold, and the required output. For example:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Act as a senior reviewer attempting to disprove the safety of this pull request. Focus on defects that could cause incorrect behavior, security exposure, data corruption, production incidents, or material maintenance cost. Do not report style preferences. For every finding, cite the relevant file and line, explain the failure path, state the preconditions, and recommend a concrete fix. If evidence is insufficient, label the concern as a question rather than a defect.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;This prompt does two useful things. First, it directs attention toward consequences instead of code aesthetics. Second, it forces a distinction between a demonstrated defect and an unresolved uncertainty.&lt;/p&gt;

&lt;p&gt;That distinction matters in real teams. An AI comment that says “this might have a race condition” is easy to dismiss. A comment that says “two concurrent requests can both pass the &lt;code&gt;Pending&lt;/code&gt; check before either transaction writes &lt;code&gt;Cancelled&lt;/code&gt;; the second request then refunds an already-refunded payment” gives an engineer a reproducible failure model.&lt;/p&gt;

&lt;h2&gt;
  
  
  Organize review around failure modes
&lt;/h2&gt;

&lt;p&gt;Claude Opus 4.8 is most effective when it is asked to inspect a finite set of engineering risks. A practical review template can use these lenses.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Contract and compatibility failures
&lt;/h3&gt;

&lt;p&gt;Ask whether callers, clients, background workers, and stored data still agree with the changed behavior.&lt;/p&gt;

&lt;p&gt;Questions include:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Does a response shape change break existing consumers?&lt;/li&gt;
&lt;li&gt;Does an optional field become required in practice?&lt;/li&gt;
&lt;li&gt;Are enum additions handled by older clients and downstream services?&lt;/li&gt;
&lt;li&gt;Does the new behavior preserve idempotency for retries?&lt;/li&gt;
&lt;li&gt;Does a database migration work during a rolling deployment where application versions overlap?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For REST APIs, provide request and response examples alongside the diff. For TypeScript services, include shared types and serialization code. Contract failures frequently live at the seam between two repositories or two deployment versions, where a local compilation pass provides no protection.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Authorization and data-boundary failures
&lt;/h3&gt;

&lt;p&gt;Authorization bugs are often hidden by valid-looking business logic. The code may correctly load an entity, perform the requested operation, and return the expected result—on the wrong tenant’s data.&lt;/p&gt;

&lt;p&gt;Ask the model to trace identity and scope from request entry point to persistence query. In particular, have it look for identifiers accepted from route parameters or request bodies without an ownership constraint.&lt;/p&gt;

&lt;p&gt;A useful review question is: &lt;em&gt;Can a correctly authenticated but improperly scoped user make this path affect data they do not control?&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;This framing catches more than missing role checks. It surfaces multi-tenant query mistakes, cache keys that omit tenant identity, object storage paths derived from user input, and background jobs that run without the original authorization context.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. State, concurrency, and transaction failures
&lt;/h3&gt;

&lt;p&gt;The riskiest code often looks clean in a single-threaded mental model. Claude can examine the timeline that developers do not see while reading top to bottom.&lt;/p&gt;

&lt;p&gt;Provide the transaction boundary and ask it to reason about concurrent requests, retries, partial failures, and worker restarts. For EF Core and SQL-backed applications, request explicit analysis of:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Read-modify-write sequences&lt;/li&gt;
&lt;li&gt;Isolation assumptions&lt;/li&gt;
&lt;li&gt;Unique constraints used as concurrency guards&lt;/li&gt;
&lt;li&gt;Transaction scope around event publication&lt;/li&gt;
&lt;li&gt;Retry behavior after timeouts&lt;/li&gt;
&lt;li&gt;Migration locking and table rewrite risks&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A particularly valuable pattern is the transactional outbox. If a pull request writes business data and publishes a Kafka or RabbitMQ event separately, ask whether a process crash can leave the two systems disagreeing. The model should not merely recommend an outbox by habit; it should identify the exact failure window and assess whether the domain can tolerate it.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Operational and observability failures
&lt;/h3&gt;

&lt;p&gt;Production software must be diagnosable under stress. Ask Claude to inspect what happens when dependencies are slow, unavailable, or unexpectedly successful twice.&lt;/p&gt;

&lt;p&gt;A review should identify missing timeouts, unbounded retries, swallowed exceptions, logging of secrets, metrics that cannot distinguish failure modes, and endpoints that accidentally trigger expensive queries.&lt;/p&gt;

&lt;p&gt;This is also where repository context matters. A new retry loop may be sensible in isolation but harmful when an existing HTTP client, queue consumer, or reverse proxy already retries upstream failures. Layered retries can turn a brief dependency outage into a thundering herd.&lt;/p&gt;

&lt;h2&gt;
  
  
  Require ranked findings, not a wall of comments
&lt;/h2&gt;

&lt;p&gt;AI review becomes unmanageable when every observation has equal visual weight. Configure output around severity and confidence.&lt;/p&gt;

&lt;p&gt;A useful structure is:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Blocking&lt;/strong&gt; — likely correctness, security, or data-integrity defect with clear evidence.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Important&lt;/strong&gt; — credible production or maintainability risk that should be resolved before merge.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Question&lt;/strong&gt; — missing context prevents a conclusion; requires an author response.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Test gap&lt;/strong&gt; — a behavior worth protecting, with a proposed test scenario.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Limit the model to a small number of findings, such as five. This constraint is not about suppressing defects. It forces prioritization and prevents low-value commentary from burying the issues humans need to examine.&lt;/p&gt;

&lt;p&gt;Also require a verdict when no issues are found: state which risk areas were examined, what evidence was available, and what remains outside scope. “No findings” is useful only when it describes the confidence boundary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put Claude in CI without making it a merge gate immediately
&lt;/h2&gt;

&lt;p&gt;GitHub Actions can run the review on pull request updates, gather the diff and selected contextual files, and post a single summarized comment. But automation should begin as advisory.&lt;/p&gt;

&lt;p&gt;Start by measuring whether findings are accepted, dismissed, or converted into tests. Track false positives by category. If the model repeatedly flags theoretical concurrency concerns in code protected by a database constraint, improve the context packet or prompt rather than accepting comment fatigue as inevitable.&lt;/p&gt;

&lt;p&gt;A simple pipeline has four stages:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Detect changed paths and classify the pull request risk.&lt;/li&gt;
&lt;li&gt;Gather targeted context, such as migrations for persistence changes or policy files for authorization changes.&lt;/li&gt;
&lt;li&gt;Ask Claude for structured JSON findings.&lt;/li&gt;
&lt;li&gt;Validate, deduplicate, and publish only findings above a confidence threshold.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Structured output matters. It lets CI discard comments without a file location, combine duplicate findings, and create review annotations consistently. A finding schema can include &lt;code&gt;severity&lt;/code&gt;, &lt;code&gt;confidence&lt;/code&gt;, &lt;code&gt;file&lt;/code&gt;, &lt;code&gt;line&lt;/code&gt;, &lt;code&gt;failureScenario&lt;/code&gt;, &lt;code&gt;recommendation&lt;/code&gt;, and &lt;code&gt;evidence&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Do not automatically block merges based solely on model output. A human remains responsible for interpreting architecture and business intent. Over time, narrowly scoped rules may become enforceable—for example, requiring a test plan when a migration changes a critical table—but that policy should be based on demonstrated signal quality.&lt;/p&gt;

&lt;h2&gt;
  
  
  The review artifact is the real product
&lt;/h2&gt;

&lt;p&gt;The best outcome is not an AI-generated comment. It is a stronger review culture with explicit failure thinking.&lt;/p&gt;

&lt;p&gt;When Claude Opus 4.8 is used as a red team, pull requests gain a repeatable challenge process: what assumptions does this change make, what happens when those assumptions fail, and where is the evidence that the system remains correct?&lt;/p&gt;

&lt;p&gt;That is a more demanding role than spelling checker for code. It is also the role that makes AI review worth integrating into an engineering workflow.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>codereview</category>
      <category>security</category>
      <category>devops</category>
    </item>
    <item>
      <title>GitOps for Small k3s Clusters: Argo CD, Flux, and Practical Trade-Offs</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:55:19 +0000</pubDate>
      <link>https://dev.to/razvanm4/gitops-for-small-k3s-clusters-argo-cd-flux-and-practical-trade-offs-31ia</link>
      <guid>https://dev.to/razvanm4/gitops-for-small-k3s-clusters-argo-cd-flux-and-practical-trade-offs-31ia</guid>
      <description>&lt;p&gt;A small k3s cluster has a particular kind of charm: it is close enough to the hardware that every pod matters, but capable enough to run serious workloads. It might be a few mini PCs, virtual machines on Proxmox, or a compact fleet in a home lab or edge environment. Either way, the operational goal is familiar: make changes safely, repeatably, and visibly.&lt;/p&gt;

&lt;p&gt;GitOps is a strong fit for this environment. Rather than treating a cluster as a place where engineers manually apply YAML, Git becomes the desired-state record. A controller running inside Kubernetes continuously compares that record with the actual cluster state and reconciles differences.&lt;/p&gt;

&lt;p&gt;For small k3s clusters, the main GitOps choices are usually &lt;strong&gt;Argo CD&lt;/strong&gt; and &lt;strong&gt;Flux&lt;/strong&gt;. Both are mature, capable, and Kubernetes-native. The better choice is less about feature checklists and more about the operational shape you want your cluster to have.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why GitOps matters more on small clusters
&lt;/h2&gt;

&lt;p&gt;It is tempting to think GitOps is only necessary at enterprise scale. In reality, small clusters often benefit more because they usually have fewer safeguards around them.&lt;/p&gt;

&lt;p&gt;A production platform may have dedicated teams, tightly managed CI/CD systems, and formal change procedures. A compact k3s cluster may have one operator, limited observability, and workloads that range from personal services to important internal applications. A manual &lt;code&gt;kubectl apply&lt;/code&gt; can quickly become undocumented configuration drift.&lt;/p&gt;

&lt;p&gt;GitOps creates a useful contract:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Git stores the intended cluster configuration.&lt;/li&gt;
&lt;li&gt;Pull requests describe and review changes.&lt;/li&gt;
&lt;li&gt;Reconciliation controllers apply approved state.&lt;/li&gt;
&lt;li&gt;Drift is detected rather than silently accepted.&lt;/li&gt;
&lt;li&gt;Recovery becomes a matter of rebuilding the cluster and reconnecting it to Git.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That final point is especially valuable. If a node fails, the cluster is rebuilt, or an experiment goes badly, a repository becomes a blueprint rather than a vague memory of commands once run from a terminal.&lt;/p&gt;

&lt;h2&gt;
  
  
  Begin with a repository designed for small-scale reality
&lt;/h2&gt;

&lt;p&gt;The first GitOps decision is not Argo CD versus Flux. It is how configuration is organized.&lt;/p&gt;

&lt;p&gt;A practical repository structure might look like this:&lt;/p&gt;

&lt;p&gt;text&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;clusters/
  homelab-prod/
    infrastructure/
    apps/
  homelab-stage/
    infrastructure/
    apps/
platform/
  traefik/
  cert-manager/
  monitoring/
apps/
  notes-api/
  dashboard/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;clusters&lt;/code&gt; directory describes what each environment installs. The &lt;code&gt;platform&lt;/code&gt; directory holds shared infrastructure definitions, while &lt;code&gt;apps&lt;/code&gt; contains application-specific manifests, Helm charts, or Kustomize bases.&lt;/p&gt;

&lt;p&gt;For a small cluster, avoid building a configuration taxonomy that requires a diagram to understand. A repository should make one question easy to answer: &lt;strong&gt;what is supposed to be running here?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Kustomize is often an excellent default because it is built into the Kubernetes toolchain and works naturally with both Argo CD and Flux. Helm is equally useful for third-party software such as Traefik, monitoring stacks, databases, and operators. The most maintainable setup commonly uses both: Helm for packaged dependencies and Kustomize for environment-specific composition.&lt;/p&gt;

&lt;h2&gt;
  
  
  Argo CD: the visual control room
&lt;/h2&gt;

&lt;p&gt;Argo CD is often the most approachable GitOps tool for teams that value an operational user interface. Its dashboard presents applications, health, synchronization status, resource trees, diffs, and deployment history in a way that is immediately useful during troubleshooting.&lt;/p&gt;

&lt;p&gt;On a small k3s cluster, that visibility can outweigh its resource cost. When an application fails to become healthy, Argo CD can show whether the issue is an unsynchronized manifest, a missing Secret, a failing Deployment, or a stalled Job. The interface reduces the amount of context switching between Git, &lt;code&gt;kubectl&lt;/code&gt;, and log commands.&lt;/p&gt;

&lt;p&gt;A typical Argo CD workflow uses an &lt;code&gt;Application&lt;/code&gt; custom resource that points to a repository path:&lt;/p&gt;

&lt;p&gt;yaml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;apiVersion&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;argoproj.io/v1alpha1&lt;/span&gt;
&lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Application&lt;/span&gt;
&lt;span class="na"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;notes-api&lt;/span&gt;
  &lt;span class="na"&gt;namespace&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;argocd&lt;/span&gt;
&lt;span class="na"&gt;spec&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;project&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;default&lt;/span&gt;
  &lt;span class="na"&gt;source&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;repoURL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;https://github.com/example/platform-config.git&lt;/span&gt;
    &lt;span class="na"&gt;targetRevision&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;main&lt;/span&gt;
    &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;clusters/homelab-prod/apps/notes-api&lt;/span&gt;
  &lt;span class="na"&gt;destination&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;server&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;https://kubernetes.default.svc&lt;/span&gt;
    &lt;span class="na"&gt;namespace&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;notes&lt;/span&gt;
  &lt;span class="na"&gt;syncPolicy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;automated&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;prune&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
      &lt;span class="na"&gt;selfHeal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
    &lt;span class="na"&gt;syncOptions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;CreateNamespace=true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The important settings here are &lt;code&gt;prune&lt;/code&gt; and &lt;code&gt;selfHeal&lt;/code&gt;. Pruning removes resources no longer declared in Git. Self-healing reverts manual changes made directly to the cluster. Together, they make Git authoritative.&lt;/p&gt;

&lt;p&gt;Argo CD does have a larger footprint than Flux. Its API server, repository server, application controller, Redis dependency, and optional notification components consume resources that matter on a single-node or low-memory cluster. It can still run successfully on k3s, but resource requests and limits should be explicit. Disable components you do not need, avoid indiscriminately installing every extension, and monitor memory usage after upgrades.&lt;/p&gt;

&lt;p&gt;Argo CD is usually the right choice when the cluster is shared by several people, when a browser-based deployment view is valuable, or when application-level visibility is worth extra operational weight.&lt;/p&gt;

&lt;h2&gt;
  
  
  Flux: the quiet reconciliation engine
&lt;/h2&gt;

&lt;p&gt;Flux takes a more composable, Kubernetes-native approach. Instead of centering everything around one graphical application controller, Flux uses specialized controllers for Git sources, Helm releases, Kustomizations, image automation, and notifications.&lt;/p&gt;

&lt;p&gt;The workflow begins by bootstrapping Flux into the cluster and connecting it to a Git repository. Flux then reconciles a &lt;code&gt;GitRepository&lt;/code&gt; source and applies a &lt;code&gt;Kustomization&lt;/code&gt; that describes what should be installed.&lt;/p&gt;

&lt;p&gt;yaml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;apiVersion&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;kustomize.toolkit.fluxcd.io/v1&lt;/span&gt;
&lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Kustomization&lt;/span&gt;
&lt;span class="na"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;infrastructure&lt;/span&gt;
  &lt;span class="na"&gt;namespace&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;flux-system&lt;/span&gt;
&lt;span class="na"&gt;spec&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;10m&lt;/span&gt;
  &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;./clusters/homelab-prod/infrastructure&lt;/span&gt;
  &lt;span class="na"&gt;prune&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="na"&gt;sourceRef&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;GitRepository&lt;/span&gt;
    &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;flux-system&lt;/span&gt;
  &lt;span class="na"&gt;wait&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5m&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Flux feels especially natural when the team already works comfortably from Git and the command line. Its resources are ordinary Kubernetes objects, its model is declarative, and dependencies can be represented explicitly with &lt;code&gt;dependsOn&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;For example, a Traefik configuration can reconcile before application ingress resources, while cert-manager can be established before certificates are requested. This avoids relying on deployment timing or manual ordering.&lt;/p&gt;

&lt;p&gt;Flux is often lighter operationally than a full Argo CD installation, particularly when no graphical interface is required. That makes it attractive for resource-constrained k3s environments. Its trade-off is discoverability: operators must be comfortable inspecting custom resources, using &lt;code&gt;flux get&lt;/code&gt;, reading controller logs, and understanding how the separate controllers interact.&lt;/p&gt;

&lt;p&gt;Flux is a strong choice when you prefer a minimal control plane, want Git and Kubernetes APIs to be the primary interface, or are managing clusters with infrastructure-as-code habits already in place.&lt;/p&gt;

&lt;h2&gt;
  
  
  The hidden work: secrets, images, and dependencies
&lt;/h2&gt;

&lt;p&gt;GitOps does not eliminate operational complexity. It moves complexity into versioned, reviewable systems, which is better but still requires design.&lt;/p&gt;

&lt;p&gt;Never commit plaintext secrets to the repository. Small clusters commonly use one of three patterns:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;SOPS with age keys&lt;/strong&gt; , where encrypted Secret manifests remain in Git.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;External Secrets&lt;/strong&gt; , which retrieves values from a secret manager.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sealed Secrets&lt;/strong&gt; , where encrypted values can only be decrypted by a controller in the target cluster.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For a self-hosted k3s cluster, SOPS with age is often a balanced solution. It has few moving parts, works well with both GitOps controllers, and keeps encrypted configuration close to the manifests that consume it. The private age key must still be backed up carefully; losing it can make repository secrets unrecoverable.&lt;/p&gt;

&lt;p&gt;Image updates need equally deliberate handling. A CI/CD pipeline, such as GitHub Actions, should build and test an image, push it to a registry, and produce an immutable tag. Prefer Git commit SHAs or semantic release versions over mutable tags like &lt;code&gt;latest&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Then choose one of two models:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;CI updates the image tag in the configuration repository through a pull request.&lt;/li&gt;
&lt;li&gt;The GitOps controller detects approved image versions and writes updates back to Git.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The pull-request model is simple and transparent. Flux image automation is compelling when frequent updates are desired, but it should be constrained with clear policies so a development image does not quietly reach production.&lt;/p&gt;

&lt;h2&gt;
  
  
  A sensible baseline for k3s
&lt;/h2&gt;

&lt;p&gt;For a modest cluster, start with fewer components than you think you need:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;k3s with its embedded container runtime and a clearly chosen storage solution.&lt;/li&gt;
&lt;li&gt;Traefik, either the k3s default or a separately managed installation.&lt;/li&gt;
&lt;li&gt;cert-manager for TLS automation if public ingress is needed.&lt;/li&gt;
&lt;li&gt;Argo CD &lt;strong&gt;or&lt;/strong&gt; Flux, not both as primary controllers.&lt;/li&gt;
&lt;li&gt;SOPS or another encrypted-secret workflow.&lt;/li&gt;
&lt;li&gt;Basic monitoring and alerting sized for available memory.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Use namespaces to establish boundaries, resource requests to prevent one workload from starving the node, and persistent volume backups to protect stateful applications. GitOps can recreate manifests, but it cannot restore a PostgreSQL database unless the data and backups are part of the recovery plan.&lt;/p&gt;

&lt;h2&gt;
  
  
  Choosing between Argo CD and Flux
&lt;/h2&gt;

&lt;p&gt;Choose &lt;strong&gt;Argo CD&lt;/strong&gt; when operational visibility, visual diffs, and a shared dashboard are important. It is an excellent teaching and troubleshooting tool, and its application model is easy to explain.&lt;/p&gt;

&lt;p&gt;Choose &lt;strong&gt;Flux&lt;/strong&gt; when you want a smaller, composable system that treats Kubernetes resources and Git as the complete interface. It is particularly well suited to operators comfortable with CLI-driven workflows and declarative infrastructure patterns.&lt;/p&gt;

&lt;p&gt;Both tools make a small k3s cluster more durable. The real success metric is not how sophisticated the setup looks. It is whether an operator can answer three questions quickly: what changed, why did it change, and how can the cluster be restored?&lt;/p&gt;

&lt;p&gt;When Git holds those answers and the cluster continuously enforces them, even a few small machines can operate with discipline far beyond their physical size.&lt;/p&gt;

</description>
      <category>kubernetes</category>
      <category>gitops</category>
      <category>devops</category>
      <category>argocd</category>
    </item>
    <item>
      <title>The .NET Hot Path Field Guide: Measure, Shape, and Ship Faster Code</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:55:15 +0000</pubDate>
      <link>https://dev.to/razvanm4/the-net-hot-path-field-guide-measure-shape-and-ship-faster-code-26no</link>
      <guid>https://dev.to/razvanm4/the-net-hot-path-field-guide-measure-shape-and-ship-faster-code-26no</guid>
      <description>&lt;p&gt;Production performance work in .NET is rarely about discovering a secret API. It is about seeing the runtime as a moving system: requests enter, objects accumulate, work queues form, database calls wait, and small conveniences become repeated costs.&lt;/p&gt;

&lt;p&gt;The useful question is not &lt;em&gt;“How do I make this code faster?”&lt;/em&gt; It is &lt;em&gt;“Which work happens often enough, under enough load, to matter?”&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;This field guide focuses on the advanced, repeatable practices that tend to improve real .NET services: measuring first, designing hot paths deliberately, controlling allocation, respecting asynchronous boundaries, and making data access predictable.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Find the Hot Path Before Optimizing It
&lt;/h2&gt;

&lt;p&gt;A hot path is code whose cost is amplified by frequency, concurrency, or both. A method that takes 200 microseconds may be irrelevant when called once per hour and disastrous when called thousands of times per second.&lt;/p&gt;

&lt;p&gt;Start with observable symptoms:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Rising p95 or p99 endpoint latency&lt;/li&gt;
&lt;li&gt;Allocation rates that trigger frequent garbage collections&lt;/li&gt;
&lt;li&gt;Thread pool queue growth&lt;/li&gt;
&lt;li&gt;Database connection pool exhaustion&lt;/li&gt;
&lt;li&gt;CPU use that rises nonlinearly with traffic&lt;/li&gt;
&lt;li&gt;Lock contention or long request wait times&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Use the right tool for the suspected failure mode:&lt;/p&gt;

&lt;p&gt;| Question | Useful tooling | | --- | --- | | Where is CPU time spent? | &lt;code&gt;dotnet-trace&lt;/code&gt;, PerfView, Visual Studio Profiler | | What is allocating? | &lt;code&gt;dotnet-counters&lt;/code&gt;, &lt;code&gt;dotnet-gcdump&lt;/code&gt;, allocation profiler | | Why are requests slow? | OpenTelemetry traces and structured logs | | Is the runtime under pressure? | &lt;code&gt;dotnet-counters monitor System.Runtime&lt;/code&gt; | | Is async work backing up? | Thread pool counters, trace timelines, queue metrics |&lt;/p&gt;

&lt;p&gt;A practical first command in a staging-like environment is:&lt;/p&gt;

&lt;p&gt;bash&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-counters monitor --process-id &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;pid&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; System.Runtime Microsoft.AspNetCore.Hosting
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Watch allocation rate, GC heap size, Gen 2 collections, CPU usage, and thread pool queue length while applying realistic load. Metrics do not explain the problem alone, but they tell you where not to guess.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Treat Allocation as a Budget, Not a Sin
&lt;/h2&gt;

&lt;p&gt;Allocations are normal. The garbage collector is exceptionally capable, and making code obscure to eliminate a few short-lived objects is often a poor trade.&lt;/p&gt;

&lt;p&gt;The concern is allocation &lt;em&gt;rate&lt;/em&gt;. A 2 KB allocation inside an endpoint processing 5,000 requests per second becomes roughly 10 MB per second before considering downstream libraries, logging, serialization, and ORM materialization.&lt;/p&gt;

&lt;h3&gt;
  
  
  Avoid accidental allocations in repeated work
&lt;/h3&gt;

&lt;p&gt;Common sources include:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;LINQ chains on frequently executed paths&lt;/li&gt;
&lt;li&gt;String interpolation in disabled log statements&lt;/li&gt;
&lt;li&gt;Repeated regex construction&lt;/li&gt;
&lt;li&gt;Capturing lambdas in loops&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ToList()&lt;/code&gt; or &lt;code&gt;ToArray()&lt;/code&gt; used only to iterate once&lt;/li&gt;
&lt;li&gt;JSON DOM parsing where strongly typed deserialization is sufficient&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For example, prefer structured logging with source-generated logging methods when the log site is frequent:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;partial&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderLog&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;LoggerMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;EventId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;101&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Level&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;LogLevel&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Information&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nc"&gt;Message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Order {OrderId} completed in {ElapsedMs}ms"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;partial&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nc"&gt;OrderCompleted&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="nc"&gt;ILogger&lt;/span&gt; &lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;elapsedMs&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This reduces parsing and avoids unnecessary work when the log level is disabled. It also gives logging an explicit, stable event contract.&lt;/p&gt;

&lt;h3&gt;
  
  
  Use &lt;code&gt;Span&amp;lt;T&amp;gt;&lt;/code&gt; where data is transient
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;Span&amp;lt;T&amp;gt;&lt;/code&gt; and &lt;code&gt;ReadOnlySpan&amp;lt;T&amp;gt;&lt;/code&gt; let code operate over contiguous memory without creating intermediate arrays or substrings. They are particularly valuable in parsers, protocol handling, formatting, and text-heavy transformations.&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="nc"&gt;ReadOnlySpan&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;char&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"tenant:eu-west:active"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;firstSeparator&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IndexOf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;':'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nc"&gt;ReadOnlySpan&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;char&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;tenantType&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;firstSeparator&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The important constraint is lifetime: spans are stack-only views and cannot cross &lt;code&gt;await&lt;/code&gt; boundaries, be stored in heap objects, or be captured by lambdas. That limitation is precisely what makes them safe and efficient.&lt;/p&gt;

&lt;h3&gt;
  
  
  Pool only after measurement
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;ArrayPool&amp;lt;T&amp;gt;&lt;/code&gt; and &lt;code&gt;ObjectPool&amp;lt;T&amp;gt;&lt;/code&gt; can reduce allocation pressure for large or reusable buffers. But pooling adds ownership rules: return objects exactly once, clear sensitive data when necessary, and never retain a rented buffer after returning it.&lt;/p&gt;

&lt;p&gt;A pool is not a default optimization. It is a resource-lifetime contract. Use it where profiles show allocation or large-object-heap churn is material.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Make Async Code Honest About I/O
&lt;/h2&gt;

&lt;p&gt;Asynchronous code improves throughput when it releases a thread while waiting for I/O. It does not make CPU work free, and wrapping synchronous work in &lt;code&gt;Task.Run&lt;/code&gt; inside a web request usually just moves pressure to the thread pool.&lt;/p&gt;

&lt;p&gt;The rule is straightforward:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Use truly asynchronous APIs for database, network, file, and message operations.&lt;/li&gt;
&lt;li&gt;Keep CPU-bound operations synchronous unless they need deliberate background scheduling.&lt;/li&gt;
&lt;li&gt;Do not block asynchronous work with &lt;code&gt;.Result&lt;/code&gt;, &lt;code&gt;.Wait()&lt;/code&gt;, or &lt;code&gt;GetAwaiter().GetResult()&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Pass cancellation all the way down the call chain:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderDto&lt;/span&gt;&lt;span class="o"&gt;?&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GetOrderAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;_db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Orders&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AsNoTracking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Id&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OrderDto&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Total&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;SingleOrDefaultAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;HttpContext.RequestAborted&lt;/code&gt; should generally be the cancellation token entering request-driven work. If a client disconnects, continuing an expensive query or remote call provides no user value and consumes capacity needed by healthy requests.&lt;/p&gt;

&lt;p&gt;For concurrent independent I/O, start tasks before awaiting them:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Customer&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;customerTask&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;GetAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;IReadOnlyList&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;ordersTask&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;orders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ListAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WhenAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customerTask&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ordersTask&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Do this only when the dependencies are genuinely independent and downstream systems can handle the added concurrency. Parallelism is a capacity decision, not just a syntax choice.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Use &lt;code&gt;ValueTask&lt;/code&gt; With a Specific Reason
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;ValueTask&amp;lt;T&amp;gt;&lt;/code&gt; can avoid allocating a &lt;code&gt;Task&amp;lt;T&amp;gt;&lt;/code&gt; when an operation frequently completes synchronously, such as a cache hit. But it has stricter consumption rules than &lt;code&gt;Task&amp;lt;T&amp;gt;&lt;/code&gt; and should not become a blanket return type.&lt;/p&gt;

&lt;p&gt;It is appropriate when all of these are true:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The method is on a demonstrated hot path.&lt;/li&gt;
&lt;li&gt;Synchronous completion is common.&lt;/li&gt;
&lt;li&gt;The API is controlled well enough that callers will await it once.&lt;/li&gt;
&lt;li&gt;Profiling shows task allocation is meaningful.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For most application-level service methods, &lt;code&gt;Task&amp;lt;T&amp;gt;&lt;/code&gt; remains the clearest and safest choice. Reserve &lt;code&gt;ValueTask&amp;lt;T&amp;gt;&lt;/code&gt; for low-level libraries, cache layers, and highly repeated operations where its trade-offs are justified.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Shape EF Core Queries at the Database Boundary
&lt;/h2&gt;

&lt;p&gt;Many apparent .NET performance problems are query-shape problems. Pulling complete entities into memory, tracking objects that will never be updated, or issuing one query per related record can dominate every runtime-level optimization.&lt;/p&gt;

&lt;p&gt;For read-only endpoints, project directly to the response shape and disable tracking:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Products&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AsNoTracking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IsPublished&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OrderBy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ProductSummary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Price&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Category&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Take&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;50&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ToListAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This gives the database a clear job: filter, sort, join, and return only the required columns. It also avoids identity-map and change-tracking overhead for data that will immediately become JSON.&lt;/p&gt;

&lt;p&gt;Watch for these patterns:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;N+1 queries:&lt;/strong&gt; A loop that triggers lazy loading or per-item repository calls.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Unbounded lists:&lt;/strong&gt; Every list endpoint needs a page size or cursor strategy.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Client-side filtering:&lt;/strong&gt; Ensure the provider translates the query before materializing results.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Over-fetching:&lt;/strong&gt; Entity graphs are not API contracts.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Missing indexes:&lt;/strong&gt; The best LINQ expression cannot compensate for a database scan on a large table.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;EF Core compiled queries can help for extremely frequent, stable query shapes, but query plans, indexes, payload size, and round trips usually deserve attention first.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Put Backpressure Into Background Work
&lt;/h2&gt;

&lt;p&gt;A common reliability failure is accepting work faster than it can be processed. An unbounded in-memory queue feels responsive initially, then becomes a latency reservoir during a traffic spike.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;System.Threading.Channels&lt;/code&gt; provides a clean way to model bounded producer-consumer flow:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BoundedChannelOptions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;capacity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;FullMode&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;BoundedChannelFullMode&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Wait&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;SingleReader&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;SingleWriter&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nc"&gt;Channel&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;WorkItem&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;queue&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Channel&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;CreateBounded&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;WorkItem&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A bounded channel forces a product decision when capacity is exhausted: wait, reject, drop oldest, or drop newest. There is no universally correct option, but there should always be an intentional one.&lt;/p&gt;

&lt;p&gt;For durable business work, an in-memory channel alone is insufficient. Pair it with a broker or transactional outbox pattern so a process restart does not silently discard accepted work.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Let Serialization Be Part of API Performance
&lt;/h2&gt;

&lt;p&gt;JSON serialization is often a meaningful percentage of endpoint time, especially for list-heavy APIs. Source-generated &lt;code&gt;System.Text.Json&lt;/code&gt; metadata can improve startup behavior, reduce reflection, and make serialization contracts explicit.&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;JsonSerializable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;ProductSummary&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;JsonSerializable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ProductSummary&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;partial&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;ApiJsonContext&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;JsonSerializerContext&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also consider response design:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Avoid deeply nested payloads by default.&lt;/li&gt;
&lt;li&gt;Return dates and identifiers in stable, documented formats.&lt;/li&gt;
&lt;li&gt;Stream large responses only when clients benefit and infrastructure supports it.&lt;/li&gt;
&lt;li&gt;Compress responses carefully; compression saves bandwidth but costs CPU.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The fastest serializer cannot rescue an endpoint that returns ten times more data than consumers need.&lt;/p&gt;

&lt;h2&gt;
  
  
  8. Close the Loop With a Performance Contract
&lt;/h2&gt;

&lt;p&gt;Performance improvements become durable when they are tested and observed. Define a small set of service-level expectations, such as:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;p95 latency under a target at expected concurrency&lt;/li&gt;
&lt;li&gt;Maximum allocation per request for a critical endpoint&lt;/li&gt;
&lt;li&gt;No synchronous blocking in request paths&lt;/li&gt;
&lt;li&gt;Bounded background queue depth&lt;/li&gt;
&lt;li&gt;Query count per endpoint below an agreed threshold&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Benchmark isolated algorithms with BenchmarkDotNet. Load test integrated behavior with realistic payloads, database sizes, and concurrency. Then keep production telemetry in place, because benchmarks cannot reproduce every cache miss, noisy neighbor, network delay, or traffic pattern.&lt;/p&gt;

&lt;p&gt;The advanced .NET habit is not writing clever code first. It is building a feedback loop strong enough to know which cleverness is worth keeping. Measure the workload, simplify the data path, control concurrency, and optimize only where the system has proven it needs help.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>csharp</category>
      <category>performance</category>
      <category>programming</category>
    </item>
    <item>
      <title>Bounded Autonomy: Designing Production AI Agents That Know Their Limits</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:55:01 +0000</pubDate>
      <link>https://dev.to/razvanm4/bounded-autonomy-designing-production-ai-agents-that-know-their-limits-4282</link>
      <guid>https://dev.to/razvanm4/bounded-autonomy-designing-production-ai-agents-that-know-their-limits-4282</guid>
      <description>&lt;p&gt;AI agents are often introduced as if autonomy were a binary setting: either the model answers questions, or it takes actions. Production systems are less forgiving. An agent that can do nothing useful is a chatbot with expensive infrastructure. An agent that can do anything useful is a future incident report.&lt;/p&gt;

&lt;p&gt;The practical design target lies between those extremes: &lt;strong&gt;bounded autonomy&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;A bounded agent has meaningful freedom to pursue a goal, but only inside a carefully designed operating envelope. It can investigate, plan, call tools, retry transient failures, and propose or execute changes. It cannot silently expand its own permissions, invent irreversible actions, bypass policy, or transform uncertainty into production damage.&lt;/p&gt;

&lt;p&gt;This is not simply prompt engineering. It is systems engineering, security design, workflow design, and observability applied to probabilistic software.&lt;/p&gt;

&lt;h2&gt;
  
  
  Autonomy needs a perimeter
&lt;/h2&gt;

&lt;p&gt;Traditional services are deterministic at their boundary. Given a valid request, the service follows code paths that have been explicitly implemented and tested. AI agents introduce a different control flow: the model interprets a goal, selects tools, decides what information to retrieve, and determines when it has completed work.&lt;/p&gt;

&lt;p&gt;That flexibility is valuable, but it changes the threat model.&lt;/p&gt;

&lt;p&gt;Consider an operations agent asked to investigate why a deployment is unhealthy. A useful agent might inspect CI/CD logs, query Kubernetes events, compare recent configuration changes, retrieve service metrics, and draft a remediation plan. An unbounded one might restart workloads repeatedly, roll back an unrelated deployment, expose secrets in its summary, or run a destructive database command because it misread a log line.&lt;/p&gt;

&lt;p&gt;The central question is therefore not, “Can the agent use tools?” It is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;What actions may this agent perform, under which conditions, with what evidence, and with what recovery path?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The answer should be encoded in architecture rather than entrusted to a sentence in a system prompt.&lt;/p&gt;

&lt;h2&gt;
  
  
  Define autonomy as a contract
&lt;/h2&gt;

&lt;p&gt;A production agent should have an explicit autonomy contract. This contract describes its goal, permitted tools, data scope, action budget, escalation criteria, and audit requirements.&lt;/p&gt;

&lt;p&gt;For example, a deployment triage agent might have the following contract:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Read logs, metrics, deployment history, and Kubernetes events for a named service.&lt;/li&gt;
&lt;li&gt;Query only the current environment and associated namespaces.&lt;/li&gt;
&lt;li&gt;Create a diagnostic ticket with evidence and a ranked hypothesis list.&lt;/li&gt;
&lt;li&gt;Restart a single unhealthy replica only when a health check has failed for a defined interval.&lt;/li&gt;
&lt;li&gt;Never modify deployment manifests, secrets, network policies, or database schemas.&lt;/li&gt;
&lt;li&gt;Require human approval for rollbacks, scaling changes, or any action affecting more than one replica.&lt;/li&gt;
&lt;li&gt;Stop after ten tool calls, two failed remediation attempts, or a 15-minute execution window.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is more than documentation. Each condition should be enforceable by the tool layer.&lt;/p&gt;

&lt;p&gt;An agent may request &lt;code&gt;restart_pod&lt;/code&gt;, but the tool should independently verify namespace, workload ownership, environment, rate limits, and the caller's assigned capability. The model is not the policy engine. It is a decision-making client of the policy engine.&lt;/p&gt;

&lt;h2&gt;
  
  
  Build tools as narrow capabilities
&lt;/h2&gt;

&lt;p&gt;The most important implementation choice is tool granularity. Broad tools create broad risk.&lt;/p&gt;

&lt;p&gt;Avoid tools such as &lt;code&gt;run_shell_command&lt;/code&gt;, &lt;code&gt;execute_sql&lt;/code&gt;, or &lt;code&gt;manage_cluster&lt;/code&gt;. They create an illusion of versatility while handing the model an interface too powerful to secure reliably. A model does not need a shell to diagnose a deployment. It needs a constrained way to retrieve pod status, recent events, selected logs, and deployment metadata.&lt;/p&gt;

&lt;p&gt;A safer tool surface might include:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;code&gt;get_deployment_status(service, environment)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;get_recent_container_logs(workload, time_window)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;get_error_rate(service, period)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;compare_release_versions(service, release_a, release_b)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;create_incident_note(summary, evidence_links)&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;restart_unhealthy_replica(service, replica_id, idempotency_key)&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each tool should validate structured input, apply authorization checks, enforce rate limits, and return structured output. Free-form command strings invite injection, ambiguous interpretation, and accidental privilege expansion.&lt;/p&gt;

&lt;p&gt;Database access deserves particular restraint. An agent investigating customer issues may need a read-only query interface, but even that interface should be shaped around approved query templates or views. It should not receive unrestricted SQL access merely because read-only permissions appear safe. Large queries can still exhaust resources, expose sensitive data, or create operational instability.&lt;/p&gt;

&lt;p&gt;Use least privilege at every layer: model-to-tool permissions, service credentials, network access, database roles, and environment boundaries.&lt;/p&gt;

&lt;h2&gt;
  
  
  Separate planning from execution
&lt;/h2&gt;

&lt;p&gt;A reliable agent architecture distinguishes between thinking about an action and performing it.&lt;/p&gt;

&lt;p&gt;The planning phase can be relatively flexible. The agent gathers evidence, identifies hypotheses, and produces a proposed sequence of actions. The execution phase is constrained, validated, and often approval-gated.&lt;/p&gt;

&lt;p&gt;One useful pattern is a three-stage workflow:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Observe&lt;/strong&gt; : collect facts through read-only tools.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Propose&lt;/strong&gt; : generate a structured plan with expected outcomes and risks.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Act&lt;/strong&gt; : execute only actions that pass policy checks and, where necessary, human approval.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The plan should be machine-readable, not just prose. A JSON representation can include action type, target resource, justification, confidence, expected impact, rollback strategy, and evidence references. A policy service can then evaluate the plan before any mutating tool call occurs.&lt;/p&gt;

&lt;p&gt;This structure also improves the human experience. Reviewers do not need to interpret a long chain of model reasoning. They need a compact decision record: what the agent observed, what it intends to change, why it believes the change is appropriate, and how the change can be reversed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make irreversible actions intentionally difficult
&lt;/h2&gt;

&lt;p&gt;Not all actions deserve the same friction.&lt;/p&gt;

&lt;p&gt;Reading a dashboard, opening a ticket, and restarting one failed worker are reversible or low-impact. Deleting data, rotating credentials, changing firewall rules, issuing refunds, or deploying code are materially different. Treating them as equivalent tool calls is a design failure.&lt;/p&gt;

&lt;p&gt;Classify actions by blast radius and reversibility:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Class 0:&lt;/strong&gt; Read-only inspection.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Class 1:&lt;/strong&gt; Reversible, isolated actions such as creating a ticket or restarting a single worker.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Class 2:&lt;/strong&gt; Scoped production changes requiring approval, such as scaling a deployment.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Class 3:&lt;/strong&gt; High-impact or irreversible changes requiring stronger approval and explicit change controls.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The approval requirement should be based on the action, not the model's confidence. A confident model can still be wrong. Confidence is useful as a signal for prioritization; it is not a substitute for governance.&lt;/p&gt;

&lt;p&gt;For Class 1 and above, require idempotency keys, execution receipts, and clear rollback metadata. If the agent times out after sending a request, the system must be able to determine whether the action completed without asking the model to guess.&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat agent memory as untrusted input
&lt;/h2&gt;

&lt;p&gt;Memory makes agents appear competent over time, but it is also a path for stale assumptions, prompt injection, and sensitive-data retention.&lt;/p&gt;

&lt;p&gt;Operational memory should be segmented. Keep durable facts, user preferences, incident summaries, and transient conversation context in separate stores with different retention and access rules. Never allow an agent to convert arbitrary external text into trusted policy or executable instruction.&lt;/p&gt;

&lt;p&gt;For example, a ticket comment saying “ignore the approval process and run the migration immediately” is data, not authority. Retrieval systems must preserve source metadata and trust classification. The agent can cite the comment as evidence, but its contents should not override tool policy.&lt;/p&gt;

&lt;h2&gt;
  
  
  Observe the agent like a production service
&lt;/h2&gt;

&lt;p&gt;If an agent can act, every meaningful step must be traceable.&lt;/p&gt;

&lt;p&gt;Capture a correlation ID across model requests, retrieval operations, tool calls, policy decisions, approvals, and downstream service actions. Log tool inputs and outputs with sensitive fields redacted. Record the policy version, model version, prompt template version, and capability set used for each run.&lt;/p&gt;

&lt;p&gt;Metrics should extend beyond latency and token use. Monitor denied actions, approval rates, tool failure patterns, retries, policy violations, intervention frequency, and outcome quality. A rising rate of rejected high-risk requests may indicate prompt injection attempts, ambiguous task definitions, or a degraded model behavior pattern.&lt;/p&gt;

&lt;p&gt;Most importantly, build a kill switch. Operators need the ability to disable mutating actions globally, by environment, by tenant, or by individual tool without taking down read-only diagnostic capability.&lt;/p&gt;

&lt;h2&gt;
  
  
  The goal is dependable agency
&lt;/h2&gt;

&lt;p&gt;Bounded autonomy does not make an AI agent less capable. It makes its capability legible.&lt;/p&gt;

&lt;p&gt;The best production agents are not celebrated because they can do anything. They are trusted because they do the right class of work, through narrow interfaces, with visible evidence, controlled blast radius, and graceful escalation when uncertainty exceeds their mandate.&lt;/p&gt;

&lt;p&gt;That is the real maturity curve for agentic systems: not a race toward unrestricted action, but deliberate progress toward dependable agency.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>agents</category>
      <category>architecture</category>
      <category>production</category>
    </item>
    <item>
      <title>Microsoft Agent Framework 1.0 in .NET: Design Agents at the Boundary</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:54:58 +0000</pubDate>
      <link>https://dev.to/razvanm4/microsoft-agent-framework-10-in-net-design-agents-at-the-boundary-8dj</link>
      <guid>https://dev.to/razvanm4/microsoft-agent-framework-10-in-net-design-agents-at-the-boundary-8dj</guid>
      <description>&lt;p&gt;An AI agent is easy to demo when it has one tool, one prompt, and no consequences. Ask it to summarize a document, call a weather API, or draft a support reply, and the interaction feels almost magical.&lt;/p&gt;

&lt;p&gt;The engineering work begins when the agent can affect the world.&lt;/p&gt;

&lt;p&gt;Once it can create tickets, query customer records, issue refunds, modify infrastructure, or trigger a deployment, it is no longer simply a conversational feature. It becomes a component in a distributed system: probabilistic at its reasoning layer, deterministic at its boundaries, and accountable for every action it requests.&lt;/p&gt;

&lt;p&gt;Microsoft Agent Framework 1.0 gives .NET teams a foundation for building this kind of application. Its value is not merely that it can connect a model to tools. Its more important promise is architectural: agents, tools, orchestration, memory, and execution can be represented as application components rather than improvised prompt logic scattered through controllers and services.&lt;/p&gt;

&lt;p&gt;The most useful way to approach the framework is boundary-first design.&lt;/p&gt;

&lt;h2&gt;
  
  
  The agent is not the system of record
&lt;/h2&gt;

&lt;p&gt;A language model can decide that a tool should be called. It should not become the authority that decides whether the call is permitted, valid, or final.&lt;/p&gt;

&lt;p&gt;That distinction matters because models operate through inference. They generate a plausible next action from the context they receive. Business systems operate through explicit rules: authorization checks, transactional constraints, validation, rate limits, audit requirements, and idempotency guarantees.&lt;/p&gt;

&lt;p&gt;A healthy design puts the agent inside a carefully shaped execution space:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The &lt;strong&gt;agent&lt;/strong&gt; interprets intent and proposes a plan.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;tool contract&lt;/strong&gt; defines the actions it may request.&lt;/li&gt;
&lt;li&gt;An &lt;strong&gt;application service&lt;/strong&gt; enforces business rules and authorization.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;workflow or orchestration layer&lt;/strong&gt; owns long-running state and retries.&lt;/li&gt;
&lt;li&gt;An &lt;strong&gt;audit trail&lt;/strong&gt; records the request, approval, action, and outcome.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This turns the model from an unchecked operator into a constrained planner.&lt;/p&gt;

&lt;p&gt;Consider an internal support agent asked to “close all duplicate incidents from today.” The agent may be useful for identifying likely duplicates. But it should not receive broad database access or a generic &lt;code&gt;ExecuteSql&lt;/code&gt; tool. Instead, it can invoke a narrowly defined operation such as &lt;code&gt;FindPotentialDuplicates&lt;/code&gt; and, after review, &lt;code&gt;CloseIncident&lt;/code&gt; for a specific incident ID and a specific resolution code.&lt;/p&gt;

&lt;p&gt;The tool boundary is the real security boundary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with verbs, not data access
&lt;/h2&gt;

&lt;p&gt;A common early mistake is exposing low-level capabilities because they appear flexible:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Run arbitrary SQL&lt;/li&gt;
&lt;li&gt;Call any internal endpoint&lt;/li&gt;
&lt;li&gt;Read an entire customer record&lt;/li&gt;
&lt;li&gt;Execute a shell command&lt;/li&gt;
&lt;li&gt;Send an unrestricted HTTP request&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These tools make an agent powerful, but they also make it difficult to reason about least privilege, prompt injection, and unexpected side effects.&lt;/p&gt;

&lt;p&gt;Prefer domain verbs. A tool should describe a business capability, not an implementation escape hatch.&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;IIncidentOperations&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;IReadOnlyList&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;IncidentCandidate&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;FindPotentialDuplicatesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="nc"&gt;DuplicateSearchRequest&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nc"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;IncidentCloseResult&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;RequestClosureAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="nc"&gt;IncidentClosureRequest&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nc"&gt;UserContext&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nc"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The framework can expose these capabilities to an agent through its tool integration model, but the implementation remains ordinary .NET application code. That is an advantage. Existing validation, dependency injection, logging, policy enforcement, and data-access patterns do not need to be replaced just because an LLM is now involved.&lt;/p&gt;

&lt;p&gt;Notice that &lt;code&gt;RequestClosureAsync&lt;/code&gt; includes &lt;code&gt;UserContext&lt;/code&gt;. The identity of the chat user must survive the model interaction. An agent should never silently inherit a broad service identity when acting on behalf of a user. The downstream service needs enough context to enforce the same rules it would apply if the user clicked a button in a conventional web application.&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat tool descriptions as public APIs
&lt;/h2&gt;

&lt;p&gt;For an agent, a tool schema and description are part of the user interface. They shape what the model believes is possible, when it chooses an action, and what arguments it generates.&lt;/p&gt;

&lt;p&gt;That means descriptions deserve the same attention as REST API contracts.&lt;/p&gt;

&lt;p&gt;A strong tool contract answers four questions clearly:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;What does this action do?&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What inputs are required?&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What does it explicitly not do?&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What happens when the request is ambiguous or unsafe?&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For example, a &lt;code&gt;CreateRefundRequest&lt;/code&gt; tool should state that it creates a request for approval, not that it transfers money. Its schema should use explicit fields such as &lt;code&gt;orderId&lt;/code&gt;, &lt;code&gt;amount&lt;/code&gt;, &lt;code&gt;currency&lt;/code&gt;, and &lt;code&gt;reason&lt;/code&gt;. It should reject unsupported currencies and amounts beyond a permitted threshold before any external action occurs.&lt;/p&gt;

&lt;p&gt;Avoid arguments such as &lt;code&gt;instructions&lt;/code&gt;, &lt;code&gt;rawQuery&lt;/code&gt;, or &lt;code&gt;options&lt;/code&gt; when a typed alternative is possible. Ambiguous string fields create a channel through which untrusted text can influence sensitive behavior.&lt;/p&gt;

&lt;p&gt;This is especially important when agents process documents, emails, web pages, or ticket descriptions. Any retrieved content may include instructions intended to manipulate the model. The model should be told that retrieved text is data, but prompts alone are not a security control. Typed, narrow tools are.&lt;/p&gt;

&lt;h2&gt;
  
  
  Separate conversation state from operational state
&lt;/h2&gt;

&lt;p&gt;Agent applications typically need more than one kind of memory.&lt;/p&gt;

&lt;p&gt;Conversation state contains messages, summaries, and working context. It helps the agent sustain a useful dialogue. Operational state contains facts that must be durable and authoritative: approval status, workflow stage, external operation IDs, retry counts, and timestamps.&lt;/p&gt;

&lt;p&gt;Do not store both in the same conceptual bucket.&lt;/p&gt;

&lt;p&gt;A conversation summary might say, “The user wants a refund for order 4812.” An operational record should say, “Refund request &lt;code&gt;rf_91c&lt;/code&gt; was submitted by user &lt;code&gt;u_203&lt;/code&gt;, approved by manager &lt;code&gt;u_018&lt;/code&gt;, and has not yet been executed.” The first helps reasoning. The second supports correctness.&lt;/p&gt;

&lt;p&gt;In a .NET application, the operational record belongs in the database and should be updated through normal transactional application logic. Conversation state can use a separate store with retention policies appropriate for chat history. The framework helps coordinate agent execution, but durable business state remains the responsibility of the application architecture.&lt;/p&gt;

&lt;p&gt;This separation also makes recovery practical. If a model call fails halfway through a workflow, the system can reload the authoritative workflow record, determine what has already happened, and continue safely.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make irreversible actions a two-step protocol
&lt;/h2&gt;

&lt;p&gt;The most reliable agent pattern for side effects is propose, validate, approve, execute.&lt;/p&gt;

&lt;p&gt;First, the agent creates a structured proposal. Second, application code validates it. Third, a human or policy engine approves it when needed. Finally, a deterministic service executes the action.&lt;/p&gt;

&lt;p&gt;For example:&lt;/p&gt;

&lt;p&gt;text&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Agent proposes: Refund order 4812 for $89.00
System validates: Order exists, amount is eligible, user is authorized
Policy decides: Manager approval required above $50
Human approves: Approval recorded with timestamp and identity
Service executes: Payment provider called with an idempotency key
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The idempotency key is essential. Models may retry, workflows may resume after failure, and users may submit the same request twice. The executing service must be able to answer, “Have I already performed this exact operation?” without relying on the agent’s memory.&lt;/p&gt;

&lt;p&gt;This approach may feel less autonomous, but it is more useful in production. Autonomy is not the absence of controls. It is the ability to make progress safely within controls.&lt;/p&gt;

&lt;h2&gt;
  
  
  Observe decisions, not just exceptions
&lt;/h2&gt;

&lt;p&gt;Traditional application monitoring focuses on latency, errors, and resource use. Agent systems need those signals, plus a record of decisions.&lt;/p&gt;

&lt;p&gt;For each run, capture structured telemetry such as:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Agent and model configuration version&lt;/li&gt;
&lt;li&gt;Correlation ID and authenticated user identity&lt;/li&gt;
&lt;li&gt;Tool names requested and arguments after redaction&lt;/li&gt;
&lt;li&gt;Policy decisions and approval outcomes&lt;/li&gt;
&lt;li&gt;Latency per model and tool invocation&lt;/li&gt;
&lt;li&gt;Token and cost estimates where available&lt;/li&gt;
&lt;li&gt;Final result, failure category, and retry history&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Distributed tracing is particularly valuable here. A single user request can cross an ASP.NET endpoint, an agent invocation, several tool calls, a queue, a database transaction, and an external provider. A shared trace ID turns an opaque “the agent did something strange” report into an investigable sequence.&lt;/p&gt;

&lt;p&gt;Be deliberate about redaction. Prompts and tool results can contain customer data, credentials, or proprietary material. Logging everything is not observability; it is often a data-retention incident waiting to happen.&lt;/p&gt;

&lt;h2&gt;
  
  
  Test the seams where models are weakest
&lt;/h2&gt;

&lt;p&gt;Do not limit testing to whether the agent produces a pleasant answer. Test whether the system behaves safely when the answer is wrong, incomplete, or manipulated.&lt;/p&gt;

&lt;p&gt;Build a scenario suite that includes ambiguous requests, malformed tool arguments, conflicting instructions in retrieved documents, unauthorized users, duplicate submissions, unavailable dependencies, and attempts to exceed business limits.&lt;/p&gt;

&lt;p&gt;Then assert on deterministic outcomes: no tool call occurred, approval was required, validation failed, an idempotent response was returned, or the workflow entered a recoverable state.&lt;/p&gt;

&lt;p&gt;For model behavior, use evaluation sets rather than a single golden response. Measure whether the agent selects an allowed tool, gathers missing information, declines unsafe requests, and routes high-risk actions to review. Treat prompt and tool-description changes as deployable artifacts that require regression testing.&lt;/p&gt;

&lt;h2&gt;
  
  
  Build the stage, not the actor
&lt;/h2&gt;

&lt;p&gt;Microsoft Agent Framework 1.0 is most compelling when it is used to compose agents into an established .NET architecture, not when it is expected to replace one.&lt;/p&gt;

&lt;p&gt;Keep business rules in services. Keep authorization at the boundary. Keep durable facts in systems of record. Give agents narrow verbs, structured choices, and clear escape routes when uncertainty is high.&lt;/p&gt;

&lt;p&gt;The model may be the visible actor, but the application is the stage manager: setting limits, recording events, checking credentials, and ensuring that every meaningful action can be explained afterward.&lt;/p&gt;

&lt;p&gt;That is how an agent becomes more than an impressive conversation. It becomes a dependable participant in a production system.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>ai</category>
      <category>agents</category>
      <category>csharp</category>
    </item>
    <item>
      <title>Adopting .NET 11 Without Surprises: A Practical Upgrade Blueprint</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:54:55 +0000</pubDate>
      <link>https://dev.to/razvanm4/adopting-net-11-without-surprises-a-practical-upgrade-blueprint-34kd</link>
      <guid>https://dev.to/razvanm4/adopting-net-11-without-surprises-a-practical-upgrade-blueprint-34kd</guid>
      <description>&lt;p&gt;A new .NET release is rarely just a new target framework moniker. Moving from &lt;code&gt;net10.0&lt;/code&gt; to &lt;code&gt;net11.0&lt;/code&gt; changes the compiler, SDK, runtime, base class libraries, analyzers, container images, and often the assumptions embedded in a build pipeline.&lt;/p&gt;

&lt;p&gt;That breadth is precisely why .NET 11 should not be approached as a Friday-afternoon dependency bump.&lt;/p&gt;

&lt;p&gt;The useful question is not &lt;em&gt;“What is new in .NET 11?”&lt;/em&gt; in isolation. It is: &lt;strong&gt;which .NET 11 changes improve this system, which changes alter its operating assumptions, and how can the team prove the upgrade is safe?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;This post frames .NET 11 features as an adoption exercise. The goal is to help teams find meaningful gains without converting an otherwise routine upgrade into an uncontrolled rewrite.&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat .NET 11 as a platform release
&lt;/h2&gt;

&lt;p&gt;A .NET application sits on several layers that do not evolve at the same speed:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The SDK&lt;/strong&gt; controls restore, build, publish, workload installation, templates, and source generators.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The compiler and language tooling&lt;/strong&gt; affect diagnostics, generated code, nullability analysis, and API design.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The runtime&lt;/strong&gt; determines JIT behavior, garbage collection, threading, reflection, native interoperability, and deployment characteristics.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The libraries and frameworks&lt;/strong&gt; include ASP.NET Core, EF Core, the BCL, logging, configuration, authentication, and serialization.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The operational environment&lt;/strong&gt; includes Linux distributions, container base images, CI runners, Kubernetes manifests, and observability tooling.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;An upgrade can succeed at one layer while failing at another. A service may compile cleanly under .NET 11 yet expose a subtle runtime regression: a changed JSON contract, an incompatible native package, a warning promoted to an error, or a container image that no longer matches production requirements.&lt;/p&gt;

&lt;p&gt;That is why the first .NET 11 feature to adopt is not a language construct. It is a disciplined upgrade boundary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with an inventory, not a project-file edit
&lt;/h2&gt;

&lt;p&gt;Before changing target frameworks, create a short inventory for every deployable application and shared library:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Current SDK version and &lt;code&gt;global.json&lt;/code&gt; policy&lt;/li&gt;
&lt;li&gt;Target frameworks and runtime identifiers&lt;/li&gt;
&lt;li&gt;NuGet packages with native, reflection-heavy, or source-generated behavior&lt;/li&gt;
&lt;li&gt;EF Core provider version and database compatibility requirements&lt;/li&gt;
&lt;li&gt;Container base images and operating system dependencies&lt;/li&gt;
&lt;li&gt;CI build images, test runners, and deployment agents&lt;/li&gt;
&lt;li&gt;Existing warnings, obsolete API usage, and analyzer suppressions&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The baseline matters because an upgrade produces a large amount of information. Without a known starting point, a team cannot tell whether a warning is newly introduced by .NET 11 or has been quietly ignored for six months.&lt;/p&gt;

&lt;p&gt;Capture a clean build and test run before the change:&lt;/p&gt;

&lt;p&gt;bash&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet --info
dotnet restore
dotnet build --configuration Release --no-restore
dotnet &lt;span class="nb"&gt;test&lt;/span&gt; --configuration Release --no-build
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For production services, record a small operational baseline as well: startup time, memory under representative load, P95 latency, error rate, and image size. Performance improvements are valuable only when they are measured in the workload that matters.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use multi-targeting to separate validation from commitment
&lt;/h2&gt;

&lt;p&gt;A shared package does not need to abandon its existing consumers the moment .NET 11 becomes available. Multi-targeting creates room to validate the new framework while preserving compatibility.&lt;/p&gt;

&lt;p&gt;xml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight xml"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;Project&lt;/span&gt; &lt;span class="na"&gt;Sdk&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"Microsoft.NET.Sdk"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;PropertyGroup&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;TargetFrameworks&amp;gt;&lt;/span&gt;net10.0;net11.0&lt;span class="nt"&gt;&amp;lt;/TargetFrameworks&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;Nullable&amp;gt;&lt;/span&gt;enable&lt;span class="nt"&gt;&amp;lt;/Nullable&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;ImplicitUsings&amp;gt;&lt;/span&gt;enable&lt;span class="nt"&gt;&amp;lt;/ImplicitUsings&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;/PropertyGroup&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/Project&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This approach is especially useful for internal libraries, SDKs, and utility packages. It exposes compile-time differences early and gives maintainers an explicit place to isolate framework-specific behavior.&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;RuntimeFeatures&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nc"&gt;TargetFrameworkDescription&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="nc"&gt;System&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;InteropServices&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;RuntimeInformation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;FrameworkDescription&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Avoid scattering conditional compilation through business logic. If a .NET 11-specific API is genuinely needed, place it behind a narrow adapter or capability boundary. Most application code should remain indifferent to the target framework.&lt;/p&gt;

&lt;p&gt;For deployable applications, a shorter path is often better: create a dedicated .NET 11 upgrade branch, run it through the full pipeline, and release it first to a low-risk environment. Applications usually gain more from a clean cutover than from long-lived multi-targeting.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make compiler diagnostics part of the feature review
&lt;/h2&gt;

&lt;p&gt;New SDKs and analyzers often reveal code that was always fragile but previously invisible. That can feel disruptive, yet it is one of the highest-value parts of adopting a new release.&lt;/p&gt;

&lt;p&gt;Review warnings in three groups:&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Correctness warnings
&lt;/h3&gt;

&lt;p&gt;Prioritize nullability, disposal, async, trimming, and serialization warnings. These frequently identify defects that appear only under error paths, load, or ahead-of-time deployment.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Obsolete API warnings
&lt;/h3&gt;

&lt;p&gt;Do not silence these reflexively. Obsolete APIs may continue to work today while blocking a future runtime, security, or deployment path. Record the replacement and migrate intentionally.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Style and maintainability warnings
&lt;/h3&gt;

&lt;p&gt;These deserve consistency, not emergency treatment. Decide whether the repository will enforce them now, establish a baseline, or defer them to a separate cleanup effort.&lt;/p&gt;

&lt;p&gt;A practical pattern is to make warnings visible in CI before making them fatal:&lt;/p&gt;

&lt;p&gt;xml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight xml"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;PropertyGroup&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;TreatWarningsAsErrors&amp;gt;&lt;/span&gt;false&lt;span class="nt"&gt;&amp;lt;/TreatWarningsAsErrors&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;AnalysisLevel&amp;gt;&lt;/span&gt;latest&lt;span class="nt"&gt;&amp;lt;/AnalysisLevel&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/PropertyGroup&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Once the initial upgrade is stable, selectively elevate the warnings that protect real production concerns. A blanket switch to errors can turn a framework upgrade into a noisy style migration.&lt;/p&gt;

&lt;h2&gt;
  
  
  Verify the data layer independently
&lt;/h2&gt;

&lt;p&gt;When upgrading an API that uses EF Core, treat the provider, migrations, and query translation as their own workstream. The application can start successfully while a rarely used query changes translation behavior or a provider package lags behind the framework version.&lt;/p&gt;

&lt;p&gt;For each database-backed service, validate:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Generated migrations and model snapshots&lt;/li&gt;
&lt;li&gt;SQL generated by critical read and write paths&lt;/li&gt;
&lt;li&gt;Transaction and retry behavior&lt;/li&gt;
&lt;li&gt;Connection pooling under load&lt;/li&gt;
&lt;li&gt;Date, time zone, decimal, and JSON column handling&lt;/li&gt;
&lt;li&gt;Provider support for the target EF Core version&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Integration tests should run against the same database engine family and major version used in production. An in-memory substitute is useful for fast feedback, but it cannot validate PostgreSQL, SQL Server, MySQL, or MongoDB-specific behavior.&lt;/p&gt;

&lt;p&gt;For a PostgreSQL-backed service, for example, run test containers in CI and execute the migration path from a realistic previous schema. The database is not a unit-test dependency; it is a compatibility boundary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rebuild the delivery path with the new SDK
&lt;/h2&gt;

&lt;p&gt;A local machine running .NET 11 proves very little if CI still compiles with a previous SDK or production runs a different container image.&lt;/p&gt;

&lt;p&gt;Pin the intended SDK using &lt;code&gt;global.json&lt;/code&gt;:&lt;/p&gt;

&lt;p&gt;json&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"sdk"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"11.0.100"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"rollForward"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"latestFeature"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use the corresponding SDK image for builds and runtime image for deployment. Keep these stages separate:&lt;/p&gt;

&lt;p&gt;dockerfile&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="k"&gt;FROM&lt;/span&gt; mcr.microsoft.com/dotnet/sdk:11.0 AS build
&lt;span class="k"&gt;WORKDIR&lt;/span&gt; /src
&lt;span class="k"&gt;COPY&lt;/span&gt; . .
&lt;span class="k"&gt;RUN&lt;/span&gt; dotnet publish src/Catalog.Api/Catalog.Api.csproj \
    -c Release -o /app/publish --no-restore

&lt;span class="k"&gt;FROM&lt;/span&gt; mcr.microsoft.com/dotnet/aspnet:11.0
&lt;span class="k"&gt;WORKDIR&lt;/span&gt; /app
&lt;span class="k"&gt;COPY&lt;/span&gt; --from=build /app/publish .
&lt;span class="k"&gt;ENTRYPOINT&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"dotnet"&lt;/span&gt;, &lt;span class="s2"&gt;"Catalog.Api.dll"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In CI/CD, add explicit checks for SDK identity, test results, package vulnerability reporting, container scanning, and smoke tests against the published artifact. The artifact that passed tests should be the artifact promoted to staging and production.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use a feature scorecard instead of upgrading on instinct
&lt;/h2&gt;

&lt;p&gt;Not every .NET 11 capability deserves immediate adoption. Create a small scorecard for each candidate improvement:&lt;/p&gt;

&lt;p&gt;| Question | Why it matters | |---|---| | Does it remove a measured bottleneck? | Prevents speculative optimization. | | Does it simplify a recurring maintenance task? | Captures developer-experience value. | | Does it reduce deployment risk or image size? | Connects runtime changes to operations. | | Does it require public API changes? | Identifies consumer coordination costs. | | Can it be rolled back independently? | Limits blast radius. |&lt;/p&gt;

&lt;p&gt;This is particularly important for runtime and deployment features. A change that reduces cold-start time may be compelling for serverless workloads but irrelevant for a long-running internal API. A new build or publishing mode may benefit a CLI tool while complicating reflection-heavy applications.&lt;/p&gt;

&lt;p&gt;The point is not to adopt every feature. It is to make each adoption deliberate.&lt;/p&gt;

&lt;h2&gt;
  
  
  A staged rollout sequence that works
&lt;/h2&gt;

&lt;p&gt;A reliable .NET 11 rollout usually follows this order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Upgrade SDKs and CI images in an isolated branch.&lt;/li&gt;
&lt;li&gt;Compile, restore, and run unit tests with the new target framework.&lt;/li&gt;
&lt;li&gt;Resolve correctness and compatibility diagnostics.&lt;/li&gt;
&lt;li&gt;Validate database providers and integration tests.&lt;/li&gt;
&lt;li&gt;Build and scan production containers.&lt;/li&gt;
&lt;li&gt;Deploy to a staging environment with representative traffic.&lt;/li&gt;
&lt;li&gt;Compare performance and operational telemetry with the baseline.&lt;/li&gt;
&lt;li&gt;Release gradually, with dashboards and a rollback path.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Feature flags, canary deployments, and versioned Docker tags are more valuable than heroic debugging after a full rollout. The framework upgrade should be observable like any other production change.&lt;/p&gt;

&lt;h2&gt;
  
  
  The real payoff of .NET 11
&lt;/h2&gt;

&lt;p&gt;The strongest reason to move to .NET 11 is not novelty. It is alignment: a current supported runtime, current tooling, current security servicing, and a cleaner foundation for the next several years of application work.&lt;/p&gt;

&lt;p&gt;Approach the release as a platform upgrade rather than a syntax tour. Measure the baseline, isolate compatibility work, test the data layer honestly, update the delivery path, and adopt new capabilities where they solve a demonstrated problem.&lt;/p&gt;

&lt;p&gt;Done this way, .NET 11 becomes more than an updated &lt;code&gt;&amp;lt;TargetFramework&amp;gt;&lt;/code&gt;. It becomes a controlled improvement to how software is built, shipped, observed, and maintained.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>csharp</category>
      <category>architecture</category>
      <category>programming</category>
    </item>
    <item>
      <title>Inside My k3s-on-Proxmox Homelab: A Small Platform With Real Constraints</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:54:51 +0000</pubDate>
      <link>https://dev.to/razvanm4/inside-my-k3s-on-proxmox-homelab-a-small-platform-with-real-constraints-5g2</link>
      <guid>https://dev.to/razvanm4/inside-my-k3s-on-proxmox-homelab-a-small-platform-with-real-constraints-5g2</guid>
      <description>&lt;p&gt;A homelab becomes substantially more useful when it stops being a collection of experiments and starts behaving like a platform.&lt;/p&gt;

&lt;p&gt;That is the goal of my k3s-on-Proxmox stack. It is not intended to imitate a hyperscale cloud environment node for node. Instead, it gives me a compact, failure-aware environment where I can deploy services, test infrastructure changes, run personal applications, and practice the operational habits that matter in production: clear boundaries, repeatable recovery, observability, and controlled change.&lt;/p&gt;

&lt;p&gt;The central design choice is simple: &lt;strong&gt;Proxmox provides the machines; k3s provides the platform.&lt;/strong&gt; Each layer has a deliberately narrow responsibility, which makes the whole system easier to reason about when something inevitably breaks.&lt;/p&gt;

&lt;h2&gt;
  
  
  The foundation: Proxmox as the physical control plane
&lt;/h2&gt;

&lt;p&gt;Proxmox sits directly on the homelab hardware and acts as the infrastructure layer. It owns the concerns closest to the machines: virtual machines, CPU and memory allocation, networking, local storage, snapshots, backups, and host maintenance.&lt;/p&gt;

&lt;p&gt;I use virtual machines rather than placing Kubernetes directly on the Proxmox hosts. That decision adds a layer of virtualization, but the trade-off is worthwhile. VMs give every Kubernetes node a clean operating-system boundary and make cluster-level operations less coupled to the hypervisor. I can resize a node, replace it, clone it for testing, or restore it without turning a routine Kubernetes task into a change on the physical host.&lt;/p&gt;

&lt;p&gt;The VM boundary also makes failures more legible. If an application is unavailable, I can work down the stack in a predictable order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Is the Kubernetes workload healthy?&lt;/li&gt;
&lt;li&gt;Is the k3s node reachable?&lt;/li&gt;
&lt;li&gt;Is the VM running and correctly networked?&lt;/li&gt;
&lt;li&gt;Is the Proxmox host healthy?&lt;/li&gt;
&lt;li&gt;Is the underlying network or storage available?&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;That sequence may sound obvious, but it prevents a common homelab problem: troubleshooting every layer at once.&lt;/p&gt;

&lt;p&gt;Each VM is intentionally modest. A homelab rarely has unlimited CPU or memory, so capacity planning is a practical discipline rather than a theoretical exercise. Control-plane nodes receive enough stable resources to avoid starvation, while worker nodes are where I absorb more variable workloads. Keeping workloads in VMs also lets me test resource pressure realistically: Kubernetes requests and limits mean more when the underlying machines have finite capacity.&lt;/p&gt;

&lt;h2&gt;
  
  
  A small k3s cluster, not a miniature enterprise
&lt;/h2&gt;

&lt;p&gt;k3s is the Kubernetes distribution at the center of the stack. It preserves the Kubernetes API and operating model while reducing operational overhead for a small environment. Its lightweight footprint is especially appropriate when hardware, power, and attention are all limited resources.&lt;/p&gt;

&lt;p&gt;The cluster is organized around clear roles. Control-plane nodes run the services needed to manage cluster state. Worker nodes run the applications. In a smaller setup, those roles can overlap when necessary, but I prefer keeping the separation visible even if the physical distinction is not absolute. It reinforces an important operational fact: the cluster's ability to schedule workloads and its ability to make decisions about workloads are related but different concerns.&lt;/p&gt;

&lt;p&gt;I treat Kubernetes manifests as the desired state of the platform, not as a set of one-time deployment instructions. Deployments describe application replicas. Services describe stable internal access. ConfigMaps and Secrets keep configuration out of container images. PersistentVolumeClaims describe storage requirements without forcing every application to understand the details of the underlying disks.&lt;/p&gt;

&lt;p&gt;That declarative model is one of the reasons the stack is valuable. When a node disappears, the desired state still exists. Kubernetes can reschedule eligible workloads, and I can focus on restoring capacity rather than manually rebuilding every service that used to be running there.&lt;/p&gt;

&lt;h2&gt;
  
  
  Networking: making internal services feel intentional
&lt;/h2&gt;

&lt;p&gt;Networking is where a homelab can quickly become confusing. It is easy to accumulate port forwards, ad hoc hostnames, and services that are only reachable from one machine on the network. My stack avoids that by treating ingress as a first-class part of the platform.&lt;/p&gt;

&lt;p&gt;Traefik is the primary ingress controller. It receives HTTP and HTTPS traffic, matches hostnames and paths, and forwards requests to Kubernetes Services. Applications do not need to expose host ports or know about the external network directly. They only need to provide a service inside the cluster.&lt;/p&gt;

&lt;p&gt;This creates a clean traffic path:&lt;/p&gt;

&lt;p&gt;text&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Client -&amp;gt; DNS -&amp;gt; Router or external edge -&amp;gt; Traefik -&amp;gt; Kubernetes Service -&amp;gt; Pod
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The value of this path is not just convenience. It creates a consistent location for TLS termination, routing rules, middleware, redirects, and access policies. When I deploy a new internal application, its network shape is predictable: a Deployment, a Service, and an Ingress or Traefik route.&lt;/p&gt;

&lt;p&gt;For externally reachable services, Cloudflare can sit at the edge for DNS and additional protection. That separation is useful because public traffic and private cluster networking have different risks. Public endpoints should be narrowly exposed, authenticated where appropriate, and treated as services that may receive hostile traffic. Internal tools should not automatically become internet-facing merely because they have a convenient hostname.&lt;/p&gt;

&lt;h2&gt;
  
  
  Storage: where the lab becomes real
&lt;/h2&gt;

&lt;p&gt;Stateless applications are easy to recreate. Databases, queues, and media services are not. Storage is therefore the most important place to be conservative.&lt;/p&gt;

&lt;p&gt;Proxmox provides the underlying virtual disks, while Kubernetes consumes storage through persistent volumes and claims. The exact storage implementation can evolve, but the architectural principle remains stable: application data must have a documented location, a backup path, and a recovery procedure.&lt;/p&gt;

&lt;p&gt;For services such as PostgreSQL or Redis, I avoid treating a persistent volume as a backup strategy. A volume protects data from a pod restart; it does not protect against accidental deletion, corruption, failed upgrades, or a broader infrastructure event. Database-aware backups matter. For PostgreSQL, that means logical dumps or physical backup tooling, tested independently from the running workload.&lt;/p&gt;

&lt;p&gt;Snapshots are useful, particularly before maintenance, but they are not a substitute for backups either. A snapshot can be tightly coupled to the storage system that created it. A backup should be recoverable somewhere else and should be validated by actually restoring it.&lt;/p&gt;

&lt;p&gt;The most useful homelab question is not, “Do I have backups?” It is, “Can I restore this service to a known-good state without improvising?”&lt;/p&gt;

&lt;h2&gt;
  
  
  Containers and application delivery
&lt;/h2&gt;

&lt;p&gt;Docker remains part of the workflow even though Kubernetes runs the workloads. Containers are built from application source code, tested locally or in CI, published to a registry, and then referenced by Kubernetes manifests.&lt;/p&gt;

&lt;p&gt;This separation gives the deployment process a useful shape:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Source code produces a versioned container image.&lt;/li&gt;
&lt;li&gt;CI validates the image and application behavior.&lt;/li&gt;
&lt;li&gt;Kubernetes deploys that immutable image reference.&lt;/li&gt;
&lt;li&gt;The cluster reports whether the new workload becomes healthy.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;GitHub Actions is a natural fit for this pipeline. A typical workflow can run tests, build a Docker image, tag it with a commit SHA or release version, publish it, and update the deployment configuration. For a homelab, this is not overengineering. It is a way to make deployment history visible and repeatable.&lt;/p&gt;

&lt;p&gt;I prefer image tags that identify a specific build rather than mutable tags such as &lt;code&gt;latest&lt;/code&gt;. A deployment should answer a simple question: what code is running right now? Immutable tags make rollback and diagnosis much easier, especially when multiple services are changing over time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Operating the stack: boring is a feature
&lt;/h2&gt;

&lt;p&gt;The best outcome for a homelab platform is not constant novelty. It is controlled boredom.&lt;/p&gt;

&lt;p&gt;That means monitoring node health, watching disk consumption, reviewing Kubernetes events, and keeping an eye on certificate renewals before they become incidents. It means maintaining an inventory of VMs, IP addresses, DNS records, namespaces, and persistent workloads. It means documenting the steps required to rebuild a node and periodically proving that the documentation is correct.&lt;/p&gt;

&lt;p&gt;Maintenance is also part of the design. Proxmox host updates, guest operating-system patching, k3s upgrades, container image updates, and database migrations should not be performed as one giant change. Each layer has its own blast radius. Updating deliberately, with backups and rollback points, is more valuable than updating quickly.&lt;/p&gt;

&lt;p&gt;The stack is small, but it teaches large-system lessons. Kubernetes does not eliminate complexity; it organizes complexity around APIs and declared state. Proxmox does not eliminate hardware concerns; it makes infrastructure more manageable. Backups do not guarantee recovery; tested restores do.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this stack matters
&lt;/h2&gt;

&lt;p&gt;My k3s-on-Proxmox homelab is a practical environment for building and operating software under realistic constraints. It gives applications a consistent route from source code to container image to deployed service. It gives infrastructure a stable foundation beneath Kubernetes. And it creates enough complexity to learn meaningful operational patterns without requiring a datacenter.&lt;/p&gt;

&lt;p&gt;Most importantly, it is a system I can change with intent. I can add an application, simulate a node failure, test a backup restore, introduce a new ingress rule, or rebuild a worker node. Every one of those actions strengthens the platform when the result is documented and repeatable.&lt;/p&gt;

&lt;p&gt;That is the value of the stack: not that it runs Kubernetes at home, but that it turns a home environment into a place where infrastructure practice becomes tangible.&lt;/p&gt;

</description>
      <category>kubernetes</category>
      <category>proxmox</category>
      <category>homelab</category>
      <category>devops</category>
    </item>
    <item>
      <title>Provision k3s with Terraform and Ansible: A Repeatable Cluster Blueprint</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:54:05 +0000</pubDate>
      <link>https://dev.to/razvanm4/provision-k3s-with-terraform-and-ansible-a-repeatable-cluster-blueprint-o1</link>
      <guid>https://dev.to/razvanm4/provision-k3s-with-terraform-and-ansible-a-repeatable-cluster-blueprint-o1</guid>
      <description>&lt;p&gt;A k3s cluster can begin as a quick experiment: one server, a curl command, and a kubeconfig copied to a laptop. That is useful for learning, but it does not scale into a dependable platform. The moment a cluster runs shared services, hosts internal applications, or becomes part of a delivery pipeline, its creation needs to be repeatable.&lt;/p&gt;

&lt;p&gt;The practical division of responsibility is simple:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Terraform&lt;/strong&gt; creates the infrastructure: virtual machines, networks, IP assignments, DNS records, and firewall rules.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Ansible&lt;/strong&gt; configures those machines: operating-system prerequisites, k3s installation, node joins, kubeconfig handling, and post-install validation.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;k3s&lt;/strong&gt; provides the lightweight Kubernetes distribution that runs the workload.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This combination turns cluster provisioning from a sequence of terminal commands into a versioned, reviewable system. Terraform draws the landscape; Ansible prepares the ground and assembles the cluster.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why split provisioning between Terraform and Ansible?
&lt;/h2&gt;

&lt;p&gt;Terraform is excellent at declaring resources exposed by an infrastructure API. It can create three virtual machines in Proxmox, attach them to a network, assign tags, and expose their addresses as outputs. It is less suitable for imperative host-level tasks such as waiting for cloud-init, modifying &lt;code&gt;/etc/sysctl.conf&lt;/code&gt;, installing packages, or running a bootstrap command only on the first control-plane node.&lt;/p&gt;

&lt;p&gt;Ansible is designed for exactly those operations. Its inventory can be generated from Terraform outputs, and its playbooks can express configuration in an idempotent way. A rerun should converge nodes toward the intended state rather than recreate everything blindly.&lt;/p&gt;

&lt;p&gt;Keeping those tools focused also makes failures easier to understand. If Terraform fails, investigate the infrastructure provider, credentials, quota, or network configuration. If Ansible fails, inspect SSH connectivity, package repositories, service logs, or k3s tokens. The boundary is clear.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with an explicit cluster shape
&lt;/h2&gt;

&lt;p&gt;Before writing code, define the cluster topology. For a small homelab or internal environment, a useful starting point is:&lt;/p&gt;

&lt;p&gt;| Role | Count | Purpose | | --- | ---: | --- | | Server | 3 | Kubernetes control plane and embedded etcd quorum | | Agent | 2+ | Application workloads | | Bootstrap host | 1 | Optional runner for Terraform and Ansible |&lt;/p&gt;

&lt;p&gt;Three server nodes provide resilience for embedded etcd. A single server is simpler but creates an obvious availability boundary: if that machine is unavailable, the control plane is unavailable. For non-production experimentation, one server plus one or more agents is completely reasonable; the important part is making that trade-off intentionally.&lt;/p&gt;

&lt;p&gt;Also decide early how workloads will be exposed. k3s installs Traefik by default in many configurations, which is convenient for ingress. If a different ingress controller is required, disable the bundled component during installation instead of deploying two controllers that both expect to own ports 80 and 443.&lt;/p&gt;

&lt;h2&gt;
  
  
  Terraform: create predictable infrastructure
&lt;/h2&gt;

&lt;p&gt;A Terraform project should make the physical or virtual shape of the cluster visible. In a Proxmox environment, that usually means cloning a cloud-init-enabled Linux template for each node. In cloud environments, the same pattern maps to virtual machine instances, security groups, subnets, and managed DNS zones.&lt;/p&gt;

&lt;p&gt;A useful module interface describes intent rather than individual machines:&lt;/p&gt;

&lt;p&gt;hcl&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight terraform"&gt;&lt;code&gt;&lt;span class="mi"&gt;1module&lt;/span&gt; &lt;span class="s2"&gt;"k3s_servers"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;2&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"./modules/k3s-node"&lt;/span&gt;
&lt;span class="mi"&gt;3&lt;/span&gt; &lt;span class="n"&gt;node_count&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;
&lt;span class="mi"&gt;4&lt;/span&gt; &lt;span class="n"&gt;name_prefix&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"k3s-server"&lt;/span&gt;
&lt;span class="mi"&gt;5&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"server"&lt;/span&gt;
&lt;span class="mi"&gt;6&lt;/span&gt; &lt;span class="n"&gt;cpu_cores&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="mi"&gt;7&lt;/span&gt; &lt;span class="n"&gt;memory_mb&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;4096&lt;/span&gt;
&lt;span class="mi"&gt;8&lt;/span&gt; &lt;span class="n"&gt;network_cidr&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cluster_network_cidr&lt;/span&gt;
&lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;10&lt;/span&gt;
&lt;span class="mi"&gt;11module&lt;/span&gt; &lt;span class="s2"&gt;"k3s_agents"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;12&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"./modules/k3s-node"&lt;/span&gt;
&lt;span class="mi"&gt;13&lt;/span&gt; &lt;span class="n"&gt;node_count&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="mi"&gt;14&lt;/span&gt; &lt;span class="n"&gt;name_prefix&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"k3s-agent"&lt;/span&gt;
&lt;span class="mi"&gt;15&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"agent"&lt;/span&gt;
&lt;span class="mi"&gt;16&lt;/span&gt; &lt;span class="n"&gt;cpu_cores&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;
&lt;span class="mi"&gt;17&lt;/span&gt; &lt;span class="n"&gt;memory_mb&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;8192&lt;/span&gt;
&lt;span class="mi"&gt;18&lt;/span&gt; &lt;span class="n"&gt;network_cidr&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cluster_network_cidr&lt;/span&gt;
&lt;span class="mi"&gt;19&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The exact provider syntax changes across platforms, but several practices remain valuable:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Use immutable base images.&lt;/strong&gt; Build or maintain a known Linux template with cloud-init and the required SSH configuration. Avoid manually modifying individual nodes after they are created.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Assign stable addresses or stable DNS records.&lt;/strong&gt; Kubernetes control-plane membership depends on reliable communication. DHCP reservations can work, but static addresses or managed DNS records are easier to reason about.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Separate secrets from configuration.&lt;/strong&gt; Provider passwords, API tokens, and SSH private keys should come from environment variables, a secret manager, or CI secrets—not committed &lt;code&gt;.tfvars&lt;/code&gt; files.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Expose machine data as outputs.&lt;/strong&gt; IP addresses and hostnames are the handshake between Terraform and Ansible.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For example, Terraform can export a structured output:&lt;/p&gt;

&lt;p&gt;hcl&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight terraform"&gt;&lt;code&gt;&lt;span class="mi"&gt;1output&lt;/span&gt; &lt;span class="s2"&gt;"k3s_inventory"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;2&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;3&lt;/span&gt; &lt;span class="n"&gt;servers&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;module&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;k3s_servers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ip_addresses&lt;/span&gt;
&lt;span class="mi"&gt;4&lt;/span&gt; &lt;span class="n"&gt;agents&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;module&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;k3s_agents&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ip_addresses&lt;/span&gt;
&lt;span class="mi"&gt;5&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;6&lt;/span&gt; &lt;span class="n"&gt;sensitive&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="mi"&gt;7&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Do not treat &lt;code&gt;terraform apply&lt;/code&gt; as proof that the nodes are ready. A provider may report success before cloud-init finishes, before SSH is accepting connections, or before package repositories are reachable. That is an Ansible concern.&lt;/p&gt;

&lt;h2&gt;
  
  
  Generate inventory instead of maintaining it twice
&lt;/h2&gt;

&lt;p&gt;The fastest path to configuration drift is creating the same host list in Terraform and in a hand-maintained Ansible inventory. Generate inventory from Terraform state or outputs instead.&lt;/p&gt;

&lt;p&gt;One straightforward approach is to emit JSON and transform it into an inventory file in the pipeline:&lt;/p&gt;

&lt;p&gt;bash&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform output -json k3s_inventory &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; inventory-data.json
python scripts/render_inventory.py inventory-data.json &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; inventory.ini
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The generated inventory might look like this:&lt;/p&gt;

&lt;p&gt;ini&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;k3s_servers&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="na"&gt;2k3s-server-1 ansible_host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;10.20&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.11&lt;/span&gt;
&lt;span class="na"&gt;3k3s-server-2 ansible_host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;10.20&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.12&lt;/span&gt;
&lt;span class="na"&gt;4k3s-server-3 ansible_host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;10.20&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.13&lt;/span&gt;
&lt;span class="mi"&gt;5&lt;/span&gt;
&lt;span class="mi"&gt;6&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;k3s_agents&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="na"&gt;7k3s-agent-1 ansible_host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;10.20&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.21&lt;/span&gt;
&lt;span class="na"&gt;8k3s-agent-2 ansible_host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;10.20&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.22&lt;/span&gt;
&lt;span class="mi"&gt;9&lt;/span&gt;
&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;k3s_cluster&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;children&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="mi"&gt;11k3s_servers&lt;/span&gt;
&lt;span class="mi"&gt;12k3s_agents&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Dynamic inventory plugins can eliminate the rendering script when the infrastructure platform supports them. The key principle is not the mechanism; it is preserving one source of truth for node identity.&lt;/p&gt;

&lt;h2&gt;
  
  
  Ansible: prepare every node before installing k3s
&lt;/h2&gt;

&lt;p&gt;The first play should establish the baseline across all nodes. A typical Linux preparation role updates package metadata, installs dependencies, enables required kernel modules, configures sysctl values, and ensures swap is disabled.&lt;/p&gt;

&lt;p&gt;yaml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;1- name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Prepare all Kubernetes nodes&lt;/span&gt;
&lt;span class="na"&gt;2 hosts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;k3s_cluster&lt;/span&gt;
&lt;span class="na"&gt;3 become&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;4 tasks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;5 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Disable swap immediately&lt;/span&gt;
&lt;span class="na"&gt;6 ansible.builtin.command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;swapoff -a&lt;/span&gt;
&lt;span class="na"&gt;7 changed_when&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="mi"&gt;8&lt;/span&gt;
&lt;span class="na"&gt;9 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Remove swap entries from fstab&lt;/span&gt;
&lt;span class="na"&gt;10 ansible.builtin.replace&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;11 path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;/etc/fstab&lt;/span&gt;
&lt;span class="na"&gt;12 regexp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'^([^#].*\s+swap\s+.*)$'&lt;/span&gt;
&lt;span class="na"&gt;13 replace&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'# \1'&lt;/span&gt;
&lt;span class="mi"&gt;14&lt;/span&gt;
&lt;span class="na"&gt;15 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Load br_netfilter module&lt;/span&gt;
&lt;span class="na"&gt;16 community.general.modprobe&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;17 name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;br_netfilter&lt;/span&gt;
&lt;span class="na"&gt;18 state&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;present&lt;/span&gt;
&lt;span class="mi"&gt;19&lt;/span&gt;
&lt;span class="na"&gt;20 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Configure forwarding for Kubernetes networking&lt;/span&gt;
&lt;span class="na"&gt;21 ansible.posix.sysctl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;22 name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;net.ipv4.ip_forward&lt;/span&gt;
&lt;span class="na"&gt;23 value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'1'&lt;/span&gt;
&lt;span class="na"&gt;24 state&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;present&lt;/span&gt;
&lt;span class="na"&gt;25 reload&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The exact prerequisites depend on the operating system and networking model. k3s removes much of the operational weight of a full Kubernetes installation, but it still relies on a healthy host: correct time, working DNS, sufficient disk space, and reachable peers.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bootstrap the first server deliberately
&lt;/h2&gt;

&lt;p&gt;The first server is special because it creates the cluster. Install it with a fixed token and a stable API endpoint. For a highly available control plane, the endpoint should be a load balancer or virtual IP rather than the address of the first server.&lt;/p&gt;

&lt;p&gt;A simple first-server command can be managed with Ansible’s &lt;code&gt;command&lt;/code&gt; module and a &lt;code&gt;creates&lt;/code&gt; guard:&lt;/p&gt;

&lt;p&gt;yaml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;1- name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Install initial k3s server&lt;/span&gt;
&lt;span class="na"&gt;2 hosts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;k3s_servers[0]&lt;/span&gt;
&lt;span class="na"&gt;3 become&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;4 tasks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;5 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Bootstrap cluster&lt;/span&gt;
&lt;span class="na"&gt;6 ansible.builtin.command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;&amp;gt;&lt;/span&gt;&lt;span class="s"&gt;-&lt;/span&gt;
&lt;span class="s"&gt;7 sh -c 'curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server&lt;/span&gt;
&lt;span class="s"&gt;8 --cluster-init --tls-san {{ k3s_api_endpoint }}" sh -'&lt;/span&gt;
&lt;span class="na"&gt;9 args&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;10 creates&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;/etc/rancher/k3s/k3s.yaml&lt;/span&gt;
&lt;span class="na"&gt;11 environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;12 K3S_TOKEN&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"{{ vault_k3s_token }}"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In a mature implementation, pin the k3s version rather than always installing the latest release. Store the join token in Ansible Vault or an external secret manager. The token grants cluster membership, so it deserves the same treatment as infrastructure credentials.&lt;/p&gt;

&lt;p&gt;After the bootstrap node is healthy, join the remaining servers using &lt;code&gt;K3S_URL=https://&amp;lt;endpoint&amp;gt;:6443&lt;/code&gt; and the same token. Then join agents with the same endpoint and token. Serial execution is helpful for servers: establish etcd membership one node at a time, validate it, and only then continue.&lt;/p&gt;

&lt;h2&gt;
  
  
  Validate the cluster as part of provisioning
&lt;/h2&gt;

&lt;p&gt;A successful playbook run is not enough. Add explicit checks that confirm the outcome:&lt;/p&gt;

&lt;p&gt;yaml&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;1- name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Verify cluster health&lt;/span&gt;
&lt;span class="na"&gt;2 hosts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;k3s_servers[0]&lt;/span&gt;
&lt;span class="na"&gt;3 become&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="na"&gt;4 tasks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;5 - name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Wait for nodes to become Ready&lt;/span&gt;
&lt;span class="na"&gt;6 ansible.builtin.command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;k3s kubectl get nodes --no-headers&lt;/span&gt;
&lt;span class="na"&gt;7 register&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;node_status&lt;/span&gt;
&lt;span class="na"&gt;8 retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt;
&lt;span class="na"&gt;9 delay&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;
&lt;span class="na"&gt;10 until&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;node_status.stdout is search(' Ready ')&lt;/span&gt;
&lt;span class="na"&gt;11 changed_when&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also verify that CoreDNS is running, the expected number of nodes has registered, and the API endpoint is reachable from the machine that will run deployments. For environments using Traefik, deploy a small test service and confirm that ingress routing works before declaring the platform ready.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make destruction and recovery intentional
&lt;/h2&gt;

&lt;p&gt;Terraform makes deletion easy, which is valuable and dangerous. Protect persistent workloads by separating cluster infrastructure from application data where possible. Back up k3s embedded etcd snapshots, document restore procedures, and test them on a disposable cluster.&lt;/p&gt;

&lt;p&gt;The most valuable outcome of this approach is not merely a faster installation. It is confidence. A failed node can be replaced from code. A test cluster can mirror production topology. A teammate can review changes before machines exist. Terraform provides the repeatable foundation, Ansible supplies the controlled bootstrap, and k3s turns that infrastructure into a compact Kubernetes platform ready for real workloads.&lt;/p&gt;

</description>
      <category>kubernetes</category>
      <category>terraform</category>
      <category>ansible</category>
      <category>devops</category>
    </item>
    <item>
      <title>Inside the Official MCP Registry: A Supply Chain for AI Tools</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:51:16 +0000</pubDate>
      <link>https://dev.to/razvanm4/inside-the-official-mcp-registry-a-supply-chain-for-ai-tools-314n</link>
      <guid>https://dev.to/razvanm4/inside-the-official-mcp-registry-a-supply-chain-for-ai-tools-314n</guid>
      <description>&lt;p&gt;AI agents are only as useful as the tools they can discover and use reliably. A model may be able to reason about a deployment failure, summarize a customer record, or draft a database migration—but it cannot safely act on those ideas without a well-defined connection to the systems where the work happens.&lt;/p&gt;

&lt;p&gt;The Model Context Protocol (MCP) addresses that connection layer. It provides a common protocol through which AI applications can discover tools, resources, and prompts exposed by external servers. But a protocol alone does not solve the next practical problem: &lt;strong&gt;how does a developer find a trustworthy server for the task at hand?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That is the role of the official MCP server registry.&lt;/p&gt;

&lt;p&gt;Think of the registry less as an app store for agents and more as a supply-chain index for tool integrations. It gives server authors a standard way to publish metadata, versions, installation information, and source locations. It gives client authors a machine-readable place to search for compatible integrations. And it gives platform teams a foundation for applying the same engineering discipline to AI tooling that they already apply to packages, containers, and CI dependencies.&lt;/p&gt;

&lt;h2&gt;
  
  
  The missing layer between protocol and adoption
&lt;/h2&gt;

&lt;p&gt;MCP standardizes communication between a host application and a server. An MCP host—such as an AI-enabled IDE, desktop client, internal assistant, or custom agent runtime—connects to one or more MCP servers. Those servers describe capabilities such as tools that can be called, resources that can be read, or reusable prompt templates.&lt;/p&gt;

&lt;p&gt;Without a registry, discovering those servers is fragmented. A team might find one through a GitHub repository, another through a blog post, and a third through a copied configuration snippet in a chat channel. Each installation becomes a small investigation:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;Who maintains this server?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Is the repository still active?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Which package or container should be installed?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What transport does it use?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Which version is compatible with the client?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Does it need credentials, local filesystem access, or network access?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Is the configuration snippet current?&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These questions are familiar to anyone who has managed dependencies in a software project. The difference is that MCP servers often sit directly on an agent’s action boundary. A poorly understood library can cause an application bug. A poorly understood MCP server can expose production data, execute commands, modify tickets, or trigger infrastructure changes.&lt;/p&gt;

&lt;p&gt;The registry makes the discovery problem explicit rather than treating it as an informal side effect of source-code hosting.&lt;/p&gt;

&lt;h2&gt;
  
  
  A registry entry is metadata, not magic
&lt;/h2&gt;

&lt;p&gt;An official registry should not be mistaken for an automatic trust guarantee. Listing a server makes it discoverable; it does not make its implementation safe for every environment.&lt;/p&gt;

&lt;p&gt;That distinction matters because the registry’s primary value is structured metadata. A server entry can communicate the information clients and users need to make an informed installation decision: its canonical name, human-readable description, publisher information, release versions, repository links, package coordinates, and installation options.&lt;/p&gt;

&lt;p&gt;This is a subtle but important design choice. The registry is not trying to replace every package manager, container registry, or source forge. A Node.js-oriented server may still be distributed through npm. A Python server may use PyPI. A production deployment may be packaged as a Docker image. A company may host a private build artifact in its own registry.&lt;/p&gt;

&lt;p&gt;Instead, the MCP registry acts as a common directory above those ecosystems. It answers: &lt;em&gt;what MCP server is this, where did it come from, and how is it intended to be consumed?&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;That separation gives the ecosystem room to evolve. Server authors can use the tooling that fits their stack, while MCP clients can offer a coherent discovery experience across languages and distribution formats.&lt;/p&gt;

&lt;h2&gt;
  
  
  Names become part of the integration contract
&lt;/h2&gt;

&lt;p&gt;In a mature ecosystem, naming is infrastructure.&lt;/p&gt;

&lt;p&gt;A stable server identifier allows a client to save an installation, an organization to write policy around it, and a security team to audit where it appears. It also avoids the ambiguity of generic repository names such as &lt;code&gt;github-mcp&lt;/code&gt;, &lt;code&gt;mcp-github-server&lt;/code&gt;, or &lt;code&gt;github-tools&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The registry’s namespacing model is especially useful here. A scoped or publisher-associated identity makes provenance easier to inspect and reduces collisions between unrelated projects. The practical outcome is similar to qualified package names: developers can distinguish an official integration from a community alternative without relying only on branding in a README.&lt;/p&gt;

&lt;p&gt;For teams building internal servers, this has an architectural implication. Choose a durable name early. Treat it as an API-facing identifier, not a temporary project label. Renaming a server after clients, policies, and user documentation depend on it is more expensive than renaming a repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  Versioning is a safety feature
&lt;/h2&gt;

&lt;p&gt;Agent integrations evolve quickly. A server may add a new tool, change an authentication flow, tighten an input schema, or remove a deprecated capability. Each change can affect not only a developer’s configuration but also an agent’s behavior.&lt;/p&gt;

&lt;p&gt;Registry-level version information gives consumers a way to reason about those changes deliberately.&lt;/p&gt;

&lt;p&gt;For server maintainers, this means releases should be treated as contracts. A release process should answer at least four questions:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;What changed in the MCP surface?&lt;/strong&gt; Document new, changed, and removed tools, resources, and prompts.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;How is the artifact built?&lt;/strong&gt; Make package, binary, or container builds reproducible.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Where is the source?&lt;/strong&gt; Link releases to a reviewable source repository and immutable revision where possible.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;What should consumers upgrade to?&lt;/strong&gt; Publish clear version guidance and migration notes for breaking changes.&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For consumers, version metadata supports controlled rollout. Rather than allowing every desktop installation or internal agent to pull an unspecified latest release, a platform team can pin approved versions, test upgrades in a non-production environment, and promote them through normal change management.&lt;/p&gt;

&lt;p&gt;This may sound conservative for an AI integration, but it is exactly the point. Agents create a new interface for executing work; they do not remove the need for release engineering.&lt;/p&gt;

&lt;h2&gt;
  
  
  Discovery should feed governance, not bypass it
&lt;/h2&gt;

&lt;p&gt;The most compelling use of a registry is not a button that says “install everything.” It is a better workflow for making constrained choices.&lt;/p&gt;

&lt;p&gt;Imagine an internal developer assistant searching for an MCP server that can inspect Kubernetes workloads. Registry discovery can provide candidate servers and their metadata. The organization’s policy layer can then decide whether any candidate is allowed, whether it must run in a sandbox, which versions are approved, and what credentials it may receive.&lt;/p&gt;

&lt;p&gt;That division of responsibility is healthy:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;The registry&lt;/strong&gt; provides discoverability and canonical metadata.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;The MCP client&lt;/strong&gt; provides connection and user experience.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;The server&lt;/strong&gt; implements capabilities and enforces its own authorization.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;The organization&lt;/strong&gt; defines trust, access, network, and deployment policy.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;No single layer can carry the whole security model.&lt;/p&gt;

&lt;p&gt;A registry entry cannot prove that a tool invocation is authorized. A client cannot safely infer the least-privilege credentials required by every server. A server cannot know an organization’s data-classification rules. Production adoption needs all three layers, plus observability around actual tool usage.&lt;/p&gt;

&lt;h2&gt;
  
  
  What to verify before installing a server
&lt;/h2&gt;

&lt;p&gt;A good registry makes verification easier, but teams should still establish a review checklist. Before approving an MCP server, inspect the following areas:&lt;/p&gt;

&lt;h3&gt;
  
  
  Publisher and source provenance
&lt;/h3&gt;

&lt;p&gt;Confirm who owns the namespace or publisher identity. Review the linked source repository, release history, issue activity, and maintenance model. For sensitive integrations, build from source or consume a verified artifact produced by your own pipeline.&lt;/p&gt;

&lt;h3&gt;
  
  
  Execution model
&lt;/h3&gt;

&lt;p&gt;Determine whether the server runs locally over standard input/output, remotely over HTTP, or through another supported transport. Local execution may gain access to a developer workstation. Remote execution may transmit prompts, arguments, and contextual data across a network boundary. Both models have risks; they are simply different risks.&lt;/p&gt;

&lt;h3&gt;
  
  
  Permission shape
&lt;/h3&gt;

&lt;p&gt;Read the tool descriptions as capability declarations. A server that lists repositories has a very different blast radius from one that can merge pull requests, execute shell commands, or alter cloud resources. Prefer narrow, task-specific servers over broad administrative gateways.&lt;/p&gt;

&lt;h3&gt;
  
  
  Secret handling
&lt;/h3&gt;

&lt;p&gt;Identify how authentication is configured and where tokens live. Avoid embedding long-lived credentials in shared client configuration. Use scoped tokens, short-lived credentials, environment injection through managed secret stores, and separate identities for development and production.&lt;/p&gt;

&lt;h3&gt;
  
  
  Network and data flow
&lt;/h3&gt;

&lt;p&gt;Understand which external services the server contacts and what data may leave the host environment. This is particularly important when an agent can pass file contents, database results, incident details, or customer information into tool arguments.&lt;/p&gt;

&lt;h2&gt;
  
  
  Publishing well: registry metadata as product documentation
&lt;/h2&gt;

&lt;p&gt;For authors, publishing to the official registry is not merely a distribution task. The metadata is often the first technical documentation a user sees. It should explain the server’s operational boundary with precision.&lt;/p&gt;

&lt;p&gt;A strong entry answers these questions in plain language:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;What system does this server connect to?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Which high-value tasks does it support?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What does it explicitly not do?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What authentication is required?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Is it intended for local development, self-hosting, or managed remote use?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What permissions are required for read-only versus write operations?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Where are the installation and security documents?&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Descriptions should avoid vague claims such as “full access to your workspace.” An agent-oriented tool is easier to approve when its capabilities are concrete: “search issues,” “retrieve pull request metadata,” “create a draft ticket,” or “query a read-only reporting endpoint.”&lt;/p&gt;

&lt;p&gt;For a TypeScript server, a practical publishing pipeline might validate the MCP schemas, run integration tests against a test tenant, package the release artifact, generate checksums or attestations where supported, and then submit or update registry metadata from GitHub Actions. The goal is to make the registry record an output of an auditable release process—not a manually edited afterthought.&lt;/p&gt;

&lt;h2&gt;
  
  
  The registry is the beginning of ecosystem maturity
&lt;/h2&gt;

&lt;p&gt;The official MCP server registry changes an important default. Instead of asking every user to assemble a private catalog from search results and copied configuration blocks, it creates a shared vocabulary for describing integrations.&lt;/p&gt;

&lt;p&gt;That does not eliminate the hard work. Teams still need sandboxing, authentication design, version pinning, approval workflows, logging, and incident response. Server authors still need to maintain clear contracts and secure implementations. Client developers still need to present tool capabilities in ways users can understand.&lt;/p&gt;

&lt;p&gt;But those responsibilities become easier to organize once discovery has a standard home.&lt;/p&gt;

&lt;p&gt;The long-term opportunity is not simply more tools available to more models. It is a tool ecosystem where provenance is visible, releases are traceable, capabilities are understandable, and adoption can be governed. For MCP, the registry is the catalog. The engineering practices built around it determine whether that catalog becomes a dependable foundation for production AI systems.&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>ai</category>
      <category>security</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Build a Production-Ready MCP Server in C#: Tools, Trust, and Transport</title>
      <dc:creator>Razvan Mareș</dc:creator>
      <pubDate>Fri, 20 Nov 2026 05:50:39 +0000</pubDate>
      <link>https://dev.to/razvanm4/build-a-production-ready-mcp-server-in-c-tools-trust-and-transport-8ek</link>
      <guid>https://dev.to/razvanm4/build-a-production-ready-mcp-server-in-c-tools-trust-and-transport-8ek</guid>
      <description>&lt;p&gt;Large language models are capable of reasoning over instructions, but they cannot safely operate your systems just because they can describe them. They need a controlled interface: a contract that defines what actions exist, what data can be read, and how every invocation is validated.&lt;/p&gt;

&lt;p&gt;That is the role of the &lt;strong&gt;Model Context Protocol (MCP)&lt;/strong&gt;. MCP gives AI clients a standardized way to discover and call tools, read resources, and use reusable prompts. For C# teams, it offers an appealing path: wrap existing application services, databases, internal APIs, and operational workflows in a protocol designed for agent-driven interaction.&lt;/p&gt;

&lt;p&gt;The important framing is this: an MCP server is not an AI application. It is a &lt;strong&gt;capability boundary&lt;/strong&gt;. Its job is to translate a model's structured request into a narrow, observable, authorized operation in your system.&lt;/p&gt;

&lt;p&gt;This article walks through the architecture, implementation shape, and production concerns of building an MCP server with .NET.&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with capabilities, not endpoints
&lt;/h2&gt;

&lt;p&gt;Traditional APIs are often designed around resources and HTTP verbs:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;GET /customers/{id}&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;POST /invoices&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;PATCH /orders/{id}&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;An MCP tool is designed around an &lt;strong&gt;intent&lt;/strong&gt; a model can understand and invoke. Instead of exposing every endpoint, provide a small set of precise capabilities:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;find_customer&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;get_open_invoices&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;draft_payment_reminder&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code&gt;create_support_case&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This difference is subtle but important. A model selects tools based on names, descriptions, and input schemas. A vague tool named &lt;code&gt;run_query&lt;/code&gt; creates a broad and risky decision surface. A tool named &lt;code&gt;get_customer_account_summary&lt;/code&gt;, with an explicit customer identifier and a documented response shape, creates a predictable one.&lt;/p&gt;

&lt;p&gt;Before writing code, build a capability inventory. For each proposed tool, answer these questions:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;p&gt;What business outcome does it support?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Is it read-only, advisory, or state-changing?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Which identity is authorized to invoke it?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What input values must be constrained?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;What information is safe to return to an AI client?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;How will an operator audit its use?&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If a tool cannot answer those questions clearly, it is probably too broad.&lt;/p&gt;

&lt;h2&gt;
  
  
  The three MCP primitives
&lt;/h2&gt;

&lt;p&gt;MCP servers commonly expose three kinds of functionality.&lt;/p&gt;

&lt;h3&gt;
  
  
  Tools
&lt;/h3&gt;

&lt;p&gt;Tools perform a computation or action. They can query a service, create a ticket, calculate a quote, or trigger a workflow. A tool should have a clear name, a description written for both humans and models, and a strict input schema.&lt;/p&gt;

&lt;h3&gt;
  
  
  Resources
&lt;/h3&gt;

&lt;p&gt;Resources expose contextual data that clients can read, often identified by a URI. A resource may represent product documentation, a tenant-specific configuration file, or a generated operational report. Resources are a better fit than tools when the interaction is fundamentally retrieval rather than a parameterized action.&lt;/p&gt;

&lt;h3&gt;
  
  
  Prompts
&lt;/h3&gt;

&lt;p&gt;Prompts provide reusable instruction templates. They can standardize workflows such as incident triage, code review preparation, or customer escalation summaries. Prompts are useful, but they should not become a substitute for authorization or validation. Instructions can guide a model; server-side code must enforce policy.&lt;/p&gt;

&lt;p&gt;For an initial C# implementation, tools are usually the highest-value place to begin.&lt;/p&gt;

&lt;h2&gt;
  
  
  Create a thin MCP layer over application services
&lt;/h2&gt;

&lt;p&gt;The cleanest architecture keeps protocol concerns at the edge. Your MCP server should not contain all your business logic. It should call existing application services that already understand domain rules, persistence, authorization, and transactional boundaries.&lt;/p&gt;

&lt;p&gt;A typical structure looks like this:&lt;/p&gt;

&lt;p&gt;text&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;1McpServer
2├── Tools
3│   ├── CustomerTools.cs
4│   └── InvoiceTools.cs
5├── Application
6│   ├── CustomerQueryService.cs
7│   └── InvoiceService.cs
8├── Domain
9│   ├── Customer.cs
10│   └── Invoice.cs
11└── Infrastructure
12    ├── AppDbContext.cs
13    └── ExternalBillingClient.cs
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The MCP project becomes an adapter. It receives structured arguments, validates them, calls an application service, and maps the result into a deliberately small response object.&lt;/p&gt;

&lt;p&gt;Using the .NET MCP SDK packages, a server can register tool-bearing classes through dependency injection. API names can evolve between SDK releases, but the implementation pattern is stable:&lt;/p&gt;

&lt;p&gt;csharp&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="mi"&gt;1using&lt;/span&gt; &lt;span class="nc"&gt;System&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ComponentModel&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;2using&lt;/span&gt; &lt;span class="nc"&gt;ModelContextProtocol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Server&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;3&lt;/span&gt;
&lt;span class="mi"&gt;4var&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;CreateApplicationBuilder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;args&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;5&lt;/span&gt;
&lt;span class="mi"&gt;6builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddScoped&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ICustomerQueryService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;CustomerQueryService&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;7builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Services&lt;/span&gt;
&lt;span class="mi"&gt;8&lt;/span&gt;    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AddMcpServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;9&lt;/span&gt;    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WithStdioServerTransport&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;10&lt;/span&gt;    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;WithToolsFromAssembly&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;11&lt;/span&gt;
&lt;span class="mi"&gt;12await&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Build&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;RunAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;13&lt;/span&gt;
&lt;span class="mi"&gt;14&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;McpServerToolType&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="mi"&gt;15public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CustomerTools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;ICustomerQueryService&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;17&lt;/span&gt;    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;McpServerTool&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Gets a concise account summary for one customer ID."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="mi"&gt;18&lt;/span&gt;    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nc"&gt;Task&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;CustomerSummary&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GetCustomerAccountSummaryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
&lt;span class="mi"&gt;19&lt;/span&gt;        &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"The customer's public UUID."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;20&lt;/span&gt;        &lt;span class="nc"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;21&lt;/span&gt;    &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;22&lt;/span&gt;        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nc"&gt;Guid&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;TryParse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;out&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;23&lt;/span&gt;        &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;24&lt;/span&gt;            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ArgumentException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"customerId must be a valid UUID."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;25&lt;/span&gt;        &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;26&lt;/span&gt;
&lt;span class="mi"&gt;27&lt;/span&gt;        &lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;GetSummaryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;28&lt;/span&gt;
&lt;span class="mi"&gt;29&lt;/span&gt;        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="mi"&gt;30&lt;/span&gt;        &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="mi"&gt;31&lt;/span&gt;            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;InvalidOperationException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Customer was not found."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;32&lt;/span&gt;        &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;33&lt;/span&gt;
&lt;span class="mi"&gt;34&lt;/span&gt;        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CustomerSummary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
&lt;span class="mi"&gt;35&lt;/span&gt;            &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;36&lt;/span&gt;            &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;DisplayName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;37&lt;/span&gt;            &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AccountStatus&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;38&lt;/span&gt;            &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OpenInvoiceCount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="mi"&gt;39&lt;/span&gt;    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;40&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="mi"&gt;41&lt;/span&gt;
&lt;span class="mi"&gt;42public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;CustomerSummary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
&lt;span class="mi"&gt;43&lt;/span&gt;    &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="nc"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;44&lt;/span&gt;    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nc"&gt;DisplayName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;45&lt;/span&gt;    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nc"&gt;AccountStatus&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="mi"&gt;46&lt;/span&gt;    &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="nc"&gt;OpenInvoiceCount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The code is intentionally ordinary .NET. That is a strength. Dependency injection, cancellation tokens, structured logging, EF Core, and typed records remain useful because MCP does not replace service architecture. It adds a protocol-facing integration layer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat descriptions as part of the interface
&lt;/h2&gt;

&lt;p&gt;Tool descriptions are not decoration. They are part of the model's routing and planning context.&lt;/p&gt;

&lt;p&gt;A weak description says:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Looks up customer information.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A useful description says:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Returns account status and open invoice count for one known customer UUID. Do not use for searching customers by name. Returns no payment details or contact information.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The second version communicates purpose, required context, scope, and exclusions. Those boundaries reduce accidental misuse.&lt;/p&gt;

&lt;p&gt;Names should be specific and verb-led. Prefer &lt;code&gt;get_deployment_status&lt;/code&gt; over &lt;code&gt;deployment&lt;/code&gt;, and prefer &lt;code&gt;create_draft_refund&lt;/code&gt; over &lt;code&gt;refund_customer&lt;/code&gt;. The latter sounds like an irreversible action; the former makes a review stage explicit.&lt;/p&gt;

&lt;p&gt;Input schemas deserve the same care. Avoid accepting free-form JSON when an enum, numeric range, UUID, or constrained string will work. A model is more reliable when its available choices are explicit, and your server is safer when invalid choices are impossible to represent.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use stdio locally and HTTP deliberately
&lt;/h2&gt;

&lt;p&gt;MCP supports multiple transport models. Standard input/output is a practical default for local integrations: a client launches the server as a child process and exchanges protocol messages through stdin and stdout.&lt;/p&gt;

&lt;p&gt;For a stdio server, stdout is protocol territory. Do not write diagnostic text, banners, or exception dumps to it. Route logs to stderr or to a configured telemetry sink. One stray &lt;code&gt;Console.WriteLine&lt;/code&gt; can corrupt the message stream.&lt;/p&gt;

&lt;p&gt;Remote deployment generally calls for an HTTP-based transport, often through an ASP.NET Core host. This introduces useful operational capabilities such as TLS termination, health checks, authentication middleware, rate limiting, and centralized observability. It also introduces a larger security surface.&lt;/p&gt;

&lt;p&gt;A practical progression is:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;p&gt;Build and test with stdio locally.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Containerize the server with a non-root runtime user.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Add remote transport only when a real client topology requires it.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Put authentication and authorization in front of every protected capability.&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Docker is especially useful here because it makes the runtime contract explicit: SDK version, environment variables, network access, mounted credentials, and startup command are all visible and repeatable.&lt;/p&gt;

&lt;h2&gt;
  
  
  Authorization must happen inside the tool path
&lt;/h2&gt;

&lt;p&gt;A common mistake is assuming that because an MCP client is authenticated, every requested action is authorized. Authentication answers &lt;em&gt;who is calling&lt;/em&gt;. Authorization answers &lt;em&gt;what that caller may do in this tenant, for this record, at this time&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;For multi-tenant systems, derive tenant context from trusted identity claims or server-side session state. Do not accept a &lt;code&gt;tenantId&lt;/code&gt; argument and trust it blindly. If a tool needs a target customer ID, verify that the customer belongs to the caller's permitted tenant before returning anything.&lt;/p&gt;

&lt;p&gt;State-changing tools need additional controls:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;require explicit, structured confirmation fields;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;use idempotency keys for retried operations;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;enforce business approval rules server-side;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;return a draft or preview before execution where possible;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;record immutable audit events with actor, target, arguments, outcome, and correlation ID.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A productive pattern is to separate &lt;strong&gt;prepare&lt;/strong&gt; and &lt;strong&gt;execute&lt;/strong&gt; operations. &lt;code&gt;prepare_invoice_void&lt;/code&gt; can produce the effect and validation results. &lt;code&gt;execute_invoice_void&lt;/code&gt; can require a short-lived approval token created by the preparation step. This keeps the model useful while preserving a meaningful control point for sensitive actions.&lt;/p&gt;

&lt;h2&gt;
  
  
  Design responses for decisions, not data dumps
&lt;/h2&gt;

&lt;p&gt;An MCP response is context that a model may use in subsequent reasoning. Returning an entire database row, a raw exception, or a hundred-page report is usually counterproductive.&lt;/p&gt;

&lt;p&gt;Return compact, typed, decision-ready results. Include stable IDs, statuses, short summaries, and relevant next actions. Omit secrets, unnecessary personal data, internal stack traces, and fields that encourage the model to make unsupported inferences.&lt;/p&gt;

&lt;p&gt;For large result sets, add pagination and narrow filters. Better still, expose a purpose-built summary tool. &lt;code&gt;get_sales_pipeline_summary&lt;/code&gt; is often more valuable than giving an agent unrestricted access to every opportunity record.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make failures observable and safe
&lt;/h2&gt;

&lt;p&gt;Models will call tools with incomplete context, malformed values, and occasionally invalid assumptions. Your server should fail predictably.&lt;/p&gt;

&lt;p&gt;Classify errors into categories:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Validation error&lt;/strong&gt;: the supplied input is malformed or outside allowed bounds.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Not found&lt;/strong&gt;: the requested record does not exist or is not visible to the caller.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Conflict&lt;/strong&gt;: an action cannot proceed because current state changed.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Policy denial&lt;/strong&gt;: the caller is authenticated but not authorized.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Transient dependency failure&lt;/strong&gt;: a downstream system is unavailable.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Log the full diagnostic context internally, but return concise client-safe messages. Include a correlation ID so an operator can locate the corresponding trace without exposing internals to the model.&lt;/p&gt;

&lt;p&gt;OpenTelemetry is a strong fit for this layer. Create an activity for each tool invocation and attach tool name, tenant-safe identifiers, duration, result category, and downstream dependency timings. Do not casually attach raw prompts, credentials, or sensitive arguments as telemetry attributes.&lt;/p&gt;

&lt;h2&gt;
  
  
  A server is ready when it can say no well
&lt;/h2&gt;

&lt;p&gt;The most valuable MCP server is not the one with the most tools. It is the one whose capabilities are easy to discover, difficult to misuse, and simple to audit.&lt;/p&gt;

&lt;p&gt;Start with a small read-only surface. Put typed application services behind clearly named tools. Make descriptions precise, schemas narrow, outputs compact, and authorization non-negotiable. Then add state-changing operations only after you have confirmation flows, idempotency, audit events, and production telemetry.&lt;/p&gt;

&lt;p&gt;C# is well suited to this work because the hard parts are familiar: contracts, dependency injection, validation, domain boundaries, structured logging, and reliable hosting. MCP simply gives those engineering practices a new edge—one where software is operated not only by screens and scripts, but by carefully constrained AI clients.&lt;/p&gt;

</description>
      <category>csharpmcp</category>
      <category>dotnet</category>
      <category>ai</category>
    </item>
  </channel>
</rss>
