cloud-mu 2.1.0beta → 3.0.0beta

data/modules/mu/clouds/google/habitat.rb

@@ -17,27 +17,19 @@ module MU
     class Google
       # Creates an Google project as configured in {MU::Config::BasketofKittens::habitats}
       class Habitat < MU::Cloud::Habitat
-        @deploy = nil
-        @config = nil
-
-        attr_reader :mu_name
-        attr_reader :config
-        attr_reader :cloud_id
-
-        # @param mommacat [MU::MommaCat]: A {MU::Mommacat} object containing the deploy of which this resource is/will be a member.
-        # @param kitten_cfg [Hash]: The fully parsed and resolved {MU::Config} resource descriptor as defined in {MU::Config::BasketofKittens::habitats}
-        def initialize(mommacat: nil, kitten_cfg: nil, mu_name: nil, cloud_id: nil)
-          @deploy = mommacat
-          @config = MU::Config.manxify(kitten_cfg)
-          @cloud_id ||= cloud_id
-
-          if !mu_name.nil?
-            @mu_name = mu_name
-          elsif @config['scrub_mu_isms']
-            @mu_name = @config['name']
-          else
-            @mu_name = @deploy.getResourceName(@config['name'])
+
+        # Initialize this cloud resource object. Calling +super+ will invoke the initializer defined under {MU::Cloud}, which should set the attribtues listed in {MU::Cloud::PUBLIC_ATTRS} as well as applicable dependency shortcuts, like <tt>@vpc</tt>, for us.
+        # @param args [Hash]: Hash of named arguments passed via Ruby's double-splat
+        def initialize(**args)
+          super
+          cloud_desc if @cloud_id # XXX maybe this isn't my job
+
+          # XXX this definitely isn't my job
+          if !@cloud_id and cloud_desc and cloud_desc.project_id
+            @cloud_id = cloud_desc.project_id
           end
+
+          @mu_name ||= @deploy.getResourceName(@config['name'])
         end
 
         # Called automatically by {MU::Deploy#createResources}
@@ -47,12 +39,13 @@ module MU
           name_string = if @config['scrub_mu_isms']
             @config["name"]
           else
-            @deploy.getResourceName(@config["name"], max_length: 30).downcase
+            @deploy.getResourceName(@config["name"], max_length: 30)
           end
