Podinfo — Go Microservice Template for Kubernetes

Introduction

Podinfo is a small Go web application designed to serve as a reference project for Kubernetes practitioners. Built by Stefan Prodan (creator of Flagger and Flux), it demonstrates how to structure a cloud-native microservice with health checks, graceful shutdown, Prometheus metrics, OpenTelemetry tracing, and 12-factor configuration. Teams use Podinfo as a starting point for GitOps pipelines, canary deployments, and Kubernetes platform validation.

What Podinfo Does

• Provides HTTP and gRPC APIs with configurable responses for testing service mesh behavior
• Exposes Prometheus metrics, readiness and liveness probes, and structured logging
• Supports feature flags, fault injection, and latency simulation for chaos testing
• Includes Helm charts and Kustomize overlays for multi-environment deployment
• Serves as the standard demo app for Flux CD, Flagger, and other CNCF GitOps tools

Architecture Overview

Podinfo is a single Go binary that runs an HTTP server and an optional gRPC server. It reads configuration from environment variables and command-line flags following 12-factor principles. The application exposes a REST API with endpoints for health, readiness, versioning, echo, and store operations (backed by an in-memory or Redis cache). Prometheus instrumentation is built in via the standard Go client library.

Self-Hosting & Configuration

• Deploy via Helm chart, Kustomize overlay, or plain Kubernetes manifests
• Configure via environment variables: PODINFO_PORT, PODINFO_GRPC_PORT, PODINFO_CACHE_SERVER
• Enable Redis caching by setting the --cache-server flag to a Redis URL
• Customize the UI message, color, and logo through command-line flags or ConfigMaps
• Use the included Dockerfile for multi-arch container builds (amd64, arm64)

Key Features

• Production-ready health check endpoints compatible with Kubernetes probes
• Prometheus metrics and OpenTelemetry trace propagation out of the box
• Fault injection endpoints for simulating errors, delays, and panics
• Helm chart with support for HPA, PDB, service accounts, and ingress
• Multi-architecture container images published to GitHub Container Registry

Comparison with Similar Tools

• httpbin — Generic HTTP testing tool; Podinfo is purpose-built for Kubernetes platform validation
• Nginx — Static web server; Podinfo includes dynamic APIs, metrics, and chaos endpoints
• Emojivoto — Linkerd demo app; Podinfo is framework-agnostic and used across CNCF projects
• Online Boutique — Google's multi-service demo; Podinfo is a single-service reference for GitOps
• Bookinfo — Istio's demo; Podinfo is lighter and designed for progressive delivery testing

FAQ

Q: Is Podinfo meant for production workloads? A: Podinfo is primarily a reference and testing tool for Kubernetes platforms. Teams use it to validate their CI/CD pipelines, GitOps workflows, and service mesh configurations.

Q: Which GitOps tools use Podinfo as their demo app? A: Flux CD, Flagger, Argo CD tutorials, and numerous CNCF project examples reference Podinfo for hands-on demonstrations.

Q: Can I extend Podinfo with my own endpoints? A: Yes. The Go source is clean and modular, making it straightforward to add custom handlers or middleware.

Q: Does Podinfo support gRPC? A: Yes. Podinfo runs both HTTP and gRPC servers simultaneously, configurable via separate port flags.

Sources

• https://github.com/stefanprodan/podinfo
• https://github.com/stefanprodan/podinfo#readme