Update user guide and readme for 2.0 changes (#262)

GoogleCloudPlatform · Jun 27, 2018 · 4ba7edf · 4ba7edf
1 parent c631d8e
commit 4ba7edf
Show file tree

Hide file tree

Showing 4 changed files with 480 additions and 79 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,23 +1,20 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 2.0.0 (in release candidate)
 ### Added
 * New `cloudSdkVersion` parameter to specify desired Cloud SDK version.
 * Cloud SDK and java app-engine components are automatically installed when `cloudSdkHome` is not provided. ([#247](../../issues/247))
 * Cloud SDK installation is verified when `cloudSdkHome` and `cloudSdkVersion` are configured. ([#248](../../issues/248))
 * New `<serviceAccountKeyFile>` configuration parameter, and `appengine:cloudSdkLogin` goal. ([#268](../../issues/268))
 * New `appengine:deployAll` goal to deploy application with all valid yaml configs simultaneously. ([#273](../../issues/273), [#277](../../issues/277))
+* Can set `project` and `version` to `GCLOUD_CONFIG` to delegate to gcloud or `APPENGINE_CONFIG` to delegate to appengine-web.xml. ([#305](../../issues/305))
 
 ### Changed
 * `appengine:stop` no longer fails if the stop request to server fails, but it will log an error. ([#309](https://github.com/GoogleCloudPlatform/app-maven-plugin/pull/309))
 * Upgrade App Engine Plugins Core dependency to 0.5.2.
 * `cloudSdkPath` has been replaced with `cloudSdkHome`. ([#257](../../issues/257))
 * Remove deprecated `appYamls` parameter. ([#162](../../issues/162))
-* `project` and `version` are no longer pulled from the global gcloud state. `project` must be configured
-in either pom.xml using the `<project>` tag or in appengine-web.xml using the `<application>` tag.
-`version` may be left unconfigured to be generated by gcloud, or it may be configured in your pom.xml or
-appengine-web.xml. To read values from appengine-web.xml, set the system property `deploy.read.appengine.web.xml=true`. ([#285](../../issues/285))
 * Appengine goals no longer fork. Instead of running `mvn appengine:<goal>`, you must either explicitly run
 `mvn package appengine:<goal>` or bind the goal to a lifecycle phase in your pom.xml. ([#301](../../issues/301))
 * Removed `deployables` parameter. To deploy specific configuration files, use the appropriate deploy goals

diff --git a/README.md b/README.md
@@ -5,6 +5,10 @@
 
 This Maven plugin provides goals to build and deploy Google App Engine applications.
 
+| 2.0.0 Release Candidates are Live |
+| :------------------------------ |
+| 2.0.0-rc have been published. The behavior of the appengine-maven-plugin has changed since v1.+; please see the [CHANGELOG](CHANGELOG.md) for a full list of changes and an updated [USER GUIDE](USER_GUIDE.md) for details. If you are having trouble using or updating your plugin, please file a [new issue](https://github.com/GoogleCloudPlatform/app-maven-plugin/issues).|
+
 # Reference Documentation
 
 App Engine Standard Environment:
@@ -41,14 +45,21 @@ In your Maven App Engine Java app, add the following plugin to your pom.xml:
 </plugin>
 ```
 
-You can now run commands like `mvn appengine:deploy` in the root folder of your Java application.
+You can now run commands like `mvn package appengine:deploy` in the root folder of your Java application.
 
 # Supported goals
 
 Goal | Description
 --- | ---
+appengine:cloudSdkLogin|Login and set the Cloud SDK common configuration user.
 appengine:stage|Generates an application directory for deployment.
 appengine:deploy|Stages and deploys an application to App Engine.
+appengine:deployCron|Deploy cron configuration.
+appengine:deployDispatch|Deploy dispatch configuration.
+appengine:deployDos|Deploy dos configuration.
+appengine:deployIndex|Deploy datastore index configuration.
+appengine:deployQueue|Deploy queue configuration.
+appengine:deployAll|Deploy the application with all available valid configuration.
 appengine:run|Runs the App Engine local development server. *(App Engine Standard Only)*
 appengine:start|Starts running the App Engine devserver asynchronously and then returns to the command line. When this goal runs, the behavior is the same as the run goal except that Maven continues processing goals and exits after the server is up and running. *(App Engine Standard Only)*
 appengine:stop|Stops a running App Engine web development server. *(App Engine Standard Only)*
@@ -65,7 +76,7 @@ To automatically run the `appengine:genRepoInfoFile` goal during the Maven build
       <phase>prepare-package</phase>
       <goals>
         <goal>genRepoInfoFile</goal>
-        </goals>
+      </goals>
     </execution>
   </executions>
   ...

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -1,6 +1,8 @@
-# User guide
+# User guide 2.+
 
-Primitive guide for users 1.3.0 and above (need to expand)
+| NOTE             |
+| :---------------- |
+| The behavior of the appengine-maven-plugin has changed since v1.+; please see the [CHANGELOG](CHANGELOG.md) for a full list of changes. If you are having trouble using or updating your plugin, please file a [new issue](https://github.com/GoogleCloudPlatform/app-maven-plugin/issues).|
 
 ## Applying the Plugin
 For both _standard_ and _flexible_ applications, include the plugin in your pom.xml:
@@ -21,6 +23,10 @@ For both _standard_ and _flexible_ applications, include the plugin in your pom.
 The [Cloud SDK](https://cloud.google.com/sdk) is required for this plugin to
 function. Download and install it before running any tasks.
 
+As of version 2.0.0, App Engine goals no longer fork. In order to run any App Engine goals, you must
+make sure to package your application first (i.e. run `mvn package appengine:<goal>`). You may also
+bind the goals to a lifecycle phase in your pom.xml.
+
 ## App Engine Standard
 The plugin will target the App Engine standard environment if you include an `appengine-web.xml`
 in `src/main/webapp/WEB-INF/`, otherwise it will assume it is an [App Engine flexible](#app-engine-flexible)
@@ -31,23 +37,25 @@ For App Engine standard, the plugin exposes the following goals :
 
 #### Local Run
 
-| Goal    | Description |
-| ------- | ----------- |
-| `run`   | Run the application locally. |
-| `start` | Start the application in the background. |
-| `stop`  | Stop a running application. |
+| Goal              | Description |
+| ----------------- | ----------- |
+| `run`             | Run the application locally. |
+| `start`           | Start the application in the background. |
+| `stop`            | Stop a running application. |
 
 #### Deployment
 
 | Goal             | Description |
 | ---------------- | ----------- |
+| `cloudSdkLogin`  | Login and set the Cloud SDK common configuration user. |
 | `stage`          | Stage an application for deployment. |
 | `deploy`         | Deploy an application. |
 | `deployCron`     | Deploy cron configuration. |
 | `deployDispatch` | Deploy dispatch configuration. |
 | `deployDos`      | Deploy dos configuration. |
 | `deployIndex`    | Deploy datastore index configuration. |
 | `deployQueue`    | Deploy queue configuration. |
+| `deployAll`      | Deploy the application and all of its configuration files at once. |
 
 ### Configuration
 Once you've [initialized](https://cloud.google.com/sdk/docs/initializing) `gcloud` you can run and deploy
@@ -65,9 +73,25 @@ If you wish to customize your configuration, the plugin can be configured using
 
 ##### Cloud SDK configuration
 
-| Parameter      | Description |
-| -------------- | ----------- |
-| `cloudSdkPath` | Location of the Cloud SDK, the plugin will try to find it if none is specified here. |
+| Parameter               | Description |
+| ----------------------- | ----------- |
+| `serviceAccountKeyFile` | A Google project service account key file to run Cloud SDK operations requiring an authenticated user. |
+| `cloudSdkHome`          | Location of the Cloud SDK. |
+| `cloudSdkVersion`       | Desired version of the Cloud SDK. (e.g. "192.0.0") |
+
+The Cloud SDK will be installed/updated/verified depending on which parameters are configured:
+
+| Parameters Specified   | Action |
+| ---------------------- | ------ |
+| None                   | Latest version of the Cloud SDK is downloaded and installed. |
+| Both parameters        | Cloud SDK installation specified at `cloudSdkHome` is verified. |
+| `cloudSdkHome` only    | No verification. |
+| `cloudSdkVersion` only | Cloud SDK at specified version is downloaded and installed. |
+
+The Cloud SDK is installed in `$USER_HOME/.cache/google-cloud-tools-java/managed-cloud-sdk/<version>/google-cloud-sdk`
+on Linux, `$USER_HOME/Library/Application Support/google-cloud-tools-java/managed-cloud-sdk/<version>/google-cloud-sdk`
+on OSX, and `%LOCALAPPDATA%/google/ct4j-cloud-sdk/<version>/google-cloud-sdk` on Windows.
+The Cloud SDK installation/verification occurs automatically before running any appengine goals.
 
 ##### Run configuration
 Note that only a subset are valid for Dev App Server version "1" and all are valid for Dev App Server
@@ -77,7 +101,6 @@ Valid for versions "1" and "2-alpha":
 
 | Parameter             | Description |
 | --------------------- | ----------- |
-| ~~`appYamls`~~        | Deprecated in favor of `services` |
 | `devserverVersion`    | Server versions to use, options are "1" or "2-alpha" |
 | `environment`         | Environment variables to pass to the Dev App Server process |
 | `host`                | Application host address. |
@@ -138,15 +161,101 @@ The `deploy` configuration has the following parameters:
 | Parameter             | Description |
 | --------------------- | ----------- |
 | `bucket`              | The Google Cloud Storage bucket used to stage files associated with the deployment. |
-| `deployables`         | The YAML files for the services or configurations you want to deploy. |
-| `project`             | The Google Cloud Project target for this deployment. |
+| `project`             | The Google Cloud Project target for this deployment. This can also be set to `GCLOUD_CONFIG` or `APPENGINE_CONFIG`.\* |
 | `promote`             | Promote the deployed version to receive all traffic. |
 | `server`              | The App Engine server to connect to. Typically, you do not need to change this value. |
 | `stopPreviousVersion` | Stop the previously running version when deploying a new version that receives all traffic. |
-| `version`             | The version of the app that will be created or replaced by this deployment. If you do not specify a version, one will be generated for you by the Cloud SDK. |
+| `version`             | The version of the app that will be created or replaced by this deployment. This also can be set to `GCLOUD_CONFIG` or `APPENGINE_CONFIG`.\* |
+
+\* setting a property to `GCLOUD_CONFIG` will deploy using the gcloud settings for the property.
+\* setting a property to `APPENGINE_CONFIG` will deploy using the value read from `appengine-web.xml`.
+
+## App Engine Flexible
+The plugin will target the App Engine flexible environment if you do **NOT** include an `appengine-web.xml`
+in `src/main/webapp/WEB-INF/`.
+
+### Goals
+For App Engine flexible, the plugin exposes the following goals:
+
+#### Deployment
+
+| Goal             | Description |
+| ---------------- | ----------- |
+| `cloudSdkLogin`  | Login and set the Cloud SDK common configuration user. |
+| `stage`          | Stage an application for deployment. |
+| `deploy`         | Deploy an application. |
+| `deployCron`     | Deploy cron configuration. |
+| `deployDispatch` | Deploy dispatch configuration. |
+| `deployDos`      | Deploy dos configuration. |
+| `deployIndex`    | Deploy datastore index configuration. |
+| `deployQueue`    | Deploy queue configuration. |
+| `deployAll`      | Deploy the application and all of its configuration files at once. |
+
+Once you've [initialized](https://cloud.google.com/sdk/docs/initializing) `gcloud` you can run and deploy
+your application using the defaults provided by the plugin.
+
+To see the generated documentation for goals and parameters including default values, execute the
+following:
+
+```bash
+$  mvn appengine:help -Ddetail
+```
+
+If you wish to customize your configuration, the plugin can be configured using the usual
+`<configuration>` element.
+
+##### Cloud SDK configuration
+
+| Parameter          | Description |
+| ------------------ | ----------- |
+| `cloudSdkHome`     | Location of the Cloud SDK. |
+| `cloudSdkVersion`  | Desired version of the Cloud SDK. (e.g. "192.0.0") |
+
+The Cloud SDK will be installed/updated/verified depending on which parameters are configured:
+
+| Parameters Specified   | Action |
+| ---------------------- | ------ |
+| None                   | Latest version of the Cloud SDK is downloaded and installed. |
+| Both parameters        | Cloud SDK installation specified at `cloudSdkHome` is verified. |
+| `cloudSdkHome` only    | No verification. |
+| `cloudSdkVersion` only | Cloud SDK at specified version is downloaded and installed. |
+
+The Cloud SDK is installed in `$USER_HOME/.cache/google-cloud-tools-java/managed-cloud-sdk/<version>/google-cloud-sdk`
+on Linux, `$USER_HOME/Library/Application Support/google-cloud-tools-java/managed-cloud-sdk/<version>/google-cloud-sdk`
+on OSX, and `%LOCALAPPDATA%/google/ct4j-cloud-sdk/<version>/google-cloud-sdk` on Windows.
+The Cloud SDK installation/verification occurs automatically before running any appengine goals.
+
+
+##### Stage
+The `stage` configuration has the following parameters:
+
+| Parameter            | Description |
+| -------------------- | ----------- |
+| `appEngineDirectory` | The directory that contains app.yaml. |
+| `dockerDirectory`    | The directory that contains Dockerfile and other docker context. |
+| `artifact`           | The artifact to deploy (a file, like a .jar or a .war). |
+| `stagingDirectory`   | The directory to which to stage the application |
+
+##### Deploy
+The `deploy` configuration has the following parameters:
+
+| Parameter             | Description |
+| --------------------- | ----------- |
+| `appEngineDirectory`  | Location of configuration files (cron.yaml, dos.yaml, etc) for configuration specific deployments. |
+| `bucket`              | The Google Cloud Storage bucket used to stage files associated with the deployment. |
+| `imageUrl`            | Deploy with a Docker URL from the Google container registry. |
+| `project`             | The Google Cloud Project target for this deployment. This can also be set to `GCLOUD_CONFIG`.\* |
+| `promote`             | Promote the deployed version to receive all traffic. |
+| `server`              | The App Engine server to connect to. Typically, you do not need to change this value. |
+| `stopPreviousVersion` | Stop the previously running version of this service after deploying a new one that receives all traffic. |
+| `version`             | The version of the app that will be created or replaced by this deployment. This can also be set to `GCLOUD_CONFIG`.\* |
+
+\* setting a property to `GCLOUD_CONFIG` will deploy using the gcloud settings for the property.
 
 ---
 
+## FAQ
+
 ### How do I deploy my project Configuration Files?
 
 You can now deploy the cron/dos/etc. configuration files separately using the new goals:
@@ -157,6 +266,8 @@ You can now deploy the cron/dos/etc. configuration files separately using the ne
 * `deployIndex`
 * `deployQueue`
 
+You may also use the `deployAll` goal to deploy the application and all valid configuration files at once.
+
 _For GAE Flexible projects_ The deployment source directory can be overridden by setting the `appEngineDirectory` parameter in the deploy configuration.
 
 For standard it defaults to `<stagingDirectory>/WEB-INF/appengine-generated` (and `stagingDirectory`
@@ -252,68 +363,31 @@ You can pass additional arguments directly to the Dev App Server:
 </configuration>
 ```
 
----
-
-## App Engine Flexible
-The plugin will target the App Engine flexible environment if you do **NOT** include an `appengine-web.xml`
-in `src/main/webapp/WEB-INF/`.
-
-### Goals
-For App Engine flexible, the plugin exposes the following goals:
-
-#### Deployment
-
-| Goal             | Description |
-| ---------------- | ----------- |
-| `stage`          | Stage an application for deployment. |
-| `deploy`         | Deploy an application. |
-| `deployCron`     | Deploy cron configuration. |
-| `deployDispatch` | Deploy dispatch configuration. |
-| `deployDos`      | Deploy dos configuration. |
-| `deployIndex`    | Deploy datastore index configuration. |
-| `deployQueue`    | Deploy queue configuration. |
-
-Once you've [initialized](https://cloud.google.com/sdk/docs/initializing) `gcloud` you can run and deploy
-your application using the defaults provided by the plugin.
+### How can I bind App Engine goals to lifecycle phases in my build file?
 
-To see the generated documentation for goals and parameters including default values, execute the
-following:
+You can add something like the following to your pom.xml:
 
-```bash
-$  mvn appengine:help -Ddetail
+```XML
+<plugin>
+  ...
+  <executions>
+    <execution>
+      <phase>deploy</phase>
+      <goals>
+        <goal>deploy</goal>
+      </goals>
+    </execution>
+  </executions>
+  ...
+</plugin>
 ```
 
-If you wish to customize your configuration, the plugin can be configured using the usual
-`<configuration>` element.
-
-##### Cloud SDK configuration
-
-| Parameter      | Description |
-| -------------- | ----------- |
-| `cloudSdkPath` | Location of the Cloud SDK, the plugin will try to find it if none is specified here. |
+In this case, running `mvn deploy` will automatically build and deploy the application to appengine.
 
+### I have a project that supports both flex and standard. How do I control which deployment to use?
 
-##### Stage
-The `stage` configuration has the following parameters:
+The plugin defaults to standard deployment if your project contains a webapp/WEB-INF/appengine-web.xml file. If
+your project also has an appengine/app.yaml and you wish to use flexible deployment, you may temporarily move the
+appengine-web.xml file to a different location before deploying.
 
-| Parameter            | Description |
-| -------------------- | ----------- |
-| `appEngineDirectory` | The directory that contains app.yaml. |
-| `dockerDirectory`    | The directory that contains Dockerfile and other docker context. |
-| `artifact`           | The artifact to deploy (a file, like a .jar or a .war). |
-| `stagingDirectory`   | The directory to which to stage the application |
-
-##### Deploy
-The `deploy` configuration has the following parameters:
-
-| Parameter             | Description |
-| --------------------- | ----------- |
-| `appEngineDirectory`  | Location of configuration files (cron.yaml, dos.yaml, etc) for configuration specific deployments. |
-| `bucket`              | The Google Cloud Storage bucket used to stage files associated with the deployment. |
-| `deployables`         | The YAML files for the services or configurations you want to deploy. |
-| `imageUrl`            | Deploy with a Docker URL from the Google container registry. |
-| `project`             | The Google Cloud Project target for this deployment. |
-| `promote`             | Promote the deployed version to receive all traffic. |
-| `server`              | The App Engine server to connect to. Typically, you do not need to change this value. |
-| `stopPreviousVersion` | Stop the previously running version of this service after deploying a new one that receives all traffic. |
-| `version`             | The version of the app that will be created or replaced by this deployment. If you do not specify a version, one will be generated for you by the Cloud SDK. |
+---