Document maintenance mode

doc/administration/index.md

@@ -102,6 +102,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 #### Updating GitLab
 
 - [GitLab versions and maintenance policy](../policy/maintenance.md): Understand GitLab versions and releases (Major, Minor, Patch, Security), as well as update recommendations.
+- [GitLab in maintenance mode](maintenance_mode/index.md): Put GitLab in maintenance mode.
 - [Update GitLab](../update/README.md): Update guides to upgrade your installation to a new version.
 - [Upgrading without downtime](../update/README.md#upgrading-without-downtime): Upgrade to a newer major, minor, or patch version of GitLab without taking your GitLab instance offline.
 - [Migrate your GitLab CI/CD data to another version of GitLab](../migrate_ci_to_ce/README.md): If you have an old GitLab installation (older than 8.0), follow this guide to migrate your existing GitLab CI/CD data to another version of GitLab.

doc/administration/maintenance_mode/index.md

+---
+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.