Creating Project Types via Raptor

Import and update project types in the Control Plane with the raptor import project-type command, covering managed and custom imports plus IaC module uploads.

The raptor import project-type command allows you to import or update project types in Control Plane. This command supports:

Upsert Behavior: Creates new or updates existing project types
Managed imports: One-flag access to the official Facets project types (for example AWS, GCP, Azure, empty, Linode, Vultr)
Custom imports: Define your own project type in a YAML metadata file, with optional base templates from public or private Git repositories
Automatic module uploads: Upload IaC modules (and their output types) alongside project types which are not yet registered in the control plane.

Quick Start

Note: Install raptor through this guide.

raptor import project-type --list-managed

Lists what the official repository currently ships.

raptor import project-type --managed facets/aws

Managed names follow the form facets/<name>, for example facets/aws, facets/gcp, facets/azure, facets/empty, facets/linode, facets/vultr. There is no fixed allowlist; run raptor import project-type --list-managed to see what the official repository currently ships. Use --name to override the display name:

raptor import project-type --managed facets/aws --name "Production AWS"

A managed import automatically:

Clones the official facets-modules-redesign repository
Imports the project type with all of its modules and output types
Skips validation (trusted official modules)

Import a Custom Project Type

raptor import project-type -f ./project-type.yml

The project type name is read from the YAML file's name field. The command takes no positional arguments.

Import a Blank Project Type

A YAML with just two fields is valid, and gives you a project type with no resource-type mappings — which the Control Plane treats as every resource type being allowed. This is the right starting point for a module-development sandbox, where you want your own modules to show up without mapping each one first.

name: my-project-type
description: What this project type is for

raptor import project-type -f ./my-project-type.yml

Note that --managed facets/empty is not the same thing: it maps exactly the three cloud_account provider flavors, so a module you author later stays invisible in projects of that type until you map it with raptor create resource-type-mapping.

Import with Modules

raptor import project-type -f ./project-type.yml --modules-dir ./modules --outputs-dir ./outputs

This imports the project type AND uploads all IaC modules specified in the project type metadata.

Project Type Metadata Format

The project-type.yml file defines your project type configuration.

name: aws                          # Required. Project type name
description: AWS project type      # Required. Human-readable description

# Git template details. Only used with --include-base-template.
gitUrl: https://github.com/myorg/templates.git
gitRef: main
baseTemplatePath: project-types/aws/base

iacTool: TERRAFORM                 # Optional. TERRAFORM (default) or OPENTOFU
iacToolVersion: 1.5.7              # Optional. TERRAFORM must be 1.5.7; OPENTOFU must be 1.12.0 or higher (default 1.12.0)

allowedClouds:                     # Optional. Defaults to [AWS, AZURE, GCP, KUBERNETES]
  - AWS

modules:                           # Optional. IaC modules to include
  # Cloud Account Setup
  - intent: cloud_account
    flavor: aws_provider

  # Networking
  - intent: network
    flavor: aws_vpc

  # Kubernetes Cluster
  - intent: kubernetes_cluster
    flavor: eks

By default, project blueprints created from the project type start from an empty template. Pass --include-base-template to use gitUrl, gitRef, and baseTemplatePath from the metadata file instead, so that new blueprints start with default resources. gitUrl and gitRef are required when --include-base-template is set. baseTemplatePath stays optional, and is only read when the flag is set.

Importing from a Private Repository

If the base template lives in a private repository, provide a VCS account so the backend can authenticate:

# 1. Get your VCS account ID
raptor get accounts --type VERSION_CONTROL

# 2. Import using the VCS account for authentication
raptor import project-type -f ./project-type.yml \
  --include-base-template \
  --vcs-account-id <ACCOUNT_ID>

For public repositories, no VCS account is needed.

Uploading IaC Modules

The --modules-dir flag uploads the IaC modules listed in your project type metadata to the control plane (if not present).

How It Works

List modules in project-type.yml by intent and flavor (see format above). You do not specify module paths.
Run import with --modules-dir:

raptor import project-type -f ./project-type.yml --modules-dir ./modules --outputs-dir ./outputs

Raptor will:
- Walk --modules-dir recursively and discover each module by matching the intent and flavor fields in its facets.yaml
- If --outputs-dir is provided, discover and create the output types the modules need before uploading them
- Upload each module with full validation and create output types automatically from output_interfaces and output_attributes
- Report success/failure for each module

Example Output

Reading metadata from file: ./project-type.yml

Creating project type 'AWS' in Control Plane...

✓ Project type created successfully
  Name: AWS
  Description: AWS project type with common configurations
  ID: 691d8859a1985a048d8fef4f
  Template Path: project-types/aws/base

📦 Uploading IaC modules...

🔧 Creating output types...
  Creating output type @facets/aws_cloud_account...
  ✓ Created output type @facets/aws_cloud_account

  [1/3] Discovering module cloud_account/aws_provider...
  [1/3] Found at: aws/cloud_account/aws_provider/1.0
  [1/3] Uploading cloud_account/aws_provider...

