How the platform works

The whole contract between a service team and the platform. The build turns it into a service chart.

# The contract between this service repo and the platform.
#
# `orchestrator-component-release generate-service` reads this file alone to produce the
# service Helm chart. Chart version and image digests come from the build's
# images.yaml, never from here.
apiVersion: v1
kind: ServiceChart
name: active-reports-service

platform:
  chart: platform-services
  # Quoted: a bare `>` is YAML's folded-block-scalar indicator.
  version: ">=2.4.0, <3.0.0"

services:

  active-reports-service:
    app:
      # Platform env groups: Okta, identity (CORS, provider URI), feature flags, OTLP. Values come from the landscape.
      envGroups: [okta, identity, featureFlags, otlp]

      # .NET settings, nested; rendered as A__B variables. "$required": the product or environment sets it at the
      # same path. Connection strings, SyncFusionLicenseKey and AppStream__SharedSecret come from the secret below.
      appSettings:
        Logging:
          LogLevel:
            Default: Trace
        AllowedHosts: "*"
        BlobPathPrefix: taxfixedassets
        Identity:
          UseIdentityProvider: "$required"     # the inverse of Okta; set by the product

      env:
        # Was http://*:80 in the legacy chart; the hardened securityContext cannot bind below 1024.
        ASPNETCORE_URLS: "http://*:8080"

      # Synced by External Secrets Operator.
      # Secret variables: env var name -> Key Vault secret name in the product's `secrets` pool (names only).
      secrets:
        AppStream__SharedSecret: tfa-reports-appstream-secret
        ConnectionStrings__AppConfig: tfa-appconfig-connection
        ConnectionStrings__Database: tfa-reports-database-connection
        ConnectionStrings__StorageAccount: tfa-reports-storage-connection
        Sentry__Dsn: tfa-sentry-dsn
        SyncFusionLicenseKey: tfa-syncfusion-license

      containerPort: 8080

      # /api/health requires authorization, so an unauthenticated probe would never pass.
      probes:
        liveness:
          enabled: false
        readiness:
          enabled: false

      # LIMITS match what runs today exactly: 2 CPU / 8Gi (from the live
      # tfa-app override, not the stale 1 CPU / 2Gi chart default).
      #
      # REQUESTS move from 100m/4Gi to 1 CPU/4Gi. Memory is unchanged;
      # the CPU reservation rises because every preset reserves half its
      # limit. Today's 100m against a 2 CPU limit is a 20:1 burst ratio --
      # the pod is scheduled as if it needs a tenth of a core and may
      # consume twenty. Raising the request costs reserved capacity and
      # buys predictable scheduling.
      resources:
        resourcePreset: xlarge

What each part means

Says what the product is made of.

# The TFA product: the components that are published and deployed together, under one product version.
# Settings for each component:
# - for every group:            configurations/<component>.yaml (this repo)
# - for one group (helm only):  cloud-config landscapes/<landscape>/environments.yaml, under products.tfa
# - for one environment:        cloud-config landscapes/<landscape>/<environment>/tfa/<component>.yaml
apiVersion: v1
kind: Product
name: tfa
components:
  helm:
    chart: tfa-app                       # published as helm/products/tfa-app
    serviceCharts:                       # each chart's services come from the service repo's deploy/service-chart.yaml
      tax-fixed-assets: {}
      active-reports-service: {}
      tfa-frontend: {}
      content-deploy: {}
      tfa-zerobus: {}                    # TFA IQ data sync; off unless an environment turns it on
  adf:
    artifact: powerplan/tfa-adf-artifact          # the ARM template package
  databricks:                                     # TFA IQ bundles, deployed in this order
    spotlight-db:                                 # schemas, silver/gold pipeline, Batch Completion job
      artifact: databricks/powerplan-spotlight-db
    spotlight-api:                                # Databricks App + Genie space; uses spotlight-db's job
      artifact: databricks/powerplan-spotlight-api
# When an environment is deployed, each component is installed at the version this product version lists.

What each part means

Product-wide settings for the application, the same in every landscape. They are sealed into the product chart.

