Pivotal Cloud Foundry discovery

The ServiceNow Discovery application finds Pivotal Cloud Foundry (PCF) version 3 components using the Pivotal Cloud Foundry pattern. Discovering some of these resources may require updating to the latest version of the Discovery and Service Mapping Patterns application from the ServiceNow Store.

You can use this pattern on the ServiceNow AI Platform starting Kingston version.

The discovery of PCF V3 components is supported when the Discovery and Service Mapping Patterns plugin Version 1.0.99, March 2023 is installed. The Pattern continues to support the discovery of PCF V2 components.

Request apps on the Store

Visit the ServiceNow Store website to view all the available apps and for information about submitting requests to the store. For cumulative release notes information for all released apps, see the ServiceNow Store version history release notes.

Prerequisites

Pivotal Cloud Foundry credentials

Create the Pivotal Cloud Foundry credentials.

1. Navigate to Discovery > Credentials.
2. Select New.
3. Select CloudFoundry Credentials.
4. On the form, fill in the fields:

   Field	Description
   Name	Credential name. As an example, pcf_user credentials
   Active	Option for enabling this credential for discovery. Select this check box to enable discovery.
   Applies to	Credentials that you may or may not want to apply to All MID servers in your network, or to one or more Specific MID servers. Select Specific MID servers.
   Order	Order in which the platform tries this credential as it tries to log in to devices. A smaller number indicates that the credential seems higher in the list. Establish the credential order when using large numbers of credentials or when security locks out users after three failed logins tries. If all the credentials have the same order number, or none, the instance tries the credentials in a random order. The default value is 100.
   User name	Name of the user of these credentials. Avoid leading or trailing spaces in user names. A warning seems if the platform detects leading or trailing spaces in the user name. An example is pcf_user. Use the client_id that is used to generate the JWT token.
   Password	Password for the user of these credentials. Use the client_secret that is used to generate the JWT token.
   Credential alias	Alternate name for these credentials. As an example, cf If this field is closed, select the unlock icon to unlock the field.

5. Select Update.

JSON web token credentials

To verify the JSON web token (JWT), perform the following token validation steps.

The format of the JWT token is: https://docs.cloudfoundry.org/api/uaa/version/4.27.0/index.html#jwt-bearer-token-grant

1. Run the following cURL script against the User Account and Authentication (UAA) server API and verify the results:

   curl -s -k https://ip_address:port/oauth/token -X; POST -H ”Content-Type: application/x-www-form-urlencoded” -H “Accept: application/json” -d “client_id=<INSERT_USER_HERE>&client_secret=<INSERT_PASS_HERE>&grant_type=client_credentials&token_format=jwt&response_type=token”

   If this command doesn’t generate a token, verify that the credentials in the ServiceNow repository are correct, otherwise go to step 2.

2. Run the following cURL script against Pivotal Cloud Foundry API:

   curl https://ip_address:port/v3/spaces -k -v -H “Accept: application/json” -H “Authorization: bearer<INSERT TOKEN HERE>”

   If this command doesn’t retrieve the PCF spaces information, verify the credentials on the ServiceNow credentials repository.

Credentials for V3 API elements

Provide a read-only user with permission to use the following API elements:

• –/v3/organizations
• –/v3/spaces
• –/v3/domains
• –/v3/routes
• –/v3/organization_quotas
• –/v3/space_quotas
• –/v3/apps
• -/v3/service_offerings
• -/v3/service_plans
• -/v3/service_instances
• -/v3/droplets

Note:

The Pivotal Cloud Foundry Pattern also supports the PCF V2 APIs.

Create a serverless Discovery schedule

1. Navigate to Discovery > Discovery Schedules.
2. Select New.
3. On the form, fill in the fields:

   Table 1. Discovery Schedule form

   Field	Description
   Name	Enter a unique and descriptive name for this Discovery schedule, for example, pcf
   Discover	For the Discover type, select Serverlesss
   MID Server	MID Servers that the credentials apply to. Specify the required MID Server, for example, Discovery_Server
   Active	Option for enabling this credential for discovery. Select this check box to enable discovery.
   Credential alias	Alternate name for these credentials. Use the alias related with the Pivotal Cloud Foundry credentials that you created earlier.

4. Right-click the header of the Discovery Schedule form and select Save.

   

