Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 7 — Resident Service

Deployment

Deploying a service that depends on another service being reachable

14 min readHOA Backend Engineering CourseMaster

Adopt the Reviewed Image Without Re-teaching It

Terminal — repository root

$cp services/flat-service/Dockerfile services/resident-service/Dockerfile && $EDITOR services/resident-service/Dockerfile

// Review only the service path, binary, UID 10002, and port 8082 substitutions.

Create services/resident-service/Dockerfile before adding the code

$mkdir -p services/resident-service && touch services/resident-service/Dockerfile

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/Dockerfile (modify — resident-specific substitutions)

-COPY services/flat-service ./services/flat-service
+COPY services/resident-service ./services/resident-service
-RUN go work init ./services/flat-service
+RUN go work init ./services/resident-service
-WORKDIR /src/services/flat-service
+WORKDIR /src/services/resident-service
-RUN go build -o /out/flat-service ./cmd/api
+RUN go build -o /out/resident-service ./cmd/api
-RUN adduser -D -u 10001 appuser
+RUN adduser -D -u 10002 appuser
-COPY --from=build /out/flat-service /usr/local/bin/flat-service
+COPY --from=build /out/resident-service /usr/local/bin/resident-service
-EXPOSE 8081
+EXPOSE 8082
-ENTRYPOINT ["/usr/local/bin/flat-service"]
+ENTRYPOINT ["/usr/local/bin/resident-service"]

Configuring the flat-service Dependency

resident-service needs FLAT_SERVICE_URL at runtime to build its FlatClient. In cluster, that is flat-service's internal ClusterIP DNS name; locally, it is whatever port flat-service is bound to. Getting this wrong does not fail loudly at startup — it fails on the first ownership or occupancy request, which is exactly why the health check below verifies it eagerly.

Terminal — repository root

$cp services/flat-service/internal/handler/http/health_handler.go services/resident-service/internal/handler/http/health_handler.go

// Resident starts from Flat's proven split-probe baseline, then adds one downstream readiness check.

Create services/resident-service/internal/handler/http/health_handler.go before adding the code

$mkdir -p services/resident-service/internal/handler/http && touch services/resident-service/internal/handler/http/health_handler.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/internal/handler/http/health_handler.go

 import (
+	"github.com/hoa-platform/backend/services/resident-service/internal/client"
 )

-func NewReadinessHandler(pool *pgxpool.Pool) gin.HandlerFunc {
+func NewReadinessHandler(pool *pgxpool.Pool, flatClient *client.FlatClient) gin.HandlerFunc {
    return func(c *gin.Context) {
        // Existing two-second context and pool.Ping check stay unchanged.
+		if err := flatClient.Ping(ctx); err != nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{
+				"status": "down", "dependency": "flat-service",
+			})
+			return
+		}
        c.JSON(http.StatusOK, gin.H{"status": "up"})
    }
 }

Flat Service already supplied the database-aware check. Resident adds only downstream readiness. Its separate liveness handler performs no network calls, so a Flat outage removes Resident from traffic without restarting the process.

Terminal — repository root

$touch services/resident-service/internal/handler/http/health_routes.go

// Keeps health dependency wiring separate from the resident business-route constructor.

Create services/resident-service/internal/handler/http/health_routes.go before adding the code

$mkdir -p services/resident-service/internal/handler/http && touch services/resident-service/internal/handler/http/health_routes.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/internal/handler/http/health_routes.go

package http

import (
	"github.com/gin-gonic/gin"
	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/hoa-platform/backend/services/resident-service/internal/client"
)

func RegisterHealthRoutes(r *gin.Engine, pool *pgxpool.Pool, flatClient *client.FlatClient) {
	r.GET("/health/live", NewLivenessHandler())
	r.GET("/health/ready", NewReadinessHandler(pool, flatClient))
}

Create services/resident-service/cmd/api/main.go before adding the code

$mkdir -p services/resident-service/cmd/api && touch services/resident-service/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/cmd/api/main.go (modify — wire existing dependencies)

 router := httphandler.NewRouter(residentHandler, familyHandler, ownershipHandler)
+httphandler.RegisterHealthRoutes(router, pool, flatClient)

Kubernetes: Explicit Dependency Ordering

Terminal — resident-service

$mkdir -p services/resident-service/deploy/k8s

$touch services/resident-service/deploy/k8s/migration-job.yaml services/resident-service/deploy/k8s/deployment.yaml

