volker.raschek/helm-gitea
1
0
Fork 0
Code Issues 2 Pull Requests 6 Actions Packages Projects Releases Wiki Activity
Files
1b82a15b7ffda8626d6655ee7f7f5b4cd8c13f37
helm-gitea/docs/ha-setup.md
T
volker.raschekandCopilot 1b82a15b7f feat!: replace postgresql-ha with CloudNativePG 
The bundled `postgresql-ha` sub-chart was the only HA-ready database option, but it pinned us to a Bitnami chart
whose images are no longer freely distributed, and it bundled repmgr and pgpool into the release. Operating a
Postgres cluster through a Helm release also means the chart has to reimplement failover, backup and upgrade
orchestration that a dedicated operator already solves.

CloudNativePG is the de-facto standard operator for Postgres on Kubernetes and handles instance management,
streaming replication, switchover and rolling upgrades itself. The operator is deliberately *not* part of this
chart: cluster-scoped CRDs and controllers do not belong into an application release and would conflict with an
operator that is already installed. The chart only renders the namespaced `Cluster` resource, so the operator can
be managed independently.

Because the operator cannot be assumed to be present, `cloudnativePG.enabled` defaults to `false`. Existing users
of `postgresql` or an external database are therefore unaffected.

Credentials follow the chart-wide `secrets.*` convention. Only the password is read from a Secret, because
CloudNativePG requires `bootstrap.initdb.database` and `bootstrap.initdb.owner` as literals in the `Cluster` spec
and cannot resolve them from a Secret. The password is injected into the `init-app-ini` container as
`GITEA__database__PASSWD` instead of being written into the generated `app.ini`.

BREAKING CHANGE: The `postgresql-ha` sub-chart and all `postgresql-ha.*` values have been removed. There is no
in-place migration path between the two deployments: dump the database of the old `postgresql-ha` release with
`pg_dump`, remove the `postgresql-ha` values, deploy the chart with `cloudnativePG.enabled=true` and restore the
dump. Setting `postgresql-ha` now fails the release with a pointer to the changelog.

Co-authored-by: Copilot <copilot@github.com>
2026-10-04 00:18:34 +02:00

8.7 KiB
Raw Blame History

High Availability

All components (in-memory DB, volume/asset storage, code indexer) used by Gitea must be deployed in a HA-ready fashion to achieve a full HA-ready Gitea deployment. The following document explains how to achieve this for all individual components.

The resulting Gitea deployment will consist of ~ 10 pods (depending on the chosen components and their replicas). One should evaluate upfront whether a HA-deployment is required as switching between HA/non-HA comes with some effort. For production instances, HA is always recommended to increase uptime and have a frictionless update process.

A general comment about chart dependencies and external services: Instead of relying on chart dependencies, it is often better to rely on an external, (managed) instances (in-memory database, asset storage provider, database, etc.). Many cloud providers offer such services, at least for databases or in-memory databases. They might cost a bit more than using a self-hosted k8s variant but are usually easier to maintain and scale, if needed. Also they can be centrally managed and are not linked to the Gitea helm chart or namespace. Please consider using external services before you start with your Gitea HA setup, it will make your life (and the life of the Gitea maintainers) easier.

This helm chart tries to help as much as possible to simplify and assert the provisioning of a HA-ready Gitea instance by implementing smart conditionals if deployment.replicas is set to a value > 1. Nevertheless, we cannot guarantee for every possible combination of Gitea settings to work together perfectly in a HA setup. As a general advice, we recommend to have a test environment aside on which to test possible changes/upgrades before applying these to a production installation.

Requirements for HA

Storage-wise, the HA-Gitea setup requires a RWX file-system which can be shared among the deployment-based replica pods. In addition, the following components are required for full HA-readiness:

  • A HA-ready issue (and optionally code) indexer: elasticsearch or meilisearch
  • A HA-ready external object/asset storage (minio) (optional, assets can also be stored on the RWX file-system)
  • A HA-ready cache (valkey-cluster)
  • A HA-ready DB

postgresql.enabled, which defaults to false, must stay disabled for a HA setup. The postgresql chart dependency is not HA-ready, use the cloudnativePG option instead.

The following sections discuss each of the components in more detail. Note that for each component discussed, the shown configurations only provides a (working) starting point, not necessarily the most optimal setup. We try to optimize this document over time as we have gained more experience with HA setups from users.

Indexers (Issues and code/repo)

The default code indexer bleve is not able to allow multiple connections and hence cannot be used in a HA setup. Alternatives are elasticsearch and meilisearch (as of >= 1.19.2). Unless you have an existing elasticsearch cluster, we recommend using meilisearch as it is faster and requires way less resources.

Unfortunately, meilisearch does only support the ISSUE_INDEXER and not the REPO_INDEXER yet (tracking issue). This means that the REPO_INDEXER must still be disabled for a HA setup right now. An alternative to the two options above for the ISSUE_INDEXER is "db", however we recommend to just go with meilisearch in this case and to not bother the DB with indexing.

