Common API workflows

Continuous Delivery for Puppet Enterprise’s API enables users to automate many common workflows.

Get your authorization token

You need a personal access token to automate common workflows using the API.

Make sure that you have read the Authentication section and have a personal access token. You need the personal access token you created in Add a personal access token. It is required for authentication.

Find a workspace ID

When using most API endpoints, you need to specify a workspace ID.

Find the workspaces you have access to by using the GET /v1/user endpoint. The domain of each workspace is its ID. 
auth_header="Authorization: <API Token>"  
uri="https://<CD4PE hostname>/cd4pe/api/v1/user 
curl --insecure --header "$auth_header" --request GET "$uri”
This returns information about your workspaces. For example, it might look similar to the following:
{  
  "user" : { ... },  
  "workspaces" : [  
    {  
      "domain" : "d6",  
      "name" : "example_workspace_1"  
    }, 
    {  
      "domain" : "d7",  
      "name" : "example_workspace_2"  
    }  
  ]  
}
Results
Use the workspace ID as needed for API endpoints, such as finding your Puppet Enterprise environment node group ID, triggering an impact analysis, triggering a deployment, and so forth.

Find a Puppet Enterprise environment node group ID

Find the ID of the environment node group in Puppet Enterprise using the ID of your Puppet Enterprise integration.

Before you begin
You need to have your workspace ID obtained in the previous task.
  1. Find the ID of your Puppet Enterprise integration. 
    auth_header="Authorization: <API Token>" 
uri="https://<CD4PE host>/cd4pe/api/v2/pe-integrations?workspaceID=<workspace ID> 
curl --insecure --header "$auth_header" --request GET "$uri"
    This returns information about your Puppet Enterprise integrations. For example, it might look similar to the following:
    {  
  "peIntegrations" : [  
    {  
      "id" : "e274e692-8423-48b6-a1f3-6e09138624ec",  
      "workspaceId" : "d5",  
      "name" : "example-pe", 
      "nodeClassifierUrl" : "puppet.example.com:4433", 
      ... 
    } 
  ]  
}
  2. Use the ID from your Puppet Enterprise integration to get information about the environments: 
    auth_header="Authorization: <API Token>" 
uri="https://<CD4PE host>/cd4pe/api/v2/pe-integrations/<PE integration ID>/environments 
curl --insecure --header "$auth_header" --request GET "$uri"
    This returns information about the environments associated with your Puppet Enterprise integration. For example, it might look similar to the following:
    "environments" : [  
  {  
    "name" : "All Environments",  
    "id" : "00e0c92e-30c9-4569-bcc2-0a4ebeffe3a3",  
    "description" : "Environment group parent and default",  
    "environment" : "production"  
  },  
  {  
    "name" : "Development environment",  
    "id" : "c2184ce4-cb96-49eb-9724-4618db267769",  
    "description" : "Development nodes",  
    "environment" : "development"  
  } 
]
What to do next
Use the environment node group ID as needed for API endpoints, such as triggering a deployment.

Get the SHA of a repo branch

Find the SHA of the HEAD of a given repo branch using Continuous Delivery for PE’s /v1/vcs/branches API endpoint.

To find the SHA of the HEAD of a given repo branch, you can either find the commit in your VCS provider or you can use Continuous Delivery for PE’s /v1/vcs/branches API endpoint. Here, project is used to refer to the owner/org of the repo for all providers except GitHub. If your repo comes from GitHub, you must supply either organization or owner instead, depending on whether the repo belongs to an individual or an organization.

Use your workspace ID to find the SHA. 
auth_header="Authorization: <API Token>" 
uri="https://<CD4PE host>/cd4pe/api/v1/vcs/branch?workspaceID=<workspace ID>&provider=BITBUCKET&project=puppet&name=my_control_repo&branch=main
curl --insecure --header "$auth_header" --request GET "$uri”
This returns information about the repo branch. For example, it might look similar to the following:
{  
  "name" : "main",  
  "headSha" : "4c2f400a77cd73ebf67271361e1dd9b1102b43b4"  
}

