google-cloud-resource_manager 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d88720fc4e202a484570afebd31023cea2ceaa7f
+  data.tar.gz: 15661f51dc41db2875032122a1ac2c238ed516f2
+SHA512:
+  metadata.gz: 206e8448c64c92417d740ac2d94096bbb95320f5539ee56f31198581a25525d057e0f2b70f920e3a1cd6510972a7f25bb4297de9ebe98aad697321570f31e470
+  data.tar.gz: ee8b81ba5e1ab811831391fa48627ed85fec3717d22fa9009a15628617e762eaa7f37351982fb5a36f4ba05163e525b6d7b74dae3cfc4a6e41d7382127b832c4

data/lib/google-cloud-resource_manager.rb

@@ -0,0 +1,116 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+##
+# This file is here to be autorequired by bundler, so that the .bigquery and
+# #bigquery methods can be available, but the library and all dependencies won't
+# be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Resource Manager service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/cloud-platform`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::ResourceManager::Manager]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud = Google::Cloud.new
+    #   resource_manager = gcloud.resource_manager
+    #   resource_manager.projects.each do |project|
+    #     puts projects.project_id
+    #   end
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   readonly_scope = \
+    #     "https://www.googleapis.com/auth/cloudresourcemanager.readonly"
+    #   resource_manager = gcloud.resource_manager scope: readonly_scope
+    #
+    def resource_manager scope: nil, retries: nil, timeout: nil
+      Google::Cloud.resource_manager @keyfile, scope: scope,
+                                               retries: (retries || @retries),
+                                               timeout: (timeout || @timeout)
+    end
+
+    ##
+    # Creates a new `Project` instance connected to the Resource Manager
+    # service. Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+    #   file path the file must be readable.
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/cloud-platform`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::ResourceManager::Manager]
+    #
+    # @example
+    #   require "google/cloud/resource_manager"
+    #
+    #   resource_manager = Google::Cloud.resource_manager
+    #   resource_manager.projects.each do |project|
+    #     puts projects.project_id
+    #   end
+    #
+    def self.resource_manager keyfile = nil, scope: nil, retries: nil,
+                              timeout: nil
+      require "google/cloud/resource_manager"
+      if keyfile.nil?
+        credentials = Google::Cloud::ResourceManager::Credentials.default(
+          scope: scope)
+      else
+        credentials = Google::Cloud::ResourceManager::Credentials.new(
+          keyfile, scope: scope)
+      end
+      Google::Cloud::ResourceManager::Manager.new(
+        Google::Cloud::ResourceManager::Service.new(
+          credentials, retries: retries, timeout: timeout))
+    end
+  end
+end

data/lib/google/cloud/resource_manager.rb

@@ -0,0 +1,248 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google-cloud-resource_manager"
+require "google/cloud/resource_manager/manager"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud Resource Manager
+    #
+    # The Resource Manager API provides methods that you can use to
+    # programmatically manage your projects in the Google Cloud Platform. You
+    # may be familiar with managing projects in the [Developers
+    # Console](https://developers.google.com/console/help/new/). With this API
+    # you can do the following:
+    #
+    # * Get a list of all projects associated with an account
+    # * Create new projects
+    # * Update existing projects
+    # * Delete projects
+    # * Undelete, or recover, projects that you don't want to delete
+    #
+    # The Resource Manager API is a Beta release and is not covered by any SLA
+    # or deprecation policy and may be subject to backward-incompatible changes.
+    #
+    # ## Accessing the Service
+    #
+    # Currently, the full functionality of the Resource Manager API is available
+    # only to whitelisted users. (Contact your account manager or a member of
+    # the Google Cloud sales team if you are interested in access.) Read-only
+    # methods such as {ResourceManager::Manager#projects} and
+    # {ResourceManager::Manager#project} are accessible to any user who enables
+    # the Resource Manager API in the [Developers
+    # Console](https://console.developers.google.com).
+    #
+    # ## Authentication
+    #
+    # The Resource Manager API currently requires authentication of a [User
+    # Account](https://developers.google.com/identity/protocols/OAuth2), and
+    # cannot currently be accessed with a [Service
+    # Account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount).
+    # To use a User Account install the [Google Cloud
+    # SDK](http://cloud.google.com/sdk) and authenticate with the following:
+    #
+    # ```
+    # $ gcloud auth login
+    # ```
+    #
+    # Also make sure all `GCLOUD` environment variables are cleared of any
+    # service accounts. Then google-cloud will be able to detect the user
+    # authentication and connect with those credentials.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # ```
+    #
+    # ## Listing Projects
+    #
+    # Project is a collection of settings, credentials, and metadata about the
+    # application or applications you're working on. You can retrieve and
+    # inspect all projects that you have permissions to. (See
+    # {Google::Cloud::ResourceManager::Manager#projects})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # resource_manager.projects.each do |project|
+    #   puts projects.project_id
+    # end
+    # ```
+    #
+    # ## Managing Projects with Labels
+    #
+    # Labels can be added to or removed from projects. (See
+    # {Google::Cloud::ResourceManager::Project#labels})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # project = resource_manager.project "tokyo-rain-123"
+    # # Label the project as production
+    # project.update do |p|
+    #   p.labels["env"] = "production"
+    # end
+    # ```
+    #
+    # Projects can then be filtered by labels. (See
+    # {Google::Cloud::ResourceManager::Manager#projects})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # # Find only the productions projects
+    # projects = resource_manager.projects filter: "labels.env:production"
+    # projects.each do |project|
+    #   puts project.project_id
+    # end
+    # ```
+    #
+    # ## Creating a Project
+    #
+    # You can also use the API to create new projects. (See
+    # {Google::Cloud::ResourceManager::Manager#create_project})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # project = resource_manager.create_project "tokyo-rain-123",
+    #                                           name: "Todos Development",
+    #                                           labels: {env: :development}
+    # ```
+    #
+    # ## Deleting a Project
+    #
+    # You can delete projects when they are no longer needed. (See
+    # {Google::Cloud::ResourceManager::Manager#delete} and
+    # {Google::Cloud::ResourceManager::Project#delete})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # resource_manager.delete "tokyo-rain-123"
+    # ```
+    #
+    # ## Undeleting a Project
+    #
+    # You can also restore a deleted project within the waiting period that
+    # starts when the project was deleted. Restoring a project returns it to the
+    # state it was in prior to being deleted. (See
+    # {Google::Cloud::ResourceManager::Manager#undelete} and
+    # {Google::Cloud::ResourceManager::Project#undelete})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # resource_manager.undelete "tokyo-rain-123"
+    # ```
+    #
+    # ## Configuring retries and timeout
+    #
+    # You can configure how many times API requests may be automatically
+    # retried. When an API request fails, the response will be inspected to see
+    # if the request meets criteria indicating that it may succeed on retry,
+    # such as `500` and `503` status codes or a specific internal error code
+    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
+    # retried after a delay. If another error occurs, the delay will be
+    # increased before a subsequent attempt, until the `retries` limit is
+    # reached.
+    #
+    # You can also set the request `timeout` value in seconds.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager retries: 10, timeout: 120
+    # ```
+    #
+    # See the [Resource Manager error
+    # messages](https://cloud.google.com/resource-manager/docs/core_errors)
+    # for a list of error conditions.
+    #
+    # ## Managing IAM Policies
+    #
+    # Google Cloud Identity and Access Management ([Cloud
+    # IAM](https://cloud.google.com/iam/)) access control policies can be
+    # managed on projects. These policies allow project owners to manage _who_
+    # (identity) has access to _what_ (role). See [Cloud IAM
+    # Overview](https://cloud.google.com/iam/docs/overview) for more
+    # information.
+    #
+    # A project's access control policy can be retrieved. (See
+    # {Google::Cloud::ResourceManager::Project#policy} and
+    # {Google::Cloud::ResourceManager::Policy}.)
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # project = resource_manager.project "tokyo-rain-123"
+    # policy = project.policy
+    # ```
+    #
+    # A project's access control policy can also be updated:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # project = resource_manager.project "tokyo-rain-123"
+    #
+    # policy = project.policy do |p|
+    #   p.add "roles/viewer", "serviceAccount:your-service-account"
+    # end
+    # ```
+    #
+    # And permissions can be tested on a project. (See
+    # {Google::Cloud::ResourceManager::Project#test_permissions})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # resource_manager = gcloud.resource_manager
+    # project = resource_manager.project "tokyo-rain-123"
+    # perms = project.test_permissions "resourcemanager.projects.get",
+    #                                  "resourcemanager.projects.delete"
+    # perms.include? "resourcemanager.projects.get"    #=> true
+    # perms.include? "resourcemanager.projects.delete" #=> false
+    # ```
+    #
+    # For more information about using access control policies see [Managing
+    # Policies](https://cloud.google.com/iam/docs/managing-policies).
+    #
+    module ResourceManager
+    end
+  end
+end

