Usage Manual

This page describes how the connector can be used and configured.

Prerequisites

The system running CMDBuild must be able to reach the Google Cloud APIs over HTTPS (*.googleapis.com).

The connector authenticates with a service account key: the credentials JSON file of the service account must be provided in the Credentials attribute of the instance (see Instance configuration).

The service account must have the following permissions on every project to be read (the connector only performs read operations):

cloudsql.instances.list
compute.addresses.list
compute.firewalls.list
compute.instances.list
compute.machineTypes.list
compute.networks.list
compute.subnetworks.list
container.clusters.list
resourcemanager.projects.get

The projects visible to the service account are discovered with a project search. Optionally, the services to read can be restricted with the Services attribute, in which case only the permissions of the selected services are needed (Resource Manager permissions are always required).

Connector dependencies

The connector requires the installation of the Connector utils plugin version 2.0.5 or higher and CMDBuild version 4.2.0 or higher.

Configuration

Plugin configuration

The standard connector plugin configuration can be found here.

The connector has no additional plugin configurations.

Instance configuration

Each instance (class Google cloud) represents a Google Cloud environment to read. Attributes marked with * are mandatory.

Config	Default	Description	Notes
Code*		Unique identifier of the instance.	Must be unique.
Active*		Whether the instance is read during the synchronization.	Only active instances are read.
Credentials*		Content of the service account key (JSON).	Can be pasted manually or loaded from a .json file using the Google cloud Credentials widget. Selecting a file overwrites the current content, after confirmation.
Projects		Projects to read.	Comma-separated list of project ids. If empty, all the projects visible to the service account are read.
Excluded projects		Projects to skip.	Comma-separated list of project ids. Applied together with Projects.
Services		Services to read.	Comma-separated list. Allowed values: compute, container, cloudsql (cloud_sql and cloud-sql are also accepted). If empty, all the services are read.
Thread timeout	15	Maximum time, in minutes, to wait for the concurrent reading of the projects.	Positive integer. When it expires, the threads still running are stopped.

Entities preview

100%

The diagram provides a high-level overview of the entities extracted by the connector and the relationships between them.

Project is related to all the other records: its arrow points to the dashed container, which groups those records.

The diagram uses the following conventions:

• Orange containers represent CMDBuild superclasses. The entities contained within them belong to the corresponding superclass.

• Grey containers represent logical groupings provided by the source system. These groups are used only for visualization purposes and help identify the service or functional area to which an entity belongs.

• Dashed orange containers group all the entities that are related to an entity outside the container. An arrow pointing to the container represents a relationship with each of the entities inside it.

• Blue boxes represent record types extracted by the connector. Each box is labeled using the format {Source Object Name} ({_type}), combining the object name used by the source service with the internal record type produced by the connector.

• Blue boxes with a dashed border represent calculated entities. These records do not directly correspond to objects exposed by the source system but are generated during data processing to represent information that would otherwise be embedded within another record.

• Arrows represent one-to-many relationships between entities managed by the connector. The arrow points to the "many" side of the relationship, as indicated by its label (1 : N).

• Lines without arrows represent many-to-many relationships between entities managed by the connector, as indicated by their label (N : N).

Below is a list of all the entities retrieved by the connector.

Resource Manager

• Project (project)

Compute Engine

• Instance (computeinstance)
• AttachedDisk (disk)
• NetworkInterface (networkinterface)
• Network (network)
• Subnetwork (subnetwork)
• Firewall (firewall)
• Address (address)
• Address usage relation (usage_rel)
• MachineType (machinetype)

Google Kubernetes Engine

• Cluster (cluster)
• NodePool (nodepool)

Cloud SQL

• DatabaseInstance (sqlinstance)
• Tier (sqltier)

Additional Information

Synchronization to Application Classes

The standard connector imports and maintains data within the CMDBuild standard classes and relationships, providing a consistent representation of the data.

As a separate and optional customization activity, organizations may define additional synchronization processes to populate application-specific classes from the imported infrastructure data. Through custom mappings and enrichment rules, connector resources can be associated with organization-specific business objects, services, assets, or other application entities.

This approach supports customer-specific business models, enrichment processes, and classification rules while preserving the standard infrastructure representation provided by the connector.

Known Limitations

• The connector operates in read-only mode.
• Large environments may require increased execution time.
• No real-time synchronization: data is updated only during scheduled runs.
• The plugin is distributed under a Premium license model. Its usage is tied to an active support and maintenance agreement, which is subject to expiration and must be renewed to remain valid.

Deployment Guidelines

Deployment of the connector includes the creation of standard CMDBuild classes and relationships corresponding to supported connector resource types. These structures provide the foundation for storing and organizing synchronized infrastructure information. The deployment process also includes configuration elements required for data visualization and the establishment of scheduled synchronization activities.

Following deployment, it is recommended to validate the configuration by executing an initial synchronization and reviewing the imported data.

Scheduling frequency should be selected according to the scale of the environment, expected rate of infrastructure change, and operational reporting requirements.