Google Cloud Platform
Thinfinity® Cloud Manager connects to Google Cloud Platform using a Service Account JSON key file. The Service Account must have the minimum IAM roles required to enumerate and manage Compute Engine VM instances. This article documents the Cloud Manager credential form for GCP, the minimum IAM roles the Service Account must have, and common configuration errors.
All API calls from Cloud Manager originate from the Thinfinity® Workspace server. Ensure outbound HTTPS (port 443) is open from that host to compute.googleapis.com and oauth2.googleapis.com. See Prerequisites for the full network requirements.
Prerequisites
Before adding GCP credentials in Cloud Manager, the following must be in place on the GCP side:
- A GCP project with the Compute Engine API enabled.
- A Service Account in that project for Cloud Manager, with a generated JSON key file. Cybele Software recommends a dedicated Service Account rather than reusing an existing one.
- The Service Account must be granted the IAM roles listed in Minimum IAM Roles below.
- Sufficient Compute Engine quotas in the target region for the instances you plan to manage or provision.
For how to create a Service Account, generate a JSON key, and assign IAM roles, refer to the Google Cloud IAM documentation.
Minimum IAM Roles
The Service Account must be granted the following roles on the target project.
| Role | Required For |
|---|---|
| Compute Viewer | All operations — enumerate instances, machine types, images, zones, and networks |
| Compute Instance Admin (v1) | VDI/DaaS Models only — start, stop, reset, and create VM instances |
If Cloud Manager will only enumerate and connect to existing VMs (Managed VMs mode), Compute Viewer alone is sufficient . Compute Instance Admin (v1) enables provisioning new instances from VDI/DaaS Models.
Authentication Method
Cloud Manager authenticates to GCP exclusively via the uploaded Service Account JSON key file. Workload Identity Federation, attached service accounts on the host VM, and other keyless flows are not currently supported — always generate a JSON key for Cloud Manager.
Add the Credentials in Cloud Manager
- In Cloud Manager, go to Credentials and click + New.
- Select GCP as the provider.
- Fill in the field below and click Save.
For the full Add / Edit / Delete procedure, see Managing Credentials.
GCP Credential Fields
| Field | Description |
|---|---|
| Service JSON file | Upload the Service Account JSON key file. Cloud Manager reads the project_id, client_email, and private_key fields from this file to authenticate all API requests via OAuth 2.0. |
GCP credentials in Cloud Manager are project-scoped. The project is determined by the project_id field within the uploaded JSON file. To manage VMs across multiple GCP projects, create one credential set per project.
Verification
After saving, Cloud Manager validates the credentials by calling the Compute Engine API to list instances in the project. If validation succeeds, the credential status shows as Ok. If it fails, review the error and refer to Common Errors below.
Common Errors
| Error | Likely Cause | Resolution |
|---|---|---|
invalid_grant / Invalid JWT |
The JSON file is malformed or the key has been deleted or disabled in GCP. | Verify the key is active in the Service Account’s Keys view. Generate a new key if needed. |
PERMISSION_DENIED |
The Service Account lacks the required IAM roles. | Review the roles assigned to the Service Account against the Minimum IAM Roles table. |
API not enabled |
The Compute Engine API is not enabled for the project. | Enable it in the project’s APIs & Services > Library. |
PROJECT_NOT_FOUND |
The project_id in the JSON file is incorrect or the project has been deleted. |
Verify the project exists and the JSON file matches the target project. |
| Connection timeout | The Workspace server cannot reach compute.googleapis.com:443. |
Check firewall and proxy settings. See Prerequisites. |
Security Recommendations
- Rotate JSON keys periodically. Delete old keys after updating Cloud Manager with the new file.
- Restrict the Service Account to a single project. Avoid granting organization-level roles unless strictly necessary.
- Enable audit logging. Enable Data Access logs for the Compute Engine API to audit all calls made by the Service Account.
See Also