Merge pull request #262 from CodeForPhilly/docs/example-app

docs(guides): use a made-up example-app as the running example

Author: themightychris

_docs/guides/README.md

@@ -14,6 +14,6 @@ Read in order the first time; each page is short.
     - [Data and backups](database/data-and-backups.md): getting a `psql` shell, loading existing data, and what the backups do and don't give you.
 4. **[Reference](reference.md)**: the directory map and the gotchas, for when you already know the shape.
 
-The running example is **paws-data-pipeline**, which is moving from a Postgres container inside its own pod to the shared cluster. Substitute your app's name.
+The running example is a made-up **example-app** that is moving from a Postgres container inside its own pod to the shared cluster. Substitute your app's name wherever you see it.
 
 If you get stuck, ask in `#civic-cloud` on the Code for Philly Slack.

_docs/guides/database/README.md

@@ -15,4 +15,4 @@ Both clusters run one PostgreSQL cluster for everyone, `shared-cluster` in the `
 2. **[Connect your app](connect.md)**: read host, database, user and password from configuration, for helm and for kustomize apps, and land the change in the right order.
 3. **[Data and backups](data-and-backups.md)**: get a `psql` shell, load existing data, and know what the shared backups do and don't cover.
 
-The running example is `paws-data-pipeline`, moving from a Postgres container inside its own pod to the shared cluster. Substitute your app's name.
+The running example is a made-up `example-app` with a Postgres user and database both named `example`. Substitute your app's name.

_docs/guides/database/connect.md

@@ -5,9 +5,9 @@ Once [provisioned](provision.md), your app needs five things: host, port, databa
 ```
 host      shared-cluster-rw.cloudnative-pg.svc.cluster.local   (-ro for a read replica)
 port      5432
-database  paws
-user      paws
-password  Secret paws-db-credentials, key "password"
+database  example
+user      example
+password  Secret example-db-credentials, key "password"
 ```
 
 ## Helm apps
@@ -31,17 +31,17 @@ env:
 ```
 {% endraw %}
 
-If the chart currently runs its own Postgres container (PAWS did, as a sidecar in the app pod), remove it, or keep it behind a `database.embedded: true` default so local dev is unchanged. Cut a release and bump `.holo/sources/<app>.toml` to the new tag.
+If the chart currently runs its own Postgres container (a common starting point: a sidecar in the app pod, or a subchart), remove it, or keep it behind a `database.embedded: true` default so local dev is unchanged. Cut a release and bump `.holo/sources/<app>.toml` to the new tag.
 
-Then set the values in the cluster repo, `paws-data-pipeline/release-values.yaml`:
+Then set the values in the cluster repo, `example-app/release-values.yaml`:
 
 ```yaml
 database:
   embedded: false
   host: shared-cluster-rw.cloudnative-pg.svc.cluster.local
-  name: paws
-  user: paws
-  passwordSecret: paws-db-credentials
+  name: example
+  user: example
+  passwordSecret: example-db-credentials
 ```
 
 ## Kustomize apps

_docs/guides/database/data-and-backups.md

@@ -5,13 +5,13 @@
 Your team's access covers your namespace, not `cloudnative-pg`, so the way in is a throwaway pod in your namespace with the credentials loaded:
 
 ```bash
-kubectl -n paws-data-pipeline run psql --rm -it --restart=Never --image=postgres:18 \
+kubectl -n example-app run psql --rm -it --restart=Never --image=postgres:18 \
   --overrides='{"spec":{"containers":[{"name":"psql","image":"postgres:18","stdin":true,"tty":true,
     "command":["psql"],
     "env":[{"name":"PGHOST","value":"shared-cluster-rw.cloudnative-pg.svc.cluster.local"},
-           {"name":"PGDATABASE","value":"paws"},
-           {"name":"PGUSER","valueFrom":{"secretKeyRef":{"name":"paws-db-credentials","key":"username"}}},
-           {"name":"PGPASSWORD","valueFrom":{"secretKeyRef":{"name":"paws-db-credentials","key":"password"}}}]}]}}'
+           {"name":"PGDATABASE","value":"example"},
+           {"name":"PGUSER","valueFrom":{"secretKeyRef":{"name":"example-db-credentials","key":"username"}}},
+           {"name":"PGPASSWORD","valueFrom":{"secretKeyRef":{"name":"example-db-credentials","key":"password"}}}]}]}}'
 ```
 
 The same pod with `["sleep","3600"]` as the command is a workbench for `pg_dump` and `pg_restore`; `kubectl cp` files in and out.
