Glossary

When talking about "the" CLI in the context of Panfactum, we are talking about the pf binary that ships with the DevShell.

This CLI can be used to drive various operations against both local IaC / CaC as well as operations against running infrastructure.

In PNCF, an environment is a set of infrastructure components that is isolated from the infrastructure components of other environments. What happens in one environment does not impact what happens in another.

Moreover, in PNCF, RBAC permissions are scoped to the environment level. Assigning a user permissions in an environment will automatically grant corresponding access to all resources contained in that envirnment (e.g., network tunnels, control plane components, databases, etc.).

Environment are conceptual in nature, but they often correspond to infrastructure primitives in the cloud hosting provider. For example, for AWS-enabled environments, a corresponding AWS account is created for the environment.

Importantly, a single environment can have multiple cloud hosting providers enabled. This enables you to have a single environment with clusters deployed to multiple hosting providers which will be able to communicate with each other and receive the same sets of permissions.

Examples of common environments:

• production: Used for user-facing infrastructure
• staging: Used for end-to-end tests
• development: Used for rapid integration tests

Note that PNCF has no opinion on what environments you create, what their purpose is, or how you use them. In other words, a "production" environment has no conceptual meaning to the underlying framework, it is just a string identifier.

The one exception is a special environment called "management". That is used for some internal meta-operations. See the corresponding glossary entry.

The infrastructure repository (often called the "infra repo") is your Git repository that houses all of the code and configuration needed to manage your Panfactum-based infrastructure.

One of the primary purposes of PNCF is to provide tooling to help you manage this repository and make it your own. Everything about how PNCF infrastructure behaves is controlled in this single repository (i.e., there is no external PNCF management server outside your control).

For more information about the standard layout of the infrastructure repository, see these docs.

A Panfactum module is an infrastructure module authored, tested, and maintained by Panfactum. These modules are published as part of the PNCF and are available for use in any PNCF deployment.

Panfactum modules are categorized as:

• Direct modules: Intended to be deployed directly via Terragrunt into your environments
• Submodules: Intended to be used as child modules within your own first-party modules

Panfactum modules are versioned alongside the Panfactum Stack and should be pinned to a specific stack version using the pf_stack_version Terragrunt variable.

In your Terragrunt configuration, Panfactum direct modules are sourced using include.panfactum.locals.pf_stack_source, which automatically handles version resolution and caching.

A region refers to an AWS geographic region (e.g., us-east-2, eu-west-1) where infrastructure resources are deployed.

In the Panfactum stack, a region is a subdivision of an environment. Each environment can span multiple regions, and each environment-region pair may host its own Kubernetes cluster.

Region-specific configuration is stored in region.yaml files within the environments directory:

environments/
  production/
    us-east-2/
      region.yaml    <- region-specific settings
      module1/
      module2/
    eu-west-1/
      region.yaml
      module1/

Each region's region.yaml can define settings such as the AWS region name, provider configuration, and Terragrunt variables that apply to all modules deployed in that region.

Infrastructure-as-Code is typically packaged as reusable modules that can be parameterized during deployment by providing different inputs. This pattern allows for significant flexibility and code reuse which are critical when deploying the same infrastructure modules across various systems and environments.

Inputs can be as simple as resource tags but can also completely change the behavior of a module. It is up to the module author to define what inputs their module allows.

Most IaC tools allow users to provide inputs interactively, but inputs can also be defined directly in code. When the configuration for a deployed module is provided via code, we call that configuration-as-code (CaC).

While OpenTofu allows defining inputs via simple .tfvars files, a more powerful approach is to use a purpose-built configuration manager such as Terragrunt. Terragrunt provides several advantages:

• Packaged in a single, free, open-source binary that runs completely locally (as opposed to Terraform Cloud or Spacelift)
• Allows you to share intra-module configuration blocks such as the state backend and providers
• Can deploy specific versions of both local and remote infrastructure modules
• Integrates with sops to define secrets directly in your configuration-as-code
• Can define inter-module dependencies to control deployment order and chain module outputs to other modules' inputs
• Adds retry logic to deal with common intermittent provider and network failures
• Adds many built-in functions that can be used in your configuration files

