Skip to content

Vijfpas concepts and glossary

1. Core terms

Product

A Vijfpas product is an application or user-facing capability, for example nibbler, genea, shop, or notimon.

  • lives in one or more environments
  • deploys onto platform services
  • is owned by a product team

Platform service

A platform service is a reusable capability that products depend on, for example Kubernetes, Keycloak, PostgreSQL, GitLab, or Ceph.

  • has an owner team
  • has a privilege tier
  • has backups, monitoring, and runbooks

Service scope

A service scope is an optional naming dimension inside a service family that expresses the purpose split of that family.

Common scope tokens:

  • customer
  • app
  • logging
  • platform

Examples:

  • gitlab-customer
  • kafka-app
  • opensearch-logging
  • taiga-platform

Notes:

  • service scope is orthogonal to environment and tier
  • service scope is not the same as a node qualifier such as prim or sec
  • not every service family needs both scopes
  • the default design is one shared service estate per environment; service-scope is an exception tool, not the baseline

Machine identity

A machine identity is a named non-human credential bound to exactly one VM, service, or automation consumer.

  • used for internal package/artifact access, database clients, and deployment paths
  • not shared across teams, environments, or multiple VMs/services
  • stored in a secrets system and delivered by configuration management

Authoritative recovery source

The authoritative recovery source is the system, archive, or configuration set from which a service is officially restored.

Examples:

  • Terraform + Ansible for rebuild-only VM and config state
  • pgBackRest for PostgreSQL data
  • GitLab non-DB backup plus backup-etc for GitLab/Gitaly filesystem and repository state
  • hosted-artifact export plus PostgreSQL restore for Nexus

Restore scope

A restore scope is the declared boundary of a recovery action.

Common restore scopes:

  • config-only rebuild
  • service restore
  • environment restore
  • tenant-scoped restore
  • platform recovery

Inventory item

A physical or foundational item such as servers, switches, VLANs, IP ranges, certificates, and administrative accounts.

Environment

A Vijfpas environment is the primary network, access, and delivery boundary.

Vijfpas defines five default environments:

  • nfr
  • pfm
  • dev
  • acc
  • prd

Environment intent:

  • nfr contains substrate services, trust anchors, and the operator-source tiers needed to build, update, and recover the rest of the platform
  • pfm contains shared internal platform services used across environments
  • dev contains development-facing internal and customer workloads
  • acc is prod-adjacent validation and UAT with prod-class controls
  • prd contains production delivery and operations

Trust domain

A trust domain is a secondary boundary inside an environment for separating identity, execution, secrets, and deployment authority.

Examples:

  • internal platform services
  • customer development SaaS control plane
  • internal application runtime
  • customer application runtime

Release stage

A lifecycle stage used by products and delivery pipelines.

Current target baseline:

  • first-party products: dev / acc / prd
  • tst is dropped from the target platform baseline
  • network and access boundaries should align with the release stage names above

Confidentiality class

The default confidentiality label assigned to a dataset or service data path:

  • uses CONF-0 through CONF-4
  • expresses impact if the data is disclosed
  • does not change merely because data is outside prd

Detailed definitions and controls are in confidentiality-model.md.

Exposure class

The tenant visibility and self-service label assigned to a platform capability:

  • uses PX0 through PX3
  • expresses who may see or use a capability
  • is separate from confidentiality class

Detailed definitions are in tenant-exposure-matrix.md.

Development tenancy

Boundary for customer developer operations and code execution:

  • repo/project ownership
  • web IDE workspace ownership
  • CI runner scope
  • artifact and deployment-request scope
  • tenant-visible logs/events

Application/data tenancy

Boundary for runtime authorization and data access inside products:

  • tenant_id-aware authorization
  • tenant-scoped runtime policy and API access
  • tenant-scoped data partitioning/isolation

Tenant

A tenant is a company/customer boundary consuming the Product Engineering Platform.

  • owns tenant users, projects, and runtime resources
  • is isolated from other tenants by identity, policy, execution, and data boundaries
  • can run in one or more environments and trust domains

Tenant isolation profile

Defines how strongly a tenant is isolated:

  • shared-by-domain profile (baseline): tenant shares control-plane foundations inside the same trust domain but uses strict tenant-scoped identity, execution, policy, and data boundaries
  • dedicated profile (exception): dedicated runtime and/or data instances for contractual or compliance requirements

Customer development SaaS domain

Customer-facing control and execution domain that includes:

  • customer portal/UI
  • Git service
  • browser IDE/workspaces
  • tenant CI/CD runners
  • artifact stores and deployment request paths

Default trust assumption: customer workspace and CI jobs execute untrusted code.

