Foundation reference - Cognite Docs

The Foundation deployment pack (dp:foundation) is the recommended starting point for a new Cognite Data Fusion (CDF) project. Instead of building access controls, a data model, extraction pipelines, and CI/CD from scratch, you deploy a tested, best-practice foundation as Cognite Toolkit modules and configure it through a guided setup wizard. The result is a production-ready project scaffold in days instead of weeks.

Who it’s for

Target personas:

Data engineers — deploy and configure the foundation on a CDF project.
Solution architects — design the overall CDF solution and integration approach.
CDF administrators — manage persona access groups and environment configuration.

Use this pack when:

You are setting up a new CDF project and need a foundation with access groups, a data model, and extraction and contextualization pipelines without building them by hand.

When not to use this pack:

This pack is built for new projects. It is not designed to retrofit an existing project that already has established access groups, a data model, and configuration in place. For brownfield projects, contact Cognite support to determine the right approach before deploying.

What’s included

The pack is a set of Toolkit modules. The common module (cdf_project_foundation) is always included. You then select one data model and any source-system and contextualization modules your project needs.

Component	Description	Optional?
`cdf_project_foundation`	Core required module — three persona-led access groups and the interactive project setup wizard.	No
`isa_manufacturing_extension`	ISA-95 enterprise data model for manufacturing assets (assets, equipment, functional locations, time series).	Yes
`cfihos_oil_and_gas_extension`	CFIHOS enterprise data model for oil and gas assets.	Yes
`*_extension_search`	Search-optimized solution views on top of the matching enterprise model.	Yes
`cdf_pi_extractor`	Extraction pipeline configs for OSIsoft PI / AVEVA PI time series.	Yes
`cdf_sap_extractor`	Extraction pipeline configs for SAP assets, equipment, and functional locations via RAW.	Yes
`cdf_opcua_extractor`	Extraction pipeline configs for OPC-UA data via RAW.	Yes
`cdf_db_extractor`	Extraction pipeline configs for generic databases via RAW.	Yes
`cdf_files_extractor`	Extraction pipeline configs for file sources such as SharePoint.	Yes
`cdf_entity_matching`	Automated asset–time series matching (rule-based and ML-assisted).	Yes
`cdf_file_annotation`	P&ID and document annotation with a Streamlit review app.	Yes
`qualitizer`	The Qualitizer tool for data quality, access, and workload insights — strongly recommended for day-one visibility.	Yes

The qualitizer module installs the same standalone Qualitizer tool documented separately — a local web application you run against your project, not a deployed CDF resource. After the pack is added, run it from modules/tools/apps/qualitizer/. See the Qualitizer page for how to run it.

Prerequisites

Verify all of the following before you start:

Cognite Toolkit version 0.8 or later is installed. See Setting up.
A cdf.toml file exists in your project root. If it is missing, run cdf modules init and select Create toml file (required).
Authentication is configured and verified — run cdf auth init and cdf auth verify using a local .env file. See Authentication and authorization.

Install and deploy

Unlike most deployment packs, the Foundation pack starts from a new Toolkit project and uses an interactive setup wizard that writes all configuration before you build and deploy.

Initialize and select modules

In your directory, run:

cdf modules init .

The cdf modules init . command opens an interactive menu. Select the Foundation deployment pack, then press Enter to see its modules.Pick exactly one data model variant (ISA-95 or CFIHOS), plus any source-system and contextualization modules. Always keep cdf_project_foundation, and installing qualitizer is strongly recommended.

Use the arrow keys to move and Space to select modules.
Press Enter to confirm.

Run the setup wizard

Run the setup wizard from the project root:

python modules/common/cdf_project_foundation/scripts/setup_project.py

The wizard prompts for project names, site or location, Microsoft Entra ID groups, and owner contacts, then writes all config.<env>.yaml files and .env in one pass.

Re-running the wizard is idempotent — it pre-fills current values, so it is safe to run again.

Build and deploy

cdf build
cdf deploy --dry-run
cdf deploy

Inspect the dry-run output and confirm the configuration looks correct before running cdf deploy.

Set up CI/CD (optional)

Run the CI/CD generator from the project root:

python modules/common/cdf_project_foundation/scripts/generate_actions.py

This creates GitHub Actions workflows for automated build, dry-run, and deploy on pull request, merge, and release.

Verify the deployment

After deploying, confirm success with these checks:

In CDF, the three persona groups (for example, consumer_all_dev, producer_all_dev, and admin_all_dev) are present and bound to the correct Entra ID group object IDs.
The selected data model (ISA-95 or CFIHOS spaces) is deployed and visible.
Any selected source-system extraction pipeline configs appear in CDF.
Run the setup wizard in check mode to validate the configuration — it reports any invalid or missing required config values without writing changes:
python modules/common/cdf_project_foundation/scripts/setup_project.py --check
If you installed qualitizer, run it against the project and confirm it reports on access, data models, and workload scheduling.

Configuration reference

Parameters are set in config.dev.yaml at the project root. Default values work for an initial test deployment. Each parameter takes its default unless you override it. Where the default is — (or a value read from .env), you must provide your own value. The wizard-computed values below (dataset, instanceSpaces, and the group names) are filled in automatically by the setup wizard — you don’t set them by hand.

