Skip to content

NO-ISSUE: Create AGENTS.md and consolidate AI convention files #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
amir-yogev-gh wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

NO-ISSUE: Create AGENTS.md and consolidate AI convention files #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
254a329
NO-ISSUE: Create AGENTS.md, consolidate CLAUDE.md, add Copilot instru…
amir-yogev-gh Jun 15, 2026
9f492a8
NO-ISSUE: Remove copilot-instructions.md from this PR
amir-yogev-gh Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# osac-test-infra

End-to-end test infrastructure for OSAC. pytest-based test suite for testing ComputeInstance lifecycle, cluster provisioning, networking, and PublicIP management through the OSAC fulfillment service.

## Critical Rules

- **Type annotations required** on all variables in pytest tests
- **Keyword-only arguments** (`*`) in all test helper methods
- **Never hardcode sleep** — use `poll_until` for waiting
- **Clean up resources in tests** — delete in reverse creation order, verify deletion from both K8s and API
- **Run `ruff check` and `ruff format`** before committing

## Dev Environment

```bash
# Setup
uv sync

# Run all pytest tests
make test

# Run VmaaS tests only
make test-vmaas

# Run CaaS tests only
make test-caas

# Run a specific test
make test TEST="test_create_compute_instance"

# Lint and format
make lint
make format

# Pre-commit hooks
pre-commit run --all-files
```

## Repository Structure

```text
osac-test-infra/
├── tests/ # pytest E2E test suite
│ ├── conftest.py # Shared fixtures (grpc, k8s clients, cli, namespace)
│ ├── core/ # Test infrastructure helpers
│ │ ├── runner.py # Test runner utilities
│ │ ├── k8s_client.py # Kubernetes client wrapper
│ │ ├── grpc_client.py # gRPC client wrapper
│ │ ├── osac_cli.py # osac CLI wrapper
│ │ ├── keycloak.py # Keycloak integration
│ │ └── helpers.py # Shared test helpers
│ ├── vmaas/ # VM-as-a-Service tests (compute, networking, security)
│ └── caas/ # Cluster-as-a-Service tests
├── Makefile # Test and lint targets
├── pyproject.toml # Python 3.11+, pytest, ruff config
└── .pre-commit-config.yaml # yamllint, ansible-lint, pre-commit hooks
```

## Test Configuration

Tests are configured via environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `OSAC_NAMESPACE` | Yes | Target namespace for tests |
| `KUBECONFIG` | Yes | Hub cluster kubeconfig |
| `OSAC_VM_KUBECONFIG` | Yes | VM/workload cluster kubeconfig |
| `OSAC_FULFILLMENT_ADDRESS` | No | Fulfillment service address |
| `OSAC_VM_TEMPLATE` | No | VM template to use |
| `OSAC_SERVICE_ACCOUNT` | No | Service account for token creation |
| `OSAC_CLI_PATH` | No | Path to osac CLI binary |

Two-kubeconfig design: hub cluster (API, operators) and VM cluster (workloads) are separate.

## Test Conventions

- Use `uuid4().hex[:8]` for random resource name suffixes
- gRPC API packages: `osac.public.v1` and `osac.private.v1`
- K8s label convention: `osac.openshift.io/<resource>-uuid`
- CRD shortnames: `computeinstance`, `virtualnetwork`, `subnet`, `securitygroup`, `clusterorder`, `publicip`, `publicippool`, `tenant`

## Code Style

- **Ruff** for linting and formatting (line-length 120, strict type annotations)
- **Ruff lint rules**: E, F, W, I, UP, ANN, B, SIM, RUF
- **Pre-commit hooks**: trailing-whitespace, yamllint (strict), ansible-lint

## CI

GitHub Actions (`.github/workflows/`):
- **pre-commit.yaml** — runs pre-commit hooks on PRs

## gRPC API Operations

| Service | RPC | Purpose |
|---------|-----|---------|
| `private.v1.Hubs/Get` | Get hub details | Hub verification |
| `private.v1.ComputeInstances/List` | List compute instances | Test discovery |
| `private.v1.ComputeInstances/Get` | Get compute instance | Status verification |
| `private.v1.ComputeInstances/Delete` | Delete compute instance | Cleanup |

All gRPC calls use insecure connections with Bearer token authentication.
141 changes: 4 additions & 137 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,141 +1,8 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@AGENTS.md

## Overview
## Claude Command Syntax

This repository contains Ansible-based test infrastructure for OSAC end-to-end testing. It focuses on testing hub creation and ComputeInstance lifecycle management through the OSAC fulfillment service using gRPC APIs and the osac CLI tool.

## Architecture

