Creating Projects

Related Guides and Examples:

• Overview: Firefly Workflows and Guardrails: High-level concepts and options.

• Creating New Firefly Workflows: How to set up managed workflows.

• Creating Guardrail Rules in Firefly: How to define and enforce policies and best practices.

• Creating Variable Sets: Managing reusable variable collections.

• Triggering Workspace Deployment: How to trigger a workspace deployment from the Firefly UI.

Firefly Projects are organizational units designed to group and manage related Infrastructure as Code (IaC) orchestration resources like workspaces, variable sets, and self-hosted runners. By establishing project hierarchies, you can maintain clear separation of environments, teams, and applications, while implementing robust access controls. Projects serve as the primary boundary for access control, resource organization, and operational management within Firefly Workflows, enabling teams to independently manage their infrastructure and providing a structured approach to organizing complex deployments across multiple environments. This document provides a comprehensive guide on how to create and configure Projects in Firefly Workflows.

Key Benefits of Using Projects:

• Organizational Structure: Group related workspaces, variables, and self-hosted runner pools by team, application, environment, or any logical boundary that matches your organization's needs.

• Access Control: Implement Role-Based Access Control (RBAC) to ensure users can only access resources within their assigned projects.

• Resource Inheritance: Leverage hierarchical variable inheritance and configuration sharing across project boundaries.

• Operational Efficiency: Set default configurations like drift detection schedules and notification settings at the project level.

• Scalability: Support complex organizational structures with up to 5 levels of project hierarchy.

Project Structure and Hierarchy

Firefly Projects support a hierarchical structure that mirrors your organizational needs:

Project Hierarchy Levels

1. Organization Level (Root):

   • The top-level container for all projects.

   • Contains global resources accessible across all projects.

   • Houses the default project that serves as the root directory.

2. Project Level:

   • First level of organization-specific groupings.

   • Examples: /aws, /azure, /development, /production.

3. Sub-Project Levels (up to 5 total levels):

   • Further subdivision of projects.

   • Examples: /aws/production, /aws/production/frontend, /aws/production/frontend/web.

Project Components

Each project can contain:

• Workspaces: Terraform/OpenTofu/Terragrunt execution environments.

• Variable Sets: Reusable collections of configuration variables.

• Runner Pools: Self-hosted execution environments.

• Users: Team members with specific role assignments.

• Sub-Projects: Nested organizational units.

Variable Inheritance

Projects follow a hierarchical variable inheritance model that distinguishes between direct variable assignment and variable set access:

Direct Variable Inheritance

• Inheritance Flow: Organization → Project → Sub-Project → Workspace.

• Automatic Propagation: When you set variables directly on a project, all underlying projects and workspaces automatically inherit those variables.

• Precedence Rules: Workspace variables override sub-project variables, which override project variables, which override organization variables.

• Example: If you set AWS_REGION=us-east-1 on the /aws project, all sub-projects like /aws/production and /aws/development, as well as all workspaces within them, will automatically have access to this variable.

Variable Set Access Control

• First-Level Assignment: Variable set assignment to projects can only occur at the first level of the hierarchy.

• Automatic Sub-Project Access: When you assign a variable set to a project, all sub-projects and workspaces within them can consume that variable set.

• Access-Based Assignment: Assigning a variable set to a project is different from direct variable inheritance. It controls who can view and use that variable set.

• User Scope: Only users who have access to that project and its sub-projects can view and use the assigned variable set.

• Selective Consumption: Child resources can choose to consume variable sets from their parent projects, but the variable set must be accessible to the user performing the assignment.

• Example: If you assign a variable set called aws-production-secrets to the /aws project, only users with access to /aws and its sub-projects can view and use this variable set when creating workspaces or sub-projects.

User Access and Project Visibility

• First-Level Assignment: User assignment to projects can only occur at the first level of the hierarchy.

• Automatic Sub-Project Access: Users assigned to a Level 1 project automatically gain visibility and access to all sub-projects beneath it.

• Inherited Permissions: The role assigned to the user at Firefly organization level applies to all projects and sub-projects, ensuring consistent access control throughout the hierarchy.

• Example: A user assigned as Admin in Firefly and assigned to the /aws project automatically has Admin access to the /aws project and all sub-projects, including /aws/production, /aws/development, and all workspaces within these sub-projects.

Creating a New Project: Step-by-Step

Follow the wizard in the Firefly UI to create a new Project.

Procedure:

1. Navigate to Projects:

   • In the Firefly UI, click on Workflows from the main navigation menu.

   • Then, click on the Projects sub-section.

2. Add New Project:

   • Click on the + Create new project button.

3. Enter Project Details:

   • Name:

     • Provide a unique name for your project (3-64 characters).

     • Use alphanumeric characters, hyphens, and underscores only.

     • The name must be unique within the selected parent directory.

     • Example: aws-production, frontend-services, data-platform.

   • Description (Optional):

     • Add a free-text explanation to help identify the project's purpose.

     • Example: "Production AWS infrastructure for customer-facing applications".

4. Configure Project Hierarchy:

   • Parent Project (Optional):

     • Select a parent project if this is a sub-project.

     • Projects can nest up to 5 levels deep.

     • Leave blank to create a root-level project.

     • Example: Select /aws as parent for a /aws/production sub-project.

5. Add Classification Labels:

   • Labels (Optional):

     • Add tags to categorize or filter projects.

     • Use existing labels from the dropdown or create new ones.

     • Example: environment:production, team:platform, cost-center:engineering.