=== Validating Module ===
✓ Checking facets.yaml...
✅ facets.yaml validated successfully
✓ Running terraform fmt...
🎨 Terraform files formatted
✓ Running terraform validate...
🔍 Terraform validation successful

=== Processing Outputs ===
✓ Found output_interfaces and/or output_attributes
✓ Generating output files...
✅ Generated output files: output-lookup-tree.json, output.facets.yaml

Uploading module cloud_account/aws_provider...
✓ Module uploaded successfully (ID: 691d9093a1985a048d8fef5c)

  [1/3] ✓ Uploaded cloud_account/aws_provider
  [2/3] Uploading network/aws_vpc...
  ...

📊 Module Upload Summary:
  ✓ Uploaded: 3
  ❌ Failed: 0

Complete Examples

Example 1: Import the Official AWS Project Type

# One command. Modules and output types are included automatically.
raptor import project-type --managed facets/aws

Example 2: Custom Project Type from a Private Repo with Modules

# 1. Get your VCS account ID
raptor get accounts --type VERSION_CONTROL

# 2. Prepare the metadata file
cat > custom-type.yml <<EOF
name: internal-platform
description: Internal platform services
gitUrl: https://github.com/myorg/private-templates.git
gitRef: main
baseTemplatePath: templates/platform
allowedClouds:
  - AWS
  - GCP

modules:
  - intent: service
    flavor: standard
EOF

# 3. Import with modules
raptor import project-type -f custom-type.yml \
  --include-base-template \
  --vcs-account-id acc_xyz123 \
  --modules-dir ./local-modules \
  --outputs-dir ./local-outputs

Troubleshooting

Module Upload Failures

Problem: Module validation fails with Terraform errors

Solution:

Check Terraform syntax in the failing module
Ensure all required variables are present
Run terraform validate locally in the module directory

Upload manually with more control:

raptor create iac-module -f /path/to/module --skip-validation

Problem: Module conflicts with built-in Facets module

Error:

Cannot update Facets built-in module with intent network and flavor aws_vpc.
Please choose a different flavor.

Solution: Use a different flavor name in your module's facets.yaml:

intent: network
flavor: aws_vpc_custom  # Changed from aws_vpc
version: 1.0

Problem: Output type creation fails

Solution:

Ensure your module has proper output_interfaces and output_attributes in outputs.tf

Create the output types manually:

raptor create output-type @custom/my-output -f output-schema.yaml

Use --dry-run to validate the schema file without creating anything:

raptor create output-type @custom/my-output -f output-schema.yaml --dry-run

Command Reference

# List the managed project types the official library currently ships
raptor import project-type --list-managed

# Managed import from the official Facets library
raptor import project-type --managed facets/<name> [--name NAME]

# Custom import from a metadata file
raptor import project-type -f <METADATA_FILE>

# Include base template resources in new blueprints
raptor import project-type -f <METADATA_FILE> --include-base-template

# Import from a private repo
raptor import project-type -f <METADATA_FILE> \
  --include-base-template \
  --vcs-account-id <ACCOUNT_ID>

# Import project type with new module uploads which are not registered in the control plane yet
raptor import project-type -f <METADATA_FILE> \
  --modules-dir <MODULES_DIRECTORY> \
  --outputs-dir <OUTPUTS_DIRECTORY>

Flags:

-f, --file string             YAML metadata file with the project type configuration
    --list-managed            List managed project types available to import, then exit
    --managed string          Import an official Facets project type (format: facets/<name>; run --list-managed for the actual list)
    --name string             Override the project type name (works with --managed and --file)
    --include-base-template   Use gitUrl/gitRef/baseTemplatePath from the metadata for default blueprint resources
    --modules-dir string      Local directory containing IaC modules to upload (auto-set for --managed)
    --outputs-dir string      Local directory containing output type definitions (auto-set for --managed)
    --vcs-account-id string   VCS account ID for private repositories
    --useBranch               Enable git branch usage (default: true)
-o, --output string           Output format (table|wide|json|yaml)

FAQ

Q: Do I need to specify the project type name in the command?

A: No. For custom imports the name is read from the YAML file's name field; for managed imports it comes from the library. Use --name to override it in either case.

Q: Do I need to upload modules every time?

A: No. If modules are already uploaded, they will be skipped. Use --modules-dir only when you want to upload new or updated modules.

Q: What happens to existing projects when I update a project type?

A: Existing projects are not affected. Project type updates only affect new projects created after the update.

Q: Will re-importing merge into the project type's existing module mappings?

A: No — it replaces them. Every import sends the complete definition, so re-importing a YAML whose modules: list is short or missing removes the mappings that are not in it, and an import with no modules: key at all turns a curated project type into an unrestricted one and resets its base template to the default empty one. Keep the YAML you import as the full source of truth for that project type, and use raptor create resource-type-mapping / raptor delete resource-type-mapping for incremental changes.

Q: Can I use modules from different project types?

A: Yes! Once modules are uploaded to the Control Plane, they can be used across any project regardless of which project type imported them.

Q: What if my module has custom dependencies?

A: Ensure all Terraform dependencies are specified in your module's Terraform configuration. The validation process runs terraform init which will fetch required providers and modules.