This article was originaly published in 2018.05.21
Auto-Discovery with Cloud Foundry
The Cloud Foundry plugin provides the ability to automatically discover a Cloud Foundry installation on an agent, and subsequently provision the environment in UrbanCode Deploy. The plugin's auto-configuration step will create resources for each organization and space found in a using the cf CLI tool. This post will discuss the process for allowing your Cloud Foundry topology to be automatically configured using UrbanCode Deploy.
Role Permissions in UrbanCode Deploy
Before you get started, there are a few required permissions that we must make sure are set on the UC Auto Discovery and UC Auto Configure roles in UCD. These two roles are meant to be used for auto-discovery and auto-configuration. However, in certain versions of UrbanCode Deploy you must add the 'Manage Properties' permission for resources. You can ensure that this permission is set on both roles from the Settings -> Role Configuration page in UrbanCode Deploy. After you have navigated to the role configurations, select the UCD Auto Configure role. Next, click to the Resource selection and expand the Edit permissions for standard resources.
Ensure that the Manage Properties field is checked on the Resource. After you've validated the permission settings for the UC Auto Configure role, repeat the process for the UC Auto Discovery role.
Properties for Auto-Discovery
cf.commandPath
The auto-discovery task will search through multiple directories for the 'cf' executable. If the file is located, a new '
CloudFoundryController' resource will be created under the agent resource. The process can utilize a few different options to discover the Cloud Foundry executable. These options are listed in order of precedence, meaning that if the first option is being utilized, all others will be ignored:
- You may set the 'cf.commandPath' property on the agent. This property is an absolute path to the Cloud Foundry executable file on the agent machine.
- You may otherwise set the 'cf.home' property on the agent. This is the path to the directory where your Cloud Foundry executable exists on the agent machine.
- If none of the above options are configured, the auto-discovery process will pick up the 'CFHOME' environment variable from the agent machine.
- After exhausting all of the above options, the auto-discovery task will search a few common installation directories listed below.
If the '
cf.commandPath' field, the '
cf.home' field, and the '
CF_HOME' environment variable are all not set the discovery task will search through a few common installation directories. If the agent is a Windows machine, it will recursively search:
- C:\Program Files\CloudFoundry
- C:\Program Files (x86)\CloudFoundry
If the agent is a Linux/Mac machine, the auto-discovery task will search:
- /opt/CloudFoundry/cf
- /usr/share/CloudFoundry/cf
These are just the most common installation locations, and hence the default search locations. It is very possible that the Cloud Foundry executable may be in a different location on the file system. In this case, you must use one of the other options described earlier.
cf.api
By default the auto-discovery process will execute the '
cf api' command using the found cf executable. Using the output from this command, the
cf.api property will also be set as your Cloud Foundry API endpoint. However, to retrieve the API endpoint from the '
cf api' command output, you need to have already successfully logged into Cloud Foundry on your agent machine. A successful login generates the '
config.json' file in your user's home directory, which holds the name of your API endpoint. If you have not yet successfully logged into Cloud Foundry on your agent machine, you will need to set the cf.api property. You have two separate ways to set the cf.api property:
-
- You may set the 'cf.api' property at the agent level before auto-discovery executes.
- This option will create the cf.api property on the CloudFoundryController when auto-discovery executes successfully.
- You must remember to set the cf.api property on the agent as an agent property before running auto-discovery.
Configure the cf.api property on the agent before running auto-discovery.
-
- You may also set the cf.api property on the CloudFoundryController after auto-discovery has completed.
- Using this option, you will allow auto-discovery to execute without a predefined cf.api property on the agent, and then update the property on the generated CloudFoundryController resource.
Setting the cf.api property on the CloudFoundryController resource after auto-discovery.
Running Auto-Discovery
Once properties are configured to actually run auto-discovery, executing the task is fairly simple. In the 'Resources' tab on UrbanCode Deploy create a new or use an existing top level resource group, and then add your Cloud Foundry agent to that group. Assuming the Cloud Foundry plugin is installed, this will kick off the auto-discovery process, which you can view under the History tab of your agent resource. After the auto-discovery process completes successfully you will have a new resource with the role 'CloudFoundryController' under your agent resource.
The newly created CloudFoundryController resource listed with your api endpoint.
Running Auto-Configuration
After successfully running auto-discovery, you may now use the CloudFoundryController resource created to run auto-configuration. This process will replicate your Cloud Foundry topology as a resource tree in UrbanCode Deploy. To access all of your Cloud Foundry domains and spaces you will need to provide your username and password. To configure the CloudFoundryController resource, click the edit resource button and you will be able to fill out the required properties to execute auto-configuration.
Configuring the CloudFoundryController resource for auto-configuration. You'll notice that the Cloud Foundry API Endpoint and Cloud Foundry Executable properties have already been configured. These properties were set during the auto-discovery process. If either of these properties have not been configured, please re-read the
Properties for Auto-Discovery section.
Auto-configuration generates all of the organizations, spaces, and applications as resources under the CloudFoundryController.
Utilizing The Resource Tree
The auto-discovery and auto-configuration processes generate the resource tree in UCD including your controller and all organizations, spaces, and applications in your Cloud Foundry installation. Each resource that is created is assigned a resource role that specifies which properties are assigned to that resource. Here are all of the resource roles created and the names of each role property defined on them:
| Property Name |
Description |
| cf.api |
The url of the Cloud Foundry API endpoint. |
| cf.commandPath |
The path to the directory where the cf command line executable resides. |
| cf.username |
The Cloud Foundry username. |
| cf.api |
The Cloud Foundry password. |
-
- CloudFoundryOrganization:
| Property Name |
Description |
| cf.org |
The name of the Cloud Foundry organization. |
| Property Name |
Description |
| cf.space |
The name of the Cloud Foundry space. |
| Property Name |
Description |
| cf.app |
The name of the Cloud Foundry application. |
The resources are defined in a hierarchical structure, which determines the properties that each resource has access to. For instance, the CloudFoundryApp resource has access to every property in the list. Components that are added to the resource tree may reference the properties of resources above it.
The 'CF' component has been added to the 'JeffPHPApp' CloudFoundryApp resource. You can now define a component process and utilize all of the resource properties in the hierarchy. The syntax to reference resource properties in UCD is '${p:resource/propName}'. The property will be resolved if it is found during runtime.
A new component process defined on the 'CF' component has access to all resource properties in the hierarchy.
#UrbanCodeDeploy#ucd-plugins#ucd