podinfo

Podinfo is a tiny web application made with Go that showcases best practices of running microservices in Kubernetes. Podinfo is used by CNCF projects like Flux and Flagger for end-to-end testing and workshops.

Specifications:

• Health checks (readiness and liveness)
• Graceful shutdown on interrupt signals
• File watcher for secrets and configmaps
• Instrumented with Prometheus and Open Telemetry
• Structured logging with zap
• 12-factor app with viper
• Fault injection (random errors and latency)
• SPIFFE mTLS with X.509 SVIDs from the SPIFFE Workload API
• Swagger docs
• Timoni, Helm and Kustomize installers
• End-to-End testing with Kubernetes Kind and Helm
• Multi-arch container image with Docker buildx and GitHub Actions
• Container image signing with Sigstore cosign
• SBOMs and SLSA Provenance embedded in the container image
• CVE scanning with govulncheck

Web API:

• GET / prints runtime information
• GET /version prints podinfo version and git commit hash
• GET /metrics return HTTP requests duration and Go runtime metrics
• GET /healthz used by Kubernetes liveness probe
• GET /readyz used by Kubernetes readiness probe
• POST /readyz/enable signals the Kubernetes LB that this instance is ready to receive traffic
• POST /readyz/disable signals the Kubernetes LB to stop sending requests to this instance
• POST /fault_injection/enable makes this instance respond with HTTP 500 to all application endpoints (probes, metrics, pprof and the /fault_injection/* control endpoints stay healthy) — useful for testing client-side circuit breakers / outlier detection against a single "sick" replica
• POST /fault_injection/disable restores normal responses
• GET /fault_injection/status returns the current fault injection state (enabled or disabled)
• GET /status/{code} returns the status code
• GET /panic crashes the process with exit code 255
• POST /echo forwards the call to the backend service and echos the posted content, without backends the content is logged at debug level
• GET /env returns the environment variables as a JSON array
• GET /headers returns a JSON with the request HTTP headers, plus X-Spiffe-Id for SPIFFE mTLS clients
• GET /delay/{seconds} waits for the specified period
• POST /token issues a JWT token valid for one minute JWT=$(curl -sd 'anon' podinfo:9898/token | jq -r .token)
• GET /token/validate validates the JWT token curl -H "Authorization: Bearer $JWT" podinfo:9898/token/validate
• GET /configs returns a JSON with configmaps and/or secrets mounted in the config volume
• POST/PUT /cache/{key} saves the posted content to Redis
• GET /cache/{key} returns the content from Redis if the key exists
• DELETE /cache/{key} deletes the key from Redis if exists
• POST /store writes the posted content to disk at /data/hash and returns the SHA1 hash of the content
• GET /store/{hash} returns the content of the file /data/hash if exists
• GET/HEAD /artifact returns the files from --artifact-path (default ./kustomize) as a tar.gz, with the sha256 digest in the X-Artifact-Digest header
• GET /ws/echo echos content via websockets podcli ws ws://localhost:9898/ws/echo
• GET /chunked/{seconds} uses transfer-encoding type chunked to give a partial response and then waits for the specified period
• GET /swagger.json returns the API Swagger docs, used for Linkerd service profiling and Gloo routes discovery

gRPC API:

• /grpc.health.v1.Health/Check health checking
• /grpc.EchoService/Echo echos the received content
• /grpc.VersionService/Version returns podinfo version and Git commit hash
• /grpc.DelayService/Delay returns a successful response after the given seconds in the body of gRPC request
• /grpc.EnvService/Env returns environment variables as a JSON array
• /grpc.HeaderService/Header returns the headers present in the gRPC request. Any custom header can also be given as a part of request and that can be returned using this API
• /grpc.InfoService/Info returns the runtime information
• /grpc.PanicService/Panic crashes the process with gRPC status code as '1 CANCELLED'
• /grpc.StatusService/Status returns the gRPC Status code given in the request body
• /grpc.TokenService/TokenGenerate issues a JWT token valid for one minute
• /grpc.TokenService/TokenValidate validates the JWT token

Web UI:

To access the Swagger UI open <podinfo-host>/swagger/index.html in a browser.

Guides

• Getting started with Timoni
• Getting started with Flux
• Progressive Deliver with Flagger and Linkerd
• Automated canary deployments with Kubernetes Gateway API

Install

To install Podinfo on Kubernetes the minimum required version is Kubernetes v1.23.

Timoni

Install with Timoni:

timoni -n default apply podinfo oci://ghcr.io/stefanprodan/modules/podinfo

Helm

Install from github.io:

helm repo add podinfo https://stefanprodan.github.io/podinfo

helm upgrade --install --wait frontend \
--namespace test \
--set replicaCount=2 \
--set backend=http://backend-podinfo:9898/echo \
podinfo/podinfo

helm test frontend --namespace test

helm upgrade --install --wait backend \
--namespace test \
--set redis.enabled=true \
podinfo/podinfo

Install from ghcr.io:

helm upgrade --install --wait podinfo --namespace default \
oci://ghcr.io/stefanprodan/charts/podinfo

Kustomize

kubectl apply -k github.com/stefanprodan/podinfo//kustomize

Docker

docker run -dp 9898:9898 stefanprodan/podinfo

SPIFFE mTLS

Podinfo can serve its HTTPS port with SPIFFE mTLS. The server gets its X.509 SVID from the SPIFFE Workload API (e.g. a SPIRE agent), rotates it automatically, and only accepts clients that present an SVID from the same trust bundle.

Flag	Description
--spiffe-endpoint-socket	Workload API address, e.g. unix:///spiffe-workload-api/spire-agent.sock, requires --secure-port
--spiffe-authorized-ids	Client SPIFFE IDs allowed to connect, when empty any ID in podinfo's trust domain is allowed
--spiffe-backend-mtls	Call the https backends with SPIFFE mTLS, requires --spiffe-endpoint-socket
--spiffe-backend-ids	Server SPIFFE IDs accepted from https backends, when empty any ID in podinfo's trust domain is accepted, requires --spiffe-backend-mtls

Podinfo starts the HTTP port and passes the liveness probe right away, and keeps retrying the Workload API until the SVID is issued. The readiness probe fails until the HTTPS port is serving with the SVID. The request log includes the spiffe_id of the client at debug level.

With --spiffe-backend-mtls, /api/echo calls the https:// backends set with --backend-url over SPIFFE mTLS, presenting the same SVID and verifying the backend against --spiffe-backend-ids. All https:// backends must then be SPIFFE workloads, calls to http:// backends are unchanged. Without the flag, backends are called with the default TLS settings. To chain two podinfo instances, point the frontend at the backend's HTTPS port and authorize the frontend's ID on the backend:

# backend
podinfo --secure-port=9899 --spiffe-endpoint-socket=unix:///spiffe-workload-api/spire-agent.sock \
  --spiffe-authorized-ids=spiffe://example.org/ns/demo/sa/frontend

# frontend
podinfo --secure-port=9899 --spiffe-endpoint-socket=unix:///spiffe-workload-api/spire-agent.sock \
  --backend-url=https://backend:9899/api/echo \
  --spiffe-backend-mtls \
  --spiffe-backend-ids=spiffe://example.org/ns/demo/sa/backend

On a cluster with SPIRE and the SPIFFE CSI driver, register the podinfo pods with the SPIRE controller manager:

apiVersion: spire.spiffe.io/v1alpha1
kind: ClusterSPIFFEID
metadata:
  name: podinfo
spec:
  # the SPIRE controller manager class, for the SPIRE Helm chart: <namespace>-<release>
  className: spire-system-spire
  spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
  podSelector: {}
  namespaceSelector:
    matchLabels:
      kubernetes.io/metadata.name: podinfo

Install with Helm:

helm upgrade --install --wait podinfo --namespace podinfo \
--set serviceAccount.enabled=true \
--set tls.enabled=true \
--set spiffe.enabled=true \
--set spiffe.authorizedIDs={spiffe://example.org/ns/podinfo/sa/podinfo} \
oci://ghcr.io/stefanprodan/charts/podinfo

The Helm test client runs with podinfo's service account, so its ID is included in authorizedIDs above.

Continuous Delivery

In order to install podinfo on a Kubernetes cluster and keep it up to date with the latest release in an automated manner, you can use Flux.

Install the Flux CLI on MacOS and Linux using Homebrew:

brew install fluxcd/tap/flux

Install the Flux controllers needed for Helm operations:

flux install \
--namespace=flux-system \
--network-policy=false \
--components=source-controller,helm-controller

Add podinfo's Helm repository to your cluster and configure Flux to check for new chart releases every ten minutes:

flux create source helm podinfo \
--namespace=default \
--url=https://stefanprodan.github.io/podinfo \
--interval=10m

Create a podinfo-values.yaml file locally:

cat > podinfo-values.yaml <<EOL
replicaCount: 2
resources:
  limits:
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 64Mi
EOL

Create a Helm release for deploying podinfo in the default namespace:

flux create helmrelease podinfo \
--namespace=default \
--source=HelmRepository/podinfo \
--release-name=podinfo \
--chart=podinfo \
--chart-version=">5.0.0" \
--values=podinfo-values.yaml

Based on the above definition, Flux will upgrade the release automatically when a new version of podinfo is released. If the upgrade fails, Flux can rollback to the previous working version.

You can check what version is currently deployed with:

flux get helmreleases -n default

To delete podinfo's Helm repository and release from your cluster run:

flux -n default delete source helm podinfo
flux -n default delete helmrelease podinfo

If you wish to manage the lifecycle of your applications in a GitOps manner, check out this workflow example for multi-env deployments with Flux, Kustomize and Helm.