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:
- 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_DIRvalue, and a sentence naming what rides it. - 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 singlecve_enrichmentdirectory 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. - 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.
- 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.
- The prune hazard in the example crontabs. Both use
gsutil rsyncwith-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, wherersync --deleteis required. - 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.rbandee/app/services/package_metadata/sync_service.rb, and re-read on19-3-stable-eeso 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 returnsv2/cve_enrichment/0/000000000.ndjson. That asymmetry is the whole reason step 5 exists. - The Helm values shape was rendered three times with
helm templateagainst 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 issues
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
- Optional. Consider taking the GitLab Technical Writing Fundamentals course.
- Follow the:
- If you're adding a new page, add the product availability details under the H1 topic title.
- Not applicable: no new page. Both files already exist and their existing details blocks are untouched.
- If you are a GitLab team member, request a review based on:
- The documentation page's metadata.
- The associated Technical Writer.
- Left unticked deliberately: the reviewers are identified in Reviewer routing above, and the request is the next action rather than something already done.
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 likeDefault behavior when you close an issue. - The headings (other than the page title) should be active. Instead of
Configuring GDK, say something likeConfigure 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.
- The headings should be something you'd do a Google search for. Instead of
- 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.