Configuring BOSH Director on vSphere

Page last updated:

This topic describes how to configure the BOSH Director for VMware vSphere.

See Installing Runtimes for more information about Pivotal Cloud Foundry (PCF) runtimes.

Note: You can also perform the procedures in this topic using the Ops Manager API. For more information, see Using the Ops Manager API.

Step 1: Set Up Ops Manager

  1. In a web browser, navigate to the fully qualified domain of your Ops Manager.

  2. When Ops Manager starts for the first time, you must choose one of the following:

    Select authentication

Use an Identity Provider

  1. Log in to your IdP console and download the IdP metadata XML. Optionally, if your IdP supports metadata URL, you can copy the metadata URL instead of the XML.

  2. Copy the IdP metadata XML or URL to the Ops Manager Use an Identity Provider login page. Meta om

    Note: The same IdP metadata URL or XML is applied for the BOSH Director. If you use a separate IdP for BOSH, copy the metadata XML or URL from that IdP and enter it into the BOSH IdP Metadata text box in the Ops Manager login page.

  3. Enter values for the fields listed below. Failure to provide values in these fields results in a 500 error.

    • SAML admin group: Enter the name of the SAML group that contains all Ops Manager administrators.
    • SAML groups attribute: Enter the groups attribute tag name with which you configured the SAML server.
  4. Enter your Decryption passphrase. Read the End User License Agreement, and select the checkbox to accept the terms.

  5. Your Ops Manager login page appears. Enter your username and password. Click Login.

  6. Download your SAML Service Provider metadata (SAML Relying Party metadata) by navigating to the following URLs:

    • 6a. Ops Manager SAML service provider metadata: https://OPS-MAN-FQDN:443/uaa/saml/metadata
    • 6b. BOSH Director SAML service provider metadata: https://BOSH-IP-ADDRESS:8443/saml/metadata

      Note: To retrieve your BOSH-IP-ADDRESS, navigate to the BOSH Director tile > Status tab. Record the BOSH Director IP address.

  7. Configure your IdP with your SAML Service Provider metadata. Import the Ops Manager SAML provider metadata from Step 6a above to your IdP. If your IdP does not support importing, provide the values below.

    • Single sign on URL: https://OPS-MAN-FQDN:443/uaa/saml/SSO/alias/OPS-MAN-FQDN
    • Audience URI (SP Entity ID): https://OP-MAN-FQDN:443/uaa
    • Name ID: Email Address
    • SAML authentication requests are always signed
  8. Import the BOSH Director SAML provider metadata from Step 6b to your IdP. If the IdP does not support an import, provide the values below.

    • Single sign on URL: https://BOSH-IP:8443/saml/SSO/alias/BOSH-IP
    • Audience URI (SP Entity ID): https://BOSH-IP:8443
    • Name ID: Email Address
    • SAML authentication requests are always signed
  9. Return to the BOSH Director tile, and continue with the configuration steps below.

Note: For an example of configuring SAML integration between Ops Manager and your IdP, see Configuring Active Directory Federation Services as an Identity Provider.

Use Internal Authentication

  1. When redirected to the Internal Authentication page, you must complete the following steps:

    • Enter a Username, Password, and Password confirmation to create an Admin user.
    • Enter a Decryption passphrase and the Decryption passphrase confirmation. This passphrase encrypts the Ops Manager datastore, and is not recoverable.
    • If you are using an HTTP proxy or HTTPS proxy, follow the instructions in Configuring Proxy Settings for the BOSH CPI.
    • Read the End User License Agreement, and select the checkbox to accept the terms.
    • Click Setup Authentication.

    Om login