Tier

A tier is the functional role of a network segment inside an environment.

Infra substrate/control tiers:

  • admin
  • ilom
  • mgmt
  • corosync
  • cephpub
  • cephclu

Platform-service tiers in the shared pfm environment:

  • svc
  • core
  • egress
  • bck

Application environment tiers (dev, acc, prd):

  • admin
  • dmz
  • svc
  • core
  • egress
  • bck

Tier placement semantics

Use tiers by service role, not by team ownership.

  • admin is the operator-source tier. Put workbenches, bastions, admin automation, and other SSH-only operator entry hosts here. Do not treat it as a general application hosting tier.
  • nfr-admin is the default operator-source tier for platform engineering across all environments, including pfm.
  • dev-admin, acc-admin, and prd-admin are environment-local admin or break-glass tiers, not the default platform engineering source path.
  • dmz is the published ingress edge. Put internet-reachable reverse proxies, public auth endpoints, and other approved public entry services here. Prefer stateless edge components.
  • svc is the shared service and control-API tier. Put internal UIs, control planes, and human/API-facing services here when they are not just raw internet edge endpoints.
  • core is the private backend and execution tier. Put stateful data stores, workers, runners, tenant execution pools, and internal compute here.
  • egress is the outbound-exception tier. Put tightly controlled fetch, mirror, sync, and scanning services here when they need approved internet egress.
  • bck is the backup-repository tier. Put pgBackRest repo hosts and similar backup-target systems here when they must stay separate from the live service and data tiers.
  • In pfm, svc, core, egress, and bck are reserved for trusted shared platform services such as gitlab-pfm, postgresql on pfm-core, gitaly on pfm-core, nexus on pfm-egress, and pgBackRest; they are not a place for customer-facing or untrusted code-execution paths.

Common split-service patterns:

  • customer-facing platforms often span dmz + svc + core
  • internal control services often span svc + core
  • GitLab is the source-control and CI/CD control plane while Nexus is the promoted artifact distribution plane; acc and prd consume promoted artifacts and are not separate default GitLab environments
  • Nexus sits in egress while its database dependency remains in core
  • keep one postgresql estate per environment by default; separate platform and application data with databases, schemas, roles, and backup/restore scope inside that estate
  • keep one rabbitmq estate per environment by default; separate workloads with vhosts, users, and policies
  • keep one keycloak estate per environment by default; separate internal and application clients with realms, clients, groups, and admin roles
  • pgBackRest repo hosts sit in bck while PostgreSQL remains in core
  • Jupyter, Airflow, and similar systems often split svc control paths from core workers
  • Kubernetes uses admin for API access sources, dmz for ingress, svc for shared control services, and core for worker and stateful workloads

Network segment

A network segment is the concrete VLAN/subnet for one environment and one tier, using the pattern <environment>-<tier>.

Examples:

  • nfr-admin
  • nfr-mgmt
  • pfm-svc
  • dev-core
  • acc-svc
  • prd-egress
  • dev-bck

Trust zone

A trust zone is the firewall and routing view of one or more network segments with the same policy treatment.

Network allocation baseline