# Settings for the helm component (the tfa-app chart), the same in every group (landscape).
# - generate-product-chart puts this file into the chart as its default values.
# - cloud-config can override them. Order (the last one wins): this file, then
#   landscapes/<landscape>/environments.yaml (products.tfa), then <environment>/tfa/helm.yaml.
# - Layout:
#     global:            settings for the whole product, including the list of secrets
#     <service chart>:   one key per service chart, then <service>.<archetype> (app or task)

global:
  # Settings for the whole product: host name prefixes, the Ingress timeout, a few fixed values and the secrets.
  # Settings of one service are not here: the service declares them in its deploy/service-chart.yaml
  # (appSettings, env), and TFA's values for them are further down, under the service chart's key.
  prefixes:
    client: ''
    it: it-
    ars: ars-
    idp: idp-
    um: umgr-
    core: core-
    compodoc: compodoc-
  # The platform chart sets the Ingress annotations: Application Gateway when app_gateway is on, otherwise nginx.
  # This includes the class, ssl-redirect and the request timeout below. A group can override the timeout.
  ingress_timeout_seconds: 900
  ingress_extra_annotations:
    nginx:
      nginx.org/client-max-body-size: 4m
      nginx.ingress.kubernetes.io/proxy-buffer-size: 16k
      nginx.ingress.kubernetes.io/proxy-body-size: 8m
  tls_secret_name: tls-cluster-secret
  okta_audience: api://default
  okta_enabled: true
  sentry_min_event_level: Error
  sentry_min_diagnostics_level: Error
  # The product's secrets: names of Key Vault secrets in the environment's vault (kv-<environment>), as tfa-<name>.
  # - Names only, never values.
  # - A service uses them with `secrets` in its service-chart.yaml.
  # - If a service uses a name that is not in this list, the render fails.
  secrets:
    tfa-adf-client-secret: {}
    tfa-appconfig-connection: {}
    tfa-client-sentry-dsn: {}
    tfa-content-storage-connection: {}
    tfa-database-connection: {}
    tfa-flatfile-api-key: {}
    tfa-flatfile-secret-key: {}
    tfa-genie-databricks-client-secret: {}
    tfa-identity-connection: {}
    tfa-migrations-database-connection: {}
    tfa-migrations-identity-connection: {}
    tfa-reports-appstream-secret: {}
    tfa-reports-database-connection: {}
    tfa-reports-storage-connection: {}
    tfa-sentry-dsn: {}
    tfa-storage-connection: {}
    tfa-syncfusion-license: {}
    tfa-tenantmapping-appconfig-connection: {}
    tfa-usermanagement-auth-header: {}
    tfa-zendesk-api-token: {}
    tfa-zerobus-client-id: {}
    tfa-zerobus-client-secret: {}
    tfa-zerobus-keda-sql-username: {}
    tfa-zerobus-keda-sql-password: {}

# … one key per service chart, for example:

active-reports-service:

  active-reports-service:
    app:
      ingress:
        prefix: ars
      appSettings:
        Identity:
          UseIdentityProvider: "false"   # TFA uses Okta (global okta_enabled: true)
      podSecurityContext:
        runAsNonRoot: false      # TEMPORARY, see the note above

Abridged: the global block in full, then one of the five service charts.

What each part means

Product-wide parameters for the ADF component. Empty today.

# Settings (ARM parameters) for the adf component, the same in every group (landscape).
# - Flat keys. Values are plain text or Key Vault secret names, never secret values.
# - An environment can override them in cloud-config: landscapes/<landscape>/<environment>/tfa/adf.yaml
#   (adf has no settings per group).
{}

What each part means

The delivery ladder: which landscapes, in which order, with which environments. The product team owns it.

# Where TFA is deployed, and in which order. The TFA product team owns this file.
# - The first group (dev) gets every new version automatically. A new version is built when this repo
#   changes, or when a service publishes a new version (checked every 30 minutes).
# - The next groups (for example qa and prod) only get a version after it passed in dev, and only when
#   someone starts "CD · Promote" by hand.
# - Each name must match a folder in the cloud-config repo: landscapes/<group>/<environment>/
# - Settings per environment:
#     {}               use the normal settings (most environments)
#     {mode: render}   only check the files, do not install
#     {strict: false}  allow placeholder values in the settings
# Planned for future:
# - Run QA tests after a deployment, input configurations would need to be specified for the tests.
# - Send Teams notifications when a deployment succeeds or fails. This file will hold the team name, users to tag etc etc.

