| name | understanding-konflux-resources |
| description | Use when user asks about Konflux resources, Custom Resources, Applications, Components, Snapshots, IntegrationTestScenarios, ReleasePlans, ReleasePlanAdmissions, or namespace placement. Provides quick reference for what Konflux resources are, who creates them, and where they belong (tenant vs managed namespace). |
Understanding Konflux Resources
Overview
Konflux uses Kubernetes Custom Resources (CRs) to manage CI/CD workflows. Understanding which resource to use, who creates it, and where it belongs prevents common configuration errors.
Core principle: Some resources YOU create, others Konflux creates automatically. Knowing the difference prevents manual work that's already automated.
NAMING CONVENTION - CRITICAL:
Always write resource names WITHOUT spaces: ReleasePlan, ReleasePlanAdmission, IntegrationTestScenario
NEVER use spaces: "Release Plan", "Release Plan Admission", "Integration Test Scenario"
⚠️ COMMON HALLUCINATION - MUST CORRECT:
ReleasePlanAdmission (RPA) is NOT automatically created by Konflux.
ReleasePlanAdmission (RPA) is NOT auto-generated by the release service.
ReleasePlanAdmission (RPA) IS manually created by a Platform Engineer in the managed namespace.
WHO CREATES WHAT - Critical Facts:
- ReleasePlanAdmission (RPA): Platform Engineer creates in managed namespace (NOT you, NOT auto-created)
- Snapshot: Auto-created by Integration Service (NOT you)
- ReleasePlan (RP): You create in tenant namespace
- IntegrationTestScenario (ITS): You create in tenant namespace
NAMESPACE PLACEMENT - Critical for RP/RPA:
- ReleasePlan (RP): Goes in tenant namespace (your workspace)
- ReleasePlanAdmission (RPA): Goes in managed namespace (platform team controlled)
- They work together across different namespaces - RPA references RP
Common abbreviations: RP (ReleasePlan), RPA (ReleasePlanAdmission), ITS (IntegrationTestScenario), App (Application), Comp (Component)
CRITICAL: Konflux has specific resource names. Do NOT invent resource names like "ApplicationSource", "DevBuildTemplate", "BuildConfig", etc. Use ONLY the resources listed in the table below.
When to Use
Use this skill when:
- Choosing which Konflux resource to create
- Understanding Application vs Component
- Confused about Snapshots (when do I create one?)
- Deciding namespace placement (tenant vs managed)
- Mapping CI/CD workflow to Konflux resources
- Getting "resource not found" or "wrong namespace" errors
Quick Reference: Konflux Custom Resources
| Resource | Abbrev | Purpose | Who Creates | Namespace | Key Point |
|---|
| Application | App | Groups related Components that deploy together (NO git URL, NO builds) | User | Tenant | Just a label for grouping |
| Component | Comp | Defines how to build artifact from git repo/branch (HAS git URL) | User | Tenant | This is what builds your code |
| Snapshot | - | Immutable set of component artifact references | Konflux (Integration Service) | Tenant | AUTO-CREATED after builds |
| IntegrationTestScenario | ITS | Defines test to run against snapshot | User | Tenant | Tests run after build |
| ReleasePlan | RP | Maps Application to release action | User | Tenant | Created by app owner |
| ReleasePlanAdmission | RPA | Defines release pipeline + credentials | Platform Engineer | Managed | Contains secrets |
| Release | - | Request to release specific snapshot | User | Tenant | References snapshot + plan |
Common Confusions - Read This First
❌ WRONG: "I need to create a Snapshot after committing code"
✅ CORRECT: Snapshots are AUTO-CREATED by Integration Service after successful builds. You never manually create them.
❌ WRONG: "Put ReleasePlan in managed namespace for security"
✅ CORRECT: ReleasePlan goes in YOUR tenant namespace. ReleasePlanAdmission (with credentials) goes in managed namespace.
❌ WRONG: "RPA is auto-created by Konflux" OR "RPA is automatically generated by the release service"
✅ CORRECT: Platform Engineer manually creates RPA in managed namespace. RPA is NOT auto-created, NOT auto-generated. It's a manual step by platform team.
❌ WRONG: "I have 5 repos, so I need 5 Applications"
✅ CORRECT: If they deploy together, create 1 Application with 5 Components (one Component per repo).
❌ WRONG: "Use Application to build from my git repo"
✅ CORRECT: Use Component to build from git repo. Application just groups Components together.
❌ WRONG: "Use Component for my entire microservices system"
✅ CORRECT: Application = the system, Component = each microservice that builds separately.
❌ WRONG: Application contains git URL and builds code
✅ CORRECT: Component contains git URL and builds code. Application is just a logical grouping label.
Decision Tree: Which Resource Do I Need?
Q: "I need to build my app from a git repository"
A: Create a COMPONENT resource
- Exact resource name: "Component"
- API: appstudio.redhat.com/v1alpha1
- One Component per repo/branch you want to build
Q: "I have multiple repos that deploy together"
A: Create 1 APPLICATION + multiple COMPONENTs
- Application resource groups them
- One Component per repo
Q: "I want to run tests after builds"
A: Create INTEGRATIONTESTSCENARIO resource
- References a Tekton pipeline with your tests
Q: "I want to release a built snapshot"
A: Create RELEASE resource
- References existing Snapshot + ReleasePlan
Q: "I'm setting up a release pipeline"
A: Two resources needed:
- User creates: RELEASEPLAN in tenant namespace
- Platform Engineer creates: RELEASEPLANADMISSION in managed namespace
Q: "I need a snapshot of my builds"
A: DON'T CREATE MANUALLY
- Konflux auto-creates Snapshot resources after builds
- Just reference existing snapshots
Namespace Rules
Tenant Namespace (your workspace):
- Application ✓
- Component ✓
- Snapshot ✓ (auto-created)
- IntegrationTestScenario ✓
- ReleasePlan ✓
- Release ✓
- Build/test PipelineRuns ✓
Managed Namespace (restricted, controlled by platform team):
- ReleasePlanAdmission ✓ (created by Platform Engineer, NOT you)
- Release pipeline credentials ✓
- Release PipelineRuns ✓
Why this separation? Keeps release credentials isolated from dev teams while allowing devs to request releases.
CRITICAL for RP/RPA: ReleasePlan and ReleasePlanAdmission are in DIFFERENT namespaces. RP (tenant) references application. RPA (managed) references RP and contains credentials. They work together across namespace boundaries.
Resource Lifecycle: What Happens When You Push Code
Initial Setup (you do once):
- Create Application (groups your components)
- Create Component (points to git repo + branch)
- (Optional) Create IntegrationTestScenario (defines tests)
Every Code Push (Konflux automates):
- Build Service triggers PipelineRun (builds your component)
- PipelineRun creates OCI artifact (container image)
- Integration Service creates NEW Snapshot (references built artifacts)
- Integration Service runs IntegrationTestScenarios (if configured)
When Ready to Release:
- Create Release CR (references snapshot + release plan)
- Release Service executes release pipeline
You create: Application, Component, IntegrationTestScenario, Release
Konflux creates: Snapshot, PipelineRuns
Application vs Component
Think hierarchy:
Application (e.g., "E-commerce Platform")
├── Component: frontend-ui (built from repo A, main branch)
├── Component: backend-api (built from repo B, main branch)
├── Component: auth-service (built from repo C, main branch)
└── Component: payment-processor (built from repo D, v2 branch)
Application = logical grouping, deploy together
Component = buildable unit, one per git source
Real-World Examples
Example 1: Simple Web App
Scenario: One repo with frontend code
Resources:
- 1 Application: "my-web-app"
- 1 Component: "my-web-app-frontend" (points to repo main branch)
- Snapshots: Auto-created on every build
Example 2: Microservices (5 repos)
Scenario: frontend, backend, auth, data, queue repos that deploy together
Resources:
- 1 Application: "payment-system"
- 5 Components: (one per repo)
- payment-frontend
- payment-backend
- payment-auth
- payment-data
- payment-queue
- Snapshots: Auto-created after each component builds
Example 3: Security Scanning
Scenario: Run security scan after build
Resources:
- 1 IntegrationTestScenario: "security-scan"
- References Tekton pipeline that runs scanning tools
- Runs automatically on every new Snapshot
Example 4: Release Setup
Scenario: Release to production
In Tenant Namespace:
- ReleasePlan: "prod-release-plan"
- Points to Application
- References target workspace
In Managed Namespace (Platform Engineer creates):
- ReleasePlanAdmission: "prod-admission"
- Contains production credentials
- Defines release pipeline
To Release:
- Create Release CR in tenant namespace
- References specific Snapshot (auto-created earlier)
- References ReleasePlan
Common Mistakes
| Mistake | Why It Fails | Fix |
|---|
| Creating Snapshot manually | They're auto-created | Just reference existing snapshots |
| ReleasePlan in managed namespace | User can't create there | ReleasePlan in tenant, ReleasePlanAdmission in managed |
| One Component for multiple repos | Can't build from multiple sources | One Component per repo |
| Creating Application per service | Loses deployment grouping | One Application, multiple Components |
| IntegrationTestScenario in managed namespace | Tests run in tenant namespace | Put in tenant namespace |
Troubleshooting
"Snapshot not found"
- Snapshots are auto-created after builds complete
- Check PipelineRun succeeded first
- List snapshots:
kubectl get snapshots -n <tenant-namespace>
"ReleasePlan not found"
- Check you're in correct namespace (tenant, not managed)
- Verify ReleasePlan name matches what Release CR references
"No builds triggering"
- Component must exist BEFORE pushing code
- Check Component git URL and revision match your repo
- Verify webhook is configured (if using webhooks)
"Integration tests not running"
- IntegrationTestScenario must exist before build completes
- Check scenario references correct Application
- Verify Tekton pipeline referenced by scenario exists
Keywords for Search
Konflux resources, Custom Resource Definition, CRD, Application CR, Component CR, Snapshot lifecycle, IntegrationTestScenario, ReleasePlan, ReleasePlanAdmission, Release CR, tenant namespace, managed namespace, build pipeline, PipelineRun, Integration Service, Build Service, Release Service, Tekton pipeline, OCI artifact, container image, git repository, webhook, automatic build, snapshot creation, integration testing, release workflow, RP, RPA, ITS, App, Comp, shortname, abbreviation, acronym, ReleasePlan abbreviation, IntegrationTestScenario abbreviation, ReleasePlanAdmission abbreviation