Step 2: vCenter Configs Page

  1. Log in to Ops Manager with the Admin username and password you created in the previous step.

    Cf login

  2. Click the BOSH Director tile.

    Director tile vmware

  3. Select vCenter Configs.

    Vcenter config

  4. Enter the following information:

    • Name: A name you provide for your vCenter configuration.
    • vCenter Host: The hostname of the vCenter that manages ESXi/vSphere.
    • vCenter Username: A vCenter username with create and delete privileges for virtual machines (VMs) and folders.
    • vCenter Password: The password for the vCenter user specified above.
    • Datacenter Name: The name of the datacenter as it appears in vCenter.
    • Virtual Disk Type: The Virtual Disk Type to provision for all VMs. For guidance about the virtual disk type to select, see Provisioning a Virtual Disk in vSphere.

      Note: The following fields do not allow whitespace. Including whitespace characters in datastore or datastore folder names causes an error.

    • Ephemeral Datastore Names (comma delimited): The names of the datastores that store ephemeral VM disks deployed by Ops Manager.
    • Persistent Datastore Names (comma delimited): The names of the datastores that store persistent VM disks deployed by Ops Manager.
    • VM Folder: The vSphere datacenter folder where Ops Manager places VMs. This defaults to pcf_vms.
    • Template Folder: The vSphere datacenter folder where Ops Manager places VMs. This defaults to pcf_templates.
    • Disk path Folder: The vSphere datastore folder where Ops Manager creates attached disk images. This defaults to pcf_disk. You must not nest this folder.
  5. Select a network configuration from one of the following:

    • Standard vCenter Networking: This is the default option when upgrading Ops Manager.
    • NSX Networking: Select this option to enable VMware NSX Network Virtualization.

    Nsxdirectorconfig

  6. Configure NSX networking by entering the following information:

    • NSX Mode: Select either NSX-V or NSX-T.
    • NSX Address: The address of the NSX manager.
    • NSX Username: The username to connect to the NSX manager.
    • NSX Password: The password for the username specified above.
    • NSX CA Cert: A CA certificate in PEM format that authenticates to the NSX server. If the NSX Manager generated a self-signed certificate, use the following command to retrieve the CA certificate using OpenSSL: openssl s_client -showcerts -connect NSX-MANAGER-ADDRESS:443 < /dev/null 2> /dev/null | openssl x509

      Note: To update NSX security group and load balancer information, see Updating NSX Security Group and Load Balancer Information.

  7. Click Save.

    Note: After your initial deployment, you cannot edit the VM Folder, Template Folder, and Disk path Folder names.

  8. (Optional) Click Add vCenter Config toward the top of the form to configure additional vCenters. Once you click Save, your multiple vCenter Configs are listed in the vCenter Configs pane. For more information about multiple vCenter configs, see Adding Multiple vSphere vCenters.

Step 3: Director Config Page

  1. Select Director Config.

    Vsphere director

  2. In the NTP Servers (comma delimited) field, enter your NTP server addresses.

  3. Leave the JMX Provider IP Address field blank.

    Note: Starting in PCF v2.0, BOSH-reported component metrics are available in the Loggregator Firehose by default. If you continue to use PCF JMX Bridge to consume these component metrics outside of the Firehose, you may receive duplicate data. To prevent this, leave the JMX Provider IP Address field blank. For additional guidance, see BOSH System Metrics Available in Loggregator Firehose in the PCF v2.0 Release Notes.

  4. Leave the Bosh HM Forwarder IP Address field blank.

    Note: Starting in PCF v2.0, BOSH-reported component metrics are available in the Loggregator Firehose by default. If you continue to use the BOSH HM Forwarder to consume these component metrics, you may receive duplicate data. To prevent this, leave the Bosh HM Forwarder IP Address field blank. For additional guidance, see BOSH System Metrics Available in Loggregator Firehose in the PCF v2.0 Release Notes.

  5. Select the Enable VM Resurrector Plugin to enable Ops Manager Resurrector functionality. If you install PAS, selecting Enable VM Resurrector Plugin also increases availability in your deployment. For more information, see Using Ops Manager Resurrector on VMware vSphere.

  6. Select Enable Post Deploy Scripts to run a post-deploy script after deployment. This script allows the job to execute additional commands against a deployment.

    Note: If you deploy Pivotal Container Service (PKS), you must enable post-deploy scripts.

  7. Select Recreate all VMs to force BOSH to recreate all VMs on the next deploy. This process does not destroy any persistent disk data.

  8. Select Enable bosh deploy retries to instruct Ops Manager to retry failed BOSH operations up to five times.

  9. (Optional) Disable Allow Legacy Agents if all of your tiles have stemcells v3468 or later. Disabling the field will allow Ops Manager to implement TLS secure communications.

  10. Select Keep Unreachable Director VMs if you want to preserve BOSH Director VMs after a failed deployment for troubleshooting purposes.

  11. Select HM Pager Duty Plugin to enable Health Monitor integration with PagerDuty. Director hm pager

    • Service Key: Enter your API service key from PagerDuty.
    • HTTP Proxy: Enter an HTTP proxy for use with PagerDuty.
  12. Select HM Email Plugin to enable Health Monitor integration with email. Director hm email

    • Host: Enter your email hostname.
    • Port: Enter your email port number.
    • Domain: Enter your domain.
    • From: Enter the address for the sender.
    • Recipients: Enter comma-separated addresses of intended recipients.
    • Username: Enter the username for your email server.
    • Password: Enter the password for your email server.
    • Enable TLS: Select this checkbox to enable Transport Layer Security.
  13. For CredHub Encryption Provider, you can choose whether BOSH CredHub stores its encryption key internally on the BOSH Director and CredHub VM, or in an external hardware security module (HSM). The HSM option is more secure.

    Before configuring an HSM encryption provider in the Director Config pane, you must follow the procedures and collect information described in Preparing CredHub HSMs for Configuration.

    Note: After you deploy Ops Manager with an HSM encryption provider, you cannot change BOSH CredHub to store encryption keys internally.

    CredHub Encryption Provider options in the Director Config pane

    • Internal: Select this option for internal CredHub key storage. This option is selected by default and requires no additional configuration.
    • Luna HSM: Select this option to use a SafeNet Luna HSM as your permanent CredHub encryption provider, and fill in the following fields:
      1. Encryption Key Name: Any name to identify the key that the HSM uses to encrypt and decrypt the CredHub data. Changing this key name after you deploy Ops Manager can cause service downtime.
      2. Provider Partition: The partition that stores your encryption key. Changing this partition after you deploy Ops Manager could cause service downtime. For this value and the ones below, use values gathered in Preparing CredHub HSMs for Configuration.
      3. Provider Partition Password
      4. Provider Client Certificate: The certificate that validates the identity of the HSM when CredHub connects as a client.
      5. Provider Client Certificate Private Key
      6. HSM Host Address
      7. HSM Port Address: If you do not know your port address, enter 1792.
      8. Partition Serial Number
      9. HSM Certificate: The certificate that the HSM presents to CredHub to establish a two-way mTLS connection.

  14. Select a Blobstore Location to either configure the blobstore as an internal server or an external endpoint. Because the internal server is unscalable and less secure, Pivotal recommends that you configure an external blobstore.

    Note: After you deploy Ops Manager, you cannot change the blobstore location.

    Blobstore location options in the Director Config pane

    • Internal: Select this option to use an internal blobstore. Ops Manager creates a new VM for blob storage. No additional configuration is required.
    • S3 Compatible Blobstore: Select this option to use an external S3-compatible endpoint. Follow the procedures in Sign up for Amazon S3 and Creating a Bucket in the AWS documentation. When you have created an S3 bucket, complete the following steps:
      1. S3 Endpoint: Navigate to the Regions and Endpoints topic in the AWS documentation.
        1. Locate the endpoint for your region in the Amazon Simple Storage Service (S3) table and construct a URL using your region’s endpoint. For example, if you are using the us-west-2 region, the URL you create would be https://s3-us-west-2.amazonaws.com. Enter this URL into the S3 Endpoint field.
        2. On a command line, run ssh ubuntu@OPS-MANAGER-FQDN to SSH into the Ops Manager VM. Replace OPS-MANAGER-FQDN with the fully qualified domain name of Ops Manager.
        3. Copy the custom public CA certificate you used to sign the S3 endpoint into /etc/ssl/certs on the Ops Manager VM.
        4. On the Ops Manager VM, run sudo update-ca-certificates -f -v to import the custom CA certificate into the Ops Manager VM truststore.

          Note: You must also add this custom CA certificate into the Trusted Certificates field in the Security page. See Complete the Security Page for instructions.

      2. Bucket Name: Enter the name of the S3 bucket.
      3. Access Key and Secret Key: Enter the keys you generated when creating your S3 bucket.
      4. Select V2 Signature or V4 Signature. If you select V4 Signature, enter your Region.

        Note: AWS recommends using Signature Version 4. For more information about AWS S3 Signatures, see Authenticating Requests in the AWS documentation.

    • Enable TLS: Select this checkbox to enable TLS.

      Note: If you are using Linux stemcells, make sure you have configured Linux stemcell v3586.16 or later for all tiles before enabling TLS.

      Note: If you are using PAS for Windows 2016, make sure you have configured Windows stemcell v1709.10 or later for all tiles before enabling TLS.

    • GCS Blobstore: Select this option to use an external GCS endpoint. To create a GCS bucket, you must have a GCS account. Follow the procedures in Creating Storage Buckets in the GCS documentation to create a GCS bucket. When you have created a GCS bucket, complete the following steps:
      1. Bucket Name: Enter the name of your GCS bucket.
      2. Storage Class: Select the storage class for your GCS bucket. See Storage Classes in the GCP documentation for more information.
      3. Service Account Key: Follow the steps in the Set Up an IAM Service Account section of Preparing to Deploy PCF on GCP to download a JSON file with a private key. Enter the contents of the JSON file into the field.

  15. Select a Database Location. By default, PCF deploys and manages an Internal database for you. If you choose to use an External MySQL Database, complete the associated fields with information obtained from your external MySQL Database provider: Host, Port, Username, Password, and Database. Director database In addition, if you selected the Enable TLS for Director Database checkbox, you can complete the following optional fields:

    • Enable TLS: Select this checkbox enables TLS communication between the BOSH Director and the database.
    • TLS CA: Enter the Certificate Authority for the TLS Certificate.
    • TLS Certificate: Enter the client certificate for mutual TLS connections to the database.
    • TLS Private Key: Enter the client private key for mutual TLS connections to the database.
  16. (Optional) Director Workers: Set the number of workers available to execute Director tasks. This field defaults to 5.

  17. (Optional) Max Threads: Enter the number of operations the BOSH Director can perform simultaneously. For vSphere, the default value is 32. Leave the field blank to use this default value. Pivotal recommends that you use the default value unless doing so results in rate limiting or errors on your IaaS.

  18. (Optional) Director Hostname: Enter a valid hostname to add a custom URL for your BOSH Director. You can also use this field to configure a load balancer in front of your BOSH Director. For more information, see How to Set Up a Load Balancer in Front of Operations Manager Director in the Pivotal Support documentation.

  19. (Optional) Enter your list of comma-separated Excluded Recursors to declare which IP addresses and ports should not be used by the DNS server.

  20. (Optional) To disable BOSH DNS, select the Disable BOSH DNS server for troubleshooting purposes checkbox. For more information about the BOSH DNS service discovery mechanism, see BOSH DNS Enabled by Default in the Ops Manager v2.2 Release Notes.

    Breaking Change: Do not disable BOSH DNS without consulting Pivotal Support.

    Note: If you plan to deploy PKS, do not disable BOSH DNS. If PAS and PKS run on the same instance of Ops Manager, you cannot use the opt-out feature of BOSH DNS for your PAS without breaking PKS. To opt out of BOSH DNS in your PAS deployment, install the tile on a separate instance of Ops Manager.

  21. (Optional) Custom SSH Banner: Enter text to set a custom banner that users see when logging in to the Director using SSH.

    Disable bosh dns

  22. (Optional) Enter your comma-separated custom Identification Tags. For example, iaas:foundation1, hello:world. You can use the tags to identify your foundation when viewing VMs or disks from your IaaS.

  23. Click Save.

Note: After your initial deployment, you cannot edit the Blobstore and Database locations.

Step 4: Create Availability Zone Page

An Ops Manager availability zone (AZ) corresponds to your vCenter clusters and resource pools.

Multiple AZs allow you to provide high-availability and load balancing to your applications. When you run more than one instance of an application, Ops Manager balances those instances across all of the AZs assigned to the application.

Pivotal recommends that you use at least three AZs for a highly available installation of your chosen runtime.

  1. Select Create Availability Zones to navigate to the pane.

    The 'Create Availability Zones' pane shows a list of two availability zones: 'first-az' and 'second-az' with a button to the right to 'Add'. The 'first-az' is expanded and shows the fields 'Name' and 'IaaS Configuration'. Below that, still in the expanded 'first-az', a subhead called 'Clusters' lists a group of two fields, 'Cluster' and 'Resource Pool' with a button to the right to 'Add Cluster'.

  2. Use the following steps to create one or more AZs for your applications to use:

    • Click Add.
    • Enter a unique Name for the AZ.
    • Select a vCenter config name from the IaaS Configuration dropdown to associate your AZ with a vCenter. If you have only one vCenter config or if you are creating your first AZ, IaaS Configuration defaults to the first vCenter and cannot be configured.
    • Enter the name of an existing vCenter Cluster to use as an AZ.
    • (Optional) Enter the name of a Resource Pool in the vCenter cluster that you specified above. The jobs running in this AZ share the CPU and memory resources defined by the pool.
    • (Optional) Click Add Cluster to create another set of Cluster and Resource Pool fields. You can add multiple clusters. Click the trash icon to delete a cluster. The first cluster cannot be deleted.

      Note: For more information about using availability zones in vSphere, see Understanding Availability Zones in VMware Installations.

  3. Click Save.

