google-cloud-resource_manager 0.39.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,300 +0,0 @@
1
- # Copyright 2015 Google LLC
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # https://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
-
16
- require "google/cloud/errors"
17
- require "google/cloud/resource_manager/credentials"
18
- require "google/cloud/resource_manager/service"
19
- require "google/cloud/resource_manager/project"
20
- require "google/cloud/resource_manager/resource"
21
-
22
- module Google
23
- module Cloud
24
- module ResourceManager
25
- ##
26
- # # Manager
27
- #
28
- # Provides methods for creating, retrieving, and updating projects.
29
- #
30
- # @example
31
- # require "google/cloud/resource_manager"
32
- #
33
- # resource_manager = Google::Cloud::ResourceManager.new
34
- # resource_manager.projects.each do |project|
35
- # puts projects.project_id
36
- # end
37
- #
38
- # See {Google::Cloud#resource_manager}
39
- class Manager
40
- ##
41
- # @private The Service object.
42
- attr_accessor :service
43
-
44
- ##
45
- # @private Creates a new Service instance.
46
- #
47
- # See {Google::Cloud.resource_manager}
48
- def initialize service
49
- @service = service
50
- end
51
-
52
- ##
53
- # Retrieves the projects that are visible to the user and satisfy the
54
- # specified filter. This method returns projects in an unspecified
55
- # order. New projects do not necessarily appear at the end of the list.
56
- #
57
- # @param [String] filter An expression for filtering the results of the
58
- # request. Filter rules are case insensitive.
59
- #
60
- # The fields eligible for filtering are:
61
- #
62
- # * `name`
63
- # * `id`
64
- # * `labels.key` - where `key` is the name of a label
65
- #
66
- # Some examples of using labels as filters:
67
- #
68
- # * `name:*` - The project has a name.
69
- # * `name:Howl` - The project's name is Howl or howl.
70
- # * `name:HOWL` - Equivalent to above.
71
- # * `NAME:howl` - Equivalent to above.
72
- # * `labels.color:*` - The project has the label color.
73
- # * `labels.color:red` - The project's label color has the value red.
74
- # * `labels.color:red labels.size:big` - The project's
75
- # label color has the value red and its label size has the value
76
- # big.
77
- # @param [String] token A previously-returned page token representing
78
- # part of the larger set of results to view.
79
- # @param [Integer] max Maximum number of projects to return.
80
- #
81
- # @return [Array<Google::Cloud::ResourceManager::Project>] (See
82
- # {Google::Cloud::ResourceManager::Project::List})
83
- #
84
- # @example
85
- # require "google/cloud/resource_manager"
86
- #
87
- # resource_manager = Google::Cloud::ResourceManager.new
88
- # projects = resource_manager.projects
89
- #
90
- # projects.each do |project|
91
- # puts project.project_id
92
- # end
93
- #
94
- # @example Projects can be filtered using the `filter` option:
95
- # require "google/cloud/resource_manager"
96
- #
97
- # resource_manager = Google::Cloud::ResourceManager.new
98
- # projects = resource_manager.projects filter: "labels.env:production"
99
- #
100
- # projects.each do |project|
101
- # puts project.project_id
102
- # end
103
- #
104
- # @example Retrieve all projects: (See {Project::List#all})
105
- # require "google/cloud/resource_manager"
106
- #
107
- # resource_manager = Google::Cloud::ResourceManager.new
108
- # projects = resource_manager.projects
109
- #
110
- # projects.all do |project|
111
- # puts project.project_id
112
- # end
113
- #
114
- def projects filter: nil, token: nil, max: nil
115
- gapi = service.list_project filter: filter, token: token, max: max
116
- Project::List.from_gapi gapi, self, filter, max
117
- end
118
-
119
- ##
120
- # Retrieves the project identified by the specified `project_id`.
121
- #
122
- # @param [String] project_id The ID of the project.
123
- #
124
- # @return [Google::Cloud::ResourceManager::Project, nil] Returns `nil`
125
- # if the project does not exist
126
- #
127
- # @example
128
- # require "google/cloud/resource_manager"
129
- #
130
- # resource_manager = Google::Cloud::ResourceManager.new
131
- # project = resource_manager.project "tokyo-rain-123"
132
- # project.project_id #=> "tokyo-rain-123"
133
- #
134
- def project project_id
135
- gapi = service.get_project project_id
136
- Project.from_gapi gapi, service
137
- rescue NotFoundError
138
- nil
139
- end
140
-
141
- ##
142
- # Creates a project resource.
143
- #
144
- # Initially, the project resource is owned by its creator exclusively.
145
- # The creator can later grant permission to others to read or update the
146
- # project.
147
- #
148
- # Several APIs are activated automatically for the project, including
149
- # Google Cloud Storage.
150
- #
151
- # @param [String] project_id The unique, user-assigned ID of the
152
- # project. It must be 6 to 30 lowercase letters, digits, or hyphens.
153
- # It must start with a letter. Trailing hyphens are prohibited.
154
- # @param [String] name The user-assigned name of the project. This field
155
- # is optional and can remain unset.
156
- #
157
- # Allowed characters are: lowercase and uppercase letters, numbers,
158
- # hyphen, single-quote, double-quote, space, and exclamation point.
159
- # @param [Hash] labels The labels associated with this project.
160
- #
161
- # Label keys must be between 1 and 63 characters long and must conform
162
- # to the following regular expression:
163
- # `[a-z]([-a-z0-9]*[a-z0-9])?`.
164
- #
165
- # Label values must be between 0 and 63 characters long and must
166
- # conform to the regular expression
167
- # `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
168
- #
169
- # No more than 256 labels can be associated with a given resource.
170
- # @param [Resource] parent A parent Resource. Optional.
171
- #
172
- # Supported parent types include "organization" and "folder". Once
173
- # set, the parent can be updated but cannot be cleared.
174
- #
175
- # The end user must have the `resourcemanager.projects.create`
176
- # permission on the parent.
177
- #
178
- # (See {#resource} and {Resource}.)
179
- #
180
- # @return [Google::Cloud::ResourceManager::Project]
181
- #
182
- # @example
183
- # require "google/cloud/resource_manager"
184
- #
185
- # resource_manager = Google::Cloud::ResourceManager.new
186
- # project = resource_manager.create_project "tokyo-rain-123"
187
- #
188
- # @example A project can also be created with a `name` and `labels`:
189
- # require "google/cloud/resource_manager"
190
- #
191
- # resource_manager = Google::Cloud::ResourceManager.new
192
- # project = resource_manager.create_project "tokyo-rain-123",
193
- # name: "Todos Development", labels: {env: :development}
194
- #
195
- # @example A project can also be created with a `name` and `parent`:
196
- # require "google/cloud/resource_manager"
197
- #
198
- # resource_manager = Google::Cloud::ResourceManager.new
199
- # folder = resource_manager.resource "folder", "1234"
200
- # project = resource_manager.create_project "tokyo-rain-123",
201
- # name: "Todos Development", parent: folder
202
- #
203
- def create_project project_id, name: nil, labels: nil, parent: nil
204
- gapi = service.create_project project_id, name, labels, parent
205
- Project.from_gapi gapi, service
206
- end
207
-
208
- ##
209
- # Marks the project for deletion. This method will only affect the
210
- # project if the following criteria are met:
211
- #
212
- # * The project does not have a billing account associated with it.
213
- # * The project has a lifecycle state of `ACTIVE`.
214
- # * This method changes the project's lifecycle state from `ACTIVE` to
215
- # `DELETE_REQUESTED`. The deletion starts at an unspecified time, at
216
- # which point the lifecycle state changes to `DELETE_IN_PROGRESS`.
217
- #
218
- # Until the deletion completes, you can check the lifecycle state by
219
- # retrieving the project with Manager#project. The project remains
220
- # visible to Manager#project and Manager#projects, but cannot be
221
- # updated.
222
- #
223
- # After the deletion completes, the project is not retrievable by the
224
- # Manager#project and Manager#projects methods.
225
- #
226
- # The caller must have modify permissions for this project.
227
- #
228
- # @param [String] project_id The ID of the project.
229
- #
230
- # @example
231
- # require "google/cloud/resource_manager"
232
- #
233
- # resource_manager = Google::Cloud::ResourceManager.new
234
- # resource_manager.delete "tokyo-rain-123"
235
- #
236
- def delete project_id
237
- service.delete_project project_id
238
- true
239
- end
240
-
241
- ##
242
- # Restores the project. You can only use this method for a project that
243
- # has a lifecycle state of `DELETE_REQUESTED`. After deletion starts, as
244
- # indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project
245
- # cannot be restored.
246
- #
247
- # The caller must have modify permissions for this project.
248
- #
249
- # @param [String] project_id The ID of the project.
250
- #
251
- # @example
252
- # require "google/cloud/resource_manager"
253
- #
254
- # resource_manager = Google::Cloud::ResourceManager.new
255
- # resource_manager.undelete "tokyo-rain-123"
256
- #
257
- def undelete project_id
258
- service.undelete_project project_id
259
- true
260
- end
261
-
262
- ##
263
- # Create a Resource object. (See {Resource}.)
264
- #
265
- # @param [String] type The resource type this id is for. At present, the
266
- # valid types are: "organization" and "folder".
267
- # @param [String] id The type-specific id. This should correspond to the
268
- # id used in the type-specific API's.
269
- # @return [resource]
270
- #
271
- # @example
272
- # require "google/cloud/resource_manager"
273
- #
274
- # resource_manager = Google::Cloud::ResourceManager.new
275
- # project = resource_manager.project "tokyo-rain-123"
276
- # folder = resource_manager.resource "folder", "1234"
277
- # project.parent = folder
278
- #
279
- def resource type, id
280
- Resource.new type, id
281
- end
282
-
283
- protected
284
-
285
- ##
286
- # Create an options hash from the projects parameters.
287
- def list_projects_options filter, options
288
- # Handle only sending in options
289
- if filter.is_a?(::Hash) && options.empty?
290
- options = filter
291
- filter = nil
292
- end
293
- # Give named parameter priority
294
- options[:filter] = filter || options[:filter]
295
- options
296
- end
297
- end
298
- end
299
- end
300
- end
@@ -1,191 +0,0 @@
1
- # Copyright 2016 Google LLC
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # https://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
-
16
- require "google/cloud/errors"
17
- require "google/apis/cloudresourcemanager_v1"
18
-
19
- module Google
20
- module Cloud
21
- module ResourceManager
22
- ##
23
- # # Policy
24
- #
25
- # Represents a Cloud IAM Policy for the Resource Manager service.
26
- #
27
- # A common pattern for updating a resource's metadata, such as its Policy,
28
- # is to read the current data from the service, update the data locally,
29
- # and then send the modified data for writing. This pattern may result in
30
- # a conflict if two or more processes attempt the sequence simultaneously.
31
- # IAM solves this problem with the
32
- # {Google::Cloud::ResourceManager::Policy#etag} property, which is used to
33
- # verify whether the policy has changed since the last request. When you
34
- # make a request to with an `etag` value, Cloud IAM compares the `etag`
35
- # value in the request with the existing `etag` value associated with the
36
- # policy. It writes the policy only if the `etag` values match.
37
- #
38
- # When you update a policy, first read the policy (and its current `etag`)
39
- # from the service, then modify the policy locally, and then write the
40
- # modified policy to the service. See
41
- # {Google::Cloud::ResourceManager::Project#policy} and
42
- # {Google::Cloud::ResourceManager::Project#policy=}.
43
- #
44
- # @see https://cloud.google.com/iam/docs/managing-policies Managing
45
- # policies
46
- # @see https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/setIamPolicy
47
- # projects.setIamPolicy
48
- #
49
- # @attr [String] etag Used to verify whether the policy has changed since
50
- # the last request. The policy will be written only if the `etag` values
51
- # match.
52
- # @attr [Hash{String => Array<String>}] roles The bindings that associate
53
- # roles with an array of members. See [Understanding
54
- # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
55
- # listing of primitive and curated roles. See
56
- # [Binding](https://cloud.google.com/resource-manager/reference/rest/Shared.Types/Binding)
57
- # for a listing of values and patterns for members.
58
- #
59
- # @example
60
- # require "google/cloud/resource_manager"
61
- #
62
- # resource_manager = Google::Cloud::ResourceManager.new
63
- # project = resource_manager.project "tokyo-rain-123"
64
- #
65
- # project.policy do |p|
66
- # p.remove "roles/owner", "user:owner@example.com"
67
- # p.add "roles/owner", "user:newowner@example.com"
68
- # p.roles["roles/viewer"] = ["allUsers"]
69
- # end
70
- #
71
- class Policy
72
- ##
73
- # Alias to the Google Client API module
74
- API = Google::Apis::CloudresourcemanagerV1
75
-
76
- attr_reader :etag
77
- attr_reader :roles
78
-
79
- ##
80
- # @private Creates a Policy object.
81
- def initialize etag, roles
82
- @etag = etag
83
- @roles = roles
84
- end
85
-
86
- ##
87
- # Convenience method for adding a member to a binding on this policy.
88
- # See [Understanding
89
- # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
90
- # listing of primitive and curated roles. See
91
- # [Binding](https://cloud.google.com/resource-manager/reference/rest/Shared.Types/Binding)
92
- # for a listing of values and patterns for members.
93
- #
94
- # @param [String] role_name A Cloud IAM role, such as `"roles/owner"`.
95
- # @param [String] member A Cloud IAM identity, such as
96
- # `"user:owner@example.com"`.
97
- #
98
- # @example
99
- # require "google/cloud/resource_manager"
100
- #
101
- # resource_manager = Google::Cloud::ResourceManager.new
102
- # project = resource_manager.project "tokyo-rain-123"
103
- #
104
- # project.policy do |p|
105
- # p.add "roles/owner", "user:newowner@example.com"
106
- # end
107
- #
108
- def add role_name, member
109
- role(role_name) << member
110
- end
111
-
112
- ##
113
- # Convenience method for removing a member from a binding on this
114
- # policy. See [Understanding
115
- # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
116
- # listing of primitive and curated roles. See
117
- # [Binding](https://cloud.google.com/resource-manager/reference/rest/Shared.Types/Binding)
118
- # for a listing of values and patterns for members.
119
- #
120
- # @param [String] role_name A Cloud IAM role, such as `"roles/owner"`.
121
- # @param [String] member A Cloud IAM identity, such as
122
- # `"user:owner@example.com"`.
123
- #
124
- # @example
125
- # require "google/cloud/resource_manager"
126
- #
127
- # resource_manager = Google::Cloud::ResourceManager.new
128
- # project = resource_manager.project "tokyo-rain-123"
129
- #
130
- # project.policy do |p|
131
- # p.remove "roles/owner", "user:owner@example.com"
132
- # end
133
- #
134
- def remove role_name, member
135
- role(role_name).delete member
136
- end
137
-
138
- ##
139
- # Convenience method returning the array of members bound to a role in
140
- # this policy, or an empty array if no value is present for the role in
141
- # {#roles}. See [Understanding
142
- # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
143
- # listing of primitive and curated roles. See
144
- # [Binding](https://cloud.google.com/resource-manager/reference/rest/Shared.Types/Binding)
145
- # for a listing of values and patterns for members.
146
- #
147
- # @return [Array<String>] The members strings, or an empty array.
148
- #
149
- # @example
150
- # require "google/cloud/resource_manager"
151
- #
152
- # resource_manager = Google::Cloud::ResourceManager.new
153
- # project = resource_manager.project "tokyo-rain-123"
154
- #
155
- # project.policy do |p|
156
- # p.role("roles/viewer") << "user:viewer@example.com"
157
- # end
158
- #
159
- def role role_name
160
- roles[role_name] ||= []
161
- end
162
-
163
- ##
164
- # @private Convert the Policy to a
165
- # Google::Apis::CloudresourcemanagerV1::Policy.
166
- def to_gapi
167
- API::Policy.new(
168
- etag: etag,
169
- bindings: roles.keys.map do |role_name|
170
- next if roles[role_name].empty?
171
- API::Binding.new(
172
- role: role_name,
173
- members: roles[role_name].uniq
174
- )
175
- end
176
- )
177
- end
178
-
179
- ##
180
- # @private New Policy from a
181
- # Google::Apis::CloudresourcemanagerV1::Policy object.
182
- def self.from_gapi gapi
183
- roles = Array(gapi.bindings).each_with_object({}) do |binding, memo|
184
- memo[binding.role] = binding.members.to_a
185
- end
186
- new gapi.etag, roles
187
- end
188
- end
189
- end
190
- end
191
- end
@@ -1,166 +0,0 @@
1
- # Copyright 2015 Google LLC
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # https://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
-
16
- require "delegate"
17
-
18
- module Google
19
- module Cloud
20
- module ResourceManager
21
- class Project
22
- ##
23
- # Project::List is a special case Array with additional values.
24
- class List < DelegateClass(::Array)
25
- ##
26
- # If not empty, indicates that there are more projects that match
27
- # the request and this value should be passed to continue.
28
- attr_accessor :token
29
-
30
- ##
31
- # @private Create a new Project::List with an array of Project
32
- # instances.
33
- def initialize arr = []
34
- super arr
35
- end
36
-
37
- ##
38
- # Whether there is a next page of projects.
39
- #
40
- # @return [Boolean]
41
- #
42
- # @example
43
- # require "google/cloud/resource_manager"
44
- #
45
- # resource_manager = Google::Cloud::ResourceManager.new
46
- #
47
- # projects = resource_manager.projects
48
- # if projects.next?
49
- # next_projects = projects.next
50
- # end
51
- #
52
- def next?
53
- !token.nil?
54
- end
55
-
56
- ##
57
- # Retrieve the next page of projects.
58
- #
59
- # @return [Project::List]
60
- #
61
- # @example
62
- # require "google/cloud/resource_manager"
63
- #
64
- # resource_manager = Google::Cloud::ResourceManager.new
65
- #
66
- # projects = resource_manager.projects
67
- # if projects.next?
68
- # next_projects = projects.next
69
- # end
70
- #
71
- def next
72
- return nil unless next?
73
- ensure_manager!
74
- @manager.projects token: token, filter: @filter, max: @max
75
- end
76
-
77
- ##
78
- # Retrieves remaining results by repeatedly invoking {#next} until
79
- # {#next?} returns `false`. Calls the given block once for each
80
- # result, which is passed as the argument to the block.
81
- #
82
- # An Enumerator is returned if no block is given.
83
- #
84
- # This method will make repeated API calls until all remaining results
85
- # are retrieved. (Unlike `#each`, for example, which merely iterates
86
- # over the results returned by a single API call.) Use with caution.
87
- #
88
- # @param [Integer] request_limit The upper limit of API requests to
89
- # make to load all projects. Default is no limit.
90
- # @yield [project] The block for accessing each project.
91
- # @yieldparam [Project] project The project object.
92
- #
93
- # @return [Enumerator]
94
- #
95
- # @example Iterating each project by passing a block:
96
- # require "google/cloud/resource_manager"
97
- #
98
- # resource_manager = Google::Cloud::ResourceManager.new
99
- # projects = resource_manager.projects
100
- #
101
- # projects.all do |project|
102
- # puts project.project_id
103
- # end
104
- #
105
- # @example Using the enumerator by not passing a block:
106
- # require "google/cloud/resource_manager"
107
- #
108
- # resource_manager = Google::Cloud::ResourceManager.new
109
- # projects = resource_manager.projects
110
- #
111
- # all_project_ids = projects.all.map do |project|
112
- # project.project_id
113
- # end
114
- #
115
- # @example Limit the number of API calls made:
116
- # require "google/cloud/resource_manager"
117
- #
118
- # resource_manager = Google::Cloud::ResourceManager.new
119
- # projects = resource_manager.projects
120
- #
121
- # projects.all(request_limit: 10) do |project|
122
- # puts project.project_id
123
- # end
124
- #
125
- def all request_limit: nil, &block
126
- request_limit = request_limit.to_i if request_limit
127
- unless block_given?
128
- return enum_for :all, request_limit: request_limit
129
- end
130
- results = self
131
- loop do
132
- results.each(&block)
133
- if request_limit
134
- request_limit -= 1
135
- break if request_limit.negative?
136
- end
137
- break unless results.next?
138
- results = results.next
139
- end
140
- end
141
-
142
- ##
143
- # @private New Projects::List from a response object.
144
- def self.from_gapi gapi_list, manager, filter = nil, max = nil
145
- projects = new(Array(gapi_list.projects).map do |gapi_object|
146
- Project.from_gapi gapi_object, manager.service
147
- end)
148
- projects.instance_variable_set :@token, gapi_list.next_page_token
149
- projects.instance_variable_set :@manager, manager
150
- projects.instance_variable_set :@filter, filter
151
- projects.instance_variable_set :@max, max
152
- projects
153
- end
154
-
155
- protected
156
-
157
- ##
158
- # Raise an error unless an active connection is available.
159
- def ensure_manager!
160
- raise "Must have active connection" unless @manager
161
- end
162
- end
163
- end
164
- end
165
- end
166
- end