gcp-hcp-architecture

name

GCP-HCP-Architecture

description

Use when working on GCP HCP-related code or design in any of the GCP HCP repositories: hypershift (platform/gcp/, GCP provider, GCP-related tests), gcp-hcp-infra (Terraform, ArgoCD, infrastructure), gcp-hcp-cli, cls-backend, cls-controller, or when creating or reviewing design decisions, or needing architectural context for GCP Hosted Control Planes on GKE. Accepts optional topic filter: networking, identity, observability, infrastructure, automation, governance, storage, operators, testing, incidents, slo.

GCP HCP Architecture Context

Provides architectural context, design decisions, and implementation plans for GCP Hosted Control Planes (HCP) on GKE. Use this skill to understand constraints and rationale before writing or reviewing code.

Source repository: openshift-online/gcp-hcp

When to Use

Auto-invoke when:

• Working on files in platform/gcp/, GCP provider code, or GCP-related tests in hypershift
• Creating or modifying design decisions in design-decisions/
• Reviewing PRs that touch GCP infrastructure or control plane components
• Writing implementation plans for GCP HCP features

Manual invocation: /gcp-hcp-architecture [topic]

See design-decisions/INDEX.md for a browsable listing of all decision records.

Topic Index

Specify a topic to narrow results. Read the linked files from the gcp-hcp repository for full context.

Topic	Design Decisions	Architecture	Implementation Plans
networking	private-service-connect-networking, gcp-private-service-connect, gke-dataplane-v2-networking, no-direct-cross-cluster-connectivity, gke-ingress-controller, google-managed-certificates, gcp-api-gateway-frontend, customer-dns-zone-management, ci-externaldns-configuration, oidc-cdn-public-serving, datastore-transport, rc-mc-transport-layer (superseded)	—	gcp-private-service-connect-implementation, gcp-customer-authentication
identity	workload-identity-implementation, prow-ci-workload-identity-federation, iap-authentication, pam-workflow-gating, zero-operator-access	—	gcp-wif-integration
observability	observability-google-managed-prometheus, integrated-alerting-framework, data-lake-for-diagnostics-and-compliance	—	—
infrastructure	gke-container-platform, gcp-folder-project-hierarchy, regional-independence-architecture, gke-fleet-management, shared-node-pools	L1 Context, L2 Container	—
automation	automation-first-philosophy, terraform-infrastructure-as-code, terraform-code-structure, terraform-automation-tooling, argocd-sync-wave-standardization, deployment-tooling-swim-lanes, pipeline-automation-tooling, cloud-workflows-automation-platform, cloud-workflows-common-tools-image, container-image-build-and-distribution, container-image-build-and-distribution-pipeline, ai-centric-sdlc, agent-autonomy-levels	—	gcp-320-automated-remediation-platform, ai-sdlc-pilot-update skill (biweekly GCP-579 pilot reporting)
governance	naming-conventions, repository-organization-policy, gcphcpctl-graduation, adopt-cincinnati-for-version-resolution	—	adopt-cincinnati-for-version-resolution-selection-and-upgrades
storage	—	—	gcp-pd-csi-operator-migration, gcp-persistent-disk-csi-driver
operators	—	L3 Component/Hypershift	gcp-321-image-registry-operator-integration
testing	—	—	hypershift-repo-gcp-hcp-e2e-tests-implementation
incidents	—	—	incidents/ — read all post-mortems for past failure patterns and lessons learned
slo	—	—	slo/ — read all SLO definitions for performance and quality targets

Architectural Invariants

These constraints apply across all topics. Violations should be flagged in code review.

1. No direct cross-cluster connectivity — All cross-cluster coordination uses asynchronous, indirect mechanisms or GCP-level APIs. Direct TCP/UDP between clusters (Global, Regional, Management) is forbidden. PSC for worker-to-control-plane data-plane is the exception.
2. Regional independence — Each region operates independently with minimal cross-region dependencies. No cross-region network costs or data residency violations.
3. Workload Identity for all authentication — No long-lived service account keys. All operators use WIF to bind Kubernetes SAs to Google SAs.
4. Google Managed Prometheus for observability — Hybrid GMP architecture (self-managed Prometheus + GMP storage). No custom Prometheus deployments.
5. ArgoCD for all deployments — No direct helm install or kubectl apply for production workloads.
6. Terraform for infrastructure — All GCP infrastructure managed via Terraform.

Cross-Repo Map

Repository	What Lives There
gcp-hcp	Design decisions, architecture docs, implementation plans, studies, Jira templates
hypershift	GCP platform implementation code, CI enforcement (Tekton/Konflux, golangci-lint, gitlint, conventional commits)
gcp-hcp-infra	Terraform modules, ArgoCD configs, infrastructure automation
gcp-hcp-cli	CLI tooling
cls-backend	Cluster Lifecycle Service backend
cls-controller	Cluster Lifecycle Service controller

Quality Standards

• Definition of Done: definition-of-done.md — test coverage >= 85%, PR merge criteria
• Story Template: jira-story-template.md — acceptance criteria format
• Design Decision Template: TEMPLATE.md — required sections and validation checklist

How to Use

1. Identify the relevant topic(s) from the user's task
2. Locate the gcp-hcp repo. If you are already working inside gcp-hcp, use the current directory. Otherwise, ask the user: "Where is your local clone of openshift-online/gcp-hcp? (e.g., ~/go/src/github.com/openshift-online/gcp-hcp)" — use the provided path for all subsequent file reads in this session. If the repo is not cloned locally, use the GitHub links in the topic index above.
3. Read the mapped design decisions and architecture docs using the topic index above
4. Apply constraints and rationale when writing or reviewing code
5. Reference specific design decisions in PR descriptions and commit messages
6. Flag any violations of architectural invariants during code review