5. Select the Serverless Execution Patterns tab.
6. Select New.
7. On the form, fill in the fields:

   Table 2. Serverless Execution Pattern form

   Field	Description
   Name	Enter a unique and descriptive name for this Serverless Execution Pattern, for example, pcf1
   Pattern	Select CloudFoundry.
   Proxy Host	Fully qualified domain name of the machine on which you’re installing the proxy server. Specify Global.
   Active	Check box to enable this schedule for discovery. Select this check box.

8. Right-click the header of the Serverless Execution Patterns form and select Save.
9. Select the Serverless Execution Patterns tab
10. Create and define the serverless execution pattern as described in the product documentation.
    Configure the parameters required by the Pivotal Cloud Foundry Pattern as follows:

    Table 3. Discovery Pattern Launcher parameters

    Parameter	Description
    Organization	Name of the organization that is required to be discovered, or all where the input is “*”.
    CredentialAlias	Alternate name for these credentials. Use the alias related with the Pivotal Cloud Foundry credentials that you created earlier.
    URL_CF	API URL of the Cloud Controller that is used to retrieve the information from Pivotal Cloud Foundry.
    URL_CF_AUTH	UAA server API​that is used to generate the token. Enter the value in the format: https://uaa.sys.dev.phx.pcf.example.com/oauth/token

11. Update.
12. To start discovery, navigate to the Serverless Discovery definition and select Discover Now.

EVAL closure functions

Use the following EVAL closure functions to concatenate all organizations with “,” as a separator.

var rtrn = ’’;
var organizations = ${organizations[*].name};
var beforeReturn = ’’;
var separator = ’’;
for (var i = 0; i < organizations.size(); i++)   
	{
	beforeReturn += separator + organizations.get(i);  
	separator = ',';   
	}
rtrn = beforeReturn;

Use the following EVAL closure functions to return 1 if the operational status is active and 2 if it isn’t active.

var rtrn = '';
var currentOrgStatus = ${organizations[].operational_status};
var status = currentOrgStatus.toLowerCase();
if(status == "active"){  
   rtrn = "1";  
}
else { 
   rtrn = "2";
}

Use the following EVAL closure function to return 1 if the operational status is started and 2 if it isn’t started.

var rtrn = '';
var currentAppStatus = ${apps[].state};
var status = currentAppStatus.toLowerCase();
if(status == "started"){
   rtrn = "1";  
}
else {   
   rtrn = "2";   
}

CloudFoundry Get Call

The CloudFoundry Get Call custom operation handles the generation of tokens. It uses the credentials and URL_CF_AUTH context variable to generate a token that is used to create API calls.

When a token is generated, the URL_CF is used to create the API calls defined in the Resource field. The custom operation also handles pagination where the response has more than one page.

CloudFoundry Get Call parses the input JSON to populate the tables and variables.

Pivotal Cloud Foundry BOSH extension section

The Pivotal Cloud Foundry BOSH is an extension section of the Pivotal Cloud Foundry Pattern.

The extension is available on the ServiceNow® Store for the June 2023 release of Discovery and Service Mapping Patterns 1.6.0.

Requirements for Pivotal Cloud Foundry BOSH

Note:

The following requirements are relevant only to the BOSH extension section.

The Opsman authentication URL has to be provided as a pattern parameter with the name URL_OPSMAN_AUTH. For example: https://<opsman entry point>/uaa/oauth/token

The added credentials must have permission to execute the following APIs:

• /uaa/oauth/token
• /api/v0/deployed/products

Note:

Custom APIs are added as Tanzu Opsman Get API step to the Pattern.

Data collected by Discovery during horizontal discovery

Table 4. Collected information

