eBizon CloudSign in

Documentation & CD3 · 06

STEP 6 — Documentation, CD3 Extract & Diagram Reconciliation

The engagement closes (and each subsequent change wave closes) by proving that what is documented, what was designed, and what actually exists in the tenancy are the same thing. The instrument for this is the CD3 toolkit export.

6.1 Produce the CD3 Extract (as-built inventory)

  • Deploy/obtain the OCI CD3 Automation Toolkit (Oracle's open-source toolkit; runs as a container/CLI against the tenancy with read-only credentials for export use).
  • Run the export workflow against the tenancy (per region: home + secondary if enabled). CD3 writes the live estate — compartments, groups, policies, tags, VCNs/subnets/routing/gateways/NSGs, instances, LBs, databases, Object Storage, DNS — into its structured Excel workbook (the CD3 sheet set) and can also generate matching Terraform.
  • Version the export: store the workbook in the docs repository as as-built/{tenancy}-{region}-{yyyymmdd}.xlsx. This is the canonical as-built record for the wave.

    • 6.2 Three-Way Reconciliation

    ComparisonMethodPass condition
    CD3 extract vs IaC stateDiff CD3 inventory against terraform state lists per stack (resource by resource)Every live resource is state-managed (or on the documented exception list, e.g., Day-0 console enablements); no orphans
    CD3 extract vs DesignWalk the design manifest / CIDR registry / IAM matrix against the corresponding CD3 sheetsDesign and reality match; every deviation has an ADR or becomes a finding
    Design diagrams vs TenancyRegenerate/redraw architecture diagrams from the CD3 data; overlay against the Step-1/Step-3 design diagramsPublished diagrams reflect the tenancy as it exists today — no aspirational boxes

    6.3 Final Documentation Pack

  • Governance pack (Step 1, final ratified versions).
  • Answered questionnaire (all sheets) + gap register disposition.
  • Design set: architecture diagrams (current), CIDR registry, IAM matrix, ADRs including exposure and DR decisions.
  • Build evidence: per-stack MRs, plan reviews, apply logs, verification checklists.
  • Validation & audit: Step-5 functional results and the signed CIS audit report with findings disposition.
  • As-built: the CD3 workbook(s) + reconciliation report + regenerated diagrams.
  • Operations handover: runbook library, alarm catalog, cost model & budget owners, Day-2 cadence calendar (weekly drift, monthly CIS + cost + Cloud Advisor review, quarterly access review + DR test).
    • Repeatability:Re-run Steps 5–6 after every subsequent wave: post-build validation → CIS audit → fresh CD3 extract → reconciliation → diagram refresh. The tenancy is compliant not when it was built correctly, but when the latest extract still matches the latest design.

    STEP 6 · DOCUMENT 6 OF 6

    Documentation & As-Built Reconciliation

    Build log · resource register · CD3 as-built extract from the live tenancy · reconciliation: CD3 extract vs design (HLD/LLD) vs architecture diagrams · drift register · handover pack

    Runs continuously through the engagement (build log), at every phase gate (delta extract), and in full at go-live and quarterly (complete as-built refresh). In a fully manual build, this document IS the drift defense.

    Documentation & CD3 As-Built Reconciliation Guide

    FieldValue
    Document ID<CUSTOMER>-DOC-ASB-006
    Versionv1.0 (Generic Template)
    Execution modelOPTION A — FULLY MANUAL (human engineers, OCI Console; no IaC/automation in the build path)
    Customer<CUSTOMER> — replace on engagement start
    Tenancy<TENANCY-NAME> / OCID: <TENANCY-OCID>
    Prepared byCloud Platform Engineering
    Review cyclePer engagement; template annually

    1. Documentation Pack — What Exists and Why

    ArtifactProduced byRefresh cadence
    Governance Standard (Doc 1, adapted)Engagement startAnnually / on Board decision
    Build log (§2)Every console action, same dayContinuous
    Resource register (§2.2)Every resource creationContinuous
    Decision logEvery DECISION POINT in Docs 2–4Continuous
    CD3 as-built extract (§3)This documentPhase gates · go-live · quarterly
    Architecture diagrams (§5)Design phase; updated on reconciliationOn drift resolution / design change
    Validation & audit evidence (Doc 5)Gates and auditsPer event
    O&M handover pack (§6)Go-liveOn operational change
    WHY THIS MATTERS IN OPTION A:An IaC build carries its own record — the code is the documentation. A manual build has no such artifact: if the build log and the as-built extract are not maintained, the tenancy’s true state exists only in the console and in engineers’ memories. Treat documentation lapses as build defects, not admin debt.

    2. Build Log and Resource Register

    2.1 Build log entry format (one row per console action)

    FieldContent
    Timestamp / PhaseDate-time · runbook + section (e.g., Doc 3 §5.2)
    ActionWhat was created/changed, with the exact name
    Executor / ReviewerTwo named engineers (four-eyes) for any state change
    InputsQuestionnaire items / design rows consumed
    EvidenceScreenshot reference / read-only CLI output file
    Temporary?YES flags anything meant to be reverted — the pre-audit sweep (Doc 5 §3.3) walks every YES row
    Change recordCR ID (or the phase umbrella CR)

    2.2 Resource register (one row per resource)

    Name · OCID · type · compartment · created date · runbook reference · tags summary · owner. Maintained as a spreadsheet in the engagement store; §4 reconciles it against the CD3 extract — the register is what you meant to build, the extract is what exists.

    3. CD3 As-Built Extract (Read-Only Export)

    3.1 What CD3 is used for here

    The CD3 (Cloud Deployment Design Deliverable) toolkit is Oracle’s automation toolkit built around an Excel workbook. This engagement uses ONLY its export path: pointed at the live tenancy, CD3 reads existing resources and produces a workbook describing them — compartments, groups, policies, tags, VCNs/subnets/route tables/security lists/NSGs, gateways, DRGs, instances, databases, buckets, and more. That workbook is the as-built record. The toolkit’s create/modify paths are out of scope under the manual-only rule.

    WARNING:CD3 export is read-only, but the same toolkit can also CREATE and MODIFY resources when run in non-export modes. Run it only under a read-only auditor identity so a mode mistake cannot mutate the tenancy — the policy denies what the tool might attempt.

    3.2 Export procedure

  • Identity: run under an OCI-AUDITOR federated identity (read-only by policy). Environment: OCI Cloud Shell or a workstation container with the CD3 toolkit image per Oracle’s published setup (record toolkit version/commit in the extract cover sheet).
  • Prepare a blank CD3 workbook of the matching toolkit version.
  • Run the toolkit in export mode (setUpOCI with the export-existing-resources workflow), scope: all compartments (or the compartment subtree for a delta extract at a phase gate), all subscribed regions.
  • Select all resource families in scope for this engagement: identity (compartments, groups, policies, tags), network (VCNs, subnets, gateways, DRG, route tables, security lists, NSGs), compute (instances), database (ADB), storage (buckets), governance (budgets, quotas) — per toolkit coverage.
  • Output: the populated CD3 workbook + generated inventory. Name it CD3_ASBUILT_<TENANCY>_<DATE>.xlsx; store versioned in the engagement documentation store; never edit the extract by hand (fixes happen in the tenancy or the design, then re-extract).
  • For resource families the toolkit version does not export (e.g., OIC instances, Vault contents, alarms), capture read-only CLI listings (oci integration integration-instance list, oci kms management vault list, oci monitoring alarm list …) into the same dated folder as annex CSVs.
    • VERIFY:The extract cover sheet records: toolkit version, executor, identity used, scope, regions, date, and the annex list. An extract without a cover sheet is not evidence.

    4. Reconciliation: Extract vs Design vs Diagrams

    4.1 Three-way comparison

    ComparisonMethodOutput
    CD3 extract vs design (HLD/LLD tables)Sheet-by-sheet: compartments vs design tree; groups/policies vs the policy set; VCN/subnet/NSG rows vs the network build spec; tags vs the tag standard. Work in the workbook — add a Reconciliation column per sheet: MATCH / DRIFT / MISSING / EXTRA.Drift register rows (§4.2)
    CD3 extract vs resource register (§2.2)Every register row must appear in the extract and vice versa. EXTRA-in-extract = undocumented resource (worst manual-build failure — investigate immediately). MISSING = register overstated or resource deleted without a log entry.Register corrections + drift rows
    Design vs architecture diagramsWalk each diagram (context, landing zone/compartments, network, identity, integration, data flow) against the reconciled design. Update diagrams where the design legitimately evolved via change records.Updated diagram set, versioned

    4.2 Drift register (one row per deviation)

    FieldContent
    IDDRF-<YYYY>-<seq>
    ClassDRIFT (exists, wrong config) / MISSING (designed, not built) / EXTRA (built, not designed)
    Resource / design refOCID + extract sheet/row · design doc + section
    Root causeUnlogged change / design change not propagated / build error / temporary item not reverted
    ResolutionFix the tenancy (via change + runbook section) OR fix the design (via design change control) — one or the other; never "note and ignore"
    StatusOpen / change raised / resolved / accepted-exception (with expiry)
    DECISION POINT:Direction of every fix must be explicit: reality is wrong (remediate the tenancy) or the design is wrong (update HLD/LLD + diagrams under design change control). The drift register is reviewed at every phase gate and quarterly by the governance board — drift count is a standing KPI (Doc 1 §14).

    4.3 Reconciliation cadence

  • Phase gates (Doc 3): delta extract of the compartments touched in the phase; zero-drift is a gate criterion.
  • Workload acceptance (Doc 4 §10): delta extract of the workload compartments.
  • Go-live: full tenancy extract + full three-way reconciliation + diagram refresh.
  • Quarterly: full extract; drift trend reported with the CIS score.

    • 5. Diagram Set

    DiagramContentSource of truth after reconciliation
    D1 — Solution contextTenancy model ([CO-TENANTED]/[ISOLATED]), Fusion SaaS plane vs OCI platform plane, external partiesDoc 1 §1 + extract
    D2 — Landing zoneCompartment tree with owners and Security ZonesExtract compartments sheet
    D3 — NetworkVCNs, subnets, gateways, DRG/FastConnect/VPN, NSG patterns, CIDRsExtract network sheets
    D4 — IdentityIdP → domains → groups → policies chain; break-glass pathExtract identity sheets
    D5 — IntegrationOIC projects, connectivity agents, File Server/SFTP, counterpartiesExtract + OIC annex
    D6 — Data & analyticsATP schemas, buckets, analytics platform, data flowsExtract + annexes
  • Keep diagrams in an editable source format (draw.io / SVG / Visio) in the documentation store, versioned alongside the extracts they were validated against.
  • Every diagram carries: version, date, author, and the extract ID it was reconciled against.
  • Update diagrams only from the reconciled design — never from memory or from the console directly (that bypasses the drift register).

    • 6. Handover Pack (Go-Live)

    #Contents
    1Adapted Governance Standard (Doc 1) with Board approval record.
    2Complete build log + decision log + resource register.
    3Final CD3 as-built extract + annexes + reconciliation with zero open drift (or accepted exceptions listed).
    4Current diagram set (D1–D6) reconciled to the final extract.
    5Validation and CIS audit reports with closed findings register (Doc 5).
    6O&M runbook set: this series Docs 2–6 with customer-specific values filled, alarm/destination matrix, on-call rota, break-glass custody record, P2T post-refresh procedure, backup/restore drill results.
    7Credentials custody: Vault secret register (names + owners + rotation dates — never values), break-glass sealed-credential custody statement.
    8Open items: exception register, deferred decisions (e.g., DR strategy), quota/limit SRs in flight.

    Handover is accepted when the customer operations lead signs that the pack is complete and a shadow-operations period (typically 2–4 weeks of hypercare) has exercised the alarms, the error queue, and at least one controlled change end-to-end.

    Revision History

    VersionDateDescription
    1.0<DATE>Generic template — documentation & CD3 as-built reconciliation edition.