Create a Looker (Google Cloud core) Private Service Connect instance

This page describes the process for using the gcloud CLI to create a Looker (Google Cloud core) instance with Private Service Connect enabled.

Private Service Connect can be enabled for a Looker (Google Cloud core) instance that meets the following criteria:

  • The Looker (Google Cloud core) instance must be new. Private Service Connect can be enabled only at the time of instance creation.
  • The instance cannot have public IP enabled.
  • The instance edition must be Enterprise (core-enterprise-annual) or Embed (core-embed-annual).

Before you begin

Before you create a Private Service Connect instance, ensure that you have received confirmation from your sales representative that your project has been added to the allowlist for Private Service Connect.

  1. In the Google Cloud console, on the project selector page, select the project where you want to create the Private Service Connect instance.

    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 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 VPC Service Controls or customer-managed encryption keys (CMEK). Visit the documentation pages for those features to learn more.

Create a Private Service Connect instance

To create a Private Service Connect instance, run the gcloud looker instances create command with all the following flags:


gcloud looker instances create INSTANCE_NAME \
--no-public-ip-enabled \
--psc-enabled \
--oauth-client-id=OAUTH_CLIENT_ID \
--oauth-client-secret=OAUTH_CLIENT_SECRET \
--region=REGION \
--edition=EDITION \
--psc-allowed-vpcs=ALLOWED_VPC,ADDITIONAL_ALLOWED_VPCS \
 --async

Replace the following:

  • INSTANCE_NAME: a name for your Looker (Google Cloud core) instance; it is not associated with the instance URL.
  • 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-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.
  • ALLOWED_VPC: a VPC that will be allowed ingress into Looker. To access the instance from outside the VPC that the instance is located in, you must list at least one VPC. Specify a VPC using one of the following formats:
    • projects/{project}/global/networks/{network}
    • https://www.googleapis.com/compute/v1/projects/{project}/global/networks/{network}
  • ADDITIONAL_ALLOWED_VPCS: any additional VPCs to be allowed ingress into Looker can be added to the --psc-allowed-vpcs flag in a comma-separated list.

The process for creating a Private Service Connect instance differs from the process for creating a regular Looker (Google Cloud core) instance in the following ways:

  • With Private Service Connect setup, the --consumer-network and --reserved-range flags are not necessary.
  • Private Service Connect instances require two additional flags: --no-public-ip-enabled and --psc-enabled.
  • The --psc-allowed-vpcs flag is a comma-separated list of VPCs. You can specify as many VPCs as you like in the list.

Specify the remaining fields as you would for a regular Looker (Google Cloud core) instance.

Check the status of the instance

It takes approximately 40-60 minutes for the instance to be created. To check the status, use the gcloud looker instances describe command:

gcloud looker instances describe INSTANCE_NAME --region=REGION

Replace INSTANCE_NAME with the name of your Looker (Google Cloud core) instance.

The instance is ready once it reaches the ACTIVE state.

Set up Private Service Connect for external services

For your Looker (Google Cloud core) instance to be able to connect to an external service, that external service must be published using Private Service Connect. Follow the instructions for publishing services by using Private Service Connect for any service that you want to publish.

Services can be published with automatic approval or with explicit approval. If you choose to publish with explicit approval, you must configure the service attachment as follows:

  • Set your service attachment allowlist to use projects (not networks).
  • Add the Looker tenant project ID to the allowlist.

You can find your Looker tenant project ID after your instance has been created by running the following command:

gcloud looker instances describe INSTANCE_NAME --region=REGION--format=json

Replace the following:

  • INSTANCE_NAME: the name of your Looker (Google Cloud core) instance.
  • REGION: the region in which your Looker (Google Cloud core) instance is hosted.

In the command output, the looker_service_attachment_uri field will contain your Looker tenant project ID. It will have the following format: projects/{Looker tenant project ID}/regions/…

Service attachment URI

When you later update your Looker (Google Cloud core) instance to connect to your service, you'll need the full service attachment URI. The URI will be specified as follows, using the project, region, and name that you used to create the service attachment:

projects/{project}/regions/{region}/serviceAttachments/{name}

Update a Looker (Google Cloud core) Private Service Connect instance

Once your Looker (Google Cloud core) Private Service Connect instance has been created, you can make the following changes:

Specify egress connections

Use --psc-service-attachment flags to enable connections to external services for which you have already set up Private Service Connect:

gcloud looker instances update INSTANCE_NAME \
--psc-service-attachment  domain=DOMAIN_1,attachment=SERVICE_ATTACHMENT_URI_1 \
--psc-service-attachment domain=DOMAIN_2,attachment=SERVICE_ATTACHMENT_URI_2 \
--region=REGION

Replace the following:

  • INSTANCE_NAME: the name of your Looker (Google Cloud core) instance.

  • DOMAIN_1 and DOMAIN_2: If you are connecting to a public service, use the service's domain name. If you are connecting to a private service, use your choice of a fully qualified domain name. The following restrictions apply to the domain name:

    • Each egress connection supports a single domain.
    • The domain name must consist of at least three parts. For example, mydomain.github.com is acceptable, but github.com is not acceptable.

    • The last part of the name cannot be any the following:

      • googleapis.com
      • google.com
      • gcr.io
      • pkg.dev

    When you set up a connection to your service from within your Looker (Google Cloud core) instance, use this domain as the alias for your service.

  • SERVICE_ATTACHMENT_1 and SERVICE_ATTACHMENT_2: the full service attachment URI. Each service attachment URI can be accessed by a single domain.

  • REGION: the region in which your Looker (Google Cloud core) instance is hosted.

Include all connections that should be enabled

Each time you run an update command with --psc-service-attachment flags, you must include every connection that you want to be enabled, including connections that were already enabled previously. For example, suppose you have previously connected an instance called my-instance to the www.cloud.com domain as follows:

gcloud looker instances update my-instance
--psc-service-attachment domain=www.cloud.com,attachment=projects/123/regions/us-central1/serviceAttachment/cloud

Running the following command to add a new www.me.com connection would delete the www.cloud.com connection:

gcloud looker instances update my-instance \
--psc-service-attachment domain=www.me.com,attachment=projects/123/regions/us-central1/serviceAttachment/my-sa

To prevent deletion of the www.cloud.comconnection when you add the new www.me.com connection, include a separate psc-service-attachment flag for both the existing connection and the new connection within the update command as follows:

gcloud looker instances update my-instance \
--psc-service-attachment domain=www.cloud.com,attachment=projects/123/regions/us-central1/serviceAttachment/cloud \
--psc-service-attachment domain=www.me.com,attachment=projects/123/regions/us-central1/serviceAttachment/my-sa

Check egress connection status

You can check the status of your egress connections by again running the gcloud looker instances describe --format=json command. Each service attachment should be populated with a connection_status field.

Delete all egress connections

To delete all egress connections, run the following command:

gcloud looker instances update MY_INSTANCE \ --clear-psc-service-attachments \
--region=REGION

Update allowed VPCs

Use the --psc-allowed-vpcs flag to update the list of VPCs that can ingress into the instance.

When you update the allowed VPCs, you must specify the entire list that you want to be in effect after your update. For example, suppose VPC ALLOWED_VPC_1 is already allowed, and you want to add VPC ALLOWED_VPC_2. To add VPC ALLOWED_VPC_1 while making sure that VPC ALLOWED_VPC_2 continues to be allowed, add the --psc-allowed-vpcs flag as follows:

gcloud looker instances update INSTANCE_NAME --psc-allowed-vpcs=ALLOWED_VPC_1,ALLOWED_VPC_2 --region=REGION

Replace the following:

  • INSTANCE_NAME: the name of your Looker (Google Cloud core) instance.
  • ALLOWED_VPC_1 and ALLOWED_VPC_2: the VPCs that will be allowed ingress into Looker. Specify each allowed VPC using one of the following formats:
    • projects/{project}/global/networks/{network}
    • https://www.googleapis.com/compute/v1/projects/{project}/global/networks/{network}
  • REGION: the region in which your Looker (Google Cloud core) instance is hosted.

Delete all allowed VPCs

To delete all allowed VPCs, run the following command:

gcloud looker instances update MY_INSTANCE \ --clear-psc-allowed-vpcs \
--region=REGION

Access your instance

To access your instance, first follow the instructions for creating a Private Service Connect endpoint within a VPC network that is allowed ingress to your Looker (Google Cloud core) instance, and then follow these guidelines:

  • Set the Target service field (for the Google Cloud console) or the SERVICE\_ATTACHMENT variable (if following Google Cloud CLI or API instructions) to looker_service_attachment_uri. You can use any subnet that you like.
  • Don't enable global access.

Similar to private IP instances, one way to access your Private Service Connect instance is to set up a public IP proxy server. Follow the instructions for setting up a proxy server, with the following differences:

  • Step 3: For NETWORK, use the VPC network in which you created a Private Service Connect endpoint. You can use any subnet in that network.
  • Step 7: For PRIVATE\_IP\_ADDRESS, use the IP address of the Private Service Connect endpoint that you created. You can find this by going to the Private Service Connect page of your project in the Google Cloud console.