A.18. Content Delivery Server (CDS)

A.18.1. Register

Registers a Content Delivery Server (CDS) instance with the Pulp server. The CDS instance must be configured and running prior to this call. This call will attempt to initialize the CDS instance which involves making an invocation against it and negotiating the shared token. If that initialization is unsuccessful, this call will fail and the CDS will not be added to the Pulp server.
There is no explicit step for creating a CDS cluster. If the CDS is to be part of a cluster, the desired cluster ID is specified in this call and effectively creates the cluster at that point.
  • method: POST
  • path: /cds/
  • permission: CREATE
  • success response: 201 - Created
  • failure response:
    • 409 - if there is already a CDS instance with the given hostname
    • 500 - if the CDS instance cannot be reached to be initialized or raises an error during initialization
  • return:dictionary describing the created CDS instance
  • parameters:dictionary describing the created CDS instance
    • hostname <str> the hostname of the CDS instance being registered
    • name <str> user-friendly name for the CDS instance
    • description <str> user-friendly description of the CDS instance
    • sync_schedule <str> schedule in iso8601 format
    • cluster_id <str> (optional) ID of the cluster the CDS should belong to
  • sample response: 
    {
  "description": null, 
  "_ns": "cds", 
  "hostname": "pulp-cds-1", 
  "last_sync": null, 
  "secret": "833925b0-2732-46dd-95bc-570d532c1e31", 
  "cluster_id": null, 
  "sync_schedule": null, 
  "repo_ids": [], 
  "_id": "pulp-cds-1", 
  "id": "pulp-cds-1", 
  "name": "pulp-cds-1"
}

A.18.2. Unregister

Removes a CDS instance from Pulp control. The CDS processes running on the instance are not stopped. The shared secret between the Pulp server and CDS is removed from the CDS, allowing it to be registered to a different Pulp server.
This call will attempt to inform the CDS it is being released. If that call to the CDS fails, this call will fail. The CDS can be forcibly removed from the Pulp server's database by passing the "force" flag to the call.
  • method: DELETE
  • path: /cds/<hostname>/
  • permission: DELETE
  • success response: 200 - OK
  • failure response:
    • 500 - if there is no CDS for the given hostname
  • return:true if the CDS was unregistered
  • parameters:dictionary describing the created CDS instance
    • hostname <str> the hostname of the CDS instance being registered
    • force <boolean> if true, the CDS will be removed from the Pulp database even if it cannot be contacted

A.18.3. List All

Returns a list of all CDS instances registered to the Pulp server.
  • method: GET
  • path: /cds/
  • permission: READ
  • success response: 200 - OK
  • failure response: None
  • return: list of dictionaries describing each CDS instance
  • sample response: 
    [
  {
    "description": null, 
    "_ns": "cds", 
    "hostname": "pulp-cds-1", 
    "last_sync": null, 
    "secret": "56f3a490-cdff-435f-ae42-4bddc0526f3e", 
    "cluster_id": null, 
    "sync_schedule": null, 
    "repo_ids": [], 
    "heartbeat": [
      false, 
      "2011-11-30T21:16:00.767145+00:00", 
      {
        "cds": {}
      }
    ], 
    "_id": "pulp-cds-1", 
    "id": "pulp-cds-1", 
    "name": "pulp-cds-1"
  }
]

A.18.4. Get CDS Instance

Retrieves metadata describing a single CDS instance.
  • method: GET
  • path: /cds/<hostname>/
  • permission: READ
  • success response: 200 - OK
  • failure response:
    • 404 - if no CDS exists with the given hostname
  • return:dictionary describing the CDS instance
  • parameters:
    • hostname <str> the hostname of the CDS instance to retrieve
  • sample response: 
    {
  "description": null, 
  "_ns": "cds", 
  "hostname": "pulp-cds-1", 
  "last_sync": null, 
  "secret": "56f3a490-cdff-435f-ae42-4bddc0526f3e", 
  "cluster_id": null, 
  "sync_schedule": null, 
  "repo_ids": [], 
  "heartbeat": [
    false, 
    "2011-11-30T21:16:00.767145+00:00", 
    {
      "cds": {}
    }
  ], 
  "_id": "pulp-cds-1", 
  "id": "pulp-cds-1", 
  "name": "pulp-cds-1"
}

A.18.5. Associate a Repository

Configures the CDS to host the given repository. The repository is not immediately sent to the CDS but rather will be downloaded in the next CDS sync.
  • method: POST
  • path: /cds/<hostname>/associate/
  • permission: EXECUTE
  • success response: 201 - Accepted
  • failure response:
    • 409 - if the Pulp server is currently redistributing consumers for the given repository across the current CDS host list for that repository
  • return:task instance describing the redistribution of consumers to take the CDS into account
  • parameters:
    • hostname <str> task instance describing the redistribution of consumers to take the CDS into account
    • repo_id <str> identifies the repository being associated with the CDS instance
  • sample response: 
    {
  "scheduled_time": "2011-11-30T21:18:49Z", 
  "exception": null, 
  "args": [
    "repo-1"
  ], 
  "job_id": null, 
  "class_name": "CdsApi", 
  "start_time": null, 
  "traceback": null, 
  "method_name": "redistribute", 
  "finish_time": null, 
  "state": "waiting", 
  "result": null, 
  "scheduler": "immediate", 
  "progress": null, 
  "id": "e5496305-1b98-11e1-9c0f-00508d977dff"
}

