v0.5.0 - Resource Manager, Pub/Sub, Datastore

Gcloud is the official library for interacting with the Google Cloud Platform. Google Cloud Platform is a set of modular cloud-based services that allow you to create anything from simple websites to complex applications.

Gcloud's goal is to provide a API that is familiar and comfortable to Rubyists. Authentication is handled by providing project and credential information, or if you are running on Google Compute Engine this configuration is taken care of for you.

Resource Manager

Resource Manager support is added in this release. The Resource Manager API (docs) provides a way to programmatically manage your projects in the Google Cloud Platform. Resource Manager can be used to list, create, update, delete, and recover deleted projects. The API is a Beta release and is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager

# List all projects
resource_manager.projects.each do |project|
  puts projects.project_id
end

# Label a project as production
project = resource_manager.project "tokyo-rain-123"
project.update do |p|
  p.labels["env"] = "production"
end

# List only projects with the "production" label
projects = resource_manager.projects filter: "labels.env:production"

See the gcloud Resource Manager docs for more information.

Pub/Sub

Pub/Sub has also several changes. Google Cloud Pub/Sub is designed to provide reliable, many-to-many, asynchronous messaging between applications. Publisher applications can send messages to a “topic” and other applications can subscribe to that topic to receive the messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows developers to communicate between independently written applications.

• Retrieving and updating policies would raise an error. This has been fixed in this release. Thanks to @jeffmendoza for reporting the issue and contributing the fix.

• The autocreate option on Topic was changed in this release. The default value is now false, where it was true previously. The auto-create behavior has also changed and will occur on the method the autocreate option is set on, instead of on happening later on the Topic object the method returns. This means that instead of this behavior:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "not-yet-created" # autocreate used to default to true here
  topic.publish "Some message" # Topic is created in this call

  We now have this behavior:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "not-yet-created", autocreate: true # Topic is created in this call
  topic.publish "Some message"

• The skip_lookup option was added on resource lookup methods, and the different lookup methods have been merged into one. This means it is still possible to publish using a topic object while skipping the lookup API call, but it is no longer possible to auto-create the topic during the publish. Before we had:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "existing-topic" # No API call, lookup was skipped by default
  topic.publish "Some message" # API call made here

  We can match this with the following:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "existing-topic", skip_lookup: true # No API call here
  topic.publish "Some message" # API call made here

• Add Project#publish method. Since we have lost the ability to create a topic resource after the topic object has been instantiated, we have introduced Project#publish that also supports the autocreate option and maintains the number of API calls made. Previously the following code made 1 API call.

  pubsub = gcloud.pubsub
  topic = pubsub.topic "existing-topic" # No API call to retrieve topic
  topic.publish "Some message" # API call made in this call

  Now this can be accomplished with the following:

  pubsub = gcloud.pubsub
  topic = pubsub.publish "existing-topic", "Some message" # API call made in this call

  Alternatively, the previous code could auto-create a missing topic with 3 API calls:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "new-topic" # The autocreate default used to be true here
  topic.publish "Some message" # 3 API calls made to create topic and publish

  Now this can be accomplished with the following:

  pubsub = gcloud.pubsub
  # 3 API calls made to create topic and publish
  topic = pubsub.publish "new-topic", "Some message", autocreate: true

• Add Project#subscribe method. Similarly, this method accepts the autocreate option and maintains the previous number of API calls:

  pubsub = gcloud.pubsub
  topic = pubsub.topic "new-topic" # The autocreate default used to be true here
  topic.subscribe "new-sub" # 3 API calls made to create topic and subscription

  Now this can be accomplished with the following:

  pubsub = gcloud.pubsub
  # 3 API calls made to create topic and subscription
  topic = pubsub.subscribe "new-topic", "new-sub", autocreate: true

Datastore

Datastore has several changes as well. Google Cloud Datastore is a fully managed, schemaless database for storing non-relational data. You should feel at home if you are familiar with relational databases, but there are some key differences to be aware of to make the most of using Datastore.

• Add namespace option has been added when running queries. This allows queries to run within a namespace when the option is provided. Thanks to @jondot for contributing this functionality.

  require "gcloud"
  
  gcloud = Gcloud.new
  dataset = gcloud.datastore
  
  query = Gcloud::Datastore::Query.new.kind("Task").
    where("completed", "=", true)
  tasks = dataset.run query, namespace: "ns~todo-project"

• The new methods query, entity, and key were added to Dataset. This enables a simplified syntax. Creating and saving an entity previously would look like this:

  dataset = gcloud.datastore
  
  # Create a new task to demo datastore
  demo_task = Gcloud::Datastore::Entity.new
  demo_task.key = Gcloud::Datastore::Key.new "Task", "datastore-demo"
  demo_task["description"] = "Demonstrate Datastore functionality"
  demo_task["completed"] = false
  
  # Save the new task
  dataset.save demo_task

  And with these new changes can look like this:

  dataset = gcloud.datastore
  
  # Create a new task to demo datastore
  demo_task = dataset.entity "Task", "datastore-demo" do |t|
    t["description"] = "Demonstrate Datastore functionality"
    t["completed"] = false
  end  
  
  # Save the new task
  dataset.save demo_task

  Similarly, running a query previously would look like this:

  # Create a query for all completed tasks
  query = Gcloud::Datastore::Query.new.
    kind("Task").
    where("completed", "=", true)
  
  # Run the query
  completed_tasks = dataset.run query

  and with these changes can look like this:

  # Create a query for all completed tasks
  query = dataset.query("Task").
    where("completed", "=", true)
  
  # Run the query
  completed_tasks = dataset.run query

Thank you!

Much thanks to @jeffmendoza and @jondot for their input and contributions to this release.