@@ -24,9 +24,9 @@ Dump the old database in custom format, then restore **as your own user**, so yo
 # from wherever can reach the old database
 pg_dump -Fc --no-owner --no-privileges -h OLDHOST -U OLDUSER -d OLDDB -f app.dump
 
-# from the workbench pod, connected as paws
+# from the workbench pod, connected as example
 pg_restore -l app.dump | grep -vE " (EXTENSION|COMMENT - EXTENSION) " > list
-pg_restore --no-owner --no-privileges -L list -d paws app.dump
+pg_restore --no-owner --no-privileges -L list -d example app.dump
 ```
 
 The `grep -v EXTENSION` matters: the dump wants to `CREATE EXTENSION`, your user can't, and the extension already exists from `database.yaml`. For a 50 MB database this takes seconds.

_docs/guides/database/provision.md

@@ -9,7 +9,7 @@ Your Postgres user needs a password. cnpg reads it from a Secret in `cloudnative
 Run this with `KUBECONFIG` pointing at the cluster you're adding to (sandbox first); sealed values only decrypt on the cluster that sealed them.
 
 ```bash
-APP=paws-data-pipeline; ROLE=paws
+APP=example-app; ROLE=example
 PW=$(openssl rand -base64 48 | tr -dc A-Za-z0-9 | head -c 40)
 for ns in cloudnative-pg $APP; do
   kubectl create secret generic $ROLE-db-credentials -n $ns \
@@ -22,42 +22,42 @@ done
 unset PW
 ```
 
-That writes `cloudnative-pg.secrets/paws-db-credentials.yaml` and `paws-data-pipeline.secrets/paws-db-credentials.yaml`. You never need to write the password down; once deployed, anyone with access to your namespace can read it back from the Secret.
+That writes `cloudnative-pg.secrets/example-db-credentials.yaml` and `example-app.secrets/example-db-credentials.yaml`. You never need to write the password down; once deployed, anyone with access to your namespace can read it back from the Secret.
 
-## 2. The user: `paws-data-pipeline.cnpg/role.yaml`
+## 2. The user: `example-app.cnpg/role.yaml`
 
 A `DatabaseRole` is your Postgres user. cnpg creates it on `shared-cluster` and keeps it matching this spec, password included.
 
 ```yaml
 apiVersion: postgresql.cnpg.io/v1
 kind: DatabaseRole
 metadata:
-  name: paws
+  name: example
   namespace: cloudnative-pg        # required: cnpg wants this next to the Cluster
 spec:
   cluster:
     name: shared-cluster
-  name: paws
+  name: example
   login: true
   connectionLimit: 20              # the cluster allows 100 in total; be a good neighbour
   passwordSecret:
-    name: paws-db-credentials
+    name: example-db-credentials
   databaseRoleReclaimPolicy: retain   # deleting this file does not drop the role
 ```
 
-## 3. The database: `paws-data-pipeline.cnpg/database.yaml`
+## 3. The database: `example-app.cnpg/database.yaml`
 
 ```yaml
 apiVersion: postgresql.cnpg.io/v1
 kind: Database
 metadata:
-  name: paws
+  name: example
   namespace: cloudnative-pg
 spec:
   cluster:
     name: shared-cluster
-  name: paws
-  owner: paws
+  name: example
+  owner: example
   extensions:                      # only if you need them
     - name: postgis
       ensure: present
@@ -73,11 +73,11 @@ Commit the four files, run the projection diff ([how](../how-deploys-work.md#see
 Then check it took:
 
 ```bash
