Skip to content

Part 1: The Foundations of Production .NET Services

Part 1: The Foundations of Production .NET Services A practical guide for building, operating, and deploying reliable ASP.NET Core services on AWS. Audience: .NET developers moving from working APIs to production service...

Ekanatha Reddy Urivakili27 min4,897 words

Part 1: The Foundations of Production .NET Services

A practical guide for building, operating, and deploying reliable ASP.NET Core services on AWS.

Audience: .NET developers moving from working APIs to production services.

Reference example: an Orders API using ASP.NET Core, EF Core, PostgreSQL, and Amazon ECS Fargate.

Prepared: 24 October 2026. Commands and configuration are instructional examples; this document does not provision or deploy resources.

1. What you will learn

  • Define what makes a service ready for production.
  • Organise a .NET application around clear responsibilities.
  • Understand request processing, dependency injection, and asynchronous I/O.
  • Design secure APIs and dependable database operations.
  • Add configuration validation, health checks, logs, metrics, and traces.
  • Package a service as a Linux container.
  • Deploy it behind HTTPS on AWS with private networking and managed persistence.
  • Validate a release, recover from failures, and understand deployment trade-offs.

Reference assumptions

  • Use .NET 10 LTS with current security patches; confirm support before starting a new project. [S1]
  • Build one independently deployable Orders service first.
  • Use PostgreSQL for the worked AWS example. The same principles apply to SQL Server, but providers, SQL syntax, licensing, and operational settings differ.
  • Start with synchronous HTTP request handling for short operations; introduce a durable queue for work that must survive an API process restart.
  • Choose ECS Fargate here to run containers without managing EC2 hosts. This is a design choice for this example, not a universal requirement.
  • Use eu-west-2 for the sample commands. Select the region based on residency, dependency availability, latency, and business requirements.

2. Working software versus production software

A production service needs predictable behaviour when users, dependencies, infrastructure, or deployments fail.

ConcernDevelopment shortcutProduction foundation
ConfigurationValues copied into codeEnvironment-specific settings validated at startup
CredentialsPassword in a settings fileManaged secrets and least-privilege identities
Failure handlingUnhandled exceptionConsistent error contract and correlated diagnostics
PersistenceHappy-path insertsConstraints, transactions, concurrency control, backups
ScalingOne local processStateless replicas and explicit capacity limits
DeploymentReplace files manuallyVersioned image, automated checks, controlled rollout
OperationsRead console outputSearchable logs, metrics, traces, alarms, runbooks
RecoveryRestart and hopeRollback procedure and tested restore process

Define measurable service goals

  • Identify the critical user journey: create an order and retrieve its status.
  • Define availability and latency targets with the product owner.
  • Example targets for discussion: 99.9% monthly availability and p95 read latency below 300 ms at the agreed load.
  • Define the measurement point, eligible requests, observation window, and exclusions before treating a target as an SLO.
  • Agree recovery time objective (RTO): how long the business can tolerate an outage.
  • Agree recovery point objective (RPO): how much data loss the business can tolerate.
  • Treat these figures as requirements to validate with testing and recovery exercises.

3. Start with a service boundary

Orders service responsibilities

  • Accept order requests.
  • Validate products, quantities, and relevant customer ownership.
  • Calculate or verify trusted prices on the server.
  • Persist orders atomically.
  • Return order status to authorised users.
  • Emit a durable event when downstream work is introduced.

Keep boundaries explicit

  • The Orders service owns its order tables and schema changes.
  • Other services use its API or published events rather than updating its tables directly.
  • Keep payment processing outside database transactions that hold locks while waiting on a remote API.
  • Avoid splitting every entity into a separate microservice.
  • A modular monolith is a valid starting point when modules share deployment and ownership needs.
  • Split services when independent deployment, security isolation, scaling, or team ownership justifies the operational cost.
flowchart TD
    Client["Web or mobile client"] --> Api["Orders API"]
    Api --> Application["Order use cases"]
    Application --> Domain["Business rules"]
    Application --> Data["Persistence adapter"]
    Data --> Db[("Orders database")]
    Application --> External["External service adapter"]
  • HTTP and persistence details stay at the edges.
  • Business rules should be testable without starting a web server.
  • The diagram shows runtime calls; source-code dependencies should point toward application contracts and domain rules.

4. A practical solution structure

Use this structure when the service has enough business behaviour to benefit from separate projects. A small CRUD service can start with feature folders in one project.

Orders/
  src/
    Orders.Api/
      Endpoints/
      Middleware/
      Configuration/
      Program.cs
      appsettings.json
      Orders.Api.csproj
    Orders.Application/
      Orders/
      Abstractions/
      Orders.Application.csproj
    Orders.Domain/
      Orders/
      Orders.Domain.csproj
    Orders.Infrastructure/
      Persistence/
      Integrations/
      Orders.Infrastructure.csproj
  tests/
    Orders.UnitTests/
    Orders.IntegrationTests/
  deploy/
    task-definition.json
    infrastructure/
  Dockerfile
  .dockerignore
  README.md