environments:
  dev:
    app01: {}
    # test01: {}

What each part means

CD · Development: makes, deploys and approves a new version. One of five thin CD workflows; it hands the work to a shared template.

name: CD · Development

# Builds a new version of TFA and deploys it to the first group in pipeline.config.yaml (dev: app01).
# Steps (cloud-cicd-templates cd-candidate):
# 1. Check what changed: a new service build, product.yaml or configurations/.
# 2. If something changed, build a new product version (a "candidate").
# 3. Deploy it to every environment of the first group. Flux installs it; the run waits until it is done.
# 4. If every deploy is green, approve the version automatically (no reviewer). This publishes the
#    <version>-approved chart, tags and package, and a GitHub pre-release.
# - To turn off automatic approval: set `approve: false` on the candidate job.
# - Next step: "CD · Release" gives an approved version a release number.
# When it runs:
#   push to main             full run: deploy, and approve if green
#   pull request             test run: build, check and render only; nothing is published or deployed
#   cd-detect.yml or hand    full run; `reason` and `version` only say why it started
#                            (the run checks again and picks its own version number)
# Secrets: DOCKER_USER, DOCKER_PASS, ORCHESTRATOR_TOKEN, CLOUD_CONFIG_TOKEN.
# GitHub Environment: tfa-dev (the identity that deploys to dev).

run-name: >-
  ${{ format('Development tfa{0} ({1})', inputs.version && format(' {0}', inputs.version) || '',
  inputs.reason || github.event_name) }}

on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:
    branches: [main]
    paths-ignore: ['**.md']
  workflow_dispatch:
    inputs:
      reason:
        description: Why this run (cd-detect.yml fills in what moved).
        type: string
        required: false
        default: ''
      version:
        description: The version cd-detect.yml saw (a hint for the run name; the run composes its own).
        type: string
        required: false
        default: ''
      strict:
        description: Reject dummy values in the landscape, unless an environment in pipeline.config.yaml says otherwise.
        type: boolean
        default: false

