Creation, Deletion, and Configuration

Create a Repository

Creates a new repository in Pulp. This call accepts optional parameters for importer and distributor configuration. More detailed description of these parameters can be found below in the documentation of APIs to associate an importer or a distributor to an already existing repository. If these parameters are not passed, the call will only create the repository in Pulp. The real functionality of a repository isn’t 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 and basic_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, and distributor_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/"
}

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/"

 },
 ...
}

Associate an Importer to a Repository

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>

Associate a Distributor with a Repository

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 will support a different set of values relevant to how it functions.

Multiple distributors may be associated with a repository at a given time. There may 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 will use to drive the behavior of the distributor
  • distributor_id (string) - (optional) if specified, this value will be used to refer to the distributor; if not specified, one will be randomly assigned to the distributor
  • auto_publish (boolean) - (optional) if true, this distributor will automatically have 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"
}

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 will be returned 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.

{
  "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 will have the following tags: "pulp:action:update_importer", "pulp:repository:<repo_id>", "pulp:repository_importer:<importer_id>

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 will have the following tags: "pulp:action:delete_importer", "pulp:repository:<repo_id>", "pulp:repository_importer:<importer_id>

Update a Distributor Associated with a Repository

Update the configuration for a distributor that has already been associated with a repository. This performs the following actions:

  1. Updates the distributor on the server.
  2. 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 will be populated 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 will 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.

Disassociate a Distributor from a Repository

Disassociating a distributor performs the following actions:

  1. Remove the association between the distributor and the repository.
  2. Unbind all bound consumers.

The first step is represented by a Call Report. Upon completion of step 1 the spawned_tasks field will be populated 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 will have the following tags: "pulp:action:remove_distributor","pulp:repository:<repo_id>", "pulp:repository_distributor:<distributor_id>

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, however, is not deleted. Deleting content is handled through the orphaned unit process.

Deleting a repository is performed in the following major steps:

  1. Delete the repository.
  2. Unbind all bound consumers.

The first step is represented by a Call Report. Upon completion of step 1 the spawned_tasks field will be populated 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 will have the following tags: "pulp:action:delete","pulp:repository:<repo_id>"