ProjectResponsibilityTypical dependencies
DomainEntities, invariants, value objectsStandard library
ApplicationUse cases and interfacesDomain
InfrastructureEF Core and external adaptersApplication and Domain
APIHTTP contract and composition rootApplication; Infrastructure for registration
  • Keep dependencies deliberate; do not create a generic repository merely to wrap every EF Core operation.
  • Use DTOs at HTTP boundaries rather than exposing tracked database entities.
  • Keep naming aligned with business operations, such as CreateOrder, rather than generic helper classes.
  • Record significant decisions in short architecture decision records.

5. Understand the ASP.NET Core request lifecycle

flowchart TD
    Request["Incoming request"] --> Proxy["Trusted proxy headers"]
    Proxy --> Errors["Exception handling and tracing"]
    Errors --> Routing["Routing and request limits"]
    Routing --> Auth["Authentication"]
    Auth --> Access{"Authorised?"}
    Access -->|No| Reject["401 or 403"]
    Access -->|Yes| Validate["Validate input"]
    Validate --> Valid{"Valid?"}
    Valid -->|No| Bad["400 validation response"]
    Valid -->|Yes| Handler["Execute use case"]
    Handler --> Response["Serialize response"]

Middleware principles

  • Order matters: exception handling must surround work whose failures it should handle.
  • Process trusted forwarded headers before logic that depends on the original scheme or client IP. [S3]
  • Put authentication before authorisation.
  • Place endpoint-specific rate limiting after routing; place it after authentication when partitions depend on user identity.
  • Configure CORS only for known browser origins that need cross-origin access.
  • CORS is a browser policy; it does not authenticate clients.
  • Serve public OpenAPI documentation only when that is an intentional access decision.
  • Do not return stack traces or database connection details to clients.

HTTPS behind an AWS load balancer

  • Terminate public TLS at the Application Load Balancer (ALB) using an ACM certificate.
  • Redirect public HTTP to HTTPS at the ALB listener.
  • The example uses HTTP from ALB to tasks inside the VPC; choose backend TLS when required by the threat model or compliance requirements.
  • If the application consumes forwarded headers, explicitly trust the actual proxy addresses or narrowly scoped networks and set an appropriate forwarding limit.
  • Do not clear all trusted proxy restrictions to make HTTPS redirects work.
  • An API using ALB-managed HTTPS can avoid application-level redirect loops by keeping redirect ownership at the ALB.

6. Dependency injection and service lifetimes

LifetimeBehaviourTypical useCommon mistake
TransientNew instance each time it is resolvedLightweight stateless componentsExpensive repeated construction
ScopedOne instance per scope, usually per HTTP requestEF Core DbContext and request use casesCapturing it in a singleton
SingletonOne instance per application containerThread-safe shared servicesMutable state without synchronisation
  • Keep DbContext scoped and avoid using the same instance concurrently.
  • Use constructor injection to make dependencies visible.
  • Do not use the service provider as a general-purpose service locator.
  • A singleton background worker must create a scope for scoped dependencies.
  • Keep request state out of singleton fields.
  • Use IHttpClientFactory for centrally configured outbound HTTP clients. [S2]
// Registration fragment in Program.cs for the example application.
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddHttpClient("catalogue", client =>
{
    client.BaseAddress = new Uri("https://catalogue.example.com/");
    client.Timeout = TimeSpan.FromSeconds(3);
});
  • The catalogue URI is a placeholder.
  • Do not register an external dependency unless the service actually needs it.

7. Async I/O, cancellation, and bounded concurrency

  • Use asynchronous database and HTTP APIs end to end.
  • Pass the request cancellation token into supported downstream operations.
  • Avoid .Result, .Wait(), and blocking I/O on request paths. [S2]
  • Do not wrap asynchronous I/O in Task.Run to make it asynchronous.
  • An await can release the request thread while I/O is incomplete; it does not allocate a dedicated waiting thread or guarantee a thread switch.
  • CPU work still occupies a thread. Large CPU workloads need bounded execution and usually a separate worker.
  • Limit concurrent downstream calls; unbounded Task.WhenAll can overwhelm a connection pool or dependency.
  • Keep database transactions short.
// Read-path fragment: requires an EF Core DbContext with an Orders DbSet.
var order = await db.Orders
    .AsNoTracking()
    .Where(x => x.Id == orderId && x.CustomerId == customerId)
    .Select(x => new OrderSummary(x.Id, x.Status, x.Total))
    .SingleOrDefaultAsync(cancellationToken);
  • The ownership filter is part of the data access, not an assumption based on an order ID.
  • Derive customerId from a validated identity or trusted server-side mapping.
  • AsNoTracking suits read-only queries; use tracking deliberately for changes.
sequenceDiagram
    autonumber
    participant Client
    participant API
    participant DB as Database
    Client->>API: Request order
    API->>DB: Start asynchronous query
    Note over API: Await incomplete I/O; thread can serve other work
    DB-->>API: Query completes
    Note over API: Continuation runs on an available thread
    API-->>Client: Return order response