In the Panfactum stack, we deploy all infrastructure modules using Terragrunt.

A first-party module is an infrastructure module written and maintained by your organization, typically stored in your stack repository under a directory configured by the iac_dir repo variable.

First-party modules are written in OpenTofu/Terraform HCL syntax and follow the same conventions as any other module. They are deployed via Terragrunt using include.panfactum.locals.source to automatically resolve versioning.

Common uses for first-party modules include:

• Deploying your own application workloads
• Combining multiple Panfactum submodules into higher-level abstractions
• Adding organization-specific infrastructure not covered by Panfactum modules

First-party modules may reference Panfactum submodules as child modules to leverage shared infrastructure patterns.

Infrastructure-as-Code (IaC) is the practice of configuring your infrastructure programmatically instead of interactively.

This came to prominence in the mid 2000s as many infrastructure providers and systems began offering well-documented configuration APIs that could be used by third-party tooling such as Terraform.

The advantages of the IaC approach include:

• Speed: Thousands of discrete infrastructure components can be deployed in a single command
• Reproducibility: Ensures the exact same infrastructure can be deployed repeatedly
• Community: Best-practice patterns are easily shared and jointly maintained
• Change management: Infrastructure changes are reviewed using the same processes as application code, often improving an organization to meet compliance standards such as SOC 2
• Documentation: All the settings for a particular system are easily searchable, often within a single file

Due to these enormous benefits, IaC has become the de-facto methodology for managing infrastructure in professional settings. This is especially critical in settings where multiple, similar, complex environments must be provisioned and managed (for example, when maintaining development, staging, and production environments with nearly identical infrastructure).

The most widely adopted IaC tool is Terraform (and its open-source fork, OpenTofu), which uses a declarative approach — you describe the desired end state rather than the steps to reach it.

Panfactum uses OpenTofu as its IaC tool, paired with Terragrunt for configuration management.

A module is a reusable, parameterizable unit of infrastructure code written in Hashicorp Configuration Language (HCL). It encapsulates a set of related infrastructure resources (e.g., a Kubernetes deployment, an AWS VPC) that can be configured and deployed together.

Modules accept inputs (also called variables) that control their behavior, and produce outputs that can be passed to other modules. This design enables infrastructure patterns to be shared and reused across environments.

In the Panfactum stack, modules are broadly categorized as:

• Root modules: Deployed directly via Terragrunt
• Submodules: Called as child modules within other modules

And by authorship:

• Panfactum modules: Provided by the Panfactum project
• First-party modules: Written by your organization
• Third-party modules: Sourced from external providers

In late 2023, HashiCorp announced a major update to its license for Terraform and its other previously open-source tools. This eliminated the ability for organizations to provide alternatives to HashiCorp's paid, hosted offerings when using Terraform.

As a result, many concerned parties came together to fork the last open-source Terraform release and create the first release of OpenTofu at the end of 2023. OpenTofu is a drop-in replacement for Terraform v1.6 (tofu vs terraform). However, as new releases emerge, the feature sets will begin to slowly diverge.

Key advantages over HashiCorp's Terraform:

• Truly open-source: Licensed under the Mozilla Public License 2.0 (MPL 2.0)
• Community-driven: Dozens of companies have come together to sponsor the salaries of many full-time engineers to work on its development
• More contributions: Already receives more contributions and bugfixes than the original Terraform project
• Drop-in replacement: Fully compatible with Terraform v1.6 syntax and providers

OpenTofu will likely become the new industry-standard as organizations grapple with the license change in their next upgrade cycle.

Panfactum uses OpenTofu exclusively. All references to "terraform" in Panfactum documentation refer to OpenTofu unless otherwise specified.

A provider is an OpenTofu/Terraform plugin that translates HCL resource declarations into API calls for a specific infrastructure platform or service. Providers are the integration layer that allows OpenTofu to manage resources across hundreds of different systems.

Each provider is responsible for:

• Authenticating with the target platform's API
• Exposing resource types (e.g., aws_vpc, kubernetes_deployment) that can be declared in HCL
• Managing create, read, update, and delete (CRUD) operations on resources

