Create a private connections (private services access) Looker (Google Cloud core) instance

This page explains how to create a private connections (PSA) Looker (Google Cloud core) production or non-production instance that uses private services access (PSA).

Private connections make services reachable without going through the internet or using external IP addresses. Because they don't traverse the internet, private connections typically provide lower latency and limited attack vectors. Private connections allow your Looker (Google Cloud core) instance to communicate with other resources in your Virtual Private Cloud (VPC) but don't allow inbound communication from the public internet.

Private connectivity enables the use of some features, such as VPC Service Controls. However, private connections aren't compatible with some Looker (Google Cloud core) features. See the feature compatibility table for more information.

Looker (Google Cloud core) supports private connections (PSA) for Enterprise or Embed instance editions.

Required roles and permissions

To set up a private connections (PSA) instance, you must have the following IAM permissions:

To create a Looker (Google Cloud core) instance, you must have the Looker Admin (roles/looker.Admin) role.
To get the permissions that you need to create allocated IP address ranges and manage private connections, ask your administrator to grant you the Compute Network Admin (roles/compute.networkAdmin) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to create allocated IP address ranges and manage private connections. To see the exact permissions that are required, expand the Required permissions section:
Required permissions

The following permissions are required to create allocated IP address ranges and manage private connections:
- See available networks in the Network drop-down:
  - compute.addresses.list
  - compute.globalAddresses.list
  - compute.networks.list
  - compute.globalAddresses.list
- Create a new VPC network:
  - compute.addresses.create
  - compute.globalAddresses.create
  - serviceusage.services.enable
- Allocate a private IP range and set up a private services access connection: compute.networks.addPeering
You might also be able to get these permissions with custom roles or other predefined roles.

Note: IAM basic roles might also contain permissions to create allocated IP address ranges and manage private connections. You shouldn't grant basic roles in a production environment, but you can grant them in a development or test environment.

If you are using a private network that has already been set up, you don't need these permissions.

You may also need additional IAM roles to set up VPC Service Controls or customer-managed encryption keys (CMEK). Learn more by visiting the VPC Service Controls support for Looker (Google Cloud core) or the Enable CMEK for Looker (Google Cloud core) documentation pages for those features.

Before you begin

Work with Sales to ensure that your annual contract is completed and that you have quota allocated in your project.
Make sure that billing is enabled for your Google Cloud project.
In the Google Cloud console, on the project selector page, create a Google Cloud project or navigate to an existing one in which you want to create the Looker (Google Cloud core) instance.
Go to project selector
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

Caution: Disabling the Looker API after instance creation will affect Looker (Google Cloud core) features. For example, disabling the API will disable the ability to create instance backups.
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
Enable the Compute Engine API for your project in the Google Cloud console. When you enable the API, you may need to refresh the console page to confirm that the API has been enabled.
Enable the API
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.

Create and configure a VPC network

Before you can create a private connection, you must first create and configure a Virtual Private Cloud (VPC) network. Looker (Google Cloud core) supports multiple private connections (PSA) instances in the same VPC, either in the same region or in different regions.

Create a VPC network in your project. Alternatively, if you are using a Shared VPC instead of creating a new VPC network, complete the steps in the following section, Creating an instance in a Shared VPC, in addition to completing the remaining steps in this section for the Shared VPC.
Allocate an IPv4 IP range (CIDR block) in your VPC for a private services access connection to Looker (Google Cloud core).

Before allocating your range, consider the constraints.
When setting the IP address range size, be aware that the minimum size is a /22 block.
Looker (Google Cloud core) supports all IPv4 ranges within RFC 1918, which specifies IP addresses that are assigned to be used internally (that is, within an organization) and won't route on the Internet. Specifically, these are the following:

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

Class E IPv4 ranges (240.0.0.0/4) are reserved for future use as noted in RFC 5735 and RFC 1112 and aren't supported for Looker (Google Cloud core).

proxy-only subnet

/26

/22

Add the private services access connection to your VPC network using the IP range allocated in the previous step for the Assigned allocation.
Once your VPC network is created, return to the Create Looker instance page in your Google Cloud project. You may need to refresh the page so that your VPC network is recognized.

Once you have completed these steps, you can begin to create your instance by following the steps on the Create a Looker (Google Cloud core) instance documentation page, starting with the Before you begin section.

Multiple private connections instances in the same VPC

If two or more private connections Looker (Google Cloud core) instances are located in the same region and in the same VPC, and you delete the first Looker (Google Cloud core) instance that was created in the region, the proxy-only subnet is not released because it is still in use by the remaining instances. If you attempt to create a new private connections (PSA) Looker (Google Cloud core) instance that uses the same address range that you used for the deleted instance (which contains the proxy-only subnet's IP address range), instance creation will fail, and you will see an "IP ranges exhausted" error. To check if an IP range is in use, check VPC peering for Service Networking, and check the import routes to see if they're using the IP range that you are interested in.

Create an instance in a Shared VPC

If you are creating a Looker (Google Cloud core) instance in a Shared VPC, complete the following steps in the Shared VPC's host project:

Enable the Looker API in the Shared VPC's host project in the Google Cloud console. When you enable the API, you may need to refresh the console page to confirm that the API has been enabled.
Enable the API
Create a service account in the Shared VPC's host project, using the gcloud services identity create command:
```
gcloud beta services identity create --service=looker.googleapis.com --project=SHARED_HOST_PROJECT_ID
```
Replace SHARED_HOST_PROJECT_ID with the Shared VPC's host project.
Grant the compute.globalAddresses.get IAM permission to the service account in the host project.

After creating the service account and granting it the IAM permission, wait a few minutes for the service account and permission to propagate.

In addition, allocate an IPv4 IP range in the Shared VPC and add the private services access connection to the Shared VPC as described in the previous section, Create and configure a VPC network.

Create the private connections instance

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

If you want a private connections (PSA) instance, you have to use Google Cloud CLI or Terraform and you must configure the instance as private connections (PSA) when you create it. Private connections cannot be added to or removed from an instance after the instance is created.

To create a private connections (PSA) instance using Google Cloud CLI, perform the following steps:

If you are using CMEK, then follow the instructions for creating a service account, key ring, and key before creating your Looker (Google Cloud core) instance.
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 \
--private-ip-enabled \
--consumer-network=CONSUMER_NETWORK --reserved-range=RESERVED_RANGE
[--no-public-ip-enabled]
[--public-ip-enabled]
```
Replace the following:
- INSTANCE_NAME: a name for your Looker (Google Cloud core) instance; it isn't 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 and environment type (production or non-production) for the instance. For a private connections (PSA) instance, this should be core-enterprise-annual, core-embed-annual, nonprod-core-enterprise-annual, or nonprod-core-embed-annual. Make sure that you choose the same edition type as listed in your annual contract and that you have quota allocated. 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 network. Must be set if you're creating a private connections (PSA) 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.
You may include the following flags:
- --private-ip-enabled enables private connections (PSA). This must be included to create a private connections (PSA) instance.
- --public-ip-enabled enables public IP.
- --no-public-ip-enabled disables public IP.
- --async is recommended when you're creating a Looker (Google Cloud core) instance.
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]
[--fips-enabled]
```
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).
You may include the --fips-enabled flag to enable FIPS 140-2 level 1 compliance.

Tip: You must have quota for the proper edition type to create an instance. If you don't have quota, contact Sales to allocate quota to your project.

As the instance is being created, you can view its status on the Instances page within the console. You can also see your instance creation activity by clicking on the notifications icon in the Google Cloud console menu.

If you create a private connections (PSA) only instance, a URL won't appear on the Instances page. See the following Accessing a private connections (PSA) instance after creation section for more information about how to set up access to your private connections (PSA) instance.

Access a private connections (PSA) instance after creation

If you create an instance that is enabled only for private connections (PSA), you will not receive a URL for the instance. To access the instance, you must configure a custom domain for the instance and add that custom domain to the instance's OAuth credentials. To understand the different private connections networking options for setting up and accessing a custom domain, visit the Custom domain networking options for Looker (Google Cloud core) private connections instances documentation page.

What's next

Custom domain networking options for Looker (Google Cloud core) private connections instances