// Use when debugging integration-service running on a cluster. Covers pod logs, health probes, metrics, webhooks, network policies, environment variables, snapshot GC, and common failure modes.
Use when CI checks fail unexpectedly, when preparing code for CI, or when encountering non-obvious build and pipeline behavior. Covers vendoring, hermetic builds, security scans, code generation checks, coverage, and webhook validation gotchas.
Use when setting up a local development environment, deploying integration-service to a cluster, installing CRDs, or tearing down a Kind cluster. Covers make targets, kustomize deployment, and full Konflux stack setup.
Use when preparing a pull request for review, before pushing, or when reviewing someone else's PR. Checklist of CI checks, commit conventions, code generation, testing, and documentation requirements.
Use when building, configuring, or running e2e tests for integration-service against a real cluster (Kind or OpenShift). Covers environment variables, test framework, Ginkgo flags, CI pipeline, and test repos.
Use when running, writing, or troubleshooting unit tests for integration-service. Covers make test, envtest setup, suite patterns, mock loader, CRD discovery, coverage, and common test failures.
| name | debugging-running-instance |
| description | Use when debugging integration-service running on a cluster. Covers pod logs, health probes, metrics, webhooks, network policies, environment variables, snapshot GC, and common failure modes. |
The integration-service runs as a Deployment in the integration-service namespace. It exposes health probes, Prometheus metrics, and optional webhooks. A separate CronJob handles snapshot garbage collection.
| What | How |
|---|---|
| Controller logs | kubectl logs -n integration-service deploy/controller-manager -f |
| Health check | kubectl get -n integration-service deploy/controller-manager -o jsonpath='{.status.conditions}' |
| Readiness probe | HTTP GET /readyz on port 8081 |
| Liveness probe | HTTP GET /healthz on port 8081 |
| Metrics | Port 8080 (HTTPS, self-signed cert), scraped at /metrics |
| Webhook port | 9443 (when enabled) |
| Leader election | Lease-based, 15s lease duration, 10s renew deadline, 2s retry period |
| Pod label | control-plane: controller-manager |
| Variable | Default | Effect if wrong |
|---|---|---|
CONSOLE_URL | none | PR status comments show CONSOLE_URL_NOT_AVAILABLE |
CONSOLE_URL_TASKLOG | none | Task log links show CONSOLE_URL_TASKLOG_NOT_AVAILABLE |
CONSOLE_NAME | none | Console display name missing from PR comments |
PIPELINE_TIMEOUT | none | Invalid duration is logged as error and skipped |
TASKS_TIMEOUT | none | Invalid duration is logged as error and skipped |
FINALLY_TIMEOUT | none | Invalid duration is logged as error and skipped |
INTEGRATION_NS | integration-service | Wrong namespace for PAC secret lookup |
PAC_SECRET | pipelines-as-code-secret | Can't authenticate to git providers |
Namespaces must be explicitly labeled for traffic to reach the controller:
| Traffic | Required label |
|---|---|
| Metrics scraping | metrics: enabled on source namespace |
| Webhook calls | webhook: enabled on source namespace |
Missing labels = silently blocked traffic. Check with: kubectl get ns <name> --show-labels
| Webhook | Type | Failure Policy | Effect |
|---|---|---|---|
| IntegrationTestScenario | Mutating | Ignore | Defaults applied silently on failure |
| IntegrationTestScenario | Validating | Fail | Rejects invalid ITS (bad names, conflicting resolver params) |
| ComponentGroup | Validating | Fail | Blocks invalid ComponentGroups |
| Snapshot | Mutating + Validating | Ignore | Failures silently pass through (by design) |
CONSOLE_URL env var and PAC secret availabilitywebhook: enabled) and cert-manager statusmetrics: enabled) and ServiceMonitor existssnapshotgc CronJob logs — runs every 6h with separate service account| Problem | Fix |
|---|---|
CONSOLE_URL_NOT_AVAILABLE in PR comments | Set CONSOLE_URL env var with {{NAMESPACE}} and {{PIPELINE_RUN_NAME}} placeholders |
| Controller crash loop | Check env var values — timeout vars must be valid Go durations (e.g., 2h, 30m) |
| Webhook silently not validating Snapshots | By design — Snapshot webhook has failurePolicy: Ignore |
| Metrics endpoint unreachable | Verify namespace label metrics: enabled and that ServiceMonitor target matches |