HyperFleet GCP Validation Adapter

Event-driven adapter for HyperFleet GCP cluster validation. Validates GCP cluster configurations and prerequisites before provisioning. Consumes CloudEvents from message brokers (GCP Pub/Sub, RabbitMQ), processes AdapterConfig, manages validation jobs in Kubernetes, and reports status via API.

Table of Contents

• Prerequisites
• Deployment Modes
• Local Development
• Helm Chart Installation
• Configuration
• Examples

Prerequisites

• Kubernetes 1.19+
• Helm 3.0+
• GCP Workload Identity (for Pub/Sub access)
• gcloud CLI configured with appropriate permissions

Deployment Modes

This adapter supports two deployment modes via the validation.useDummy parameter:

Real Mode (Default, Production)

• Value: validation.useDummy: false (default)
• Description: Performs actual GCP validation checks
• Config File: Uses charts/configs/validation-adapter.yaml
• Features:
  • Real GCP API validation
  • Production-ready validation checks
  • Comprehensive error reporting

Dummy Mode (Testing/Development)

• Value: validation.useDummy: true
• Description: Simulates GCP validation for testing and development
• Config File: Uses charts/configs/validation-dummy-adapter.yaml
• Features:
  • Configurable simulation results (success, failure, hang, crash, invalid-json, missing-status)
  • No actual GCP API calls
  • Fast validation cycles for testing

Local Development

Run the adapter locally for development and testing.

Prerequisites

• hyperfleet-adapter binary installed and in PATH
• GCP service account key for Pub/Sub access
• Access to a GKE cluster (for applying Kubernetes resources)
• podman or docker for RabbitMQ (if BROKER_TYPE=rabbitmq)

Setup

1. Copy environment template:

cp env.example .env

2. Edit .env with your configuration:

# Required for Google Pub/Sub (default)
GCP_PROJECT_ID="your-gcp-project-id"
BROKER_TOPIC="hyperfleet-adapter-topic"
BROKER_SUBSCRIPTION_ID="hyperfleet-adapter-validation-gcp-subscription"

# Required for all broker types
HYPERFLEET_API_BASE_URL="https://localhost:8000"

# Optional (defaults provided)
SUBSCRIBER_PARALLELISM="1"
HYPERFLEET_API_VERSION="v1"

# Validation-specific settings
STATUS_REPORTER_IMAGE="<The image built by https://github.com/openshift-hyperfleet/status-reporter>"
SIMULATE_RESULT="success"  # success, failure, hang, crash, invalid-json, missing-status
RESULTS_PATH="/results/adapter-result.json"
MAX_WAIT_TIME_SECONDS="300"

# Required for RabbitMQ (if BROKER_TYPE=rabbitmq)
# RABBITMQ_URL="amqp://guest:guest@localhost:5672/"

3. Set up GCP authentication:

# Create service account key and set in .env
export GOOGLE_APPLICATION_CREDENTIALS="./sa-key.json"

4. Connect to your GKE cluster:

gcloud container clusters get-credentials "$GKE_CLUSTER_NAME" \
  --region "$GKE_CLUSTER_REGION" \
  --project "$GCP_PROJECT_ID"

kubectl cluster-info

Run

# For Google Pub/Sub (default)
./run-local.sh

# For RabbitMQ
BROKER_TYPE=rabbitmq ./run-local.sh

Helm Chart Installation

Installing the Chart

Real Validation Mode (Default, Production):

helm install validation-gcp ./charts/ \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription \
  --set hyperfleetApi.baseUrl=https://api.hyperfleet.example.com

With Specific Deployment Mode:

# Dummy mode (simulated validation for testing)
helm install validation-gcp ./charts/ \
  --set validation.useDummy=true \
  --set validation.dummy.simulateResult=success \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription

# Real mode (production GCP validation - this is the default)
helm install validation-gcp ./charts/ \
  --set validation.useDummy=false \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription

Install to a Specific Namespace

helm install validation-gcp ./charts/ \
  --namespace hyperfleet-system \
  --create-namespace \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription

Uninstalling the Chart

helm delete validation-gcp

# Or with namespace
helm delete validation-gcp --namespace hyperfleet-system

Configuration

All configurable parameters are in values.yaml. For advanced customization, modify the templates directly.

Validation Mode

Parameter	Description	Default
validation.useDummy	Use dummy mode for testing (true) or real validation (false)	false

Image & Replica

Parameter	Description	Default
replicaCount	Number of replicas	1
image.registry	Image registry	registry.ci.openshift.org
image.repository	Image repository	ci/hyperfleet-adapter
image.tag	Image tag	latest
image.pullPolicy	Image pull policy	Always
imagePullSecrets	Image pull secrets	[]

