setup.md

Setup Guide

This guide covers setting up a HyperFleet environment for running E2E tests locally.

Table of Contents

• Deployment Options
  • Option 1: Kind (Local)
  • Option 2: GCP
• Authentication mode
• Configure Test Settings
• Troubleshooting

Deployment Options

Clone the infrastructure repository:

git clone https://github.com/openshift-hyperfleet/hyperfleet-infra/
cd hyperfleet-infra/terraform

Choose one of the following deployment options based on your needs:

• Kind (local): Fast setup, no cloud dependencies, uses port-forwarding
• GCP: Cloud environment, requires GCP access, slower setup, uses a LoadBalancer service

Both options deploy the desire delivery stack next to the adapters: Redis (the desire store), the applier, and the remote adapter cl-desire. The remote-transport suites need it (test cases). See Desire delivery in the hyperfleet-infra README.

The tests reach the API through the gateway, svc/hyperfleet-gateway, which listens on plain HTTP on port 8000. svc/hyperfleet-api is ClusterIP-only and serves TLS to the gateway, so do not point the tests at it.

Authentication mode

The E2E runner defaults to AUTH_MODE=EDGE+API. Set AUTH_MODE to the same value used to deploy HyperFleet. Supported values are NONE, API, EDGE, and EDGE+API.

For authenticated modes, E2E acquires a projected token for hyperfleet-e2e-runner using Kubernetes TokenRequest. The e2e Helmfile environment creates this ServiceAccount before tests start. The runner needs permission to create TokenRequests; the multi-issuer test also creates a temporary alternate ServiceAccount. The token namespace defaults to NAMESPACE, and the audit identity is derived automatically.

Mode	Machine token sent by E2E	Machine token sent by test adapters
NONE	No token	Chart default; auth is disabled
API	Bearer <token>	Chart default Bearer
EDGE	ServiceAccount <token>	ServiceAccount <token>
EDGE+API	ServiceAccount <token>	ServiceAccount <token>

The schemes select different Authorino authentication methods. ServiceAccount triggers Kubernetes TokenReview; Bearer triggers human OIDC JWT validation. This prevents a machine token from entering the human-token path. See the infra authentication explanation.

Option 1: Kind (Local)

1. Deploy HyperFleet to Kind cluster:

# option 1: Export namespace and helmfile env
export NAMESPACE=<your-dev-namespace> ; export HELMFILE_ENV=e2e-kind ; make local-up-kind
# option 2: Set in command line
NAMESPACE=<your-dev-namespace> HELMFILE_ENV=e2e-kind make local-up-kind

2. Port-forward the gateway:

export API_LOCAL_PORT=8000
kubectl port-forward -n ${NAMESPACE} svc/hyperfleet-gateway ${API_LOCAL_PORT}:8000

3. Configure environment variables:

export HYPERFLEET_API_URL=http://localhost:${API_LOCAL_PORT}
export NAMESPACE=<your-dev-namespace>

4. Verify deployment:

# Check Helm releases
helm list -n ${NAMESPACE}

# Verify all pods are running
kubectl get pods -n ${NAMESPACE}

# Test API connectivity
curl -f -X GET ${HYPERFLEET_API_URL}/api/hyperfleet/v1/clusters/

Option 2: GCP

1. Deploy HyperFleet to GCP cluster:

Note: Make sure your terraform files are up to date. See hyperfleet-infra/CONTRIBUTING.md for details.

• terraform/envs/gke/dev.tfbackend
• terraform/envs/gke/dev.tfvars

See hyperfleet-infra/README.md for infrastructure deployment details.

# option 1: Export namespace and helmfile env
export NAMESPACE=<your-dev-namespace> ; export HELMFILE_ENV=e2e-gcp ; make local-up-gcp
# option 2: Set in command line
NAMESPACE=<your-dev-namespace> HELMFILE_ENV=e2e-gcp make local-up-gcp

2. Wait for the gateway's external IP:

In e2e-gcp, svc/hyperfleet-gateway is a LoadBalancer.

# Wait for the external IP to be assigned (may take 1-2 minutes)
kubectl get svc hyperfleet-gateway -n ${NAMESPACE} -w

With AUTH_MODE=EDGE or EDGE+API, Authorino denies requests whose host it does not know. For a dynamically assigned LoadBalancer IP, re-apply the gateway with AUTHORINO_HOSTS set to that IP before running tests. CI setup performs this second apply automatically.

3. Configure environment variables:

export API_EXTERNAL_IP=$(kubectl get svc hyperfleet-gateway -n ${NAMESPACE} -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
export HYPERFLEET_API_URL=http://${API_EXTERNAL_IP}:8000
export NAMESPACE=<your-dev-namespace>

4. Verify deployment:

# Check Helm releases
helm list -n ${NAMESPACE}

# Verify all pods are running
kubectl get pods -n ${NAMESPACE}

# Test API connectivity
curl -f -X GET ${HYPERFLEET_API_URL}/api/hyperfleet/v1/clusters/

Configure Test Settings

Override Image Settings (Optional)

If your deployment uses custom image settings, update env/env.local in this repo to match your infrastructure deployment settings:

• Kind deployments: Match settings from env.kind
• GCP deployments: Match settings from env.gcp

Update env/env.local:

# env/env.local
export IMAGE_REGISTRY=<registry>
export <COMPONENT>_IMAGE_REPO=<repo>
export <COMPONENT>_IMAGE_TAG=<tag>

Source the configuration:

source env/env.local

This configuration is required for running tier2 tests.

Troubleshooting

Infrastructure Setup Issues

For additional help with infrastructure deployment and configuration, see:

• hyperfleet-infra README - Main infrastructure documentation

For test-specific troubleshooting (timeouts, API errors, namespace mismatches), see the Runbook Troubleshooting section.

---

Next Steps: Once your environment is set up, see the Runbook for running tests and troubleshooting.