Segment VLAN Subnet Gateway Primary intent Status
nfr-ilom 10 10.0.10.0/24 10.0.10.1 hardware out-of-band management live
nfr-admin 42 10.0.42.0/24 10.0.42.1 substrate operator-source tier for substrate and trust workbenches live
nfr-mgmt 20 10.0.20.0/24 10.0.20.1 Proxmox host management and substrate control services live
nfr-corosync 21 10.0.21.0/24 10.0.21.1 Proxmox Corosync cluster-control traffic live
pfm-svc 43 10.0.43.0/24 10.0.43.1 shared platform control/API tier for self-hosted services such as gitlab.pfm-svc.vijfpas.be and keycloak.pfm-svc.vijfpas.be target
pfm-core 44 10.0.44.0/24 10.0.44.1 shared platform backend/data tier for self-hosted services such as postgresql.pfm-core.vijfpas.be and gitaly.pfm-core.vijfpas.be target
pfm-egress 45 10.0.45.0/24 10.0.45.1 shared platform mirror/proxy/scanner tier for services such as nexus.pfm-egress.vijfpas.be target
pfm-bck 46 10.0.46.0/24 10.0.46.1 shared platform backup-repository tier for pgBackRest and similar backup targets target
prd-admin 22 10.0.22.0/24 10.0.22.1 production admin/jump/automation interface live
dev-admin 23 10.0.23.0/24 10.0.23.1 development admin/jump/automation interface live
acc-admin 24 10.0.24.0/24 10.0.24.1 acceptance admin/jump/automation interface planned
acc-dmz 25 10.0.25.0/24 10.0.25.1 acceptance internet-facing ingress workloads planned
acc-svc 26 10.0.26.0/24 10.0.26.1 acceptance service API tier planned
acc-core 27 10.0.27.0/24 10.0.27.1 acceptance internal workloads and prod-like backends planned
acc-egress 28 10.0.28.0/24 10.0.28.1 acceptance egress-exception workloads planned
acc-bck 48 10.0.48.0/24 10.0.48.1 acceptance backup-repository tier planned
prd-dmz 30 10.0.30.0/24 10.0.30.1 internet-facing production ingress workloads live
prd-svc 31 10.0.31.0/24 10.0.31.1 production backend and service APIs live
dev-core 32 10.0.32.0/24 10.0.32.1 development internal workloads live
dev-egress 33 10.0.33.0/24 10.0.33.1 development egress-exception workloads live
prd-egress 34 10.0.34.0/24 10.0.34.1 production egress-exception workloads live
prd-core 35 10.0.35.0/24 10.0.35.1 production private backend/data workloads planned
dev-dmz 36 10.0.36.0/24 10.0.36.1 development internet-facing ingress workloads planned
dev-svc 37 10.0.37.0/24 10.0.37.1 development service API tier live
dev-bck 47 10.0.47.0/24 10.0.47.1 development backup-repository tier live
prd-bck 49 10.0.49.0/24 10.0.49.1 production backup-repository tier live
nfr-cephpub 40 10.0.40.0/24 10.0.40.1 Ceph client/public path live
nfr-cephclu 41 10.0.41.0/24 10.0.41.1 Ceph cluster replication path live

Terminology note:

  • nfr-admin is the operator-source tier for platform engineering across nfr, pfm, dev, acc, and prd.
  • nfr-mgmt remains the management/control tier for Proxmox, PBS, UniFi, DNS/DHCP, firewall/VPN, and similar substrate systems.
  • pfm-svc, pfm-core, pfm-egress, and pfm-bck are the trusted shared-platform tiers for services that must not depend on dev for recovery or supply-chain trust.
  • Platform engineering admin traffic should originate from nfr-admin by default and land on workload or service IPs in the target environment.
  • dev-admin, acc-admin, and prd-admin remain environment-local admin or break-glass paths when routine application operations justify them.
  • Do not place customer-facing or untrusted code-execution surfaces on the pfm service tiers.
  • Dedicated admin NICs on workload VMs are exception-only.

Environment and tier grouping map (Mermaid)

flowchart TB
  subgraph NFR[nfr]
    IADM[nfr-admin]
    ILOM[nfr-ilom]
    MGMT[nfr-mgmt]
    CORO[nfr-corosync]
    PUB[nfr-cephpub]
    CLU[nfr-cephclu]
  end

  subgraph PFM[pfm]
    PFSVC[pfm-svc]
    PFCORE[pfm-core]
    PFEGR[pfm-egress]
    PFBCK[pfm-bck]
  end

  subgraph DEV[dev]
    DADM[dev-admin]
    DDMZ[dev-dmz]
    DSVC[dev-svc]
    DCORE[dev-core]
    DEGR[dev-egress]
    DBCK[dev-bck]
  end

  subgraph ACC[acc]
    AADM[acc-admin]
    ADMZ[acc-dmz]
    ASVC[acc-svc]
    ACORE[acc-core]
    AEGR[acc-egress]
  end

  subgraph PRD[prd]
    PADM[prd-admin]
    PDMZ[prd-dmz]
    PSVC[prd-svc]
    PCORE[prd-core]
    PEGR[prd-egress]
  end

  IADM --> MGMT
  IADM --> PFSVC
  IADM --> PFEGR
  MGMT --> DADM
  MGMT --> AADM
  MGMT --> PADM
  PFSVC --> PFCORE
  DDMZ --> DSVC --> DCORE
  ADMZ --> ASVC --> ACORE
  PDMZ --> PSVC --> PCORE
  PUB --> CLU

DNS namespace

Domain namespace baseline:

  • vijfpas.com: public internet namespace for externally exposed endpoints
  • vijfpas.be: internal platform namespace for non-public services
  • both domains are registered in AWS

Environment-first split

A design rule for duplicated service instances across environments and trust domains:

  • separate dev, acc, and prd as first-class network and access boundaries
  • keep acc separate from prd, even when acc receives production data copies
  • separate internal and customer execution domains inside dev where external customer code runs
  • keep dedicated-tenant profile available for strict compliance cases

1.1 Domain model (Mermaid)

