262 lines
11 KiB
Markdown
262 lines
11 KiB
Markdown
---
|
|
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):
|
|
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
|