> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Foundation reference
> Deploy a production-ready CDF foundation with persona-based access groups, enterprise data models, extraction pipelines, and contextualization modules.
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](/cdf/deploy/cdf_toolkit/references/packages/qualitizer) tool for data quality, access, and workload insights — strongly recommended for day-one visibility. | Yes |
The `qualitizer` module installs the same standalone [Qualitizer](/cdf/deploy/cdf_toolkit/references/packages/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](/cdf/deploy/cdf_toolkit/references/packages/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](/cdf/deploy/cdf_toolkit/guides/setup).
* 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](/cdf/deploy/cdf_toolkit/guides/auth).
## 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.
In your directory, run:
```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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.
1. Use the arrow keys to move and **Space** to select modules.
2. Press **Enter** to confirm.
Run the setup wizard from the project root:
```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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..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.
```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf build
cdf deploy --dry-run
cdf deploy
```
Inspect the dry-run output and confirm the configuration looks correct before running `cdf deploy`.
Run the CI/CD generator from the project root:
```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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:
1. 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.
2. The selected data model (ISA-95 or CFIHOS spaces) is deployed and visible.
3. Any selected source-system extraction pipeline configs appear in CDF.
4. Run the setup wizard in check mode to validate the configuration — it reports any invalid or missing required config values without writing changes:
```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
python modules/common/cdf_project_foundation/scripts/setup_project.py --check
```
5. 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___` | Read-only | READ on data models, instances, time series, files, RAW, and transformations, scoped to the dataset and spaces. |
| `producer___` | Read/write | Consumer rights plus WRITE, run transformations, workflow orchestration, and sessions CREATE. |
| `admin___` | Admin | Full capabilities including `groups:write`, projects, datasets, data models, transformations, and pipelines. |
Group names follow the persona-led convention `_[_]_` — see the [Resource naming reference](/cdf/deploy/reference/cdf_resource_naming_conventions#access-management) 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.
```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
/
├── .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..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 ` 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](https://hub.cognite.com/groups/578) |
| Version | 1.0.0 |
| Last updated | 2026 |