Connecting GCP

Zynnode connects to Google Cloud using a Google OAuth setup flow. You sign in with Google, choose the Google Cloud project you want Zynnode to deploy into, and Zynnode prepares a keyless deployer service account in that project.

The recommended setup does not require you to download or upload a service account JSON key. Zynnode uses service account impersonation instead, so it can deploy without storing a long-lived Google Cloud private key.

Manual service account key upload is still available as an advanced fallback when OAuth setup is blocked by your organization or project permissions.

What the Google Cloud connection does

When you connect Google Cloud, Zynnode:

• sends you through Google OAuth consent
• asks for your Google Cloud project ID
• verifies that your Google account can access the project
• enables required Google Cloud APIs when possible
• creates or reuses this service account in your project:

zynnode-deployer@<project-id>.iam.gserviceaccount.com

• grants that service account the roles needed for deployment
• grants Zynnode permission to impersonate the deployer service account
• stores a keyless Google Cloud connection in Zynnode

After setup, the connection mode should appear as:

Keyless

or:

service_account_impersonation

Before you start

Make sure you have:

• a Google account that can access the target Google Cloud project
• the correct Google Cloud project ID
• permission to enable APIs on the project
• permission to create service accounts
• permission to update project IAM policy
• permission to update IAM policy on the deployer service account

If you do not manage IAM settings for the Google Cloud project, ask someone on your team who does to complete the connection or grant the setup permissions before you start.

Recommended setup option

The simplest option is for someone who manages the Google Cloud project to connect it from Zynnode.

Use this option when:

• the project belongs to a company or client
• you are not sure which Google Cloud project to use
• you cannot enable APIs
• you cannot create service accounts
• you receive a missing permission error during connection
• your organization blocks third-party OAuth apps

They should sign in to Zynnode, click Connect Google Cloud, complete Google consent, enter the project ID, and allow Zynnode to finish setup.

Required Google Cloud permissions

The Google account completing the connection needs enough access to configure the project for deployments.

At a high level, the account must be able to:

• view the project
• enable Google Cloud APIs
• create and read service accounts
• read and update the project IAM policy
• read and update the deployer service account IAM policy

For the smoothest setup, use an account that is allowed to manage service accounts, IAM roles, and APIs for the project.

For a more restricted setup, the account needs permissions covered by roles such as:

• roles/serviceusage.serviceUsageAdmin
• roles/iam.serviceAccountAdmin
• roles/resourcemanager.projectIamAdmin

Depending on your organization's IAM policy, someone who manages Google Cloud access may also need to grant permission to view the project and manage service account IAM bindings.

Roles Zynnode grants to the deployer service account

During setup, Zynnode creates or reuses:

zynnode-deployer@<project-id>.iam.gserviceaccount.com

Zynnode grants this deployer service account roles for supported Google Cloud deployment targets such as Cloud Run, Compute Engine, App Engine, Cloud Build, Artifact Registry, and Cloud Storage:

• roles/run.admin
• roles/cloudbuild.builds.editor
• roles/artifactregistry.admin
• roles/storage.admin
• roles/compute.admin
• roles/appengine.appAdmin
• roles/iam.serviceAccountUser
• roles/logging.logWriter
• roles/serviceusage.serviceUsageAdmin

Zynnode also grants its own deployer principal:

roles/iam.serviceAccountTokenCreator

on the zynnode-deployer service account. This lets Zynnode deploy keylessly by impersonating the service account instead of storing a JSON key.

APIs Zynnode may enable

Zynnode tries to enable the required Google Cloud APIs automatically during OAuth setup.

Bootstrap APIs:

• serviceusage.googleapis.com
• cloudresourcemanager.googleapis.com
• iam.googleapis.com
• iamcredentials.googleapis.com

Deployment APIs:

• cloudbuild.googleapis.com
• run.googleapis.com
• artifactregistry.googleapis.com
• compute.googleapis.com
• appengine.googleapis.com
• storage.googleapis.com

If Google blocks automatic API enablement, Zynnode will show the API that needs to be enabled manually.

Step-by-step setup

Production Google Cloud

my-production-project

Provider: Google Cloud
Project: <project-id>
Mode: Keyless
Deployer: zynnode-deployer@<project-id>.iam.gserviceaccount.com
Connected as: <google-account-email>

Advanced fallback: manual service account key

Use manual setup only when OAuth/keyless setup is not available for your project or organization.

Manual setup requires you to create a service account in Google Cloud, grant it deployment roles, download a JSON key, and upload that key to Zynnode.

Create a service account

1. Open the Google Cloud Console.
2. Select the correct project.
3. Go to IAM & Admin → Service Accounts.
4. Click Create service account.
5. Use a name such as zynnode-deploy.
6. Click Create and continue.

Assign roles

For a basic manual setup, assign these roles:

Your project may need additional roles if you deploy to App Engine, Compute Engine, or other Google Cloud targets.

Download the JSON key

1. Open the service account you created.
2. Go to Keys.
3. Click Add key → Create new key.
4. Select JSON.
5. Click Create.

The JSON key file downloads to your computer.

Upload or paste the key in Zynnode

Back in Zynnode:

1. Open Advanced manual setup.
2. Enter a connection name.
3. Upload the JSON key file or paste its contents.
4. Confirm the project ID.
5. Click Connect.

Zynnode parses the JSON key, shows the service account email, validates the connection, and saves it.

Troubleshooting

Google account cannot access the project

You may see:

Your Google account cannot access this GCP project.

This means the Google account used during OAuth does not have access to the submitted project ID.

To fix it:

1. Confirm the project ID is correct.
2. Confirm you selected the right Google account during OAuth.
3. Ask someone who manages Google Cloud access to add you to the project.
4. Start the Google Cloud connection flow again.

Project ID is wrong

You may see:

We could not find that GCP project. Check the project ID.

This usually means the submitted project ID is wrong, or the Google account cannot see the project.

Common mistakes:

• using the project name instead of the project ID
• copying the project number instead of the project ID
• connecting with a personal Google account instead of the company account
• selecting a project from the wrong Google Cloud organization

To fix it, copy the project ID from the Google Cloud project selector and retry.

Missing IAM permission

You may see:

Your Google account does not have enough permission to configure this project for deployment.

This means Google accepted the OAuth login, but your Google account cannot complete one of the project setup actions.

The account may be missing permission to:

• enable APIs
• create service accounts
• read project IAM policy
• update project IAM policy
• grant Zynnode access to impersonate the deployer service account

To fix it, ask someone who manages the Google Cloud project to run the connection flow, or grant you the required setup roles.

Required APIs are disabled

Zynnode tries to enable required APIs automatically. If Google blocks that request, Zynnode will show which API needs to be enabled manually.

Common APIs that may need manual enablement:

• Service Usage API
• Cloud Resource Manager API
• IAM API
• IAM Service Account Credentials API
• Cloud Build API
• Cloud Run Admin API
• Artifact Registry API
• Compute Engine API
• App Engine Admin API
• Cloud Storage API

To fix it:

1. Open the API enablement link shown by Zynnode.
2. Confirm the correct project is selected in Google Cloud.
3. Click Enable.
4. Return to Zynnode.
5. Start the Google Cloud connection flow again.

OAuth state expired or invalid

You may see:

Google Cloud connection expired. Please start again.

This can happen when:

• you wait too long after Google redirects back
• the callback URL is opened in a different browser
• you sign out of Zynnode during setup
• the connection flow is restarted in another tab

To fix it:

1. Close old Google Cloud connection tabs.
2. Return to Zynnode.
3. Click Connect Google Cloud again.
4. Complete the OAuth flow in the same browser session.

Google OAuth is blocked by the organization

Some Google Workspace organizations restrict third-party OAuth apps.

If Google says the app is blocked or needs admin approval:

1. Ask the Google Workspace admin to review the app access request.
2. Approve the Zynnode OAuth app for the organization or the required users.
3. Retry the Google Cloud connection flow.

Connection completes but deployment fails later

If the connection appears active but deployment fails later:

1. Confirm the zynnode-deployer service account still exists.
2. Confirm the deployer service account still has the roles listed in this guide.
3. Confirm Zynnode still has roles/iam.serviceAccountTokenCreator on the deployer service account.
4. Confirm required APIs are still enabled.
5. Check the Zynnode deployment logs for the exact Google Cloud error.

This can happen if someone manually removes IAM roles, disables APIs, or deletes the deployer service account after the connection was created.

Invalid service account key

This applies only to manual setup.

• Make sure you downloaded the key in JSON format, not P12.
• Verify the JSON file contains type, project_id, client_email, and private_key.
• Do not modify the JSON file before uploading or pasting it.

Message to send to a Google Cloud admin

Use this when asking a Google Cloud admin for help:

We are connecting a Google Cloud project to Zynnode using the OAuth/keyless setup.

Zynnode needs to create or reuse a service account named zynnode-deployer@<project-id>.iam.gserviceaccount.com, grant it deployment roles, and grant Zynnode permission to impersonate it.

Please either run the Zynnode Google Cloud connection flow with an account that can manage service accounts, IAM roles, and APIs for the project, or grant my Google account enough access to:

- enable required Google Cloud APIs
- create and read service accounts
- read and update the project IAM policy
- read and update IAM policy on the zynnode-deployer service account

The easiest option is for someone who already manages the Google Cloud project to connect it from Zynnode.

Quick checklist

Before retrying a failed Google Cloud connection:

• Confirm the project ID is correct.
• Confirm you selected the right Google account.
• Confirm the Google account can access the project.
• Confirm the Google account can enable APIs.
• Confirm the Google account can create service accounts.
• Confirm the Google account can update project IAM policy.
• Enable any APIs Zynnode listed in the error.
• Close old OAuth tabs and restart the connection from Zynnode.