8. API contracts and predictable errors

Suggested endpoints

Method and routePurposeTypical success
POST /api/ordersCreate an order201 Created with Location header
GET /api/orders/{id}Retrieve an owned order200 OK
GET /api/orders?cursor=...&limit=...List a bounded page200 OK
POST /api/orders/{id}/cancelRequest a valid state transition200 OK or 204 No Content
GET /health/liveProcess liveness200 OK
GET /health/readyReadiness to receive traffic200 OK or 503

Input and error rules

  • Reject invalid quantities, missing fields, unsupported states, oversized payloads, and invalid identifiers.
  • Cap page sizes and use deterministic ordering.
  • Use a consistent Problem Details response for errors.
  • Return 401 when authentication is required or invalid; 403 when an authenticated identity lacks permission.
  • Decide consistently whether inaccessible resources return 404 to avoid disclosing their existence.
  • Return 409 for a conflict with current state or a conflicting idempotency request.
  • Return 429 for throttling and supply retry guidance where appropriate.
  • Include a trace identifier that helps operators find the failure.
{
  "type": "https://api.example.com/problems/order-state-conflict",
  "title": "Order cannot be cancelled",
  "status": 409,
  "detail": "The order has already been dispatched.",
  "traceId": "example-trace-id"
}

Idempotency for create operations

  • Accept an idempotency key for client retries where duplicate effects are costly.
  • Scope the key to the authenticated caller and operation.
  • Persist the key, a request fingerprint, processing state, and reusable result with a uniqueness constraint.
  • Make the key reservation and order write atomic where possible.
  • Return the prior result for the same completed request; reject a reused key with a different payload.
  • Define behaviour for concurrent requests and abandoned in-progress records.
  • Document retention and expiry; an expired key cannot prevent all future duplicates.

9. Data integrity and database performance

  • Use constraints for invariants that must hold across concurrent requests.
  • Use parameterised EF Core queries or parameterised SQL; never concatenate untrusted input into SQL.
  • Index actual lookup and filtering patterns, such as customer plus creation time.
  • Inspect execution plans and query counts under representative data volumes.
  • Project only required columns and avoid N+1 queries.
  • Use optimistic concurrency for conflicting updates and translate conflicts into a clear API response.
  • Use a transaction for related writes that must succeed together.
  • Bound command timeouts and connection pool capacity.
  • Calculate connection capacity across all replicas, workers, migration jobs, and deployment surge tasks.
  • Use UTC timestamps and an appropriate monetary representation such as decimal plus a currency code.
  • Use a restricted application database user; separate schema migration permissions.
  • Enable backups and point-in-time recovery where required, then test restoration.

Safe schema changes

flowchart TD
    Expand["Add compatible schema"] --> Deploy["Deploy compatible application"]
    Deploy --> Backfill["Backfill data in bounded batches"]
    Backfill --> Verify{"Data and traffic verified?"}
    Verify -->|No| Investigate["Investigate; retain compatibility"]
    Investigate --> Verify
    Verify -->|Yes| Contract["Remove old schema in a later release"]
  • Run migrations as an explicit deployment job with one migration executor.
  • Do not have every API replica race to apply migrations on startup.
  • A rolling release temporarily runs old and new binaries together.
  • Application rollback does not undo database changes.
  • Keep schema compatible with the previous image until the rollback window closes.

10. Configuration and secrets

  • Store safe defaults in appsettings.json.
  • Supply environment-specific settings through deployment configuration.
  • Use .NET user secrets for local development; they are a development convenience, not an encrypted production vault.
  • Store production credentials in Secrets Manager or an appropriate encrypted parameter store. [S7]
  • Inject the database connection string using the .NET environment-variable key ConnectionStrings__Orders.
  • Validate required values at startup so misconfigured tasks fail before receiving traffic.
  • Never log the configuration tree, connection strings, access tokens, or secret values.
  • When ECS injects a secret at task startup, rotation does not update running task environments; launch replacement tasks. [S7]
  • Use workload IAM roles for AWS access rather than static AWS access keys.
// Options fragment with domain-specific validation added.
builder.Services.AddOptions<OrderOptions>()
    .Bind(builder.Configuration.GetSection("Orders"))
    .Validate(x => x.MaxItems is > 0 and <= 1000,
        "Orders:MaxItems must be between 1 and 1000.")
    .ValidateOnStart();

public sealed class OrderOptions
{
    public int MaxItems { get; set; }
}

11. Security foundations

Identity and access

  • Use a trusted identity provider and validate JWT signature, issuer, audience, and expiry.
  • Enforce ownership and tenant isolation for every resource access.
  • Apply operation-level permissions, including administrative and bulk endpoints.
  • Never trust a caller-supplied tenant or customer ID without authorisation.
  • Give the application role access only to the AWS resources it uses.

