138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
---
|
|
stage: Enablement
|
|
group: Geo
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# GitLab in maintenance mode **PREMIUM SELF**
|
|
|
|
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9.
|
|
|
|
In maintenance mode, most write operations are disabled at the application level.
|
|
This means that GitLab is effectively in a read-only mode for all non-administrative
|
|
users (administrators are still able to edit application settings). Regular users
|
|
are able to log in to GitLab, view the interface and perform other read-only
|
|
operations, such as `git clone` or `git pull`.
|
|
|
|
## Enable maintenance mode
|
|
|
|
There are three ways to enable maintenance mode as an administrator:
|
|
|
|
- **Web UI**:
|
|
1. Navigate to the **Admin Area > Application settings > General** and toggle
|
|
the maintenance mode. You can optionally add a message for the banner as well.
|
|
1. Click **Save** for the changes to take effect.
|
|
|
|
- **API**:
|
|
|
|
```shell
|
|
curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"
|
|
```
|
|
|
|
- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session):
|
|
|
|
```ruby
|
|
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: true)
|
|
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode_message: "New message")
|
|
```
|
|
|
|
## Disable maintenance mode
|
|
|
|
There are three ways to disable maintenance mode:
|
|
|
|
- **Web UI**:
|
|
1. Navigate to the **Admin Area > Application settings > General** and toggle
|
|
the maintenance mode. You can optionally add a message for the banner as well.
|
|
1. Click **Save** for the changes to take effect.
|
|
|
|
- **API**:
|
|
|
|
```shell
|
|
curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"
|
|
```
|
|
|
|
- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session):
|
|
|
|
```ruby
|
|
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: false)
|
|
```
|
|
|
|
## Behavior in maintenance mode
|
|
|
|
When maintenance mode is enabled, a banner is displayed at the top of the page.
|
|
The banner can be customized with a specific message.
|
|
|
|
An error is displayed when a user tries to perform a write operation that isn't allowed.
|
|
The API will return a 403 or 503 error for failed write requests.
|
|
|
|
NOTE:
|
|
In some cases, the visual feedback from an action could be misleading, for example
|
|
when starring a project, the **Star** button changes to show the **Unstar** action,
|
|
however, this is only the frontend update, and it doesn't take into account the
|
|
failed status of the POST request. These visual bugs are to be fixed
|
|
[in follow-up iterations](https://gitlab.com/gitlab-org/gitlab/-/issues/295197).
|
|
|
|
### Application settings
|
|
|
|
In maintenance mode, admins can edit the application settings. This will allow
|
|
them to disable maintenance mode after it's been enabled.
|
|
|
|
### Logging in/out
|
|
|
|
All users can log in and out of the GitLab instance.
|
|
|
|
### CI/CD
|
|
|
|
In maintenance mode:
|
|
|
|
- No new jobs are started. Already running jobs stay in 'running'
|
|
status but their logs are no longer updated.
|
|
- If the job has been in 'running' state for longer than the project's time limit,
|
|
it will **not** time out.
|
|
- Pipelines cannot be started, retried or canceled in maintenance mode.
|
|
No new jobs can be created either.
|
|
|
|
Once maintenance mode is disabled, new jobs are picked up again. The jobs that were
|
|
in the running state before enabling maintenance mode, will resume, and their logs
|
|
will start getting updated again.
|
|
|
|
### Git actions
|
|
|
|
All read-only Git operations will continue to work in maintenance mode, for example
|
|
`git clone` and `git pull`, but all write operations will fail, both through the CLI
|
|
and Web IDE.
|
|
|
|
Geo secondaries are read-only instances that allow Git pushes because they are
|
|
proxied to the primary instance. However, in maintenance mode, Git pushes to
|
|
both primary and secondaries will fail.
|
|
|
|
### Merge requests, issues, epics
|
|
|
|
All write actions except those mentioned above will fail. So, in maintenace mode, a user cannot update merge requests, issues, etc.
|
|
|
|
### Container Registry
|
|
|
|
In maintenance mode, `docker push` is blocked, but `docker pull` is available.
|
|
|
|
### Auto Deploys
|
|
|
|
It is recommended to disable auto deploys during maintenance mode, and enable
|
|
them once maintenance mode is disabled.
|
|
|
|
### Background jobs
|
|
|
|
Background jobs (cron jobs, Sidekiq) will continue running as is, because maintenance
|
|
mode does not disable any background jobs.
|
|
|
|
[During a planned Geo failover](../geo/disaster_recovery/planned_failover.md#prevent-updates-to-the-primary-node),
|
|
it is recommended that you disable all cron jobs except for those related to Geo.
|
|
|
|
You can monitor queues and disable jobs in **Admin Area > Monitoring > Background Jobs**.
|
|
|
|
### Geo secondaries
|
|
|
|
The maintenance mode setting will be propagated to the secondary as they sync up.
|
|
It is important that you do not disable replication before enabling maintenance mode.
|
|
|
|
Replication and verification will continue to work in maintenance mode.
|