understanding-konflux-resources

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):

1. Create Application (groups your components)
2. Create Component (points to git repo + branch)
3. (Optional) Create IntegrationTestScenario (defines tests)

Every Code Push (Konflux automates):

1. Build Service triggers PipelineRun (builds your component)
2. PipelineRun creates OCI artifact (container image)
3. Integration Service creates NEW Snapshot (references built artifacts)
4. Integration Service runs IntegrationTestScenarios (if configured)

When Ready to Release:

1. Create Release CR (references snapshot + release plan)
2. 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