hunfabric/modules/analytics-hub/README.md

BigQuery Analytics Hub

This module allows managing Analytics Hub Exchange and Listing resources.

Examples

Exchange

Exchange argument references can be found in: https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_analytics_hub_data_exchange

module "analytics-hub" {
  source          = "./fabric/modules/analytics-hub"
  project_id      = "project-id"
  region          = "us-central1"
  prefix          = "test"
  name            = "exchange"
  primary_contact = "exchange-owner-group@domain.com"
  documentation   = "documentation"
}
# tftest modules=1 resources=1

Listings

Listing definitions can be provided in the form {LISTING_ID => LISTING_CONFIGS}. Listing argument references can be found in: https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_analytics_hub_listing

module "analytics-hub" {
  source     = "./fabric/modules/analytics-hub"
  project_id = "project-id"
  region     = "us-central1"
  name       = "exchange"
  listings = {
    "listing_id" = {
      bigquery_dataset = "projects/{project}/datasets/{dataset}"
    },
    "listing_id_2" = {
      bigquery_dataset = "projects/{project}/datasets/{dataset}"
      description      = "(Optional) Short description of the listing."
      documentation    = "(Optional) Documentation describing the listing."
      categories       = []
      primary_contact  = "(Optional) Email or URL of the primary point of contact of the listing."
      icon             = "(Optional) Base64 encoded image representing the listing."
      request_access   = "(Optional) Email or URL of the request access of the listing. Subscribers can use this reference to request access."
      data_provider = {
        name            = "(Required) Name of the data provider."
        primary_contact = "(Optional) Email or URL of the data provider."
      }
      publisher = {
        name            = "(Required) Name of the listing publisher."
        primary_contact = "(Optional) Email or URL of the listing publisher."
      }
      restricted_export_config = {
        enabled               = true
        restrict_query_result = true
      }
    }
  }
}
# tftest modules=1 resources=3

IAM

This module supports setting IAM permissions on both the exchange and listing resources. IAM permissions on the exchange is inherited on the listings.

See this page to see IAM roles that can be granted on exchange and listings.

Exchange

Input to variables iam, iam_bindings, and iam_by_principals will be merged, and are authoritative for the given role. Inputs to variable iam_bindings_additive are additive.

In practice, you should only need to use either iam or iam_bindings.

module "analytics-hub" {
  source     = "./fabric/modules/analytics-hub"
  project_id = "project-id"
  region     = "us-central1"
  name       = "exchange"
  iam = {
    "roles/analyticshub.viewer" = [
      "group:viewer@domain.com"
    ],
  }
  iam_bindings = {
    "viewers" = {
      role    = "roles/analyticshub.viewer"
      members = ["user:user@domain.com"]
    }
  }
  iam_by_principals = {
    "user:user@domain.com" = [
      "roles/analyticshub.viewer"
    ]
  }
  iam_bindings_additive = {
    "subscribers" = {
      role   = "roles/analyticshub.subscriber"
      member = "user:user@domain.com"
    }
  }
}
# tftest modules=1 resources=3 inventory=iam_exchange.yaml

Listings

The listings variable block support the iam input which are authoritative for the given role.

module "analytics-hub" {
  source     = "./fabric/modules/analytics-hub"
  project_id = "project-id"
  region     = "us-central1"
  name       = "exchange"
  iam = {
    "roles/analyticshub.viewer" = [
      "group:viewer@domain.com"
    ],
  }
  listings = {
    "listing_id" = {
      bigquery_dataset = "projects/{project}/datasets/{dataset}"
      iam = {
        "roles/analyticshub.subscriber" = [
          "group:subscriber@domain.com"
        ],
        "roles/analyticshub.subscriptionOwner" = [
          "group:subscription-owner@domain.com"
        ],
      }
    }
  }
}
# tftest modules=1 resources=5 inventory=iam_listing.yaml

Factory

Similarly to other modules, a rules factory is also included here to allow managing listings inside the same exchange via descriptive configuration files.

Factory configuration is via one optional attributes in the factory_config_path variable specifying the path where tags files are stored.

Factory tags are merged with rules declared in code, with the latter taking precedence where both use the same key.

This is an example of a simple factory:

module "analytics-hub" {
  source     = "./fabric/modules/analytics-hub"
  project_id = "project-id"
  region     = "us-central1"
  name       = "exchange"
  listings = {
    "listing_id" = {
      bigquery_dataset = "projects/{project}/datasets/{dataset}"
    },
  }
  factories_config = {
    listings = "listings"
  }
}
# tftest modules=1 resources=5 files=yaml

# tftest-file id=yaml path=listings/listing_1.yaml
bigquery_dataset: projects/{project}/datasets/{dataset}
description: "(Optional) Short description of the listing."
documentation: "(Optional) Documentation describing the listing."
categories: []
icon: "(Optional) Base64 encoded image representing the listing."
primary_contact: "(Optional) Email or URL of the primary point of contact of the listing."
request_access: "(Optional) Email or URL of the request access of the listing. Subscribers can use this reference to request access."
data_provider:
  name: "(Required) Name of the data provider."
  primary_contact: "(Optional) Email or URL of the data provider."
iam:
  roles/analyticshub.subscriber:
    - group:subscriber@domain.com
  roles/analyticshub.subscriptionOwner:
    - group:subscription-owner@domain.com
publisher:
  name: "(Required) Name of the listing publisher."
  primary_contact: "(Optional) Email or URL of the listing publisher."
restricted_export_config:
  enabled: true
  restrict_query_result: true

Variables

name	description	type	required	default
name	The ID of the data exchange. Must contain only Unicode letters, numbers (0-9), underscores (_). Should not use characters that require URL-escaping or characters outside of ASCII spaces.	string	✓
project_id	The ID of the project where the data exchange will be created.	string	✓
region	Region for the data exchange.	string	✓
description	Resource description for data exchange.	string		null
documentation	Documentation describing the data exchange.	string		null
factories_config	Paths to data files and folders that enable factory functionality.	object({…})		{}
iam	Authoritative IAM bindings in {ROLE => [MEMBERS]} format.	map(list(string))		{}
iam_bindings	Authoritative IAM bindings in {KEY => {role = ROLE, members = []}}. Keys are arbitrary.	map(object({…}))		{}
iam_bindings_additive	Individual additive IAM bindings. Keys are arbitrary.	map(object({…}))		{}
iam_by_principals	Authoritative IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid cycle errors. Merged internally with the iam variable.	map(list(string))		{}
icon	Base64 encoded image representing the data exchange.	string		null
listings	Listings definitions in the form {LISTING_ID => LISTING_CONFIGS}. LISTING_ID must contain only Unicode letters, numbers (0-9), underscores (_). Should not use characters that require URL-escaping or characters outside of ASCII spaces.	map(object({…}))		{}
prefix	Optional prefix for data exchange ID.	string		null
primary_contact	Email or URL of the primary point of contact of the data exchange.	string		null

Outputs

name	description	sensitive
data_exchange_id	Data exchange id.
data_listings	Data listings and corresponding configs.