Parameter	Description	Default
`site`	Optional site/location segment in access-group names (for example, `oslo`). Leave blank to omit.	`""`
`dataset`	Datasets used to scope the foundation access-group ACLs. Wizard-computed from the extractor modules you selected.	`[]`
`schemaSpace`	Schema space where the selected data model views are defined.	`dm_dom_isa_manufacturing` (ISA) / `dm_dom_oil_and_gas` (CFIHOS)
`instanceSpace`	Project-level instance space where data model instances are written.	`inst_isa_manufacturing` (ISA) / `inst_location` (CFIHOS)
`instanceSpaces`	All instance spaces the consumer group gets read access to — the project-level `instanceSpace` plus one per installed extractor module. Wizard-computed.	`["inst_isa_manufacturing"]`
`dataModelVariant`	Selected enterprise data model (`isa_manufacturing_extension` or `cfihos_oil_and_gas_extension`).	`isa_manufacturing_extension`
`consumerGroupName` / `producerGroupName` / `adminGroupName`	Access-group names. Wizard-computed per environment.	`consumer_all_dev` / `producer_all_dev` / `admin_all_dev`
`consumerSourceId` / `producerSourceId` / `adminSourceId`	Microsoft Entra ID group object IDs per persona, referenced from `.env` (`CONSUMER_SOURCE_ID`, `PRODUCER_SOURCE_ID`, `ADMIN_SOURCE_ID`). These are object IDs, not secrets.	—

Access groups deployed

Group	Persona	Capability scope
`consumer_<site>_<type>_<env>`	Read-only	READ on data models, instances, time series, files, RAW, and transformations, scoped to the dataset and spaces.
`producer_<site>_<type>_<env>`	Read/write	Consumer rights plus WRITE, run transformations, workflow orchestration, and sessions CREATE.
`admin_<site>_<type>_<env>`	Admin	Full capabilities including `groups:write`, projects, datasets, data models, transformations, and pipelines.

Group names follow the persona-led convention <persona>_[<site>_]<type>_<env> — see the Resource naming reference for the full grammar. For this pack, the human persona groups use the all type (default consumer_all_dev, producer_all_dev, admin_all_dev), while per-source service-principal groups created by extractor modules use a source-specific token (for example, producer_ep_pi_dev). The dev name covers both dev and test.

Architecture

The pack is structured as a common foundation module plus selectable model, source, and contextualization modules. The setup wizard configures all of them in one pass, writing per-environment config files and a .env file.

<project>/
├── .github/                  # CI/CD workflows (optional, generated by the wizard)
├── build/                    # Toolkit build output
├── docs/                     # Generated docs (for example, FOUNDATION_CICD.md)
├── modules/
│   ├── common/               # cdf_project_foundation — persona groups + setup wizard
│   ├── contextualization/    # Entity matching, file annotation (optional)
│   ├── datamodels/           # ISA-95 or CFIHOS enterprise model (select one)
│   ├── sourcesystem/         # PI, SAP, OPC-UA, DB, files pipeline configs (optional)
│   └── tools/                # qualitizer and other tooling (optional)
├── .env                      # Entra ID group object IDs (written by the wizard)
├── cdf.toml                  # Toolkit project config
├── config.dev.yaml           # Per-environment configuration (dev)
├── config.test.yaml          # Per-environment configuration (test)
└── config.prod.yaml          # Per-environment configuration (prod)

We recommend three CDF environments — dev, test, and prod — each with its own config.<env>.yaml file. The setup wizard writes configuration for all environments in one pass. Data flow: source systems → extraction pipeline configs (PI, SAP, OPC-UA, DB, files) → CDF RAW / instances → data model (ISA-95 or CFIHOS) → optional contextualization (entity matching, file annotation) → consumed via persona-scoped access groups.

Troubleshooting

Symptom	Likely cause	Resolution
`cdf auth verify` fails with 401 Unauthorized	Missing or incorrect credentials in `.env` file.	Run `cdf auth init`, re-enter credentials, then re-run `cdf auth verify`.
Module files unexpectedly overwritten	Ran `cdf modules init . --clean` without committing changes first.	Commit or stash local changes before running the command. Use `cdf modules add` for existing projects to avoid this risk.
Library modules not found during `cdf modules add`	`[library.toolkit-data]` section still present in `cdf.toml`, or `[library.cognite]` not yet added.	Replace the `[library.toolkit-data]` section with `[library.cognite]` in `cdf.toml`. The two sections cannot coexist.
`cdf deploy` fails with “Insufficient permissions”	Toolkit service account is missing required CDF capabilities.	Add `spaces:write`, `datamodels:write`, `transformations:write`, `workflows:write`, `datasets:write`, and `rawdb:write` to the CDF group used by the Toolkit.
Auto-detection of the data model fails or asks for `--variant`	More than one data model directory is present.	Select only one data model variant, or pass `--variant <name>` explicitly.
Wizard prompts re-appear empty on re-run	Expected behavior.	Re-runs are idempotent and pre-fill current values. The wizard is safe to re-run.
Deploy fails on access groups	`*_SOURCE_ID` values missing or wrong in `.env`.	Confirm the Entra ID group object IDs are correct and present in `.env`.
Dry-run reports config errors	Mismatched dataset or space values across modules.	Ensure `{{ dataset }}`, `{{ instanceSpace }}`, and `{{ schemaSpace }}` match across installed modules. Fix and re-run the dry-run.

For issues not covered here, contact Cognite support.

Support

Field	Details
Team	Cognite Value Delivery Team
Documentation	Cognite product documentation
Questions and feedback	Deployment Packs group on Cognite Hub
Version	1.0.0
Last updated	2026

​Who it’s for

​What’s included

​Prerequisites

​Install and deploy

​Verify the deployment

​Configuration reference

​Access groups deployed

​Architecture

​Troubleshooting

​Support

Who it’s for

What’s included

Prerequisites

Install and deploy

Verify the deployment

Configuration reference

Access groups deployed

Architecture

Troubleshooting

Support