Merge branch '216191-puma-docs' into 'master'

Update administration docs to reflect Puma being default

Closes #216191

See merge request gitlab-org/gitlab!31745

.markdownlint.json

@@ -102,6 +102,7 @@
       "PostgreSQL",
       "Prometheus",
       "Puma",
+      "puma-worker-killer",
       "Python",
       "Rake",
       "Redis",

doc/administration/database_load_balancing.md

@@ -167,6 +167,10 @@ queried over UDP. To overcome this issue, you can use TCP for querying by settin
 
 ### Forking
 
+NOTE: **Note:**
+Starting with GitLab 13.0, Puma is the default web server used in GitLab
+all-in-one package based installations as well as GitLab Helm chart deployments.
+
 If you use an application server that forks, such as Unicorn, you _have to_
 update your Unicorn configuration to start service discovery _after_ a fork.
 Failure to do so will lead to service discovery only running in the parent

doc/administration/geo/replication/database.md

@@ -91,7 +91,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
    postgresql['sql_user_password'] = '<md5_hash_of_your_password>'
 
-   # Every node that runs Unicorn or Sidekiq needs to have the database
+   # Every node that runs Puma or Sidekiq needs to have the database
    # password specified as below. If you have a high-availability setup, this
    # must be present in all application nodes.
    gitlab_rails['db_password'] = '<your_password_here>'
@@ -273,7 +273,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
 1. Stop application server and Sidekiq
 
    ```shell
-   gitlab-ctl stop unicorn
+   gitlab-ctl stop puma
    gitlab-ctl stop sidekiq
    ```
 

doc/administration/geo/replication/high_availability.md

@@ -261,7 +261,7 @@ Configure the tracking database.
    redis_exporter['enable'] = false
    repmgr['enable'] = false
    sidekiq['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    ```
 
 After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) so the changes take effect.
@@ -354,7 +354,7 @@ On the secondary the following GitLab frontend services will be enabled:
 - `registry`
 - `remote-syslog`
 - `sidekiq`
-- `unicorn`
+- `puma`
 
 Verify these services by running `sudo gitlab-ctl status` on the frontend
 application servers.