+          display_name = @config['display_name'] || name_string.gsub(/[^a-z0-9\-'"\s!]/i, "-")
 
           params = {
-            name: name_string,
-            project_id: name_string,
+            name: display_name,
+            project_id: name_string.downcase.gsub(/[^0-9a-z\-]/, "-")
           }
 
           MU::MommaCat.listStandardTags.each_pair { |name, value|
@@ -65,6 +58,9 @@ module MU
             params[:labels] = labels
           end
 
+          if @config['parent']['name'] and !@config['parent']['id']
+            @config['parent']['deploy_id'] = @deploy.deploy_id
+          end
           parent = MU::Cloud::Google::Folder.resolveParent(@config['parent'], credentials: @config['credentials'])
           if !parent
             MU.log "Unable to resolve parent resource of Google Project #{@config['name']}", MU::ERR, details: @config['parent']
@@ -79,22 +75,31 @@ module MU
 
           project_obj = MU::Cloud::Google.resource_manager(:Project).new(params)
 
-          MU.log "Creating project #{name_string} under #{parent}", details: project_obj
-          MU::Cloud::Google.resource_manager(credentials: @config['credentials']).create_project(project_obj)
+          MU.log "Creating project #{params[:project_id]} (#{params[:name]}) under #{parent} (#{@config['credentials']})", details: project_obj
+
+          begin
+            pp MU::Cloud::Google.resource_manager(credentials: @config['credentials']).create_project(project_obj)
+          rescue ::Google::Apis::ClientError => e
+            MU.log "Got #{e.message} attempting to create #{params[:project_id]}", MU::ERR, details: project_obj
+          end
 
 
           found = false
           retries = 0
           begin
-            resp = MU::Cloud::Google.resource_manager(credentials: credentials).list_projects
+# can... can we filter this?
+            resp = MU::Cloud::Google.resource_manager(credentials: credentials).list_projects(filter: "id:#{name_string.downcase.gsub(/[^0-9a-z\-]/, "-")}")
             if resp and resp.projects
               resp.projects.each { |p|
-                if p.name == name_string.downcase
+                if p.project_id ==  name_string.downcase.gsub(/[^0-9a-z\-]/, "-")
                   found = true
                 end
               }
             end
             if !found
+              if retries > 30
+                raise MuError, "Project #{name_string} never showed up in list_projects after I created it!"
+              end
               if retries > 0 and (retries % 3) == 0
                 MU.log "Waiting for Google Cloud project #{name_string} to appear in list_projects results...", MU::NOTICE
               end
@@ -104,8 +109,16 @@ module MU
           end while !found
 
 
-          @cloud_id = name_string.downcase
-          setProjectBilling
+          @cloud_id = params[:project_id]
+          @habitat_id = parent_id
+          begin
+            setProjectBilling
+          rescue Exception => e
+            MU.log "Failed to set billing account #{@config['billing_acct']} on project #{@cloud_id}: #{e.message}", MU::ERR
+            MU::Cloud::Google.resource_manager(credentials: @config['credentials']).delete_project(@cloud_id)
+            raise e
+          end
+          MU.log "Project #{params[:project_id]} (#{params[:name]}) created"
         end
 
         # Called automatically by {MU::Deploy#createResources}
@@ -113,6 +126,18 @@ module MU
           setProjectBilling
         end
 
+        # Retrieve the IAM bindings for this project (associates between IAM roles and groups/users)
+        def bindings
+          MU::Cloud::Google::Habitat.bindings(@cloud_id, credentials: @config['credentials'])
+        end
+
+        # Retrieve the IAM bindings for this project (associates between IAM roles and groups/users)
+        # @param project [String]:
+        # @param credentials [String]:
+        def self.bindings(project, credentials: nil)
+          MU::Cloud::Google.resource_manager(credentials: credentials).get_project_iam_policy(project).bindings
+        end
+
         # Associate a billing account with this project. If none is specified in
         # our configuration, use the billing account tied the the default
         # project of our credential set.
@@ -130,17 +155,26 @@ module MU
               project_id: @cloud_id
             )
             MU.log "Associating project #{@cloud_id} with billing account #{@config['billing_acct']}"
-            MU::Cloud::Google.billing(credentials: credentials).update_project_billing_info(
-              "projects/"+@cloud_id,
-              billing_obj
-            )
+            begin
+              MU::Cloud::Google.billing(credentials: credentials).update_project_billing_info(
+                "projects/"+@cloud_id,
+                billing_obj
+              )
+            rescue ::Google::Apis::ClientError => e
+              MU.log "Error setting billing for #{@cloud_id}: "+e.message, MU::ERR, details: billing_obj
+            end
 
           end
         end
 
         # Return the cloud descriptor for the Habitat
+        # @return [Google::Apis::Core::Hashable]
         def cloud_desc
-          MU::Cloud::Google::Habitat.find(cloud_id: @cloud_id).values.first
+          @cached_cloud_desc ||= MU::Cloud::Google::Habitat.find(cloud_id: @cloud_id).values.first
+          if @cached_cloud_desc and @cached_cloud_desc.parent
+            @habitat_id ||= @cached_cloud_desc.parent.id
+          end
+          @cached_cloud_desc
         end
 
         # Return the metadata for this project's configuration
@@ -159,7 +193,27 @@ module MU
         # Denote whether this resource implementation is experiment, ready for
         # testing, or ready for production use.
         def self.quality
-          MU::Cloud::BETA
+          MU::Cloud::RELEASE
+        end
+
+        # Check whether is in the +ACTIVE+ state and has billing enabled.
+        # @param project_id [String]
+        # @return [Boolean]
+        def self.isLive?(project_id, credentials = nil)
+          project = MU::Cloud::Google::Habitat.find(cloud_id: project_id, credentials: credentials).values.first
+          return false if project.nil? or project.lifecycle_state != "ACTIVE"
+
+          begin
+            billing = MU::Cloud::Google.billing(credentials: credentials).get_project_billing_info("projects/"+project_id)
+            if !billing or !billing.billing_account_name or
+               billing.billing_account_name.empty?
+              return false
+            end
+          rescue ::Google::Apis::ClientError => e
+            return false
+          end
+
+          true
         end
 
         # Remove all Google projects associated with the currently loaded deployment. Try to, anyway.
@@ -173,15 +227,16 @@ module MU
             resp.projects.each { |p|
               if p.labels and p.labels["mu-id"] == MU.deploy_id.downcase and
                  p.lifecycle_state == "ACTIVE"
-                MU.log "Deleting project #{p.name}", details: p
+                MU.log "Deleting project #{p.project_id} (#{p.name})", details: p
                 if !noop
                   begin
-                    MU::Cloud::Google.resource_manager(credentials: credentials).delete_project(p.name)
+                    MU::Cloud::Google.resource_manager(credentials: credentials).delete_project(p.project_id)
                   rescue ::Google::Apis::ClientError => e
                     if e.message.match(/Cannot delete an inactive project/)
                       # this is fine
                     else
-                      raise e
+                      MU.log "Got #{e.message} trying to delete project #{p.project_id} (#{p.name})", MU::ERR
+                      next
                     end
                   end
                 end
@@ -190,28 +245,94 @@ module MU
           end
         end
 
+        @@list_projects_cache = nil
+
         # Locate an existing project
-        # @param cloud_id [String]: The cloud provider's identifier for this resource.
-        # @param region [String]: The cloud provider region.
-        # @param flags [Hash]: Optional flags
-        # @return [OpenStruct]: The cloud provider's complete descriptions of matching project
-        def self.find(cloud_id: nil, region: MU.curRegion, credentials: nil, flags: {}, tag_key: nil, tag_value: nil)
+        # @return [Hash<OpenStruct>]: The cloud provider's complete descriptions of matching project
+        def self.find(**args)
+          args[:project] ||= args[:habitat]
+          args[:cloud_id] ||= args[:project]
+#MU.log "habitat.find called by #{caller[0]}", MU::WARN, details: args
           found = {}
-          if cloud_id
-            resp = MU::Cloud::Google.resource_manager(credentials: credentials).list_projects(
-              filter: "name:#{cloud_id}"
+
+# XXX we probably want to cache this
+# XXX but why are we being called over and over?
+
+          if args[:cloud_id]
+            resp = MU::Cloud::Google.resource_manager(credentials: args[:credentials]).list_projects(
+              filter: "id:#{args[:cloud_id]}"
             )
-            found[resp.name] = resp.projects.first if resp and resp.projects
+
+            if resp and resp.projects and resp.projects.size == 1
+              found[args[:cloud_id]] = resp.projects.first if resp and resp.projects
+            else
+              # it's loony that there's no filter for project_number
+              resp = MU::Cloud::Google.resource_manager(credentials: args[:credentials]).list_projects
+              resp.projects.each { |p|
+                if p.project_number.to_s == args[:cloud_id].to_s
+                  found[args[:cloud_id]] = p
+                  break
+                end
+              }
+            end
           else
-            resp = MU::Cloud::Google.resource_manager(credentials: credentials).list_projects().projects
-            resp.each { |p|
-              found[p.name] = p
+            return @@list_projects_cache if @@list_projects_cache # XXX decide on stale-ness after time or something
+            resp = MU::Cloud::Google.resource_manager(credentials: args[:credentials]).list_projects#(page_token: page_token)
+            resp.projects.each { |p|
+              next if p.lifecycle_state == "DELETE_REQUESTED"
+              found[p.project_id] = p
             }
+            @@list_projects_cache = found
           end
-          
+
           found
         end
 
+        # Reverse-map our cloud description into a runnable config hash.
+        # We assume that any values we have in +@config+ are placeholders, and
+        # calculate our own accordingly based on what's live in the cloud.
+        def toKitten(rootparent: nil, billing: nil, habitats: nil)
+          bok = {
+            "cloud" => "Google",
+            "credentials" => @config['credentials']
+          }
+
+          bok['name'] = cloud_desc.project_id
+          bok['cloud_id'] = cloud_desc.project_id
+#          if cloud_desc.name != cloud_desc.project_id
+            bok['display_name'] = cloud_desc.name
+#          end
+
+          if cloud_desc.parent and cloud_desc.parent.id
+            if cloud_desc.parent.type == "folder"
+              bok['parent'] = MU::Config::Ref.get(
+                id: "folders/"+cloud_desc.parent.id, # honestly, Google, make up your mind about your identifiers
+                cloud: "Google",
+                credentials: @config['credentials'],
+                type: "folders"
+              )
+            elsif rootparent
+              bok['parent'] = {
+                'id' => rootparent.is_a?(String) ? rootparent : rootparent.cloud_desc.name
+              }
+            else
+              # org parent is *probably* safe to infer from credentials
+            end
+          end
+
+          if billing
+            bok['billing_acct'] = billing
+          else
+            cur_billing = MU::Cloud::Google.billing(credentials: @config['credentials']).get_project_billing_info("projects/"+@cloud_id)
+            if cur_billing and cur_billing.billing_account_name
+              bok['billing_acct'] = cur_billing.billing_account_name.sub(/^billingAccounts\//, '')
+            end
+          end
+
+          bok
+        end
+
+
         # Cloud-specific configuration properties.
         # @param config [MU::Config]: The calling MU::Config object
         # @return [Array<Array,Hash>]: List of required fields, and json-schema Hash of cloud-specific configuration parameters for this resource
@@ -221,6 +342,10 @@ module MU
             "billing_acct" => {
               "type" => "string",
               "description" => "Billing account ID to associate with a newly-created Google Project. If not specified, will attempt to locate a billing account associated with the default project for our credentials."
+            },
+            "display_name" => {
+              "type" => "string",
+              "description" => "A human readable name for this project. If not specified, will default to our long-form deploy-generated name."
             }
           }
           [toplevel_required, schema]
@@ -234,7 +359,7 @@ module MU
           ok = true
 
           if !MU::Cloud::Google.getOrg(habitat['credentials'])
-            MU.log "Cannot manage Google Cloud projects in environments without an organization. See also: https://cloud.google.com/resource-manager/docs/creating-managing-organization", MU::ERR
+            MU.log "Cannot manage Google Cloud folders in environments without an organization", MU::ERR
             ok = false
           end
 

data/modules/mu/clouds/google/loadbalancer.rb

@@ -18,41 +18,18 @@ module MU
       # A load balancer as configured in {MU::Config::BasketofKittens::loadbalancers}
       class LoadBalancer < MU::Cloud::LoadBalancer
 
-        @project_id = nil
-        @deploy = nil
         @lb = nil
-        attr_reader :mu_name
-        attr_reader :config
-        attr_reader :cloud_id
         attr_reader :targetgroups
 
-        @cloudformation_data = {}
-        attr_reader :cloudformation_data
-
-        # @param mommacat [MU::MommaCat]: A {MU::Mommacat} object containing the deploy of which this resource is/will be a member.
-        # @param kitten_cfg [Hash]: The fully parsed and resolved {MU::Config} resource descriptor as defined in {MU::Config::BasketofKittens::loadbalancers}
-        def initialize(mommacat: nil, kitten_cfg: nil, mu_name: nil, cloud_id: nil)
-          @deploy = mommacat
-          @config = MU::Config.manxify(kitten_cfg)
-          @cloud_id ||= cloud_id
-          if !mu_name.nil?
-            @mu_name = mu_name
-            @config['project'] ||= MU::Cloud::Google.defaultProject(@config['credentials'])
-            if !@project_id
-              project = MU::Cloud::Google.projectLookup(@config['project'], @deploy, sibling_only: true, raise_on_fail: false)
-              @project_id = project.nil? ? @config['project'] : project.cloudobj.cloud_id
-            end
-          elsif @config['scrub_mu_isms']
-            @mu_name = @config['name']
-          else
-            @mu_name = @deploy.getResourceName(@config["name"])
-          end
+        # Initialize this cloud resource object. Calling +super+ will invoke the initializer defined under {MU::Cloud}, which should set the attribtues listed in {MU::Cloud::PUBLIC_ATTRS} as well as applicable dependency shortcuts, like <tt>@vpc</tt>, for us.
+        # @param args [Hash]: Hash of named arguments passed via Ruby's double-splat
+        def initialize(**args)
+          super
+          @mu_name ||= @deploy.getResourceName(@config["name"])
         end
 
         # Called automatically by {MU::Deploy#createResources}
         def create
-          @project_id = MU::Cloud::Google.projectLookup(@config['project'], @deploy).cloudobj.cloud_id
-
           parent_thread_id = Thread.current.object_id
 
           backends = {}
@@ -81,7 +58,7 @@ module MU
             if !@config["private"]
 #TODO ip_address, port_range, target
               realproto = ["HTTP", "HTTPS"].include?(l['lb_protocol']) ? l['lb_protocol'] : "TCP"
-              ruleobj = ::Google::Apis::ComputeBeta::ForwardingRule.new(
+              ruleobj = ::Google::Apis::ComputeV1::ForwardingRule.new(
                 name: MU::Cloud::Google.nameStr(@mu_name+"-"+l['targetgroup']),
                 description: @deploy.deploy_id,
                 load_balancing_scheme: "EXTERNAL",
@@ -91,7 +68,7 @@ module MU
               )
             else
 # TODO network, subnetwork, port_range, target
-              ruleobj = ::Google::Apis::ComputeBeta::ForwardingRule.new(
+              ruleobj = ::Google::Apis::ComputeV1::ForwardingRule.new(
                 name: MU::Cloud::Google.nameStr(@mu_name+"-"+l['targetgroup']),
                 description: @deploy.deploy_id,
                 load_balancing_scheme: "INTERNAL",
@@ -118,10 +95,6 @@ module MU
 
         end
 
-        # Wrapper that fetches the API's description of one of these things
-        def cloud_desc
-        end
-
         # Return the metadata for this LoadBalancer
         # @return [Hash]
         def notify
@@ -175,6 +148,7 @@ module MU
         # @return [void]
         def self.cleanup(noop: false, ignoremaster: false, region: nil, credentials: nil, flags: {})
           flags["project"] ||= MU::Cloud::Google.defaultProject(credentials)
+          return if !MU::Cloud::Google::Habitat.isLive?(flags["project"], credentials)
 
           if region
             ["forwarding_rule", "region_backend_service"].each { |type|
@@ -192,6 +166,7 @@ module MU
               MU::Cloud::Google.compute(credentials: credentials).delete(
                 type,
                 flags["project"],
+                nil,
                 noop
               )
             }

data/modules/mu/clouds/google/role.rb

@@ -0,0 +1,1211 @@
+# Copyright:: Copyright (c) 2019 eGlobalTech, Inc., all rights reserved
+#
+# Licensed under the BSD-3 license (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License in the root of the project or at
+#
+#     http://egt-labs.com/mu/LICENSE.html
+#
+# 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.
+
+module MU
+  class Cloud
+    class Google
+      # A role as configured in {MU::Config::BasketofKittens::roles}
+      class Role < MU::Cloud::Role
+
+        # Initialize this cloud resource object. Calling +super+ will invoke the initializer defined under {MU::Cloud}, which should set the attribtues listed in {MU::Cloud::PUBLIC_ATTRS} as well as applicable dependency shortcuts, like <tt>@vpc</tt>, for us.
+        # @param args [Hash]: Hash of named arguments passed via Ruby's double-splat
+        def initialize(**args)
+          super
+
+          @mu_name ||= if !@config['scrub_mu_isms']
+            @deploy.getResourceName(@config["name"])
+          else
+            @config['name']
+          end
+
+          # If we're being reverse-engineered from a cloud descriptor, use that
+          # to determine what sort of account we are.
+          if args[:from_cloud_desc]
+            @cloud_desc_cache = args[:from_cloud_desc]
+            if args[:from_cloud_desc].class == ::Google::Apis::AdminDirectoryV1::Role
+              @config['role_source'] = "directory"
+            elsif args[:from_cloud_desc].name.match(/^roles\/(.*)/) or
+                  (@cloud_id and @cloud_id.match(/^roles\/(.*)/))
+              @config['role_source'] = "canned"
+              @config['name'] = Regexp.last_match[1]
+            elsif args[:from_cloud_desc].name.match(/^organizations\/\d+\/roles\/(.*)/) or
+                  (@cloud_id and @cloud_id.match(/^organizations\/\d+\/roles\/(.*)/))
+              @config['role_source'] = "org"
+              @config['name'] = Regexp.last_match[1]
+            elsif args[:from_cloud_desc].name.match(/^projects\/([^\/]+?)\/roles\/(.*)/) or
+                  (@cloud_id and @cloud_id.match(/^projects\/\d+\/roles\/(.*)/))
+              @config['project'] = Regexp.last_match[1]
+              @config['name'] = Regexp.last_match[2]
+              @project_id = @config['project']
+              @config['role_source'] = "project"
+            else
+              MU.log "I don't know what to do with this #{args[:from_cloud_desc].class.name}", MU::ERR, details: args[:from_cloud_desc]
+              raise MuError, "I don't know what to do with this #{args[:from_cloud_desc].class.name}"
+            end
+          end
+        end
+
+        # Called automatically by {MU::Deploy#createResources}
+        def create
+          @config['display_name'] ||= @mu_name
+          if @config['role_source'] == "directory"
+            role_obj = MU::Cloud::Google.admin_directory(:Role).new(
+              role_name: @mu_name,
+              role_description: @config['display_name'],
+              role_privileges: MU::Cloud::Google::Role.map_directory_privileges(@config['import'], credentials: @credentials).first
+            )
+            MU.log "Creating directory role #{@mu_name}", details: role_obj
+
+            resp = MU::Cloud::Google.admin_directory(credentials: @credentials).insert_role(@customer, role_obj)
+            @cloud_id = resp.role_id.to_s
+
+          elsif @config['role_source'] == "canned"
+            @cloud_id = @config['name']
+            if !@cloud_id.match(/^roles\//)
+              @cloud_id = "roles/"+@cloud_id
+            end
+          else
+            create_role_obj = MU::Cloud::Google.iam(:CreateRoleRequest).new(
+              role: MU::Cloud::Google.iam(:Role).new(
+                title: @config['display_name'],
+                description: @config['description']
+              ),
+              role_id: MU::Cloud::Google.nameStr(@deploy.getResourceName(@config["name"], max_length: 64)).gsub(/[^a-zA-Z0-9_\.]/, "_")
+            )
+
+            resp = if @config['role_source'] == "org"
+              my_org = MU::Cloud::Google.getOrg(@config['credentials'])
+              MU.log "Creating IAM organization role #{@mu_name} in #{my_org.display_name}", details: create_role_obj
+              resp = MU::Cloud::Google.iam(credentials: @credentials).create_organization_role(my_org.name, create_role_obj)
+            elsif @config['role_source'] == "project"
+              if !@project_id
+                raise MuError, "Role #{@mu_name} is supposed to be in project #{@config['project']}, but no such project was found"
+              end
+              MU.log "Creating IAM project role #{@mu_name} in #{@project_id}", details: create_role_obj
+              MU::Cloud::Google.iam(credentials: @credentials).create_project_role("projects/"+@project_id, create_role_obj)
+            end
+
+            @cloud_id = resp.name
+
+          end
+        end
+
+        # Called automatically by {MU::Deploy#createResources}
+        def groom
+          if @config['role_source'] == "directory"
+#            MU.log "Updating directory role #{@mu_name}", MU::NOTICE, details: role_obj
+#            MU::Cloud::Google.admin_directory(credentials: @credentials).patch_role(@customer, @cloud_id, role_obj)
+          elsif @config['role_source'] == "org"
+          elsif @config['role_source'] == "project"
+          elsif @config['role_source'] == "canned"
+          end
+
+          @config['bindings'].each { |binding|
+            binding.keys.each { |scopetype|
+              next if scopetype == "entity"
+              binding[scopetype].each { |scope|
+# XXX handle entity being a MU::Config::Ref
+                entity_id = if binding["entity"]["name"]
+                  sib = @deploy.findLitterMate(name: binding["entity"]["name"], type: binding["entity"]["type"])
+                  raise MuError, "Failed to look up sibling #{binding["entity"]["type"]}:#{binding["entity"]["name"]}" if !sib
+                  if binding["entity"]["type"] == "users" and sib.config["type"] == "service"
+                    binding["entity"]["type"] = "serviceAccount"
+                  end
+                  sib.cloud_id
+                else
+                  binding["entity"]["id"]
+                end
+# XXX resolve scope as well, if it's named or a MU::Config::Ref
+                bindToIAM(binding["entity"]["type"], entity_id.sub(/.*?\/([^\/]+)$/, '\1'), scopetype, scope["id"])
+              }
+            }
+          }
+        end
+
+        # Return the cloud descriptor for the Role
+        # @return [Google::Apis::Core::Hashable]
+        def cloud_desc
+          return @cloud_desc_cache if @cloud_desc_cache
+
+          my_org = MU::Cloud::Google.getOrg(@config['credentials'])
+
+          @cloud_desc_cache = if @config['role_source'] == "directory"
+            MU::Cloud::Google.admin_directory(credentials: @config['credentials']).get_role(@customer, @cloud_id)
+          elsif @config['role_source'] == "canned"
+            MU::Cloud::Google.iam(credentials: @config['credentials']).get_role(@cloud_id)
+          elsif @config['role_source'] == "project"
+            MU::Cloud::Google.iam(credentials: @config['credentials']).get_project_role(@cloud_id)
+          elsif @config['role_source'] == "org"
+            MU::Cloud::Google.iam(credentials: @config['credentials']).get_organization_role(@cloud_id)
+          end
+
+          @cloud_desc_cache
+        end
+
+        # Return the metadata for this group configuration
+        # @return [Hash]
+        def notify
+          base = MU.structToHash(cloud_desc)
+          base.delete(:etag)
+          base["cloud_id"] = @cloud_id
+
+          base
+        end
+
+        # Wrapper for #{MU::Cloud::Google::Role.bindToIAM}
+        def bindToIAM(entity_type, entity_id, scope_type, scope_id)
+          MU::Cloud::Google::Role.bindToIAM(@cloud_id, entity_type, entity_id, scope_type, scope_id, credentials: @config['credentials'])
+        end
+
+        @@role_bind_semaphore = Mutex.new
+        @@role_bind_scope_semaphores = {}
+
+        # Attach a role to an entity
+        # @param role_id [String]: The cloud identifier of the role to which we're binding
+        # @param entity_type [String]: The kind of entity to bind; typically user, group, or domain
+        # @param entity_id [String]: The cloud identifier of the entity
+        # @param scope_type [String]: The kind of scope in which this binding will be valid; typically project, folder, or organization
+        # @param scope_id [String]: The cloud identifier of the scope in which this binding will be valid
+        # @param credentials [String]:
+        def self.bindToIAM(role_id, entity_type, entity_id, scope_type, scope_id, credentials: nil, debug: false)
+          loglevel = debug ? MU::NOTICE : MU::DEBUG
+
+          MU.log "Google::Role.bindToIAM(role_id: #{role_id}, entity_type: #{entity_type}, entity_id: #{entity_id}, scope_type: #{scope_type}, scope_id: #{scope_id}, credentials: #{credentials})", loglevel
+
+          # scope_id might actually be the name of a credential set; if so, we
+          # map it back to an actual organization on the fly
+          if scope_type == "organizations"
+            my_org = MU::Cloud::Google.getOrg(scope_id)
+            if my_org
+              scope_id = my_org.name
+            end
+          end
+
+          @@role_bind_semaphore.synchronize {
+            @@role_bind_scope_semaphores[scope_id] ||= Mutex.new
+          }
+
+          @@role_bind_scope_semaphores[scope_id].synchronize {
+            entity = entity_type.sub(/s$/, "")+":"+entity_id
+            policy = if scope_type == "organizations"
+              MU::Cloud::Google.resource_manager(credentials: credentials).get_organization_iam_policy(scope_id)
+            elsif scope_type == "folders"
+              MU::Cloud::Google.resource_manager(credentials: credentials).get_folder_iam_policy(scope_id)
+            elsif scope_type == "projects"
+              if !scope_id
+                raise MuError, "Google::Role.bindToIAM was called without a scope_id"
+              elsif scope_id.is_a?(Hash)
+                if scope_id["id"]
+                  scope_id = scope_id["id"]
+                else
+                  raise MuError, "Google::Role.bindToIAM was called with a scope_id Ref hash that has no id field"
+                end
+              end
+              MU::Cloud::Google.resource_manager(credentials: credentials).get_project_iam_policy(scope_id.sub(/^projects\//, ""))
+            else
+              puts "WTF DO WIT #{scope_type}"
+            end
+
+            saw_role = false
+            policy.bindings.each { |binding|
+              if binding.role == role_id 
+                saw_role = true
+                if binding.members.include?(entity)
+                  return # it's already bound, nothing needs doing
+                else
+                  binding.members << entity
+                end
+              end
+            }
+            if !saw_role
+              policy.bindings <<  MU::Cloud::Google.resource_manager(:Binding).new(
+                role: role_id,
+                members: [entity]
+              )
+            end
+            MU.log "Granting #{role_id} to #{entity} in #{scope_id}", MU::NOTICE
+            req_obj = MU::Cloud::Google.resource_manager(:SetIamPolicyRequest).new(
+              policy: policy
+            )
+            policy = if scope_type == "organizations"
+              MU::Cloud::Google.resource_manager(credentials: credentials).set_organization_iam_policy(
+                scope_id,
+                req_obj
+              )
+            elsif scope_type == "folders"
+              MU::Cloud::Google.resource_manager(credentials: credentials).set_folder_iam_policy(
+                scope_id,
+                req_obj
+              )
+            elsif scope_type == "projects"
+              MU::Cloud::Google.resource_manager(credentials: credentials).set_project_iam_policy(
+                scope_id,
+                req_obj
+              )
+            end
+          }
+        end
+
+        # Remove all bindings for the specified entity
+        # @param entity_type [String]: The kind of entity to bind; typically user, group, or domain
+        # @param entity_id [String]: The cloud identifier of the entity
+        # @param credentials [String]:
+        # @param noop [Boolean]: Just say what we'd do without doing it
+        def self.removeBindings(entity_type, entity_id, credentials: nil, noop: false)
+
+          scopes = {}
+
+          my_org = MU::Cloud::Google.getOrg(credentials)
+          if my_org
+            scopes["organizations"] = [my_org.name]
+            folders = MU::Cloud::Google::Folder.find(credentials: credentials)
+            if folders and folders.size > 0
+              scopes["folders"] = folders.keys
+            end
+          end
+
+          projects = MU::Cloud::Google::Habitat.find(credentials: credentials)
+          if projects and projects.size > 0
+            scopes["projects"] = projects.keys
+          end
+
+          scopes.each_pair { |scope_type, scope_ids|
+            scope_ids.each { |scope_id|
+              @@role_bind_semaphore.synchronize {
+                @@role_bind_scope_semaphores[scope_id] ||= Mutex.new
+              }
+
+              @@role_bind_scope_semaphores[scope_id].synchronize {
+                entity = entity_type.sub(/s$/, "")+":"+entity_id
+                policy = if scope_type == "organizations"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).get_organization_iam_policy(my_org.name)
+                elsif scope_type == "folders"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).get_folder_iam_policy(scope_id)
+                elsif scope_type == "projects"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).get_project_iam_policy(scope_id)
+                end
+
+                need_update = false
+                policy.bindings.each { |binding|
+                  if binding.members.include?(entity)
+                    MU.log "Unbinding #{binding.role} from #{entity} in #{scope_id}"
+                    need_update = true
+                    binding.members.delete(entity)
+                  end
+                }
+# XXX maybe drop bindings with 0 members?
+                next if !need_update or noop
+                req_obj = MU::Cloud::Google.resource_manager(:SetIamPolicyRequest).new(
+                  policy: policy
+                )
+
+                policy = if scope_type == "organizations"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).set_organization_iam_policy(
+                    scope_id,
+                    req_obj
+                  )
+                elsif scope_type == "folders"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).set_folder_iam_policy(
+                    scope_id,
+                    req_obj
+                  )
+                elsif scope_type == "projects"
+                  MU::Cloud::Google.resource_manager(credentials: credentials).set_project_iam_policy(
+                    scope_id,
+                    req_obj
+                  )
+                end
+              }
+
+            }
+          }
+        end
+
+        # Add role bindings for a given entity from its BoK config
+        # @param entity_type [String]: The kind of entity to bind; typically user, group, or domain
+        # @param entity_id [String]: The cloud identifier of the entity
+        # @param cfg [Hash]: A configuration block confirming to our own {MU::Cloud::Google::Role.ref_schema}
+        # @param credentials [String]:
+        def self.bindFromConfig(entity_type, entity_id, cfg, credentials: nil, deploy: nil, debug: false)
+          loglevel = debug ? MU::NOTICE : MU::DEBUG
+
+          bindings = []
+
+          return if !cfg
+          MU.log "Google::Role::bindFromConfig binding called for #{entity_type} #{entity_id}", loglevel, details: cfg
+
+          cfg.each { |binding|
+            if deploy and binding["role"]["name"] and !binding["role"]["id"]
+              role_obj = deploy.findLitterMate(name: binding["role"]["name"], type: "roles")
+              binding["role"]["id"] = role_obj.cloud_id if role_obj
+            end
+            ["organizations", "projects", "folders"].each { |scopetype|
+              next if !binding[scopetype]
+
+              binding[scopetype].each { |scope|
+# XXX resolution of Ref bits (roles, projects, and folders anyway; organizations and domains are direct)
+                MU::Cloud::Google::Role.bindToIAM(
+                  binding["role"]["id"],
+                  entity_type,
+                  entity_id,
+                  scopetype,
+                  scope,
+                  credentials: credentials
+                )
+              }
+            }
+            if binding["directories"]
+              binding["directories"].each { |dir|
+                # this is either an organization cloud_id, or the name of one
+                # of our credential sets, which we must map to an organization
+                # cloud id
+                creds = MU::Cloud::Google.credConfig(dir)
+
+                customer = if creds
+                  my_org = MU::Cloud::Google.getOrg(dir)
+                  if !my_org
+                    raise MuError, "Google directory role binding specified directory #{dir}, which looks like one of our credential sets, but does not appear to map to an organization!"
+                  end
+                  my_org.owner.directory_customer_id
+                elsif dir.match(/^organizations\//)
+                  # Not sure if there's ever a case where we can do this with
+                  # an org that's different from the one our credentials go with
+                  my_org = MU::Cloud::Google.getOrg(credentials, with_id: dir)
+                  if !my_org
+                    raise MuError, "Failed to retrieve #{dir} with credentials #{credentials} in Google directory role binding for role #{binding["role"].to_s}"
+                  end
+                  my_org.owner.directory_customer_id
+                else
+                  # assume it's a raw customer id and hope for the best
+                  dir
+                end
+
+                if !binding["role"]["id"].match(/^\d+$/)
+                  resp = MU::Cloud::Google.admin_directory(credentials: credentials).list_roles(customer)
+                  if resp and resp.items
+                    resp.items.each { |role|
+                      if role.role_name == binding["role"]["id"]
+                        binding["role"]["id"] = role.role_id
+                        break
+                      end
+                    }
+                  end
+                end
+
+                # Ensure we're using the stupid internal id, instead of the
+                # email field (which is the "real" id most of the time)
+                real_id = nil
+                if entity_type == "group"
+                  found = MU::Cloud::Google::Group.find(cloud_id: entity_id, credentials: credentials)
+                  if found[entity_id]
+                    real_id = found[entity_id].id
+                  end
+                elsif entity_type == "user"
+                  found = MU::Cloud::Google::User.find(cloud_id: entity_id, credentials: credentials)
+                  if found[entity_id]
+                    real_id = found[entity_id].id
+                  end
+                else
+                  raise MuError, "I don't know how to identify entity type #{entity_type} with id #{entity_id} in directory role binding"
+                end
+                real_id ||= entity_id # fingers crossed
+
+                assign_obj = MU::Cloud::Google.admin_directory(:RoleAssignment).new(
+                  assigned_to: real_id,
+                  role_id: binding["role"]["id"],
+                  scope_type: "CUSTOMER"
+                )
+# XXX guard this mess
+                MU.log "Binding directory role #{(binding["role"]["name"] || binding["role"]["id"])} to #{entity_type} #{entity_id} in #{dir}", details: assign_obj
+                MU::Cloud::Google.admin_directory(credentials: credentials).insert_role_assignment(
+                  customer,
+                  assign_obj
+                )
+
+              }
+            end
+          }
+
+# XXX whattabout GSuite-tier roles?
+        end
+
+        # Does this resource type exist as a global (cloud-wide) artifact, or
+        # is it localized to a region/zone?
+        # @return [Boolean]
+        def self.isGlobal?
+          true
+        end
+
+        # Return the list of "container" resource types in which this resource
+        # can reside. The list will include an explicit nil if this resource
+        # can exist outside of any container.
+        # @return [Array<Symbol,nil>]
+        def self.canLiveIn
+          [nil, :Habitat, :Folder]
+        end
+
+        # Denote whether this resource implementation is experiment, ready for
+        # testing, or ready for production use.
+        def self.quality
+          MU::Cloud::RELEASE
+        end
+
+        # Remove all roles associated with the currently loaded deployment.
+        # @param noop [Boolean]: If true, will only print what would be done
+        # @param ignoremaster [Boolean]: If true, will remove resources not flagged as originating from this Mu server
+        # @param region [String]: The cloud provider region
+        # @return [void]
+        def self.cleanup(noop: false, ignoremaster: false, region: MU.curRegion, credentials: nil, flags: {})
+          customer = MU::Cloud::Google.customerID(credentials)
+          my_org = MU::Cloud::Google.getOrg(credentials)
+
+          if flags['known']
+            flags['known'].each { |id|
+              next if id.nil?
+              # GCP roles don't have a useful field for packing in our deploy
+              # id, so if we have metadata to leverage for this, use it. For
+              # directory roles, we try to make it into the name field, so
+              # we'll check that later, but for org and project roles this is 
+              # our only option.
+              if my_org and id.is_a?(Integer) or id.match(/^\d+/)
+                begin
+                  resp = MU::Cloud::Google.admin_directory(credentials: credentials).get_role(customer, id)
+                rescue ::Google::Apis::ClientError => e
+                  next if e.message.match(/notFound/)
+                  raise e
+                end
+                if resp
+                  MU.log "Deleting directory role #{resp.role_name}"
+                  if !noop
+                    MU::Cloud::Google.admin_directory(credentials: credentials).delete_role(customer, id)
+                  end
+                end
+              elsif id.match(/^projects\//)
+                begin
+                  resp = MU::Cloud::Google.iam(credentials: credentials).get_project_role(id)
+                rescue ::Google::Apis::ClientError => e
+#MU.log e.message, MU::ERR, details: id
+#next
+                  next if e.message.match(/notFound/)
+                  raise e
+                end
+                if resp
+                  MU.log "Deleting project role #{resp.name}"
+                  if !noop
+                    MU::Cloud::Google.iam(credentials: credentials).delete_project_role(id)
+                  end
+                end
+              elsif id.match(/^organizations\//)
+                begin
+                  resp = MU::Cloud::Google.iam(credentials: credentials).get_organization_role(id)
+                rescue ::Google::Apis::ClientError => e
+#MU.log e.message, MU::ERR, details: id
+#next
+                  next if e.message.match(/notFound/)
+                  raise e
+                end
+                if resp
+                  MU.log "Deleting organization role #{resp.name}"
+                  if !noop
+                    MU::Cloud::Google.iam(credentials: credentials).delete_organization_role(id)
+                  end
+                end
+              end
+            }
+          end
+
+          if my_org and MU.deploy_id and !MU.deploy_id.empty?
+            resp = MU::Cloud::Google.admin_directory(credentials: credentials).list_roles(customer)
+            if resp and resp.items
+              resp.items.each { |role|
+                if role.role_name.match(/^#{Regexp.quote(MU.deploy_id)}/)
+                  MU.log "Deleting directory role #{role.role_name}"
+                  if !noop
+                    MU::Cloud::Google.admin_directory(credentials: credentials).delete_role(customer, role.role_id)
+                  end
+                end
+              }
+            end
+          end
+
+        end
+
+        # Locate and return cloud provider descriptors of this resource type
+        # which match the provided parameters, or all visible resources if no
+        # filters are specified. At minimum, implementations of +find+ must
+        # honor +credentials+ and +cloud_id+ arguments. We may optionally
+        # support other search methods, such as +tag_key+ and +tag_value+, or
+        # cloud-specific arguments like +project+. See also {MU::MommaCat.findStray}.
+        # @param args [Hash]: Hash of named arguments passed via Ruby's double-splat
+        # @return [Hash<String,OpenStruct>]: The cloud provider's complete descriptions of matching resources
+        def self.find(**args)
+          credcfg = MU::Cloud::Google.credConfig(args[:credentials])
+          customer = MU::Cloud::Google.customerID(args[:credentials])
+          my_org = MU::Cloud::Google.getOrg(args[:credentials])
+
+          found = {}
+          args[:project] ||= args[:habitat]
+
+          if args[:project]
+            canned = Hash[MU::Cloud::Google.iam(credentials: args[:credentials]).list_roles.roles.map { |r| [r.name, r] }]
+            begin
+              MU::Cloud::Google::Habitat.bindings(args[:project], credentials: args[:credentials]).each { |binding|
+                found[binding.role] = canned[binding.role]
+              }
+            rescue ::Google::Apis::ClientError => e
+              raise e if !e.message.match(/forbidden: /)
+            end
+
+            resp = begin
+              MU::Cloud::Google.iam(credentials: args[:credentials]).list_project_roles("projects/"+args[:project])
+            rescue ::Google::Apis::ClientError => e
+              raise e if !e.message.match(/forbidden: /)
+            end
+            if resp and resp.roles
+              resp.roles.each { |role|
+                found[role.name] = role
+              }
+            end
+            if args[:cloud_id]
+              found.reject! { |k, v| k != role.name }
+            end
+
+            # Now go get everything that's bound here
+            bindings = MU::Cloud::Google::Role.getAllBindings(args[:credentials])
+            if bindings and bindings['by_scope'] and
+               bindings['by_scope']['projects'] and
+               bindings['by_scope']['projects'][args[:project]]
+              bindings['by_scope']['projects'][args[:project]].keys.each { |r|
+                if r.match(/^roles\//)
+                  role = MU::Cloud::Google.iam(credentials: args[:credentials]).get_role(r)
+                  found[role.name] = role
+                elsif !found[r]
+                  MU.log "NEED TO GET #{r}", MU::WARN
+                end
+              }
+            end
+          else
+            if credcfg['masquerade_as']
+              if args[:cloud_id]
+                begin
+                  resp = MU::Cloud::Google.admin_directory(credentials: args[:credentials]).get_role(customer, args[:cloud_id].to_i)
+                  if resp
+                    found[args[:cloud_id].to_s] = resp
+                  end
+                rescue ::Google::Apis::ClientError => e
+                  raise e if !e.message.match(/(?:forbidden|notFound): /)
+                end
+              else
+                resp = MU::Cloud::Google.admin_directory(credentials: args[:credentials]).list_roles(customer)
+                if resp and resp.items
+                  resp.items.each { |role|
+                    found[role.role_id.to_s] = role
+                  }
+                end
+              end
+
+            end
+#            These are the canned roles
+            resp = begin
+              MU::Cloud::Google.iam(credentials: args[:credentials]).list_roles
+            rescue ::Google::Apis::ClientError => e
+              raise e if !e.message.match(/forbidden: /)
+            end
+            if resp
+              resp.roles.each { |role|
+                found[role.name] = role
+              }
+            end
+
+            resp = begin
+              MU::Cloud::Google.iam(credentials: args[:credentials]).list_organization_roles(my_org.name)
+            rescue ::Google::Apis::ClientError => e
+              raise e if !e.message.match(/forbidden: /)
+            end
+            if resp and resp.roles
+              resp.roles.each { |role|
+                found[role.name] = role
+              }
+            end
+          end
+
+          found
+        end
+
+        # Reverse-map our cloud description into a runnable config hash.
+        # We assume that any values we have in +@config+ are placeholders, and
+        # calculate our own accordingly based on what's live in the cloud.
+        def toKitten(rootparent: nil, billing: nil, habitats: nil)
+          bok = {
+            "cloud" => "Google",
+            "credentials" => @config['credentials'],
+            "cloud_id" => @cloud_id
+          }
+
+          my_org = MU::Cloud::Google.getOrg(@config['credentials'])
+
+          # This can happen if the role_source isn't set correctly. This logic
+          # maybe belongs inside cloud_desc. XXX
+          if cloud_desc.nil?
+            if @cloud_id and @cloud_id.match(/^roles\/(.*)/)
+              @config['role_source'] = "canned"
+            elsif @cloud_id and @cloud_id.match(/^organizations\/\d+\/roles\/(.*)/)
+              @config['role_source'] = "org"
+            elsif @cloud_id and @cloud_id.match(/^projects\/\d+\/roles\/(.*)/)
+              @config['role_source'] = "project"
+            end
+          end
+
+          # GSuite or Cloud Identity role
+          if cloud_desc.class == ::Google::Apis::AdminDirectoryV1::Role
+            return nil if cloud_desc.is_system_role
+
+            bok["name"] = @config['name'].gsub(/[^a-z0-9]/i, '-').downcase
+            bok['role_source'] = "directory"
+            bok["display_name"] = @config['name']
+            if !cloud_desc.role_description.empty?
+              bok["description"] = cloud_desc.role_description
+            end
+            if !cloud_desc.role_privileges.nil? and !cloud_desc.role_privileges.empty?
+              bok['import'] = []
+              ids, names, privs = MU::Cloud::Google::Role.privilege_service_to_name(@config['credentials'])
+              cloud_desc.role_privileges.each { |priv|
+                if !ids[priv.service_id]
+                  MU.log "Role privilege defined for a service id with no name I can find, writing with raw id", MU::WARN, details: priv
+                  bok["import"] << priv.service_id+"/"+priv.privilege_name
+                else
+                  bok["import"] << ids[priv.service_id]+"/"+priv.privilege_name
+                end
+              }
+              bok['import'].sort! # at least be legible
+            end
+          else # otherwise it's a GCP IAM role of some kind
+
+            return nil if cloud_desc.stage == "DISABLED"
+            if cloud_desc.name.match(/^roles\/([^\/]+)$/)
+              name = Regexp.last_match[1]
+              bok['name'] = name.gsub(/[^a-z0-9]/i, '-')
+              bok['role_source'] = "canned"
+            elsif cloud_desc.name.match(/^([^\/]+?)\/([^\/]+?)\/roles\/(.*)/)
+              junk, type, parent, name = Regexp.last_match.to_a
+              bok['name'] = name.gsub(/[^a-z0-9]/i, '-')
+              bok['role_source'] = type == "organizations" ? "org" : "project"
+              if bok['role_source'] == "project"
+                bok['project'] = parent
+              end
+              if cloud_desc.included_permissions and cloud_desc.included_permissions.size > 0
+                bok['import'] = cloud_desc.included_permissions
+              end
+
+            else
+              raise MuError, "I don't know how to parse GCP IAM role identifier #{cloud_desc.name}"
+            end
+
+            if !cloud_desc.description.nil? and !cloud_desc.description.empty?
+              bok["description"] = cloud_desc.description
+            end
+            bok["display_name"] = cloud_desc.title
+
+            bindings = MU::Cloud::Google::Role.getAllBindings(@config['credentials'])["by_role"][@cloud_id]
+
+            if bindings
+              refmap = {}
+              bindings.keys.each { |scopetype|
+                bindings[scopetype].each_pair { |scope_id, entity_types|
+                  # If we've been given a habitat filter, skip over bindings
+                  # that don't match it.
+                  if scopetype == "projects" and habitats and
+                     !habitats.empty? and !habitats.include?(scope_id)
+                    next
+                  end
+
+                  entity_types.each_pair { |entity_type, entities|
+                    mu_entitytype = (entity_type == "serviceAccount" ? "user" : entity_type)+"s"
+                    entities.each { |entity|
+                      entity_ref = if entity_type == "organizations"
+                        { "id" => ((org == my_org.name and @config['credentials']) ? @config['credentials'] : org) }
+                      elsif entity_type == "domain"
+                        { "id" => entity }
+                      else
+                        MU::Config::Ref.get(
+                          id: entity,
+                          cloud: "Google",
+                          type: mu_entitytype
+                        )
+                      end
+                      refmap ||= {}
+                      refmap[entity_ref] ||= {}
+                      refmap[entity_ref][scopetype] ||= []
+                      mu_scopetype = scopetype == "projects" ? "habitats" : scopetype
+                      if scopetype == "organizations" or scopetype == "domains" # XXX singular? plural? barf
+                        refmap[entity_ref][scopetype] << ((scope_id == my_org.name and @config['credentials']) ? @config['credentials'] : scope_id)
+                      else
+                        refmap[entity_ref][scopetype] << MU::Config::Ref.get(
+                          id: scope_id,
+                          cloud: "Google",
+                          type: mu_scopetype
+                        )
+                      end
+                      refmap[entity_ref][scopetype].uniq!
+                    }
+                  }
+                }
+              }
+              bok["bindings"] ||= []
+              refmap.each_pair { |entity, scopes|
+                newbinding = { "entity" => entity }
+                scopes.keys.each { |scopetype|
+                  newbinding[scopetype] = scopes[scopetype].sort
+                }
+                bok["bindings"] << newbinding
+              }
+            end
+          end
+
+          # Our only reason for declaring canned roles is so we can put their
+          # bindings somewhere. If there aren't any, then we don't need
+          # to bother with them.
+          if bok['role_source'] == "canned" and
+             (bok['bindings'].nil? or bok['bindings'].empty?)
+            return nil
+          end
+
+          bok
+        end
+
+
+        # Schema used by +user+ and +group+ entities to reference role
+        # assignments and their scopes.
+        # @return [<Hash>]
+        def self.ref_schema
+          {
+            "type" => "object",
+            "description" => "One or more Google IAM roles to associate with this entity. IAM roles in Google can be associated at the project (+Habitat+), folder, or organization level, so we must specify not only role, but each container in which it is granted to the entity in question.",
+            "properties" => {
+              "role" => MU::Config::Ref.schema(type: "roles"),
+              "projects" => {
+                "type" => "array",
+                "items" => MU::Config::Ref.schema(type: "habitats")
+              },
+              "folders" => {
+                "type" => "array",
+                "items" => MU::Config::Ref.schema(type: "folders")
+              },
+              "organizations" => {
+                "type" => "array",
+                "items" => {
+                  "type" => "string",
+                  "description" => "Either an organization cloud identifier, like +organizations/123456789012+, or the name of set of Mu credentials listed in +mu.yaml+, which can be used as an alias to the organization to which they authenticate."
+                }
+              }
+            }
+          }
+        end
+
+        @@binding_semaphore = Mutex.new
+        @@bindings_by_role = {}
+        @@bindings_by_entity = {}
+        @@bindings_by_scope = {}
+
+        # Retrieve IAM role bindings for all entities throughout our
+        # organization, map them in useful ways, and cache the result.
+        def self.getAllBindings(credentials = nil, refresh: false)
+          my_org = MU::Cloud::Google.getOrg(credentials)
+          @@binding_semaphore.synchronize {
+            if @@bindings_by_role.size > 0 and !refresh
+              return {
+                "by_role" => @@bindings_by_role.dup,
+                "by_scope" => @@bindings_by_scope.dup,
+                "by_entity" => @@bindings_by_entity.dup
+              }
+            end
+
+            def self.insertBinding(scopetype, scope, binding = nil, member_type: nil, member_id: nil, role_id: nil)
+              role_id = binding.role if binding
+              @@bindings_by_scope[scopetype] ||= {}
+              @@bindings_by_scope[scopetype][scope] ||= {}
+              @@bindings_by_scope[scopetype][scope][role_id] ||= {}
+              @@bindings_by_role[role_id] ||= {}
+              @@bindings_by_role[role_id][scopetype] ||= {}
+              @@bindings_by_role[role_id][scopetype][scope] ||= {}
+
+              do_binding = Proc.new { |type, id|
+                @@bindings_by_role[role_id][scopetype][scope][type] ||= []
+                @@bindings_by_role[role_id][scopetype][scope][type] << id
+                @@bindings_by_scope[scopetype][scope][role_id][type] ||= []
+                @@bindings_by_scope[scopetype][scope][role_id][type] << id
+                @@bindings_by_entity[type] ||= {}
+                @@bindings_by_entity[type][id] ||= {}
+                @@bindings_by_entity[type][id][role_id] ||= {}
+                @@bindings_by_entity[type][id][role_id][scopetype] ||= []
+                @@bindings_by_entity[type][id][role_id][scopetype] << scope
+              }
+
+              if binding
+                binding.members.each { |member|
+                  member_type, member_id = member.split(/:/)
+                  do_binding.call(member_type, member_id)
+                }
+              elsif member_type and member_id
+                do_binding.call(member_type, member_id)
+              end
+
+            end
+
+            if my_org
+              resp = MU::Cloud::Google.admin_directory(credentials: credentials).list_role_assignments(MU::Cloud::Google.customerID(credentials))
+
+              resp.items.each { |binding|
+
+                begin
+                  user = MU::Cloud::Google.admin_directory(credentials: credentials).get_user(binding.assigned_to)
+                  insertBinding("directories", my_org.name, member_id: user.primary_email, member_type: "user", role_id: binding.role_id.to_s)
+                  next
+                rescue ::Google::Apis::ClientError # notFound
+                end
+
+                begin
+                  group = MU::Cloud::Google.admin_directory(credentials: credentials).get_group(binding.assigned_to)
+                  MU.log "GROUP", MU::NOTICE, details: group
+#                  insertBinding("directories", my_org.name, member_id: group.primary_email, member_type: "group", role_id: binding.role_id.to_s)
+                  next
+                rescue ::Google::Apis::ClientError # notFound
+                end
+
+                role = MU::Cloud::Google.admin_directory(credentials: credentials).get_role(MU::Cloud::Google.customerID(credentials), binding.role_id)
+                MU.log "Failed to find entity #{binding.assigned_to} referenced in GSuite/Cloud Identity binding to role #{role.role_name}", MU::WARN, details: role
+              }
+
+              resp = MU::Cloud::Google.resource_manager(credentials: credentials).get_organization_iam_policy(my_org.name)
+              resp.bindings.each { |binding|
+                insertBinding("organizations", my_org.name, binding)
+              }
+
+              MU::Cloud::Google::Folder.find(credentials: credentials).keys.each { |folder|
+                MU::Cloud::Google::Folder.bindings(folder, credentials: credentials).each { |binding|
+                  insertBinding("folders", folder, binding)
+                }
+              }
+            end
+            MU::Cloud::Google::Habitat.find(credentials: credentials).keys.each { |project|
+              begin
+                MU::Cloud::Google::Habitat.bindings(project, credentials: credentials).each { |binding|
+                  insertBinding("projects", project, binding)
+                }
+              rescue ::Google::Apis::ClientError => e
+                if e.message.match(/forbidden: /)
+                  MU.log "Do not have permissions to retrieve bindings in project #{project}, skipping", MU::WARN
+                else
+                  raise e
+                end
+              end
+
+            }
+
+            return {
+              "by_role" => @@bindings_by_role.dup,
+              "by_scope" => @@bindings_by_scope.dup,
+              "by_entity" => @@bindings_by_entity.dup
+            }
+          }
+        end
+
+        # Convert a list of bindings of the type returned by {MU::Cloud::Google::Role.getAllBindings} into valid configuration language.
+        # @param roles [Hash]
+        # @param credentials [String]
+        # @return [Hash]
+        def self.entityBindingsToSchema(roles, credentials: nil)
+          my_org = MU::Cloud::Google.getOrg(credentials)
+          role_cfg = []
+
+          roles.each_pair { |role, scopes|
+            rolemap = { }
+            rolemap["role"] = if !role.is_a?(Integer) and role.match(/^roles\//)
+              # generally referring to a canned GCP role
+              { "id" => role.to_s }
+            elsif role.is_a?(Integer) or role.match(/^\d+$/)
+              # If this is a GSuite/Cloud Identity system role, reference it by
+              # its human-readable name intead of its numeric id
+              role_desc = MU::Cloud::Google::Role.find(cloud_id: role, credentials: credentials).values.first
+              if role_desc.is_system_role
+                { "id" => role_desc.role_name }
+              else
+                MU::Config::Ref.get(
+                  id: role,
+                  cloud: "Google",
+                  credentials: credentials,
+                  type: "roles"
+                )
+              end
+            else
+              # Possi-probably something we're declaring elsewhere in this
+              # adopted Mu stack
+              MU::Config::Ref.get(
+                id: role,
+                cloud: "Google",
+                credentials: credentials,
+                type: "roles"
+              )
+            end
+            scopes.each_pair { |scopetype, places|
+              if places.size > 0
+                rolemap[scopetype] = []
+                if scopetype == "organizations" or scopetype == "directories"
+                  places.each { |org|
+                    rolemap[scopetype] << ((org == my_org.name and credentials) ? credentials : org)
+                  }
+                else
+                  places.each { |place|
+                    mu_type = scopetype == "projects" ? "habitats" : scopetype
+                    rolemap[scopetype] << MU::Config::Ref.get(
+                      id: place,
+                      cloud: "Google",
+                      credentials: credentials,
+                      type: mu_type
+                    )
+                  }
+                end
+              end
+            }
+            role_cfg << rolemap
+          }
+
+          role_cfg
+        end
+
+        # Cloud-specific configuration properties.
+        # @param config [MU::Config]: The calling MU::Config object
+        # @return [Array<Array,Hash>]: List of required fields, and json-schema Hash of cloud-specific configuration parameters for this resource
+        def self.schema(config)
+          toplevel_required = []
+          schema = {
+            "name" => {
+              "pattern" => '^[a-zA-Z0-9\-\.\/]+$'
+            },
+            "display_name" => {
+              "type" => "string",
+              "description" => "A human readable name for this role. If not specified, will default to our long-form deploy-generated name."
+            },
+            "role_source" => {
+              "type" => "string",
+              "description" => "Google effectively has four types of roles:
+              
++directory+: An admin role in GSuite or Cloud Identity
+
++org+: A custom organization-level IAM role. Note that these are only valid in GSuite or Cloud Identity environments
+
++project+: A custom project-level IAM role.
+
++canned+: A reference to one of the standard pre-defined IAM roles, usually only declared to apply {bindings} to other artifacts.
+
+If this value is not specified, and the role name matches the name of an existing +canned+ role, we will assume it should be +canned+. If it does not, and we have credentials which map to a valid organization, we will assume +org+; if the credentials do not map to an organization, we will assume +project+.",
+              "enum" => ["directory", "org", "project", "canned"]
+            },
+            "description" => {
+              "type" => "string",
+              "description" => "Detailed human-readable description of this role's purpose"
+            },
+            "bindings" => {
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "description" => "One or more entities (+user+, +group+, etc) to associate with this role. IAM roles in Google can be associated at the project (+Habitat+), folder, or organization level, so we must specify not only the target entity, but each container in which it is granted to the entity in question.",
+                "properties" => {
+                  "entity" => MU::Config::Ref.schema,
+                  "projects" => {
+                    "type" => "array",
+                    "items" => MU::Config::Ref.schema(type: "habitats")
+                  },
+                  "folders" => {
+                    "type" => "array",
+                    "items" => MU::Config::Ref.schema(type: "folders")
+                  },
+                  "organizations" => {
+                    "type" => "array",
+                    "items" => {
+                      "type" => "string",
+                      "description" => "Either an organization cloud identifier, like +organizations/123456789012+, or the name of set of Mu credentials, which can be used as an alias to the organization to which they authenticate."
+                    }
+                  }
+                }
+              }
+            }
+          }
+          [toplevel_required, schema]
+        end
+
+        # Cloud-specific pre-processing of {MU::Config::BasketofKittens::roles}, bare and unvalidated.
+        # @param role [Hash]: The resource to process and validate
+        # @param configurator [MU::Config]: The overall deployment configurator of which this resource is a member
+        # @return [Boolean]: True if validation succeeded, False otherwise
+        def self.validateConfig(role, configurator)
+          ok = true
+
+          credcfg = MU::Cloud::Google.credConfig(role['credentials'])
+
+          my_org = MU::Cloud::Google.getOrg(role['credentials'])
+          if !role['role_source']
+            begin
+              lookup_name = role['name'].dup
+              if !lookup_name.match(/^roles\//)
+                lookup_name = "roles/"+lookup_name
+              end
+              canned = MU::Cloud::Google.iam(credentials: role['credentials']).get_role(lookup_name)
+              MU.log "Role #{role['name']} appears to be a referenced to canned role #{role.name} (#{role.title})", MU::NOTICE
+              role['role_source'] = "canned"
+            rescue ::Google::Apis::ClientError
+              role['role_source'] = my_org ? "org" : "project"
+            end
+          end
+
+          if role['role_source'] == "canned"
+            if role['bindings'].nil? or role['bindings'].empty?
+              MU.log "Role #{role['name']} appears to refer to a canned role, but does not have any bindings declared- this will effectively do nothing.", MU::WARN
+            end
+          end
+
+          if role['role_source'] == "directory" 
+
+            if role['import'] and role['import'].size > 0
+              mappings, missing = map_directory_privileges(role['import'], credentials: role['credentials'])
+              if mappings.size == 0
+                MU.log "None of the directory service privileges available to credentials #{role['credentials']} map to the ones declared for role #{role['name']}", MU::ERR, details: role['import'].sort
+                ok = false
+              elsif missing.size > 0
+                MU.log "Some directory service privileges declared for role #{role['name']} aren't available to credentials #{role['credentials']}, will skip", MU::WARN, details: missing
+              end
+            end
+          end
+
+          if role['role_source'] == "directory" or role['role_source'] == "org"
+            if !my_org
+              MU.log "Role #{role['name']} requires an organization/directory, but credential set #{role['credentials']} doesn't appear to have access to one", MU::ERR
+              ok = false
+            end
+          end
+
+          if role['role_source'] == "project"
+            role['project'] ||= MU::Cloud::Google.defaultProject(role['credentials'])
+            if configurator.haveLitterMate?(role['project'], "habitats")
+              role['dependencies'] ||= []
+              role['dependencies'] << {
+                "type" => "habitat",
+                "name" => role['project']
+              }
+            end
+          end
+
+          if role['bindings']
+            role['bindings'].each { |binding|
+              if binding['entity'] and binding['entity']['name'] and 
+                 configurator.haveLitterMate?(binding['entity']['name'], binding['entity']['type'])
+                role['dependencies'] ||= []
+                role['dependencies'] << {
+                  "type" => binding['entity']['type'].sub(/s$/, ''),
+                  "name" => binding['entity']['name']
+                }
+
+              end
+            }
+          end
+
+          ok
+        end
+
+        private
+
+        @@service_id_to_name = {}
+        @@service_id_to_privs = {}
+        @@service_name_to_id = {}
+        @@service_name_map_semaphore = Mutex.new
+
+        def self.privilege_service_to_name(credentials = nil)
+
+          customer = MU::Cloud::Google.customerID(credentials)
+          @@service_name_map_semaphore.synchronize {
+            if !@@service_id_to_name[credentials] or
+               !@@service_id_to_privs[credentials] or
+               !@@service_name_to_id[credentials]
+              @@service_id_to_name[credentials] ||= {}
+              @@service_id_to_privs[credentials] ||= {}
+              @@service_name_to_id[credentials] ||= {}
+              resp = MU::Cloud::Google.admin_directory(credentials: credentials).list_privileges(customer)
+
+              def self.id_map_recurse(items, parent_name = nil)
+                id_to_name = {}
+                name_to_id = {}
+                id_to_privs = {}
+
+                items.each { |p|
+                  svcname = p.service_name || parent_name
+                  if svcname
+                    id_to_name[p.service_id] ||= svcname
+                    name_to_id[svcname] ||= p.service_id
+                  else
+#                    MU.log "FREAKING #{p.service_id} HAS NO NAME", MU::WARN
+                  end
+                  id_to_privs[p.service_id] ||= []
+                  id_to_privs[p.service_id] << p.privilege_name
+                  if p.child_privileges
+                    ids, names, privs = id_map_recurse(p.child_privileges, svcname)
+                    id_to_name.merge!(ids)
+                    name_to_id.merge!(names)
+                    privs.each_pair { |id, childprivs|
+                      id_to_privs[id] ||= []
+                      id_to_privs[id].concat(childprivs)
+                    }
+                  end
+                }
+
+                [id_to_name, name_to_id, id_to_privs]
+              end
+
+              @@service_id_to_name[credentials], @@service_id_to_privs[credentials], @@service_name_to_id[credentials] = self.id_map_recurse(resp.items)
+            end
+
+            return [@@service_id_to_name[credentials], @@service_id_to_privs[credentials], @@service_name_to_id[credentials]]
+          }
+        end
+
+        def self.map_directory_privileges(roles, credentials: nil)
+          rolepriv_objs = []
+          notfound = []
+          if roles
+            ids, names, privlist = MU::Cloud::Google::Role.privilege_service_to_name(credentials)
+            roles.each { |p|
+              service, privilege = p.split(/\//)
+              if !names[service] and !ids[service]
+                notfound << service
+              elsif !privlist[names[service]].include?(privilege)
+                notfound << p
+              elsif names[service]
+                rolepriv_objs << MU::Cloud::Google.admin_directory(:Role)::RolePrivilege.new(
+                  privilege_name: privilege,
+                  service_id: names[service]
+                )
+              else
+                rolepriv_objs << MU::Cloud::Google.admin_directory(:Role)::RolePrivilege.new(
+                  privilege_name: privilege,
+                  service_id: service
+                )
+              end
+            }
+          end
+          [rolepriv_objs, notfound.uniq.sort]
+        end
+
+      end
+    end
+  end
+end