Common providers used in the Panfactum stack include:

• AWS: Manages AWS resources (VPCs, EKS clusters, IAM roles, etc.)
• Kubernetes: Manages Kubernetes resources
• Helm: Deploys Helm charts
• Vault: Manages HashiCorp Vault resources

Providers must be declared in the terraform.required_providers block and initialized before a module can be deployed. Panfactum's Terragrunt scaffolding automatically handles provider configuration for the most common providers via the pf-tf-init command.

A root module is the top-level OpenTofu/Terraform module that is deployed directly into your infrastructure. It is the entry point for a deployment unit and is configured by a terragrunt.hcl file.

Root modules differ from submodules in that they:

• Are invoked directly by Terragrunt via terragrunt apply
• Maintain their own Terraform state file
• Define provider configurations
• Can declare dependencies on other root modules

In the Panfactum stack, root modules typically live in packages/infrastructure/ (for Panfactum-provided modules) or in the directory specified by the iac_dir repo variable (for first-party modules).

A submodule is an OpenTofu/Terraform module that is called as a child module within another module rather than being deployed directly via Terragrunt. Submodules are composed into larger modules using module blocks in HCL.

In the Panfactum stack, submodules are a key mechanism for code reuse. Panfactum provides many submodules (such as kube_pod, kube_service, etc.) that encapsulate common infrastructure patterns and can be imported into first-party modules.

Unlike root modules, submodules:

• Do not have their own Terraform state
• Do not declare provider configurations (these are inherited from the parent)
• Cannot be deployed standalone via Terragrunt

When using Panfactum submodules in first-party code, use the pf_module_source and pf_module_ref variables to ensure the submodule version automatically tracks the deployed Panfactum Stack version.

While many IaC tools exist, none has achieved as much popularity as HashiCorp's Terraform.

Terraform provides a few key benefits over the alternatives which has allowed it to become the standard way to work with infrastructure:

• Declarative: You only need to declare your desired infrastructure state in the simple Hashicorp Configuration Language. This unlocks key capabilities:

  • Removal of complex imperative logic for reconciling the current state and the desired state
  • Easily readable source-code files that can quickly be understood by developers of all skill levels
  • Infrastructure deltas that alert you to potential changes before they are applied
  • A robust ecosystem of tooling that can easily parse source code files to ensure organizational compliance standards are met

• API-oriented: Rather than develop its own infrastructure management logic, Terraform simply wraps your infrastructure providers' public APIs. This allows for a simple, concise programming interface and a straightforward mechanism for debugging if something goes awry.

• Plugin-oriented: Terraform provides a standard, stable interface for adding new infrastructure providers, allowing the wider developer community to produce integrations with nearly every system that provides a public API. This allows organizations to define all infrastructure using a single toolchain, greatly simplifying infrastructure management.

In late 2023, HashiCorp announced a major update to its license for Terraform and its other previously open-source tools, changing from the Mozilla Public License (MPL 2.0) to the Business Source License (BSL). This eliminated the ability for organizations to provide alternatives to HashiCorp's paid, hosted offerings when using Terraform, prompting the community to fork Terraform and create OpenTofu.

Panfactum uses OpenTofu (the open-source Terraform fork) rather than HashiCorp's Terraform. References to "terraform" throughout the Panfactum documentation should be understood as referring to OpenTofu.

Terragrunt is a thin wrapper around OpenTofu/Terraform that provides configuration-as-code capabilities for managing infrastructure module deployments. It is developed by Gruntwork and is free, open-source, and runs entirely locally.

In the Panfactum stack, Terragrunt is the primary tool for deploying all infrastructure modules. It is configured via terragrunt.hcl files in the environments directory.

Key capabilities that Terragrunt adds over plain OpenTofu:

• Configuration sharing: Share provider configurations, backend settings, and common inputs across modules
• Version management: Pin specific versions of both local and remote infrastructure modules
• Inter-module dependencies: Declare deployment order and chain outputs between modules
• Secrets integration: Integrates with sops for encrypted secrets in configuration files
• Retry logic: Handles common intermittent provider and network failures automatically
• Built-in functions: Additional helper functions for constructing configuration values

