From 2314bb66cc489196ccfc5dbce25d80358785b5ae Mon Sep 17 00:00:00 2001 From: Jaime Martinez Date: Wed, 8 Apr 2020 14:51:07 +1000 Subject: [PATCH 1/4] Update documentation for Pages administration Update documentation for GitLab Pages administration to include a section about using API-based configuration. Includes steps to disable this feature introduced via this [Pages MR]( https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/264) and [Omnibus MR] (https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4057) Add sync secrets section to pages admin --- .../update-gitlab-pages-admin-doc.yml | 5 ++ doc/administration/pages/index.md | 74 +++++++++++++++---- 2 files changed, 63 insertions(+), 16 deletions(-) create mode 100644 changelogs/unreleased/update-gitlab-pages-admin-doc.yml diff --git a/changelogs/unreleased/update-gitlab-pages-admin-doc.yml b/changelogs/unreleased/update-gitlab-pages-admin-doc.yml new file mode 100644 index 00000000000000..3e94bef8ca098d --- /dev/null +++ b/changelogs/unreleased/update-gitlab-pages-admin-doc.yml @@ -0,0 +1,5 @@ +--- +title: Update documentation for GitLab Pages administration +merge_request: 29103 +author: +type: other diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index e2863eb7e40536..ad05f3a5fd103c 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -500,21 +500,12 @@ configuring a load balancer to work at the IP level, and so on. If you wish to set up GitLab Pages on multiple servers, perform the above procedure for each Pages server. -### Access control when running GitLab Pages on a separate server +### Sync secrets with GitLab server when running GitLab Pages on a seprate server If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), -then you must use the following procedure to configure [access control](#access-control): - -1. On the **GitLab server**, add the following to `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['enable'] = true - gitlab_pages['access_control'] = true - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. The `gitlab-secrets.json` file is now updated with the - new configuration. +and you want to enable [access-control](#access-control) or use +[GitLab Pages API-based configuration](#gitlab-pages-api-based-configuration), +then you must use the following procedure to sync secrets between your instances: DANGER: **Danger:** The `gitlab-secrets.json` file contains secrets that control database encryption. @@ -534,6 +525,30 @@ then you must use the following procedure to configure [access control](#access- cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak ``` +1. Open the `/etc/gitlab/gitlab-secrets.json` file on the **GitLab server** + and copy the value of the `gitlab_pages` section to the + `/etc/gitlab/gitlab-secrets.json` file on the **Pages server** + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + +### Access control when running GitLab Pages on a separate server + +If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +then you must use the following procedure to configure [access control](#access-control): + +1. On the **GitLab server**, add the following to `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['enable'] = true + gitlab_pages['access_control'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the + changes to take effect. The `gitlab-secrets.json` file is now updated with the + new configuration. + +1. [Sync secrets with GitLab server when running GitLab Pages on a seprate server](#sync-secrets-with-gitlab-server-when-running-gitlab-pages-on-a-seprate-server) + 1. Disable Pages on the **GitLab server** by setting the following in `/etc/gitlab/gitlab.rb`: @@ -543,9 +558,6 @@ then you must use the following procedure to configure [access control](#access- 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the **GitLab server** - to the **Pages server**. - 1. On your **Pages server**, add the following to `/etc/gitlab/gitlab.rb`: ```ruby @@ -555,6 +567,36 @@ then you must use the following procedure to configure [access control](#access- 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +### GitLab Pages API-based configuration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/282) in GitLab 12.10. + +GitLab Pages new API-based configuration is now available in 13.0 and will replace the +disk source configuration. You still can use the old configuration for next year, +although we don't recommend it and new features will not be supported. In many cases, +GitLab Pages will automatically switch to the API-based configuration without any action. +If you host GitLab Pages on a separate server, see the +[how to use API-Based configuration](#how-to-use-api-based-configuration) section. +Should you encounter an issue with the new configuration, you can +[disable it](#disable-api-based-configuration) and report an issue. + +#### How to use API-based configuration + +If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +you must [Sync secrets with GitLab server when running GitLab Pages on a seprate server](#sync-secrets-with-gitlab-server-when-running-gitlab-pages-on-a-seprate-server). + +#### Disable API-based configuration + +If you run into some problems with API configuration source, you can disable it by following these steps: + +1. On your **Pages server**, add the following to `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['disable_gitlab_config_source'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + ## Backup GitLab Pages are part of the [regular backup](../../raketasks/backup_restore.md), so there is no separate backup to configure. -- GitLab From c22a0d17ed2fc8ee34608a74e0d16e08cb081c79 Mon Sep 17 00:00:00 2001 From: Jaime Martinez Date: Fri, 17 Apr 2020 10:52:39 +1000 Subject: [PATCH 2/4] Consolidate Pages admin guide Update section on running pages on a separate server, and consolidate steps with access control. Apply suggestions from review --- .../update-gitlab-pages-admin-doc.yml | 5 - doc/administration/pages/index.md | 152 +++++++++--------- 2 files changed, 72 insertions(+), 85 deletions(-) delete mode 100644 changelogs/unreleased/update-gitlab-pages-admin-doc.yml diff --git a/changelogs/unreleased/update-gitlab-pages-admin-doc.yml b/changelogs/unreleased/update-gitlab-pages-admin-doc.yml deleted file mode 100644 index 3e94bef8ca098d..00000000000000 --- a/changelogs/unreleased/update-gitlab-pages-admin-doc.yml +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Update documentation for GitLab Pages administration -merge_request: 29103 -author: -type: other diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index ad05f3a5fd103c..00fc651726d54f 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -455,9 +455,37 @@ You can run the GitLab Pages daemon on a separate server in order to decrease th To configure GitLab Pages on a separate server: + DANGER: **Danger:** + The `gitlab-secrets.json` file contains secrets that control database encryption. + Do not edit or replace this file on the **GitLab server** or you might + experience permanent data loss. Make a backup copy of this file before proceeding, + as explained in the following steps. + +1. On the **GitLab server**, to enable Pages, add the following to `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['enable'] = true + ``` + +1. Optionally, to enable access control, add the following to `/etc/gitlab/gitlab.rb` : + + ```ruby + gitlab_pages['access_control'] = true + ``` + +1. [Reconfigure the **GitLab server**](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the + changes to take effect. The `gitlab-secrets.json` file is now updated with the + new configuration. + +1. Create a backup of the secrets file on the **GitLab server**: + + ```shell + cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak + ``` + 1. Set up a new server. This will become the **Pages server**. -1. Create an NFS share on the new server and configure this share to +1. Create an [NFS share](../high_availability/nfs_host_client_setup.md) on the new server and configure this share to allow access from your main **GitLab server**. For this example, we use the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` as the shared folder on the new server and we will mount it to `/mnt/pages` @@ -481,6 +509,15 @@ To configure GitLab Pages on a separate server: gitlab_rails['auto_migrate'] = false ``` +1. Create a backup of the secrets file on the **Pages server**: + + ```shell + cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak + ``` + +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the **GitLab server** + to the **Pages server**. + 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. On the **GitLab server**, make the following changes to `/etc/gitlab/gitlab.rb`: @@ -500,94 +537,34 @@ configuring a load balancer to work at the IP level, and so on. If you wish to set up GitLab Pages on multiple servers, perform the above procedure for each Pages server. -### Sync secrets with GitLab server when running GitLab Pages on a seprate server - -If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), -and you want to enable [access-control](#access-control) or use -[GitLab Pages API-based configuration](#gitlab-pages-api-based-configuration), -then you must use the following procedure to sync secrets between your instances: - - DANGER: **Danger:** - The `gitlab-secrets.json` file contains secrets that control database encryption. - Do not edit or replace this file on the **GitLab server** or you might - experience permanent data loss. Make a backup copy of this file before proceeding, - as explained in the following steps. - -1. Create a backup of the secrets file on the **GitLab server**: - - ```shell - cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak - ``` - -1. Create a backup of the secrets file on the **Pages server**: - - ```shell - cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak - ``` - -1. Open the `/etc/gitlab/gitlab-secrets.json` file on the **GitLab server** - and copy the value of the `gitlab_pages` section to the - `/etc/gitlab/gitlab-secrets.json` file on the **Pages server** - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. - -### Access control when running GitLab Pages on a separate server - -If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), -then you must use the following procedure to configure [access control](#access-control): - -1. On the **GitLab server**, add the following to `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['enable'] = true - gitlab_pages['access_control'] = true - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. The `gitlab-secrets.json` file is now updated with the - new configuration. - -1. [Sync secrets with GitLab server when running GitLab Pages on a seprate server](#sync-secrets-with-gitlab-server-when-running-gitlab-pages-on-a-seprate-server) - -1. Disable Pages on the **GitLab server** by setting the following in - `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['enable'] = false - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +### GitLab Pages API-based configuration -1. On your **Pages server**, add the following to `/etc/gitlab/gitlab.rb`: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/282) in GitLab 13.0. - ```ruby - gitlab_pages['gitlab_server'] = "https://" - gitlab_pages['access_control'] = true - ``` +GitLab Pages uses an API-based configuration. This replaces disk source configuration, which +was used prior to GitLab 13.0. -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +If you are using disk source configuration, in most cases GitLab Pages will automatically +switch to the API-based configuration and use disk source configuration in case of errors. -### GitLab Pages API-based configuration +NOTE: **NOTE** +If you are [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +you will need to have copied the `/etc/gitlab/gitlab-secrets.json` file +from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.0. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/282) in GitLab 12.10. +Disk source configuration is available until the end of 2021. You should switch to the +API-based configuration as soon as possible. -GitLab Pages new API-based configuration is now available in 13.0 and will replace the -disk source configuration. You still can use the old configuration for next year, -although we don't recommend it and new features will not be supported. In many cases, -GitLab Pages will automatically switch to the API-based configuration without any action. -If you host GitLab Pages on a separate server, see the -[how to use API-Based configuration](#how-to-use-api-based-configuration) section. -Should you encounter an issue with the new configuration, you can -[disable it](#disable-api-based-configuration) and report an issue. - -#### How to use API-based configuration - -If you are [running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), -you must [Sync secrets with GitLab server when running GitLab Pages on a seprate server](#sync-secrets-with-gitlab-server-when-running-gitlab-pages-on-a-seprate-server). +If you encounter an issue, you can +[disable the API-based configuration](#disable-api-based-configuration) and report an issue. #### Disable API-based configuration -If you run into some problems with API configuration source, you can disable it by following these steps: +CAUTION: **Warning:** +The `disable_gitlab_config_source` configuration flag will be removed in 14.0. + +If you have problems with API-based source configuration, +you can disable it by following these steps: 1. On your **Pages server**, add the following to `/etc/gitlab/gitlab.rb`: @@ -650,3 +627,18 @@ The fix is to correct the source file permissions and restart Pages: sudo chmod 644 /opt/gitlab/embedded/ssl/certs/cacert.pem sudo gitlab-ctl restart gitlab-pages ``` + +### `GitLab API is not configured` in pages logs + +If you are [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +and you see the following warning message + +```plaintext +WARN[0000] GitLab API is not configured error="failed to connect to internal pages API: HTTP status: 401" +``` + +you will need to have copied the `/etc/gitlab/gitlab-secrets.json` file +from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.0. + +you need to sync `gitlab-pages.json` file from your main GitLab server to +GitLab Pages server. -- GitLab From 2ee1e393b69bfa8062a8586d88409451fbcfefff Mon Sep 17 00:00:00 2001 From: Jaime Martinez Date: Tue, 21 Apr 2020 11:12:52 +1000 Subject: [PATCH 3/4] Apply suggestions from review --- doc/administration/pages/index.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 00fc651726d54f..e30b2146bebc69 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -467,7 +467,7 @@ To configure GitLab Pages on a separate server: gitlab_pages['enable'] = true ``` -1. Optionally, to enable access control, add the following to `/etc/gitlab/gitlab.rb` : +1. Optionally, to enable access control, add the following to `/etc/gitlab/gitlab.rb`: ```ruby gitlab_pages['access_control'] = true @@ -545,7 +545,8 @@ GitLab Pages uses an API-based configuration. This replaces disk source configur was used prior to GitLab 13.0. If you are using disk source configuration, in most cases GitLab Pages will automatically -switch to the API-based configuration and use disk source configuration in case of errors. +switch to the API-based configuration after upgrading to GitLab 13.0; +however, it will use disk source configuration in case of errors. NOTE: **NOTE** If you are [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), @@ -638,7 +639,7 @@ WARN[0000] GitLab API is not configured error="failed to connec ``` you will need to have copied the `/etc/gitlab/gitlab-secrets.json` file -from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.0. - -you need to sync `gitlab-pages.json` file from your main GitLab server to -GitLab Pages server. +from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.0, +as described in the +[Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server) +section. -- GitLab From 0e0a97896b8d921f0d950f519ead05b8759c12d2 Mon Sep 17 00:00:00 2001 From: Jaime Martinez Date: Mon, 4 May 2020 11:59:20 +1000 Subject: [PATCH 4/4] Rename flag to disable-gitlab-api-config-source --- doc/administration/pages/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index e30b2146bebc69..fcccaa4facb0ea 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -562,7 +562,7 @@ If you encounter an issue, you can #### Disable API-based configuration CAUTION: **Warning:** -The `disable_gitlab_config_source` configuration flag will be removed in 14.0. +The `disable_gitlab_api_config_source` configuration flag will be removed in 14.0. If you have problems with API-based source configuration, you can disable it by following these steps: @@ -570,7 +570,7 @@ you can disable it by following these steps: 1. On your **Pages server**, add the following to `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['disable_gitlab_config_source'] = true + gitlab_pages['disable_gitlab_api_config_source'] = true ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -- GitLab