Synchronizing GKE Resources from Google Cloud

Overview

QueryPie supports GCP integration for Kubernetes cluster registration and management. You can synchronize GKE clusters in a GCP Project, register them as clusters managed by QueryPie, and grant users and groups Kubernetes API access and configure policies for the synchronized clusters.

This document explains how to register a GCP Service Account Key JSON directly in QueryPie and synchronize GKE Standard or Autopilot clusters.

Prerequisites

1. Identify the target GCP Project ID.
2. Verify that the GKE cluster to synchronize was created as a GKE Standard or Autopilot cluster.
3. Prepare GCP administrator permissions to create a Service Account, grant IAM roles, and create a Service Account Key.
4. Prepare QueryPie administrator permissions to create and synchronize a KAC Cloud Provider.
5. Verify that the following APIs are enabled in the GCP Project.

If the APIs are not enabled, enable them from APIs & Services > Enabled APIs & services in the GCP Console, or run the following command.

gcloud services enable \
  container.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  --project=<PROJECT_ID>

Creating and Granting Permissions to a GCP Service Account

Create a dedicated QueryPie Service Account so that QueryPie can authenticate with GCP and GKE.

gcloud iam service-accounts create querypie-kac-gke \
  --display-name="QueryPie KAC GKE" \
  --project=<PROJECT_ID>
export QUERYPIE_GKE_SA="querypie-kac-gke@<PROJECT_ID>.iam.gserviceaccount.com"

Grant the Service Account the IAM role required for GKE cluster synchronization and Kubernetes API access.

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:${QUERYPIE_GKE_SA}" \
  --role="roles/container.admin"

The roles/container.admin role includes the container.clusters.impersonate permission required for QueryPie KAC cluster synchronization and user and group impersonation.

Creating a Service Account Key JSON

Create the Service Account Key JSON file to register as a QueryPie Cloud Provider Credential.

gcloud iam service-accounts keys create querypie-kac-gke-key.json \
  --iam-account="${QUERYPIE_GKE_SA}" \
  --project=<PROJECT_ID>

Enter the entire contents of the generated JSON file in QueryPie without converting it to Base64.

Registering GCP Integration Information in QueryPie

1. Navigate to Administrator > Kubernetes > Connection Management > Cloud Providers.
2. Click the + Create Provider button in the upper-right corner.
3. In Name, enter a name that identifies the provider.
4. In Cloud Provider, select GCP.
5. In Project ID, enter the GCP Project ID containing the GKE clusters.
6. In Credential, select Service Account.
7. In Service Account JSON, enter the entire contents of the querypie-kac-gke-key.json file.
8. Configure Search Filter or Auto Configuration Upon Synchronization > Tag as needed.
9. In Replication Frequency, select a synchronization method.
   • Manual: Synchronizes resources manually only when synchronization is initiated.
   • Scheduling: Synchronizes resources periodically based on a Cron Expression.
10. Click Dry Run to preview the Credential and cluster lookup results.
11. Click Save to save the Cloud Provider.

Synchronizing and Managing a Registered GCP Cloud Provider

1. Navigate to Administrator > Kubernetes > Connection Management > Cloud Providers.
2. Click the registered GCP Cloud Provider to open its details page.
3. Click Synchronize in the upper-right corner to synchronize GKE clusters from GCP.
4. Check the synchronization progress in the displayed Synchronization Log.
5. You can also check the synchronization history in Settings > Systems > Jobs.
6. Verify that the GKE clusters are registered in Administrator > Kubernetes > Connection Management > Clusters.

QueryPie uses the projects/<PROJECT_ID>/locations/-/clusters API to retrieve GKE clusters from every location in the Project. You can synchronize both Standard and Autopilot GKE clusters.

After registering a Cloud Provider, some provider information cannot be changed.

Differences Between GKE Standard and Autopilot

In Autopilot, you cannot use system:* groups such as system:masters as impersonation groups in a KAC Policy. When using a custom group, create a ClusterRoleBinding in the target GKE cluster that connects the group to the required Kubernetes ClusterRole for both Standard and Autopilot.

For example, if you use the querypie:kac-admins group as an impersonation group in QueryPie, you can configure the following ClusterRoleBinding in the target GKE cluster.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: querypie-kac-admins
subjects:
  - kind: Group
    name: querypie:kac-admins
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

In a production environment, we recommend using a least-privilege ClusterRole that follows your organization’s policies instead of cluster-admin.

Dry Run/Synchronization Log Messages

Frequently Asked Questions

Q. Do I need to encode the Service Account JSON in Base64 before entering it?

A. No. Enter the entire contents of the querypie-kac-gke-key.json file as-is.

Q. Can I synchronize GKE Autopilot clusters?

A. Yes. You can synchronize both GKE Standard and Autopilot clusters. However, Autopilot does not support system:* user and group impersonation such as system:masters. We recommend using a custom group and the required Kubernetes RBAC Binding.

Q. Can I modify the Project ID or Credential after saving the Cloud Provider?

A. No. After saving the provider, you cannot change core connection information such as Cloud Provider, Project ID, Credential, or Service Account JSON. Register a new Cloud Provider if you need to use another Project or Credential.

Q. Synchronization succeeded, but the user cannot connect to the cluster.

A. Even after the cluster is registered in QueryPie, the user or group must be granted KAC access and assigned a policy separately. If you use a custom impersonation group, verify that the group is connected to a Kubernetes RoleBinding or ClusterRoleBinding in the target GKE cluster.