Trigger an Impact Analysis

Use the Continuous Delivery for PE API to trigger an impact analysis on the module of a control repo.

Before you begin
In order to trigger an Impact Analysis run of your code changes, you need to collect the following: 

data="$(cat <<EOF  
{  
  "workspaceId": "<workspace ID>", 
  "projectName": "control-repo",  
  "projectType": "CONTROL_REPO",  
  "settings": {  
    "environments": [  
      {  
        "nodeGroupId": "<environment node group ID>",  
        "peCredentialsId": {  
          "name": "example-pe",  
          "domain": "<workspace ID>"  
        }  
      },  
      {  
        "nodeGroupId": "defcea94-e7e5-4fe3-b971-1acd44785695",  
        "peCredentialsId": {  
          "name": "example-pe",  
          "domain": "<workspace ID>"  
        }  
      }  
    ],  
    "sourceBranch": "<branch to test>",  
    "sourceSha": "<SHA to test>",  
    "analyzeAllDeployments": false,  
    "compileBatchSize": 10,  
    "controlRepoId": {  
      "name": "control-repo",  
      "domain": "<workspace ID>"  
    }  
  }  
}  
EOF  
)"  
type_header='Content-Type: application/json'  
auth_header="Authorization: <authorization token>"  
uri="https://<cd4pe host>/cd4pe/api/v1/impact-analysis/trigger"  
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

This returns something similar to the following:

{  
  "appEventId" : 18900,  
  "baseTaskUrl" : "https://<cd4pe host>/cd4pe/root/deployments",  
  "domain" : "d5",  
  "id" : 110,  
  ...data repeated from request...  
  "state" : "QUEUED"  
}

Once the impact analysis has finished, you might want to check the state of the run and fetch the analysis report, to do so use the ID of the response that was returned like so:

type_header='Content-Type: application/json'  
auth_header="Authorization: <API token>"  
uri="https://<cd4pe host>/cd4pe/api/v1/impact-analysis/<IA run ID>/csv?workspaceId=<workspace ID>"  
curl --insecure --header "$type_header" --header "$auth_header" --request GET "$uri"

Trigger a deployment

Use the Continuous Delivery for PE API to trigger a deployment from one of your branches to a Puppet Enterprise environment.

Before you begin
In order to trigger a deployment, you need to collect the following:
Note: If the deployment targets a protected environment, it does not run without approval. An approval request is created in the Continuous Delivery for PE console that must be approved to trigger the code to be deployed to the environment.
  1. Get the deployment policy details. A deployment policy describes how you want the code from your source branch to be deployed to your Puppet Enterprise instance. You can list all the policies available in your workspace using: 
    auth_header="Authorization: <API token>"  
uri="https://<CD4PE host>/cd4pe/api/v1/deployments/policies?workspaceId=<workspace ID>&projectName=my_control_repo&projectType=CONTROL_REPO"  
curl --insecure --header "$type_header" --header "$auth_header" --request GET "$uri"
    This returns information about the policies in your workspace. For example, it might look similar to the following:
    
