Create a Looker (Google Cloud core) instance

This page discusses how to provision a Looker (Google Cloud core) instance.

Before you begin

  1. In the Google Cloud console, on the project selector page, create a Google Cloud project or navigate to an existing one.

    Go to project selector

  2. Enable the Looker API for your project in the Google Cloud console. When enabling the API, you may need to refresh the console page to confirm that the API has been enabled.

    Enable the API

  3. Enable the Service Networking API for your project in the Google Cloud console. When enabling the API, you may need to refresh the console page to confirm that the API has been enabled.

    Enable the API

  4. Set up an OAuth client and create authorization credentials. The OAuth client lets you authenticate and access the instance. You must set up OAuth to create a Looker (Google Cloud core) instance, even if you are using a different authentication method to authenticate users into your instance.
  5. If you want to use private IP, VPC Service Controls, or customer-managed encryption keys (CMEK) with the Looker (Google Cloud core) instance that you are creating, additional setup is required prior to instance creation. Additional edition and network configuration may also be required during instance creation.

Required roles

To get the permissions that you need to create a Looker (Google Cloud core) instance, ask your administrator to grant you the Looker Admin (roles/looker.admin) IAM role on the project the instance will reside in. For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

You may also need additional IAM roles to set up private IP, VPC Service Controls, or customer-managed encryption keys (CMEK). Visit the documentation pages for those features to learn more.

Create a Looker (Google Cloud core) instance

Looker (Google Cloud core) requires approximately 60 minutes to generate a new instance.

To create your Looker (Google Cloud core) instance, select one of the following options:

console

  1. Navigate to the Looker (Google Cloud core) product page from your project in the Google Cloud console. If you have already created a Looker (Google Cloud core) instance within this project, this will open the Instances page.

    Go to Looker (Google Cloud core)

  2. Click CREATE INSTANCE.
  3. In the Instance name section, provide a name for your Looker (Google Cloud core) instance. The instance name is not associated with the URL of the Looker (Google Cloud core) instance once it is created. The instance name cannot be changed after instance creation.
  4. In the OAuth Application Credentials section, enter the OAuth client ID and OAuth secret that you created when you set up your OAuth client.
  5. In the Region section, select the appropriate option from the drop-down menu. The appropriate region is the one in which your Looker (Google Cloud core) instance is hosted. Select the region that matches the region in the subscription contract, which is where the quota for your project is allocated. Available regions are listed on the Looker (Google Cloud core) locations documentation page.

  6. In the Edition section, set the instance edition according to your organization's needs. The edition type affects some of the features available for the instance. These are the edition options:

    • Standard: Looker platform for small organizations or teams with fewer than 50 users. This can be purchased through an annual contract.
    • Enterprise: Looker platform with enhanced security features for addressing a wide variety of internal BI and analytics use cases. Available with an annual contract.
    • Embed: Looker platform for deploying and maintaining reliable external analytics and custom applications at scale. Available with an annual contract.

    Editions cannot be changed after instance creation. If you want to change an edition, you can use import and export to move your Looker (Google Cloud core) instance data into a new instance that is configured with a different edition.

  7. In the Customize your instance section, click SHOW CONFIGURATION OPTIONS to display a group of additional settings that you can customize for the instance.

  8. In the Connections section, the network connection options are displayed. The type of network connection selected impacts the Looker features available to the instance. The following network connection options are available:

    • Public IP: Assigns an external, internet-accessible IP address.
    • Private IP: Assigns an internal, Google-hosted IP address that is accessible on a Virtual Private Cloud (VPC). You can use this address to connect from other resources with access to the VPC. If you select this option, follow the instructions on the Create a private IP connection for Looker (Google Cloud core) documentation page to complete your network setup. Only Enterprise and Embed editions support private IP.
    • You can also select both options. If both options are selected, incoming traffic will be routed through public IP and outgoing traffic will be routed through private IP. The Looker (Google Cloud core) instance won't use the public IP to originate internet outbound traffic.

    If you select only Private IP or both Public IP and Private IP, follow the steps on the Use private IP with Looker (Google Cloud core) documentation page to complete your network setup during instance creation.

  9. In the Encryption section, you can select whether to use the default Google-managed encryption or a customer-managed encryption key (CMEK). See the Using customer-managed encryption keys with Looker (Google Cloud core) documentation page for more information on CMEK and how to configure it during instance creation. The type of encryption cannot be changed after instance creation.

  10. In the Maintenance Window section, you can optionally specify the day of the week and the hour in which Looker (Google Cloud core) schedules maintenance. Maintenance windows last for one hour. By default, the Preferred Window option in the Maintenance Window is set to Any window.

  11. In the Deny Maintenance Period section, you can optionally specify a block of days in which Looker (Google Cloud core) does not schedule maintenance. Deny maintenance periods can be up to 60 days long. You must allow at least 14 days of maintenance availability between any 2 deny maintenance periods.

  12. Click Create.

