Role Workflows¶

Pulp organizes role content into repositories, and you associate the ansible-galaxy client with one or more repositories. From a high level you can:

Create a repo
Create a distribution expose that repository at a URL
Sync content from galaxy.ansible.com
Install content from the repo with ansible-galaxy

API Client Setup¶

To use the bash examples on this page. Run these basic bash utilities below:

#!/usr/bin/env bash
echo "Setting environment variables for default hostname/port for the API and the Content app"
export BASE_ADDR=${BASE_ADDR:-http://localhost:24817}
export CONTENT_ADDR=${CONTENT_ADDR:-http://localhost:24816}

# Necessary for `django-admin`
export DJANGO_SETTINGS_MODULE=pulpcore.app.settings

# Poll a Pulp task until it is finished.
wait_until_task_finished() {
    echo "Polling the task until it has reached a final state."
    local task_url=$1
    while true
    do
        local response=$(http $task_url)
        local state=$(jq -r .state <<< ${response})
        jq . <<< "${response}"
        case ${state} in
            failed|canceled)
                echo "Task in final state: ${state}"
                exit 1
                ;;
            completed)
                echo "$task_url complete."
                break
                ;;
            *)
                echo "Still waiting..."
                sleep 2
                ;;
        esac
    done
}

Create a Repository¶

Create a repository and name it the foo repository.

echo "Start by creating a new repository named foo"
http POST $BASE_ADDR/pulp/api/v3/repositories/ansible/ansible/ name=foo

# If you want to copy/paste your way through the guide,
# create an environment variable for the repository URI.
export REPO_HREF=$(http $BASE_ADDR/pulp/api/v3/repositories/ansible/ansible/ | \
  jq -r '.results[] | select(.name == "foo") | .pulp_href')

echo "Inspecting repository."
http $BASE_ADDR$REPO_HREF

Repository GET Response:

{
    "pulp_created": "2019-04-29T15:57:59.763712Z",
    "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/1b2b0af1-5588-4b4b-b2f6-cdd3a3e1cd36/",
    "latest_version_href": null,
    "versions_href": "/pulp/api/v3/repositories/ansible/ansible/1b2b0af1-5588-4b4b-b2f6-cdd3a3e1cd36/versions/",
    "description": "",
    "name": "foo"
}

Reference (pulpcore): Repository API Usage

Create a Distribution for Repository ‘foo’¶

