Installing Pivotal Platform on Microsoft Azure

Page last updated:

Note: This document describes how to install a basic, opinionated Pivotal Platform on Azure using the Azure Marketplace. To install a more robust Pivotal Platform deployment on Azure for development or production, see Installing Pivotal Platform on Azure.

This topic describes how to deploy Pivotal Platform on Microsoft Azure.

Pivotal Platform on Microsoft Azure is available in Azure Marketplace. The Azure Marketplace offering installs a pre-configured deployment of Pivotal Platform.


Pivotal Platform on Microsoft Azure includes the following components:



You must have the following in order to use Pivotal Platform on Microsoft Azure:

  • A pay-as-you-go subscription on your Azure account.

  • A Pivotal Network account: If you do not already have an account, create one. Retrieve the API token for your profile by performing the following steps:

    1. Sign into the Pivotal Network.
    2. Navigate to your name in the top right and click Edit Profile.
    3. Record the API token located at the bottom of the page.
  • An Azure command line tool installed on your computer.

    • For Linux/Unix/Mac OS X, follow these instructions to install the Azure CLI.
    • For Windows, follow these instructions to install the Azure PowerShell.
  • A JSON-formatted file named azure-credentials.json that contains an Azure Service Principal. If you need an azure-credentials.json file, follow the instructions in Create an Azure Service Principal File below.

  • Sufficient resources for your Azure account. See the installation requirements at Installing Pivotal Platform on Azure.

    For more information, see Azure subscription and service limits, quotas, and constraints. To raise your quota, follow the instructions in Raise Your Quota below.

    Note: The cost per day for Azure resources varies, but it is likely in the $50-75 (US) range.

Create an Azure Service Principal File

The Azure Service Principal is an identity created for an app or script. This identity allows the app or script to authenticate with its own credentials. When you create an Azure Service Principal, make sure to create it with Contributor privileges and scope it to your target resource group. For more information, see the Microsoft documentation.

Follow the steps below to create a JSON-formatted Azure Service Principal file.

  1. Using a text editor, open a new file.

  2. Add the following content to the file: { "subscriptionID": "SUBSCRIPTION-ID", "tenantID": "TENANT-ID", "clientID": "SERVICE-PRINCIPAL-NAME", "clientSecret": "SERVICE-PRINCIPAL-PASSWORD" }

  3. Replace the placeholder text in the file as follows:

    • SUBSCRIPTION-ID: Replace this with your default Azure Subscription ID.
    • TENANT-ID: Replace this with your default Azure Tenant ID.
    • SERVICE-PRINCIPAL-NAME: Replace this with the application ID.
    • SERVICE-PRINCIPAL-PASSWORD: Replace this with the application authentication key.

      To retrieve the application ID and authentication key, see Get application ID and authentication key in the Microsoft Azure documentation.
  4. Save the file as azure-credentials.json.

Raise Your Quota

  • To request a core quota increase, follow these instructions.

  • When filling in the Details section of the Support Request Description, provide the following information to expedite your request, replacing REGION with your region of choice:

“We are preparing to roll out Pivotal Platform from the Azure Marketplace.
We would like to raise our ARM (Azure Resource Manager) core limits.
Requested quantity of ARM Cores: 50
Requested region: REGION
Please fulfill this request as soon as possible.
The request is not temporary.
This will not be a bursting request.
Please allocate 1 TB of standard storage.
VM Types to be used: F1s, F2s, F4s, DS11v2, DS12v2 VM count (minimum):
27 F1s
4 F2s
4 F4s
1 DS11v2
1 DS12v2”

Install Pivotal Platform on Microsoft Azure

  1. Log in to your Microsoft Azure portal.

  2. Select Marketplace from the Azure Dashboard.

    Note: Alternately, navigate to the Pivotal Platform on Azure Marketplace page and click the Get It Now button.

  3. Search for “Pivotal Platform” and select Pivotal Platform on Microsoft Azure. Screenshot of the Ops Manager on Azure Marketplace. The page includes these sections: 'Business Benefits', 'Key Features', and 'Prerequisites'.

  4. Click Create.

  5. Enter the following User Inputs:

    • Storage Account Name Prefix: Installing Pivotal Platform on Microsoft Azure creates a new storage account. Use a unique prefix that contains lower-case letters and numbers and is no more than 10 characters long. For more information, see About Azure storage accounts.
    • SSH public key: You must generate 2048-bit RSA public and private key files.
      • Linux/Unix/Mac OS X: From the command line, run $ ssh-keygen -t rsa -b 2048. Locate your public key in ~/.ssh/ and paste the contents into the parameter sshKeyData.
      • Windows: Download, install, and use PuTTYgen. Locate your public key file and paste the contents into the parameter sshKeyData.
    • Service Principal: Upload the azure-credentials.json file that you created from Prerequisites section.
    • Pivotal Network Token: Enter the API token of your Pivotal Network Account that you recorded in the Prerequisites section.
    • Resource Group: Use a new resource group with a unique name for each new deployment. For more information about Azure resource groups, see Manage Azure resources through portal.
    • Location: Choose which Azure location you want to deploy to. If you requested a quota increase, you must choose the same region that you submitted in your request.
  6. Click OK and review the Summary Page.

  7. Click OK and read the Terms of Use and Privacy Policy.

  8. Click Create to be directed to the main Azure portal page, where a new tile shows the deployment is in progress.

    Note: The tile deployment progress shows completed when the initial jumpbox VM is provisioned. This does not indicate the deployment is complete.

    The full deployment takes approximately 3-4 hours.

  9. Check the Outputs section of the deployment. Azure confirms your quota before deploying Pivotal Platform. Select the new resource group that was created and select the Deployments tab. Then select the specific deployment. If you see this message in the Outputs section of the deployment template CRITICAL Insufficient Quota, Pivotal Platform will NOT deploy, you need to raise your quota. See Raise Your Quota. Screenshot of the Microsoft Template page. The 'SCRIPTOUTPUT' field is highlighted with a red box.

  10. When the deployment is complete, the Outputs section of the deployment displays the Ops Manager FQDN URL along with the Ops Manager login credentials and the jumpbox FQDN URL.