HTTP and application controls

  • Require HTTPS at the public boundary.
  • Set request size limits, accepted content types, and bounded execution budgets.
  • Use rate limits and abuse controls; in-process counters apply per replica unless backed by a shared design.
  • Protect cookie-authenticated state-changing requests against CSRF. SameSite settings support the defence but should be assessed with the complete authentication flow.
  • A bearer-token API without automatically attached authentication cookies has a different CSRF exposure; XSS and token theft remain relevant.
  • Apply CSP to pages that render HTML and scripts; CSP does not replace API authorisation.
  • Prevent SSRF when fetching caller-provided URLs: constrain destinations, redirects, DNS resolution, and internal or metadata address access.
  • Redact personal data and set log retention deliberately.
  • Keep runtime, NuGet packages, base images, and operating-system layers patched.
  • Scan source, dependencies, and images; triage findings rather than treating a green scanner as proof of security.

12. Reliability when dependencies fail

ControlPurposeExample rule
TimeoutBound waitingSet an operation budget and shorter dependency budgets
CancellationStop unnecessary workPropagate cancellation where supported
Retry with jitterRecover from transient errorsLimited retries within the total budget
Circuit breakerAvoid repeated calls to a failing dependencyReject temporarily after a configured failure threshold
Concurrency limitBound pressureCap simultaneous calls to the catalogue
IdempotencyAvoid duplicate effectsPersist request keys for order creation
Durable queueSurvive process lossPersist work before acknowledging acceptance
  • Retry only failures likely to be transient.
  • Do not retry non-idempotent writes unless their semantics make retries safe.
  • Avoid nested retry policies that multiply attempts.
  • Treat a database commit timeout as an uncertain outcome; reconcile before blindly repeating writes.
  • Use an outbox when a database write and an outgoing event must remain consistent.
  • A BackgroundService alone does not make an in-memory job durable.
  • Keep the detailed queue, outbox, and worker implementation for a later part; recognise the boundary now.

13. Observability and health checks

Logs

  • Emit structured JSON logs to standard output.
  • Include service name, environment, deployment version, trace ID, operation, duration, and outcome.
  • Use message templates rather than string interpolation for searchable properties.
  • Redact tokens, passwords, payment details, and unnecessary personal information.
logger.LogInformation(
    "Order {OrderId} created in {ElapsedMs} ms", order.Id, elapsedMs);

Metrics and traces

  • Track request count, error rate, p50/p95/p99 latency, and throughput.
  • Monitor CPU, memory, thread-pool pressure, database connection usage, and dependency latency.
  • Track business signals such as order creation failures separately from HTTP failures.
  • Use OpenTelemetry instrumentation and a configured exporter or collector for end-to-end tracing.
  • Do not put order IDs, email addresses, or user IDs into metric labels; high cardinality makes metrics expensive and hard to use.
  • Connect actionable alarms to an on-call owner and a runbook.

Liveness and readiness

  • Liveness asks whether the process is functioning; do not make it depend on database availability.
  • Readiness asks whether the instance can serve its intended traffic.
  • Register lightweight dependency checks only where their failure should remove an instance from traffic. [S4]
  • Use bounded probe timeouts and avoid costly database queries.
  • Do not disclose internal diagnostic detail in public health responses.
  • Consider fleet-wide outages: making every replica unready does not repair a failed shared database.
  • ALB can fail open when all registered targets are unhealthy; readiness is not an access-control boundary. [S10]
// Health endpoint fragment; register actual ready-tagged checks separately.
builder.Services.AddHealthChecks();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
});
  • Import Microsoft.AspNetCore.Diagnostics.HealthChecks.
  • With no registered readiness checks, /health/ready does not verify database connectivity.
  • Define an IHealthCheck or deliberately selected integration for the actual dependency probe before using this as a production readiness signal.
  • Allow health endpoints without user authentication, restrict detailed output, and block public listener access to health paths if only internal probing is required.

14. Containerise the service

Example Dockerfile

This assumes the solution structure from section 4, no private package feed, and an API assembly named Orders.Api.dll.

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore src/Orders.Api/Orders.Api.csproj
RUN dotnet publish src/Orders.Api/Orders.Api.csproj \
    --configuration Release \
    --no-restore \
    --output /app/publish \
    /p:UseAppHost=false

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
USER app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "Orders.Api.dll"]

Example .dockerignore

**/bin/
**/obj/
.git/
.env
.env.*
**/appsettings.*.local.json
**/*.pfx
**/*.pem
TestResults/
  • Keep secrets out of the build context and image layers.
  • Run the container as a non-root user.
  • Pin approved image digests in the production build process and rebuild deliberately for security patches.
  • Keep the runtime image separate from the SDK build stage.
  • Use an explicit image architecture that matches the ECS task runtime platform.
  • Write logs to stdout; do not rely on container-local files for durable storage.
  • Ensure shutdown drains work within the container stop timeout and ALB deregistration settings.
  • The Dockerfile is a template; build and smoke-test it against the actual application.

15. AWS reference architecture