This will make the latest Repository Version content available for ansible-galaxy` clients. Each distribution names the url it can be accessed from on an attribute called ``client_url. The client_url can be used with the ansible-galaxy client with the -s option. See the Install a Role, hosted by Pulp, using ansible-galaxy docs for more details.

For example a distribution with base_path set to my_content could have a URL like:

http://pulp.example.com/pulp_ansible/galaxy/my_content/

# Distributions are created asynchronously. Create one, and specify the publication that will
# be served at the base path specified.
export TASK_HREF=$(http POST $BASE_ADDR/pulp/api/v3/distributions/ansible/ansible/ \
  name='baz' \
  base_path='my_content' \
  repository=${REPO_HREF} | jq -r '.task')

# Poll the task (here we use a function defined in docs/_scripts/base.sh)
# When the task is complete, it gives us the href for our new Distribution
wait_until_task_finished $BASE_ADDR$TASK_HREF
export DIST_PATH=${CREATED_RESOURCE[0]}

# Lets inspect the Distribution
http $BASE_ADDR$DIST_PATH

{
    "pulp_created": "2019-07-26T16:46:23.666410Z",
    "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/4262ed83-e86c-4a13-baff-fc543c46a391/",
    "base_path": "my_content",
    "base_url": "/pulp/content/foo",
    "content_guard": null,
    "name": "baz",
    "repository": "/pulp/api/v3/repositories/ansible/ansible/301bec4f-c5e7-4a20-a124-f8a1ec1f9229/",
    "repository_version": null
}

Create a Distribution for a RepositoryVersion (optional)¶

Instead of always distributing the latest RepositoryVersion, you can also specify a specific RepositoryVersion for a Distribution. This should be used in place of the distribution above, not in addition to it.

# Distributions are created asynchronously. Create one, and specify the publication that will
# be served at the base path specified.
export TASK_HREF=$(http POST $BASE_ADDR/pulp/api/v3/distributions/ansible/ansible/ \
  name='baz' \
  base_path='my_content' \
  repository_version=${REPO_HREF}versions/1/ | jq -r '.task')

# Poll the task (here we use a function defined in docs/_scripts/base.sh)
# When the task is complete, it gives us the href for our new Distribution
wait_until_task_finished $BASE_ADDR$TASK_HREF
export DIST_PATH=${CREATED_RESOURCE[0]}

# Lets inspect the Distribution
http $BASE_ADDR$DIST_PATH

{
    "pulp_created": "2019-07-26T16:51:04.803014Z",
    "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/c9879338-8656-46aa-a2b2-46fa5d7b0329/",
    "base_path": "my_content",
    "base_url": "/pulp/content/foo",
    "content_guard": null,
    "name": "baz",
    "repository": null,
    "repository_version": "/pulp/api/v3/repositories/ansible/ansible/301bec4f-c5e7-4a20-a124-f8a1ec1f9229/versions/1/"
}

Create a Remote¶

Creating a Remote object informs Pulp about an external content source, which most commonly is https://galaxy.ansible.com/ or another pulp_ansible instance. In this case, we will be syncing all Roles where namespace=elastic on Galaxy. You can browse those Roles Pulp will import here.

echo "Create a remote that syncs some versions of django into your repository."
http POST $BASE_ADDR/pulp/api/v3/remotes/ansible/role/ \
    name='bar' \
    url='https://galaxy.ansible.com/api/v1/roles/?namespace__name=elastic'

# Export an environment variable for the new remote URI.
export REMOTE_HREF=$(http $BASE_ADDR/pulp/api/v3/remotes/ansible/role/ | jq -r '.results[] | select(.name == "bar") | .pulp_href')

echo "Inspecting new Remote."
http $BASE_ADDR$REMOTE_HREF

Remote GET Response:

{
    "pulp_href": "/pulp/api/v3/remotes/ansible/role/e1c65074-3a4f-4f06-837e-75a9a90f2c31/",
}

Sync Repository foo with Remote¶

Use the Remote object to kick off a synchronize task by specifying the Repository to sync with. You are telling Pulp to fetch content from the Remote and add to the Repository.

#!/usr/bin/env bash

# Sync repository foo using remote bar
echo "Create a task to sync the repository using the remote."
export TASK_HREF=$(http POST $BASE_ADDR$REPO_HREF'sync/' \
    remote=$REMOTE_HREF \
    | jq -r '.task')

# Poll the task (here we use a function defined in docs/_scripts/base.sh)
wait_until_task_finished $BASE_ADDR$TASK_HREF

# After the task is complete, it gives us a new repository version
echo "Set REPOVERSION_HREF from finished task."
export REPOVERSION_HREF=$(http $BASE_ADDR$TASK_HREF| jq -r '.created_resources | first')

echo "Inspecting RepositoryVersion."
http $BASE_ADDR$REPOVERSION_HREF

Repository Version GET Response (when complete):

{
    "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/78286e2c-829a-4a8c-a3ca-3a2e490e01a7/versions/1/",
    "base_version": null,
    "content_summary": {
        "added": {
            "ansible.role": {
                "count": 16,
                "href": "/pulp/api/v3/content/ansible/roles/?repository_version_added=/pulp/api/v3/repositories/ansible/ansible/78286e2c-829a-4a8c-a3ca-3a2e490e01a7/versions/1/"
            }
        },
        "present": {
            "ansible.role": {
                "count": 16,
                "href": "/pulp/api/v3/content/ansible/roles/?repository_version=/pulp/api/v3/repositories/ansible/ansible/78286e2c-829a-4a8c-a3ca-3a2e490e01a7/versions/1/"
            }
        },
        "removed": {}
    },
    "number": 1
}

Reference (pulpcore): Repository Version List API Usage

Install a Role, hosted by Pulp, using `ansible-galaxy`¶

Using a direct path¶

Install your role by name by specifying the distribution serving your Repository’s content using the -s option.

ansible-galaxy install elasticsearch,6.2.4 -c -s http://pulp.example.com/pulp_ansible/galaxy/my_content/

Configuring ansible-galaxy Permanently¶

Use the ansible-galaxy config files to specify the distribution ansible-galaxy should interact with. To use this, set up your distribution in your ansible config (e.g. ~/.ansible.cfg or /etc/ansible/ansible.cfg):

[galaxy]
server: http://pulp.example.com/pulp_ansible/galaxy/my_content/

Then you can install without the -s url

$ ansible-galaxy install elastic.elasticsearch,6.2.4
- downloading role 'elasticsearch', owned by elastic
- downloading role from http://localhost:24816/pulp/content/dev/elastic/elasticsearch/6.2.4.tar.gz
- extracting elastic.elasticsearch to /home/vagrant/.ansible/roles/elastic.elasticsearch
- elastic.elasticsearch (6.2.4) was installed successfully

Add/Remove Content to a Repository¶

Whether your Role was fetched with a sync or uploaded, any content can also be added/removed to a repository manually:

http POST pulp.example.com/pulp/api/v3/repositories/ansible/ansible/modify/ \
    add_content_units:="['/pulp/api/v3/content/ansible/roles/d2bab58c-50f2-4f1d-9cf0-8ceb1680f31b/']"

This is entirely implemented by pulpcore, please see their reference docs for more information.

Reference (pulpcore): Repository Version Creation API Usage

Role Workflows¶

API Client Setup¶

Create a Repository¶

Create a Distribution for Repository ‘foo’¶

Create a Distribution for a RepositoryVersion (optional)¶

Create a Remote¶

Sync Repository foo with Remote¶

Install a Role, hosted by Pulp, using `ansible-galaxy`¶

Using a direct path¶

Configuring ansible-galaxy Permanently¶

Add/Remove Content to a Repository¶

Pulp Ansible

Navigation

Related Topics

Role Workflows¶

API Client Setup¶

Create a Repository¶

Create a Distribution for Repository ‘foo’¶

Create a Distribution for a RepositoryVersion (optional)¶

Create a Remote¶

Sync Repository foo with Remote¶

Install a Role, hosted by Pulp, using ansible-galaxy¶

Using a direct path¶

Configuring ansible-galaxy Permanently¶

Add/Remove Content to a Repository¶

Install a Role, hosted by Pulp, using `ansible-galaxy`¶