Restructure changelog/upgrading approach (#331)
Description of the change
Mostly, this change just moves the changelog to the bottom of the README which helps new users to see the actual documentation. As the structure for the changes itself is slightly different, there are some changes in wording so that it still makes sense. But mostly structural changes.
The change within the dependency section is due to a broken link since auto-generating the parameters section. Now there are links to every dependency related parameters.
Benefits
It helps us to maintain a clear structure for the README of this project.
Possible drawbacks
Our users are currently trained to look at the top of the document to see the changes. They now have to scroll down or use the quick link from installation section.
Applicable issues
fixes #247
Additional information
Every version section starts with a disclaimer right now. This is duplicated and might hide important text due to its existence. A centralized intruduction at top of the upgrading section tells the reader what to expect from that whole section.
I've also noticed that on ArtifactHub the emotes are not rendered correctly. So I replaced them with the actual ones and reduced their usage. That way it better highlights those parts the reader must not miss.
Reviewed-on: https://gitea.com/gitea/helm-chart/pulls/331
Reviewed-by: luhahn <luhahn@noreply.gitea.io>
Reviewed-by: techknowlogick <techknowlogick@gitea.io>
Co-authored-by: justusbunsi <justusbunsi@noreply.gitea.io>
Co-committed-by: justusbunsi <justusbunsi@noreply.gitea.io>
This commit is contained in:
justusbunsi
luhahn
parent
aa97cdab5b
commit
32735ed4df
361
README.md
361
README.md
|
|
@ -15,13 +15,14 @@ as well as being deployed as a statefulset to retain stored repositories.
|
|||
|
||||
Gitea can be run with an external database and cache. This chart provides those
|
||||
dependencies, which can be enabled, or disabled via
|
||||
[configuration](#configuration).
|
||||
configuration.
|
||||
|
||||
Dependencies:
|
||||
|
||||
- PostgreSQL
|
||||
- Memcached
|
||||
- MySQL
|
||||
- PostgreSQL ([configuration](#postgresql))
|
||||
- Memcached ([configuration](#memcached))
|
||||
- MySQL ([configuration](#mysql))
|
||||
- MariaDB ([configuration](#mariadb))
|
||||
|
||||
## Installing
|
||||
|
||||
|
|
@ -31,185 +32,15 @@ helm repo update
|
|||
helm install gitea gitea-charts/gitea
|
||||
```
|
||||
|
||||
When upgrading, please refer to the [Upgrading](#upgrading) section at the bottom
|
||||
of this document for major and breaking changes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Kubernetes 1.12+
|
||||
- Helm 3.0+
|
||||
- PV provisioner for persistent data support
|
||||
|
||||
## Chart upgrade to 6.0.0
|
||||
|
||||
:warning: The most recent `6.0.0` update brings some major and breaking changes.
|
||||
Please note the following changes in the Chart to upgrade successfully. :warning:
|
||||
|
||||
### Enabled flag for `startupProbe`
|
||||
|
||||
Prior to this version the `startupProbe` was just a commented sample within the
|
||||
`values.yaml`. With the migration to an auto-generated [Parameters](#parameters)
|
||||
section, a new parameter `gitea.startupProbe.enabled` has been introduced set to
|
||||
`false` by default. If you are using the `startupProbe` you need to add that new
|
||||
parameter and set it to `true`. Otherwise, your defined probe won't be considered
|
||||
after the upgrade.
|
||||
|
||||
## Chart upgrade to 5.0.0
|
||||
|
||||
:warning: The most recent `5.0.0` update brings some major and breaking changes.
|
||||
Please note the following changes in the Chart to upgrade successfully. :warning:
|
||||
|
||||
### Enable Dependencies
|
||||
|
||||
:warning: The values to enable the dependencies,
|
||||
such as PostgreSQL, Memcached, MySQL and MariaDB
|
||||
have been moved from `gitea.database.builtIn.` to the dependency values. :warning:
|
||||
|
||||
You can now enable the dependencies as followed:
|
||||
|
||||
```yaml
|
||||
memcached:
|
||||
enabled: true
|
||||
|
||||
postgresql:
|
||||
enabled: true
|
||||
|
||||
mysql:
|
||||
enabled: false
|
||||
|
||||
mariadb:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
### App.ini generation
|
||||
|
||||
The app.ini generation has changed and now utilizes the environment-to-ini
|
||||
script provided by newer Gitea versions.
|
||||
|
||||
> :boom: The Helm Chart now requires Gitea versions of at least 1.11.0.
|
||||
|
||||
This change ensures, that the app.ini is now persistent.
|
||||
|
||||
#### Secret Key generation
|
||||
|
||||
Gitea secret keys (SECRET_KEY, INTERNAL_TOKEN, JWT_SECRET) are now generated
|
||||
automatically in certain situations:
|
||||
|
||||
- New install: By default the secrets are created automatically. If you provide
|
||||
secrets via `gitea.config` they will be used instead of automatic generation.
|
||||
- Existing installs: The secrets won't be deployed, neither via
|
||||
configuration nor via auto generation. We explicitly prevent to set new secrets.
|
||||
|
||||
> :rotating_light: It would be possible to set new secret keys manually by entering
|
||||
the running container and rewriting the app.ini by hand. However, this it is
|
||||
not advisable to do so for existing installations. Certain settings like
|
||||
_LDAP_ would not be readable anymore.
|
||||
|
||||
### Probes
|
||||
|
||||
> :boom: `gitea.customLivenessProbe`, `gitea.customReadinessProbe` and `gitea.customStartupProbe`
|
||||
have been removed.
|
||||
|
||||
They are replaced by the settings `gitea.livenessProbe`, `gitea.readinessProbe`
|
||||
and `gitea.startupProbe` which are now fully configurable and used _as-is_ for
|
||||
a Chart deployment.
|
||||
If you have customized their values instead of using the `custom` prefixed settings,
|
||||
please ensure that you remove the `enabled` property from each of them.
|
||||
|
||||
In case you want to disable one of these probes, let's say the `livenessProbe`, add
|
||||
the following to your values. The `podAnnotation` is just there to have a bit more
|
||||
context.
|
||||
|
||||
```diff
|
||||
gitea:
|
||||
+ livenessProbe:
|
||||
podAnnotations: {}
|
||||
```
|
||||
|
||||
### Multiple OAuth and LDAP authentication sources
|
||||
|
||||
With `5.0.0` of this Chart it is now possible to configure Gitea with multiple
|
||||
OAuth and LDAP sources. As a result, you need to update an existing OAuth/LDAP configuration
|
||||
in your customized `values.yaml` by replacing the object with settings to a list
|
||||
of settings objects. See [OAuth2 Settings](#oauth-settings) and
|
||||
[LDAP Settings](#ldap-settings) section for details.
|
||||
|
||||
## Chart upgrade from 3.x.x to 4.0.0
|
||||
|
||||
:warning: The most recent `4.0.0` update brings some breaking changes. Please note
|
||||
the following changes in the Chart to upgrade successfully. :warning:
|
||||
|
||||
### Ingress changes
|
||||
|
||||
To provide a more flexible Ingress configuration we now support not only host
|
||||
settings but also provide configuration for the path and pathType. So this
|
||||
change changes the hosts from a simple string list, to a list containing a more
|
||||
complex object for more configuration.
|
||||
|
||||
```diff
|
||||
ingress:
|
||||
enabled: false
|
||||
annotations: {}
|
||||
# kubernetes.io/ingress.class: nginx
|
||||
# kubernetes.io/tls-acme: "true"
|
||||
- hosts:
|
||||
- - git.example.com
|
||||
+ hosts:
|
||||
+ - host: git.example.com
|
||||
+ paths:
|
||||
+ - path: /
|
||||
+ pathType: Prefix
|
||||
tls: []
|
||||
# - secretName: chart-example-tls
|
||||
# hosts:
|
||||
# - git.example.com
|
||||
```
|
||||
|
||||
If you want everything as it was before, you can simply add the following code
|
||||
to all your host entries.
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
```
|
||||
|
||||
### Dropped kebab-case support
|
||||
|
||||
In 3.x.x it was possible to provide an ldap configuration via kebab-case, this
|
||||
support has now been dropped and only camel case is supported. See [LDAP
|
||||
section](#ldap-settings) for more information.
|
||||
|
||||
### Dependency update
|
||||
|
||||
The chart comes with multiple databases and Memcached as dependency, the latest
|
||||
release updated the dependencies.
|
||||
|
||||
- Memcached: `4.2.20` -> `5.9.0`
|
||||
- PostgreSQL: `9.7.2` -> `10.3.17`
|
||||
- MariaDB: `8.0.0` -> `9.3.6`
|
||||
|
||||
If you're using the builtin databases you will most likely redeploy the chart in
|
||||
order to update the database correctly.
|
||||
|
||||
### Execution of initPreScript
|
||||
|
||||
Generally spoken, this might not be a breaking change, but it is worth to be
|
||||
mentioned.
|
||||
|
||||
Prior to `4.0.0` only one init container was used to both setup directories and
|
||||
configure Gitea. As of now the actual Gitea configuration is separated from the
|
||||
other pre-execution. This also includes the execution of _initPreScript_. If you
|
||||
have such script, please be aware of this. Dynamically prepare the Gitea setup
|
||||
during execution by e.g. adding environment variables to the execution context
|
||||
won't work anymore.
|
||||
|
||||
## Gitea Version 1.14.X repository ROOT
|
||||
|
||||
Previously the ROOT folder for the Gitea repositories was located at
|
||||
`/data/git/gitea-repositories`. In version `1.14` has the path been changed to
|
||||
`/data/gitea-repositories`.
|
||||
|
||||
This chart will set the `gitea.config.repository.ROOT` value default to
|
||||
`/data/git/gitea-repositories`.
|
||||
|
||||
## Configure Commit Signing
|
||||
|
||||
When using the rootless image the gpg key folder was is not persistent by
|
||||
|
|
@ -639,8 +470,8 @@ gitea:
|
|||
...
|
||||
```
|
||||
|
||||
:warning: Some options are just flags and therefore don't any values. If they
|
||||
are defined in `gitea.ldap` configuration, they will be passed to the Gitea cli
|
||||
⚠️ Some options are just flags and therefore don't have any values. If they
|
||||
are defined in `gitea.ldap` configuration, they will be passed to the Gitea CLI
|
||||
without any value. Affected options:
|
||||
|
||||
- notActive
|
||||
|
|
@ -947,3 +778,175 @@ gitea:
|
|||
Expected workflow is: Fork -> Patch -> Push -> Pull Request
|
||||
|
||||
See [CONTRIBUTORS GUIDE](CONTRIBUTING.md) for details.
|
||||
|
||||
## Upgrading
|
||||
|
||||
This section lists major and breaking changes of each Helm Chart version.
|
||||
Please read them carefully to upgrade successfully.
|
||||
|
||||
### To 6.0.0
|
||||
|
||||
#### New `enabled` flag for `startupProbe`
|
||||
|
||||
Prior to this version the `startupProbe` was just a commented sample within the
|
||||
`values.yaml`. With the migration to an auto-generated [Parameters](#parameters)
|
||||
section, a new parameter `gitea.startupProbe.enabled` has been introduced set to
|
||||
`false` by default.
|
||||
|
||||
If you are using the `startupProbe` you need to add that new
|
||||
parameter and set it to `true`. Otherwise, your defined probe won't be considered
|
||||
after the upgrade.
|
||||
|
||||
### To 5.0.0
|
||||
|
||||
> 💥 The Helm Chart now requires Gitea versions of at least 1.11.0.
|
||||
|
||||
#### Enable Dependencies
|
||||
|
||||
The values to enable the dependencies,
|
||||
such as PostgreSQL, Memcached, MySQL and MariaDB
|
||||
have been moved from `gitea.database.builtIn.` to the dependency values.
|
||||
|
||||
You can now enable the dependencies as followed:
|
||||
|
||||
```yaml
|
||||
memcached:
|
||||
enabled: true
|
||||
|
||||
postgresql:
|
||||
enabled: true
|
||||
|
||||
mysql:
|
||||
enabled: false
|
||||
|
||||
mariadb:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
#### App.ini generation
|
||||
|
||||
The app.ini generation has changed and now utilizes the environment-to-ini
|
||||
script provided by newer Gitea versions. This change ensures, that the app.ini
|
||||
is now persistent.
|
||||
|
||||
##### Secret Key generation
|
||||
|
||||
Gitea secret keys (SECRET_KEY, INTERNAL_TOKEN, JWT_SECRET) are now generated
|
||||
automatically in certain situations:
|
||||
|
||||
- New install: By default the secrets are created automatically. If you provide
|
||||
secrets via `gitea.config` they will be used instead of automatic generation.
|
||||
- Existing installs: The secrets won't be deployed, neither via
|
||||
configuration nor via auto generation. We explicitly prevent to set new secrets.
|
||||
|
||||
> 💡 It would be possible to set new secret keys manually by entering
|
||||
the running container and rewriting the app.ini by hand. However, this it is
|
||||
not advisable to do so for existing installations. Certain settings like
|
||||
_LDAP_ would not be readable anymore.
|
||||
|
||||
#### Probes
|
||||
|
||||
`gitea.customLivenessProbe`, `gitea.customReadinessProbe` and `gitea.customStartupProbe`
|
||||
have been removed.
|
||||
|
||||
They are replaced by the settings `gitea.livenessProbe`, `gitea.readinessProbe`
|
||||
and `gitea.startupProbe` which are now fully configurable and used _as-is_ for
|
||||
a Chart deployment.
|
||||
If you have customized their values instead of using the `custom` prefixed settings,
|
||||
please ensure that you remove the `enabled` property from each of them.
|
||||
|
||||
In case you want to disable one of these probes, let's say the `livenessProbe`, add
|
||||
the following to your values. The `podAnnotation` is just there to have a bit more
|
||||
context.
|
||||
|
||||
```diff
|
||||
gitea:
|
||||
+ livenessProbe:
|
||||
podAnnotations: {}
|
||||
```
|
||||
|
||||
#### Multiple OAuth and LDAP authentication sources
|
||||
|
||||
With `5.0.0` of this Chart it is now possible to configure Gitea with multiple
|
||||
OAuth and LDAP sources. As a result, you need to update an existing OAuth/LDAP configuration
|
||||
in your customized `values.yaml` by replacing the object with settings to a list
|
||||
of settings objects. See [OAuth2 Settings](#oauth2-settings) and
|
||||
[LDAP Settings](#ldap-settings) section for details.
|
||||
|
||||
### To 4.0.0
|
||||
|
||||
#### Ingress changes
|
||||
|
||||
To provide a more flexible Ingress configuration we now support not only host
|
||||
settings but also provide configuration for the path and pathType. So this
|
||||
change changes the hosts from a simple string list, to a list containing a more
|
||||
complex object for more configuration.
|
||||
|
||||
```diff
|
||||
ingress:
|
||||
enabled: false
|
||||
annotations: {}
|
||||
# kubernetes.io/ingress.class: nginx
|
||||
# kubernetes.io/tls-acme: "true"
|
||||
- hosts:
|
||||
- - git.example.com
|
||||
+ hosts:
|
||||
+ - host: git.example.com
|
||||
+ paths:
|
||||
+ - path: /
|
||||
+ pathType: Prefix
|
||||
tls: []
|
||||
# - secretName: chart-example-tls
|
||||
# hosts:
|
||||
# - git.example.com
|
||||
```
|
||||
|
||||
If you want everything as it was before, you can simply add the following code
|
||||
to all your host entries.
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
```
|
||||
|
||||
#### Dropped kebab-case support
|
||||
|
||||
In 3.x.x it was possible to provide an ldap configuration via kebab-case, this
|
||||
support has now been dropped and only camel case is supported. See [LDAP
|
||||
section](#ldap-settings) for more information.
|
||||
|
||||
#### Dependency update
|
||||
|
||||
The chart comes with multiple databases and Memcached as dependency, the latest
|
||||
release updated the dependencies.
|
||||
|
||||
- Memcached: `4.2.20` -> `5.9.0`
|
||||
- PostgreSQL: `9.7.2` -> `10.3.17`
|
||||
- MariaDB: `8.0.0` -> `9.3.6`
|
||||
|
||||
If you're using the builtin databases you will most likely redeploy the chart in
|
||||
order to update the database correctly.
|
||||
|
||||
#### Execution of initPreScript
|
||||
|
||||
Generally spoken, this might not be a breaking change, but it is worth to be
|
||||
mentioned.
|
||||
|
||||
Prior to `4.0.0` only one init container was used to both setup directories and
|
||||
configure Gitea. As of now the actual Gitea configuration is separated from the
|
||||
other pre-execution. This also includes the execution of _initPreScript_. If you
|
||||
have such script, please be aware of this. Dynamically prepare the Gitea setup
|
||||
during execution by e.g. adding environment variables to the execution context
|
||||
won't work anymore.
|
||||
|
||||
### Misc
|
||||
|
||||
#### Gitea Version 1.14.X repository ROOT
|
||||
|
||||
Previously the ROOT folder for the Gitea repositories was located at
|
||||
`/data/git/gitea-repositories`. In version `1.14` has the path been changed to
|
||||
`/data/gitea-repositories`.
|
||||
|
||||
This chart will set the `gitea.config.repository.ROOT` value default to
|
||||
`/data/git/gitea-repositories`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue