Configuring BOSH Director on GCP Using Terraform

Page last updated:

Warning: Pivotal Operations Manager v2.1 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

Page last updated:

This topic describes how to configure the BOSH Director for Pivotal Cloud Foundry (PCF) on Google Cloud Platform (GCP) after Preparing to Deploy Ops Manager on GCP Using Terraform.

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

Prerequisite

To complete the procedures in this topic, you must have access to the output from when you ran terraform apply to create resources for this deployment. You can view this output at any time by running terraform output. You use the values in your Terraform output to configure the BOSH Director tile.

Step 1: Access Ops Manager

  1. In a web browser, navigate to the fully qualified domain name (FQDN) of the BOSH Director. Use the ops_manager_dns value from running terraform output.

    Note: In order to set up Ops Manager authentication correctly, Pivotal recommends using a Fully Qualified Domain Name (FQDN) to access Ops Manager. Using an ephemeral IP address to access Ops Manager can cause authentication errors upon subsequent access.

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

    Select authentication

Use an Identity Provider (IdP)

  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 log in 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 log in page.

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

    Note: These attributes are case-sensitive.

    • 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 log in 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 Status tab in the BOSH Director. 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-ADDRESS:8443/saml/SSO/alias/BOSH-IP-ADDRESS
    • Audience URI (SP Entity ID): https://BOSH-IP-ADDRESS: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.

Internal Authentication

  1. When redirected to the Internal Authentication page, do the following:

    • 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 lost.
    • If you are using an HTTP proxy or HTTPS proxy, follow the instructions in the Configuring Proxy Settings for the BOSH CPI topic.
    • Read the End User License Agreement, and select the checkbox to accept the terms.
    • Click Setup Authentication.

    Om login

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

    Cf login

Step 2: Google Cloud Platform Config

  1. Click the Google Cloud Platform tile within the Installation Dashboard. Director tile gcp
  2. Select Google Config. Complete the following fields:

    • Project ID: Enter the value of project from your terraform.tfvars file.
    • Default Deployment Tag: Enter the value of env_name from your terraform.tfvars file.
    • Select AuthJSON and in the field below enter the contents of the JSON file for you service account key.

      Note: As an alternative, you can select The Ops Manager VM Service Account option to use the service account automatically created by GCP for the Ops Manager VM.

      Google config
  3. Click Save.

Step 3: Director Config Page

  1. Select Director Config to open the Director Config page.

    Director gcp

  2. In the NTP Servers (comma delimited) field, enter metadata.google.internal.

    Note: To resolve metadata.google.internal as the NTP server hostname, you must provide the two IP addresses for DNS configuration as described in Step 5: Create Networks Page of this procedure.

    Note: The NTP server configuration only updates after VM recreation. Ensure that you select the Recreate all VMs checkbox if you modify the value of this field.

  3. Leave the JMX Provider IP Address field blank.

    Note: Starting from PCF v2.0, BOSH-reported component metrics are available in the Loggregator Firehose by default. Therefore, if you continue to use PCF JMX Bridge for consuming them 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.

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

    Note: Starting from PCF v2.0, BOSH-reported component metrics are available in the Loggregator Firehose by default. Therefore, if you continue to use the BOSH HM Forwarder for consuming them, 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.

  5. Select the Enable VM Resurrector Plugin checkbox to enable the Ops Manager Resurrector functionality and increase Pivotal Application Service (PAS) availability.

  6. (Optional) 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: You must enable post-deploy scripts to install PKS.

  7. (Optional) 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 for Ops Manager to retry failed BOSH operations up to five times.

  9. (Optional) Select Keep Unreachable Director VMs if you want to preserve BOSH Director VMs after a failed deployment for troubleshooting purposes.

  10. (Optional) 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.
  11. (Optional) 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.
  12. 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 as 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 could 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 from 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 don’t 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.

  13. 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 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 from 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. 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 in Ops Manager.
      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 the Authenticating Requests documentation.

    • GCS Blobstore: Select this option to use an external Google Cloud Storage (GCS) endpoint. To create a GCS bucket, follow the procedures in Creating Storage Buckets. 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: Enter the contents of the JSON file that you downloaded in the Set up an IAM Service Account section of Preparing to Deploy Ops Manager on GCP Manually.

  14. For Database Location, if you configured your terraform.tfvars file to create an external database for Ops Manager, select External MySQL Database and complete the fields below. Otherwise, select Internal.

    • Host: Enter the value of sql_db_ip from your Terraform output.
    • Port: Enter 3306.
    • Username: Enter the value of opsman_sql_username from your Terraform output.
    • Password: Enter the value of opsman_sql_password from your Terraform output.
    • Database: Enter the value of opsman_sql_db_name from your Terraform output.
  15. (Optional) Modify the Director Workers value, which sets the number of workers available to execute Director tasks. This field defaults to 5.

  16. (Optional) Max Threads sets the maximum number of threads that the BOSH Director can run simultaneously. Pivotal recommends that you leave the field blank to use the default value, unless doing so results in rate limiting or errors on your IaaS.

  17. (Optional) To add a custom URL for your BOSH Director, enter a valid hostname in Director Hostname. You can also use this field to configure a load balancer in front of your BOSH Director.

    WARNING: In Ops Manager v2.1.17 and earlier, if you change the Director Hostname after your initial deployment, VMs become unavailable. This causes PCF downtime. To restore VM availability, enable Recreate All VMs and redeploy. This issue is resolved in Ops Manager v2.1.18 and later.

    Director workers

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

  19. (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 Service Discovery for Application Containers in the Pivotal Application Service (PAS) Release Notes.

    Note: Disabling BOSH DNS affects Step 5: Create Networks Page below when you configure your network DNS. You must first navigate to your PAS tile and enter 8.8.8.8 into the DNS Servers field.

    Breaking Change: Do not disable BOSH DNS without consulting Pivotal Support. For more information about disabling BOSH DNS, see Disabling or Opting Out of BOSH DNS in PCF in the Pivotal Knowledge Base.

  20. (Optional) To set a custom banner that users see when logging in to the Director using SSH, enter text in the Custom SSH Banner field. Disable bosh dns

  21. Click Save.

Step 4: Create Availability Zones Page

Note: Pivotal recommends at least three availability zones for a highly available installation of PAS. For an example of a three availability zone deployment, see Reference Architecture for Pivotal Cloud Foundry on GCP.

  1. Select Create Availability Zones.

  2. Use the Add button to add three availability zones corresponding to those listed in the azs field in your Terraform output.

  3. Click Save.

Step 5: Create Networks Page

  1. Select Create Networks.

  2. Make sure Enable ICMP checks is not selected. GCP routers do not respond to ICMP pings.

  3. Use the Add Network button to create the following three networks:

    Note: To use a shared VPC network, enter the shared VPC host project name before the network name in the format VPC-PROJECT-NAME/NETWORK-NAME/SUBNET-NAME/REGION-NAME. For example, vpc-project/opsmgr/central/us-central1. For more information, see Configuring a Shared VPC on GCP.

    Note: If you disabled BOSH DNS, enter 8.8.8.8 into the DNS Servers field of the PAS tile. For more information, see step 29g in the Configure Networking section of the Deploying PAS on GCP Using Terraform topic.

    Infrastructure Network

    Network Name infrastructure
    Google Network Name Use the network_name, infrastructure_subnet_name, and region fields from your Terraform output to enter the name of the infrastructure network created by Terraform.
    The format is: network_name/infrastructure_subnet_name/region
    CIDR Enter the value of infrastructure_subnet_cidrs from your Terraform output.
    Reserved IP Ranges Enter the first .1 through .9 addresses from the CIDR. For example, if the CIDR is 192.168.101.0/26, enter the range 192.168.101.1-192.168.101.9.
    DNS 169.254.169.254
    Gateway Enter the value of infrastructure_subnet_gateway from your Terraform output.
    Availability Zones Select all three availability zones.

    Runtime Network

    Network Name pas
    Google Network Name Use the network_name, pas_subnet_name, and region fields from your Terraform output to enter the name of the PAS network created by Terraform.
    The format is: network_name/pas_subnet_name/region
    CIDR Enter the value of pas_subnet_cidrs from your Terraform output.
    Reserved IP Ranges Enter the first .1 through .9 addresses from the CIDR. For example, if the CIDR is 192.168.16.0/22, enter the range 192.168.16.1-192.168.16.9.
    DNS 169.254.169.254
    Gateway Enter the value of pas_subnet_gateway from your Terraform output.
    Availability Zones Select all three availability zones.

    Services Network

    Network Name services
    Google Network Name Use the network_name, services_subnet_name, and region fields from your Terraform output to enter the name of the services network created by Terraform.
    The format is: network_name/services_subnet_name/region
    CIDR Enter the value of services_subnet_cidrs from your Terraform output.
    Reserved IP Ranges Enter the first .1 through .9 addresses from the CIDR. For example, if the CIDR is 192.168.16.0/22, enter the range 192.168.20.1-192.168.20.9.
    DNS 169.254.169.254
    Gateway Enter the value of services_subnet_gateway from your Terraform output.
    Availability Zones Select all three availability zones.

    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.

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

  3. Under Network, select the infrastructure 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 on running app instances in PAS using Docker Registries.

  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

  1. Select Syslog. Syslog bosh

  2. (Optional) To send BOSH Director system logs to a remote server, select Yes.

  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.

  2. Verify that the Internet Connected checkbox for every job is checked. The Terraform templates do not provision a Network Address Translation (NAT) box for Internet connectivity to your VMs so instead they will be provided with ephemeral public IP addresses to allow the jobs to reach the Internet.

    Note: If you want to provision a Network Address Translation (NAT) box to provide Internet connectivity to your VMs instead of providing them with public IP addresses, deselect the Internet Connected checkboxes. For more information about using NAT in GCP, see the GCP documentation.

Note: If you install PAS for Windows, provision your Master Compilation Job with at least 100 GB of disk space.

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. If the following ICMP error message appears, return to the Network Config screen, and make sure you have deselected the Enable ICMP Checks box. Then click Apply Changes again.

    Install error

  3. BOSH Director installs. This may take a few moments. When the installation process successfully completes, the Changes Applied window appears.

    Ops manager complete

What to Do Next

After you complete this procedure, follow the instructions in the Deploying PAS on GCP topic.