-kubectl -n cloudnative-pg get databaserole paws -o jsonpath='{.status}'
-kubectl -n cloudnative-pg get database paws -o jsonpath='{.status.applied}{"\n"}'
+kubectl -n cloudnative-pg get databaserole example -o jsonpath='{.status}'
+kubectl -n cloudnative-pg get database example -o jsonpath='{.status.applied}{"\n"}'
 ```
 
-You now have an empty database named `paws`, owned by a user named `paws`, reachable from inside the cluster at `shared-cluster-rw.cloudnative-pg.svc.cluster.local`. Nothing uses it yet.
+You now have an empty database named `example`, owned by a user named `example`, reachable from inside the cluster at `shared-cluster-rw.cloudnative-pg.svc.cluster.local`. Nothing uses it yet.
 
 !!! warning "Secret before role"
     If cnpg reconciles the `DatabaseRole` before its Secret exists, it marks the role failed and does not retry on its own. Landing both in one PR is enough. If it happens anyway: `kubectl annotate cluster -n cloudnative-pg shared-cluster cnpg.io/reconciliationLoop="$(date +%s)" --overwrite`, and check `.status` again.

_docs/guides/your-project-in-the-repo.md

@@ -1,16 +1,16 @@
 # Your project in the repo
 
-A project is a small set of files in predictable places. Here they are for `paws-data-pipeline`; yours look the same with the name swapped.
+A project is a small set of files in predictable places. Here they are for a made-up `example-app`; yours look the same with the name swapped.
 
 ```
-.holo/sources/paws-data-pipeline.toml          ← where your code comes from, pinned to a tag
-.holo/branches/k8s-manifests/paws-data-pipeline/helm-chart.toml
-.holo/lenses/paws-data-pipeline.toml           ← how it's rendered (helm or kustomize)
-paws-data-pipeline/release-values.yaml         ← your helm values (or kustomization.yaml)
-paws-data-pipeline.secrets/*.yaml              ← SealedSecrets for your namespace
-paws-data-pipeline.cnpg/*.yaml                 ← your database user + database (next page)
-_gateways/paws-data-pipeline.yaml              ← your public hostname and TLS
-_admins/paws-data-pipeline.yaml                ← namespace + a deployment-admin role for your team
+.holo/sources/example-app.toml          ← where your code comes from, pinned to a tag
+.holo/branches/k8s-manifests/example-app/helm-chart.toml
+.holo/lenses/example-app.toml           ← how it's rendered (helm or kustomize)
+example-app/release-values.yaml         ← your helm values (or kustomization.yaml)
+example-app.secrets/*.yaml              ← SealedSecrets for your namespace
+example-app.cnpg/*.yaml                 ← your database user + database (next page)
+_gateways/example-app.yaml              ← your public hostname and TLS
+_admins/example-app.yaml                ← namespace + a deployment-admin role for your team
 ```
 
 ## What you own
@@ -21,15 +21,15 @@ Directories starting with `_` (`_infra/`, `_gateways/`, `_admins/`) are cluster-
 
 ## The one rule about `<app>/`
 
-`paws-data-pipeline/` is the **input to a lens**. For a helm app that means: the chart is fetched into it from your repo, `release-values.yaml` is applied, and the rendered output *replaces* the directory in the projected tree. Anything else you put in that directory is not rendered and silently disappears.
+`example-app/` is the **input to a lens**. For a helm app that means: the chart is fetched into it from your repo, `release-values.yaml` is applied, and the rendered output *replaces* the directory in the projected tree. Anything else you put in that directory is not rendered and silently disappears.
 
-That's why things that belong to your app but aren't part of the chart live in **sibling directories** with a suffix: `paws-data-pipeline.secrets/` and `paws-data-pipeline.cnpg/`. Those are raw manifests, applied as written, and routed to the right namespace by the `namespace:` they declare.
+That's why things that belong to your app but aren't part of the chart live in **sibling directories** with a suffix: `example-app.secrets/` and `example-app.cnpg/`. Those are raw manifests, applied as written, and routed to the right namespace by the `namespace:` they declare.
 
 (A kustomize app can get away with a subdirectory instead, because kustomize passes raw resources through; balancer keeps its database files in `balancer/cnpg/` and lists them in its kustomization. Either way is fine; the sibling directory works for both.)
 
 ## Pins
 
-`.holo/sources/paws-data-pipeline.toml` names a git ref in your repo. **Make it a tag.** Tracking `refs/heads/master` means a merge in your repo can change what's deployed, or break the cluster build, with no PR here to review it. Cut a release, bump the pin, open the PR: that's a deploy.
+`.holo/sources/example-app.toml` names a git ref in your repo. **Make it a tag.** Tracking `refs/heads/master` means a merge in your repo can change what's deployed, or break the cluster build, with no PR here to review it. Cut a release, bump the pin, open the PR: that's a deploy.
 
 ## Your namespace