此内容没有您所选择的语言版本。
Appendix D. API Reference in Red Hat Update Infrastructure
All material cited here was taken from the Pulp 2.18 repository.
D.1. Repository APIs
D.1.1. Creation, deletion, and configuration
D.1.1.1. Create a repository
This call creates a new repository in Pulp and accepts optional parameters for importer and distributor configuration. More detailed description of these parameters can be found in the documentation of APIs to associate an importer or a distributor to an existing repository. If these parameters are not passed, the call will create the repository only in Pulp. The real functionality of a repository is not defined until importers and distributors are added. Repository IDs must be unique across all repositories in the server.
Method: POST
Path: /pulp/api/v2/repositories/
Permission: create
Request Body Contents
- id
- (string) unique identifier for the repository
- display_name
- (string) (optional) user-friendly name for the repository
- description
- (string) (optional) user-friendly text describing the repository’s contents
- notes
- (object) (optional) key-value pairs to programmatically tag the repository
- importer_type_id
- (string) (optional) type id of importer being associated with the repository
- importer_config
-
(object) (optional) configuration the repository will use to drive the behavior of the importer. Note that
proxy_password
andbasic_auth_password
will be returned as*
for security purposes. - distributors
-
(array) (optional) array of objects containing values of
distributor_type_id
,repo_plugin_config
,auto_publish
, anddistributor_id
Response Codes
- 201
- The repository was successfully created.
- 400
- If one or more of the parameters is invalid
- 409
- If there is already a repository with the given ID
- 500
- If the importer or distributor raises an error during initialization
Return: database representation of the created repository
Sample Request:
{ "display_name": "Harness Repository: harness_repo_1", "id": "harness_repo_1", "importer_type_id": "harness_importer", "importer_config": { "num_units": "5", "write_files": "true" }, "distributors": [{ "distributor_id": "dist_1", "distributor_type_id": "harness_distributor", "distributor_config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "auto_publish": false }], }
Sample 201 Response Body:
{ "scratchpad": {}, "display_name": "Harness Repository: harness_repo_1", "description": null, "_ns": "repos", "notes": {}, "content_unit_counts": {}, "_id": { "$oid": "52280416e5e71041ad000066" }, "id": "harness_repo_1", "_href": "/pulp/api/v2/repositories/harness_repo_1/" }
D.1.1.2. Update a repository
Much like create repository is simply related to the repository metadata (as compared to the associated importers/distributors), the update repository call is centered around updating only that metadata.
Method: PUT
Path: /pulp/api/v2/repositories/<repo_id>/
Permission: update
Request Body Contents: The body of the request is a JSON document with three possible root elements
- delta
- (object) (optional) object containing keys with values that should be updated on the repository
- importer_config
- (object) (optional) object containing keys with values that should be updated on the repository’s importer config
- distributor_configs
- (object) (optional) object containing keys that are distributor IDs, and values that are objects containing plugin specific keys/value pairs
Response Codes
- 200
- If the update was executed and successful
- 202
- If the update was executed but additional tasks were created to update nested distributor configurations
- 400
- If one or more of the parameters is invalid
- 404
- If there is no repository with the give ID
Return: A Call Report containing the database representation of the repository (after changes made by the update) and any tasks spawned to apply the consumer bindings for the repository. See Bind a Consumer to a Repository for details on the bindings tasks that will be generated.
Sample Request:
{ "delta": { "display_name" : "Updated" }, "importer_config": { "demo_key": "demo_value" }, "distributor_configs": { "demo_distributor": { "demo_key": "demo_value" } } }
Sample result value: The result field of the Call Report contains the database representation of the repository.
{ ... "result": { "display_name": "zoo", "description": "foo", "_ns": "repos", "notes": { "_repo-type": "rpm-repo" }, "content_unit_counts": { "package_group": 2, "package_category": 1, "rpm": 32, "erratum": 4 }, "_id": { "$oid": "5328b2983738202945a3bb47" }, "id": "zoo", "_href": "/pulp/api/v2/repositories/zoo/" }, ... }
D.1.1.3. Associate an importer to a repository
This call configures an importer for a previously created Pulp repository. Each repository maintains its own configuration for the importer, which is used to dictate how the importer will function when it synchronizes content. The possible configuration values are contingent on the type of importer being added; each importer type will support a different set of values relevant to how it functions.
Only one importer may be associated with a repository at a given time. If a repository already has an associated importer, the previous association is removed. The removal is performed before the new importer is initialized, thus there is the potential that if the new importer initialization fails the repository is left without an importer.
Adding an importer performs the following validation steps before confirming the addition:
- The importer plugin is contacted and asked to validate the supplied configuration for the importer. If the importer indicates its configuration is invalid, the importer is not added to the repository.
-
The importer’s
importer_added
method is invoked to allow the importer to do any initialization required for that repository. If the plugin raises an exception during this call, the importer is not added to the repository. - The Pulp database is updated to store the importer’s configuration and the knowledge that the repository is associated with the importer.
The details of the added importer are returned from the call.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/importers/
Permission: create
Request Body Contents
- importer_type_id
- (string) - indicates the type of importer being associated with the repository; there must be an importer installed in the Pulp server with this ID
- importer_config
- (object) - configuration the repository will use to drive the behavior of the importer
Response Codes
- 202
- If the association was queued to be performed
- 400
- If one or more of the required parameters is missing, the importer type ID refers to a non-existent importer, or the importer indicates the supplied configuration is invalid
- 404
- If there is no repository with the given ID
- 500
- If the importer raises an error during initialization
Return: A Call Report containing the current state of the association task
Sample Request:
{ "importer_type_id": "harness_importer", "importer_config": { "num_units": "5", "write_files": "true" } }
Sample result value for the Task Report: The result field of the Task Report will contain the database representation of the importer (not the full repository details, just the importer).
{ "scratchpad": null, "_ns": "repo_importers", "importer_type_id": "harness_importer", "last_sync": null, "repo_id": "harness_repo_1", "_id": "bab0f9d5-dfd1-45ef-bd1d-fd7ea8077d75", "config": { "num_units": "5", "write_files": "true" }, "id": "harness_importer" }
Tags: The task created will have the following tags: pulp:action:update_importer
, pulp:repository:<repo_id>
, pulp:repository_importer:<importer_type_id
>
D.1.1.4. Associate a distributor with a repository
This call configures a distributor for a previously created Pulp repository. Each repository maintains its own configuration for the distributor, which is used to dictate how the distributor will function when it publishes content. The possible configuration values are contingent on the type of distributor being added; each distributor type supports a different set of values relevant to how it functions.
There is an optional distributor configuration parameter that is usable on all distributor plugin types called force_full
. If this parameter is set, every publish of the repo using this distributor is done from scratch. See Release Notes for more information.
Multiple distributors can be associated with a repository at a given time. There might be more than one distributor with the same type. The only restriction is that the distributor ID must be unique across all distributors for a given repository.
Adding a distributor performs the following validation steps before confirming the addition:
- If provided, the distributor ID is checked for uniqueness in the context of the repository. If not provided, a unique ID is generated.
- The distributor plugin is contacted and asked to validate the supplied configuration for the distributor. If the distributor indicates its configuration is invalid, the distributor is not added to the repository.
-
The distributor’s
distributor_added
method is invoked to allow the distributor to do any initialization required for that repository. If the plugin raises an exception during this call, the distributor is not added to the repository. - The Pulp database is updated to store the distributor’s configuration and the knowledge that the repository is associated with the distributor.
The details of the added distributor are returned from the call.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/distributors/
Permission: create
Request Body Contents
- distributor_type_id
- (string) Indicates the type of distributor being associated with the repository; there must be a distributor installed in the Pulp server with this ID.
- distributor_config
- (object) Plugin-specific configuration the repository uses to drive the behavior of the distributor
- distributor_id
- (string) (optional) If specified, this value refers to the distributor; if not specified, one is randomly assigned to the distributor.
- auto_publish
- (boolean) (optional) If true, this distributor automatically has its publish operation invoked after a successful repository sync. Defaults to false if unspecified.
Response Codes
- 201
- If the distributor was successfully added
- 400
- If one or more of the required parameters is missing, the distributor type ID refers to a non-existent distributor, or the distributor indicates the supplied configuration is invalid
- 404
- If there is no repository with the given ID
- 500
- If the distributor raises an error during initialization
Return: Database representation of the distributor (not the full repository details, just the distributor)
Sample Request:
{ "distributor_id": "dist_1", "distributor_type_id": "harness_distributor", "distributor_config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "auto_publish": false }
Sample 201 Response Body:
{ "scratchpad": null, "_ns": "repo_distributors", "last_publish": null, "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "cfdd6ab9-6dbe-4192-bde2-d00db768f268", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" }
D.1.1.5. Update an importer associated with a repository
Update the configuration for an importer that has already been associated with a repository.
Any importer configuration value that is not specified remains unchanged.
Note that the importer’s proxy_password
and basic_auth_password
fields return as *
if they are populated. This is done for security purposes.
Method: PUT
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/
Permission: update
Request Body Contents
- importer_config
- (object) Object containing keys with values that should be updated on the importer
Response Codes
- 202
- If the request was accepted by the server to update the importer when the repository is available
- 400
- If request body parameters are invalid
- 404
- If there is no repository or importer with the specified IDs
Return: A Call Report, which includes a spawned task that should be polled for a Task Report
Sample Request:
{ "importer_config": { "demo_key": "demo_value" } }
Sample result value for the Task Report: The result field of the Task Report contains the database representation of the importer. This does not include the full repository details.
[options="nowrap"] { "scratchpad": null, "_ns": "repo_importers", "importer_type_id": "demo_importer", "last_sync": "2013-10-03T14:08:35Z", "scheduled_syncs": [], "repo_id": "demo_repo", "_id": { "$oid": "524db282dd01fb194283e53f" }, "config": { "demo_key": "demo_value" }, "id": "demo_importer" }
Tags: The task created has the following tags: pulp:action:update_importer
, pulp:repository:<repo_id>
, pulp:repository_importer:<importer_id>
D.1.1.6. Disassociate an importer from a repository
Method: DELETE
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/
Permission: delete
Response Codes
- 202
- If the request was accepted by the server to disassociate when the repository is available
- 404
- If there is no repository or importer with the specified IDs
Return: A Call Report
Tags: The task created has the following tags: pulp:action:delete_importer
, pulp:repository:<repo_id>
, pulp:repository_importer:<importer_id>
D.1.1.7. Update a distributor associated with a repository
Update the configuration for a distributor associated with a repository. This performs the following actions:
- Updates the distributor on the server
- Rebinds any bound consumers
Any distributor configuration value that is not specified remains unchanged, and any value that is set to explicitly to None
will be removed from the config.
The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required to complete Step 2. Updating a distributor causes each binding associated with that repository to be updated as well. See Bind a Consumer to a Repository for details.
Method: PUT
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/
Permission: update
Request Body Contents
- distributor_config
- (object) (optional) Object containing plugin specific keys with values that will update the distributor config
- delta
-
(object) (optional) Object containing keys with values that will update the distributor object, currently only supports
auto_publish
Response Codes
- 202
- If the request was accepted by the server to update the distributor when the repository is available
- 404
- If there is no repository or distributor with the specified IDs
Return: A Call Report
Sample Request:
{ "distributor_config": { "demo_key": "demo_value" }, "delta": { "auto_publish": true } }
Tags: The task created to update the distributor have the following tags: pulp:action:update_distributor
, pulp:repository:<repo_id>
, pulp:repository_distributor:<distributor_id>
. Information about the binding tasks can be found at Bind a Consumer to a Repository.
D.1.1.8. Disassociate a distributor from a repository
Disassociating a distributor performs the following actions:
- Remove the association between the distributor and the repository.
- Unbind all bound consumers.
The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required complete step 2. The total number of spawned tasks depends on how many consumers are bound to the repository.
Method: DELETE
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/
Permission: delete
Response Codes
- 202
- If the request was accepted by the server to disassociate when the repository is available
- 404
- If there is no repository or distributor with the specified IDs
- 500
- If the server raises an error during disassociation
Return: A Call Report
Tags: The task created to delete the distributor has the following tags: pulp:action:remove_distributor
, pulp:repository:<repo_id>
, pulp:repository_distributor:<distributor_id>
D.1.1.9. Delete a repository
When a repository is deleted, it is removed from the database and its local working directory is deleted. The content within the repository is not deleted. Deleting content is handled through the orphaned unit process.
Deleting a repository is performed in the following major steps:
- Delete the repository.
- Unbind all bound consumers.
The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required to complete Step 2. The total number of spawned tasks depends on how many consumers are bound to the repository.
Method: DELETE
Path: /pulp/api/v2/repositories/<repo_id>/
Permission: delete
Response Codes
- 202
- If the request was accepted by the server to delete the repository
- 404
- If the requested repository does not exist
Return: A Call Report
Tags: The task created to delete the repository has the following tags: pulp:action:delete
,pulp:repository:<repo_id>
D.1.2. Retrieval
D.1.2.1. Retrieve a single repository
This call retrieves information on a single Pulp repository. The returned data includes general repository metadata, metadata describing any importers and distributors associated with it, and a count of how many content units have been stored locally for the repository.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/
Permission: read
Query Parameters
- details
- (boolean) (optional) Shortcut for including distributors, importers, and content unit counts
- importers
-
(boolean) (optional) Include the
importers
attribute on each repository - distributors
- (boolean) (optional) Include the “distributors” attribute on each repository
Response Codes
- 200
- If the repository exists
- 404
- If no repository exists with the given ID
Return: database representation of the matching repository
Sample 200 Response Body:
{ "display_name": "Harness Repository: harness_repo_1", "description": null, "distributors": [ { "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "addf9261-345e-4ce3-ad1e-436ba005287f", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" } ], "notes": {}, "scratchpad": {}, "content_unit_counts": {}, "last_unit_added": "2012-01-25T15:26:32Z", "last_unit_removed": "2012-01-25T15:26:32Z", "importers": [ { "scratchpad": 1, "_ns": "repo_importers", "importer_type_id": "harness_importer", "last_sync": "2012-01-25T15:26:32Z", "repo_id": "harness_repo_1", "sync_in_progress": false, "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e", "config": { "num_units": "5", "write_files": "true" }, "id": "harness_importer" } ], "id": "harness_repo_1", "total_repository_units": 5, "locally_stored_units": 3 }
D.1.2.2. Retrieve all repositories
This call returns information on all repositories in the Pulp server. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no repositories.
Method: GET
Path: /pulp/api/v2/repositories/
Permission: read
Query Parameters
- details
- (boolean) (optional) Shortcut for including both distributors and importers
- importers
- (boolean) (optional) Include the “importers” attribute on each repository
- distributors
- (boolean) (optional) Include the “distributors” attribute on each repository
Response Codes
- 200
- Containing the array of repositories
Return: The same format as retrieving a single repository, except the base of the return value is an array of them
Sample 200 Response Body:
[ { "display_name": "Harness Repository: harness_repo_1", "description": null, "last_unit_added": "2012-01-25T15:26:32Z", "last_unit_removed": null, "distributors": [ { "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "addf9261-345e-4ce3-ad1e-436ba005287f", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" } ], "notes": {}, "scratchpad": {}, "content_unit_counts": {}, "importers": [ { "scratchpad": 1, "_ns": "repo_importers", "importer_type_id": "harness_importer", "last_sync": "2012-01-25T15:26:32Z", "repo_id": "harness_repo_1", "sync_in_progress": false, "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e", "config": { "num_units": "5", "write_files": "true" }, "id": "harness_importer" } ], "id": "harness_repo_1" } ]
D.1.2.3. Advanced Search for Repositories
See Search API for more details on how to perform these searches.
This call returns information on repositories in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned when there are no repositories.
Method: POST
Path: /pulp/api/v2/repositories/search/
Permission: read
Request Body Contents
- details
- (boolean) (optional) Shortcut to include “importers” and “distributors”
- importers
- (boolean) (optional) Include the “importers” attribute on each repository
- distributors
- (boolean) (optional) Include the “distributors” attribute on each repository
Response Codes
- 200
- Containing the array of repositories
Return: The same format as retrieving a single repository, except the base of the return value is an array of them
Sample 200 Response Body:
[ { "display_name": "Harness Repository: harness_repo_1", "description": null, "distributors": [ { "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "addf9261-345e-4ce3-ad1e-436ba005287f", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" } ], "notes": {}, "scratchpad": {}, "content_unit_counts": {}, "last_unit_added": null, "last_unit_removed": null, "importers": [ { "scratchpad": 1, "_ns": "repo_importers", "importer_type_id": "harness_importer", "last_sync": "2012-01-25T15:26:32Z", "repo_id": "harness_repo_1", "sync_in_progress": false, "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e", "config": { "num_units": "5", "write_files": "true" }, "id": "harness_importer" } ], "id": "harness_repo_1" } ]
This call returns information on repositories in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no repositories.
This method is more limiting than the POST alternative because some filter expressions may not be serializable as query parameters.
Method: GET
Path: /pulp/api/v2/repositories/search/
Permission: read
Query Parameters
- details
- (boolean) (optional) Shortcut for including both distributors and importers
- importers
-
(boolean) (optional) Include the
importers
attribute on each repository - distributors
-
(boolean) - (optional) Include the
distributors
attribute on each repository
Query parameters should match the attributes of a Criteria object as defined in Search Criteria. The exception is the fields
parameter, which should be specified in singular form, for example: /v2/repositories/search/?field=id&field=display_name&limit=20’
.
Response Codes
- 200
- Vontaining the array of repositories
Return: The same format as retrieving a single repository, except the base of the return value is an array of them
Sample 200 Response Body:
[ { "display_name": "Harness Repository: harness_repo_1", "description": null, "distributors": [ { "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "addf9261-345e-4ce3-ad1e-436ba005287f", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" } ], "notes": {}, "scratchpad": {}, "content_unit_counts": {}, "last_unit_added": null, "last_unit_removed": null, "importers": [ { "scratchpad": 1, "_ns": "repo_importers", "importer_type_id": "harness_importer", "last_sync": "2012-01-25T15:26:32Z", "repo_id": "harness_repo_1", "sync_in_progress": false, "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e", "config": { "num_units": "5", "write_files": "true" }, "id": "harness_importer" } ], "id": "harness_repo_1" } ]
D.1.2.4. Retrieve importers associated with a repository
This call retrieves the importer (if any) associated with a repository. The array will be empty (no importer configured) or contain a single entry.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/importers/
Permission: read
Query Parameters: None
Response Codes
- 200
- Containing an array of importers
- 404
- If there is no repository with the given ID; this will not occur if the repository exists but has no associated importers.
Return: Database representation of the repository’s importer or an empty list
Sample 200 Response Body:
[ { "_href": "/pulp/api/v2/repositories/zoo/importers/yum_importer/", "_id": { "$oid": "563c82fa45ef48043f026c32" }, "_ns": "repo_importers", "config": { "feed": "http://example.com/repos/zoo/" }, "id": "yum_importer", "importer_type_id": "yum_importer", "last_sync": "2015-11-06T10:38:23Z", "repo_id": "zoo", "scratchpad": { "repomd_revision": 1331832478 } } ]
D.1.2.5. Retrieve an importer associated with a repository
This call retrieves the given importer (if any) associated with a repository.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/
Permission: read
Query Parameters: None
Response Codes
- 200
- Containing the details of the importer
- 404
- If there is either no repository or importer with a matching ID
Return: Database representation of the repository’s importer
Sample 200 Response Body:
{ "_href": "/pulp/api/v2/repositories/zoo/importers/yum_importer/", "_id": { "$oid": "563c82fa45ef48043f026c32" }, "_ns": "repo_importers", "config": { "feed": "http://example.com/repos/zoo/" }, "id": "yum_importer", "importer_type_id": "yum_importer", "last_sync": "2015-11-06T10:38:23Z", "repo_id": "zoo", "scratchpad": { "repomd_revision": 1331832478 } }
D.1.2.6. Retrieve distributors associated with a repository
This call retrieves all distributors associated with a repository. If the repository has no associated distributors, an empty array is returned.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/distributors/
Permission: read
Query Parameters: None
Response Codes
- 200
- Containing an array of distributors
- 404
- If there is no repository with the given ID; this will not occur if the repository exists but has no associated distributors
Return: Database representations of all distributors on the repository
Sample 200 Response Body:
[ { "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": "addf9261-345e-4ce3-ad1e-436ba005287f", "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" } ]
D.1.2.7. Retrieve a distributor associated with a repository
This call retrieves a single distributor associated with a repository.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/
Permission: read
Query Parameters: None
Response Code
- 200
- Containing the details of a distributors
- 404
- If there is either no repository or distributor with a matching ID.
Return: Database representation of the distributor
Sample 200 Response Body:
{ "scratchpad": 1, "_ns": "repo_distributors", "last_publish": "2012-01-25T15:26:32Z", "auto_publish": false, "distributor_type_id": "harness_distributor", "repo_id": "harness_repo_1", "publish_in_progress": false, "_id": {"$oid": "addf9261-345e-4ce3-ad1e-436ba005287f"}, "config": { "publish_dir": "/tmp/harness-publish", "write_files": "true" }, "id": "dist_1" }
D.1.2.8. Advanced search for distributors
See Search API for more details on how to perform these searches.
This call returns information on distributors in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no distributors.
Method: POST
Path: /pulp/api/v2/distributors/search/
Permission: read
Request Body Contents: None
Response Codes
- 200
- Containing the array of distributors
Return: A list of distributor objects
Sample 200 Response Body:
[ { "repo_id": "el7", "last_publish": "2015-04-28T18:19:01Z", "auto_publish": null, "scheduled_publishes": [], "distributor_type_id": "ostree_web_distributor", "scratchpad": null, "config": { "relative_path": "/opt/content/ostree/el7" }, "id": "ostree_web_distributor_name_cli" }, { "repo_id": "el6", "last_publish": "2015-5-28T18:18:01Z", "auto_publish": null, "scheduled_publishes": [], "distributor_type_id": "ostree_web_distributor", "scratchpad": null, "config": { "relative_path": "/opt/content/ostree/el6" }, "id": "ostree_web_distributor_name_cli" } ]
D.1.3. Synchronization
D.1.3.1. Sync a repository
This call syncs content into a repository from a feed source using the repository’s importer.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/actions/sync/
Permission: execute
Request Body Contents
- override_config
- (object) (optional) Importer configuration values that override the importer’s default configuration for this sync
Response Codes
- 202
- If the sync is set to be executed
- 404
- If repo does not exist
Return: A Call Report
Sample Request:
{ "override_config": {"verify_checksum": false, "verify_size": false}, }
Tags: The task created has the following tags: pulp:action:sync
, pulp:repository:<repo_id>
D.1.3.2. Download a Repository
This call downloads content into a repository that was deferred at sync time. This is useful for repositories with importers that are configured with download_policy=(background | on_demand)
. Content that has already been downloaded will not be downloaded again.
This API requires that the Alternate Download Policies features must be installed and configured to work. If it has not been configured, the task dispatched by this API does nothing.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/actions/download/
Permission: execute
Request Body Contents
- verify_all_units
- (boolean) (optional) Check all units in the repository for corrupted or missing files and download files as necessary rather than just downloading files that are known to be missing (defaults to false)
Response Codes
- 202
- If the download is set to be executed
- 404
- If the repository does not exist
Return: A Call Report
Sample Request:
{ "verify_all_units": false }
Tags: The task created will have the following tags: pulp:action:download_repo
, pulp:repository:<repo_id>
D.1.3.3. Scheduling a Sync
A repository can be synced automatically using an iso8601 interval. To create a scheduled sync, the interval, sync override config, and other schedule options must be set on the repository’s importer.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/
Permission: create
Request Body Contents
- schedule
- (string) The schedule as an iso8601 interval
- override_config
- (object) (optional) The overridden configuration for the importer to be used on the scheduled sync
failure_threshold (number) (optional) Consecutive failures allowed before this scheduled sync is disabled
- enabled
- (boolean) (optional) Whether the scheduled sync is initially enabled (defaults to true)
Response Codes
- 201
- If the schedule was successfully created
- 400
- If one or more of the parameters are invalid
- 404
- If there is no repository or importer with the specified IDs
Return: schedule report representing the current state of the scheduled call
Sample Request:
{ "override_config": {}, "schedule": "00:00:00Z/P1DT", "failure_threshold": 3, }
Sample 201 Response Body:
{ "next_run": "2014-01-27T21:41:50Z", "task": "pulp.server.tasks.repository.sync_with_auto_publish", "last_updated": 1390858910.292712, "first_run": "2014-01-27T21:41:50Z", "schedule": "PT1H", "args": [ "demo" ], "enabled": true, "last_run_at": null, "_id": "52e6d29edd01fb70bd0d9c37", "total_run_count": 0, "failure_threshold": 3, "kwargs": { "overrides": {} }, "resource": "pulp:importer:demo:puppet_importer", "remaining_runs": null, "consecutive_failures": 0, "_href": "/pulp/api/v2/repositories/demo/importers/puppet_importer/schedules/sync/52e6d29edd01fb70bd0d9c37/" }
D.1.3.4. Updating a scheduled sync
The same parameters used to create a scheduled sync may be updated at any point.
Method: PUT
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/
Permission: create
Request Body Contents
- schedule
- (string) (optional) New schedule as an iso8601 interval
- override_config
- (object) (optional) New overridden configuration for the importer to be used on the scheduled sync
failure_threshold (number) (optional) New consecutive failures allowed before this scheduled sync is disabled
- enabled
- (boolean) (optional) Whether the scheduled sync is enabled
Response Codes
- 200
- If the schedule was successfully updated
- 400
- If one or more of the parameters are invalid
- 404
- If there is no repository, importer or schedule with the specified IDs
Return: Schedule report representing the current state of the scheduled call (See sample response of Scheduling a Sync for details.)
D.1.3.5. Deleting a Scheduled Sync
Delete a scheduled sync to remove it permanently from the importer.
Method: DELETE
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/
Permission: delete
Response Codes
- 200
- If the schedule was deleted successfully
- 404
- If there is no repository, importer or schedule with the specified IDs
Return: null
D.1.3.6. Listing All Scheduled Syncs
All of the scheduled syncs for a given importer may be listed.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/
Permission: read
Response Codes
- 200
- If repo, importer exist
- 404
- If there is no repository or importer with the specified IDs
Return: array of schedule reports for all scheduled syncs defined
Sample 200 Response Body:
[ { "_href": "/pulp/api/v2/repositories/test/importers/yum_importer/schedules/sync/54d8852245ef4876fade7cc2/", "_id": "54d8852245ef4876fade7cc2", "args": [ "test" ], "consecutive_failures": 0, "enabled": true, "failure_threshold": null, "first_run": "2015-02-09T10:00:02Z", "kwargs": { "overrides": {} }, "last_run_at": "2015-02-09T10:00:23Z", "last_updated": 1423476133.825821, "next_run": "2015-02-10T10:00:02Z", "remaining_runs": null, "resource": "pulp:importer:test:yum_importer", "schedule": "P1DT", "task": "pulp.server.tasks.repository.sync_with_auto_publish", "total_run_count": 1 } ]
D.1.3.7. Listing a single scheduled sync
Each scheduled sync may be inspected.
Method: GET
Permission: read
Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/
Response Codes
- 200
- If repo, importer, schedule exist
- 404
- If there is no repository, importer or schedule with the specified IDs
Return: A schedule report for the scheduled sync
Sample 200 Response Body:
{ "_href": "/pulp/api/v2/repositories/test/importers/yum_importer/schedules/sync/54d8852245ef4876fade7cc2/", "_id": "54d8852245ef4876fade7cc2", "args": [ "test" ], "consecutive_failures": 0, "enabled": true, "failure_threshold": null, "first_run": "2015-02-09T10:00:02Z", "kwargs": { "overrides": {} }, "last_run_at": "2015-02-09T10:00:23Z", "last_updated": 1423476133.825821, "next_run": "2015-02-10T10:00:02Z", "remaining_runs": null, "resource": "pulp:importer:test:yum_importer", "schedule": "P1DT", "task": "pulp.server.tasks.repository.sync_with_auto_publish", "total_run_count": 1 }
D.1.3.8. Retrieving sync history
This call retrieves sync history for a repository. Each sync performed on a repository creates a history entry.
Method: GET
Permission: read
Path: /pulp/api/v2/repositories/<repo_id>/history/sync/
Query Parameters
- limit
- (integer) (optional) The maximum number of history entries to return; if not specified, the entire history is returned
- sort
- (string) (optional) Options are ‘ascending’ and ‘descending’; the array is sorted by the sync timestamp
- start_date
- (iso8601 datetime) (optional) Any entries with a timestamp prior to the given date are not returned
- end_date
- (iso8601 datetime) (optional) Any entries with a timestamp after the given date are not returned
Response Codes
- 200
- If the history was successfully retrieved
- 404
- If the repository id given does not exist
Return: An array of sync history entries
Sample 200 Response Body:
[ { "result": "success", "importer_id": "my_demo_importer", "exception": null, "repo_id": "demo_repo", "traceback": null, "started": "1970:00:00T00:00:00Z", "completed": "1970:00:00T00:00:01Z", "importer_type_id": "demo_importer", "error_message": null, } ]
D.1.4. Publication
D.1.4.1. Publish a repository
This call publishes content from a repository using a repository’s distributor. This call always executes asynchronously and returns a Call Report.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/actions/publish/
Permission: execute
Request Body Contents
- id
- (string) Identifies which distributor on the repository to publish
- override_config
- (object) (optional) Distributor configuration values that override the distributor’s default configuration for this publish
Response Codes
- 202
- If the publish is set to be executed
- 404
- If repo does not exist
Return: A Call Report representing the current state of the sync
Sample Request:
{ "id": "distributor_1", "override_config": {}, }
Tags: The task created has the following tags: pulp:action:publish
, pulp:repository:<repo_id>
D.1.4.2. Scheduling a publish
A repository can be published automatically using an iso8601 interval. To create a scheduled publish, the interval, publish override config, and other schedule options must be set on a repository’s distributor.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/
Permission: create
Request Body Contents
- schedule
- (string) The schedule as an iso8601 interval
- override_config
- (object) (optional) The overridden configuration for the distributor to be used on the scheduled publish
- failure_threshold
- (number) (optional) Consecutive failures allowed before this scheduled publish is disabled
- enabled
- (boolean) (optional) Whether the scheduled publish is initially enabled (defaults to true)
Response Codes
- 201
- If the schedule was successfully created
- 400
- If one or more of the parameters are invalid
- 404
- If there is no repository or distributor with the specified IDs
Return: Schedule report representing the current state of the scheduled call
Sample Request:
{ "override_config": {}, "schedule": "PT1H", "failure_threshold": 3, }
Sample 201 Response Body:
{ "next_run": "2014-01-27T21:27:56Z", "task": "pulp.server.tasks.repository.publish", "last_updated": 1390858076.682694, "first_run": "2014-01-27T21:27:56Z", "schedule": "PT1H", "args": [ "demo", "puppet_distributor" ], "enabled": true, "last_run_at": null, "_id": "52e6cf5cdd01fb70bd0d9c34", "total_run_count": 0, "failure_threshold": 3, "kwargs": { "overrides": {} }, "resource": "pulp:distributor:demo:puppet_distributor", "remaining_runs": null, "consecutive_failures": 0, "_href": "/pulp/api/v2/repositories/demo/distributors/puppet_distributor/schedules/publish/52e6cf5cdd01fb70bd0d9c34/" }
D.1.4.3. Updating a scheduled publish
The same parameters used to create a scheduled publish may be updated at any point.
Method: PUT
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/
Permission: create
Request Body Contents
- schedule
- (string) (optional) New schedule as an iso8601 interval
- override_config
- (object) (optional) New overridden configuration for the importer to be used on the scheduled sync
- failure_threshold
- (number) (optional) New consecutive failures allowed before this scheduled sync is disabled
- enabled
- (boolean) (optional) Whether the scheduled sync is enabled
Response Codes
- 200
- If the schedule was successfully updated
400: If one or more of the parameters are invalid
404: If there is no repository, distributor or schedule with the specified IDs
Return: Schedule report representing the current state of the scheduled call (See sample response of Scheduling a Publish for details.)
D.1.4.4. Deleting a scheduled publish
Delete a scheduled publish to remove it permanently from the distributor.
Method: DELETE
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/
Permission: delete
Response Codes
- 200
- If the schedule was deleted successfully
- 404
- If there is no repository, distributor or schedule with the specified IDs
Return: null
D.1.4.5. Listing all scheduled publishes
All of the scheduled publishes for a given distributor may be listed.
Method: GET
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/
Permission: read
Response Codes
- 200
- If there is a repository, a distributor exists
- 404
- If there is not repository or distributor with the specified IDs
Return: Array of schedule reports for all scheduled publishes defined (See sample response of Scheduling a Publish for details.)
Sample 200 Response Body:
{ "_href": "/pulp/api/v2/repositories/test/distributors/yum_distributor/schedules/publish/54d88df045ef4876fb50c994/", "_id": "54d88df045ef4876fb50c994", "args": [ "test", "yum_distributor" ], "consecutive_failures": 0, "enabled": true, "failure_threshold": null, "first_run": "2015-02-09T10:37:36Z", "kwargs": { "overrides": {} }, "last_run_at": "2015-02-09T10:38:23Z", "last_updated": 1423478256.805917, "next_run": "2015-02-10T10:37:36Z", "remaining_runs": null, "resource": "pulp:distributor:test:yum_distributor", "schedule": "P1DT", "task": "pulp.server.tasks.repository.publish", "total_run_count": 1 }
D.1.4.6. Listing a single scheduled publish
Each scheduled publish may be inspected.
Method: GET
Permission: read
Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/
Response Codes:
- 200
- If there is a repository, a distributor or schedule exists
- 404
- If there is not a repository, distributor or schedule with the specified IDs
Return: A schedule report for the scheduled publish (See sample response of Scheduling a Publish for details.)
Sample 200 Response Body:
{ "_href": "/pulp/api/v2/repositories/test/distributors/yum_distributor/schedules/publish/54d88df045ef4876fb50c994/", "_id": "54d88df045ef4876fb50c994", "args": [ "test", "yum_distributor" ], "consecutive_failures": 0, "enabled": true, "failure_threshold": null, "first_run": "2015-02-09T10:37:36Z", "kwargs": { "overrides": {} }, "last_run_at": "2015-02-09T10:38:23Z", "last_updated": 1423478256.805917, "next_run": "2015-02-10T10:37:36Z", "remaining_runs": null, "resource": "pulp:distributor:test:yum_distributor", "schedule": "P1DT", "task": "pulp.server.tasks.repository.publish", "total_run_count": 1 }
D.1.4.7. Retrieving publish history
This call retrieves publish history for a repository. Each publish performed on a repository creates a history entry.
Method: GET
Permission: read
Path: /pulp/api/v2/repositories/<repo_id>/history/publish/<distributor_id>/
Query Parameters
- limit
- (integer) (optional) The maximum number of history entries to return; if not specified, the entire history is returned.
- sort
- (string) (optional) Options are ‘ascending’ and ‘descending’; the array is sorted by the publish timestamp.
start_date (iso8601 datetime) (optional) Any entries with a timestamp prior to the given date are not returned.
- end_date
- (iso8601 datetime) (optional) Any entries with a timestamp after the given date are not returned.
Response Codes
- 200
- If the history was successfully retrieved
404: If the repository id given does not exist
Return: An array of publish history entries
Sample 200 Response Body:
[ { "result": "success", "distributor_id": "my_demo_distributor", "distributor_type_id": "demo_distributor", "exception": null, "repo_id": "demo_repo", "traceback": null, "started": "1970:00:00T00:00:00Z", "completed": "1970:00:00T00:00:01Z", "error_message": null, } ]
D.1.5. Content retrieval
D.1.5.1. Advanced unit search
A Unit Association Criteria can be used to search for units within a repository.
Method: POST
Path: /pulp/api/v2/repositories/<repo_id>/search/units/
Permission: read
Request Body Contents
- criteria
- (object) A UnitAssociationCriteria
Response Codes
- 200
- If the search executed
- 400
- If the criteria is missing or not valid
- 404
- If the repository is not found
Return: Array of objects representing content unit associations
Sample Request:
{ "criteria": { "fields": { "unit": [ "name", "version" ] }, "type_ids": [ "rpm" ], "limit": 1 } }
Sample 200 Response Body:
[ { "updated": "2013-09-04T22:12:05Z", "repo_id": "zoo", "created": "2013-09-04T22:12:05Z", "_ns": "repo_content_units", "unit_id": "4a928b95-7c4a-4d23-9df7-ac99978f361e", "metadata": { "_id": "4a928b95-7c4a-4d23-9df7-ac99978f361e", "version": "4.1", "name": "bear", "pulp_user_metadata": {} }, "unit_type_id": "rpm", "id": "522777f5e19a002faebebf79" } ]
D.2. Task management
Pulp can execute almost any call asynchronously, and some calls are always executed asynchronously. Pulp provides REST APIs to inspect and manage the tasks executing these calls.
D.2.1. Task report
The task information object is used to report information about any asynchronously executed task.
Task information object
- _href
- (string) URI path to retrieve this task report object
- state
-
(string) The current state of the task; the possible values include
waiting
,skipped
,‘running
,suspended
,finished
,error
, andcanceled
. - task_id
- (string) The unique ID of the task that is executing the asynchronous call
- task_type
- (string) Deprecated the fully qualified (package/method) type of the task that is executing the asynchronous call; the field is empty for tasks performed by consumer agent.
- progress_report
- (object) Arbitrary progress information, usually in the form of an object
- result
- (any) The return value of the call, if any
- exception
- (null or string) Deprecated the error exception value, if any
- traceback
- (null or array) Deprecated the resulting traceback if an exception was raised
- start_time
- (null or string) The time the call started executing
- finish_time
- (null or string) The time the call stopped executing
- tags
- (array) Arbitrary tags useful for looking up the Call Report
- spawned_tasks
- (array) List of objects containing the URI and task ID for any tasks that were spawned by this task
- worker_name
- (string) The worker associated with the task; this field is empty if a worker is not yet assigned.
- queue
- (string) The queue associated with the task; this field is empty if a queue is not yet assigned.
- error
- (null or object) Any errors that occurred that did not cause the overall call to fail. See Error Details.
The exception and traceback fields have been deprecated as of Pulp 2.4. The information about errors that have occurred will be contained in the error block. See Error Details for more information.
Example Task Report:
{ "_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/", "state": "running", "worker_name": "reserved_resource_worker-0@your.domain.com", "task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff", "task_type": "pulp.server.tasks.repository.sync_with_auto_publish", "progress_report": {}, # contents depend on the operation "result": null, "start_time": "2012-05-17T16:48:00Z", "finish_time": null, "exception": null, "traceback": null, "tags": [ "pulp:repository:f16", "pulp:action:sync" ], "spawned_tasks": [{"href": "/pulp/api/v2/tasks/7744e2df-39b9-46f0-bb10-feffa2f7014b/", "task_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b" }], "error": null }
D.2.2. Polling task progress
Poll a task for progress and result information for the asynchronous call it is executing. Polling returns a Task Report.
Method: GET
Path: /pulp/api/v2/tasks/<task_id>/
Permission: read
Response Codes
- 200
- If the task is found
- 404
- If the task is not found
Return: A Task Report representing the task queried
D.2.3. Canceling a task
Some asynchronous tasks may be canceled by the user before they complete. A task must be in the waiting or running states in order to be canceled.
It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be canceled as a result of this call. In these instances, this method call will still return a response code of 200.
Method: DELETE
Path: /pulp/api/v2/tasks/<task_id>/
Permission: delete
Response Codes
- 200
- If the task cancellation request was successfully received
- 404
- If the task is not found
Return: null
D.2.4. Listing tasks
All currently running and waiting tasks may be listed. This returns an array of Task Report instances. the array can be filtered by tags.
Method: GET
Path: /pulp/api/v2/tasks/
Permission: read
Query Parameters
- tag
- (string) (optional) Only return tasks tagged with all tag parameters
Response Codes
- 200
- Containing an array of tasks
Return: Array of Task Report
D.2.5. Deleting completed tasks
All completed tasks with states finished, error, skipped can be deleted. This call returns response code 204 if successful or code 403 if the request is forbidden.
Method: DELETE
Path: /pulp/api/v2/tasks/
Permission: delete
- state
- (string) (optional) Only delete tasks currently in this state
For example:
/pulp/api/v2/tasks/?state=finished&state=skipped
Response Codes
- 204
- if the tasks were successfully deleted
- 403
- If there was a forbidden request
Return: http Response or pulp Exception
D.2.6. Searching for tasks
API callers may also search for tasks. This uses a search criteria document.
Method: POST
Path: /pulp/api/v2/tasks/search/
Permission: read
Request Body Contents: Include the key criteria
, whose value is a mapping structure as defined in Search Criteria.
Response Codes
- 200
- Containing the list of tasks
Return: The same format as retrieving a single task, except the base of the return value is a list; if no results are found, an empty list is returned.
Method: GET
Path: /pulp/api/v2/tasks/search/
Permission: read
Query Parameters: Query parameters should match the attributes of a Criteria object as defined in Search Criteria. The exception is that field names should be specified in singular form with as many ‘field=foo’ pairs as needed.
For example:
/pulp/api/v2/tasks/search/?field=id&field=task_type&limit=20
Response Codes
- 200
- Containing the array of tasks
D.3. Task group management
D.3.1. Canceling tasks in a task group
All asynchronous tasks in a particular task group can be canceled by the user before they complete. A task must be in the waiting
or running
state to be canceled.
=== It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be canceled as a result of this call. In these instances, this method call will still return a response code of 200. ===
Method: DELETE
Path: /pulp/api/v2/task_groups/<group_id>/
Permission: delete
Response Codes
- 200
- If the task group cancellation request was successfully received
- 404
- If the task group is not found
Return: null
D.3.2. Task group summary
The Task Group Summary object summarizes the state of all the tasks belonging to a task group.
Task Group Summary object
- accepted
-
(int) Number of tasks in
accepted
state - finished
-
(int) Number of tasks in
finished
state - running
-
(int) Number of tasks in
running
state - canceled
-
(int) Number of tasks in
canceled
state - waiting
-
(int) Number of tasks in
waiting
state - skipped
-
(int) Number of tasks in
skipped
state - suspended
-
(int) Number of tasks in
suspended
state - error
-
(int) Number of tasks in
error
state - tota
- (int) Total number of tasks in the task group
Example task group summary:
{ "accepted": 0, "finished": 100, "running": 4, "canceled": 0, "waiting": 2, "skipped": 0, "suspended": 0, "error": 0, "total": 106 }
D.3.3. Polling task group progress
Poll a group of tasks for progress summary. Polling returns a Cancelling Tasks in a Task Group.
Method: GET
Path: /pulp/api/v2/task_groups/<task_group_id>/state_summary/
Permission: read
Response Codes
- 200
- If the task group is found
- 404
- If the task group id is not found
Return: A Cancelling Tasks in a Task Group summarizing the state of all tasks belonging to queried task group ID