{  
  "deploymentPolicies" : [  
    {  
      "custom" : false,  
      "displayName" : "Direct deployment policy",  
      "name" : "cd4pe_deployments::direct",  
      "parameters" : [  
        {  
          "name" : "max_node_failure",  
          "type" : "Optional[Integer]",  
          "value" : null  
        },  
        {  
          "name" : "noop",  
          "type" : "Boolean",  
          "value" : false  
        },  
        {  
          "name" : "fail_if_no_nodes",  
          "type" : "Boolean",  
          "value" : true  
        }  
      ]  
    }, 
    ....  
  ]  
}

    From this you can choose which policy you want to use for this deployment and supply it to the deployment request, customizing the values of any parameters that you want to change.

  2. Trigger the deployment. Once you have collected all the information you need, you can trigger the deployment. 
    data="$(cat <<EOF  
{  
  "workspaceId": "<workspace ID>",  
  "projectName": "<name of control repo or module to deploy from>",  
  "projectType": "CONTROL_REPO",  
  "displayName": "Deployment to production on example-pe",  
  "description": "Run Production Deployment from main",  
  "maxRuntime": 3600000,  
  "deploymentPolicy": {  
    "custom": false,  
    "displayName": "Direct deployment policy",  
    "name": "cd4pe_deployments::direct",  
    "parameters": [ 
      {  
          "name" : "max_node_failure",  
          "type" : "Optional[Integer]",  
          "value" : 1 
      },  
      {  
        "name" : "noop",  
        "type" : "Boolean",  
        "value" : false  
      }, 
      {  
        "name" : "fail_if_no_nodes",  
        "type" : "Boolean",  
        "value" : true  
      } 
    ],  
    "controlRepoId": {  
      "domain": "<workspace ID>",  
      "name": "<project name>"  
    }  
  },  
  "deploymentTarget": {  
    "type": "NODE_GROUP",  
    "nodeGroupId": "<ID of the enviornment node group to deploy to>", 
    "environmentPrefix": ""  
  },  
  "puppetEnterpriseServer": "example-pe",  
  "repoTargetBranch": "<branch to deploy to>",  
  "repoSourceBranch": "<branch to deploy from>",  
  "repoSourceSha": "<SHA of HEAD of branch>"  
}  
EOF  
)"  
type_header='Content-Type: application/json'  
auth_header="Authorization: <API token>"  
uri="https://<CD4PE host>/cd4pe/api/v1/deployments/trigger"  
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Trigger a pipeline

Use the Continuous Delivery for PE API to trigger a pipeline from one of your branches to a Puppet Enterprise environment.

Before you begin
In order to trigger a pipeline, you need to collect the following:
  • The ID of the workspace containing the pipeline you want to trigger
  • The name of the control repo or module whose pipeline you want to trigger
  • The ID of the pipeline belonging to that code project
  • The SHA with which you want to trigger the pipeline

  1. Get the pipeline ID, which are returned in the details for control repos and modules. You can find this using: 
    auth_header="Authorization: <API token>"  
uri="https://<CD4PE host>/cd4pe/api/v1/<control-repos OR modules>/<repo name>?workspaceId=d5" 
curl --insecure --header "$auth_header" --request GET "$uri"
    This returns information about the control repo. For example, it might look similar to the following:
    {  
  "name": "my_control_repo",  
  "srcRepoProvider": "BITBUCKET",  
  "srcRepoOwner": "{a8b34a31-8814-4c5d-aca1-580ee518c290}",  
  "srcRepoName": "my_control_repo",  
  "srcRepoId": "{a8b34a31-8814-4c5d-aca1-580ee518c290}",  
  "srcRepoDisplayName": "my_control_repo",  
  "pipelines": [  
    {  
      "name": "regex",  
      "pipelineId": "e64kq33s04kh05pbxfr6w8e9y"  
    },  
    {  
      "name": "main",  
      "pipelineId": "1jqloxhyphh0w03r8h82i996tr"  
    }  
  ], 
  ... 
}

    From this you can choose which pipeline you want to trigger.

  2. Trigger the pipeline. Once you have collected all the information you need, you can trigger the pipeline. 
    data="$(cat <<EOF  
{  
  "workspaceId": "<workspace ID>",  
  "projectName": "<name of control repo or module>",  
  "sha": "<SHA to run against>"  
}  
EOF  
)"  
type_header='Content-Type: application/json'  
auth_header="Authorization: <API token>"  
uri="https://<cd4pe host>/cd4pe/api/v1/pipelines/<pipeline ID>/trigger"  
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"