Commit b1a9ebfc authored by xuwang's avatar xuwang
Browse files

docs(readme): trim Framework Structure tree and drop CI Runner Images section 



Collapse the Framework Structure listing to a 2-level tree with general
per-directory descriptions instead of enumerating every .mk/.sh file (the
per-file detail is generated via `make help` / `ls scripts/`). Remove the
CI Runner Images section.

Co-Authored-By: default avatarClaude Opus 4.8 <noreply@anthropic.com>
parent 7d239b65

README.md

+18 −130
Original line number Diff line number Diff line
@@ -148,109 +148,26 @@ Notes: 


```

~/.otica/

├── README.md                    # Basic framework info

├── README.md         # This file

├── CONTRIBUTING.md   # Contributor workflow, conventions, changelog trailers

├── LICENSE                      # Framework license

├── LICENSE

├── VERSION           # Current framework version (semver; source of truth)

├── CHANGELOG.md      # Release notes (generated from Changelog: trailers)

├── .gitlab/

│   └── changelog_config.yml    # Changelog category config for the GitLab generator

├── Makefile          # Developer-only: validation + release targets for this repo

├── tests/

│   └── validate.sh             # parse + deps + scripts checks (see `make validate`)

├── makefiles/                   # Reusable Makefile modules

│   ├── help.mk                 # Help system, PATH setup, variable validation

│   ├── release.mk              # Developer-only: cut framework releases (version/changelog/tag)

│   ├── azure.mk                # Azure authentication and operations

│   ├── aca.mk                  # Azure Container Apps

│   ├── acr.mk                  # Azure Container Registry

│   ├── aks.mk                  # Azure Kubernetes Service

│   ├── az-pim.mk               # Azure AD PIM group activation (standalone — not wired to IaC)

│   ├── gcp.mk                  # Google Cloud Platform

│   ├── gke.mk                  # Google Kubernetes Engine

│   ├── gke-wi.mk               # GKE Workload Identity

│   ├── cloudsql.mk             # Cloud SQL admin (export/import/proxy/connect)

│   ├── aws.mk                  # Amazon Web Services

│   ├── docker.mk               # Docker operations

│   ├── kube.mk                 # Kubernetes operations + TLS cert inspection

│   ├── cert-manager.mk         # cert-manager and CA issuers

│   ├── external-dns.mk         # External DNS (Bitnami helm chart)

│   ├── stakater-reloader.mk    # Stakater Reloader operator

│   ├── terraform.mk            # Terraform operations

│   ├── tf-gitlab-backend.mk    # GitLab Terraform HTTP backend (auto-included by terraform.mk)

│   ├── hc-vault.mk             # HashiCorp Vault (auto-included by gitlab.mk)

│   ├── opa.mk                  # OPA policy-as-code validation

│   ├── gh.mk                   # GitHub CLI auth + ops (auto-included by opa.mk for bundle mode)

│   ├── gitlab.mk               # GitLab project-scoped: secrets, deploy keys, MR merge

│   ├── gitlab-admin.mk         # GitLab instance-scoped: runner inventory + cleanup

│   └── sub-repos.mk            # Sub-repository management

├── scripts/                     # Shell scripts (added to PATH by help.mk)

│   ├── az-login.sh             # Azure authentication

│   ├── az-logout.sh

│   ├── az-create-blob.sh       # Create Azure storage blob

│   ├── gcp-login.sh            # GCP authentication

│   ├── gcp-logout.sh

│   ├── gcp-create-bucket.sh

│   ├── aws-login.sh            # AWS authentication

│   ├── aws-logout.sh

│   ├── aws-create-bucket.sh

│   ├── gke-login.sh            # GKE cluster credentials

│   ├── gke-logout.sh

│   ├── aks-login.sh            # AKS cluster credentials

│   ├── aks-logout.sh

│   ├── get-ksa-kubeconfig.sh   # Generate kubeconfig for a K8s service account

│   ├── render-all.sh           # Render all templates in a directory

│   ├── render.sh               # Single-file template rendering (filter)

│   ├── confirm.sh              # Interactive confirmation prompt

│   ├── functions.sh            # Shared bash utilities (sourced by other scripts)

│   ├── tools-check.sh          # Verify required tools from tools.txt

│   ├── repos-update.sh         # Clone/update sub-repositories

│   ├── update-downstream-tag.sh

│   ├── twoline_prompt.sh       # Two-line shell prompt helper

│   ├── tf-envvars.sh           # Generate TF_VAR_* env file

│   ├── tf-outputs-to-env.sh    # Convert Terraform outputs to env file

│   ├── opa-scan.sh             # OPA source-dir policy scan

│   ├── opa-bundle-download.sh  # Download signed OPA bundle from GitHub

│   ├── opa-bundle-scan.sh      # Scan with downloaded signed bundle

│   ├── az-pim-activate.sh      # Activate PIM-eligible AAD group membership via Graph

│   ├── az-pim-status.sh        # Show active + eligible PIM group assignments

│   ├── az-pim-deactivate.sh    # Release an active PIM group membership early

│   ├── vault-login.sh          # Vault authentication

│   ├── vault-logout.sh

│   ├── vault-read.sh           # Read a Vault secret

│   ├── vault-write.sh          # Write a Vault secret

│   ├── vault-list.sh           # List secrets at a path

│   ├── vault-list-tree.sh

│   ├── vault-list-users.sh

│   ├── vault-info.sh

│   ├── vault-wrap.sh           # Vault token wrapping

│   ├── vault-unwrap.sh

│   ├── vault-wrap-url.sh

│   ├── vault-pwgen.sh          # Generate a random password and store in Vault

│   ├── vault-sshgen.sh         # Generate SSH keypair and store in Vault

│   ├── vault-kv-cp.sh          # Copy Vault KV secrets

│   ├── vault-token-inventory.sh

│   ├── gitlab-pid.sh           # Get GitLab project ID from URL

│   ├── gitlab-pid-number.sh

│   ├── gitlab-server.sh

│   ├── gitlab.sh

│   ├── gl-add-all-sec.sh       # Bulk-add CI/CD secrets from file

│   ├── gl-rm-all-sec.sh        # Bulk-remove CI/CD secrets

│   ├── otica-version.sh        # Read / compute the framework version (semver)

│   ├── otica-changelog.sh      # Render changelog notes via the GitLab changelog API

│   ├── otica-release.sh        # Cut a release: validate, tag, push, publish

│   ├── otica-server-token.sh   # Resolve the OTICA hosting-server API token (sourced)

│   ├── otica-update.sh         # Sync a consumer checkout to latest release (or a tag/branch)

│   └── otica-upgrade-check.sh  # Release-aware "newer version available" notice

├── envs/                        # Environment configuration templates

│   ├── otica-env.mk

│   ├── azure-env.mk

│   ├── gcp-env.mk

│   ├── aws-env.mk

│   └── tf-env.mk

└── helm-charts/                 # Helm chart templates

├── makefiles/        # Reusable Makefile modules — one per platform/feature (azure, gcp,

│                     #   gke, aws, docker, kube, terraform, vault, opa, gitlab, …)

├── scripts/          # Shell helpers added to PATH by help.mk (cloud login/logout, template

│                     #   rendering, Vault ops, GitLab/release tooling, confirm prompt, …)

├── envs/             # Environment config templates (otica/azure/gcp/aws/tf -env.mk)

├── helm-charts/      # Helm chart templates

├── tests/            # Validation harness (see `make validate`)

└── .gitlab/          # Changelog category config for the GitLab generator

```