Step 5: Create Networks Page

  1. Select Create Networks.

    Create network

  2. Select Enable ICMP checks to enable ICMP on your networks. Ops Manager uses ICMP checks to confirm that components within your network are reachable.

  3. Use the following steps to create one or more Ops Manager networks:

    • Click Add Network.
    • Enter a unique Name for the network.
    • Click Add Subnet to create one or more subnets for the network.
    • Enter the full path and vSphere Network Name as it displays in vCenter. For example, enter YOUR-DIRECTORY-NAME/YOUR-NETWORK-NAME. If your vSphere Network Name contains a forward slash character, replace the forward slash with the URL-encoded forward slash character %2f.
    • For CIDR, enter a valid CIDR block in which to deploy VMs. For example, enter 192.0.2.0/24.
    • For Reserved IP Ranges, enter any IP addresses from the CIDR that you want to blacklist from the installation. Ops Manager will not deploy VMs to any address in this range.
    • Enter your DNS and Gateway IP addresses.
    • Select which Availability Zones to use with the network.
  4. Click Save.

    Note: Multiple networks allow you to place vCenter on a private network and the rest of your deployment on a public network. Isolating vCenter in this manner denies access to it from outside sources and reduces possible security vulnerabilities.

    Note: If you use the Cisco Nexus 1000v Switch, see to Using the Cisco Nexus 1000v Switch with Ops Manager for more information.

    Note: After you deploy Ops Manager, you add subnets with overlapping Availability Zones to expand your network. For more information about configuring additional subnets, see Expanding Your Network with Additional Subnets.

Step 6: Assign AZs and Networks Page

  1. Select Assign AZs and Networks. Assign az

  2. Use the dropdown to select a Singleton Availability Zone. The BOSH Director installs in this Availability Zone.

  3. Use the dropdown to select a Network for your BOSH Director.

  4. Click Save.

