The documentation for ACS is lacking a whole workflow for syncing

From the documentation, it is not clear how ACS should be used (Alternate Content Sources — Pulp RPM Support 3.17.5 documentation, Alternate Content Sources — Pulp File 1.10.2 documentation).

The following workflow obviously does not work for pulp_file (similarly, for pulp_rpm):

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file remote create --name remoteForACS --policy on_demand --url
  "pulp_href": "/pulp/api/v3/remotes/file/file/382242e2-20c9-4ad0-8cfb-d4045413075a/",
  "pulp_created": "2022-06-12T19:52:15.996127Z",
  "name": "remoteForACS",
  "url": "",
  "ca_cert": null,
  "client_cert": null,
  "tls_validation": true,
  "proxy_url": null,
  "pulp_labels": {},
  "pulp_last_updated": "2022-06-12T19:52:15.996148Z",
  "download_concurrency": null,
  "max_retries": null,
  "policy": "on_demand",
  "total_timeout": null,
  "connect_timeout": null,
  "sock_connect_timeout": null,
  "sock_read_timeout": null,
  "headers": null,
  "rate_limit": null

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file acs create --name fileAcs --remote remoteForACS --path "file/PULP_MANIFEST" --path "file2/PULP_MANIFEST"
  "pulp_href": "/pulp/api/v3/acs/file/file/25dfb2e1-6530-47c7-897f-b0d94ea44bfc/",
  "pulp_created": "2022-06-12T19:52:20.709004Z",
  "name": "fileAcs",
  "last_refreshed": null,
  "paths": [
  "remote": "/pulp/api/v3/remotes/file/file/382242e2-20c9-4ad0-8cfb-d4045413075a/"

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file acs refresh --name fileAcs
Started background task group /pulp/api/v3/task-groups/9486534f-a9a6-4bfb-ac4f-e7c64b5e78d0/
Waiting for task /pulp/api/v3/tasks/625ee9ee-d4c3-4700-a3dd-1ff720e85769/
Waiting for task /pulp/api/v3/tasks/6b18fe93-5433-4335-9a03-06ec59f6beff/
(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file repository create --name repoacs
  "pulp_href": "/pulp/api/v3/repositories/file/file/6c97fdee-2645-4b88-8957-876d72d12535/",
  "pulp_created": "2022-06-12T19:52:49.368870Z",
  "versions_href": "/pulp/api/v3/repositories/file/file/6c97fdee-2645-4b88-8957-876d72d12535/versions/",
  "pulp_labels": {},
  "latest_version_href": "/pulp/api/v3/repositories/file/file/6c97fdee-2645-4b88-8957-876d72d12535/versions/0/",
  "name": "repoacs",
  "description": null,
  "retain_repo_versions": null,
  "remote": null,
  "autopublish": false,
  "manifest": "PULP_MANIFEST"

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file repository sync --name repoacs --remote remoteForACS
Started background task /pulp/api/v3/tasks/d369ed67-d4cb-4e43-ad1b-bb35a6f9a50c/
.Error: Task /pulp/api/v3/tasks/d369ed67-d4cb-4e43-ad1b-bb35a6f9a50c/ failed: 'Error: manifest line:1: must be: <relative_path>,<digest>,<size>'

The statement " Alternate Content Sources have a global scope so if any content is found in ACS it will be used in all future syncs." should be explained in detail.

As a regular user, I would like to see a complete workflow including syncing.

The documentation is lacking and I can see where it’s confusing. I agree that it needs to be updated.

To give an example use case, imagine you have a remote repo that has a slow/unreliable connection. So slow/unreliable in fact that you can’t access its content (we’ll use the repo at to represent this). But maybe you have some local content you could fetch from. In our example, we’ll use to represent this. Here’s how you’d use ACS to sync this repo:

# set up the ACS and its remote artifacts
pulp rpm remote create --name rpm_acs_remote --policy on_demand --url
pulp rpm acs create --name rpm_acs --remote rpm_acs_remote
pulp rpm acs refresh --name rpm_acs

# now set up your remote and repo
pulp rpm remote create --name rpm_remote --policy on_demand --url
pulp rpm repository create --name rpm_repo --remote rpm_remote
pulp rpm repository sync --name rpm_repo

Now if you publish, distribute, and attempt to fetch packages from rpm_repo, it should work as it will pull content from rpm_acs_remote. In fact any time you pull content, Pulp will check if it’s in rpm_acs_remote first attempt to fetch it from there first.

Hope that helps.