-
Notifications
You must be signed in to change notification settings - Fork 48
Cloud Tools for Eclipse Technical Design
Cloud Tools for Eclipse (C4E) supports development of Java servlet applications on the Google Cloud Platform (GCP) inside the Eclipse Integrated Development Environment (IDE) version 4.5 and later. It enables you to build web applications and sites that run on top of:
- App Engine Standard
- App Engine Flex
- Google Compute Engine (GCE)
- Google Container Environment (GKE)
Each of these is a separate Eclipse WTP facet:
- com.google.cloud.tools.eclipse.facets.appengine_standard
- com.google.cloud.tools.eclipse.facets.appengine_flex
- com.google.cloud.tools.eclipse.facets.gce
- com.google.cloud.tools.eclipse.facets.gke
FYI, code is not up to date with this and only defines a single appengine facet. We need to modify it along these lines.
All code will be hosted in the open on Github. Design docs, issue trackers, and the like will also be hosted on Github.
Build will be based on Maven and tycho.
Eclipse settings will be checked into the repo for easy development and import.
Travis will be used for continuous integration and testing.
Java 7 or later will be assumed.
File encoding is UTF-8.
The Google Java Style Guide is followed.
Official plugin releases will be signed by Google and can be installed from Google's Eclipse download site.
The plugin will be based on the Eclipse Web Tools Platform (WTP).
There will be a single feature and and multiple plugins. Note that here "features" and "plugins" are technical Eclipse terms that have almost the reverse of their normal meanings. A "feature" is a group of bundled functionality installed as a unit. Each feature contains multiple "plugins" (OSGI bundles) that provide specific functionality such as authorization, deployment, problem reports, etc.
For most interactions with the Google Cloud Platform, C4E will rely on the appengine-plugins-core library rather than invoking network services directly. This library shells out to the gcloud tool. The details are hidden from the user.
The user needs to manually install gcloud on their local system,
and possibly tell Eclipse where to find it (if it's not in one of several common locations).
Eventually, we may bundle the latest version of gcloud into C4E; but this
will likely not happen for 1.0. Initially we assume there is exactly one version of the Cloud SDK installed that applies across an Eclipse workspace.
(If the user has multiple workspaces, they can specify different cloud SDK locations in each. They can also update the cloud SDK location in a given workspace as an Eclipse preference. However multiple projects in a workspace at the same time all use the same version of the Cloud SDK.)
The App Engine Standard facet is used to expose the App Engine functionality (run, debug and deploy). To use the App Engine Standard runtime, the project must have the App Engine Standard facet. This means that adding the App Engine runtime without first adding the facet, would cause the facet to be added to the project.
Installing the App Engine facet does the following
- Adds the App Engine Runtime jars and SDK jars to the project's classpath
- Adds the appengine-web.xml if it doesn't exist
Uninstalling the App Engine facet does the following
- Removes the App Engine runtimes from the project
- Removes the App Engine Runtime jars and SDK jars from the project's classpath
Creating new App Engine projects with the 'New App Engine Standard Project' wizard or the 'New Maven-based App Engine Standard Project' wizard includes adding the App Engine Standard facet and runtimes to the new project. However when adding the App Engine facet to an existing project, the user would need to select the App Engine runtime instance of choice.
Each wizard will provide a fully configured, ultra-simple Eclipse project.
The wizard generates a new project containing these files and directories:
- src directory
- HelloWorldServlet.java that responds only to GET requests with a constant message
- test directory
- HelloWorldServletTest.java
- war directory
- WEB-INF directory
- appengine-web.xml AppEngine configuration file
- web.xml servlet configuration file
- lib directory containing any jars the servlet requires
- index.html with a link that points to the servlet.
- WEB-INF directory
- README file
The project will be associated with a WTP runtime that runs devappserver, and supplies general Java libraries, in particular servlet-api.jar and jsp-api.jar, to the classpath of the project.
The project will be tagged with an App Engine Standard facet. This facet supplies AppEngine specific libraries such as appengine-tools-api.jar to the classpath.
Both groups of libraries are shipped and installed locally with the Cloud SDK.
The project is set to build with Java 7 (the latest version supported by App Engine Standard).
The wizard generates a new project containing these files and directories:
- src directory
- HelloWorldServlet.java that responds only to GET requests with a constant message
- test directory
- HelloWorldServletTest.java
- war directory
- WEB-INF directory
- appengine-web.xml AppEngine configuration file
- web.xml servlet configuration file
- lib directory containing any jars the servlet requires
- index.html with a link that points to the servlet.
- WEB-INF directory
- README file
- Maven pom.xml file
All library jars will be loaded from maven central.
The project is set to build with Java 7 (the latest version supported by App Engine Standard).
The sample for the Flexible environment is almost identical to the sample for the standard environment except:
- The project will be tagged with an App Engine Flexible nature.
- app.yaml replaces appengine-web.xml and sets
vm: true - The javac source and target are set to Java 8
If M2Eclipse is installed in Eclipse, then an existing Maven based project can be imported into Eclipse in the usual way ("File > Import > Existing Maven Projects"). The project will be tagged with the matching facet (standard, flex, GCE, GKE).
We will build a WTP runtime in the com.google.cloud.tools.eclipse.appengine.localserver package. This runtime relies on dev_appserver via app-tools-lib-for-java and is launched in the usual way for a WTP server. (Select Project in Project Explorer and then choose Run As > Run On Server from the context menu).
Switching from a run to debug environment is also provided by Eclipse, with no additional work on our part.
Individual servers, that is instances of a runtime, are each configured with ports, host names, and so forth.
C4E will reference a white list of Java classes available in the App Engine Standard environment. This is supplied from appengine-plugins-core.
It checks that only Google App Engine supported JRE types are used by a CompilationUnit, and no classes are imported from com.google.appengine.repackaged.
It will be possible for the user to exclude classes and packages from these checks; e.g. testing packages that are not deployed to the server.
Configuration files (e.g. appengine-web.xml, web.xml, etc.) will be scanned for assorted problems.
C4E launches an external system browser (e.g. Chrome) where users can log in and grant necessary permissions to C4E. Assuming the user consents, the server sends an OAuth 2.0 access token back. C4E stores the token on a temporary stash and presents it when necessary, e.g., with future App Engine deployments.
For the entire list of available Google API scopes, see here.
| Scope | Description | APIs / Purposes |
|---|---|---|
email |
Know who you are on Google View your email address |
ide-login extracts email addresses |
https://www.googleapis.com/auth/cloud-platform |
View and manage your data across Google Cloud Platform services | Enables multiple APIs |
Login requires supplying an OAuth client ID and its associated client secret that identify a client product. We have created these ID and secret in the Cloud Tools for Eclipse GCP project. (Navigate to API Manager > Credentials.) The actual values are not hard-coded in our code-base and thus should be injected when building a release as described in README.md.
If the user deploys before logging in, Eclipse presents the login window in the external browser.
We use the ide-login library which offers IDE agnostic functionality for authorizing code to deploy, monitor, and manage GCP resources. This enables us to share code with IntelliJ.
In order to deploy, several things must first be done in the Cloud Console outside of Eclipse. In particular,
-
The environment you're deploying to must be enabled in the Cloud Console.
-
Billing should be turned on. (Required for GCE, GKE, and App Engine Flex).
-
Create a project with name and ID in the Developer console.
Deployment will be managed via appengine-plugins-core.
These targets invoke gcloud beta app deploy with the correct arguments to locate the user's authorization credentials and upload the artifacts to Google servers.
When the plugin execution reaches some predefined event points of our interest, the user is asked (only once) to opt in for usage tracking.
If and only if they agree, then the plugin sends non-personally identifiable pings for usage of the features below to a Google Analytics (GA) account. The account being used is a platform-wide Google Cloud Platform GA account.
- New Project Wizard: initiation and completion
- Deploy action: initiation and completion
- Local run and debug action: initiation
- Login: initiation and completion
For the purpose of counting the unique number of users, we additionally generate a random UUID as a client ID. This UUID is tied to a preference in the configuration scope (instead of being tied to each Eclipse installation due to technical limitation.)
At no time do we include or send the project ID, the project name, the Gaia ID, the username, or any other such personally identifiable information. We merely track the total number of events. The only thing we track that are not simple counters are UUIDs.
The Google Analytics tracking ID is not stored in the source repository on GitHub. Instead it is supplied when the official artifact is built.
End User Documentation
- Installation and setup
- Creating a new project
- Running and debugging
- Deploying
- Cloud Tools for Eclipse Tutorial
- Migration from the Google Plugin for Eclipse (GPE)
Contributor Docs