flowchart LR
  INV[Inventory items] --> PLAT[Platform services]
  PLAT --> PROD[Products]
  ENV[Environments] --> PLAT
  TD[Trust domains] --> PLAT
  TENANT[Tenants] --> PLAT
  TENANT --> PROD
  SEG[Network segments] --> PLAT
  TEAM[Teams] --> PLAT
  TEAM --> PROD

1.2 First-party application stack

Default stack for self-developed web applications:

  • Front-end: Next.js with TypeScript
  • Back-end: Axum with Rust
  • Primary operational database: PostgreSQL
  • Projection pattern: Kafka streams/events into query and analytics stores (for example Neo4j, OpenSearch app/search, lakehouse)

2. Privilege-tier model (SoD)

privilege-tier is the SoD and control-criticality dimension. It is distinct from network tier, which describes placement inside an environment.

  • Privilege-tier 0: identity, secrets, and network edge
  • Privilege-tier 1: compute and storage
  • Privilege-tier 2: runtime, CI/CD, observability
  • Privilege-tier 3: products and product-owned schemas

Tier usage notes:

  • customer development SaaS execution resources (workspaces/runners) are privilege-tier 2 and treated as untrusted execution surfaces
  • production deployment authority is separated from ordinary customer development permissions

Detailed policy and access controls are in Vijfpas Security and SoD.

2.1 Tier stack (Mermaid)

flowchart TB
  T0[Privilege-tier 0: IAM/Secrets/Network]
  T1[Privilege-tier 1: Compute/Storage]
  T2[Privilege-tier 2: Runtime/CI-CD/Observability]
  T3[Privilege-tier 3: Products]

  T0 --> T1 --> T2 --> T3

3. Planes (ownership domains)

Planes are the logical operating split of the platform. They overlay environments and tiers, but they are not themselves network segments or trust zones.

Plane usage rules:

  • every platform service has exactly one primary owner plane
  • a plane may operate across multiple environments and tiers, but only through explicit approved paths
  • a plane workbench is an operator source for that plane; it is not a substitute for environment and tier boundaries
  • higher-risk environments should use separate workbench instances per plane and environment boundary

Recommended platform planes:

  • substrate: Proxmox, Ceph, PBS, UniFi, DNS/DHCP/NTP, base images, VM lifecycle
  • trust: Keycloak, OpenBao, CA hierarchy, Vaultwarden, certificate policy, security controls
  • delivery: GitLab, Gitaly, Nexus, runners, package/artifact delivery, developer workflow tooling
  • runtime: Kubernetes, Traefik, Rancher, shared runtime and ingress capabilities
  • data: PostgreSQL, MariaDB, Neo4j, Redis, Kafka/RabbitMQ, lakehouse, notebook, and data workflow services

Plane and network model relationship:

  • environments and tiers define trust boundaries and routing policy
  • planes define ownership, workbench placement, and SoD boundaries
  • do not create plane-specific VLANs; grant plane-specific access into the approved environment/tier matrix instead

Domain

A domain is a capability area inside a plane.

Domain usage rules:

  • every platform service has one primary owner domain inside its owner plane
  • a domain is smaller than a plane and represents a coherent knowledge area
  • domains are stable enough to anchor ownership, runbooks, backlog, and automation boundaries

Examples:

  • substrate/storage-backup
  • trust/identity-access
  • delivery/artifact-package
  • runtime/cluster-foundation
  • data/databases

Team

A team is the staffed ownership unit for one or more domains.

Team usage rules:

  • one team may own multiple domains during early platform growth
  • domains may be split into separate teams later without redefining the plane model
  • team names should describe the owned domain rather than imply a strict hierarchy

Examples:

  • infra-storage
  • security-platform
  • runtime-cluster
  • data-database
  • data-lakehouse

Squad

A squad is a temporary delivery group that spans domains or planes for a defined outcome.

Squad usage rules:

  • squads are temporary and outcome-oriented
  • squads do not replace primary service ownership
  • squads should be named for the initiative, not for a standing org unit

Examples:

  • k8s-bootstrap
  • gitlab-rollout
  • tenant-onboarding

4. Teams and squads

Current consolidated team identifiers used across docs:

  • infra
  • contain
  • net
  • data
  • observ
  • cicd
  • security
  • buscon (business continuity)
  • iam
  • tenant-enablement (cross-team squad)
  • product teams (web, mobile, fpga, third)

Recommended stable team-unit naming pattern:

  • <plane>-<domain> where practical
  • examples: infra-storage, runtime-ingress, data-analytics
  • temporary cross-plane work should use a squad name, not a pseudo-team hierarchy

