Document the offline CVE enrichment export and Helm chart mount

What does this MR do?

Fills five gaps in Enabling the Package Metadata Database on the offline install guide, and gives the offline security scanning page its first pointer to that procedure. The change is purely additive: 120 added lines, no line removed or reworded.

On doc/topics/offline/quick_start_guide.md:

  1. The CVE enrichment export. The bucket list names the license and advisory buckets only. An operator who follows the page ends up with dependency scanning and license data and no vulnerability risk assessment data, because CVE enrichment is a third export with its own bucket and its own vendor directory. Adds the bucket, the DATA_DIR value, and a sentence naming what rides it.
  2. The one-level move that export needs. The license and advisory buckets hold one directory per package registry under v2/. CVE enrichment has no package registry, and its bucket holds a single cve_enrichment directory in that position instead, so a copy made as it is leaves the files one level below where GitLab reads them. GitLab then imports nothing and logs nothing. Adds a step, and a matching line in Confirm correct file structure.
  3. Connector precedence. The page states precedence only for malware advisories, and only in troubleshooting. For licenses, advisories, and CVE enrichment the vendor directory wins whenever it is present, with no fallback, so a directory holding stale data serves stale data and reports nothing. Adds a note where an operator reads it, before the download procedures.
  4. Before the first load. The page links the package registry metadata setting only from troubleshooting, which is after the load it should have shaped. Adds a short subsection: scope the enabled types first, the import rate is set by a throttle in the sync job rather than by the instance, and an unscoped first load can take on the order of a day.
  5. The prune hazard in the example crontabs. Both use gsutil rsync with -d. GitLab records the last file it imported and resumes after it; if a prune removes the sequence directory that record points to, GitLab imports the whole data type again from the start. Adds a warning, with the shared-directory rule, scoped so it does not contradict the malware advisory procedure, where rsync --delete is required.
  6. Instances installed with the Helm chart. Every procedure on this page writes to the Rails directory of a Linux package installation. The page already says that a Kubernetes installation needs the files on a volume the Sidekiq pods read, and defers the mechanism to #561085. Adds the values shape that works today, plus the two mistakes that cost the most time.

On doc/user/application_security/offline_deployments/_index.md, a short section under Specific scanner instructions saying that dependency scanning and continuous vulnerability scanning also need the Package Metadata Database, that it is data rather than an analyzer image, and where the procedure is. The page currently has no path to it at all, so a reader following the offline scanning trail never arrives.

How the claims were checked

Every factual claim was traced to a source rather than written from memory. The load-bearing parts:

  • The precedence, glob depth, throttle, and checkpoint-replay behaviour were read from ee/app/models/package_metadata/sync_configuration.rb, ee/lib/gitlab/package_metadata/connector/offline.rb and ee/app/services/package_metadata/sync_service.rb, and re-read on 19-3-stable-ee so none of it is master-only.
  • The two bucket layouts were confirmed against the buckets themselves. The license bucket returns v2/cargo/1787591958/000000000.ndjson; the CVE enrichment bucket returns v2/cve_enrichment/0/000000000.ndjson. That asymmetry is the whole reason step 5 exists.
  • The Helm values shape was rendered three times with helm template against chart 10.3.1, showing the mount on three containers with the correct values, a valid Deployment with no mount and exit 0 when the keys sit at the wrong level, and a render error naming the template when they are typed as a YAML list. The silent case is the wrong nesting level, which is why the page warns about that one specifically.
  • No version, milestone, or history claim is made, so no {{< history >}} block is added or touched.
  • No measurement appears in the prose. The one duration is an order of magnitude, written as such, so it cannot go stale against hardware or export size.

Vale runs clean with the repository's own configuration (0 errors, and no new warnings against the unedited pages), and markdownlint-cli2 reports 0 issues.

Two things reviewers should know

A code change is in preparation for the enrichment path depth, so that the export can be copied as it is. This MR documents the behaviour of current releases, so step 5 stays as written; the paragraph will need a version note once that change lands.

Three other documentation MRs are open against this page right now (!253121 (merged), !252827, !251824), all on the license v3 layout and the malware advisory wording. This diff deletes nothing and touches different sections, so it should apply over any order of merges. The one place to watch is the Confirm correct file structure list, where !251824 edits two existing bullets and this MR appends after them.

Reviewer routing

The page frontmatter and the content owner disagree, so this needs more than one pair of eyes:

Page Frontmatter stage and group CODEOWNERS technical writer
doc/topics/offline/quick_start_guide.md GitLab Delivery, Operate @axil, @eread
doc/user/application_security/offline_deployments/_index.md Application Security Testing, Static Analysis @rsarangadharan

The Package Metadata Database is Composition Analysis content on a Delivery-owned page, so a groupcomposition analysis subject-matter review is worth having alongside the technical writer review. The labels follow the content owner rather than the frontmatter, matching what !253121 (merged) and !252827 already do on this page.

The Helm subsection is the part most likely to draw a scope question, because it documents a composition the chart does not model and #561085 is open about exactly that. It is self-contained: if Composition Analysis or the technical writer would rather Kubernetes content did not live on a Delivery-owned page, that one subsection can move to its own MR and everything else lands unchanged.

Related to #561085

Related to #577051 (partially addresses it: the issue covers both the Package Metadata Database and the GitLab advisory database, and asks about update cadence for each. This MR answers the offline half for the Package Metadata Database only, so the issue stays open for the rest.)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

AI-Generated Content Disclosure: This MR was prepared with assistance from Claude Code. The output has been reviewed for correctness, verified against source per the verification discipline above, and validated against the documentation style guide.

Merge request reports

Loading
Loading