fix(helm): add liveliness and readiness probes to helm chart

[alukach]

What I'm changing

This PR attempts to integrate our existing /healthz endpoint into K8s environments

How I did it

I admittedly know very little about Helm/K8s and reached for Claude Code (Opus 4.6) to complete this. Please review thoroughly

closes #140

[thenav56]

Thanks @alukach, few concerns from my side.

[thenav56]

Do we need to enable the health endpoint?

Currently, when running this inside a stac-auth-proxy pod container, it returns a 404:

>>> import httpx
>>> httpx.get("http://localhost:8000/healthz")
<Response [404 Not Found]>

[alukach]

The healthz path DOES include the root_path, are you using that? ie does http://localhost:8000/stac/healthz work?

[thenav56]

Note

Findings from a live environment test (tested in a separate internal cluster):

Config used

    - repoURL: https://github.com/developmentseed/stac-auth-proxy.git
      targetRevision: v1.0.3-rc2
      path: helm/
      helm:
        valuesObject:
          env:
            UPSTREAM_URL: "http://ifrcgo-montandon-eoapi-{{ $i }}-stac:8080"
            OIDC_DISCOVERY_URL: "https://goadmin-stage.ifrc.org/o/.well-known/openid-configuration"
            OVERRIDE_HOST: "0"
            ROOT_PATH: "/stac"
            COLLECTIONS_FILTER_CLS: stac_auth_proxy.montandon_filters:CollectionsFilter
            ITEMS_FILTER_CLS: stac_auth_proxy.montandon_filters:ItemsFilter
          ingress:
            enabled: "true"
            host: "montandon-eoapi-{{ $i }}-auth-proxy.ifrc-go.dev.togglecorp.com"
            className: "nginx"
            tls:
              enabled: "false"
          replicaCount: 1
          extraVolumes:
            - name: filters
              configMap:
                name: stac-auth-proxy-filters
          extraVolumeMounts:
            - name: filters
              mountPath: /app/src/stac_auth_proxy/montandon_filters.py
              subPath: montandon_filters.py
              readOnly: true

When setting ROOT_PATH=""

• When OIDC_DISCOVERY_URL is down
  • The pod does not exit or retry at the application level (same as before).
  • After some time, Kubernetes deletes the pod due to the health check.
  • Pod status is green after OIDC_DISCOVERY_URL is up
• When OIDC_DISCOVERY_URL is up
  • Pod status is green after few seconds

When setting ROOT_PATH="/stac"

• The pod gets stuck in an error state.
  • logs shows 404 for /healthz

How should the health check be handled when ROOT_PATH is defined?

[alukach]

The pod does not exit or retry at the application level (same as before).

@thenav56 Am I correct that even though you're using the newer helm chart, that helm chart is still pointing at the latest docker image which is still using v1.0.2 (link):

Perhaps we should hardcode this value to the helm chart version?

stac-auth-proxy/helm/values.yaml

Lines 5 to 8 in 647dfa0

	image:
	repository: ghcr.io/developmentseed/stac-auth-proxy
	pullPolicy: IfNotPresent
	tag: "latest"

[thenav56]

Hey @alukach, I was also wondering the same thing for the image tag

After including this, everything is working as expected:

---

Would it be feasible to expose the health endpoint at /healthz instead of $ROOT_PATH/healthz? This would avoid requiring additional configuration changes on the consumer side.

It was also a bit confusing since all requests under /stac are redirected to the STAC API server, but the /stac/healthz endpoint is not.

If the chart consumer need to include that, then we should also update the documentation and note this as a breaking change in the release.

• https://github.com/developmentseed/stac-auth-proxy/blob/0c3173d294ca10a237f6ce9b7cc4fedad277adc3/docs/user-guide/tips.md#root-paths
• https://github.com/developmentseed/stac-auth-proxy/blob/0c3173d294ca10a237f6ce9b7cc4fedad277adc3/docs/user-guide/configuration.md#root_path

[thenav56]

👋🏽 @alukach @pantierra
Just a reminder for this PR, let me know if I help on the changes using a fork PR?

[alukach]

@thenav56 Apologies for the delay, I was away last week.

Would it be feasible to expose the health endpoint at /healthz instead of $ROOT_PATH/healthz? This would avoid requiring additional configuration changes on the consumer side.

This is a bit more challenging than it would seem. The root path (/stac in your case) is handled by FastAPI and applied to all routes:

stac-auth-proxy/src/stac_auth_proxy/app.py

Lines 214 to 218 in 0c3173d

	app = FastAPI(
	openapi_url=None, # Disable OpenAPI schema endpoint, we want to serve upstream's schema
	lifespan=build_lifespan(settings=settings),
	root_path=settings.root_path,
	)

stac-auth-proxy/src/stac_auth_proxy/app.py

Lines 81 to 85 in 0c3173d

	if settings.healthz_prefix:
	app.include_router(
	HealthzHandler(upstream_url=str(settings.upstream_url)).router,
	prefix=settings.healthz_prefix,
	)

Removing the root path from the health check endpoint would be challenging. Not saying that we shouldn't do it, moreso it's something we could track in another issue.

[pantierra]

Default value below is 5. Please make sure they are the same, either 5 or 15.

[alukach]

How can we make these types of check in a helm chart?

[pantierra]

Currently the schema is ignored in the checks because it is a yaml not json. This should fix. I am not entirely sure if checks would include the standard values, though.

In this PR i just changed the preStopSleepSeconds in values.yaml to 15.

[pantierra]

Must be greater than preStopSleepSeconds.

Can we have a check for this?

[pantierra]

Added a check for this in the helm/templates/_helpers.tpl

[pantierra]

Overall looks good to me, only a couple of small things I would improve, see my comments.