A third-party module is an infrastructure module written and maintained by an organization other than Panfactum or your own organization. These are typically sourced from public module registries such as the OpenTofu Registry or Terraform Registry.

Third-party modules can be used in the Panfactum stack just like any other module. However, Panfactum recommends preferring Panfactum-provided modules for infrastructure within the Panfactum ecosystem, as they are tested and maintained to work together correctly.

When using third-party modules, be mindful of:

• Versioning: Pin modules to specific versions to ensure reproducibility
• Trust: Review module code before deploying, as it will have access to your infrastructure credentials
• License: Check the module's license for compatibility with your organization's requirements

A unit is a single deployable infrastructure instance in the Panfactum stack. It corresponds to a directory containing a terragrunt.hcl file within the environments directory.

Each unit:

• Sources exactly one infrastructure module
• Has its own configuration (inputs, provider settings, dependencies)
• Maintains its own Terraform state file
• Is deployed and managed independently via terragrunt apply

In practice, a unit is what you interact with when running IaC commands — you navigate to a unit's directory and run terragrunt plan or terragrunt apply.

For example, in this environments layout:

environments/
  production/
    us-east-2/
      kube_cert_manager/
        terragrunt.hcl    <- this is a unit
      kube_vault/
        terragrunt.hcl    <- this is a unit

Each terragrunt.hcl represents a separate unit, even if multiple units source the same module.

A cluster refers to a Kubernetes cluster deployed on AWS EKS (Elastic Kubernetes Service). It serves as the container orchestration platform for running application workloads within a Panfactum environment.

Key characteristics:

• One per environment-region pair: Each combination of environment and AWS region gets its own cluster
• Managed via EKS: Panfactum uses AWS EKS for the Kubernetes control plane
• Image caching: Container images are pulled through an AWS ECR pull-through cache for reliability and performance
• Cost: A cluster costs approximately $75–150/month at minimum due to EKS and node costs

Clusters are bootstrapped using Panfactum's infrastructure modules and managed through Terraform/OpenTofu. Once provisioned, the cluster hosts Panfactum's standard set of addons (ingress, monitoring, secret management, etc.) before application workloads are deployed.

Determinate Nix is a downstream distribution of the Nix package manager produced by Determinate Systems. Panfactum strongly recommends it as the way to install Nix, though it is not strictly required.

Key differences from other Nix implementations:

• Flakes enabled by default: Nix flakes are enabled out of the box without extra configuration
• Improved installer: Provides a reliable, uninstallable installer that works across Linux and macOS
• macOS Linux builder: Includes a native Linux builder on macOS via the Apple Virtualization framework
• Performance improvements: Parallel evaluation, lazy trees, and multi-threaded garbage collection

A DevShell (development shell) is a reproducible, isolated shell environment built using Nix flakes that automatically provides all the tooling required to work with the Panfactum framework.

Key properties:

• Automatic activation: Activated automatically via direnv when you navigate into the repository
• Isolated: Installed in a separate directory and does not interfere with system-level tooling
• Versioned: Tools are pinned to specific versions that are tested to work with your live infrastructure
• Configurable: Defined in a flake.nix file at the repository root; custom tools can be added
• First-run build time: Takes several minutes on initial setup as Nix downloads and builds packages

The Panfactum DevShell includes CLI tools like kubectl, tofu, aws, helm, and all other utilities needed for infrastructure management. Organizations can extend the base DevShell to include their own tooling.

Nix is both a package manager and a functional programming language used by Panfactum to codify local developer environments and tooling.

Panfactum uses Nix to:

• Define the DevShell: All development tooling is declared in various flake.nix files and built reproducibly by Nix
• Pin tool versions: Specific versions of every tool are locked, ensuring all developers and CI systems use identical binaries
• Isolate environments: Nix installs packages in isolation without polluting system paths

Nix hosts nixpkgs, one of the largest software repositories in the world, making nearly any tool available as a Nix package. Panfactum leverages Nix flakes for reproducible, version-locked environment definitions that integrate with direnv for seamless shell activation.

