Guides
Start typing to search…

Importing Project Types Using Raptor CLI

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
  • Facets Templates: Quick access to Facets-provided templates/project-types
  • Custom repository imports: Use your own Git repositories (public or private) to import any project-type
  • Automatic module uploads: Upload IaC modules alongside project types which are not yet registered in the control plane.

Quick Start

Note: Install raptor through this guide.

Import Project Type from Provided Library

raptor import project-type aws

This imports the AWS project type from the provided library with all metadata and templates.

Import with Modules

git clone github.com/Facets-cloud/facets-modules-redesign.git
raptor import project-type aws --modules-dir ./facets-modules-redesign/modules

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

Import Sources

1. Project Type Import from Existing Library

raptor import project-type <PROJECT_TYPE_NAME>

What Happens:

  • Fetches metadata from https://github.com/Facets-cloud/facets-modules-redesign (Provided Library of project types.)
  • Reads project-types/<NAME>/project-type.yml for configuration, imports base template from project-types/<NAME>/base/and finally creates or updates the project type in Control Plane

2. Custom Public/Private Repository Import

Import project types from any Git repository apart from the default one.(GitHub, GitLab, Bitbucket, Azure DevOps, self-hosted Git, etc.).

Command:

raptor import project-type <NAME> \
  --git-url <PRIVATE/PUBLIC REPOSITORY_URL> \
  --git-ref <BRANCH_OR_TAG> \
  --path <PATH_TO_PROJECT_TYPE>
  --vcs-account-id <VCS_ACCOUNT_ID (only incase of private repo)> \
  -f <LOCAL_METADATA_FILE (only incase of private repo)>

Required Flags:

  • --git-url - Full Git repository URL (HTTPS)
  • --git-ref - Git branch, tag, or commit reference
  • --path - Path within the repository to the project type directory (containing project-type.yml)
  • --vcs-account-id - VCS account ID from Facets Control Plane
  • -f, --file - Local path to project-type.yml metadata file

Examples:

// For Public Repo
raptor import project-type java-service \
  --git-url https://github.com/myorg/templates.git \
  --git-ref main \
  --path templates/java-service
  
//For Private Repo
raptor import project-type internal-service \
  --git-url https://github.com/myorg/private-templates.git \
  --git-ref main \
  --path templates/internal-service \
  --vcs-account-id acc_a1b2c3d4e5 \
  -f ./internal-service.yml

Getting Your VCS Account ID:

# List VCS accounts in your Control Plane
raptor get vcs-accounts

Uploading IaC Modules

The --modules-dir flag allows to uploads IaC modules in the control plane (if not present), which are specified in your project type metadata.

How It Works

  1. Specify modules in project-type.yml:
name: aws
description: AWS project type with common configurations
allowedClouds:
  - AWS

modules:
  - path: aws/cloud_account/aws_provider/1.0
    intent: cloud_account
    flavor: aws_provider
    version: 1.0

  - path: aws/network/aws_vpc/1.0
    intent: network
    flavor: aws_vpc
    version: 1.0

  - path: aws/kubernetes_cluster/eks/1.0
    intent: kubernetes_cluster
    flavor: eks
    version: 1.0
  1. Run import with --modules-dir:
raptor import project-type aws --modules-dir /Users/myuser/facets-modules-redesign/modules
  1. Raptor will:
    • Read module paths from project-type.yml and look for modules at: <modules-dir>/<path>
    • 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

Fetching project type metadata from repository...
Cloning repository (shallow clone)...
Updating existing project type 'AWS' in Control Plane...

✓ Project type updated successfully
  Name: AWS
  Description: AWS project type with common configurations.
  ID: 691d8859a1985a048d8fef4f
  Version: v1 (non-legacy)
  Repository: https://github.com/Facets-cloud/facets-modules-redesign.git (default library)
  Template Path: project-types/aws/base
  IaC Tool: TERRAFORM 1.5.7

📦 Uploading IaC modules...
  [1/5] Uploading cloud_account/aws_provider from aws/cloud_account/aws_provider/1.0...

=== 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)
  Stage: PREVIEW (use 'raptor publish iac-module cloud_account/aws_provider/' to publish)

  [1/5] ✓ Uploaded cloud_account/aws_provider
  [2/5] Uploading kubernetes_cluster/eks...
  ...

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

Project Type Metadata Format

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

name: aws
description: AWS project type with Cloud, VPC, and other modules
allowedClouds:
  - AWS

modules:
  # Cloud Account Setup
  - path: aws/cloud_account/aws_provider/1.0
    intent: cloud_account
    flavor: aws_provider
    version: 1.0

  # Networking
  - path: aws/network/aws_vpc/1.0
    intent: network
    flavor: aws_vpc
    version: 1.0
	#and other modules..

Complete Examples

Example 1: Import AWS Project Type with Modules

# Clone your project type repository
git clone https://github.com/myorg/project-types.git
cd project-types

# Import project type and upload modules
raptor import project-type aws \
  --modules-dir ./modules

# All modules from project-type.yml will be uploaded automatically

Example 2: Import from Private Repo with Modules

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

# 2. Prepare local metadata file
cat > custom-type.yml <<EOF
name: internal-platform
description: Internal platform services
allowedClouds:
  - AWS
  - GCP

modules:
  - path: internal/service/standard/1.0
    intent: service
    flavor: standard
    version: 1.0
EOF

# 3. Import with modules
raptor import project-type internal-platform \
  --git-url https://github.com/myorg/private-templates.git \
  --git-ref main \
  --path templates/platform \
  --vcs-account-id acc_xyz123 \
  -f custom-type.yml \
  --modules-dir ./local-modules

Troubleshooting

Module Upload Failures

Problem: Module validation fails with Terraform errors

Solution:

  1. Check Terraform syntax in the failing module
  2. Ensure all required variables are present
  3. Run terraform validate locally in the module directory
  4. 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:

  1. Ensure your module has proper output_interfaces and output_attributes in outputs.tf
  2. Use --skip-output-write to skip output processing: 
    raptor create iac-module -f /path/to/module --skip-output-write
  3. Create output types manually: 
    raptor create output-type @custom/my-output -f output-schema.yaml

Command Reference

# Import from Facets library
raptor import project-type <NAME>

# Import from custom public repo
raptor import project-type <NAME> \
  --git-url <GIT_URL> \
  --git-ref <BRANCH> \
  --path <PATH>

# Import from private repo
raptor import project-type <NAME> \
  --git-url <GIT_URL> \
  --git-ref <BRANCH> \
  --path <PATH> \
  --vcs-account-id <ACCOUNT_ID> \
  -f <METADATA_FILE>

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

# Flags
--git-url string          # Git repository URL
--git-ref string          # Git branch/tag (default: master)
--path string             # Path to project type directory
--vcs-account-id string   # VCS account ID for private repos
-f, --file string         # Local metadata YAML file
--modules-dir string      # Local modules directory
--useBranch               # Enable git branch usage (default: true)
-o, --output string       # Output format (table|wide|json|yaml)

FAQ

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.

Updated 33 minutes ago