To configure meilisearch within Gitea, do the following:

gitea:
  config:
    indexer:
      ISSUE_INDEXER_CONN_STR: <http://meilisearch.<namespace>.svc.cluster.local:7700>
      ISSUE_INDEXER_ENABLED: true
      ISSUE_INDEXER_TYPE: meilisearch
      REPO_INDEXER_ENABLED: false
      # REPO_INDEXER_TYPE: meilisearch # not yet working

Unfortunately meilisearch cannot be deployed in HA as of now. Nevertheless it allows for multiple Gitea requests at the same time and is therefore required in a HA setup.

Exemplary configuration for the meilisearch-kubernetes chart:

persistence:
  enabled: true
  accessMode: ReadWriteOnce
  size: 5Gi

Cache, session and queue

A valkey instance is required for the in-memory cache. Two options exist:

  • valkey
  • valkey-cluster

The chart provides valkey-cluster as a dependency as this one can be used for both HA and non-HA setups. You're also welcome to go with valkey if you prefer or already have a running instance.

It should be noted that valkey-cluster support is only available starting with Gitea 1.19.2. You can also configure an external (managed) valkey instance to be used. To do so, you need to set the following configuration values yourself:

  • gitea.config.queue.TYPE: valkey`

  • gitea.config.queue.CONN_STR: <your valkey connection string>

  • gitea.config.session.PROVIDER: valkey

  • gitea.config.session.PROVIDER_CONFIG: <your valkey connection string>

  • gitea.config.cache.ENABLED: true

  • gitea.config.cache.ADAPTER: valkey

  • gitea.config.cache.HOST: <your valkey connection string>

By default, the valkey-cluster chart provisions three standalone master nodes of which each has a single replica. To reduce the number of pods for a default Gitea deployment, we opted to omit the replicas (replicas: 0) by default. Only the minimum required number of master pods for a functional valkey-cluster deployment are provisioned. For a "proper" valkey-cluster setup however, we recommend to set replicas: 1 and nodes: 6.

Object and asset storage

Object/asset storage refers to the storage of attachments, avatars, LFS files, etc. While most of these can be stored on the RWX file-system, it is recommended to use an external S3-compatible object storage for such, mainly for performance reasons.

By default the chart provisions a single RWO volume to store everything (repos, avatars, packages, etc.). This volume cannot be mounted by multiple pods. Hence, a RWX volume is required and (optionally) an external HA-ready object storage.

Note: Double-check that the file permissions are set correctly on the RWX volume! That is everything should be owned by the git user which usually has uid=1000 and gid=1000.

To use minio you need to deploy and configure an external minio instance yourself and explicitly define the STORAGE_TYPE values as shown below.

Note that MINIO_BUCKET here is just a name and does not refer to a S3 bucket. It's the root access point for all objects belonging to the respective application, i.e., to Gitea in this case.

gitea:
  config:
    attachment:
      STORAGE_TYPE: minio
    lfs:
      STORAGE_TYPE: minio
    picture:
      AVATAR_STORAGE_TYPE: minio
    "storage.packages":
      STORAGE_TYPE: minio

    storage:
      MINIO_ENDPOINT: <minio-headless.<namespace>.svc.cluster.local:9000>
      MINIO_LOCATION: <location>
      MINIO_ACCESS_KEY_ID: <access key>
      MINIO_SECRET_ACCESS_KEY: <secret key>
      MINIO_BUCKET: <bucket name>
      MINIO_USE_SSL: false

Exemplary configuration for the bitnami minio chart:

auth:
  rootUser: minio
mode: distributed
replicaCount: 4
persistence:
  enabled: true
  size: 20Gi
  accessModes:
    - ReadWriteOnce

Database

By enabling cloudnativePG, the chart renders a CloudNativePG Cluster, which provides a HA-ready PostgreSQL via streaming replication. The CloudNativePG operator itself is not part of this chart and has to be installed cluster-wide beforehand. For that reason the option is disabled by default.

cloudnativePG:
  enabled: true
  instances: 3
  storage:
    size: 10Gi
    storageClass: <storage class>
  walStorage:
    enabled: true
    size: 2Gi
    storageClass: <storage class>

If you do not want to run the operator, using a managed database service in the cloud might be the easiest and most robust solution. Remember: keep cloudnativePG and postgresql disabled and configure the database connection manually via gitea.config.database:

cloudnativePG:
  enabled: false
postgresql:
  enabled: false

gitea:
  config:
    database:
      DB_TYPE: postgres
      HOST: <host>
      NAME: <name>
      USER: <user>

Known issues

  • Currently Cron jobs are run on all replicas as no leader election is implemented. See https://github.com/go-gitea/gitea/issues/13791 for a discussion and possible solution.

  • Running with multiple replicas slows down Gitea a bit, i.e. page loading time increases.

Reference in New Issue View Git Blame Copy Permalink