Verify the Pivotal Platform on Microsoft Azure Installation

  1. From your Azure Portal, navigate to Resource Groups and ensure the new Resource Group has been created. Screenshot of the Resource Groups page. The last deployment value is highlighted with a red box.

  2. Find the Ops Manager URL and the admin password:

    1. In the Azure Portal, return to the Outputs section of your deployment.
    2. Navigate to the Ops Manager URL.
    3. Log in with username admin and the password provided in the Outputs.
  3. Log in to Apps Manager:

    1. Find the Apps Manager password by following Logging in to Apps Manager
    2. Find the System Domain needed for the Apps Manager URL:
    3. Navigate to the Ops Manager Installation Dashboard.
    4. Select PAS.
    5. Select Domains.
    6. Copy the System Domain URL, referred to as SYSTEMDOMAINURL below.
    7. Navigate to the URL https://apps.SYSTEMDOMAINURL.
    8. Log in to Apps Manager with the username admin and the password obtained above.
  4. From Apps Manager, verify that your services are running. Screenshot of the Pivotal Apps Manager page. The System tab shows information about your deployment.

Delete a Deployment of Pivotal Platform on Microsoft Azure

To remove the deployment, navigate to your Azure Portal and delete the Resource Group associated with the deployment.


Deployment Fails

Symptom: Deployment fails before the jumpbox VM is created. The Resource Group Events shows an event with a Provisioning State: Failed. The Status Message may show something like:

  "status": "Failed",
  "error": {
    "code": "ResourceDeploymentFailure",
    "message": "The resource operation completed with terminal provisioning state 'Failed'.",
    "details": [
        "code": "VMExtensionProvisioningError",
        "message": "VM has reported a failure when processing extension 'initbootstrap'.
                    Error message: \"Script returned an error.\n---stdout---\nDownload complete.\n
                    Current working dir : /var/lib/waagent/Microsoft.OSTCExtensions.CustomScriptForLinux-\n
                    Sys.Path: ['/usr/share/python-wheels/distlib-0.1.8-py2.py3-none-any.whl',
                    '/usr/lib/python2.7', '/usr/lib/python2.7/plat-x86_64-linux-gnu',
                    '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload',
                    '/usr/local/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages', '']\n
                    \n---errout---\n\rExtracting templates from packages: 61%\r
                    Extracting templates from packages: 100%\nTraceback (most recent call last):\n
                    File \"\", line 165, in <module>\n    check_quota(subscription_id, tenant,
                    client_id, client_secret, location, numofcores)\n  File \"\", line 62, in check_quota\n
                    token = get_token_from_client_credentials(endpoint,client_id,secret)\n
                    File \"\", line 55, in get_token_from_client_credentials\n
                    result = urlopen(request)\n  File \"/usr/lib/python2.7/\", line 127, in urlopen\n
                    return, data, timeout)\n  File \"/usr/lib/python2.7/\", line 410, in open\n
                    response = meth(req, response)\n  File \"/usr/lib/python2.7/\", line 523, in http_response\n
                    'http', request, response, code, msg, hdrs)\n  File \"/usr/lib/python2.7/\", line 448, in error\n
                    return self._call_chain(*args)\n  File \"/usr/lib/python2.7/\", line 382, in _call_chain\n
                    result = func(*args)\n  File \"/usr/lib/python2.7/\", line 531, in http_error_default\n
                    raise HTTPError(req.get_full_url(), code, msg, hdrs, fp)\nurllib2.HTTPError: HTTP Error 400: Bad Request\n\n\"."

Solution: If an HTTP 400 error is shown, the Client-ID or Tentant-ID is incorrect. If an HTTP 401 error is shown, the Client Secret is incorrect. Finally, if quota is insufficient, you see such a message. There is no error code associated with this.

Symptom: Deployment fails after the jumpbox VM has been created.

Solution: Capture the Pivotal Platform deployment log as described in the verification procedure above and send it to with any additional information about the installation that you can provide.