As the instance is being created, you will be redirected to the Instances page within the console. You may need to refresh the page to view the status of your new instance. You can also see your instance creation activity by clicking on the notifications icon in the Google Cloud console menu. While your instance is being created, the notifications icon in the Google Cloud console menu will be encircled by a loading icon.

gcloud

  1. If you are using CMEK, then create the Looker service account and follow the instructions for setting up CMEK first.

  2. Use the gcloud looker instances create command to create the instance:

    gcloud looker instances create INSTANCE_NAME \
--project=PROJECT_ID \
--oauth-client-id=OAUTH_CLIENT_ID \
--oauth-client-secret=OAUTH_CLIENT_SECRET \
--region=REGION \
--edition=EDITION \
[--consumer-network=CONSUMER_NETWORK --private-ip-enabled --reserved-range=RESERVED_RANGE]
[--no-public-ip-enabled]
[--public-ip-enabled]
[--async]

    Replace the following:

    • INSTANCE_NAME: a name for your Looker (Google Cloud core) instance; it is not associated with the instance URL.
    • PROJECT_ID: the name of the Google Cloud project in which you are creating the Looker (Google Cloud core) instance.
    • OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET: the OAuth client ID and OAuth secret that you created when you set up your OAuth client. After the instance has been created, enter the instance's URL in the Authorized redirect URIs section of the OAuth client.
    • REGION: the region in which your Looker (Google Cloud core) instance is hosted. Select the region that matches the region in the subscription contract. Available regions are listed on the Looker (Google Cloud core) locations documentation page.
    • EDITION: the edition for the instance. Its possible values are core-standard-annual, core-enterprise-annual, or core-embed-annual. Editions cannot be changed after instance creation. If you want to change an edition, you can use import and export to move your Looker (Google Cloud core) instance data into a new instance that is configured with a different edition.
    • CONSUMER_NETWORK: your VPC network or Shared VPC. Must be set if you're creating a private IP instance.
    • RESERVED_RANGE: the range of IP addresses within the VPC in which Google will provision a subnetwork for your Looker (Google Cloud core) instance. Must be set if you're creating a private IP instance.

    You may also include these flags:

    • --private-ip-enabled enables private IP.
    • --public-ip-enabled or --no-public-ip-enabled are used to enable or disable public IP.
    • --async is recommended when you're creating a Looker (Google Cloud core) instance.

  3. You can add more parameters to apply other instance settings: 

    [--maintenance-window-day=MAINTENANCE_WINDOW_DAY
      --maintenance-window-time=MAINTENANCE_WINDOW_TIME]
[--deny-maintenance-period-end-date=DENY_MAINTENANCE_PERIOD_END_DATE
      --deny-maintenance-period-start-date=DENY_MAINTENANCE_PERIOD_START_DATE
      --deny-maintenance-period-time=DENY_MAINTENANCE_PERIOD_TIME]
--kms-key=KMS_KEY_ID
    Replace the following:

    • MAINTENANCE_WINDOW_DAY: must be one of the following: friday, monday, saturday, sunday, thursday, tuesday, wednesday. See the Manage maintenance policies for Looker (Google Cloud core) documentation page for more information about maintenance window settings.
    • MAINTENANCE_WINDOW_TIME and DENY_MAINTENANCE_PERIOD_TIME: must be in UTC time in 24-hour format (for example, 13:00, 17:45).
    • DENY_MAINTENANCE_PERIOD_START_DATE and DENY_MAINTENANCE_PERIOD_END_DATE: must be in the format YYYY-MM-DD.
    • KMS_KEY_ID: must be the key that is created when setting up customer-managed encryption keys (CMEK).

Terraform

Use the following Terraform resource to provision a Standard Looker (Google Cloud core) instance with basic functionality:

# Creates a Standard edition Looker (Google Cloud core) instance with basic functionality enabled.
resource "google_looker_instance" "main" {
  name             = "my-instance"
  platform_edition = "LOOKER_CORE_STANDARD"
  region           = "us-central1"
  oauth_config {
    client_id     = "my-client-id"
    client_secret = "my-client-secret"
  }
}

Use the following Terraform resource to provision a Standard Looker (Google Cloud core) instance with additional settings applied:

# Creates a Standard edition Looker (Google Cloud core) instance with full functionality enabled.

resource "google_looker_instance" "main" {
  name              = "my-instance"
  platform_edition  = "LOOKER_CORE_STANDARD"
  region            = "us-central1"
  public_ip_enabled = true
  admin_settings {
    allowed_email_domains = ["google.com"]
  }
  // User metadata config is only available when platform edition is LOOKER_CORE_STANDARD.
  user_metadata {
    additional_developer_user_count = 10
    additional_standard_user_count  = 10
    additional_viewer_user_count    = 10
  }
  maintenance_window {
    day_of_week = "THURSDAY"
    start_time {
      hours   = 22
      minutes = 0
      seconds = 0
      nanos   = 0
    }
  }
  deny_maintenance_period {
    start_date {
      year  = 2050
      month = 1
      day   = 1
    }
    end_date {
      year  = 2050
      month = 2
      day   = 1
    }
    time {
      hours   = 10
      minutes = 0
      seconds = 0
      nanos   = 0
    }
  }
  oauth_config {
    client_id     = "my-client-id"
    client_secret = "my-client-secret"
  }
}

Use the following Terraform resource to provision an Enterprise Looker (Google Cloud core) instance with a private network connection:

# Creates an Enterprise edition Looker (Google Cloud core) instance with full, Private IP functionality.
resource "google_looker_instance" "main" {
  name               = "my-instance"
  platform_edition   = "LOOKER_CORE_ENTERPRISE_ANNUAL"
  region             = "us-central1"
  private_ip_enabled = true
  public_ip_enabled  = false
  reserved_range     = google_compute_global_address.main.name
  consumer_network   = data.google_compute_network.main.id
  admin_settings {
    allowed_email_domains = ["google.com"]
  }
  encryption_config {
    kms_key_name = google_kms_crypto_key.main.id
  }
  maintenance_window {
    day_of_week = "THURSDAY"
    start_time {
      hours   = 22
      minutes = 0
      seconds = 0
      nanos   = 0
    }
  }
  deny_maintenance_period {
    start_date {
      year  = 2050
      month = 1
      day   = 1
    }
    end_date {
      year  = 2050
      month = 2
      day   = 1
    }
    time {
      hours   = 10
      minutes = 0
      seconds = 0
      nanos   = 0
    }
  }
  oauth_config {
    client_id     = "my-client-id"
    client_secret = "my-client-secret"
  }
  depends_on = [
    google_service_networking_connection.main,
    google_kms_crypto_key.main
  ]
}

resource "google_kms_key_ring" "main" {
  name     = "keyring-example"
  location = "us-central1"
}

resource "google_kms_crypto_key" "main" {
  name     = "crypto-key-example"
  key_ring = google_kms_key_ring.main.id
}

resource "google_service_networking_connection" "main" {
  network                 = data.google_compute_network.main.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.main.name]
}

resource "google_compute_global_address" "main" {
  name          = "looker-range"
  purpose       = "VPC_PEERING"
  address_type  = "INTERNAL"
  prefix_length = 20
  network       = data.google_compute_network.main.id
}

data "google_project" "main" {}

data "google_compute_network" "main" {
  name = "default"
}

resource "google_kms_crypto_key_iam_member" "main" {
  crypto_key_id = google_kms_crypto_key.main.id
  role          = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member        = "serviceAccount:service-${data.google_project.main.number}@gcp-sa-looker.iam.gserviceaccount.com"
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Instance creation cannot be paused or terminated once it has been initiated. When your Terraform resource has been provisioned successfully, your terminal will print the following message:

Creation complete after XmXs [id=projects/PROJECT-ID/locations/REGION/instances/my-instance-randomly-generated-name]


Apply complete! Resources: X added, X changed, X destroyed.

To view the status of your new instance, which will be assigned a randomly generated name, visit the Instances page within the console.

It may take up to 60 minutes to provision the instance.

After the instance has been created, enter the instance's URL in the Authorized redirect URIs section of the OAuth client.

After the instance is created and you have completed OAuth setup, you can view the instance by navigating to the instance URL, which will be shown on the Instances page. You can then select your user authentication method and add users, connect to your database, and continue instance setup.

Looker service account

Looker (Google Cloud core) uses a service agent, called a Looker service account, to perform certain activities. A single Looker service account works on behalf of all Looker (Google Cloud core) instances in a given Google Cloud project. The Looker service account is automatically created the first time a Looker (Google Cloud core) instance is created in a project.

Sometimes, such as when you're using Application Default Credentials (ADC) with a connection to BigQuery in another project, you need to view information about the Looker service account, such as its email address.

Or, if you are planning to use CMEK and are going to use the Google Cloud CLI, Terraform, or the API to configure CMEK before you create the Looker (Google Cloud core) instance, you must create the Looker service account manually before you create the instance.

To view or create the Looker service account, select one of the following options:

console

To view the Looker service account:

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project that the Looker (Google Cloud core) instance resides in.
  3. Select the Include Google-provided role grants checkbox.

gcloud

To create or view the Looker service account:


gcloud beta services identity create --service=looker.googleapis.com --project=PROJECT_ID

Replace PROJECT_ID with the project that the Looker (Google Cloud core) instance resides in.

The service account name will be Looker Service Account. The email will have the format service-<project number>@gcp-sa-looker.iam.gserviceaccount.com.

What's next