Create services/resident-service/deploy/k8s/deployment.yaml before adding the code

$mkdir -p services/resident-service/deploy/k8s && touch services/resident-service/deploy/k8s/deployment.yaml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/deploy/k8s/deployment.yaml

 spec:
   template:
     spec:
       containers:
         - name: resident-service
+          env:
+            - name: FLAT_SERVICE_URL
+              value: "http://flat-service.default.svc.cluster.local"
+          readinessProbe:
+            httpGet:
+              path: /health/ready
+              port: 8082
+            failureThreshold: 3
+            periodSeconds: 5
+          livenessProbe:
+            httpGet:
+              path: /health/live
+              port: 8082
+            failureThreshold: 3
+            periodSeconds: 15

Do not copy Flat's entire Deployment. Start from the service manifest pattern already established there and review only Resident's new operational contract: readiness depends on Flat, while liveness proves only that the Resident process can continue running.

Simulating a Downstream Outage

Terminal — rehearse both services together

$docker compose up -d flat-postgres resident-postgres

$go run ./services/flat-service/cmd/api &

$FLAT_SERVICE_URL=http://localhost:8081 go run ./services/resident-service/cmd/api &

$curl -s localhost:8082/health/ready

// expect {"status":"up"} — both dependencies reachable

$kill %2

// stop resident-service

$kill %1

// stop flat-service

$FLAT_SERVICE_URL=http://localhost:8081 go run ./services/resident-service/cmd/api &

// flat-service is now down

$curl -s localhost:8082/health/ready

// expect 503, dependency: flat-service

Applied exercise

Add a startup probe so slow flat-service recovery doesn't kill resident-service

25 min

During a flat-service redeploy, resident-service's liveness probe (which also checks flat-service via the shared health handler) starts failing and Kubernetes restarts resident-service unnecessarily — a working process gets killed because a dependency was briefly restarting.

Split the health handler into a liveness variant that only checks resident-service's own Postgres, and a readiness variant that also checks flat-service.
Update the Deployment manifest: livenessProbe hits the liveness-only path, readinessProbe hits the full dependency-check path.
Document in a comment why liveness must never depend on a downstream service's health.

Deliverable

Two health handler functions (or one parameterized), and an updated deployment.yaml.

Completion checks

Liveness failing no longer depends on flat-service's state.
Readiness still correctly reports not-ready when flat-service is unreachable.
A working resident-service process is never restarted just because flat-service redeployed.

Quiz & Practice

Question 1 / 2

Why does resident-service's readiness probe check flat-service's reachability, while a well-designed liveness probe should not?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 7 — Resident Service

Deployment

Deploying a service that depends on another service being reachable

14 min readHOA Backend Engineering CourseMaster

Adopt the Reviewed Image Without Re-teaching It

Terminal — repository root

$cp services/flat-service/Dockerfile services/resident-service/Dockerfile && $EDITOR services/resident-service/Dockerfile

// Review only the service path, binary, UID 10002, and port 8082 substitutions.

Create services/resident-service/Dockerfile before adding the code

$mkdir -p services/resident-service && touch services/resident-service/Dockerfile

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/Dockerfile (modify — resident-specific substitutions)

-COPY services/flat-service ./services/flat-service
+COPY services/resident-service ./services/resident-service
-RUN go work init ./services/flat-service
+RUN go work init ./services/resident-service
-WORKDIR /src/services/flat-service
+WORKDIR /src/services/resident-service
-RUN go build -o /out/flat-service ./cmd/api
+RUN go build -o /out/resident-service ./cmd/api
-RUN adduser -D -u 10001 appuser
+RUN adduser -D -u 10002 appuser
-COPY --from=build /out/flat-service /usr/local/bin/flat-service
+COPY --from=build /out/resident-service /usr/local/bin/resident-service
-EXPOSE 8081
+EXPOSE 8082
-ENTRYPOINT ["/usr/local/bin/flat-service"]
+ENTRYPOINT ["/usr/local/bin/resident-service"]

Configuring the flat-service Dependency

Terminal — repository root

$cp services/flat-service/internal/handler/http/health_handler.go services/resident-service/internal/handler/http/health_handler.go

// Resident starts from Flat's proven split-probe baseline, then adds one downstream readiness check.

Create services/resident-service/internal/handler/http/health_handler.go before adding the code

