Skip to content

[3007.x] [DOCS] Refresh gitfs/git_pillar/s3fs/file_roots docs#69566

Draft
dwoz wants to merge 1 commit into
saltstack:3007.xfrom
dwoz:dwoz/docs/gitfs-fileserver-3007
Draft

[3007.x] [DOCS] Refresh gitfs/git_pillar/s3fs/file_roots docs#69566
dwoz wants to merge 1 commit into
saltstack:3007.xfrom
dwoz:dwoz/docs/gitfs-fileserver-3007

Conversation

@dwoz

@dwoz dwoz commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Summary

Refresh of the gitfs / git_pillar / s3fs / file_roots docs to address five
long-standing documentation issues:

  • [DOCS] gitfs walkthrough references out of date dependencies #62260 gitfs walkthrough: drops EOL distro notes (Ubuntu 14, Debian
    Wheezy, RHEL/CentOS 7.3-era CFFI quirks) and pins the recommended
    dependency versions to what requirements/base.txt and the CI lockfiles
    already require (pygit2 >= 1.13.1 / >= 1.19.2 on py3.11+, GitPython
    >= 3.1.50). Salts internal GITPYTHON_MINVER / PYGIT2_MINVER floors
    are unchanged.
  • external git pillar docs ref incorrect #56127 git_pillar external pillar: enumerates the supported remote
    URL forms (https, ssh://, scp-style user@host:path, file://) and calls
    out the scp-style colon as the most common source of "Failed to resolve
    address" / "Unable to exchange encryption keys" errors at master start.
  • [DOCS] Adding gitlab config info in GIT FILESERVER BACKEND WALKTHROUGH #60809 GitLab support: new "GitLab" subsection in the Authentication
    section of the walkthrough covering deploy tokens, project access
    tokens, personal access tokens, and SSH deploy keys, plus the 401
    failure mode for expired or under-scoped tokens.
  • [DOCS] please document that s3fs may require setting regional s3 endpoint #60408 s3fs regional endpoint: new "Regional endpoints" section in
    the s3fs.py module docstring documenting s3.location,
    s3.service_url, s3.https_enable, s3.path_style, and s3.verify_ssl
    with the SigV4 redirect failure mode.
  • salt docs recommending file_roots change? #53746 file_roots location: new "Where should file_roots live?"
    section explaining the /srv/salt default. Updates the
    netconfig.managed and napalm_network docstring examples to use
    /srv/salt so the inline example matches the recommendation.

Test plan

  • sphinx-build -W --keep-going -b html clean (no new warnings)
  • sphinx-build -W --keep-going -b man clean
  • pre-commit run on all modified files
  • pytest tests/pytests/functional/fileserver/gitfs/test_documented_providers.py (7 passed)
  • pytest tests/pytests/unit/fileserver/test_s3fs_documented_options.py (6 passed) — 3006.x / 3007.x only

Closes #62260
Closes #56127
Closes #60809
Closes #60408
Closes #53746

* gitfs walkthrough: drop EOL Ubuntu 14/Debian Wheezy/CentOS 7.3 notes
  and pin pygit2>=1.13.1, GitPython>=3.1.50 (matches base.txt + CI
  lockfiles). Adds a GitLab subsection covering deploy tokens,
  project access tokens, PATs, and SSH deploy keys.
* git_pillar docstring: enumerate supported remote URL forms
  (https://, ssh://, scp-style user@host:path, file://). The scp-style
  colon is the most common source of 'Failed to resolve address'
  errors.
* s3fs docstring: document s3.location / s3.service_url /
  s3.https_enable / s3.path_style / s3.verify_ssl with a Regional
  endpoints section, citing the SigV4 redirect failure mode.
* file_roots.rst: new section explaining why /srv/salt is the
  default. Update netconfig/napalm_network examples to use /srv/salt
  instead of /etc/salt/states so the example matches the
  recommendation.
* New tests: tests/pytests/functional/fileserver/gitfs/
  test_documented_providers.py and
  tests/pytests/unit/fileserver/test_s3fs_documented_options.py
  pin the docs to the loader.

Closes saltstack#62260
Closes saltstack#56127
Closes saltstack#60809
Closes saltstack#60408
Closes saltstack#53746
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test:full Run the full test suite

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant