Skip to main content

How to Set Up Collibra

Setup takes about about 40 minutes.

Introduction

Connecting Collibra to Foundational allows Foundational to export its computed lineage into your Collibra data catalog, so your team can explore Foundational's table- and column-level lineage alongside your existing Collibra assets.

The connection process has three parts:

  • Part 1: Configure the export in Foundational
    ​

  • Part 2: Configure Collibra Edge to read the bucket
    ​

  • Part 3: Run the sync, schedule it, and verify

Prerequisites

Ensure you have:

  • Added Foundational IP addresses to the allowlist, see the article Allowing IP access to Foundational.

  • Administrator access to the AWS account that will host the destination S3 bucket, and the ability to create an S3 bucket and an IAM role.

  • The AWS Region for the bucket.

  • A Collibra Edge site in Healthy status (self-hosted or a Collibra-managed Cloud site), permission to add Edge connections and capabilities, and the Technical Lineage global permission (needed to view lineage and its status page).

This integration uses Collibra's OpenLineage (Cloud) technical-lineage capability, which reads files from cloud storage (S3). The local Shared Storage variant is not used.

Access permissions

The role Foundational assumes needs the following permissions on your bucket and prefix:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetBucketLocation"],
    "Resource": [
      "arn:aws:s3:::<bucket>",
      "arn:aws:s3:::<bucket>/<prefix>/*"
    ]
  }]
}


This allows Foundational to:

  • Write the exported lineage files to your bucket and prefix.
    ​

  • List objects in the bucket, to confirm the destination exists and is reachable.
    ​

  • Delete the temporary object it writes during setup, to verify write access (s3:DeleteObject).
    ​

  • Resolve the bucket's AWS Region before writing (s3:GetBucketLocation)

Foundational does not read from or modify anything else in your AWS account. The CloudFormation template in Part 1 creates a role with this policy and the correct trust relationship. You don't need to build it by hand.

Part 1: Configure the export in Foundational

  1. In your AWS account, create an S3 bucket (or choose a dedicated prefix within an existing bucket) to hold the exported files, for example s3://acme-collibra-lineage/foundational. Make a note of the bucket name, the optional prefix, and the Region.
    ​

  2. In Foundational, open the Connectors & Integrations page. Under Catalogs, select the Collibra card and click Connect.
    ​

  3. A screen opens. Click Add account.
    ​

  4. Click Start Setup.
    ​

  5. In Configure Collibra Export, complete the connection details:

    • S3 Bucket Name: Your bucket, without s3://.
      ​

    • Prefix (optional): The folder within the bucket, if any.
      ​

    • AWS Account ID: The account that owns the bucket.
      ​

    • IAM Role Name: The name of the role the CloudFormation template creates (e.g., FoundationalLineageExport). Enter the name you intend to use. The template is generated from it.
      ​

    • External ID: Generated for you and read-only. The template locks the role's trust policy to this value.
      ​

    • Export Interval (days): How often Foundational re-exports. Minimum and default is 14.
      ​

  6. Click Next. A new screen opens.
    ​

  7. Click Download YAML File. The template is generated from the values you entered in step 5. Leave Foundational open. You’ll come back to it in step 10.
    ​

  8. In AWS, go to CloudFormation > Create stack, choose Upload a template file.
    ​

  9. Upload the downloaded YAML, give the stack a name, and finish creating it. This creates the cross-account IAM role that trusts Foundational, with the permissions described in Access permissions above.

  10. Back in Foundational, click Save.​
    Foundational assumes the new role and writes a temporary object to the bucket to confirm access before storing the configuration. If the check fails, the error appears here. Use the Edit button on the previous step to correct any field, then save again.

    Warning: Download the YAML and save it in the same browser session. Foundational regenerates the External ID if you reload the form, so a role created from an older template no longer matches what Foundational sends when it assumes the role.

  11. Review the read-only Collibra-side recap and click Done to leave the wizard.
    ​

  12. Once you save the connector, it shows as configured. Its card displays the last export time and status after the first export completes.

Part 2: Configure Collibra Edge to read the bucket

There are two authentication methods:

  • Use Option A if your Edge runs on an AWS EC2 instance whose instance role can read the bucket.
    ​

  • Use Option B if you authenticate with a dedicated IAM principal.

Option A: EC2 instance role

  1. Go to Settings > Edge > [your site] > Connections > Add connection > AWS connection.
    ​

  2. For Authentication Type, select EC2.
    ​

  3. Confirm the EC2 instance's IMDS hop limit is set to 2. The AWS default is 1; the harvester runs in pods and can't fetch role credentials at the default value.
    ​

  4. Save the connection.

The principal needs s3:Get* and s3:List* on the bucket and its objects. Plain GetObject/ListBucket is not enough. The harvester also calls, e.g., GetBucketLocation.

Option B: IAM access key

  1. Go to Settings > Edge > [your site] > Connections > Add connection > AWS connection.
    ​

  2. For Authentication Type, select IAM.
    ​

  3. Enter the Access Key ID and Secret Access Key for a principal that can read the bucket.
    ​

  4. Click Save.
    ​

    The principal needs s3:Get* and s3:List* on the bucket and its objects.
    Plain GetObject / ListBucket is not enough. The harvester also calls, e.g.,

    GetBucketLocation.

Step 2: Add the OpenLineage capability

  1. Go to Settings > Edge > [your site] > Capabilities > Add capability.
    ​

  2. Choose Technical Lineage for OpenLineage (Cloud).
    ​

  3. Complete the capability fields:
    ​

    • Name: Any name (e.g., foundational-openlineage)
      ​

    • Description: Free text.
      ​

    • Source ID: A unique source name, with no / or special characters (e.g., foundational_lineage).
      ​

    • Cloud Connection: The AWS connection you just created.
      ​

    • Cloud Storage Bucket/Container: Your bucket name (no s3://).
      ​

    • Cloud Storage Region: e.g., eu-west-1.
      ​

    • Cloud Storage path: Your prefix (leave empty for the bucket root)

    • Mask: *.jsonl.
      ​

    • Processing Level: Sync for a full ingest (use Analyze first to preview).
      ​

  4. Click Add.

Part 3: Run the sync, schedule it, and verify

  1. Go to Catalog > Integrations > Integration Configuration. Find the connection you created in Part 2 and click your capability in the Capabilities column.
    ​

  2. In Synchronization Configuration, click Synchronize. A notification confirms the run started, and its status shows on this capability's page.<

    Warning: A "Completed" status does not guarantee Collibra ingested the lineage. Collibra silently skips events with problems (for example, a dataset namespace it doesn't recognize), and the run still reports success. Always verify (step 6).

  3. On the same capability page, in the Synchronization Schedule section, click Add Schedule.
    ​

  4. Set Repeat to Daily (or use a Cron expression, Quartz format), an At time (on the hour only, e.g., 14:00), and your Time zone.
    ​

  5. Click Save.
    ​

    Run the sync at least as often as your Export Interval, so no export goes un-ingested. A daily schedule is a safe default. Syncing more often than Foundational exports is harmless, since a run that finds no new files simply does nothing.

  6. Open any Table or Column asset page and click the Technical Lineage tab. In the viewer's Browse pane, your source appears under its namespace (e.g., snowflake://<org>-<account>), with the database, schema, table, and column tree, and the graph shows table- and column-level edges.
    ​

  7. Check for skipped events. Click View status (the 📈 icon, bottom-right). The Transformations table lists per-event results for your Source ID. ANALYZE_ERROR entries explain any dropped events.

Validation and troubleshooting

Symptom

Cause / fix

Lineage lands as orphan or duplicate assets

Exported lineage stitches onto your existing Collibra assets only when the OpenLineage dataset namespaces match how your catalog identifies those sources.

If you see orphaned assets, coordinate the account and host identifiers with Foundational during setup

Events are dropped even though the sync reports success

Namespaces are load-bearing. Collibra maps each dataset namespace to a source type using the OpenLineage naming convention and silently drops non-conforming events.
​
Check the View status > Transformations table for ANALYZE_ERROR details.

"Catalog authorization failed", or the lineage viewer hangs on "Loading Collibra"

This points to the Collibra Data Lineage service or entitlement on your instance, not your AWS configuration. Contact Collibra support.
​
Some instances need the techlinHost / techlinKey capability properties to point at the correct regional lineage service.

Self-hosted Edge site won't install or run the harvester

A self-hosted Edge site needs at least 16 vCPU / 64 GB (enforced by the installer), RHEL with the k3s SELinux policy, nm-cloud-setup disabled, and IMDS hop limit 2 on EC2.

See Collibra's Edge installation documentation.

That’s it. Foundational is now connected to Collibra.

Useful links

Related Articles
Did this answer your question?