Add health check endpoint

[ttys3]

Add /api/healthz for health check. Which does not need auth and is cloud native friendly

By convention, most cases the path is /healthz or /_healthz, I think we need this.

https://kubernetes.io/docs/reference/using-api/health-checks/

https://www.nomadproject.io/docs/job-specification/service#header-stanza

[zeripath]

This will require a new username restriction,

Is there really nothing we can use on say /api or even in .well-known?

If it has to be this name then you must add a restriction to models/user and mark this as BREAKING.

[ttys3]

@zeripath no, the path (/healthz or /_healthz) is only for convention.

do you think it is OK change to /api/_healthz ? thus, it is not BREAKING

[lunny]

We already have HEAD /

[ttys3]

HEAD / is not as clear as a standalone GET /_healthz.
and also, not all health check has builtin HEAD method option. although you can use a custom http client like curl, but this is not normal way and need user do more things.

adding an explicit GET /_healthz will always be good and has better compatibility and does not add extra overhead

[techknowlogick]

Fwiw, the gitea project uses the version api endpoint for this in our monitoring

[6543]

as per tech ... use the version endpoint it does the same (return 200 & a tiny string)

It would only be a valid pull if it really do check health of the running instance (check DB, cache, storage backends, ...

[ttys3]

@6543

yes, I tried the /api/v1/version

The version api does need authentication. So it does not meet the needs.

returns 403 and json {"message":"Only signed in user is allowed to call APIs."}

I know how to build a request to pass the authentication. but this is not a ping api shoud look like.

when system op deploy the app, it does not and has no need to know the user account of the system or a token.

[6543]

ACK for code

but we need documentation

[ttys3]

@6543 some tips ? Sorry, I don't know where to add the documentation.

Since it is not an API for client request, I think it is Ok not write swagger doc.
Maybe in the doc markdown ? But, which section ?

[6543]

yes swagger docs would be the wrong place :D

-> https://github.com/go-gitea/gitea/tree/main/docs (just read the readme in there - it's a hugo repo)

add it to https://docs.gitea.io/en-us/install-on-kubernetes/ ?

[silverwind]

Consider implementing a response as per https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check. I think should at minimum do a test against the database.

GET /api/health

{
  "status": "pass",
  "releaseId": "1.16.0",
  "description": "Gitea: Git with a cup of tea",
  "checks": {
    "database:ping": [
      {
        "status": "pass",
        "time": "2022-01-17T03:36:48Z"
      }
    ]
  }
}

[lunny]

LGTM if it's /api/xxxx.

[ttys3]

@wxiaoguang option 2 will works, but maybe a little confusing ?
should we add another /readyz that just return a simple OK ? which will works for not installed gitea instance.

the diff between other micro service is, gitea need interactive installation to work for the first time.

is there any automatic method to make this work in k8s without interactive installation? I mean something like a cli to allow fast installation (for example: gitea installation), thus, the instance will initilzation itself, so the healthz api should also work for the first time.

[jbg]

Does Gitea actually need interactive installation the first time? I thought you could fill in the config and enable install lock and it would just work (run the migrations on first launch).

[wxiaoguang]

@wxiaoguang option 2 will works, but maybe a little confusing ? should we add another /readyz that just return a simple OK ? which will works for not installed gitea instance.

the diff between other micro service is, gitea need interactive installation to work for the first time.

is there any automatic method to make this work in k8s without interactive installation? I mean something like a cli to allow fast installation (for example: gitea installation), thus, the instance will initilzation itself, so the healthz api should also work for the first time.

@lafriks

[lafriks]

It's not about if healthz endpoint being usable for k8s, for k8s there is helm chart that will make gitea usable without installation. Problem is that health endpoint is not usable for docker/docker swarm, at least from most used perspective install stage is most common scenario as we don't have easy way to skip it.

[lafriks]

I don't see much point in readyz endpoint as that would pretty much be same as HEAD / request. Point for healthz endpoint is that requests can be started to route to that container as it has database and cache available and container is in working condition

[markkrj]

Couldn't one /api/healthz endpoint be registered in installation routes that will ever return 200? That way, if Gitea isn't provisioned, Docker will think it's healthy, and if it is, installation routes will not be used anyway...

[lafriks]

Couldn't one /api/healthz endpoint be registered in installation routes that will ever return 200? That way, if Gitea isn't provisioned, Docker will think it's healthy, and if it is, installation routes will not be used anyway...

Yes, that was my suggestion

[markkrj]

Couldn't one /api/healthz endpoint be registered in installation routes that will ever return 200? That way, if Gitea isn't provisioned, Docker will think it's healthy, and if it is, installation routes will not be used anyway...

Yes, that was my suggestion

@lafriks @wxiaoguang would ttys3#1 be acceptable, then?

[wxiaoguang]

@lafriks

[markkrj]

@lafriks

Or maybe you just want r.Get("/api/healthz", func(http.ResponseWriter, *http.Request){}) on install routes, to not depend on healthcheck package... That might be even better/simpler..

[lafriks]

Small nit but otherwise looks good

[wxiaoguang]

OK, since there is no objection, let me take the remaining work:

1. conflicts are resolved
2. remove CheckInstall, use Check with InstallLock check instead.
3. set Description to setting.AppName instead of the hard-coded string.