|
| 1 | +# Blueprint Templates |
| 2 | + |
| 3 | +This directory holds curated bundles of Facets blueprint resources. Each |
| 4 | +subdirectory is one template. Raptor's `get bp-templates` command |
| 5 | +fetches templates from this repo over HTTPS at runtime — consumers do |
| 6 | +**not** need to clone the repo manually. |
| 7 | + |
| 8 | +## Layout |
| 9 | + |
| 10 | +``` |
| 11 | +templates/ |
| 12 | +├── README.md (this file) |
| 13 | +└── <template-name>/ |
| 14 | + ├── template.yaml (metadata; required) |
| 15 | + └── *.json (resource JSONs; one per file) |
| 16 | +``` |
| 17 | + |
| 18 | +## Architecture |
| 19 | + |
| 20 | +Templates are split into two tiers: |
| 21 | + |
| 22 | +**Foundational templates** ship a single low-level platform resource |
| 23 | +that other templates depend on. Apply these first to any project that |
| 24 | +doesn't already have the equivalent resource. |
| 25 | + |
| 26 | +| Template | Provides | Cloud | |
| 27 | +|---|---|---| |
| 28 | +| `compute` | `karpenter/karpenter` (updates if present) and `kubernetes_node_pool/nodepool` | AWS-only (uses `karpenter/default/1.0` and `kubernetes_node_pool/karpenter/1.0`) | |
| 29 | +| `cert-manager` | `cert_manager/cert-manager` for TLS issuance | cloud-agnostic | |
| 30 | +| `gateway-api-crd` | `gateway_api_crd/gateway-api-crd` for Gateway API CRDs | cloud-agnostic | |
| 31 | + |
| 32 | +**Leaf templates** ship a complete stack that consumes foundational |
| 33 | +resources via their `requires:` declarations. |
| 34 | + |
| 35 | +| Template | Consumes | Cloud | |
| 36 | +|---|---|---| |
| 37 | +| `observability` | `cluster`, `nodepool` — ships prometheus + alert-rules + grafana-dashboards | cloud-agnostic | |
| 38 | +| `ingress` | `cluster`, `nodepool`, `cert-manager`, `gateway-api-crd` — ships the NGINX Gateway Fabric ingress on AWS (`nginx_gateway_fabric_aws/1.0`) | AWS-only | |
| 39 | + |
| 40 | +GCP / Azure / OVH variants of `compute` and `ingress` will land as |
| 41 | +separate templates (e.g. `compute-gcp`, `ingress-azure`) following the |
| 42 | +same pattern. |
| 43 | + |
| 44 | +Most leaves contain an internal dependency chain too (e.g. observability's |
| 45 | +`alert-rules` and `grafana-dashboards` reference its `prometheus`). |
| 46 | +Raptor's per-file `apply` validator only sees resources that already |
| 47 | +exist in the target project — co-applied siblings in the same |
| 48 | +`apply -f <dir>` batch are invisible to it. The two-stage apply pattern |
| 49 | +below works around this honestly. |
| 50 | + |
| 51 | +## Apply order |
| 52 | + |
| 53 | +The end-to-end workflow that has been tested against a fresh project |
| 54 | +(`redesign-aws` project type, no extra customization). Other project |
| 55 | +types may name resources differently — see "Adapting to a different |
| 56 | +bootstrap" below. |
| 57 | + |
| 58 | +```bash |
| 59 | +# 0. Project bootstrap provides: cluster, cloud, network (+ karpenter) |
| 60 | + |
| 61 | +# 1. Apply compute — creates kubernetes_node_pool/nodepool, updates karpenter. |
| 62 | +# If your project's bootstrap doesn't already include karpenter, apply |
| 63 | +# karpenter.json first (release), then nodepool.json — kubernetes-node-pool |
| 64 | +# references karpenter and the validator can't see co-applied siblings. |
| 65 | +raptor get bp-templates compute --save-to ./compute/ |
| 66 | +raptor apply -f ./compute/ -p PROJECT |
| 67 | + |
| 68 | +# 2. Apply foundational add-ons (each independent of the others) |
| 69 | +raptor get bp-templates cert-manager --save-to ./cm/ |
| 70 | +raptor apply -f ./cm/ -p PROJECT |
| 71 | +raptor get bp-templates gateway-api-crd --save-to ./gac/ |
| 72 | +raptor apply -f ./gac/ -p PROJECT |
| 73 | + |
| 74 | +# 3. Apply observability in two stages (alert-rules + grafana depend on |
| 75 | +# prometheus, which is in the same template) |
| 76 | +raptor get bp-templates observability --save-to ./obs/ |
| 77 | +raptor apply -f ./obs/prometheus.json -p PROJECT |
| 78 | +raptor apply -f ./obs/alert-rules.json -f ./obs/grafana-dashboards.json -p PROJECT |
| 79 | + |
| 80 | +# 4. Apply ingress (consumes cert-manager and gateway-api-crd) |
| 81 | +raptor get bp-templates ingress --save-to ./ing/ |
| 82 | +raptor apply -f ./ing/ -p PROJECT |
| 83 | +``` |
| 84 | + |
| 85 | +Resources ship `disabled: true`. After applying, enable them and trigger |
| 86 | +a release. |
| 87 | + |
| 88 | +### Adapting to a different bootstrap |
| 89 | + |
| 90 | +These templates assume conventional resource names: `cluster` (for |
| 91 | +`kubernetes_cluster`), `nodepool`, `cloud`, `network`, `cert-manager`, |
| 92 | +`gateway-api-crd`, `prometheus`. If your project's bootstrap uses |
| 93 | +different names, edit the downloaded JSONs' `inputs.<key>.resource_name` |
| 94 | +values before applying — `raptor get bp-templates <name>` writes them to |
| 95 | +disk first, so the consumer (or AI agent) can rewrite refs in place. |
| 96 | + |
| 97 | +## template.yaml |
| 98 | + |
| 99 | +```yaml |
| 100 | +name: <template-name> # required, must match dir name |
| 101 | +displayName: <human name> # required |
| 102 | +description: <one paragraph> # required |
| 103 | +category: <observability|network|compute|security|...> # required |
| 104 | +version: "1.0" # required; bump on backwards-incompatible changes |
| 105 | + # (resource removed, requires: tightened, etc.) |
| 106 | +tags: [list, of, tags] # optional |
| 107 | +maintainers: # optional |
| 108 | + - name: <name> |
| 109 | +resources: # optional; if omitted, *.json sorted alphabetically |
| 110 | + - cert-manager.json |
| 111 | + - prometheus.json |
| 112 | +requires: # optional but encouraged; documents externals |
| 113 | + - kubernetes_cluster/cluster |
| 114 | + - kubernetes_node_pool/nodepool |
| 115 | +source: # optional; provenance for --details / -o yaml |
| 116 | + gitUrl: https://github.com/Facets-cloud/facets-modules-redesign.git |
| 117 | + gitRef: main |
| 118 | + path: templates/<template-name> |
| 119 | +``` |
| 120 | +
|
| 121 | +## Resource JSONs |
| 122 | +
|
| 123 | +Each `*.json` is a Facets resource definition with the shape: |
| 124 | + |
| 125 | +```json |
| 126 | +{ |
| 127 | + "kind": "<intent>", |
| 128 | + "flavor": "<flavor>", |
| 129 | + "version": "<schema-version>", |
| 130 | + "metadata": {"name": "<resource-name>"}, |
| 131 | + "disabled": true, |
| 132 | + "spec": { ... }, |
| 133 | + "inputs": { ... } |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +Conventions: |
| 138 | +- Ship with `disabled: true` so the consumer reviews before triggering a release. |
| 139 | +- `metadata.name` matches the filename stem (`prometheus.json` → |
| 140 | + `metadata.name: "prometheus"`). Raptor's loader enforces this. |
| 141 | +- `inputs` references use conventional default names (`cluster`, |
| 142 | + `cloud`, `network`, `nodepool`, `cert-manager`, `gateway-api-crd`) so |
| 143 | + externals line up with what foundational templates provide and with |
| 144 | + what `requires:` lists. |
| 145 | +- For inputs that consume a Kubernetes cluster, set `output_name` |
| 146 | + explicitly. The right value depends on what the consuming module's |
| 147 | + `kubernetes_details` (or equivalent) input declares as its `type:`: |
| 148 | + - `@facets/kubernetes-details` (cloud-agnostic) → `output_name: "attributes"` |
| 149 | + — used by cert-manager, prometheus, grafana-dashboards, gateway-api-crd. |
| 150 | + - `@facets/eks` (or `@facets/gke` / `@facets/azure_aks`, cloud-specific) → |
| 151 | + `output_name: "default"` (or omitted) — used by karpenter, |
| 152 | + kubernetes_node_pool, **and the AWS ingress flavor** |
| 153 | + (`nginx_gateway_fabric_aws`). Always check the producing module's |
| 154 | + `facets.yaml` to be sure. |
| 155 | +- Input KEY names are dictated by the consuming module's `facets.yaml` |
| 156 | + and aren't always uniform — e.g. most modules call the Kubernetes |
| 157 | + cluster input `kubernetes_details`, but `alert_rules/prometheus` |
| 158 | + calls it `kubernetes_cluster`. Mirror what the module declares |
| 159 | + rather than guessing. |
| 160 | + |
| 161 | +## Verifying resources |
| 162 | + |
| 163 | +Before authoring a resource JSON, inspect the producing module's |
| 164 | +`facets.yaml` in `modules/<intent>/<flavor>/<version>/facets.yaml` — the |
| 165 | +`inputs:` block declares each input's `type:` (e.g. `@facets/eks` vs |
| 166 | +`@facets/kubernetes-details`), and the `outputs:` block of the producer |
| 167 | +declares which output emits which type. |
| 168 | + |
| 169 | +For an extra check against a real control plane, fetch a known-working |
| 170 | +resource: |
| 171 | + |
| 172 | +```bash |
| 173 | +FACETS_PROFILE=<profile> raptor get resource <kind>/<name> -p <project> -o json |
| 174 | +``` |
| 175 | + |
| 176 | +…and mirror its `inputs` shape (resource_type / resource_name / |
| 177 | +output_name). |
| 178 | + |
| 179 | +## Consuming templates |
| 180 | + |
| 181 | +```bash |
| 182 | +# List |
| 183 | +raptor get bp-templates |
| 184 | +raptor get bp-templates -o wide # adds REQUIRES column |
| 185 | +raptor get bp-templates --category observability # filter |
| 186 | +
|
| 187 | +# Inspect metadata without saving |
| 188 | +raptor get bp-templates observability --details |
| 189 | +raptor get bp-templates observability --details -o yaml # full metadata incl. source |
| 190 | +
|
| 191 | +# Download to disk (default ./bp-templates/<name>/) |
| 192 | +raptor get bp-templates observability |
| 193 | +raptor get bp-templates observability --save-to ./obs/ |
| 194 | +raptor get bp-templates observability --include-metadata # also write template.yaml |
| 195 | +
|
| 196 | +# Print to stdout instead of saving (pipe-friendly) |
| 197 | +raptor get bp-templates observability -o json |
| 198 | +``` |
| 199 | + |
| 200 | +Override the upstream fetch with a local checkout (useful when |
| 201 | +iterating on templates locally before opening a PR): |
| 202 | + |
| 203 | +```bash |
| 204 | +# Flag form |
| 205 | +raptor get bp-templates --templates-dir /path/to/facets-modules-redesign/templates |
| 206 | +
|
| 207 | +# Env form (composable with scripts) |
| 208 | +export FACETS_TEMPLATES_DIR=/path/to/facets-modules-redesign/templates |
| 209 | +raptor get bp-templates |
| 210 | +``` |
| 211 | + |
| 212 | +GitHub's unauthenticated rate limit is 60/hr per IP. Set |
| 213 | +`GITHUB_TOKEN` or `GH_TOKEN` to lift it to 5000/hr if needed. |
| 214 | + |
| 215 | +## After fetching |
| 216 | + |
| 217 | +`raptor get bp-templates` is fetch-only — it does not apply. See |
| 218 | +`raptor apply --help` for the applying half. Resources ship |
| 219 | +`disabled: true`, so review them and enable selectively (or via a |
| 220 | +per-environment override) before triggering a release. |
0 commit comments