flowchart TD
    User["API client"] --> DNS["Route 53 DNS"]
    DNS --> ALB["Public ALB with ACM HTTPS"]
    WAF["AWS WAF web ACL"] -.-> ALB
    subgraph VPC["VPC across two Availability Zones"]
        ALB --> A["Private Fargate task in AZ A"]
        ALB --> B["Private Fargate task in AZ B"]
        A --> DB[("Private RDS PostgreSQL Multi-AZ")]
        B --> DB
    end
    A --> Logs["CloudWatch logs and metrics"]
    B --> Logs
  • Route 53 resolves the domain to the ALB; it does not proxy application traffic.
  • Associate the WAF web ACL with the ALB when filtering or abuse controls are needed.
  • The ALB spans public subnets in two Availability Zones.
  • The ECS service runs at least two tasks spread across the selected private application subnets; verify actual placement.
  • RDS uses private database subnets and is not publicly accessible.
  • Multi-AZ improves availability; it does not replace backups or guarantee zero interruption during failover.
  • ECR stores container images; Secrets Manager stores credentials.
  • A separate worker service and SQS can be added when asynchronous workflows are required.

AWS component responsibilities

ComponentResponsibilityImportant setting
ECRContainer image registryImmutable release references and scanning policy
ECS cluster and serviceSchedule and maintain tasksDesired count, deployment policy, autoscaling
FargateManaged task computeCorrect CPU, memory, architecture
ALB and target groupHTTP routing and probesHTTPS listener, ip targets, port 8080
ACMPublic TLS certificateCertificate in the ALB region
RDS PostgreSQLDurable relational storageEncryption, backups, Multi-AZ as required
Secrets ManagerStore connection credentialsNarrow access and rotation procedure
CloudWatchLogs, metrics, alarmsRetention, ownership, alert thresholds
IAMService identities and permissionsSeparate execution, application, and deployment roles
VPC endpoints or NATOutbound connectivityExplicit routes and security groups

Network boundaries

Security groupInbound rulePurpose
ALBTCP 443 from approved clients, or internet for a public APIPublic HTTPS
ALBTCP 80 if HTTP redirect is supportedRedirect to HTTPS
API tasksTCP 8080 from ALB security group onlyApplication traffic and ALB probes
DatabaseTCP 5432 from API and approved migration-task security groupsPostgreSQL
Interface endpointsTCP 443 from relevant task security groupsPrivate AWS API access
  • Disable public IP assignment for API tasks.
  • Use Fargate awsvpc networking and an ALB target group with target type ip. [S6, S8]
  • Ensure tasks can pull images, retrieve injected secrets, and send logs before removing NAT connectivity.
  • A private endpoint design commonly needs ECR API and Docker interface endpoints, an S3 gateway endpoint for image layers, and interface endpoints for Logs and Secrets Manager.
  • Enable private DNS, configure endpoint policies, and permit network paths to the endpoints.
  • External services still need a suitable outbound path; ECR endpoints do not provide general internet access.
  • Compare NAT and endpoint costs against actual traffic and Availability Zone design.

16. AWS deployment walkthrough

Step 1: Prepare the application

  • Build the application with its supported SDK and lock the intended package versions.
  • Implement authentication, ownership checks, startup validation, and real health probes.
  • Confirm that ConnectionStrings__Orders is consumed by the database registration.
  • Run unit and integration tests against the intended database engine.
  • Verify local container startup and the health endpoints.
  • Use disposable test data, not production credentials.

Step 2: Provision the infrastructure

  • Define the VPC, subnets, routing, security groups, endpoints or NAT, ECR, ECS, ALB, RDS, secrets, and monitoring using reviewed infrastructure as code.
  • Prefer separate AWS accounts for production and non-production where feasible.
  • Create the ACM certificate and validate the domain.
  • Configure the HTTPS listener and ip target group on port 8080.
  • Set the target-group health path to /health/ready and success code to 200.
  • Configure realistic startup grace, health thresholds, and deregistration timing.
  • Enable database encryption, backup retention, and production deletion protection.
  • Create CloudWatch log groups with explicit retention before tasks start.
  • These resources are prerequisites for the following CLI fragments; the fragments do not create the full infrastructure.

Step 3: Create the IAM roles

  • Execution role: used by ECS for image pulls, log delivery, and task-definition secret injection. Scope additional secret and KMS permissions to the selected resources. [S5]
  • Task role: used by application code for AWS SDK calls. Grant only resources and actions the application needs.
  • Deployment role: used by CI to register task definitions and update the selected ECS service.
  • Restrict iam:PassRole to the intended task and execution roles and relevant AWS service.
  • Use CI workload federation, such as an OIDC trust scoped to the approved repository and deployment environment, rather than long-lived access keys.

Step 4: Build and push a release image

Run these Bash commands from the solution root with Docker, AWS CLI, and an authorised AWS session. The ECR repository must already exist. The example targets Linux x86-64 explicitly.

export AWS_REGION=eu-west-2
export AWS_ACCOUNT_ID="<your-account-id>"
export ECR_REPOSITORY=orders-api
export RELEASE_TAG="<immutable-release-id>"
export IMAGE_URI="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}:${RELEASE_TAG}"

aws sts get-caller-identity