$mkdir -p services/resident-service/internal/handler/http && touch services/resident-service/internal/handler/http/health_handler.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/internal/handler/http/health_handler.go

 import (
+	"github.com/hoa-platform/backend/services/resident-service/internal/client"
 )

-func NewReadinessHandler(pool *pgxpool.Pool) gin.HandlerFunc {
+func NewReadinessHandler(pool *pgxpool.Pool, flatClient *client.FlatClient) gin.HandlerFunc {
    return func(c *gin.Context) {
        // Existing two-second context and pool.Ping check stay unchanged.
+		if err := flatClient.Ping(ctx); err != nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{
+				"status": "down", "dependency": "flat-service",
+			})
+			return
+		}
        c.JSON(http.StatusOK, gin.H{"status": "up"})
    }
 }

Terminal — repository root

$touch services/resident-service/internal/handler/http/health_routes.go

// Keeps health dependency wiring separate from the resident business-route constructor.

Create services/resident-service/internal/handler/http/health_routes.go before adding the code

$mkdir -p services/resident-service/internal/handler/http && touch services/resident-service/internal/handler/http/health_routes.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/internal/handler/http/health_routes.go

package http

import (
	"github.com/gin-gonic/gin"
	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/hoa-platform/backend/services/resident-service/internal/client"
)

func RegisterHealthRoutes(r *gin.Engine, pool *pgxpool.Pool, flatClient *client.FlatClient) {
	r.GET("/health/live", NewLivenessHandler())
	r.GET("/health/ready", NewReadinessHandler(pool, flatClient))
}

Create services/resident-service/cmd/api/main.go before adding the code

$mkdir -p services/resident-service/cmd/api && touch services/resident-service/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/cmd/api/main.go (modify — wire existing dependencies)

 router := httphandler.NewRouter(residentHandler, familyHandler, ownershipHandler)
+httphandler.RegisterHealthRoutes(router, pool, flatClient)

Kubernetes: Explicit Dependency Ordering

Terminal — resident-service

$mkdir -p services/resident-service/deploy/k8s

$touch services/resident-service/deploy/k8s/migration-job.yaml services/resident-service/deploy/k8s/deployment.yaml

Create services/resident-service/deploy/k8s/deployment.yaml before adding the code

$mkdir -p services/resident-service/deploy/k8s && touch services/resident-service/deploy/k8s/deployment.yaml

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/resident-service/deploy/k8s/deployment.yaml

 spec:
   template:
     spec:
       containers:
         - name: resident-service
+          env:
+            - name: FLAT_SERVICE_URL
+              value: "http://flat-service.default.svc.cluster.local"
+          readinessProbe:
+            httpGet:
+              path: /health/ready
+              port: 8082
+            failureThreshold: 3
+            periodSeconds: 5
+          livenessProbe:
+            httpGet:
+              path: /health/live
+              port: 8082
+            failureThreshold: 3
+            periodSeconds: 15

Simulating a Downstream Outage

Terminal — rehearse both services together

$docker compose up -d flat-postgres resident-postgres

$go run ./services/flat-service/cmd/api &

$FLAT_SERVICE_URL=http://localhost:8081 go run ./services/resident-service/cmd/api &

$curl -s localhost:8082/health/ready

// expect {"status":"up"} — both dependencies reachable

$kill %2

// stop resident-service

$kill %1

// stop flat-service

$FLAT_SERVICE_URL=http://localhost:8081 go run ./services/resident-service/cmd/api &

// flat-service is now down

$curl -s localhost:8082/health/ready

// expect 503, dependency: flat-service

Applied exercise

Add a startup probe so slow flat-service recovery doesn't kill resident-service

25 min

Split the health handler into a liveness variant that only checks resident-service's own Postgres, and a readiness variant that also checks flat-service.
Update the Deployment manifest: livenessProbe hits the liveness-only path, readinessProbe hits the full dependency-check path.
Document in a comment why liveness must never depend on a downstream service's health.

Deliverable

Two health handler functions (or one parameterized), and an updated deployment.yaml.

Completion checks

Liveness failing no longer depends on flat-service's state.
Readiness still correctly reports not-ready when flat-service is unreachable.
A working resident-service process is never restarted just because flat-service redeployed.

Quiz & Practice

Question 1 / 2

Why does resident-service's readiness probe check flat-service's reachability, while a well-designed liveness probe should not?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.