Cloud Foundry Eclipse Plugin
The Cloud Foundry Eclipse Plugin is an extension that enables Cloud Foundry users to deploy and manage Java and Spring applications on a Cloud Foundry instance from Eclipse or Spring Tools Suite (STS).
The plugin supports Eclipse v3.8 and v4.3 (a Java EE version is recommended), and STS 3.0.0 and later.
This page has instructions for installing and using v1.5.1 of the plugin, which is compatible with Cloud Foundry v2.
You can use the plugin to:
- Deploy applications from an Eclipse or STS workspace to a running Cloud Foundry instance. The plugin supports Java/JVM applications and frameworks, such as:
- Java Web
- Java standalone
- Create, bind, and unbind services.
- View and manage deployed applications and services.
- Start and stop applications.
v1.5.1 of the plugin provides several new features:
- Custom buildpack support — When you deploy an application using the plugin, you can supply the URL of a custom buildpack.
- Separately defined host and domain — In this version of the plugin, you specify the components (host and domain) of an application URL separately, rather than as a complete URL.
- Cloud Foundry server cloning — v1.5.1 of the plugin makes it easier to work with multiple Cloud Foundry spaces. After configuring a first Cloud Foundry server instance using the plugin, you can use the new Clone Server command to create additional server instances that target other Cloud Foundry spaces.
If you have a previous version of the Cloud Foundry Eclipse Plugin installed, uninstall it before installing the new version. To uninstall the plugin:
- Choose About Eclipse (or About Spring Tools Suite) from the Eclipse (or Spring Tools Suite) menu and click Installation Details.
- On the Installation Details, select the previous version of the plugin and click Uninstall.
Follow the installation instructions appropriate for your environment:
- Install to Eclipse from Marketplace
- Install to STS from Extensions Tab
- Install from a Local Repository
Follow these instructions to install the Cloud Foundry Eclipse Plugin to Eclipse from the Eclipse Marketplace.
- Start Eclipse.
- Select Eclipse Marketplace from the Eclipse Help menu.
- On the marketplace window, enter “Cloud Foundry” in the Find field, and click Go.
In the search results, click the Install control next to the listing for Cloud Foundry Integration.
The Confirm Selected Features window lists the plugin — “Cloud Foundry Integration for Eclipse” — and the optional “SpringSource UAA Integration” component, which reports tool usage data, anonymously. If you do not want your plugin usage statistics to be reported, de-select the UAA component before clicking Confirm.
The Review Licenses window appears. Click “I accept the terms of the license agreement” and click Finish.
The Software Updates window appears. Click Yes to restart Eclipse.
Follow these instructions to install the Cloud Foundry Eclipse Plugin to STS from the Extensions tab.
- Start STS.
- Select the Extensions tab from the STS Dashboard.
- Enter “Cloud Foundry” in the Find field.
Select Cloud Foundry Integration for Eclipse and click Install.
The Install window lists the plugin — “Cloud Foundry Integration for Eclipse” — and the optional “Spring UAA Integration” component, which reports tool usage data, anonymously. If you prefer that your plugin usage statistics not be reported, de-select the UAA component beform clicking Next.
On the Install Details window, click Next.
The Review Licenses window appears. Click “I accept the terms of the license agreement” and click Finish to perform the installation.
The Software Updates window appears. Click Yes to restart STS.
After STS restarts, you can see new panes in the Editor portion of the screen. See About the Plugin User Interface below for a description of the plugin tabs and the information in each.
Proceed to Create a Cloud Foundry Server.
If you need to install the Cloud Foundry Eclipse Plugin locally, rather than via the Internet, you can download the source and create a repository that you can copy to the target machine and then install from it.
Step 1: Obtain the plugin source from GitHub.
- You can download archived source code for released versions of the plugin from https://github.com/SpringSource/eclipse-integration-cloudfoundry/releases.
If you want the very latest source code for the plugin, clone the project repository:
git clone https://github.com/SpringSource/eclipse-integration-cloudfoundry
Step 2: Build repository.
Unzip the downloaded archive, change directory to the root directory and run this command in the shell:
mvn -Pe37 package
org.cloudfoundry.ide.eclipse.server.site/target/site to the machine where you want to install the plugin. If you zip it up, be sure to unzip prior to installation.
Step 3: Install from local repository.
On the machine running Eclipse or Spring Tools Suite:
- In Eclipse (or STS), select Install New Software from the Help menu.
- On the Available Software window, click Add to the right of the Work with field.
- On the Add Repository window, enter a name for the repository, for example “Cloud Foundry Integration”, and click Local.
- On the Open window, browse to
org.cloudfoundry.ide.eclipse.server.site/target/siteand click Open.
- On the Add Repository window, click OK.
- On the Available Software window, checkmark: “Core/Cloud Foundry Integration” and “Resources/Cloud Foundry Integration” and click Next.
- On the Review Licenses window, click “I accept the terms of the license agreement” and click Finish.
This section has instructions for configuring a server resource that will represent a target Cloud Foundry space. You will create a server for each space in Cloud Foundry to which you will deploy applications. Once you create your first Cloud Foundry service instances using the instructions below, you can create additional instances using the Clone Server feature.
- Right-click the Servers view and select New > Server.
In the Define a New Server window, expand the Pivotal folder, select Cloud Foundry, and click Next.
Note: Do not enter values for Server host name or Server Runtime Environment. These fields are unused and will be removed in a future version of the plugin.
On the Cloud Foundry Account window, if you already have a Cloud Foundry account, enter the email account and password you use to log on to Cloud Foundry and click Validate Account.
If you do not have a Cloud Foundry account, you can click Pivotal CF Signup to get one and complete this procedure after your account is established.
Note: The Register Account function is not supported by public instances of Cloud Foundry v2. You can register accounts for Pivotal CF Hosted using the Pivotal CF portal at run.pivotal.io.
The Cloud Foundry Account window is refreshed and displays a message indicating whether or not your credentials were valid — if they were, click Next.
On the Organizations and Spaces window, select the space you want to target, and click Finish.
Note: If you do not select a space, the server will be configured to connect to the default space, which is the first encountered in a list of your spaces.
Once you have successfully configured the Pivotal Cloud Foundry server, it will appear in the Servers view of the Eclipse or STS user interface. To familiarize yourself with the plugin user interface, see About the Plugin User Interface. When you are ready, proceed to Deploy an Application.
The paragraphs below describe the Cloud Foundry Eclipse plugin user interface. If you do not see the tabs described below, select the Pivotal Cloud Foundry server in the Servers view. To expose the Servers view, ensure that you are using the Java perspective, then select Window > Show View > Other > Server > Servers.
The Cloud Foundry editor, outlined in red in the screenshot below, is the primary plugin user interface. Some workflows involve interacting with standard elements of the Eclipse user interface, such as the Project Explorer and the Console and Servers views.
Note that the Cloud Foundry editor allows you to work with a single Cloud Foundry space; each space is represented by a distinct server instance in the Servers view (B). Multiple editors, each targeting a different space, can be open simultaneously. However, only one editor targeting a particular Cloud Foundry server instance can be open at a time.
The follow panes and views are present when the Overview tab is selected:
- A — The Package Explorer view lists the projects in the current workspace.
- B – The Servers view lists server instances configured in the current workspace. A server of type “Pivotal Cloud Foundry” represents a targeted space in a Cloud Foundry instance.
- C – The General Information pane.
- D – The Account Information pane lists your Cloud Foundry credentials and the target organization and space. The pane includes these controls:
- Clone Server — Use to create additional Pivotal Cloud Foundry server instances. You must configure a server instance for each Cloud Foundry space you wish to target. For more information, see Create Additional Server Instances.
- Change Password — Use to change your Cloud Foundry password.
- Validate Account — Use to verify your currently configured Cloud Foundry credentials.
- Pivotal CF Signup — Use to sign up for a Cloud Foundry account.
- E – The Server Status pane shows whether or not you are connected to the target Cloud Foundry space, and the Disconnect and Connect controls.
- F – The Console view displays status messages when you perform an action such as deploying an application.
G – The Remote Systems view allows you to view the contents of a file that is part of a deployed application. For more information, see View an Application File.
The follow panes are present when the Applications and Services tab is selected:
- H — The Applications pane lists the applications deployed to the target space.
- I — The Services pane lists the services provisioned in the targeted space.
J — The General pane displays the following information for the application currently selected in the Applications pane:
- Mapped URLs – Lists URLs mapped to the application. You can click a URL to open a browser to the application within Eclipse (or STS); and click the pencil icon to add or remove mapped URLs. See Manage Application URLs.
- Memory Limit – The amount of memory allocated to the application. You can use the pull-down to change the memory limit.
- Instances – The number of instances of the application that are deployed. You can use the pull-down to change number of instances.
- Start, Stop, Restart, Update and Restart — The controls that appear depend on the current state of the application. The Update and Restart command will attempt an incremental push of only those application resources that have changed. It will not perform a full application push. See Push Application Changes below.
K — The Services pane lists services that are bound to the application currently selected in the Applications pane. Note the icon in the upper right corner of the pane — it allows you to create a service, as described in Create a Service.
To deploy an application to Cloud Foundry using the plugin:
To initiate deployment either:
- Drag the application from the Package Explorer view onto the Pivotal Cloud Foundry server in the Servers view, or
- Right-click the Pivotal Cloud Foundry server in the Servers view, select Add and Remove from the server context menu, and move the application from the Available to the Configured column.
On the Application Details window:
By default, the Name field is populated with the application project name. You can enter a different name if desired — the name will be assigned to the deployed application, but will not rename the project.
If you want to use an external buildpack to stage the application, enter the URL of the buildpack.
You can deploy the application without further configuration by clicking Finish. Note that becuase the application default values may take a second or two to load, the Finish button might not be enabled immediately. A progress indicator will indicate when the application default values have been loaded, and the “Finish” button will be enabled.
Click Next to continue.
On the Launch Deployment window:
Host — By default, contains the name of the application. You can enter a different value if desired. Note that if you push the same application to multiple spaces in the same organization, you must assign a unique Host to each.
Domain — Contains the default domain. If you have mapped custom domains to the target space, they appear in the pull-down list. Note: This version of the Cloud Foundry Eclipse plugin does not provide a mechanism for mapping a custom domain to a space. You must use the
cf map domaincommand to do so. For more information, see map-domain.
Deployed URL — By default, contains the value of the Host and Domain fields, separated by a period (.) character.
Memory Reservation — Select the amount of memory to allocate to the application from the pull-down list.
Start application on deployment — If you do not want the application to be started upon deployment, uncheck the box.
The Services Selection window lists services provisioned in the target space. Checkmark the services, if any, that you want to bind to the application, and click Finish. Note that you can bind services to the application after deployment, as described in Bind and Unbind Services.
As the deployment proceeds, progress messages appear in the Console view. When deployment is complete, the application is listed in the Applications pane.
Before you can bind a service to an application you must create it. To do so:
- Select the Applications and Services tab.
- Click the icon in the upper right corner of the “Services” pane.
- In the Service Configuration window:
- Name — Enter a name for the service.
Type — Select the service type from the pull-down list.
The new service appears in the Services pane.
You can bind a service to an application when you deploy it. To bind a service to an application that is already deployed, drag the service from the Services pane to the Application Services pane. (See the area labelled “G” in the screenshot in the Applications and Services above.)
To unbind a service, right-click the service in the Application Services pane, and select Unbind from Application.
You can view the contents of a file in a deployed application by selecting it the Remote Systems View. (See the areas labelled “I” and “J” in the screenshot in the Applications and Services Tab above.)
If the Remote Systems View is not visible:
- Select the Applications and Services tab.
- Select the application of interest from the Applications pane.
- In the Instances pane, click the Remote Systems View link.
On the Remote Systems View, browse to the application and application file of interest, and double-click the file. A new tab appears in the editor area with the contents of the selected file.
To undeploy an application, right click the appliation in either the Servers or the Applications pane and clicke Remove.
You can change the memory allocation for an application and the number of instances deployed in the General pane when the Applications and Services tab is selected. Use the Memory Limit and Instances selector lists.
Although the scaling can be performed while the application is running, if the scaling has not taken effect, restart the application. If necessary, the application statistics can be manually refreshed by clicking the Refresh button in the top, right corner of the “Applications” pane, labelled “H” in the screenshot in Applications and Services Tab.
The Cloud Foundry editor supports these application operations:
Start and Stop — When you Start an application, the plugin pushes all application files to the Cloud Foundry instance before starting the application, regardless of whether there are changes to the files or not.
Restart — When you Restart a deployed application, the plugin does not push any resources to the Cloud Foundry instance.
Update and Restart — When you run this command, the plugin pushes only the changes that were made to the application since last update, not the entire application. This is useful for performing incremental updates to large applications.
You add, edit, and remove URLs mapped to the currently selected application in the General pane when the Applications and Services tab is selected. Click the pencil icon to display the Mapped URIs Configuration window.
When you start, restart, or update and restart an application, application output will generally be streamed to the Console view (labelled “F” in the screenshot in Overview Tab). The information shown in the Console view for a running application instance includes staging information, and the application's
If multiple instances of the application are running, only the output of the first instance appears in the Console view. To view the output of another running instance, or to refresh the output that is currently displayed:
In the Applications and Services tab, select the deployed application in the Applications pane.
Click the Refresh button on the top right corner of the Applications pane.
In the Instances pane, wait for the application instances to be updated.
Once non-zero health is shown for an application instance, right-click on that instance to open the context menu and select Show Console.
Each space in Cloud Foundry to which you want to deploy applications must be represented by a Cloud Foundry server instance in the Servers view. After you have created a Cloud Foundry server instance, as decribed in Create a Cloud Foundry Server, you can clone it to create another.
To clone a server:
- In the Cloud Foundry server instance editor “Overview” tab, click on the “Clone Server” button, or
- Right-click a Cloud Foundry server instance in the Servers view, and select Clone Server from the context menu,
On the Organizations and Spaces window, select the space you want to target.
The name field will be filled with the name of the space you selected. If desired, edit the server name before clicking finish Finish.
By default, the Cloud Foundry Eclipse plugin is configured to connect with Pivotal CF Hosted instance. You can configure the plugin to work with other Cloud Foundry instances to which you have access. To do so:
- Perform steps 1 and 2 of Create a Cloud Foundry Server.
On the Cloud Foundry Account window, enter the email account and password you use to log on to the target instance, and then click Manage Cloud URLs
On the Manage Cloud URLs window, click Add.
On the Add a Cloud URL window, enter the name and URL of the target cloud instance and click Finish.
The new cloud instance should appear in the list on the Manage Cloud URLs window. Click OK to proceed.
On the Cloud Foundry Account window, click Validate Account.
Complete steps 4 through 6 of Create a Cloud Foundry Server.