Field	Description
Main CI: PCF Foundation [cmdb_ci_pcf_foundation]
Name	Pivotal Cloud Foundry cluster entry name <name>-<hostCf:<portCf>
ip_address	Pivotal Cloud Foundry host IP.
port	Pivotal Cloud Foundry service port.
short_description	Pivotal Cloud Foundry service build number.
Organization	Organization list, managed by PCF cluster. The entries are separated using a “,” comma separator.
PCF Organization [cmdb_ci_pcf_organization]
Name	Organization name
URL	Organization unique URL
pcf_guid	Organization UID in CF
operational_status	Organization status
PCF Space [cmdb_ci_pcf_space]
Name	Space name
URL	Space unique URL
pcf_guid	Space UID in CF
PCF Application [cmdb_ci_pcf_appl]
Name	Application name
URL	Application unique URL
pcf_guid	Application UID in CF
PCF Route [cmdb_ci_pcf_route]
Name	Route name
URL	Route unique URL
pcf_guid	Route UID in CF
port	Route port
type	Route type
PCF Quota [cmdb_ci_pcf_quota]
Name	Quota name
URL	Quota unique URL
pcf_guid	Quota UID in CF
PCF Domain [cmdb_ci_pcf_domain]
name	Domain name
url	Domain unique URL
pcf_guid	Domain UID in CF
PCF Space instance [cmdb_ci_pcf_space_instance]
name	Space service instance name
url	Space service instance unique URL
pcf_guid	Space service instance UID in CF
PCF Service Plan [cmdb_ci_pcf_service_plan]
name	Service plan instance name
url	Service plan unique URL
pcf_guid	Space service instance UID in CF
PCF Service [cmdb_ci_pcf_service]
name	Service name
url	Service unique URL
pcf_guid	Service UID in CF
PCF Droplet [cmdb_ci_pcf_droplet]
name	Resource URL
pcf_guid	Droplet ID
url	Droplet URL
install_status	Installation status: 1, "installed"
operational_status	Operational status: 1, "operational"
Key Value [cmdb_key_value]
key	Resource Tag key Note: This data is only collected for V3 API calls.
value	Resource Tag value. Note: This data is only collected for V3 API calls.

Table 5. Data discovered by the Pivotal Cloud Foundry BOSH extension section

Field	Description
BOSH Deployment (cmdb_ci_bosh_deployment)
Name	The installation name of the resource.
object_id	The ID of the deployed product.
install_status	Hard-coded to the value: 1= installed.
operational_status	Hard-coded to the value: 1= operational.
deployment_version	The version of the deployed product.
deployment_type	The type of the deployed product.

CI relationships

These relationships are created to support Pivotal Cloud Foundry discovery.

CI	Relationship	CI
PCF Space [cmdb_ci_pcf_space]
cmdb_ci_pcf_space	Contains::Contained by	cmdb_ci_pcf_organization
PCF Application [cmdb_ci_pcf_appl]
cmdb_ci_pcf_appl	Contains::Contained by	cmdb_ci_pcf_space
PCF Route [cmdb_ci_pcf_route]
cmdb_ci_pcf_route	Contains::Contained by	cmdb_ci_pcf_foundation
PCF Quota [cmdb_ci_pcf_quota]
cmdb_ci_pcf_quota	Uses::Used by	cmdb_ci_pcf_space cmdb_ci_pcf_organization
PCF Domain [cmdb_ci_pcf_domain]
cmdb_ci_pcf_domain	Uses::Used by	cmdb_ci_pcf_route
	Owns::Owned by	cmdb_ci_pcf_organization
	Contains::Contained by	cmdb_ci_pcf_foundation
PCF Space instance [cmdb_ci_pcf_space_instance]
cmdb_ci_pcf_space_instance	Contains::Contained by	cmdb_ci_pcf_space
PCF Service Plan [cmdb_ci_pcf_service_plan]
cmdb_ci_pcf_service_plan	Uses::Used by	cmdb_ci_pcf_space_instance
PCF Service [cmdb_ci_pcf_service]
cmdb_ci_pcf_service	Uses::Used by	cmdb_ci_pcf_service_plan
PCF Droplet [cmdb_ci_pcf_droplet]
cmdb_ci_pcf_appl	Contains::Contained by	cmdb_ci_pcf_droplet
Key Value [cmdb_key_value]
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_droplet
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_organization
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_space
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_domain
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_route
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_appl
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_service
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_service_plan
cmdb_key_value	Reference only. For example: configuration_item	cmdb_ci_pcf_space_instance

Pivotal Cloud Foundry BOSH relationships

These relationships are created to support Pivotal Cloud Foundry BOSH extension section discovery.

CI	Relationship	CI
Cloud Foundry Cluster [cmdb_ci_pcf_foundation]	Contains::Contained by	BOSH Deployment [cmdb_ci_bosh_deployment]