Naming

Parameter	Description	Default
nameOverride	Override chart name	""
fullnameOverride	Override full release name	""

ServiceAccount & RBAC

Parameter	Description	Default
serviceAccount.create	Create ServiceAccount	true
serviceAccount.name	ServiceAccount name (auto-generated if empty)	""
serviceAccount.annotations	ServiceAccount annotations (for Workload Identity)	{}
rbac.create	Create ClusterRole and ClusterRoleBinding	false

When rbac.create=true, the adapter gets minimal permissions needed for validation:

• Namespaces: get, list, watch (read-only, to verify target namespace exists)
• ServiceAccounts: Full management (create, update, patch, delete, get, list, watch)
• Roles/RoleBindings: Full management (for validation job RBAC)
• Jobs: Full management (for validation job lifecycle)
• Jobs/status: get, update, patch (for status reporter sidecar)
• Pods: get, list, watch (read-only, to check validation job pod status)

Logging

Parameter	Description	Default
logging.level	Log level: debug, info, warn, error	info
logging.format	Log format: text, json	text
logging.output	Log output: stdout, stderr	stderr

Scheduling

Parameter	Description	Default
nodeSelector	Node selector	{}
tolerations	Tolerations	[]
affinity	Affinity rules	{}

Broker Configuration

Parameter	Description	Default
broker.type	Broker type: googlepubsub or rabbitmq (required)	""
broker.subscriber.parallelism	Number of parallel workers	1
broker.yaml	Raw YAML override (advanced use)	""

Google Pub/Sub (when broker.type=googlepubsub)

Parameter	Description	Default
broker.googlepubsub.projectId	GCP project ID (required)	""
broker.googlepubsub.topic	Pub/Sub topic name (required)	""
broker.googlepubsub.subscription	Pub/Sub subscription ID (required)	""
broker.googlepubsub.deadLetterTopic	Dead letter topic name (optional)	""

RabbitMQ (when broker.type=rabbitmq)

Parameter	Description	Default
broker.rabbitmq.url	RabbitMQ connection URL (required)	""

HyperFleet API

Parameter	Description	Default
hyperfleetApi.baseUrl	HyperFleet API base URL	""
hyperfleetApi.version	API version	v1

Validation Configuration

Common Settings (Both Modes)

Parameter	Description	Default
validation.statusReporterImage	Status reporter sidecar image	registry.ci.openshift.org/ci/status-reporter:latest
validation.resultsPath	Path where validation results are written	"/results/adapter-result.json"
validation.maxWaitTimeSeconds	Maximum time to wait for validation completion	"300"

Dummy Mode Settings (when validation.useDummy=true)

Parameter	Description	Default
validation.dummy.simulateResult	Simulated result (success, failure, hang, crash, invalid-json, missing-status)	"success"

Real Mode Settings (when validation.useDummy=false)

Parameter	Description	Default
validation.real.gcpValidatorImage	GCP validator container image	registry.ci.openshift.org/ci/gcp-validator:latest
validation.real.disabledValidators	Comma-separated list of validators to disable	"quota-check"
validation.real.requiredApis	Comma-separated list of required GCP APIs to validate	"compute.googleapis.com,iam.googleapis.com,cloudresourcemanager.googleapis.com"
validation.real.logLevel	Log level for validation containers (debug, info, warn, error)	"info"
validation.real.stopOnFirstFailure	Stop execution on first failure. true = fail-fast, false = collect all results	false

Environment Variables

Parameter	Description	Default
env	Additional environment variables	[]

Example:

env:
  - name: MY_VAR
    value: "my-value"
  - name: MY_SECRET
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: key

Examples

Basic Real Validation with Google Pub/Sub (Default)

helm install validation-gcp ./charts/ \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription \
  --set hyperfleetApi.baseUrl=https://api.hyperfleet.example.com

Dummy Validation with Different Simulation Results

# Simulate failure
helm install validation-gcp ./charts/ \
  --set validation.useDummy=true \
  --set validation.dummy.simulateResult=failure \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription

# Simulate hang (for timeout testing)
helm install validation-gcp ./charts/ \
  --set validation.useDummy=true \
  --set validation.dummy.simulateResult=hang \
  --set validation.maxWaitTimeSeconds=60 \
  --set broker.type=googlepubsub \
  ...

With RabbitMQ

helm install validation-gcp ./charts/ \
  --set validation.useDummy=true \
  --set broker.type=rabbitmq \
  --set broker.rabbitmq.url="amqp://user:password@rabbitmq.svc:5672/"

