---
title: Project
---

**Projects** group related resources under a shared operational boundary. A project gives teams one place to manage ownership, access policies, inherited defaults, and an optional shared workspace for a set of infrastructure resources.

Projects do not provision infrastructure themselves. Instead, they help standardize how multiple [Resources](./resource) are created and managed.

## Project Properties

Each project in InfraKitchen contains the following core properties:

| Property | Description | Notes |
| :------- | :---------- | :---- |
| **Name** | Human-readable project name | Must be unique |
| **Description** | Summary of the project's purpose | Optional |
| **Workspace** | Shared workspace reference | Optional |
| **Configuration** | Project-level behavior flags | Includes workspace behavior and resource approval exceptions |
| **Owners** | Users allowed to administer the project | Owners effectively gain project admin actions |
| **Dependency Tags** | Default tags shared with project resources | Can be inherited by children |
| **Dependency Config** | Default config values shared with project resources | Can be inherited by children |
| **Labels** | Tags for filtering and organization | Free-form list |
| **Status** | Current project status | `enabled` or `disabled` |
| **Revision Number** | Version tracking for changes | Auto-incremented on updates |
| **Creator** | User who created the project | Used for audit and permissions |

## What Projects Are For

Use projects when you want multiple resources to share the same governance and defaults.

Projects are useful for:

- Grouping resources by team, product, environment, or business domain
- Assigning a clear set of project owners
- Applying shared labels, tags, and inherited configuration defaults
- Reusing a single workspace across project resources when appropriate
- Managing project-level policies separately from individual resources

Example:

```yaml
Project: payments-platform
Owners:
  - platform-admin@example.com
  - sre@example.com

Workspace: platform-live-infra
Configuration:
  always_use_workspace: true
  allow_unapproved_metadata_edits:
    - description
    - labels

Dependency Tags:
  - name: team
    value: platform
    inherited_by_children: true
  - name: cost_center
    value: fin-042
    inherited_by_children: true

Dependency Config:
  - name: environment
    value: production
    inherited_by_children: true
```

Resources assigned to this project can inherit those values automatically, while still keeping their own template, variables, parents, and lifecycle state.

## Creating Projects

Projects are created from the **Projects** section in the UI:

1. **Create the project**

    Navigate to **Projects** and click <kbd>Create</kbd>. Enter the project name and an optional description.

2. **Assign a workspace**

    Select an optional shared workspace.

3. **Add labels and owners**

    Configure optional labels and owners.

4. **Set project configuration**

    Set project configuration such as **Always use workspace** and any resource fields that can bypass approval.

5. **Add dependency defaults**

    Add optional dependency tags and dependency config values, then save.

## Project Configuration

Projects currently support the following project-level configuration options:

| Option | Description | Notes |
| :----- | :---------- | :---- |
| **Always Use Workspace** | Forces project resources to use the project's assigned workspace for workspace sync operations | Requires the project to have a workspace assigned |
| **Allow Unapproved Metadata Edits** | Lets project owners choose which `ResourceUpdate` fields can be updated without creating an approval request | Users still need normal resource edit permission; field-specific validation still applies |

When `always_use_workspace` is enabled:

- A resource in the project can use the project's workspace automatically
- The project workspace acts as the fallback sync target during resource workspace operations
- This helps keep related resource code in one repository boundary

When `allow_unapproved_metadata_edits` contains selected resource update fields:

- A resource update is applied directly when every changed field is included in the configured list
- InfraKitchen skips the temporary-state approval step for those selected fields
- Normal permission checks still apply, including special checks for sensitive fields such as storage changes
- Mixed updates still require approval if even one changed field is not included in the configured list

Example:

```yaml
Configuration:
  allow_unapproved_metadata_edits:
    - description
    - labels
```

With this configuration:

- Changing only `description` updates the resource immediately
- Changing only `labels` updates the resource immediately
- Changing `description` and `labels` together updates the resource immediately
- Changing `description` and `variables` together still creates an approval request because `variables` is not in the allowed list

InfraKitchen allows selecting any field from the `ResourceUpdate` model in the project UI. This makes it possible to tune approval flow at the project level, but broad allow-lists should be used carefully because they reduce review for resource lifecycle changes.

## Project Defaults and Inheritance

Projects can define shared dependency tags and dependency config values.

### Dependency Tags

Project dependency tags are useful for applying shared metadata such as billing, ownership, or environment classification across the resources in that project.

### Dependency Config

Project dependency config values act as low-priority defaults for resource variables. When InfraKitchen prepares a resource, project config is applied first, and then parent resource config can override it.

This makes projects a good place for broad defaults such as:

- environment names
- naming prefixes
- common region or platform settings
- standard cloud tagging inputs

:::info[Priority Order]
Project dependency config acts as defaults. Parent resource configuration is applied after that and can override project-provided values.
:::

## Managing Projects

Projects support the following lifecycle actions:

| Action | When Available | Description |
| :----- | :------------- | :---------- |
| **Edit** | Status: `enabled` | Update project metadata, owners, labels, workspace, or defaults |
| **Disable** | Status: `enabled` | Prevent further project administration actions until re-enabled |
| **Enable** | Status: `disabled` | Re-activate the project |
| **Delete** | Status: `disabled` | Permanently remove the project |

## Permissions

Project actions are controlled by RBAC and project ownership.

| Action | Permission Model | Notes |
| :----- | :--------------- | :---- |
| **View** | Standard authenticated access and entity visibility rules | Depends on platform RBAC |
| **Create** | Project API write permission | Required to create new projects |
| **Edit / Disable / Enable / Delete** | Project admin, project owner, or super admin | Owners effectively gain admin actions |
| **Manage Policies** | Project admin-level access | Controls entity-level rules |

Owners are not just informational. InfraKitchen checks the owner list when deciding whether a user can administer project actions.

## Integration with Other Features

Projects connect several InfraKitchen concepts:

- **Resources** can belong to a project and inherit project tags/config defaults
- **Golden State** shows whether project resources are aligned with each template's active version
- **Workspaces** can be assigned at the project level to centralize generated code sync
- **Policies** can be applied at the project boundary, separate from individual resources
- **Audit Logs** and **Revisions** track changes to project metadata over time

See also: [Golden State](golden-state)