5. Naming conventions

Objects

  • Hosts: <role>-<index> or <site>-<role>-<index>
  • VMs and guest hostnames: <service>[-<qualifier>]-<environment>-<tier> (example: nexus-pfm-egress, postgresql-prim-dev-core, workbench-runtime-prd-admin)
  • Workbenches: workbench-<plane>-<environment>-<tier> as the unique machine name (example: workbench-runtime-prd-admin)
  • Service and SSH aliases in DNS should stay short and zone-scoped: <service>.<environment>-<tier>.vijfpas.be (example: nexus.dev-egress.vijfpas.be, workbench-runtime.prd-admin.vijfpas.be)
  • Do not rely on the DNS zone alone to make machine identities unique across the platform; the VM/object/guest hostname should already be unique before DNS is applied.
  • Kubernetes clusters:
  • k8s-dev-internal
  • k8s-dev-customer
  • k8s-acc
  • k8s-prd

Qualifiers

qualifier is the generic term for the optional segment between service and environment-tier.

Use these qualifier rules:

  • omit the qualifier when there is one obvious singleton for that service in that environment/tier (for example nexus-pfm-egress, taiga-pfm-svc)
  • use a semantic qualifier when the node responsibility is intentionally different and stable (for example prim, sec, hub, proxy, coord, worker, broker, controller, connect, plane)
  • use stable numeric ordinals for homogeneous clusters or elected-role systems where leadership can move between nodes: n01, n02, n03
  • when both a role and an ordinal are needed, combine them: broker01, controller01, worker01, coord01, data01
  • prefer zero-padded numeric ordinals over a/b/c; ordinals sort better, scale better, and avoid accidental semantic meaning
  • do not encode transient runtime state in machine names; avoid leader, primary, active, or master for systems where that role can move between nodes
  • an explicit assigned pair such as the current PostgreSQL primary/standby can still use prim and sec when those roles are operationally stable and intentionally managed as named nodes

DNS Records

Use DNS records like this:

  • unique machine name: <service>[-<qualifier>]-<environment>-<tier> for the Proxmox object, inventory hostname, and guest hostname
  • canonical per-node FQDN: <service>[-<qualifier>].<environment>-<tier>.vijfpas.be (for example workbench-runtime.dev-admin.vijfpas.be, postgresql-prim.dev-core.vijfpas.be, rabbitmq-n01.dev-core.vijfpas.be)
  • canonical service alias: <service>.<environment>-<tier>.vijfpas.be when clients should use a stable shared endpoint instead of a node-specific name
  • canonical per-node FQDNs and canonical service aliases should use A/AAAA records to the real node IP or service VIP
  • use CNAME only for compatibility aliases, controlled indirection, or transition windows where a short alias should follow another canonical name
  • prefer one canonical service alias and keep overlap aliases temporary during migrations
  • PTR records should point to the canonical per-node FQDN, not to a shared service alias and not to a CNAME

Linux Users

Use Linux account names like this:

  • human workbench/operator users: codex-<team>
  • non-human machine/service users: mi-<plane>-<domain>-<service>
  • mi-* names intentionally do not include environment or node qualifiers; environments are fully separated and the same logical service identity should keep the same account name everywhere
  • reserve fixed numeric UID/GID values for both codex-* and mi-* users across all environments
  • see account-registry.md for the canonical UID/GID table

Platform control services

  • GitLab instances:
  • gitlab-dev
  • gitlab-pfm
  • gitlab-customer
  • Keycloak instances:
  • keycloak-pfm
  • optional env-local keycloak-dev
  • optional env-local keycloak-acc
  • optional env-local keycloak-prd

Keycloak baseline rule:

  • keep keycloak-pfm as the default shared internal Keycloak deployment
  • add env-local Keycloak only when an environment needs a distinct public/runtime/customer identity boundary
  • publish an env-local Keycloak endpoint through the appropriate ingress or service path for that environment
  • use realms, clients, groups, and admin-role separation for internal versus application identity boundaries unless a stronger deployment split is explicitly required
  • create a separate Keycloak deployment only by exception, for example a materially different exposure boundary or a hard trust/isolation requirement

Repositories

  • infra-live/ for applied IaC
  • infra-modules/ for reusable IaC modules
  • platform/ for platform manifests and charts
  • products/<product>/ for product source and deploy config
  • docs/ for platform documentation

6. Documentation patterns

  • one service catalog entry for every platform service
  • one product catalog entry for every product
  • one ADR per major decision
  • one runbook for each operationally critical service
  • when environment, tier, or trust-domain boundaries change, update concepts.md, architecture.md, and implementation docs in the same change set