Creating Project Types via Raptor

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 (AWS, GCP, Azure, empty)
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 --managed facets/aws

Valid managed names are facets/aws, facets/gcp, facets/azure, and facets/empty. 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 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 can be any version

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. These three fields are only required when --include-base-template 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

# Managed import from the official Facets library
raptor import project-type --managed facets/<aws|gcp|azure|empty> [--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
    --managed string          Import an official Facets project type (facets/aws, facets/gcp, facets/azure, facets/empty)
    --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: 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.