diff options
Diffstat (limited to 'doc/administration/packages')
-rw-r--r-- | doc/administration/packages/container_registry.md | 52 | ||||
-rw-r--r-- | doc/administration/packages/dependency_proxy.md | 27 | ||||
-rw-r--r-- | doc/administration/packages/index.md | 22 |
3 files changed, 63 insertions, 38 deletions
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 541bd99084c..633129e98bd 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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/#designated-technical-writers +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 Container Registry administration @@ -93,7 +93,7 @@ auth: rootcertbundle: /root/certs/certbundle ``` -CAUTION: **Caution:** +WARNING: If `auth` is not set up, users can pull Docker images without authentication. ## Container Registry domain configuration @@ -101,7 +101,7 @@ If `auth` is not set up, users can pull Docker images without authentication. There are two ways you can configure the Registry's external domain. Either: - [Use the existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain). - The Registry listens on a port and reuses GitLab's TLS certificate. + The Registry listens on a port and reuses the TLS certificate from GitLab. - [Use a completely separate domain](#configure-container-registry-under-its-own-domain) with a new TLS certificate for that domain. @@ -374,7 +374,7 @@ driver for the Container Registry. [Read more about using object storage with GitLab](../object_storage.md). -CAUTION: **Warning:** +WARNING: GitLab does not back up Docker images that are not stored on the file system. Enable backups with your object storage provider if desired. @@ -468,7 +468,7 @@ you can pull from the Container Registry, but you cannot push. sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket ``` - TIP: **Tip:** + NOTE: If you have a lot of data, you may be able to improve performance by [running parallel sync operations](https://aws.amazon.com/premiumsupport/knowledge-center/s3-improve-transfer-sync-command/). @@ -485,7 +485,7 @@ you can pull from the Container Registry, but you cannot push. [`--dryrun`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) flag and run the command. - DANGER: **Warning:** + WARNING: The [`--delete`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) flag deletes files that exist in the destination but not in the source. If you swap the source and destination, all data in the Registry is deleted. @@ -612,8 +612,8 @@ You can use GitLab as an auth endpoint with an external container registry. gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" ``` - `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab's - Container Registry features and authentication endpoint. GitLab's bundled + `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab + Container Registry features and authentication endpoint. The GitLab bundled Container Registry service does not start, even with this enabled. 1. A certificate-key pair is required for GitLab and the external container @@ -820,7 +820,7 @@ If you did not change the default location of the configuration file, run: sudo gitlab-ctl registry-garbage-collect ``` -This command will take some time to complete, depending on the amount of +This command takes some time to complete, depending on the amount of layers you have stored. If you changed the location of the Container Registry `config.yml`: @@ -837,7 +837,7 @@ understand the implications. > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) in Omnibus GitLab 11.10. -DANGER: **Warning:** +WARNING: This is a destructive operation. The GitLab Container Registry follows the same default workflow as Docker Distribution: @@ -867,7 +867,7 @@ You can perform garbage collection without stopping the Container Registry by pu it in read-only mode and by not using the built-in command. On large instances this could require Container Registry to be in read-only mode for a while. During this time, -you will be able to pull from the Container Registry, but you will not be able to +you are able to pull from the Container Registry, but you are not able to push. By default, the [registry storage path](#configure-storage-for-the-container-registry) @@ -896,7 +896,7 @@ To enable the read-only mode: sudo gitlab-ctl reconfigure ``` - This will set the Container Registry into the read only mode. + This command sets the Container Registry into the read only mode. 1. Next, trigger one of the garbage collect commands: @@ -908,7 +908,7 @@ To enable the read-only mode: sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml ``` - This will start the garbage collection, which might take some time to complete. + This command starts the garbage collection, which might take some time to complete. 1. Once done, in `/etc/gitlab/gitlab.rb` change it back to read-write mode: @@ -935,7 +935,7 @@ To enable the read-only mode: Ideally, you want to run the garbage collection of the registry regularly on a weekly basis at a time when the registry is not being in-use. -The simplest way is to add a new crontab job that it will run periodically +The simplest way is to add a new crontab job that it runs periodically once a week. Create a file under `/etc/cron.d/registry-garbage-collect`: @@ -1137,6 +1137,12 @@ and a simple solution would be to enable relative URLs in the Registry. ### Enable the Registry debug server +You can use the Container Registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. + +WARNING: +Sensitive information may be available from the debug endpoint. +Access to the debug endpoint must be locked down in a production environment. + The optional debug server can be enabled by setting the registry debug address in your `gitlab.rb` configuration. @@ -1149,13 +1155,13 @@ After adding the setting, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitl Use curl to request debug output from the debug server: ```shell -curl localhost:5001/debug/health -curl localhost:5001/debug/vars +curl "localhost:5001/debug/health" +curl "localhost:5001/debug/vars" ``` ### Advanced Troubleshooting -We will use a concrete example in the past to illustrate how to +We use a concrete example to illustrate how to diagnose a problem with the S3 setup. #### Unexpected 403 error during push @@ -1227,14 +1233,14 @@ To verify that the certificates are properly installed, run: mitmproxy --port 9000 ``` -This will run mitmproxy on port `9000`. In another window, run: +This command runs mitmproxy on port `9000`. In another window, run: ```shell -curl --proxy http://localhost:9000 https://httpbin.org/status/200 +curl --proxy "http://localhost:9000" "https://httpbin.org/status/200" ``` -If everything is set up correctly, you will see information on the mitmproxy window and -no errors from the curl commands. +If everything is set up correctly, information is displayed on the mitmproxy window and +no errors are generated by the curl commands. #### Running the Docker daemon with a proxy @@ -1248,7 +1254,7 @@ export HTTPS_PROXY="https://localhost:9000" docker daemon --debug ``` -This will launch the Docker daemon and proxy all connections through mitmproxy. +This command launches the Docker daemon and proxies all connections through mitmproxy. #### Running the Docker client @@ -1273,4 +1279,4 @@ The above image shows: What does this mean? This strongly suggests that the S3 user does not have the right [permissions to perform a HEAD request](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html). The solution: check the [IAM permissions again](https://docs.docker.com/registry/storage-drivers/s3/). -Once the right permissions were set, the error will go away. +Once the right permissions were set, the error goes away. diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index 56b39658dc2..9e315722c24 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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/#designated-technical-writers +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 Dependency Proxy administration @@ -16,7 +16,7 @@ dependency proxies, see the [user guide](../../user/packages/dependency_proxy/in ## Enabling the Dependency Proxy feature -NOTE: **Note:** +NOTE: Dependency proxy requires the Puma web server to be enabled. To enable the dependency proxy feature: @@ -34,7 +34,7 @@ To enable the dependency proxy feature: **Installations from source** -1. After the installation is complete, you will have to configure the `dependency_proxy` +1. After the installation is complete, configure the `dependency_proxy` section in `config/gitlab.yml`. Set to `true` to enable it: ```yaml @@ -88,7 +88,7 @@ store the blobs of the dependency proxy. [Read more about using object storage with GitLab](../object_storage.md). -NOTE: **Note:** +NOTE: In GitLab 13.2 and later, we recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). This section describes the earlier configuration format. @@ -161,3 +161,22 @@ This section describes the earlier configuration format. ``` 1. [Restart GitLab](../restart_gitlab.md#installations-from-source "How to restart GitLab") for the changes to take effect. + +## Disabling Authentication + +Authentication was introduced in 13.7 as part of [enabling private groups to use the +Dependency Proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/11582). If you +previously used the Dependency Proxy without authentication and need to disable +this feature while you update your workflow to [authenticate with the Dependency +Proxy](../../user/packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy), +the following commands can be issued in a Rails console: + +```ruby +# Disable the authentication +Feature.disable(:dependency_proxy_for_private_groups) + +# Re-enable the authentication +Feature.enable(:dependency_proxy_for_private_groups) +``` + +The ability to disable this feature will be [removed in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/276777). diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 4af0de864ca..0f391371a6a 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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/#designated-technical-writers +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 Package Registry administration @@ -32,8 +32,8 @@ The Package Registry supports the following formats: ## Accepting contributions -The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) will -guide you through the process. +The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) +guides you through the process. | Format | Status | | ------ | ------ | @@ -53,10 +53,10 @@ guide you through the process. ## Enabling the Packages feature -NOTE: **Note:** +NOTE: After the Packages feature is enabled, the repositories are available -for all new projects by default. To enable it for existing projects, users will -have to explicitly do so in the project's settings. +for all new projects by default. To enable it for existing projects, users +explicitly do so in the project's settings. To enable the Packages feature: @@ -72,7 +72,7 @@ To enable the Packages feature: **Installations from source** -1. After the installation is complete, you will have to configure the `packages` +1. After the installation is complete, you configure the `packages` section in `config/gitlab.yml`. Set to `true` to enable it: ```yaml @@ -84,7 +84,7 @@ To enable the Packages feature: **Helm Chart installations** -1. After the installation is complete, you will have to configure the `packages` +1. After the installation is complete, you configure the `packages` section in `global.appConfig.packages`. Set to `true` to enable it: ```yaml @@ -136,8 +136,8 @@ store packages. [Read more about using object storage with GitLab](../object_storage.md). -NOTE: **Note:** -We recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original config format. +NOTE: +We recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format. **Omnibus GitLab installations** @@ -214,7 +214,7 @@ We recommend using the [consolidated object storage settings](../object_storage. After [configuring the object storage](#using-object-storage), you may use the following task to migrate existing packages from the local storage to the remote one. -The processing will be done in a background worker and requires **no downtime**. +The processing is done in a background worker and requires **no downtime**. For Omnibus GitLab: |