|
| 1 | +Google Cloud Java Client for Compute (Alpha) |
| 2 | +==================================== |
| 3 | + |
| 4 | +Java idiomatic client for [Google Cloud Compute](https://cloud.google.com/compute). |
| 5 | + |
| 6 | +[](https://travis-ci.org/GoogleCloudPlatform/gcloud-java) |
| 7 | +[](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master) |
| 8 | +[]( https://img.shields.io/maven-central/v/com.google.cloud/gcloud-java-compute.svg) |
| 9 | +[](https://www.codacy.com/app/mziccard/gcloud-java) |
| 10 | +[](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969) |
| 11 | + |
| 12 | +- [Homepage](https://googlecloudplatform.github.io/gcloud-java/) |
| 13 | +- [API Documentation](http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/compute/package-summary.html) |
| 14 | + |
| 15 | +> Note: This client is a work-in-progress, and may occasionally |
| 16 | +> make backwards-incompatible changes. |
| 17 | +
|
| 18 | +Quickstart |
| 19 | +---------- |
| 20 | +If you are using Maven, add this to your pom.xml file |
| 21 | +```xml |
| 22 | +<dependency> |
| 23 | + <groupId>com.google.cloud</groupId> |
| 24 | + <artifactId>gcloud-java-compute</artifactId> |
| 25 | + <version>0.2.0</version> |
| 26 | +</dependency> |
| 27 | +``` |
| 28 | +If you are using Gradle, add this to your dependencies |
| 29 | +```Groovy |
| 30 | +compile 'com.google.cloud:gcloud-java-compute:0.2.0' |
| 31 | +``` |
| 32 | +If you are using SBT, add this to your dependencies |
| 33 | +```Scala |
| 34 | +libraryDependencies += "com.google.cloud" % "gcloud-java-compute" % "0.2.0" |
| 35 | +``` |
| 36 | + |
| 37 | +Example Application |
| 38 | +------------------- |
| 39 | + |
| 40 | +[`ComputeExample`](../gcloud-java-examples/src/main/java/com/google/cloud/examples/compute/ComputeExample.java) |
| 41 | +is a simple command line interface that provides some of Google Cloud Compute Engine's |
| 42 | +functionality. Read more about using the application on the |
| 43 | +[`ComputeExample` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/cloud/examples/compute/ComputeExample.html). |
| 44 | + |
| 45 | +Authentication |
| 46 | +-------------- |
| 47 | + |
| 48 | +See the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) section in the base directory's README. |
| 49 | + |
| 50 | +About Google Cloud Compute |
| 51 | +-------------------------- |
| 52 | + |
| 53 | +[Google Cloud Compute][cloud-compute] delivers virtual machines running in Google's innovative data |
| 54 | +centers and worldwide fiber network. Compute Engine's tooling and workflow support enable scaling |
| 55 | +from single instances to global, load-balanced cloud computing. Compute Engine's VMs boot quickly, |
| 56 | +come with persistent disk storage, deliver consistent performance and are available in many |
| 57 | +configurations. |
| 58 | + |
| 59 | +Be sure to activate the Google Cloud Compute API on the Developer's Console to use Compute from |
| 60 | +your project. |
| 61 | + |
| 62 | +See the ``gcloud-java`` API [compute documentation][compute-api] to learn how to interact |
| 63 | +with Google Cloud Compute using this Client Library. |
| 64 | + |
| 65 | +Getting Started |
| 66 | +--------------- |
| 67 | + |
| 68 | +#### Prerequisites |
| 69 | +For this tutorial, you will need a [Google Developers Console](https://console.developers.google.com/) |
| 70 | +project with the Compute Engine API enabled. You will need to [enable billing](https://support.google.com/cloud/answer/6158867?hl=en) |
| 71 | +to use Google Cloud DNS. [Follow these instructions](https://cloud.google.com/docs/authentication#preparation) |
| 72 | +to get your project set up. You will also need to set up the local development environment by |
| 73 | +[installing the Google Cloud SDK](https://cloud.google.com/sdk/) and running the following commands |
| 74 | +in command line: `gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`. |
| 75 | + |
| 76 | +#### Installation and setup |
| 77 | +You'll need to obtain the `gcloud-java-compute` library. See the [Quickstart](#quickstart) section |
| 78 | +to add `gcloud-java-compute` as a dependency in your code. |
| 79 | + |
| 80 | +#### Creating an authorized service object |
| 81 | +To make authenticated requests to Google Cloud Compute Engine, you must create a service object with |
| 82 | +credentials. You can then make API calls by calling methods on the Compute service object. The |
| 83 | +simplest way to authenticate is to use [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). |
| 84 | +These credentials are automatically inferred from your environment, so you only need the following |
| 85 | +code to create your service object: |
| 86 | + |
| 87 | +```java |
| 88 | +import com.google.cloud.compute.Compute; |
| 89 | +import com.google.cloud.compute.ComputeOptions; |
| 90 | + |
| 91 | +Compute compute = ComputeOptions.defaultInstance().service(); |
| 92 | +``` |
| 93 | + |
| 94 | +For other authentication options, see the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) |
| 95 | +page. |
| 96 | + |
| 97 | +#### Creating a region IP address |
| 98 | +An external region IP address can be associated to a Google Compute Engine instance to communicate |
| 99 | +with instances in different regions or to communicate with the instance from ouside of Compute |
| 100 | +Engine. In this code snippet, we will create a new external region address. |
| 101 | + |
| 102 | +Add the following imports at the top of your file: |
| 103 | + |
| 104 | +```java |
| 105 | +import com.google.cloud.compute.AddressInfo; |
| 106 | +import com.google.cloud.compute.Operation; |
| 107 | +import com.google.cloud.compute.RegionAddressId; |
| 108 | +``` |
| 109 | + |
| 110 | +Then add the following code to create an address. Most Compute Engine calls return an `Operation` |
| 111 | +object that can be used to wait for operation completion and to check whether operation failed or |
| 112 | +succeeded: |
| 113 | + |
| 114 | +```java |
| 115 | +RegionAddressId addressId = RegionAddressId.of("us-central1", "test-address"); |
| 116 | +Operation operation = compute.create(AddressInfo.of(addressId)); |
| 117 | +while (!operation.isDone()) { |
| 118 | + Thread.sleep(1000L); |
| 119 | +} |
| 120 | +operation = operation.reload(); |
| 121 | +if (operation.errors() == null) { |
| 122 | + System.out.println("Address " + addressId + " was successfully created"); |
| 123 | +} else { |
| 124 | + // inspect operation.errors() |
| 125 | + throw new RuntimeException("Address creation failed"); |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +#### Creating a persistent disk |
| 130 | +A persistent disk can be used as primary storage for your virtual machine instances. Persistent |
| 131 | +disks can be created empty, from a disk image or from a disk snapshot. Compute Engine offers |
| 132 | +[publicly-available images](https://cloud.google.com/compute/docs/operating-systems/) of certain |
| 133 | +operating systems that you can use. In this code snippet, we will create a new persistent disk from |
| 134 | +a publicly-available image. |
| 135 | + |
| 136 | +Add the following imports at the top of your file: |
| 137 | + |
| 138 | +```java |
| 139 | +import com.google.cloud.compute.DiskInfo; |
| 140 | +import com.google.cloud.compute.DiskId; |
| 141 | +import com.google.cloud.compute.ImageDiskConfiguration; |
| 142 | +import com.google.cloud.compute.ImageId; |
| 143 | +``` |
| 144 | + |
| 145 | +Then add the following code to create a disk and wait for disk creation to terminate. |
| 146 | + |
| 147 | +```java |
| 148 | +ImageId imageId = ImageId.of("debian-cloud", "debian-8-jessie-v20160329"); |
| 149 | +DiskId diskId = DiskId.of("us-central1-a", "test-disk"); |
| 150 | +ImageDiskConfiguration diskConfiguration = ImageDiskConfiguration.of(imageId); |
| 151 | +DiskInfo disk = DiskInfo.of(diskId, diskConfiguration); |
| 152 | +Operation operation = compute.create(disk); |
| 153 | +while (!operation.isDone()) { |
| 154 | + Thread.sleep(1000L); |
| 155 | +} |
| 156 | +operation = operation.reload(); |
| 157 | +if (operation.errors() == null) { |
| 158 | + System.out.println("Disk " + diskId + " was successfully created"); |
| 159 | +} else { |
| 160 | + // inspect operation.errors() |
| 161 | + throw new RuntimeException("Disk creation failed"); |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +#### Creating a virtual machine instance |
| 166 | +An Google Compute Engine instance is a virtual machine (VM) hosted on Google's infrastructure. An |
| 167 | +instance can be created given it's identity, a machine type, one boot disk and a network interface. |
| 168 | +In this code snippet, we will create a virtual machine instance in the default network using as a |
| 169 | +boot disk the disk we have just created and assigning to it the just created IP address. |
| 170 | + |
| 171 | +Add the following imports at the top of your file: |
| 172 | + |
| 173 | +```java |
| 174 | +import com.google.cloud.compute.AttachedDisk; |
| 175 | +import com.google.cloud.compute.AttachedDisk.PersistentDiskConfiguration; |
| 176 | +import com.google.cloud.compute.InstanceId; |
| 177 | +import com.google.cloud.compute.InstanceInfo; |
| 178 | +import com.google.cloud.compute.MachineTypeId; |
| 179 | +import com.google.cloud.compute.NetworkConfiguration; |
| 180 | +import com.google.cloud.compute.NetworkConfiguration.AccessConfig; |
| 181 | +import com.google.cloud.compute.NetworkId; |
| 182 | +import com.google.cloud.compute.NetworkInterface; |
| 183 | +``` |
| 184 | + |
| 185 | +Then add the following code to create an instance and wait for instance creation to terminate. |
| 186 | + |
| 187 | +```java |
| 188 | +Address externalIp = compute.getAddress(addressId); |
| 189 | +InstanceId instanceId = InstanceId.of("us-central1-a", "test-instance"); |
| 190 | +NetworkId networkId = NetworkId.of("default"); |
| 191 | +PersistentDiskConfiguration attachConfiguration = |
| 192 | + PersistentDiskConfiguration.builder(diskId).boot(true).build(); |
| 193 | +AttachedDisk attachedDisk = AttachedDisk.of("dev0", attachConfiguration); |
| 194 | +NetworkInterface networkInterface = NetworkInterface.builder(networkId) |
| 195 | + .accessConfigurations(AccessConfig.of(externalIp.address())) |
| 196 | + .build(); |
| 197 | +MachineTypeId machineTypeId = MachineTypeId.of("us-central1-a", "n1-standard-1"); |
| 198 | +InstanceInfo instance = |
| 199 | + InstanceInfo.of(instanceId, machineTypeId, attachedDisk, networkInterface); |
| 200 | +Operation operation = compute.create(instance); |
| 201 | +while (!operation.isDone()) { |
| 202 | + Thread.sleep(1000L); |
| 203 | +} |
| 204 | +operation = operation.reload(); |
| 205 | +if (operation.errors() == null) { |
| 206 | + System.out.println("Instance " + instanceId + " was successfully created"); |
| 207 | +} else { |
| 208 | + // inspect operation.errors() |
| 209 | + throw new RuntimeException("Instance creation failed"); |
| 210 | +} |
| 211 | +``` |
| 212 | + |
| 213 | +#### Complete source code |
| 214 | + |
| 215 | +In |
| 216 | +[CreateAddressDiskAndInstance.java](../gcloud-java-examples/src/main/java/com/google/cloud/examples/compute/snippets/CreateAddressDiskAndInstance.java) |
| 217 | +we put together all the code shown above into one program. The program assumes that you are |
| 218 | +running on Compute Engine or from your own desktop. To run the example on App Engine, simply move |
| 219 | +the code from the main method to your application's servlet class and change the print statements to |
| 220 | +display on your webpage. |
| 221 | + |
| 222 | +Troubleshooting |
| 223 | +--------------- |
| 224 | + |
| 225 | +To get help, follow the `gcloud-java` links in the `gcloud-*`[shared Troubleshooting document](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/troubleshooting/readme.md#troubleshooting). |
| 226 | + |
| 227 | +Java Versions |
| 228 | +------------- |
| 229 | + |
| 230 | +Java 7 or above is required for using this client. |
| 231 | + |
| 232 | +Testing |
| 233 | +------- |
| 234 | + |
| 235 | +This library has tools to help make tests for code using Cloud Compute. |
| 236 | + |
| 237 | +See [TESTING] to read more about testing. |
| 238 | + |
| 239 | +Versioning |
| 240 | +---------- |
| 241 | + |
| 242 | +This library follows [Semantic Versioning](http://semver.org/). |
| 243 | + |
| 244 | +It is currently in major version zero (``0.y.z``), which means that anything |
| 245 | +may change at any time and the public API should not be considered |
| 246 | +stable. |
| 247 | + |
| 248 | +Contributing |
| 249 | +------------ |
| 250 | + |
| 251 | +Contributions to this library are always welcome and highly encouraged. |
| 252 | + |
| 253 | +See [CONTRIBUTING] for more information on how to get started. |
| 254 | + |
| 255 | +License |
| 256 | +------- |
| 257 | + |
| 258 | +Apache 2.0 - See [LICENSE] for more information. |
| 259 | + |
| 260 | + |
| 261 | +[CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md |
| 262 | +[LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE |
| 263 | +[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-compute |
| 264 | +[cloud-platform]: https://cloud.google.com/ |
| 265 | + |
| 266 | +[cloud-compute]: https://cloud.google.com/compute/ |
| 267 | +[compute-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/compute/package-summary.html |
0 commit comments