# Full runs: one at a time, the others wait.
# Pull request test runs: one per pull request; a new push cancels the old run.
concurrency:
  group: cd-development-${{ github.event_name == 'pull_request' && github.ref || 'main' }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  candidate:
    uses: PowerPlanDev/cloud-cicd-templates/.github/workflows/cd-candidate.yaml@main
    permissions:
      contents: write   # create the GitHub Release of the approved version
      packages: write   # publish product versions and -approved tags
    with:
      pipeline-file: pipeline.config.yaml   # remove when cloud-cicd-templates uses this name by default
      deploy: ${{ github.event_name != 'pull_request' }}
      dry-run: ${{ github.event_name == 'pull_request' }}
      strict: ${{ inputs.strict == true }}
    secrets: inherit

What each part means

CD · Promote: moves a later landscape to an approved version, behind that landscape's reviewers.

name: CD · Promote

# Started by hand. Moves a later group (landscape) in pipeline.config.yaml, qa or prod, to an approved version.
# Steps (cloud-cicd-templates cd-promote):
# 1. A reviewer approves in the GitHub Environment tfa-<landscape>-release.
# 2. One cloud-config commit sets <version>-approved for every environment of the group.
# 3. cloud-config's Environments workflow applies it.
# 4. One check job per environment confirms the deploy (runs as tfa-<landscape>).
# - `version` empty: the latest approved version.
# - Placeholder values are not allowed, unless the environment sets `strict: false` in pipeline.config.yaml.
# - For now qa is promoted here. Later "CD · Release" will deploy releases to qa, and this workflow will
#   be used for prod only, with release numbers. (This needs release-number support in orchestrator-component-release.)
# Secrets: DOCKER_USER, DOCKER_PASS, ORCHESTRATOR_TOKEN, CLOUD_CONFIG_TOKEN,
#   CD_APP_ID and CD_APP_PRIVATE_KEY (the GitHub App that writes to cloud-config).
# GitHub Environments: tfa-<landscape>-release (reviewers), tfa-<landscape> (the identity that deploys).

run-name: Promote tfa ${{ inputs.version || 'latest approved' }} → ${{ inputs.landscape }} by @${{ github.actor }}

on:
  workflow_dispatch:
    inputs:
      landscape:
        description: The landscape of pipeline.config.yaml to promote to.
        type: choice
        required: true
        options: [qa, prod]
      version:
        description: The approved version, e.g. 202610.19.183801 (or -approved). Empty = the latest approved release.
        type: string
        required: false
        default: ''

# One promotion per group at a time; the others wait.
concurrency:
  group: cd-promote-${{ inputs.landscape }}
  cancel-in-progress: false

permissions:
  contents: read

jobs:
  promote:
    uses: PowerPlanDev/cloud-cicd-templates/.github/workflows/cd-promote.yaml@main
    permissions:
      contents: read
      packages: read
    with:
      pipeline-file: pipeline.config.yaml   # remove when cloud-cicd-templates uses this name by default
      landscape: ${{ inputs.landscape }}
      version: ${{ inputs.version }}
    secrets: inherit

What each part means

What generate-service makes from service-chart.yaml: a chart that depends on the platform chart once per service.

apiVersion: v2
name: active-reports-service
description: 'GENERATED by `release-component generate-service` from deploy/service-chart.yaml.
  Do not edit: the next build overwrites it.'
type: application
version: 202601.1.1
appVersion: 202601.1.1
dependencies:
- name: platform-services
  alias: active-reports-service
  version: '*'
  repository: file://../../../../..
  condition: active-reports-service.app.enabled
annotations:
  powerplan.com/source-commit: '0000000000000000000000000000000000000000'

This copy is a golden-test input: it uses a placeholder version and a local path. A real build uses the CalVer and oci://ppdevops.azurecr.io/helm/platform.

What each part means

What generate-product-chart makes: an umbrella chart with no templates, just the service charts.

apiVersion: v2
name: tfa-app
description: GENERATED by `release-component generate-product-chart` from product.yaml
  and configurations/. Do not edit.
type: application
version: 202601.1.1
appVersion: 202601.1.1
dependencies:
- name: tax-fixed-assets
  version: '*'
  repository: file://../service-charts/tax-fixed-assets
- name: active-reports-service
  version: '*'
  repository: file://../service-charts/active-reports-service
- name: tfa-frontend
  version: '*'
  repository: file://../service-charts/tfa-frontend
- name: content-deploy
  version: '*'
  repository: file://../service-charts/content-deploy
annotations:
  powerplan.com/source-commit: '0000000000000000000000000000000000000000'

A golden-test input: placeholder version, local paths and '*' ranges instead of exact pins.

What each part means

The record of exactly what one product version contains. Every deploy reads it first.

# EXAMPLE of a composition: what one product version is made of. It lives only in GitHub Packages:
#   compose   pushes  oci://ghcr.io/powerplandev/tfa-composition:<version>-candidate
#   approval  pushes  oci://ghcr.io/powerplandev/tfa-composition:<version>-approved (approval filled in) and writes that
#             address and digest into the GitHub Release notes -- the release points at the composition, no copy
# The package is linked to product-deploy-tfa (pushed from it, annotation org.opencontainers.image.source) and inherits
# its access; cloud-config is granted read on it.
# Every deploy run (production included) pulls the composition first and deploys exactly the components, versions and
# digests it names. Detect follows the latest approved release to its composition and compares with the newest builds.
apiVersion: v1
kind: Composition
product: tfa
version: 202610.18.1
state: candidate                          # candidate when composed; approved after the deploy ladder (approve job)
source:
  repository: PowerPlanDev/product-deploy-tfa
  commit: 0123456789abcdef0123456789abcdef01234567
composedAt: 2026-10-18T09:30:00Z
components:
  helm:
    chart: helm/products/tfa-app
    version: 202610.18.1-candidate        # the chart's own version carries the state (Flux: tag must equal it)
    digest: sha256:...
    serviceCharts:                        # what the product chart pins
      tax-fixed-assets: 202610.17.3
      active-reports-service: 202610.15.2
      tfa-frontend: 202610.18.1
      content-deploy: 202610.12.4
  adf:
    artifact: powerplan/tfa-adf-artifact
    version: 202610.18.1-candidate
    digest: sha256:...
    built: 202610.16.2                    # the ADF build this product version carries
  databricks:
    artifact: databricks/tfa
    version: 202610.18.1-candidate
    digest: sha256:...
    built: 202610.18.1
approval: {}                              # filled by approve: approvedAt, approvedBy, run

The format example from the design. Real compositions are published to ghcr.io/powerplandev/tfa-composition.

What each part means

Landscape defaults: true for every environment in dev.

# Landscape defaults: apply to every environment in this landscape.
# No secrets, no tokens. Secrets live in the environment's Key Vault, named by the `secrets` pool in
# product-deploy-tfa/configurations/global.yaml.
landscape: dev
tier: dev
registry: ppdevops.azurecr.io
# What deploy-environment installs here (charts in `registry`). environmentChart.version is exact or a range,
# resolved to the newest match at deploy time; narrow it (or pin) in the landscapes after this one.
platform:
  environmentChart:
    name: platform-environment
    repository: helm/platform
    version: ">=0.1.0, <1.0.0"
  productCharts:
    tfa:
      chart: tfa-app
      repository: helm/products
  # Flux delivery pulls the product chart with the same secret the images use (the cluster is not attached to ACR).
  chartPullSecret: acr-pull-secret
products:
  tfa:
    domain_name: dev.az.powerplancloud.com
    app_gateway: true
    frontdoor_enabled: false
    okta_domain: https://powerplan-dev.oktapreview.com/
    platform_user_management_api_rest_url: https://umgrnew-uat.dev.az.powerplancloud.com/
    platform_user_management_api_grpc_enabled: false
    platform_user_management_api_grpc_url: https://dummy.invalid
    azure_ad_tenant_id: 00000000-0000-0000-0000-000000000000
    azure_ad_client_id: 00000000-0000-0000-0000-000000000000
    db_server: <redacted>
    db_username: dummy-db-user
    sql_command_timeout: 90
    long_running_sql_command_timeout: 3600
    graphql_query_timeout: 300
    genie_databricks_base_url: https://dummy.invalid
    genie_databricks_client_id: 00000000-0000-0000-0000-000000000000
    genie_databricks_workspace_host: dummy.invalid
    feature_flag_cache_seconds: 1800
    # Every service pulls with the docker-registry secret `acr-pull-secret`, created by hand in the namespace
    # (the cluster is not attached to the registry yet). Other landscapes attach the registry and need none.
    services:
      tax-fixed-assets:
        tax-fixed-assets-api:
          app:
            imagePullSecrets:
            - name: acr-pull-secret
            resources:
              resourcePreset: micro
            replicaCount: 1
            appSettings:
              Azure:
                TenantId: <redacted>
                SubscriptionId: <redacted>
              DisableInServiceMigrations: true
        tfa-migrations:
          task:
            imagePullSecrets:
            - name: acr-pull-secret
            resources:
              resourcePreset: small
        redis:
          app:
            imagePullSecrets:
            - name: acr-pull-secret
      tfa-frontend:
        tfa-client:
          app:
            imagePullSecrets:
            - name: acr-pull-secret
            resources:
              resourcePreset: nano
            env:
              USER_MANAGEMENT_API_URL: https://umgrnew-uat.dev.az.powerplancloud.com/api
              PORTAL_URL: https://dummy.invalid
              OKTA_ISSUER: https://powerplan-dev.oktapreview.com/oauth2/default
              ZENDESK_WIDGET_KEY: dummy-zendesk-widget
              FLATFILE_ENVIRONMENT_ID: dummy-flatfile-env
              FLATFILE_PUBLISHABLE_KEY: dummy-flatfile-pub
        compodoc:
          app:
            imagePullSecrets:
            - name: acr-pull-secret
            enabled: true
        flatfile-listeners:
          task:
            imagePullSecrets:
            - name: acr-pull-secret
            enabled: true
      active-reports-service:
        active-reports-service:
          app:
            imagePullSecrets:
            - name: acr-pull-secret
            resources:
              resourcePreset: micro
      content-deploy:
        content-deploy:
          task:
            imagePullSecrets:
            - name: acr-pull-secret
            resources:
              resourcePreset: micro

IDs and server names are redacted. The header comment still names global.yaml; the pool is now in configurations/helm.yaml.

What each part means

Where the landscape's clusters are. Environments refer to a stack, never to a cluster name.

# The subscription and clusters of the dev landscape: what `az aks get-credentials` and `helm upgrade` need.
# One subscription per landscape. An environment names a stack in its environment.yaml; orchestrator-component-release checks the
# stack is listed here and deploys to that stack's cluster in `activeRegion`. Never put a cluster name in an
# environment file. Names follow the naming standard (aks-<landscape>, rg-<landscape>-platform).
# Tenant and subscription ids are dummy (all zeros) until the real ones are known.
tenant: "powerplan"
tenantId: <redacted>
subscription: dev
subscriptionId: <redacted>
managementGroup: mg-development
activeRegion: primary
stacks:
  dev-v1:
    primary:
      name: pp-aks-cloud-eastus-main3
      resourceGroup: pp-rg-cloud-eastus-aks3
      tier: free
      kubelogin: azurecli
      gateway: {name: dev-lower-gateway, namespace: env-system}

Tenant and subscription IDs are redacted.

What each part means

The environment itself. Also the main input of the environment chart.

# Environment manifest: identity, the product pins and environment-wide overrides.
# Also the platform-environment chart's values (namespaces, Key Vault SecretStores, and with delivery: flux the
# OCIRepository + HelmRelease per product), with a second file deploy-environment derives from environments.yaml.
# Move to environments namespace once ready
environment: app01
landscape: dev
stack: dev-v1
delivery: flux
# The environment's managed identity (target name id-app01-dev; testing uses id-app01-tfa-dev): every product
# namespace's ServiceAccount shared-pp-workload. One federated credential per product namespace and cluster, Key Vault
# Secrets User on the vault below. A product may override it with products.<product>.workloadIdentityClientId.
workloadIdentityClientId: <redacted>
products:
  tfa:
    enabled: true
    track: candidate
# The environment's Key Vault (name defaults to kv-<environment>-<landscape>). WorkloadIdentity: each
# product's SecretStore reads it as the environment's identity. No secret values here.
keyVault:
  name: kv-app01-prod          # override for now: the vault that exists; remove once kv-app01-dev is created
  authType: WorkloadIdentity
  tenantId: <redacted>

Client and tenant IDs are redacted.

What each part means

This environment's settings for the product chart. Optional; becomes the 20-overrides layer.

# Values for the TFA product chart, this environment only. The inputs are the same set in every landscape.
# Everything else derives from the environment name or comes from the landscape and product tiers.
okta_client_id: <redacted>
storage_account: <redacted>
okta_integration_app_client_id: dummy-okta-integration
services:
  tax-fixed-assets:
    tax-fixed-assets-api:
      app:
        appSettings:
          Azure:
            ClientId: <redacted>
            AppInfo:
              TFAResourceGroup: pp-rg-cloud-tfadevops-tfa
              TFAFactoryName: pp-adf-cloud-tfadevops-tfa
    tfa-migrations:
      task:
        appSettings:
          UserTokens:
            TfaIqEnabled: false
            ZerobusServicePrincipal: dummy-zerobus
  tfa-frontend:
    tfa-client:
      app:
        env:
          GAINSIGHT_TAG_KEY: dummy-gainsight
          OKTA_CLIENT_ID: <redacted>
          ENVIRONMENT_TAG: app01
    flatfile-listeners:
      task:
        enabled: false    # on for the dev landscape; not run in app01

IDs and the storage account name are redacted.

What each part means

This environment's ADF parameters. Empty today.

# ARM override parameters for the TFA data factory, this environment only.
# Flat keys; literals or AKV secret names, never secret values. Empty when the environment has none.
{}

What each part means