Step 7: Security Page

  1. Select Security.

    Om security

  2. In Trusted Certificates, enter your custom certificate authority (CA) certificates to insert into your organization’s certificate trust chain. This feature enables all BOSH-deployed components in your deployment to trust custom root certificates.

    To enter multiple certificates, paste your certificates one after the other. For example, format your certificates like the following:

    -----BEGIN CERTIFICATE-----
    ABCDEFGH12345678ABCDEFGH12345678ABCDEFGH12345678AB
    EFGH12345678ABCDEFGH12345678ABCDEFGH12345678ABCDEF
    GH12345678ABCDEFGH12345678ABCDEFGH12345678...
    ------END CERTIFICATE------
    -----BEGIN CERTIFICATE-----
    BCDEFGH12345678ABCDEFGH12345678ABCDEFGH12345678ABB
    EFGH12345678ABCDEFGH12345678ABCDEFGH12345678ABCDEF
    GH12345678ABCDEFGH12345678ABCDEFGH12345678...
    ------END CERTIFICATE------
    -----BEGIN CERTIFICATE-----
    CDEFGH12345678ABCDEFGH12345678ABCDEFGH12345678ABBB
    EFGH12345678ABCDEFGH12345678ABCDEFGH12345678ABCDEF
    GH12345678ABCDEFGH12345678ABCDEFGH12345678...
    ------END CERTIFICATE------

    Note: If you want to use Docker Registries for running app instances in Docker containers, enter the certificate for your private Docker Registry in this field. See Using Docker Registries for more information.

  3. Choose Generate passwords or Use default BOSH password. Pivotal recommends that you use the Generate passwords option for greater security.

  4. Click Save. To view your saved Director password, click the Credentials tab.

Step 8: Syslog Page

Note: BOSH Director logs contain sensitive information that should be considered privileged. For example, these logs may contain cloud provider credentials. If you choose to forward logs to an external syslog endpoint, use TLS encryption to prevent information from being intercepted by a third party.

  1. Select Syslog. Syslog bosh

  2. (Optional) Select Yes to send BOSH Director system logs to a remote server.

  3. In the Address field, enter the IP address or DNS name for the remote server.

  4. In the Port field, enter the port number that the remote server listens on.

  5. In the Transport Protocol dropdown menu, select TCP, UDP, or RELP. This selection determines which transport protocol is used to send the logs to the remote server.

  6. (Optional) Pivotal strongly recommends that you enable TLS encryption when forwarding logs as they may contain sensitive information. For example, these logs may contain cloud provider credentials. To enable TLS, perform the following steps.

    • In the Permitted Peer field, enter either the name or SHA1 fingerprint of the remote peer.
    • In the SSL Certificate field, enter the SSL certificate for the remote server.
  7. Click Save.

Step 9: Resource Config Page

  1. Select Resource Config.

    Vsphere om resources

  2. Adjust any values as necessary for your deployment. Under the Instances, Persistent Disk Type, and VM Type fields, choose Automatic from the dropdown to allocate the recommended resources for the job. If the Persistent Disk Type field reads None, the job does not require persistent disk space.

    Note: Ops Manager requires a Director VM with at least 8 GB memory.

    Note: If you set a field to Automatic and the recommended resource allocation changes in a future version, Ops Manager automatically uses the updated recommended allocation.

  3. Click Save.

Step 10: (Optional) Add Custom VM Extensions

Use the Ops Manager API to add custom properties to your VMs such as associated security groups and load balancers. For more information, see Managing Custom VM Extensions.

Step 11: Complete the BOSH Director Installation

  1. Click the Installation Dashboard link to return to the Installation Dashboard.

  2. Click Apply Changes on the right navigation.

  3. After you complete this procedure, follow the instructions in Deploying PAS on vSphere.

Create a pull request or raise an issue on the source for this page in GitHub