Commit 6478b448 authored by Amy Qualls's avatar Amy Qualls Committed by Marcel Amirault

Tidy and polish the Pseudonymizer page

parent 06924b81
......@@ -557,7 +557,7 @@ supported by consolidated configuration form, refer to the following guides:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| **{dotted-circle}** No |
| [Packages](packages/index.md#using-object-storage) (optional feature) | **{check-circle}** Yes |
| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM SELF)** | **{check-circle}** Yes |
| [Pseudonymizer](pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | **{dotted-circle}** No |
| [Pseudonymizer](pseudonymizer.md) (optional feature) | **{dotted-circle}** No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | **{dotted-circle}** No |
| [Terraform state files](terraform_state.md#using-object-storage) | **{check-circle}** Yes |
| [GitLab Pages content](pages/index.md#using-object-storage) | **{check-circle}** Yes |
......
......@@ -6,33 +6,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Pseudonymizer **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in GitLab 11.1.
Your GitLab database contains sensitive information. To protect sensitive information
when you run analytics on your database, you can use the Pseudonymizer service, which:
As the GitLab database hosts sensitive information, using it unfiltered for analytics
implies high security requirements. To help alleviate this constraint, the Pseudonymizer
service is used to export GitLab data in a pseudonymized way.
1. Uses `HMAC(SHA256)` to mutate fields containing sensitive information.
1. Preserves references (referential integrity) between fields.
1. Exports your GitLab data, scrubbed of sensitive material.
WARNING:
This process is not impervious. If the source data is available, it's possible for
a user to correlate data to the pseudonymized version.
If the source data is available, users can compare and correlate the scrubbed data
with the original.
The Pseudonymizer currently uses `HMAC(SHA256)` to mutate fields that shouldn't
be textually exported. This ensures that:
To generate a pseudonymized data set:
- the end-user of the data source cannot infer/revert the pseudonymized fields
- the referential integrity is maintained
1. [Configure Pseudonymizer](#configure-pseudonymizer) fields and output location.
1. [Enable Pseudonymizer data collection](#enable-pseudonymizer-data-collection).
1. Optional. [Generate a data set manually](#generate-data-set-manually).
## Configuration
## Configure Pseudonymizer
To configure the Pseudonymizer, you need to:
To use the Pseudonymizer, configure both the fields you want to anonymize, and the location to
store the scrubbed data:
- Provide a manifest file that describes which fields should be included or
pseudonymized ([example `manifest.yml` file](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/pseudonymizer.yml)).
A default manifest is provided with the GitLab installation, using a relative file path that resolves from the Rails root.
Alternatively, you can use an absolute file path.
- Use an object storage and specify the connection parameters in the `pseudonymizer.upload.connection` configuration option.
[Read more about using object storage with GitLab](object_storage.md).
1. **Create a manifest file**: This file describes the fields to include or pseudonymize.
- **Default manifest** - GitLab provides a default manifest in your GitLab installation
([example `manifest.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/pseudonymizer.yml)).
To use the example manifest file, use the `config/pseudonymizer.yml` relative path
when you configure connection parameters.
- **Custom manifest** - To use a custom manifest file, use the absolute path to
the file when you configure the connection parameters.
1. **Configure connection parameters**: In the configuration method appropriate for
your version of GitLab, specify the [object storage](object_storage.md)
connection parameters (`pseudonymizer.upload.connection`).
**For Omnibus installations:**
......@@ -50,7 +55,7 @@ To configure the Pseudonymizer, you need to:
}
```
If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
If you are using AWS IAM profiles, omit the AWS access key and secret access key/value pairs.
```ruby
gitlab_rails['pseudonymizer_upload_connection'] = {
......@@ -85,24 +90,34 @@ To configure the Pseudonymizer, you need to:
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source)
for the changes to take effect.
## Usage
## Enable Pseudonymizer data collection
To enable data collection:
1. On the top bar, select **Menu > Admin**.
1. On the left sidebar, select **Settings > Metrics and Profiling**, then expand
**Pseudonymizer data collection**.
1. Select **Enable Pseudonymizer data collection**.
1. Select **Save changes**.
You can optionally run the Pseudonymizer using the following environment variables:
## Generate data set manually
- `PSEUDONYMIZER_OUTPUT_DIR` - where to store the output CSV files (defaults to `/tmp`)
- `PSEUDONYMIZER_BATCH` - the batch size when querying the DB (defaults to `100000`)
You can also run the Pseudonymizer manually:
```shell
## Omnibus
sudo gitlab-rake gitlab:db:pseudonymizer
1. Set these environment variables:
- `PSEUDONYMIZER_OUTPUT_DIR` - Where to store the output CSV files. Defaults to `/tmp`.
These commands produce CSV files that can be quite large. Make sure the directory
can store a file at least 10% of the size of your database.
- `PSEUDONYMIZER_BATCH` - The batch size when querying the database. Defaults to `100000`.
1. Run the command appropriate for your application:
- **Omnibus GitLab**:
`sudo gitlab-rake gitlab:db:pseudonymizer`
- **Installations from source**:
`sudo -u git -H bundle exec rake gitlab:db:pseudonymizer RAILS_ENV=production`
## Source
sudo -u git -H bundle exec rake gitlab:db:pseudonymizer RAILS_ENV=production
```
After you run the command, upload the output CSV files to your configured object
storage. After the upload completes, delete the output file from the local disk.
This produces some CSV files that might be very large, so make sure the
`PSEUDONYMIZER_OUTPUT_DIR` has sufficient space. As a rule of thumb, at least
10% of the database size is recommended.
## Related topics
After the pseudonymizer has run, the output CSV files should be uploaded to the
configured object storage and deleted from the local disk.
- [Using object storage with GitLab](object_storage.md).
......@@ -2085,7 +2085,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
......@@ -2091,7 +2091,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
......@@ -352,7 +352,7 @@ Omnibus:
```ruby
## Enable Redis
redis['enable'] = true
# Avoid running unnecessary services on the Redis server
gitaly['enable'] = false
postgresql['enable'] = false
......@@ -922,7 +922,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
......@@ -2039,7 +2039,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
......@@ -2105,7 +2105,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
......@@ -2033,7 +2033,7 @@ on what features you intend to use:
| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No |
| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes |
| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes |
| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE SELF)** | No |
| [Pseudonymizer](../pseudonymizer.md) (optional feature) | No |
| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No |
| [Terraform state files](../terraform_state.md#using-object-storage) | Yes |
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment