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
- In the Google Cloud console, on the project selector page, select the project where you want to create the Private Service Connect instance.
- 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 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.
- 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.
- 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 to projects, folders, and organizations.
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
andOAUTH_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 arecore-enterprise-annual
, orcore-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
andDOMAIN_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, butgithub.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
andSERVICE_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.com
connection 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
andALLOWED_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) tolooker_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.