Note: You do not need to learn the Nix language to use Panfactum. The flake.nix file follows a straightforward template, and adding custom tools requires only minimal edits.

A Nix flake is a standardized project structure for Nix that provides hermetic, reproducible builds by explicitly declaring all dependencies and locking them to exact versions.

A flake consists of two key files:

• flake.nix: Declares the flake's inputs (dependencies) and outputs (packages, shells, etc.)
• flake.lock: A lockfile that pins every input to a specific revision, ensuring reproducibility

In Panfactum, the flake.nix at the repository root defines the DevShell. It imports the Panfactum flake as an input and uses it to construct a development environment with all required tooling. A typical Panfactum flake.nix includes:

• The Panfactum flake input (pinned to a specific release)
• A devShells output that extends the Panfactum base shell
• Optional additional packages or customizations for the organization

Flakes are a relatively new Nix feature and are enabled by default in Determinate Nix. They replace older patterns like shell.nix and default.nix with a more standardized approach.

Hardware-as-a-Service (HaaS) is a model in which a provider owns and maintains physical hardware (servers, networking equipment, storage devices, etc.) and leases it to customers. The provider handles hardware procurement, maintenance, repairs, and physical hosting, while the customer manages the software stack running on that hardware.

HaaS differs from IaaS in that the customer typically gets access to dedicated physical machines rather than virtualized resources. This can be important for workloads that require:

• Bare-metal performance: No hypervisor overhead
• Hardware-level control: Custom firmware, specialized accelerators (GPUs, FPGAs)
• Compliance: Certain regulatory requirements mandate dedicated physical hardware

HaaS sits below IaaS in the cloud computing stack — IaaS providers themselves often use HaaS arrangements (or own their hardware outright) to build their virtualized offerings.

Infrastructure-as-a-Service (IaaS) is a cloud computing model in which a provider supplies virtualized computing resources — servers, storage, networking, and other fundamental infrastructure — over the internet on a pay-as-you-go basis.

With IaaS, the provider manages the physical hardware (data centers, physical servers, power, cooling, etc.), while the customer manages everything above that: operating systems, middleware, runtimes, applications, and data.

Common IaaS providers include:

• AWS (Amazon Web Services)
• Google Cloud Platform (GCP)
• Microsoft Azure

IaaS is the foundational layer of the cloud computing stack. Panfactum is built primarily on top of AWS IaaS offerings and uses Infrastructure-as-Code to manage IaaS resources programmatically.

Platform-as-a-Service (PaaS) is a cloud computing model in which a provider delivers a complete platform — including the operating system, runtime, middleware, and development tools — so that customers can focus on building and deploying applications without managing the underlying infrastructure.

PaaS sits between IaaS and SaaS in the cloud computing stack:

• IaaS gives you raw infrastructure (VMs, storage, networking)
• PaaS gives you a managed platform to run your code
• SaaS gives you a fully managed application

Examples of PaaS offerings include Heroku, AWS Elastic Beanstalk, Google App Engine, and Vercel.

Panfactum effectively serves as a self-hosted PaaS — it provides a complete, production-ready platform built on IaaS that handles networking, autoscaling, observability, CI/CD, and more, so that teams can focus on deploying their applications.

Software-as-a-Service (SaaS) is a software distribution model in which a provider hosts an application and makes it available to customers over the internet, typically on a subscription basis. The provider manages everything — infrastructure, platform, application code, updates, and security.

SaaS sits at the top of the cloud computing stack:

• IaaS gives you raw infrastructure
• PaaS gives you a managed platform
• SaaS gives you a fully managed application

Examples of SaaS products include GitHub, Slack, Datadog, and PagerDuty.

In the Panfactum ecosystem, several third-party SaaS products are integrated via IaC modules (e.g., Authentik SSO connectors for services like GitHub and MongoDB Atlas). One goal of Panfactum is to reduce reliance on expensive SaaS tools by providing self-hosted alternatives where practical (e.g., using Grafana instead of Datadog for observability).