Hyphen
Log In

Google Cloud

A comprehensive guide to setting up and connecting your Google Cloud organization with Hyphen, covering account creation, permission requirements, and various connection types.

Table of Contents

1. Create or sign into your Google Cloud account

2. Connect your Google Cloud organization to Hyphen

  • Sign in with your Google account
  • Select the GCP organization you wish to connect
  • (Optional) Select a billing account

That's it! After you've completed these steps, Hyphen will automatically:

  • Verify the credentials and selected organization
  • Grant necessary permissions to the Hyphen service
  • Configure the domain-restricted sharing policy to allow access from Hyphen

Required Permissions

The one-click installation requires the following permissions:

resourcemanager.organizations.getIamPolicy
resourcemanager.organizations.setIamPolicy
resourcemanager.organizations.get
billing.accounts.list
orgpolicy.policies.create
orgpolicy.policies.update
orgpolicy.policies.get
orgpolicy.policies.list
resourcemanager.tagKeys.create
resourcemanager.tagKeys.get
resourcemanager.tagKeys.list
resourcemanager.tagValues.create
resourcemanager.tagValues.get
resourcemanager.tagValues.list

Required OAuth Scopes

To perform the setup and ongoing management securely, Hyphen requires access to specific Google Cloud scopes:

https://www.googleapis.com/auth/cloud-platform

This broad scope allows Hyphen to manage resources across your GCP organization. It is required to:

  • List organizations
  • Set the domain restricted sharing policy
  • Assign roles to the Hyphen service account, including:
    • Artifact Registry Administrator (roles/artifactregistry.admin)
    • Billing Account User (roles/billing.user)
    • Cloud Run Admin (roles/run.admin)
    • Compute Network Admin (roles/compute.networkAdmin)
    • Folder Admin (roles/resourcemanager.folderAdmin)
    • Organization Administrator (roles/resourcemanager.organizationAdmin)
    • Project Creator (roles/resourcemanager.projectCreator)
    • Secret Manager Admin (roles/secretmanager.admin)
    • Secret Manager Secret Version Manager (roles/secretmanager.secretVersionManager)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Service Account Key Admin (roles/iam.serviceAccountKeyAdmin)
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
    • Tag Viewer (roles/resourcemanager.tagViewer)
    • Tag User (roles/resourcemanager.tagUser)
    • Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)
    • Cloud Asset Viewer (roles/cloudasset.viewer)
    • Kubernetes Engine Viewer (roles/container.viewer)
    • DNS Administrator (roles/dns.admin)
    • Certificate Manager Owner (roles/certificatemanager.owner)
    • Storage Admin (roles/storage.admin)
    • Logs Viewer (roles/logging.viewer)
    • Monitoring Viewer (roles/monitoring.viewer)
    • Kubernetes Engine Cluster Viewer (roles/container.clusterViewer)

These roles are necessary to let Hyphen create and manage GCP projects and resources on your behalf.

https://www.googleapis.com/auth/cloud-billing.readonly

This scope allows Hyphen to:

  • List available billing accounts

This is optional but recommended to allow you to associate a billing account during project creation.

Connections

Permission Group

Permission group connections correspond to Google Workspace distribution lists and require an existing Google Workspace integration within the Hyphen organization. Connections can link to existing Groups in Google Workspace, or a new group will be created if no input is provided.

If a distribution list already exists for the same resource in Google Workspace, it will be used as the Permission Group connection.

When creating a new Group in Google Workspace, the Hyphen team name will be used as the group name.

Configuration

Field Type Description
groupId string Unique group ID in Google Workspace.
groupName string Display name of the group in Google Workspace.
groupEmail string Unique group email used for reference in future requests.

Connection Input

Provide the Google Workspace group email to create a connection to an existing Group.

Verification

Scenario Action
Group has an owner Verification handled by the owner.
No owner exists A verification email is sent to the group email.

Folder

Folder connections can link to existing folders in Google Cloud, or a new folder will be created if no input is provided.

When creating a new folder in Google Cloud, the Hyphen project name will be used as the folder name, adjusted to include only alphanumeric characters.

Configuration

Field Type Description
folderId string Unique folder ID in Google Cloud.
folderPath string Path in the format folders/{folderId}.
folderName string Display name of the folder in Google Cloud.

Connection Input

Provide the Google Cloud folder ID to create a connection to an existing Folder.

Cloud Workspace

Cloud Workspace connections can link to existing projects in Google Cloud, or a new project will be created if no input is provided.

A Google Cloud project relies on a Folder. If no Folder connection exists for the Hyphen project, a new Folder will be created.

When creating a new project in Google Cloud, the project name will combine the Hyphen project name and the Hyphen project environment name.

Configuration

Field Type Description
projectId string Unique project ID in Google Cloud.
projectPath string Path in the format projects/{projectId}.
projectName string Display name of the project in Google Cloud.

Connection Input

Provide the Google Cloud project ID to create a connection to an existing Project.

Access

A Team connection will be added with the "Owner" role when added to the project.

User

User connections correspond to Google Workspace users and require an existing Google Workspace integration within the Hyphen organization.

User connections can only link to existing users in Google Workspace. If no input is provided, the member email will be used to locate the user.

Configuration

Field Type Description
userId string Unique user ID in Google Workspace.
email string Unique user email in Google Workspace.

Connection Input

A connection to an existing user can be created by providing the user email.

Object Storage

Object Storage connections link to existing GCS buckets in Google Cloud or create a new one if none is provided. Object Storage requires a Cloud Workspace connection for the target project environment.

When creating a new bucket, the name is derived from the Hyphen project and environment alternate IDs (e.g. {projectAlternateId}-{envAlternateId}).

Configuration

Field Type Description
bucketName string GCS bucket name.
bucketPath string Full bucket path in gs://{bucketName} format.
projectId string GCP project ID where the bucket resides.

Connection Input

Provide the GCS bucket name to connect to an existing bucket.

Access

Hyphen creates a dedicated service account with the Storage Admin role scoped to the bucket and generates a service account key (JSON) that is injected into the application at runtime.

Kubernetes Observability

Kubernetes Observability connections let Hyphen Agent query Google Cloud Monitoring metrics and Cloud Logging entries for a registered GKE cluster.

Connection Input

Provide the full GKE cluster resource name:

projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME

Hyphen validates that the cluster exists and stores its project, location, and cluster name with the connection.

Required Access

The Hyphen service account needs:

  • Logs Viewer (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Kubernetes Engine Cluster Viewer (roles/container.clusterViewer)

The Google Cloud one-click setup assigns these roles. If the connection reports that the cluster cannot be found, verify the resource name and confirm the roles are present.

Hyphen may create the connection automatically when Horizon detects Google Cloud observability, the organization has one Google Cloud integration, and Cloud Asset Inventory can resolve the GKE cluster. Otherwise, connect it from the cluster's Settings tab.

For complete setup instructions, see Kubernetes Observability.

Test Connect