@@ -407,7 +407,7 @@ application servers above, with some changes to run only the `sidekiq` service:
    redis['enable'] = false
    redis_exporter['enable'] = false
    repmgr['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
 
    ##
    ## The unique identifier for the Geo node.

doc/administration/geo/replication/security_review.md

@@ -177,7 +177,7 @@ from [owasp.org](https://owasp.org/).
 
 ### What databases and application servers support the application?
 
-- PostgreSQL >= 9.6, Redis, Sidekiq, Unicorn.
+- PostgreSQL >= 9.6, Redis, Sidekiq, Puma.
 
 ### How will database connection strings, encryption keys, and other sensitive components be stored, accessed, and protected from unauthorized detection?
 

doc/administration/gitaly/index.md

@@ -74,7 +74,7 @@ The following list depicts what the network architecture of Gitaly is:
 - A GitLab server can use one or more Gitaly servers.
 - Gitaly addresses must be specified in such a way that they resolve
   correctly for ALL Gitaly clients.
-- Gitaly clients are: Unicorn, Sidekiq, GitLab Workhorse,
+- Gitaly clients are: Puma/Unicorn, Sidekiq, GitLab Workhorse,
   GitLab Shell, Elasticsearch Indexer, and Gitaly itself.
 - A Gitaly server must be able to make RPC calls **to itself** via its own
   `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`.
@@ -195,7 +195,7 @@ authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configurati
    postgresql['enable'] = false
    redis['enable'] = false
    nginx['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    sidekiq['enable'] = false
    gitlab_workhorse['enable'] = false
    grafana['enable'] = false

doc/administration/gitaly/praefect.md

@@ -207,7 +207,7 @@ application server, or a Gitaly node.
    nginx['enable'] = false
    prometheus['enable'] = false
    grafana['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    sidekiq['enable'] = false
    gitlab_workhorse['enable'] = false
    gitaly['enable'] = false
@@ -421,7 +421,7 @@ documentation](index.md#3-gitaly-server-configuration).
    nginx['enable'] = false
    prometheus['enable'] = false
    grafana['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    sidekiq['enable'] = false
    gitlab_workhorse['enable'] = false
    prometheus_monitoring['enable'] = false

doc/administration/high_availability/gitlab.md

@@ -162,7 +162,7 @@ If you enable Monitoring, it must be enabled on **all** GitLab servers.
    node_exporter['listen_address'] = '0.0.0.0:9100'
    gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
    sidekiq['listen_address'] = "0.0.0.0"
-   unicorn['listen'] = '0.0.0.0'
+   puma['listen'] = '0.0.0.0'
 
    # Add the monitoring node's IP address to the monitoring whitelist and allow it to
    # scrape the NGINX metrics. Replace placeholder `monitoring.gitlab.example.com` with
@@ -174,9 +174,11 @@ If you enable Monitoring, it must be enabled on **all** GitLab servers.
 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration.
 
    CAUTION: **Warning:**
-   After changing `unicorn['listen']` in `gitlab.rb`, and running `sudo gitlab-ctl reconfigure`,
-   it can take an extended period of time for Unicorn to complete reloading after receiving a `HUP`.
-   For more information, see the [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401).
+   If running Unicorn, after changing `unicorn['listen']` in `gitlab.rb`, and
+   running `sudo gitlab-ctl reconfigure`, it can take an extended period of time
+   for Unicorn to complete reloading after receiving a `HUP`. For more
+   information, see the
+   [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401).
 
 ## Troubleshooting
 

doc/administration/high_availability/monitoring_node.md

@@ -64,7 +64,7 @@ Omnibus:
    redis['enable'] = false
    redis_exporter['enable'] = false
    sidekiq['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    node_exporter['enable'] = false
    gitlab_exporter['enable'] = false
    ```

doc/administration/high_availability/pgbouncer.md

@@ -165,7 +165,7 @@ Refer to your preferred Load Balancer's documentation for further guidance.
 
 1. Run `gitlab-ctl reconfigure`
 
-1. On the node running Unicorn, make sure the following is set in `/etc/gitlab/gitlab.rb`
+1. On the node running Puma, make sure the following is set in `/etc/gitlab/gitlab.rb`
 
    ```ruby
    gitlab_rails['db_host'] = 'PGBOUNCER_HOST'

doc/administration/high_availability/redis.md

@@ -63,7 +63,7 @@ Omnibus:
    ## Disable all other services
    sidekiq['enable'] = false
    gitlab_workhorse['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    postgresql['enable'] = false
    nginx['enable'] = false
    prometheus['enable'] = false

doc/administration/high_availability/sidekiq.md

@@ -88,7 +88,7 @@ you want using steps 1 and 2 from the GitLab downloads page.
    postgresql['enable'] = false
    redis['enable'] = false
    redis_exporter['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    gitlab_exporter['enable'] = false
    ```
 
@@ -119,7 +119,7 @@ postgres_exporter['enable'] = false
 postgresql['enable'] = false
 redis['enable'] = false
 redis_exporter['enable'] = false
-unicorn['enable'] = false
+puma['enable'] = false
 gitlab_exporter['enable'] = false
 
 ########################################

doc/administration/index.md

@@ -79,7 +79,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 
 - [Rake tasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, and more.
   - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance.
-- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Unicorn).
+- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Puma).
 - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components.
 - [Invalidate Markdown cache](invalidate_markdown_cache.md): Invalidate any cached Markdown.
 

doc/administration/job_logs.md

@@ -12,8 +12,8 @@ In the following table you can see the phases a log goes through:
 
 | Phase          | State        | Condition               | Data flow                                | Stored path |
 | -------------- | ------------ | ----------------------- | -----------------------------------------| ----------- |
-| 1: patching    | log          | When a job is running   | GitLab Runner => Unicorn => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` |
-| 2: overwriting | log          | When a job is finished  | GitLab Runner => Unicorn => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` |
+| 1: patching    | log          | When a job is running   | GitLab Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` |
+| 2: overwriting | log          | When a job is finished  | GitLab Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` |
 | 3: archiving   | archived log | After a job is finished | Sidekiq moves log to artifacts folder    | `#{ROOT_PATH}/gitlab-rails/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` |
 | 4: uploading   | archived log | After a log is archived | Sidekiq moves archived log to [object storage](#uploading-logs-to-object-storage) (if configured) | `#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` |
 

doc/administration/logs.md

@@ -538,8 +538,18 @@ This file lives in `/var/log/gitlab/gitaly/current` and is produced by [runit](h
 
 This file lives in `/var/log/gitlab/gitlab-rails/grpc.log` for Omnibus GitLab packages. Native [gRPC](https://grpc.io/) logging used by Gitaly.
 
+## `puma_stderr.log` & `puma_stdout.log`
+
+This file lives in `/var/log/gitlab/puma/puma_stderr.log` and `/var/log/gitlab/puma/puma_stdout.log` for
+Omnibus GitLab packages or in `/home/git/gitlab/log/puma_stderr.log` and `/home/git/gitlab/log/puma_stdout.log`
+for installations from source.
+
 ## `unicorn_stderr.log` & `unicorn_stdout.log`
 
+NOTE: **Note:**
+Starting with GitLab 13.0, Puma is the default web server used in GitLab
+all-in-one package based installations as well as GitLab Helm chart deployments.
+
 This file lives in `/var/log/gitlab/unicorn/unicorn_stderr.log` and `/var/log/gitlab/unicorn/unicorn_stdout.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/unicorn_stderr.log` and `/home/git/gitlab/log/unicorn_stdout.log`
 for installations from source.
@@ -565,12 +575,6 @@ I, [2015-02-13T07:16:01.534501 #13379]  INFO -- : worker=1 spawned pid=13379
 I, [2015-02-13T07:16:01.534848 #13379]  INFO -- : worker=1 ready
 ```
 
-## `puma_stderr.log` & `puma_stdout.log`
-
-This file lives in `/var/log/gitlab/puma/puma_stderr.log` and `/var/log/gitlab/puma/puma_stdout.log` for
-Omnibus GitLab packages or in `/home/git/gitlab/log/puma_stderr.log` and `/home/git/gitlab/log/puma_stdout.log`
-for installations from source.
-
 ## `repocheck.log`
 
 This file lives in `/var/log/gitlab/gitlab-rails/repocheck.log` for
@@ -657,7 +661,7 @@ will be generated in `/var/log/gitlab/gitlab-rails/sidekiq_exporter.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/sidekiq_exporter.log` for
 installations from source.
 
-If Prometheus metrics and the Web Exporter are both enabled, Unicorn/Puma will
+If Prometheus metrics and the Web Exporter are both enabled, Puma/Unicorn will
 start a Web server and listen to the defined port (default: `8083`). Access logs
 will be generated in `/var/log/gitlab/gitlab-rails/web_exporter.log` for
 Omnibus GitLab packages or in `/home/git/gitlab/log/web_exporter.log` for

doc/administration/operations/index.md

@@ -12,6 +12,7 @@ Keep your GitLab instance up and running smoothly.
 - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller
   to restart Sidekiq.
 - [Multiple Sidekiq processes](extra_sidekiq_processes.md): Configure multiple Sidekiq processes to ensure certain queues always have dedicated workers, no matter the number of jobs that need to be processed. **(CORE ONLY)**
+- [Puma](puma.md): Understand Puma and puma-worker-killer.
 - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer.
 - Speed up SSH operations by [Authorizing SSH users via a fast,
   indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or

doc/administration/operations/puma.md

@@ -3,7 +3,9 @@
 ## Puma
 
 As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced [Unicorn](https://yhbt.net/unicorn/).
-as the default web server.
+as the default web server. Starting with 13.0, both all-in-one package based
+installations as well as Helm chart based installations will run Puma instead of
+Unicorn unless explicitly specified not to.
 
 ## Why switch to Puma?
 

doc/administration/operations/sidekiq_memory_killer.md

@@ -2,13 +2,13 @@
 
 The GitLab Rails application code suffers from memory leaks. For web requests
 this problem is made manageable using
-[`unicorn-worker-killer`](https://github.com/kzk/unicorn-worker-killer) which
-restarts Unicorn worker processes in between requests when needed. The Sidekiq
+[`puma-worker-killer`](https://github.com/schneems/puma_worker_killer) which
+restarts Puma worker processes if it exceeds a memory limit. The Sidekiq
 MemoryKiller applies the same approach to the Sidekiq processes used by GitLab
 to process background jobs.
 
-Unlike unicorn-worker-killer, which is enabled by default for all GitLab
-installations since GitLab 6.4, the Sidekiq MemoryKiller is enabled by default
+Unlike puma-worker-killer, which is enabled by default for all GitLab
+installations since GitLab 13.0, the Sidekiq MemoryKiller is enabled by default
 _only_ for Omnibus packages. The reason for this is that the MemoryKiller
 relies on runit to restart Sidekiq after a memory-induced shutdown and GitLab
 installations from source do not all use runit or an equivalent.

doc/administration/operations/unicorn.md

 # Understanding Unicorn and unicorn-worker-killer
 
+NOTE: **Note:**
+Starting with GitLab 13.0, Puma is the default web server used in GitLab
+all-in-one package based installations as well as GitLab Helm chart deployments.
+
 ## Unicorn
 
 GitLab uses [Unicorn](https://yhbt.net/unicorn/), a pre-forking Ruby web

doc/administration/pages/index.md

@@ -472,7 +472,7 @@ To configure GitLab Pages on a separate server:
    postgresql['enable'] = false
    redis['enable'] = false
    prometheus['enable'] = false
-   unicorn['enable'] = false
+   puma['enable'] = false
    sidekiq['enable'] = false
    gitlab_workhorse['enable'] = false
    gitaly['enable'] = false

doc/administration/reference_architectures/index.md

@@ -165,7 +165,7 @@ column.
 | Redis Sentinel | High availability for Redis | [Redis Sentinel configuration](../high_availability/redis.md) | Yes |
 | [Gitaly](../../development/architecture.md#gitaly) ([2](#footnotes)) ([7](#footnotes)) ([10](#footnotes)) | Provides access to Git repositories | [Gitaly configuration](../gitaly/index.md#running-gitaly-on-its-own-server) | Yes |
 | [Sidekiq](../../development/architecture.md#sidekiq) | Asynchronous/background jobs | [Sidekiq configuration](../high_availability/sidekiq.md) | Yes |
-| [GitLab application services](../../development/architecture.md#unicorn)([1](#footnotes)) | Unicorn/Puma, Workhorse, GitLab Shell - serves front-end requests (UI, API, Git over HTTP/SSH) | [GitLab app scaling configuration](../high_availability/gitlab.md) | Yes |
+| [GitLab application services](../../development/architecture.md#unicorn)([1](#footnotes)) | Puma/Unicorn, Workhorse, GitLab Shell - serves front-end requests (UI, API, Git over HTTP/SSH) | [GitLab app scaling configuration](../high_availability/gitlab.md) | Yes |
 | [Prometheus](../../development/architecture.md#prometheus) and [Grafana](../../development/architecture.md#grafana) | GitLab environment monitoring | [Monitoring node for scaling](../high_availability/monitoring_node.md) | Yes |
 
 ## Footnotes

doc/administration/restart_gitlab.md

@@ -16,7 +16,7 @@ If you have used the [Omnibus packages](https://about.gitlab.com/install/) to in
 you should already have `gitlab-ctl` in your `PATH`.
 
 `gitlab-ctl` interacts with the Omnibus packages and can be used to restart the
-GitLab Rails application (Unicorn) as well as the other components, like:
+GitLab Rails application (Puma) as well as the other components, like:
 
 - GitLab Workhorse
 - Sidekiq
@@ -45,7 +45,7 @@ ok: run: nginx: (pid 11309) 0s
 ok: run: postgresql: (pid 11316) 1s
 ok: run: redis: (pid 11325) 0s
 ok: run: sidekiq: (pid 11331) 1s
-ok: run: unicorn: (pid 11338) 0s
+ok: run: puma: (pid 11338) 0s
 ```
 
 To restart a component separately, you can append its service name to the
@@ -110,25 +110,25 @@ sudo service gitlab restart
 The output should be similar to this:
 
 ```plaintext
-Shutting down GitLab Unicorn
+Shutting down GitLab Puma
 Shutting down GitLab Sidekiq
 Shutting down GitLab Workhorse
 Shutting down GitLab MailRoom
 ...
 GitLab is not running.
-Starting GitLab Unicorn
+Starting GitLab Puma
 Starting GitLab Sidekiq
 Starting GitLab Workhorse
 Starting GitLab MailRoom
 ...
-The GitLab Unicorn web server with pid 28059 is running.
+The GitLab Puma web server with pid 28059 is running.
 The GitLab Sidekiq job dispatcher with pid 28176 is running.
 The GitLab Workhorse with pid 28122 is running.
 The GitLab MailRoom email processor with pid 28114 is running.
 GitLab and all its components are up and running.
 ```
 
-This should restart Unicorn, Sidekiq, GitLab Workhorse, and [Mailroom](reply_by_email.md)
+This should restart Puma, Sidekiq, GitLab Workhorse, and [Mailroom](reply_by_email.md)
 (if enabled). The init service file that does all the magic can be found on
 your server in `/etc/init.d/gitlab`.
 
@@ -142,7 +142,7 @@ If you are using other init systems, like systemd, you can check the
 
 There is no single command to restart the entire GitLab application installed via
 the [cloud native Helm Chart](https://docs.gitlab.com/charts/). Usually, it should be
-enough to restart a specific component separately (for example, `gitaly`, `unicorn`,
+enough to restart a specific component separately (for example, `gitaly`, `puma`,
 `workhorse`, or `gitlab-shell`) by deleting all the pods related to it:
 
 ```shell

doc/administration/troubleshooting/kubernetes_cheat_sheet.md

@@ -52,7 +52,7 @@ and they will assist you with any issues you are having.
   - Check logs via Kubectl:
 
     ```shell
-    kubectl logs <unicorn pod> -c dependencies
+    kubectl logs <webservice pod> -c dependencies
     ```
 
 - How to tail all Kubernetes cluster events in real time:
@@ -87,20 +87,20 @@ and they will assist you with any issues you are having.
 - Minimal config that can be used to test a Kubernetes Helm chart can be found
   [here](https://gitlab.com/gitlab-org/charts/gitlab/issues/620).
 
-- Tailing logs of a separate pod. An example for a Unicorn pod:
+- Tailing logs of a separate pod. An example for a Webservice pod:
 
   ```shell
-  kubectl logs gitlab-unicorn-7656fdd6bf-jqzfs -c unicorn
+  kubectl logs gitlab-webservice-54fbf6698b-hpckq -c webservice
   ```
 
-- Tail and follow all pods that share a label (in this case, `unicorn`):
+- Tail and follow all pods that share a label (in this case, `webservice`):
 
   ```shell
-  # all containers in the unicorn pods
-  kubectl logs -f -l app=unicorn --all-containers=true --max-log-requests=50
+  # all containers in the webservice pods
+  kubectl logs -f -l app=webservice --all-containers=true --max-log-requests=50
 
-  # only the unicorn containers in all unicorn pods
-  kubectl logs -f -l app=unicorn -c unicorn --max-log-requests=50
+  # only the webservice containers in all webservice pods
+  kubectl logs -f -l app=webservice -c webservice --max-log-requests=50
   ```
 
 - One can stream logs from all containers at once, similar to the Omnibus

doc/administration/uploads.md

@@ -65,7 +65,7 @@ For source installations the following settings are nested under `uploads:` and
 |---------|-------------|---------|
 | `enabled` | Enable/disable object storage | `false` |
 | `remote_directory` | The bucket name where Uploads will be stored| |
-| `direct_upload` | Set to true to remove Unicorn from the Upload path. Workhorse handles the actual Artifact Upload to Object Storage while Unicorn does minimal processing to keep track of the upload. There is no need for local shared storage. The option may be removed if support for a single storage type for all files is introduced. Read more on [direct upload](../development/uploads.md#direct-upload). | `false` |
+| `direct_upload` | Set to true to remove Puma from the Upload path. Workhorse handles the actual Artifact Upload to Object Storage while Puma does minimal processing to keep track of the upload. There is no need for local shared storage. The option may be removed if support for a single storage type for all files is introduced. Read more on [direct upload](../development/uploads.md#direct-upload). | `false` |
 | `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 (if `direct_upload` is set to `true` it will override `background_upload`) | `true` |
 | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
 | `connection` | Various connection options described below | |