With GCP Workload Identity and RBAC

First, grant Pub/Sub permissions to the KSA (Kubernetes Service Account) :

# Get project number
PROJECT_NUMBER=$(gcloud projects describe my-gcp-project --format="value(projectNumber)")

# Grant permissions using direct principal binding
gcloud projects add-iam-policy-binding my-gcp-project \
  --role="roles/pubsub.subscriber" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/my-gcp-project.svc.id.goog/subject/ns/hyperfleet-system/sa/validation-gcp" \
  --condition=None

gcloud projects add-iam-policy-binding my-gcp-project \
  --role="roles/pubsub.viewer" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/my-gcp-project.svc.id.goog/subject/ns/hyperfleet-system/sa/validation-gcp" \
  --condition=None

Then deploy:

# Real validation mode (default)
helm install validation-gcp ./charts/ \
  --namespace hyperfleet-system \
  --create-namespace \
  --set image.registry=us-central1-docker.pkg.dev/my-project/my-repo \
  --set image.repository=hyperfleet-adapter \
  --set image.tag=v0.1.0 \
  --set broker.type=googlepubsub \
  --set broker.googlepubsub.projectId=my-gcp-project \
  --set broker.googlepubsub.topic=my-topic \
  --set broker.googlepubsub.subscription=my-subscription \
  --set hyperfleetApi.baseUrl=https://api.hyperfleet.example.com \
  --set rbac.create=true

With Values File

Example my-values.yaml

replicaCount: 1

image:
  registry: registry.ci.openshift.org
  repository: ci/hyperfleet-adapter
  tag: latest

serviceAccount:
  create: true

rbac:
  create: true

logging:
  level: debug
  format: json
  output: stderr

hyperfleetApi:
  baseUrl: https://api.hyperfleet.example.com
  version: v1

broker:
  type: googlepubsub
  googlepubsub:
    projectId: my-gcp-project
    topic: hyperfleet-events
    subscription: hyperfleet-validation-subscription
  subscriber:
    parallelism: 1

validation:
  # Use dummy mode for testing, false for production (default)
  useDummy: false

  # Common settings
  statusReporterImage: registry.ci.openshift.org/ci/status-reporter:latest
  resultsPath: /results/adapter-result.json
  maxWaitTimeSeconds: "300"

  # Dummy mode settings (only when useDummy=true)
  dummy:
    simulateResult: success

  # Real mode settings (only when useDummy=false)
  real:
    gcpValidatorImage: registry.ci.openshift.org/ci/gcp-validator:latest
    disabledValidators: "quota-check"
    requiredApis: "compute.googleapis.com,iam.googleapis.com,cloudresourcemanager.googleapis.com"
    logLevel: "info"
    stopOnFirstFailure: false  # true = fail-fast, false = collect all results

Install with values file

helm install validation-gcp ./charts/ -f my-values.yaml

Note: If you encounter a PermissionDenied related subscription error in the Pod, refer to With GCP Workload Identity and RBAC to grant the required permissions first.

Deployment Environment Variables

The deployment sets these environment variables automatically:

Variable	Value	Condition
HYPERFLEET_API_BASE_URL	From hyperfleetApi.baseUrl	When set
HYPERFLEET_API_VERSION	From hyperfleetApi.version	Always (default: v1)
ADAPTER_CONFIG_PATH	/etc/adapter/adapter.yaml	Always
BROKER_CONFIG_FILE	/etc/broker/broker.yaml	When broker.type is set
BROKER_SUBSCRIPTION_ID	From broker.googlepubsub.subscription	When broker.type=googlepubsub
BROKER_TOPIC	From broker.googlepubsub.topic	When broker.type=googlepubsub
GCP_PROJECT_ID	From broker.googlepubsub.projectId	When broker.type=googlepubsub
STATUS_REPORTER_IMAGE	From validation.statusReporterImage	Always
RESULTS_PATH	From validation.resultsPath	Always
MAX_WAIT_TIME_SECONDS	From validation.maxWaitTimeSeconds	Always
SIMULATE_RESULT	From validation.dummy.simulateResult	When validation.useDummy=true
GCP_VALIDATOR_IMAGE	From validation.real.gcpValidatorImage	When validation.useDummy=false
DISABLED_VALIDATORS	From validation.real.disabledValidators	When validation.useDummy=false
REQUIRED_APIS	From validation.real.requiredApis	When validation.useDummy=false
VALIDATOR_LOG_LEVEL	From validation.real.logLevel	When validation.useDummy=false
STOP_ON_FIRST_FAILURE	From validation.real.stopOnFirstFailure	When validation.useDummy=false

License

See LICENSE for details.