diff --git a/clientdocs/README.md b/clientdocs/README.md index c9b7679..9401fb1 100644 --- a/clientdocs/README.md +++ b/clientdocs/README.md @@ -28,8 +28,6 @@ running a Jenkins-to-Kubernetes workflow; same instantiation rule. It is the single end-to-end flow (cluster create -> kubeconfig -> deploy) and cross-links the CI guide and self-service guide for detail. - - `glossary.md` -- with every client; the shared plain-language reference for - the terms used across the pack. Same instantiation rule. - `scripts/` (the tenant starter kit) -- WITH the handover pack: `tenancy-audit.sh`, `smoke-test.sh`, `acceptance-run.sh`, and `ci-cleanup-sweep.sh` go to every client; `clouds.yaml.template` and @@ -74,8 +72,9 @@ cloud access). Contents: `intake-form.md`, `welcome.md`, `self-service-guide.md`, -`handover-pack.md`, `ci-integration-guide.md`, `jenkins-kubernetes-guide.md`, -`glossary.md`, `acceptance-checklist.md`, +`handover-pack.md` (includes the Glossary appendix), +`ci-integration-guide.md`, `jenkins-kubernetes-guide.md`, +`acceptance-checklist.md`, `ai-assistant-guide.md`, `tenant-skill/` (SKILL.md + references/), `scripts/` (starter kit: `tenancy-audit.sh`, `smoke-test.sh`, `acceptance-run.sh`, `ci-cleanup-sweep.sh`, `clouds.yaml.template`, diff --git a/clientdocs/glossary.md b/clientdocs/glossary.md deleted file mode 100644 index f958665..0000000 --- a/clientdocs/glossary.md +++ /dev/null @@ -1,89 +0,0 @@ -# Omega Cloud -- Glossary (TEMPLATE) - -TEMPLATE NOTE (removed before delivery): fields written as {{THIS}} are filled -in by us per client. - -Plain-language definitions of the terms used across your document pack. Each -guide gives you a workflow; this is the shared reference for what the pieces -are. Terms are grouped, not alphabetized, so related ideas sit together. - -## Your tenancy - -- Domain: your private, isolated boundary on the platform. Nothing inside it is - visible to any other client, and vice versa. Your whole tenancy lives in one - domain. -- Project: a container for resources (servers, networks, volumes, clusters) - inside your domain, with its own quota. You are delivered one production - project. -- Quota: the capacity envelope for a project -- how many instances, cores, how - much memory, how many load balancers and floating IPs you may hold at once. - Requests beyond quota are refused; changing it is a request to your account - contact, not self-service. - -## Your accounts (authoritative details in the Handover Pack) - -- `{{TENANT_SHORT_NAME}}-domain-admin`: manages your team's users, projects, and - role grants inside your domain. Identity work only, not workloads. -- `{{TENANT_SHORT_NAME}}-cluster`: the only account that creates and deletes - Kubernetes clusters, using its password. It owns the cluster SSH keypair. -- `{{TENANT_SHORT_NAME}}-svc`: the automation account. All scripted and day-to-day - work authenticates as this account's application credential. -- Application credential: a scoped, revocable secret tied to the `-svc` account. - Automation uses it instead of a password; it can be revoked without touching - the account. It cannot create Kubernetes clusters. - -## Networking - -- External network (`provider-ext`): the shared network that carries traffic to - and from the outside world. You attach floating IPs from it. -- Floating IP: a routable address you allocate from the external network and - attach to a server or load balancer to make it reachable. It counts against - your quota even while unattached, so release ones you are not using. -- Network / subnet / router: your private network, the address range on it, and - the device that connects it to the external network. You create these inside - your project. -- Security group: a set of firewall rules controlling what traffic reaches your - servers. -- Load balancer: distributes traffic across several backends behind one address. - A Kubernetes LoadBalancer Service creates one automatically (see below). - -## Compute and images - -- Instance (server): a virtual machine in your project. -- Flavor: a machine size (CPU, memory, disk). You choose one when creating a - server or a cluster; list them with `openstack flavor list`. -- Image: the operating-system or Kubernetes image a server or cluster boots - from. The platform provides shared base images. -- Keypair: the SSH key used to reach servers. For clusters, the keypair is owned - by the `{{TENANT_SHORT_NAME}}-cluster` account. - -## Kubernetes - -- Cluster template: the recipe (image, flavors, network driver, options) a - Kubernetes cluster is built from. On this platform, templates must use the - calico network driver, and must not set the Public or Hidden flag. -- Kubernetes cluster: a managed set of control and worker nodes running in your - project. You create it once and deploy into it many times. -- kubeconfig: the certificate-bearing file that grants access to a cluster's - Kubernetes API. Treat it like a password. -- LoadBalancer Service: a Kubernetes Service that asks the platform for a real - load balancer and floating IP, so an app inside the cluster is reachable from - outside. Each one draws a load balancer and a floating IP from your quota. -- Ingress controller: a single LoadBalancer Service that routes to many internal - Services by hostname or path -- one load balancer instead of many. - -## Access and trust - -- API endpoint: the address your tools authenticate against (the identity - service). Your specific URL is in the Handover Pack. -- Dashboard: the web console for your tenancy. Its URL is in the Handover Pack. -- Region: the named location your resources live in; some commands take it. -- CA bundle: the certificate file that lets your tools trust the platform's TLS - certificates. Point your tools at it; never disable certificate verification. -- Catalog: the platform's own list of service endpoints. Discover endpoints from - it (`openstack catalog list`) rather than hardcoding them. -- Secrets / certificates store: where you keep application secrets and TLS - certificates for your project, referenced by your load balancers and apps. - -For anything not defined here, or a change to your tenancy, contact -{{ACCOUNT_CONTACT}}. diff --git a/clientdocs/handover-pack.md b/clientdocs/handover-pack.md index 7d3a619..d366682 100644 --- a/clientdocs/handover-pack.md +++ b/clientdocs/handover-pack.md @@ -135,3 +135,84 @@ Acknowledged for {{TENANT_SHORT_NAME}} by: ______________________ (name, role) Date: ______________ + +-------------------------------------------------------------------------------- + +## Glossary + +Plain-language definitions of the terms used across your document pack, grouped +by theme. Your own values (identifiers, accounts, endpoints) are in sections 1-3 +above; this defines what the terms mean. + +Your tenancy: + +- Domain: your private, isolated boundary on the platform. Nothing inside it is + visible to any other client, and vice versa. Your whole tenancy is one domain. +- Project: a container for resources (servers, networks, volumes, clusters) + inside your domain, with its own quota. You are delivered one production + project. +- Quota: the capacity envelope for a project -- how many instances, cores, how + much memory, how many load balancers and floating IPs you may hold at once. + Requests beyond quota are refused; changing it is a request to your account + contact, not self-service. + +Your accounts (exact rights in section 2): + +- `{{TENANT_SHORT_NAME}}-domain-admin`: manages your team's users, projects, and + role grants inside your domain. Identity work only, not workloads. +- `{{TENANT_SHORT_NAME}}-cluster`: the only account that creates and deletes + Kubernetes clusters, using its password. It owns the cluster SSH keypair. +- `{{TENANT_SHORT_NAME}}-svc`: the automation account. All scripted and + day-to-day work authenticates as this account's application credential. +- Application credential: a scoped, revocable secret tied to the `-svc` account. + Automation uses it instead of a password; it can be revoked without touching + the account. It cannot create Kubernetes clusters. + +Networking: + +- External network (`provider-ext`): the shared network that carries traffic to + and from the outside world. You attach floating IPs from it. +- Floating IP: a routable address you allocate from the external network and + attach to a server or load balancer to make it reachable. It counts against + your quota even while unattached, so release ones you are not using. +- Network / subnet / router: your private network, the address range on it, and + the device that connects it to the external network. +- Security group: a set of firewall rules controlling what traffic reaches your + servers. +- Load balancer: distributes traffic across several backends behind one address. + A Kubernetes LoadBalancer Service creates one automatically. + +Compute and images: + +- Instance (server): a virtual machine in your project. +- Flavor: a machine size (CPU, memory, disk). List them with + `openstack flavor list`. +- Image: the operating-system or Kubernetes image a server or cluster boots + from. The platform provides shared base images. +- Keypair: the SSH key used to reach servers. For clusters, the keypair is owned + by the `{{TENANT_SHORT_NAME}}-cluster` account. + +Kubernetes: + +- Cluster template: the recipe (image, flavors, network driver, options) a + cluster is built from. Templates must use the calico network driver, and must + not set the Public or Hidden flag. +- Kubernetes cluster: a managed set of control and worker nodes in your project. + You create it once and deploy into it many times. +- kubeconfig: the certificate-bearing file that grants access to a cluster's + Kubernetes API. Treat it like a password. +- LoadBalancer Service: a Kubernetes Service that asks the platform for a real + load balancer and floating IP, so an app inside the cluster is reachable from + outside. Each one draws a load balancer and a floating IP from your quota. +- Ingress controller: a single LoadBalancer Service that routes to many internal + Services by hostname or path -- one load balancer instead of many. + +Access and trust: + +- API endpoint / dashboard / region: your specific values are in section 3. +- CA bundle: the certificate file that lets your tools trust the platform's TLS + certificates. Point your tools at it; never disable certificate verification. +- Catalog: the platform's own list of service endpoints. Discover endpoints from + it (`openstack catalog list`) rather than hardcoding them. +- Secrets / certificates store: where you keep application secrets and TLS + certificates for your project, referenced by your load balancers and apps. diff --git a/clientdocs/jenkins-kubernetes-guide.md b/clientdocs/jenkins-kubernetes-guide.md index e3b4d74..cc0d963 100644 --- a/clientdocs/jenkins-kubernetes-guide.md +++ b/clientdocs/jenkins-kubernetes-guide.md @@ -546,8 +546,8 @@ `ci-cleanup-sweep.sh` (the backstop quota sweep). - Your tenant AI assistant kit: the Kubernetes, day-2 operations, and troubleshooting references, for step-by-step help in context. -- Glossary: plain-language definitions of every term used across your pack, if - a component in this guide is unfamiliar. +- The Glossary (at the end of the Handover Pack): plain-language definitions of + every term used across your pack, if a component in this guide is unfamiliar. For anything not covered here, or a change to your tenancy, contact {{ACCOUNT_CONTACT}}. diff --git a/clientdocs/self-service-guide.md b/clientdocs/self-service-guide.md index 0d8012c..b04308a 100644 --- a/clientdocs/self-service-guide.md +++ b/clientdocs/self-service-guide.md @@ -7,14 +7,11 @@ ## Your three accounts, and what each is for -| Account | Use it for | Do NOT use it for | -|---|---|---| -| `-domain-admin` | Creating/removing team users and projects, granting roles inside your domain | Running workloads, automation | -| `-cluster` | Creating and deleting Kubernetes clusters; it holds the SSH keypair for cluster nodes | General automation, team logins | -| `-svc` | Scripted/automated work via its application credential: networks, VMs, load balancers, day-2 operations | Kubernetes cluster create/delete | - -The Handover Pack (section 2) is the authoritative list of your accounts and -their exact rights; the table above is the day-to-day summary. +You have three accounts: `-domain-admin` for managing your team's users and +projects, `-cluster` for creating and deleting Kubernetes clusters (with +its password; it holds the cluster SSH keypair), and `-svc` for all other +automation via its application credential. The full table of exact rights is in +the Handover Pack, section 2. Three rules that prevent the three most common self-inflicted outages: diff --git a/clientdocs/sweep-receipt.txt b/clientdocs/sweep-receipt.txt index 65964ce..2016d22 100644 --- a/clientdocs/sweep-receipt.txt +++ b/clientdocs/sweep-receipt.txt @@ -9,27 +9,26 @@ # Repo lint fails when any pinned file drifts, until clientdocs/ has been # reviewed for staleness and this receipt is re-recorded with: # bash scripts/repo-lint.sh --record-clientdocs-sweep -0c3c922e6cdd83bdd325eae4d4a935adcd97f6b6c1ed298a1ecba410a77a85bd clientdocs/README.md +2bb24c2647c532e0079eee04d986076f4f80624303285d18be60175991cd778b clientdocs/README.md b402dda98d3fe63f9b8a6b2798b86dc0c41a8e9348cdc197f32265c1e7267289 clientdocs/acceptance-checklist.md 30c46fd7644637c0a929bfdd195c451dff8cd0df6785cccf3a304a8422b82711 clientdocs/ai-assistant-guide.md 2e394bd459aa59237c4d68afde64e6cd185c17a900dad42c40a974b02b225bc0 clientdocs/ci-integration-guide.md -2fff42f76839b73c9fd0df2e8ef21e05da02b8225a89cb80882521f9adc52887 clientdocs/glossary.md -6060d29108d742a04d5ec9d1151f4dcfacd52ef3979f057ceb60ea42fd91f06b clientdocs/handover-pack.md +e5df7e25b3c073a1169799990ba480d7d4eb81abe398f323c46a0649adac6991 clientdocs/handover-pack.md 3f08eb458bcbb36172a5ca2785a6ec72a69a4f8cd440fec53ed604f074b1b8c6 clientdocs/intake-form.md -415fa8a7e8609df3f75a7b4e32f987523dc98d50417977d86b08fa3d29b97d6f clientdocs/jenkins-kubernetes-guide.md +2b6bf741c6415aaf42197b8af44769b0cb86cb015201234f77ca1d50a3445a8a clientdocs/jenkins-kubernetes-guide.md 2acd231062e10b33864e3e350ace07a86eac831021825b739ed641f50149e3e3 clientdocs/scripts/Jenkinsfile.example 1955db5d789a2e48d9054e307fbec2678efc1fbafda18103caa389cb896701fd clientdocs/scripts/acceptance-run.sh c2a2ff7ad719cb5866b1b58f5ca2cac930ccc99b96efaf8a3f12301d645727d3 clientdocs/scripts/ci-cleanup-sweep.sh d45eb3738d7fb2742ea1a3abb5af464df8a96bfd4e6c2f56b7182b42f997b289 clientdocs/scripts/clouds.yaml.template 3dd17ab9e95d99bea0c9f36a2662e77d25ea9d691f8c60d1d314f237c7c3f655 clientdocs/scripts/smoke-test.sh 7667bb1d2ff1e315f8ecaa2b4f680d04978a79ceeeb8cc3f5e16de2b295b2205 clientdocs/scripts/tenancy-audit.sh -a5f1d96ed87e6ce9c8c4a84db57c3adf3b64ed9e3475c7710671e64e87626ec1 clientdocs/self-service-guide.md +783eb0a2c0cff3b6b7906364cc67b5b62c9bfe3ded3f54994bbb0f437464cb46 clientdocs/self-service-guide.md 3ee4cfd5e83b4179ff736dc14d1dc8fd51f6701d6c1b894033febce7aa2bb7f2 clientdocs/tenant-skill/SKILL.md c7708c35d1d5fceab763268f6a10ed214e23e9458018b115cb944b6a3168f182 clientdocs/tenant-skill/references/ci-automation.md 42c8dc4f451befdba2fb8f75e9023255ae65698f81af7b7273c0b5a1291ec555 clientdocs/tenant-skill/references/day2-operations.md 8dfbbb8c053c32c7a63ed58910366f4262fb1d0ac2935defc9c507233b1d96b0 clientdocs/tenant-skill/references/kubernetes.md b844e00610df813275779320a13ecc131525a89b052bd5c8ab522d7666eb4fad clientdocs/tenant-skill/references/troubleshooting.md -4af7bb2afd175863f89cc17dd9ebbdea337965d82d5c518270bbc5d100fa7dac clientdocs/welcome.md +3e13aaf7987c952c0970ce1126d7de93514165bf027b46a01925a34a2963f2e1 clientdocs/welcome.md e00900e6d08d19c195edee6cab5d8198295a35371cd6333a50ca5ad28940b129 docs/tenant-onboarding-contract.md 64f99b638a1855b02180e907c9535db8bddc5847a502759a9e0d63c513b63077 policies/domain-manager-policy.yaml 02fe1fd7fcf07bfc6088622d4aa8430da53e435d60006d0b81f6b9c2e720a011 policies/overrides.zip diff --git a/clientdocs/welcome.md b/clientdocs/welcome.md index a296d1b..3799450 100644 --- a/clientdocs/welcome.md +++ b/clientdocs/welcome.md @@ -57,10 +57,10 @@ 6. The Acceptance Checklist -- run it once at onboarding to prove your environment works. -The pack also includes a Glossary (plain-language definitions of every -term used across the guides), a `scripts/` starter kit (referenced -throughout the guides), and, if your team uses an AI assistant, an AI -assistant guide with its skill package. +The Handover Pack ends with a Glossary (plain-language definitions of +every term used across the guides). The pack also includes a `scripts/` +starter kit (referenced throughout the guides) and, if your team uses an +AI assistant, an AI assistant guide with its skill package. ## Going straight to a task? diff --git a/docs/session-ledger.md b/docs/session-ledger.md index 2a29776..0b29b22 100644 --- a/docs/session-ledger.md +++ b/docs/session-ledger.md @@ -31,8 +31,8 @@ - **OPEN security rows:** SEC-001 (rotate at v1 close, re-ruled 2026-07-06), SEC-003 (custodians + second-person unseal -- DEFERRED; keeps d011-06 MANUAL), SEC-004 (flip repo to private at v1 close -- deferral reaffirmed). -- **Next-free numbers:** D = 076, DOCFIX = 128, BUNDLEFIX = 012. - (Seeded from the 2026-07-08 scan, post-addendum-45.) +- **Next-free numbers:** D = 076, DOCFIX = 129, BUNDLEFIX = 012. + (Seeded from the 2026-07-08 scan, post-addendum-46.) --- diff --git a/docs/v1-redeploy-changelog.md b/docs/v1-redeploy-changelog.md index 099a3c5..93a635f 100644 --- a/docs/v1-redeploy-changelog.md +++ b/docs/v1-redeploy-changelog.md @@ -3129,4 +3129,32 @@ - Numbers consumed: DOCFIX-126, DOCFIX-127. REVERT: git checkout HEAD~ -- scripts/tenant-offboard.sh scripts/tenant-onboard.sh tests/tenant-offboard/run-tests.sh clientdocs/sweep-receipt.txt docs/v1-redeploy-changelog.md docs/session-ledger.md; then bash scripts/repo-lint.sh --record-clientdocs-sweep. -Next-free after this push (per scan, keep this line unwrapped): D-076, DOCFIX-128, BUNDLEFIX-012. +### 2026-07-08 (addendum 46, jumphost stream) -- DOCFIX-128: handover package consolidation phase 1 (glossary folded in, hard de-dup, no extra files) + +Operator re-ruling: consolidate the handover package WITHOUT extra files, remove +outliers, hard de-dup (delete, not pointer-mark), and do not let the AI skill +block it -- the skill is rewritten from the consolidated docs next (phase 2). +This supersedes the addendum-43 softer M1/M2 (pointers-keep-copies). + +- **Glossary folded in, glossary.md REMOVED:** the standalone glossary.md added + earlier today is now a "## Glossary" appendix at the end of handover-pack.md + (definitions grouped by theme; the client's own values stay in sections 1-3). + No extra file. References updated: README Contents/Packaging, welcome.md, the + Jenkins guide section 11, and LEAK_FILES (glossary now scanned as part of + handover-pack via the sweep, not a separate harness line). +- **Hard de-dup of the account model:** self-service-guide.md's duplicate + Account/Use/Do-not TABLE is DELETED, replaced by a one-sentence orientation + that points to handover-pack section 2 (the canonical rights table). The + addendum-43 "keep copy + pointer" is gone -- the duplication itself is gone. +- **Distinct task guides KEPT** (operator's chosen consolidation level): intake, + welcome, self-service, handover-pack, ci-integration, jenkins-kubernetes, + acceptance, ai-assistant. Net top-level docs 9 -> 8 (glossary removed). +- Gates: L7 receipt 31 -> 30 files, gauntlet 38/38, repo-lint 0 fail. +- **PHASE 2 NEXT (this session): rewrite the tenant AI skill** (SKILL.md + + references) from the consolidated handover package -- remove the skill's own + duplication of the account model / clouds.yaml, align to the new structure + (glossary location, Jenkins guide, driver/capacity rules). +- Numbers consumed: DOCFIX-128. +REVERT: git checkout HEAD~ -- clientdocs tests/clientdocs-skill/run-tests.sh docs/v1-redeploy-changelog.md docs/session-ledger.md; git checkout HEAD~ -- clientdocs/glossary.md (restore deleted file); then bash scripts/repo-lint.sh --record-clientdocs-sweep. + +Next-free after this push (per scan, keep this line unwrapped): D-076, DOCFIX-129, BUNDLEFIX-012. diff --git a/tests/clientdocs-skill/run-tests.sh b/tests/clientdocs-skill/run-tests.sh index b181e60..a1d2b9c 100644 --- a/tests/clientdocs-skill/run-tests.sh +++ b/tests/clientdocs-skill/run-tests.sh @@ -67,7 +67,6 @@ LEAK_FILES=("${FILES[@]}") [[ -f "$REPO/clientdocs/ai-assistant-guide.md" ]] && LEAK_FILES+=("$REPO/clientdocs/ai-assistant-guide.md") [[ -f "$REPO/clientdocs/jenkins-kubernetes-guide.md" ]] && LEAK_FILES+=("$REPO/clientdocs/jenkins-kubernetes-guide.md") -[[ -f "$REPO/clientdocs/glossary.md" ]] && LEAK_FILES+=("$REPO/clientdocs/glossary.md") for s in "$REPO"/clientdocs/scripts/*.sh; do [[ -f "$s" ]] && LEAK_FILES+=("$s"); done LEAKS="$(grep -rniE "$LEAK_RX" "${LEAK_FILES[@]}" 2>/dev/null)" if [[ -z "$LEAKS" ]]; then