Usage Manual

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

Prerequisites

The connector requires network access to the AWS public API endpoints: the regional endpoints of the services that are read and the global endpoints of IAM, S3 and STS.

An AWS access key (access key ID and secret access key) must be provided for each connector instance. The connector can read data in two ways:

• without roles: data is read with the identity that owns the access key;
• with roles: for each configured role, the connector assumes it through STS and reads data with the role credentials. In this case the identity that owns the access key needs only the sts:AssumeRole permission on those roles, and the data of the identity itself is not read. If the roles require an external ID, it must be set in the instance configuration.

The identity that reads the data (the access key owner, or each assumed role) needs the following read-only permissions:

"apigateway:GET",
"autoscaling:DescribeAutoScalingGroups",
"cloudhsm:DescribeClusters",
"dynamodb:DescribeEndpoints",
"dynamodb:DescribeTable",
"dynamodb:ListTables",
"dynamodb:ListTagsOfResource",
"ec2:DescribeDhcpOptions",
"ec2:DescribeHosts",
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:DescribeInternetGateways",
"ec2:DescribeNetworkAcls",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeRegions",
"ec2:DescribeSubnets",
"ec2:DescribeVolumes",
"ec2:DescribeVpcs",
"eks:DescribeCluster",
"eks:ListClusters",
"elasticache:DescribeCacheClusters",
"elasticache:DescribeCacheEngineVersions",
"elasticache:ListTagsForResource",
"elasticfilesystem:DescribeFileSystems",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:DescribeLoadBalancers",
"elasticloadbalancing:DescribeTags",
"es:DescribeElasticsearchDomain",
"es:ListDomainNames",
"es:ListTags",
"firehose:DescribeDeliveryStream",
"firehose:ListDeliveryStreams",
"firehose:ListTagsForDeliveryStream",
"glue:GetDatabases",
"iam:ListGroups",
"iam:ListRoles",
"iam:ListUsers",
"lambda:ListFunctions",
"lambda:ListTags",
"mq:DescribeBroker",
"mq:ListBrokers",
"rds:DescribeDBClusters",
"rds:DescribeDBEngineVersions",
"rds:DescribeDBInstances",
"rds:ListTagsForResource",
"s3:GetBucketPolicyStatus",
"s3:GetBucketTagging",
"s3:ListAllMyBuckets",
"s3:ListBucket",
"sns:GetTopicAttributes",
"sns:ListTagsForResource",
"sns:ListTopics",
"sqs:GetQueueAttributes",
"sqs:ListQueues",
"sqs:ListQueueTags",
"ssm:DescribeInstanceInformation",
"states:DescribeStateMachine",
"states:ListStateMachines",
"states:ListTagsForResource"

Permissions are needed only for the services that are actually read (see the Services instance configuration).

Connector dependencies

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

Configuration

Plugin configuration

The standard connector plugin configuration can be found here.

This plugin has no additional configurations.

Instance configuration

Config	Default	Description	Notes
Code*		Unique name used to identify the connector instance.	Used in executions, logs, notifications, and data source references.
Active*	true	Defines whether the instance is included in connector batch executions.
Access Key*		Access key ID used to authenticate to AWS.
Secret*		Secret access key associated with the access key.
Roles		Comma-separated list of the ARNs of the IAM roles to assume.	If set, data is read once for each role and not with the access key identity.
Regions		Comma-separated list of the names of the regions to read (e.g. eu-west-1).	If empty, all the regions enabled for the account are read.
Services		Comma-separated list of the services to read, case insensitive.	If empty, all services are read. Allowed values: ApiGateway, AutoScaling, DocumentDB, DynamoDB, EC2, EFS, EKS, ElastiCache, ElasticLoadBalancing, ElasticSearch, Glue, HSM, IAM, KinesisFirehose, Lambda, MQ, RDS, S3, SNS, SQS, SSM, StepFunctions.
Timeout	5	Maximum number of minutes to wait for the reading of the regions and of the services to complete.	Empty or non-positive values use the default. Reading executions that are still running when the timeout expires are interrupted.
External Id		External ID sent when assuming the configured roles.	Used only when Roles is set.

Entities preview

100%

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

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.

• 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.

• 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 arrow tips 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, grouped by AWS service.

• ApiGateway: RestApi (restapi)
• AutoScaling: AutoScalingGroup (autoscalinggroup)
• DocumentDB: DBCluster (docdbcluster), DBEngineVersion (docdbengineversion), DBInstance (docdbinstance)
• DynamoDB: TableDescription (table)
• EC2: Instance (instance), Host (host), Volume (volume), NetworkInterface (networkinterface), Subnet (subnet), Vpc (vpc), DhcpOptions (dhcp), InternetGateway (internetgateway), InternetGatewayAttachment (internetgatewayvpcrelation), NetworkAcl (networkacl), NetworkAclAssociation (networkaclsubnetrelation), InstanceTypeInfo (instancetype)
• EFS: FileSystemDescription (filesystem)
• EKS: Cluster (ekscluster)
• ElastiCache: CacheCluster (cachecluster), CacheEngineVersion (cacheengineversion), CacheNode (cachenode)
• ElasticLoadBalancing: LoadBalancer (loadbalancer)
• ElasticSearch: ElasticsearchDomainStatus (domain)
• Glue: Database (gluedatabase)
• HSM: Cluster (cluster), Hsm (hsm)
• IAM: User (user), Role (role), Group (group)
• KinesisFirehose: DeliveryStreamDescription (deliverystream)
• Lambda: FunctionConfiguration (function)
• MQ: DescribeBrokerResponse (broker)
• RDS: DBCluster (rdsdbcluster), DBEngineVersion (rdsdbengineversion), DBInstance (rdsdbinstance)
• S3: Bucket (bucket)
• SNS: Topic (topic)
• SQS: Queue (queue)
• SSM: InstanceInformation (instanceinformation)
• StepFunctions: DescribeStateMachineResponse (statemachine)

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 Subscription 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.