### Directory Structure
- `playbooks/` - Main Ansible playbooks for executing tests
- `roles/` - Reusable Ansible roles for test functionality
- `test_compute_instance_creation/` - Role for ComputeInstance creation, verification, and cleanup
- `test_hub_creation/` - Role for hub creation, verification, and cleanup
- `osac_cli_base/` - Base role for osac CLI operations (dependency)
- `inventory/` - Ansible inventory and group variables
- `group_vars/all.yml` - Global configuration variables
- `retry/` - Ansible retry files for failed playbook runs

### Core Components

**Hub Creation Testing**
- Hub creation and registration using osac CLI
- Hub verification through gRPC API calls (private.v1.Hubs/Get)
- Automated cleanup of hub resources and temporary files

**ComputeInstance Lifecycle Testing**
- ComputeInstance creation using osac CLI with OSAC templates
- gRPC-based verification through the fulfillment service
- Status monitoring and readiness checks
- Automated cleanup and deletion

**Communication Methods**
- `osac` for hub/ComputeInstance creation operations
- `grpcurl` for direct API communication with fulfillment service
- gRPC authentication using Bearer tokens from OpenShift service accounts

## Development Commands

### Code Quality
```bash
# Run pre-commit hooks (yamllint, ansible-lint, etc.)
pre-commit run --all-files

# Run yamllint specifically
yamllint --strict *.yml *.yaml

# Run ansible-lint specifically
ansible-lint
```

### Running Tests

Execute hub creation test:
```bash
ansible-playbook playbooks/test_hub_creation.yml -e test_hub_id=my-test-hub-001 -e test_namespace=foobar
```

Execute ComputeInstance creation test:
```bash
ansible-playbook playbooks/test_compute_instance_creation.yml -e test_compute_instance_id=my-test-ci-001 -e test_namespace=foobar
```

### Test Tags

Use tags to run specific parts of tests:
- `info` - Display test information and resource listings
- `test` - Run actual creation tests (hub_creation, compute_instance_creation)
- `validation` - Resource verification and status checks
- `cleanup` - Resource deletion and file cleanup
- `mrclean` - Mass cleanup of test ComputeInstances with e2e-test-ci- prefix

Examples:
```bash
# Run only hub creation without cleanup
ansible-playbook playbooks/test_hub_creation.yml --tags test

# Run only ComputeInstance creation without cleanup
ansible-playbook playbooks/test_compute_instance_creation.yml --tags test

# Run only cleanup operations
ansible-playbook playbooks/test_compute_instance_creation.yml --tags cleanup

# Mass cleanup of all test ComputeInstances
ansible-playbook playbooks/test_compute_instance_creation.yml --tags mrclean
```

## Configuration

### Key Variables (inventory/group_vars/all.yml)

**Required for customization:**
- `cluster_domain_suffix` - OpenShift cluster domain (e.g., "apps.hcp.local.lab")
- `test_namespace` - Target namespace (default: "foobar")
- `osac_cli_path` - Path to osac binary

**Auto-constructed addresses:**
- `fulfillment_address` - Constructed as `{app_name}-{namespace}.{domain}:{port}`
- `fulfillment_token_script` - OpenShift token creation command

**Hub creation specific:**
- `hub_service_account` - Service account for hub operations (default: "fulfillment-admin")
- `hub_token_duration` - Token validity period (default: "1h")

## ComputeInstance Template Configuration

Default ComputeInstance template: `cloudkit.templates.ocp_virt_vm`
- CPU: 2 cores
- Memory: 4GB
- Disk: 20GB
- Network: default
- Ready timeout: 15 minutes

## gRPC API Operations

**Hub Operations:**
- `private.v1.Hubs/Get` - Get specific hub details

**ComputeInstance Operations:**
- `private.v1.ComputeInstances/List` - List all ComputeInstances
- `private.v1.ComputeInstances/Get` - Get specific ComputeInstance details
- `private.v1.ComputeInstances/Delete` - Delete a ComputeInstance

All gRPC calls use insecure connections and require Bearer token authentication.

## Test Execution Flow

1. **Setup**: Display test information and parameters
2. **Creation**: Create hub/ComputeInstance using osac CLI with specified parameters
3. **Verification**: Verify registration via gRPC API
4. **Monitoring**: Wait for resources to reach desired status
5. **Cleanup**: Delete resources and remove temporary files
6. **Logging**: Record test results to test-execution.log

## Error Handling

- Failed tests trigger automatic cleanup of temporary files
- Resource deletion verification ensures proper cleanup
- All operations include proper error logging and failure messages
- Retry functionality available through Ansible retry files in `retry/` directory
- `/e2e` — Write a pytest E2E test from a description or Jira ticket
- `/debug-e2e` — Debug a failing Prow CI job using build logs and gathered OSAC artifacts