A.18.6. Unassociate a Repository

Removes a repository from being hosted by a CDS instance. As with associate, this call simply updates the Pulp database. The change is not seen on the CDS instance until the next sync occurs.
  • method: POST
  • path: /cds/<hostname>/unassociate/
  • permission: EXECUTE
  • success response: 201 - Accepted
  • failure response:
    • 409 - if the Pulp server is currently redistributing consumers for the given repository across the current CDS host list for that repository
  • return:task instance describing the redistribution of consumers to take the CDS removal into account
  • parameters:
    • hostname <str> the hostname of the CDS instance to update
    • repo_id <str> identifies the repository being removed from the CDS instance
  • sample response: 
    {
  "scheduled_time": "2011-11-30T21:19:16Z", 
  "exception": null, 
  "args": [
    "repo-1"
  ], 
  "job_id": null, 
  "class_name": "CdsApi", 
  "start_time": null, 
  "traceback": null, 
  "method_name": "redistribute", 
  "finish_time": null, 
  "state": "waiting", 
  "result": null, 
  "scheduler": "immediate", 
  "progress": null, 
  "id": "f5968980-1b98-11e1-86e4-00508d977dff"
}

A.18.7. Retrieve CDS History

Retrieves history entries describing events that took place on a CDS instance.
  • method: POST
  • path: /cds/<hostname>/history/
  • permission: EXECUTE
  • success response: 200 - OK
  • failure response: None
  • return:list of CDS history items (empty list if none match) containing the following fields:
    • cds_hostname <str> hostname of the CDS the entry refers to
    • originator <str> indicates the user who triggered the action that caused the history event
    • type_name <str> describes the type of event that occurred; possible values: registered, unregistered, sync_started, sync_finished, repo_associated, repo_unassociated
    • details <str> arbitrary text further describing the event (will differ based on event type
    • timestamp <str> timestamp in iso8601 format of when the event item was added
  • parameters:(any of the parameters can be combined for advanced queries)
    • hostname <str> the hostname of the CDS instance to update
    • event_type <str> (optional) if specified, only events of the given type are returned (see above for valid type names)
    • limit <str> (optional) if specified, only up to the given amount of items will be returned
    • sort <str> (optional) indicates the sort direction by timestamp; valid values: ascending, descending
    • start_date <str> (optional) if specified, only events that took place after the given date (in iso8601 format) will be returned
    • end_date <str> (optional) if specified, only events that took place before the given date (in iso8601 format) will be returned
  • sample response: 
    [
  {
    "originator": "admin", 
    "cds_hostname": "pulp-cds-1", 
    "timestamp": "2011-11-30T21:19:16Z", 
    "type_name": "repo_unassociated", 
    "details": {
      "repo_id": "repo-1"
    }, 
    "_ns": "cds_history", 
    "_id": "4d813279-1fac-4f04-b9c6-28a00545e0e3", 
    "id": "4d813279-1fac-4f04-b9c6-28a00545e0e3"
  }, 
  {
    "originator": "admin", 
    "cds_hostname": "pulp-cds-1", 
    "timestamp": "2011-11-30T21:18:49Z", 
    "type_name": "repo_associated", 
    "details": {
      "repo_id": "repo-1"
    }, 
    "_ns": "cds_history", 
    "_id": "93d7d6dd-baf7-4ce5-b580-c134736ceeca", 
    "id": "93d7d6dd-baf7-4ce5-b580-c134736ceeca"
  }
]

A.18.8. Trigger a CDS Synchronization

Schedules a CDS sync to run as soon as possible (may be delayed depending on what other work the Pulp server is doing). The sync will take place asynchronously and the call will return immediately with information on how to track the sync.
  • method: POST
  • path: /cds/<hostname>/sync/
  • permission: EXECUTE
  • success response: 201 - Accepted
  • failure response:
    • 400 - if the timeout cannot correctly be parsed
    • 404 - if no CDS exists with the given hostname
  • return:task instance describing the sync task
  • parameters:
    • hostname <str> the hostname of the CDS instance to update
    • timeout <str> timeout value in iso8601 format that dictates how long the sync may run before the Pulp server aborts the request
  • sample response: 
    {
  "scheduled_time": "2011-11-30T21:21:04Z", 
  "exception": null, 
  "args": [
    "pulp-cds-1"
  ], 
  "job_id": null, 
  "class_name": "CdsApi", 
  "start_time": null, 
  "traceback": null, 
  "method_name": "cds_sync", 
  "finish_time": null, 
  "state": "waiting", 
  "result": null, 
  "scheduler": "immediate", 
  "progress": null, 
  "id": "36203045-1b99-11e1-add9-00508d977dff"
}