aws ecr get-login-password --region "$AWS_REGION" \
  | docker login --username AWS --password-stdin \
    "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

docker buildx build \
  --platform linux/amd64 \
  --tag "$IMAGE_URI" \
  --load .

docker push "$IMAGE_URI"
  • Replace placeholders before running commands.
  • Use a release ID or full commit SHA; do not deploy mutable latest references.
  • Resolve and record the image digest after push and use the digest in the release task definition.
  • Scan the image and enforce the agreed vulnerability policy before promotion.
  • Build once, then promote the same image digest through environments.

Step 5: Register a task definition

The following JSON is a template. Replace every angle-bracket placeholder; it is not directly deployable as written. The secret value is a complete PostgreSQL connection string for the restricted application user, configured with verified TLS according to the driver and RDS certificate setup.

{
  "family": "orders-api",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "runtimePlatform": {
    "operatingSystemFamily": "LINUX",
    "cpuArchitecture": "X86_64"
  },
  "executionRoleArn": "<execution-role-arn>",
  "taskRoleArn": "<application-task-role-arn>",
  "containerDefinitions": [
    {
      "name": "orders-api",
      "image": "<ecr-repository-uri>@sha256:<image-digest>",
      "essential": true,
      "stopTimeout": 60,
      "portMappings": [
        { "containerPort": 8080, "protocol": "tcp" }
      ],
      "environment": [
        { "name": "ASPNETCORE_ENVIRONMENT", "value": "Production" },
        { "name": "ASPNETCORE_HTTP_PORTS", "value": "8080" },
        { "name": "Orders__MaxItems", "value": "100" }
      ],
      "secrets": [
        {
          "name": "ConnectionStrings__Orders",
          "valueFrom": "<secrets-manager-connection-string-arn>"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/orders-api",
          "awslogs-region": "eu-west-2",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}
  • The example starts at 0.5 vCPU and 1 GiB RAM; validate sizing with representative traffic.
  • This definition relies on ALB health checks; it does not include a container health command.
  • If adding container liveness, include a suitable probe executable in the image rather than assuming curl is present.
  • Configure application graceful shutdown to fit inside stopTimeout; verify behaviour with in-flight requests.
aws ecs register-task-definition \
  --region "$AWS_REGION" \
  --cli-input-json file://deploy/task-definition.json
  • Record the returned revision ARN; do not guess the revision number.

Step 6: Run migrations and roll out the service

  • Run reviewed compatible migrations using a dedicated one-off task with the same network access to RDS.
  • Wait for the migration task and check its exit code; stop the release if it fails.
  • For the initial service creation, bind the existing target group to container orders-api, port 8080, and select the private subnets and API security group.
  • Set desired count to two, disable public IP assignment, and configure health-check grace time.
  • For later releases, update the existing service using the registered task-definition ARN.
  • Enable the ECS rolling deployment circuit breaker with rollback. It requires an earlier completed deployment to roll back to; the first deployment has no previous working release. [S9]
export ECS_CLUSTER=production-services
export ECS_SERVICE=orders-api
export TASK_DEFINITION_ARN="<returned-task-definition-arn>"

aws ecs update-service \
  --region "$AWS_REGION" \
  --cluster "$ECS_CLUSTER" \
  --service "$ECS_SERVICE" \
  --task-definition "$TASK_DEFINITION_ARN" \
  --deployment-configuration \
    'minimumHealthyPercent=100,maximumPercent=200,deploymentCircuitBreaker={enable=true,rollback=true}'

aws ecs wait services-stable \
  --region "$AWS_REGION" \
  --cluster "$ECS_CLUSTER" \
  --services "$ECS_SERVICE"
  • The update command assumes the ECS service already exists and uses the rolling deployment controller.
  • Keep sufficient subnet IP space, task quota, and database connection headroom for surge capacity.
  • A stability waiter alone is insufficient: a successful rollback can leave the service stable on the old revision.
  • Inspect service deployments and confirm the primary task definition matches the intended ARN and the rollout completed.

Step 7: Validate the release

  • Confirm both intended replicas are healthy and the deployed image digest is correct.
  • Verify HTTPS hostname and certificate validation.
  • Test an authenticated order creation and retrieval with a controlled test account.
  • Verify invalid requests, ownership isolation, and unauthorised access.
  • Check logs and traces for the new deployment version.
  • Watch latency, errors, resource usage, and database connections during the observation window.
  • Test task replacement and assess the behaviour of a dependency timeout.
  • Confirm alarms reach the responsible team.

Step 8: Roll back when needed

  • If startup or health checks fail, allow the configured deployment circuit breaker to act and inspect the result.
  • If business-level smoke tests fail after rollout, update the service to the recorded previous compatible task-definition ARN.
  • Wait for stability, verify the active revision, and repeat smoke tests.
  • Do not assume image rollback repairs corrupt data or reverses a migration.
  • Use the restore or data-repair runbook when the failure affects stored data.

17. Delivery pipeline and release gates

flowchart TD
    Change["Pull request"] --> Checks["Build, tests, and security checks"]
    Checks --> Pass{"Checks pass?"}
    Pass -->|No| Fix["Fix and review"]
    Fix --> Change
    Pass -->|Yes| Image["Build and scan release image"]
    Image --> Stage["Deploy same digest to staging"]
    Stage --> Verify{"Smoke and load checks pass?"}
    Verify -->|No| Stop["Stop promotion"]
    Verify -->|Yes| Release["Run compatible migration and deploy production"]
    Release --> Observe{"Revision and user journey healthy?"}
    Observe -->|Yes| Complete["Complete release"]
    Observe -->|No| Rollback["Restore previous compatible revision"]
  • Run focused unit tests for pricing rules, state transitions, and validation.
  • Use integration tests for constraints, transactions, query behaviour, and concurrent updates.
  • Test authorisation with multiple users and tenants.
  • Test duplicate and concurrent idempotency requests.
  • Build and smoke-test the actual container image.
  • Load-test an agreed workload, including error paths and realistic data sizes.
  • Exercise deployment and rollback in staging.
  • Preserve release provenance: commit, digest, task-definition ARN, migration version, and validation result.

18. Scaling, availability, and cost

Scale deliberately

  • Use measured demand to choose task CPU and memory.
  • Start with CPU or ALB request-count scaling where it correlates with the workload; add more suitable signals as needed.
  • Define minimum and maximum task counts and scale-in cooldowns.
  • Keep session and durable state outside the task.
  • For cookie authentication across replicas, share and protect ASP.NET Core Data Protection keys as required.
  • Check the database and downstream capacity before increasing replica limits.
  • Spread tasks across Availability Zones and verify replacement behaviour.
  • Multi-AZ in one region does not provide a complete regional disaster recovery strategy.

Understand the bill

  • Include Fargate compute, ALB, RDS, NAT gateways or endpoints, CloudWatch, ECR, WAF where used, backups, and data transfer.
  • Set budgets and anomaly alerts before production use.
  • Tune log retention and trace sampling without losing incident evidence.
  • Avoid exact cost commitments without region, traffic, retention, and availability requirements.
  • A smaller development environment can use fewer resources; do not assume it demonstrates production availability.

19. Common failure scenarios

SymptomLikely investigationFirst corrective direction
Task cannot pull imageECR URI, execution role, DNS, NAT or endpointsRestore registry connectivity and permissions
Task fails retrieving secretSecret ARN, execution role, KMS and endpoint accessCorrect scoped secret access
ALB reports unhealthy targetPort 8080, health path, security groups, startup timeAlign task, target group, and probe configuration
Repeated HTTPS redirectsForwarded scheme and redirect ownershipCorrect trusted proxy configuration or edge redirects
Database timeouts at scaleSlow queries, pool saturation, connection limitsInspect plans and bound concurrency
High latency with low CPUBlocking calls, dependency waits, pool contentionInspect traces and thread-pool signals
Duplicate ordersMissing or non-atomic idempotency handlingEnforce persisted uniqueness and replay semantics
Tasks fail after secret rotationCredentials differ between running tasks and RDSCoordinate rotation and task replacement
New release breaks old tasksIncompatible schema changeRestore compatibility; use expand-and-contract
Service stable on wrong versionCircuit breaker rolled backInspect rollout state and active task-definition ARN

20. Production readiness checklist

Application

  • Service ownership, supported runtime, and upgrade policy are documented.
  • Business rules and API contracts have meaningful tests.
  • Authentication, ownership, tenant isolation, and validation are enforced.
  • Error responses are consistent and do not leak internal information.
  • I/O is asynchronous, timeouts are bounded, and cancellation is propagated.
  • Duplicate requests and concurrency conflicts have defined outcomes.

Data and security

  • Database constraints and indexes match the workload.
  • Runtime credentials have restricted privileges.
  • Secrets are externalised, redacted, and covered by a rotation procedure.
  • Backup retention, restore testing, RTO, and RPO are agreed.
  • Schema changes preserve the required rollback window.
  • Dependencies and images meet the agreed security policy.

AWS and operations

  • ALB HTTPS and certificate validation work.
  • API tasks and RDS have the intended private network boundaries.
  • Registry, secrets, logs, and external dependency connectivity are verified.
  • Intended task count and Availability Zone placement are verified.
  • Health checks distinguish process health from dependency readiness.
  • Logs, metrics, traces, alarms, and runbooks are usable.
  • Task shutdown, replacement, deployment, and rollback have been exercised.
  • The active image digest and task-definition ARN are recorded.
  • Cost budgets, retention, and capacity limits are configured.

21. Suggested hands-on exercise

  • Build the Orders API with create, get, list, and cancel operations.
  • Add PostgreSQL persistence, ownership filtering, and optimistic concurrency.
  • Add persisted idempotency for order creation.
  • Add startup validation and meaningful health checks.
  • Containerise the API using a non-root runtime image.
  • Deploy a staging environment using infrastructure as code.
  • Deploy two Fargate tasks behind an HTTPS ALB.
  • Run a controlled load test and record p95 latency, error rate, and database connections.
  • Release an intentionally unhealthy image in staging and confirm rollback behaviour.
  • Restore a database backup into an isolated environment and measure recovery time.
  • Record the design decisions and evidence needed to pass the readiness checklist.

Completion criteria

  • An authorised user can create and retrieve an order over HTTPS.
  • A different user cannot retrieve that order without the required permission.
  • Repeating the same idempotent create request does not create a second order.
  • Stopping one task does not lose acknowledged orders.
  • A failed release is detected and recovery to a known version is demonstrated.
  • An operator can trace a failed request and follow a recovery runbook.

22. Realistic code examples

To complement the architectural guidance, here are two realistic code examples from our .NET 10 Orders API stack showcasing typical usage of EF Core with async operations and a complete minimal API endpoint.

Code Example 1: Creating an Order with Idempotency and Dependency Injection

This example shows a simplified service method to create a new order with idempotency key handling, cancellation support, validation, and atomic database transaction.

public class OrderService : IOrderService
{
    private readonly OrdersDbContext _dbContext;
    private readonly ILogger<OrderService> _logger;

    public OrderService(OrdersDbContext dbContext, ILogger<OrderService> logger)
    {
        _dbContext = dbContext;
        _logger = logger;
    }

    public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request, string idempotencyKey, CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(idempotencyKey))
            throw new ArgumentException("Idempotency key must be provided", nameof(idempotencyKey));

        // Check if request with the same idempotency key exists and completed
        var existingRequest = await _dbContext.IdempotentRequests
            .Where(r => r.Key == idempotencyKey && r.UserId == request.UserId)
            .SingleOrDefaultAsync(cancellationToken);

        if (existingRequest != null)
        {
            if (existingRequest.Completed)
            {
                _logger.LogInformation("Idempotency key {Key} found - returning cached result", idempotencyKey);
                return existingRequest.Response;
            }
            throw new InvalidOperationException("Duplicate in-progress request detected");
        }

        // Begin atomic transaction
        await using var tx = await _dbContext.Database.BeginTransactionAsync(cancellationToken);
        try
        {
            var order = new Order
            {
                UserId = request.UserId,
                Items = request.Items.Select(i => new OrderItem(i.ProductId, i.Quantity)).ToList(),
                Created = DateTime.UtcNow,
                Status = OrderStatus.Pending
            };

            // Reserve idempotency key record
            var idempotencyRecord = new IdempotentRequest
            {
                Key = idempotencyKey,
                UserId = request.UserId,
                StartedAt = DateTime.UtcNow,
                Completed = false
            };

            _dbContext.IdempotentRequests.Add(idempotencyRecord);
            _dbContext.Orders.Add(order);

            await _dbContext.SaveChangesAsync(cancellationToken);

            // Simulate event emission omitted here...

            idempotencyRecord.Completed = true;
            idempotencyRecord.Response = new OrderDto(order.Id, order.Status.ToString(), order.Items.Count);

            await _dbContext.SaveChangesAsync(cancellationToken);
            await tx.CommitAsync(cancellationToken);

            return idempotencyRecord.Response;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to create order with idempotency key {Key}", idempotencyKey);
            await tx.RollbackAsync(cancellationToken);
            throw;
        }
    }
}

Notice how idempotency records and orders are created inside a transaction to ensure atomicity, and cancellation tokens are propagated for async database calls.

Code Example 2: Minimal API Endpoint for Creating Orders

This code snippet demonstrates how to expose the create order functionality as a secured minimal API endpoint in the ASP.NET Core 10 Program.cs style.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddDbContext<OrdersDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Orders")));
builder.Services.AddAuthentication("Bearer").AddJwtBearer("Bearer", options =>
{
    options.Authority = "https://auth.example.com";
    options.Audience = "orders-api";
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapPost("/api/orders", async (
    [FromBody] CreateOrderRequest request,
    [FromHeader(Name = "Idempotency-Key")] string idempotencyKey,
    IOrderService orderService,
    CancellationToken cancellationToken) =>
{
    if (string.IsNullOrEmpty(idempotencyKey))
        return Results.BadRequest(new { error = "Missing Idempotency-Key header" });

    try
    {
        var order = await orderService.CreateOrderAsync(request, idempotencyKey, cancellationToken);
        return Results.Created($"/api/orders/{order.Id}", order);
    }
    catch (ArgumentException ex)
    {
        return Results.BadRequest(new { error = ex.Message });
    }
    catch (InvalidOperationException ex)
    {
        return Results.Conflict(new { error = ex.Message });
    }
});

app.Run();

This minimal API endpoint uses dependency injection to resolve the service, enforces idempotency through a custom header, and returns proper HTTP codes based on business exceptions.

23. Sources and further reading

The architecture, targets, and sizing in this guide are illustrative engineering choices. The references below support platform behaviour; verify service limits, regional availability, and current configuration guidance during implementation.


This article introduces code that shows practical idiomatic usage of async EF Core, dependency injection, idempotency, and minimal APIs, bridging the gap between architectural concepts and runnable implementation.