The authoritative per-module/per-script reference is generated, not hand-maintained:

run `make help` for targets, `ls scripts/` for scripts, or see the

[Technical Reference](docs/OTICA_TECHNICAL_REFERENCE.md#module-reference).



## Examples



Examples live in their own repo tree, not in this framework checkout:
@@ -319,35 +236,6 @@ include ${OTICA_DIR}/makefiles/terraform.mk 
make help

```



## CI Runner Images



OTICA provides per-platform container images for GitLab CI jobs. Each carries the

common OTICA toolchain (gomplate, helm, tfenv/terraform, make, jq, git)

plus **one** cloud CLI, so pick the image matching your project's platform:



| Platform | Image | Source repo |

|----------|-------|-------------|

| GCP   | `us-docker.pkg.dev/clever-circlet-125504/docker-public/gcloud` | `irt-dcs/docker-gcloud` |

| AWS   | `us-docker.pkg.dev/clever-circlet-125504/docker-public/awscli` | `irt-dcs/docker-awscli` |

| Azure | `us-docker.pkg.dev/clever-circlet-125504/docker-public/az`     | `irt-dcs/docker-az` |



Use the image in your job's `image:` (the OTICA Make targets, login scripts, and

terraform all work the same in each):



```yaml

# .gitlab-ci.yml — an AWS project

tf-apply:

  image: us-docker.pkg.dev/clever-circlet-125504/docker-public/awscli:latest

  script:

    - make aws-login

    - make tf-apply

```



> These images were split from the former all-in-one `docker-gcloud` (which

> bundled all three CLIs). `gcloud` is now **gcloud-only** — AWS/Azure jobs that

> previously relied on `aws`/`az` being present in the gcloud image must switch

> to `awscli` / `az`.



## Makefile Modules



Every target is self-documenting — run `make help` (or `make help grep=<topic>`) for the