6. Assign Users and Permissions:

   • User Assignment (Optional):

     • Select users who should have access to this project.

     • Users will receive permissions based on their assigned roles.

     • Available Roles:

       • Viewer: Can view project assets and resources.

       • Admin: Can create, update, and delete project resources.

     • Users assigned to parent projects automatically inherit access to sub-projects.

7. Configure Periodic Plan for Drift Detection:

   • Set Default Periodic Plan (Optional):

     • Enable automatic drift detection for all workspaces in this project.

     • Simple Configuration:

       • Check the box to enable periodic plans.

       • Set frequency: "Once every X hours" (e.g., 5 hours).

     • Advanced Configuration:

       • Click the rotation icon to convert to full cron expression.

       • Enter custom cron pattern (minimum frequency: hourly).

       • Example: 0 */5 * * * for every 5 hours.

8. Configure Project Variables:

   • Variable Set Selection (Optional):

     • Choose one or more reusable variable sets to inherit.

     • Variable sets can be defined at organization or project level.

     • Conflict Resolution: If multiple variable sets contain the same variable name, you'll see a warning and must resolve the conflict.

   • Custom Variables (Optional):

     • Define project-specific variables that will be inherited by all child resources.

     • Variable Properties:

       • Name: The variable key (must be unique within the project).

       • Value: The variable value (can be overridden at workspace level).

       • Sensitive: Mark as sensitive to hide the value in logs and UI.

       • Environment Variable: Export as environment variable during execution.

9. Review and Create:

   • Carefully review all configured settings for your project.

   • Ensure the hierarchy, user assignments, and variable configurations are correct.

   • Click Create to create the project.

After Creating a Project

• Activation: The project becomes active immediately and is available for workspace creation and resource assignment.

• Workspace Creation: When creating new workspaces, the project will appear in the project assignment dropdown.

• Variable Inheritance: All variables and variable sets configured at the project level will automatically be available to child resources.

• Access Control: Users assigned to the project will gain access to all project resources according to their roles.

• Drift Detection: If configured, automatic drift detection will begin running for all workspaces created within the project.

Managing Projects

Once created, you can manage your projects through various operations:

Viewing and Filtering Projects

• Project List View: The Projects page displays all projects you have access to.

• Search and Filter:

  • Text Search: Search by project name, description, or labels.

  • Hierarchy Navigation: Expand and collapse project hierarchies.

  • Column Sorting: Sort by name, user count, workspace count, or other attributes.

Editing Projects

• Basic Information: Update name, description, parent project, and labels.

• User Management: Add or remove users.

• Periodic Plan for Drift Detection: Modify periodic plan schedules.

• Variable Configuration: Access through the Edit Variables option in the actions menu.

Variable Management

• Variable Sets: Attach or detach variable sets from projects.

• Custom Variables: Add, modify, or remove project-specific variables.

• Inheritance Tracking: View variable origins and override indicators.

• Conflict Resolution: Resolve conflicts between variable sets with duplicate keys.

Deleting Projects

• Workspace Handling: Choose to delete associated workspaces or transfer them to the parent project.

• Resource Cleanup: Optionally run IaC destroy operation before deleting workspaces.

• Confirmation Required: Type the exact project name to confirm deletion.

Examples of Project Structures

Here are some practical examples of how to organize projects:

Environment-Based Organization

Organization
├── development/
│   ├── frontend/
│   └── backend/
├── staging/
│   ├── frontend/
│   └── backend/
└── production/
    ├── frontend/
    └── backend/

Cloud Provider Organization

Organization
├── aws/
│   ├── production/
│   │   ├── us-east-1/
│   │   └── us-west-2/
│   └── development/
├── azure/
│   ├── production/
│   └── development/
└── gcp/
    ├── production/
    └── development/

Team-Based Organization

Organization
├── platform-team/
│   ├── infrastructure/
│   └── monitoring/
├── frontend-team/
│   ├── web-apps/
│   └── mobile-apps/
└── data-team/
    ├── analytics/
    └── ml-pipelines/

Best Practices for Creating Projects

• Plan Your Hierarchy: Design your project structure before creating projects. Consider your organization's structure, deployment patterns, and access control requirements.

• Use Meaningful Names: Choose descriptive names that clearly indicate the project's purpose and scope.

• Leverage Labels: Use consistent labeling conventions to enable effective filtering and organization.

• Design Variable Inheritance: Plan your variable inheritance strategy to minimize duplication and ensure consistency.

• Start Simple: Begin with a basic project structure and expand as your needs grow.

• Document Your Structure: Maintain documentation explaining your project hierarchy and naming conventions.

• Regular Review: Periodically review and optimize your project structure as your organization evolves.

• Use Periodic Plan for Drift Detection Wisely: Configure appropriate drift detection schedules that balance monitoring needs with resource consumption.

• Consider Compliance: Ensure your project structure supports any regulatory or compliance requirements.

Project Permissions and RBAC

Understanding the Role-Based Access Control (RBAC) system is crucial for effective project management:

Role Definitions

• Viewer:

  • Can view project assets and resources.

  • Cannot modify configurations or trigger deployments.

  • Suitable for stakeholders who need visibility without operational access.

• Admin:

  • Can create, update, and delete project resources.

  • Can manage workspaces, variable sets, and self-hosted runner pools.

  • Can assign users and modify project configurations.

  • Suitable for team leads and infrastructure operators.

Permission Inheritance

• Project Hierarchy: Users with admin role in a project automatically have admin access to all sub-projects.

• Resource Access: Project membership determines access to workspaces, variable sets, and self-hosted runner pools within the project.

• Global Access: Some resources can be marked as global, making them accessible across all projects.

By thoughtfully creating and managing projects, you can build a scalable, secure, and well-organized infrastructure management system that grows with your organization's needs.