data/lib/google/cloud/resource_manager/credentials.rb

@@ -0,0 +1,32 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/credentials"
+
+module Google
+  module Cloud
+    module ResourceManager
+      ##
+      # @private Represents the Oauth2 signing logic for Resource Manager.
+      class Credentials < Google::Cloud::Credentials
+        SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
+        PATH_ENV_VARS = %w(RESOURCE_MANAGER_KEYFILE
+                           GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(RESOURCE_MANAGER_KEYFILE_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON GCLOUD_KEYFILE_JSON)
+      end
+    end
+  end
+end

data/lib/google/cloud/resource_manager/manager.rb

@@ -0,0 +1,270 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/errors"
+require "google/cloud/resource_manager/credentials"
+require "google/cloud/resource_manager/service"
+require "google/cloud/resource_manager/project"
+
+module Google
+  module Cloud
+    module ResourceManager
+      ##
+      # # Manager
+      #
+      # Provides methods for creating, retrieving, and updating projects.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   resource_manager.projects.each do |project|
+      #     puts projects.project_id
+      #   end
+      #
+      # See {Google::Cloud#resource_manager}
+      class Manager
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Service instance.
+        #
+        # See {Google::Cloud.resource_manager}
+        def initialize service
+          @service = service
+        end
+
+        ##
+        # Retrieves the projects that are visible to the user and satisfy the
+        # specified filter. This method returns projects in an unspecified
+        # order. New projects do not necessarily appear at the end of the list.
+        #
+        # @param [String] filter An expression for filtering the results of the
+        #   request. Filter rules are case insensitive.
+        #
+        #   The fields eligible for filtering are:
+        #
+        #   * `name`
+        #   * `id`
+        #   * `labels.key` - where `key` is the name of a label
+        #
+        #   Some examples of using labels as filters:
+        #
+        #   * `name:*` - The project has a name.
+        #   * `name:Howl` - The project's name is Howl or howl.
+        #   * `name:HOWL` - Equivalent to above.
+        #   * `NAME:howl` - Equivalent to above.
+        #   * `labels.color:*` - The project has the label color.
+        #   * `labels.color:red` - The project's label color has the value red.
+        #   * <code>labels.color:red labels.size:big</code> - The project's
+        #     label color has the value red and its label size has the value
+        #     big.
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of projects to return.
+        #
+        # @return [Array<Google::Cloud::ResourceManager::Project>] (See
+        #   {Google::Cloud::ResourceManager::Project::List})
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   projects = resource_manager.projects
+        #
+        #   projects.each do |project|
+        #     puts project.project_id
+        #   end
+        #
+        # @example Projects can be filtered using the `filter` option:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   projects = resource_manager.projects filter: "labels.env:production"
+        #
+        #   projects.each do |project|
+        #     puts project.project_id
+        #   end
+        #
+        # @example Retrieve all projects: (See {Project::List#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   projects = resource_manager.projects
+        #
+        #   projects.all do |project|
+        #     puts project.project_id
+        #   end
+        #
+        def projects filter: nil, token: nil, max: nil
+          gapi = service.list_project filter: filter, token: token, max: max
+          Project::List.from_gapi gapi, self, filter, max
+        end
+
+        ##
+        # Retrieves the project identified by the specified `project_id`.
+        #
+        # @param [String] project_id The ID of the project.
+        #
+        # @return [Google::Cloud::ResourceManager::Project, nil] Returns `nil`
+        #   if the project does not exist
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   project = resource_manager.project "tokyo-rain-123"
+        #   project.project_id #=> "tokyo-rain-123"
+        #
+        def project project_id
+          gapi = service.get_project project_id
+          Project.from_gapi gapi, service
+        rescue NotFoundError
+          nil
+        end
+
+        ##
+        # Creates a project resource.
+        #
+        # Initially, the project resource is owned by its creator exclusively.
+        # The creator can later grant permission to others to read or update the
+        # project.
+        #
+        # Several APIs are activated automatically for the project, including
+        # Google Cloud Storage.
+        #
+        # @param [String] project_id The unique, user-assigned ID of the
+        #   project. It must be 6 to 30 lowercase letters, digits, or hyphens.
+        #   It must start with a letter. Trailing hyphens are prohibited.
+        # @param [String] name The user-assigned name of the project. This field
+        #   is optional and can remain unset.
+        #
+        #   Allowed characters are: lowercase and uppercase letters, numbers,
+        #   hyphen, single-quote, double-quote, space, and exclamation point.
+        # @param [Hash] labels The labels associated with this project.
+        #
+        #   Label keys must be between 1 and 63 characters long and must conform
+        #   to the following regular expression:
+        #   <code>[a-z]([-a-z0-9]*[a-z0-9])?</code>.
+        #
+        #   Label values must be between 0 and 63 characters long and must
+        #   conform to the regular expression
+        #   <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>.
+        #
+        #   No more than 256 labels can be associated with a given resource.
+        #
+        # @return [Google::Cloud::ResourceManager::Project]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   project = resource_manager.create_project "tokyo-rain-123"
+        #
+        # @example A project can also be created with a `name` and `labels`:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   project = resource_manager.create_project "tokyo-rain-123",
+        #     name: "Todos Development", labels: {env: :development}
+        #
+        def create_project project_id, name: nil, labels: nil
+          gapi = service.create_project project_id, name, labels
+          Project.from_gapi gapi, service
+        end
+
+        ##
+        # Marks the project for deletion. This method will only affect the
+        # project if the following criteria are met:
+        #
+        # * The project does not have a billing account associated with it.
+        # * The project has a lifecycle state of `ACTIVE`.
+        # * This method changes the project's lifecycle state from `ACTIVE` to
+        #   `DELETE_REQUESTED`. The deletion starts at an unspecified time, at
+        #   which point the lifecycle state changes to `DELETE_IN_PROGRESS`.
+        #
+        # Until the deletion completes, you can check the lifecycle state by
+        # retrieving the project with Manager#project. The project remains
+        # visible to Manager#project and Manager#projects, but cannot be
+        # updated.
+        #
+        # After the deletion completes, the project is not retrievable by the
+        # Manager#project and Manager#projects methods.
+        #
+        # The caller must have modify permissions for this project.
+        #
+        # @param [String] project_id The ID of the project.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   resource_manager.delete "tokyo-rain-123"
+        #
+        def delete project_id
+          service.delete_project project_id
+          true
+        end
+
+        ##
+        # Restores the project. You can only use this method for a project that
+        # has a lifecycle state of `DELETE_REQUESTED`. After deletion starts, as
+        # indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project
+        # cannot be restored.
+        #
+        # The caller must have modify permissions for this project.
+        #
+        # @param [String] project_id The ID of the project.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   resource_manager = gcloud.resource_manager
+        #   resource_manager.undelete "tokyo-rain-123"
+        #
+        def undelete project_id
+          service.undelete_project project_id
+          true
+        end
+
+        protected
+
+        ##
+        # Create an options hash from the projects parameters.
+        def list_projects_options filter, options
+          # Handle only sending in options
+          if filter.is_a?(::Hash) && options.empty?
+            options = filter
+            filter = nil
+          end
+          # Give named parameter priority
+          options[:filter] = filter || options[:filter]
+          options
+        end
+      end
+    end
+  end
+end