![\"Mirrored](\"https://docs.kuberocketci.io/assets/images/gitlab-cicd-component-e6844f12e1f7b8c493f819b020300433.png\" "\\"The")
GitLab CI integration in KubeRocketCI lets a single application run its CI pipeline in GitLab CI - on a GitLab Runner - instead of Tekton, while still being managed as a first-class Codebase on the platform. You set one field on the Codebase (spec.ciTool: gitlab), and KubeRocketCI generates a .gitlab-ci.yml in the repository; GitLab then runs the pipeline, with no Tekton involved. From then on, every merge request runs a review pipeline and every merge runs a build pipeline - all native GitLab CI, all on your own cluster.
This is part three of my hands-on series on the local try-kuberocketci testbed. In part one I stood up the full platform in two commands; in part two I built ephemeral preview environments from a feature branch. Both ran their CI in Tekton. This post takes the same kind cluster running KubeRocketCI 3.13 and shows the multi-CI path: how GitLab CI integration works, the three things you must set up before you enable it - a Runner, the onboarded CI/CD components, and a ConfigMap - and a full review-to-build run with real output.
\nBy default, KubeRocketCI runs your CI in Tekton. Version 3.13 added multi-CI: a per-Codebase choice of engine, set with one field - spec.ciTool: tekton (the default) or spec.ciTool: gitlab (see the 3.13 notes and Codebase API). Choosing gitlab is what this post is about.
When you set ciTool: gitlab, KubeRocketCI handles the wiring. Instead of the Tekton EventListener and webhook it would normally create, it generates a .gitlab-ci.yml and commits it to the repository; GitLab CI then runs the pipeline. The file is generated rather than written by hand, and no Tekton is involved - the build runs as native GitLab CI jobs on a GitLab Runner, and the logs reside in GitLab.
Other aspects are unchanged: the application remains a first-class Codebase, with the same Portal, branches, and GitOps deployment as a Tekton application. GitLab-CI and Tekton applications can run side by side on the same platform; only the CI execution moves to GitLab (see the comparison below).
\n\nOn a real codebase the file lands in the repo, and there is no project webhook - GitLab CI does not need one:
\n$ kubectl -n krci get codebase java-gitlabci-app -o jsonpath='{.spec.ciTool}'
gitlab
# .gitlab-ci.yml is committed to the repo; project webhooks: 0
The generated .gitlab-ci.yml is intentionally minimal: it contains no build logic of its own and instead references reusable GitLab CI/CD components. Those components must be in place first.
GitLab CI integration has three prerequisites that the Tekton path does not - a one-time platform setup, not something you repeat per app. Skip any one and the first pipeline fails to start or cannot resolve its components; complete them once, and subsequent GitLab-CI Codebases require no additional setup.
\n\nTekton ships with KubeRocketCI; a GitLab Runner does not. GitLab CE already serves CI, but with no runner registered, jobs sit pending forever. On the testbed, make gitlab-ci installs the official gitlab/gitlab-runner Helm chart with the Kubernetes executor and registers it.
$ kubectl -n gitlab-runner get pods
NAME READY STATUS RESTARTS AGE
gitlab-runner-f655c776c-xr9cm 1/1 Running 0 26m
# the runner reports online as an instance runner
runner: krci-kubernetes online=True executor=kubernetes
The Kubernetes executor runs each job as a pod in the cluster - the same model Tekton uses, so your CI capacity scales with the cluster. The testbed uses Helm for simplicity, but on a real cluster you install the runner the GitOps way, like every other platform component: KubeRocketCI ships a gitlab-runner add-on in the edp-cluster-add-ons repository that Argo CD reconciles, with the runner's registration token supplied through External Secrets. Either way you end up with one registered runner, sized to your job volume, ready to execute GitLab CI jobs.
This prerequisite is easy to overlook. The injected .gitlab-ci.yml does not contain the build steps directly; it references a GitLab CI/CD component - the kuberocketci/ci-java17-mvn library, which exposes review and build entry points over a 7-stage flow (prepare → test → build → verify → package → publish → release).
The catch: GitLab CI/CD components only resolve on the same GitLab instance ($CI_SERVER_FQDN). A component reference like $CI_SERVER_FQDN/kuberocketci/ci-java17-mvn/build@0.1.1 will not reach out to gitlab.com - it resolves against your GitLab. So you must onboard (mirror) the components into your instance before enabling GitLab CI, and tag them at the version your template pins.
On the testbed, make gitlab-ci mirrors the component into the local GitLab as kuberocketci/ci-java17-mvn at tag 0.1.1 (with two local-only patches: native arm64 builds and pushing to the in-cluster GitLab Container Registry instead of Docker Hub). In your own environment, this is where you publish the KubeRocketCI components - or your own forked components - to your GitLab CI/CD Catalog so every project can include them.
If you set ciTool: gitlab before the component exists at the pinned tag on your instance, KubeRocketCI still injects .gitlab-ci.yml, but the very first pipeline fails at the include: stage with an unresolved-component error. Mirror and tag the components first.
.gitlab-ci.yml Template ConfigMapKubeRocketCI does not invent the pipeline - it fills in a template stored in a ConfigMap, one per tech stack. The Codebase points at the template with an annotation (or KubeRocketCI falls back to a gitlab-ci-{lang}-{buildtool} naming convention), and your codebase name is substituted in before the file is committed.
The ConfigMap for Java/Maven contains only orchestration - a workflow rule set, variables, and two included component entry points (review and build) gated by rules:
apiVersion: v1
kind: ConfigMap
metadata:
name: gitlab-ci-java-maven
namespace: krci
data:
.gitlab-ci.yml: |
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == \"merge_request_event\"
- if: $CI_COMMIT_REF_PROTECTED == \"true\"
- if: $CI_COMMIT_TAG =~ /^\\d+\\.\\d+\\.\\d+$/
variables:
CODEBASE_NAME: \"{{.CodebaseName}}\"
CONTAINER_IMAGE: \"maven:3.9-eclipse-temurin-17\"
IMAGE_REGISTRY: \"$CI_REGISTRY_IMAGE\"
CHART_DIR: \"deploy-templates\"
include:
# REVIEW - merge-request validation (test/build/lint/sonar/dockerbuild-verify; no push)
- component: $CI_SERVER_FQDN/kuberocketci/ci-java17-mvn/review@0.1.1
inputs: { codebase_name: ${CODEBASE_NAME}, container_image: ${CONTAINER_IMAGE}, chart_dir: ${CHART_DIR} }
rules:
- if: $CI_PIPELINE_SOURCE == \"merge_request_event\"
# BUILD - protected/default branch: build, push image, deploy/tag
- component: $CI_SERVER_FQDN/kuberocketci/ci-java17-mvn/build@0.1.1
inputs: { codebase_name: ${CODEBASE_NAME}, container_image: ${CONTAINER_IMAGE}, image_registry: ${IMAGE_REGISTRY}, chart_dir: ${CHART_DIR} }
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_REF_PROTECTED == \"true\"
stages: [prepare, test, build, verify, package, publish, release]
Apply it once:
\n$ kubectl apply -f manifests/gitlab-ci-java-maven-configmap.yaml
configmap/gitlab-ci-java-maven created
These two rules are the entire control flow: the review component runs on merge_request_event, and the build component runs on the protected/default branch. That split produces the \"MR → review, merge → build\" behavior, with no webhook required.
spec.ciTool: gitlab)With the Runner online, the components onboarded, and the ConfigMap applied, enabling GitLab CI is one Codebase manifest. The ciTool: gitlab field selects the engine; the annotation selects the template:
apiVersion: v2.edp.epam.com/v1
kind: Codebase
metadata:
name: java-gitlabci-app
namespace: krci
annotations:
app.edp.epam.com/gitlab-ci-template: gitlab-ci-java-maven # pick the ConfigMap
spec:
type: application
lang: java
framework: java17
buildTool: maven
ciTool: gitlab # <-- run CI in GitLab CI, not Tekton
strategy: import
gitServer: gitlab
gitUrlPath: /krci/java-gitlabci-app
disablePutDeployTemplates: true
In the KubeRocketCI Portal, the component is a normal Codebase - same lifecycle, same branches, same deployment story as a Tekton app - but its CI Tool reads GitLab. That is the platform side of the integration: you manage the app on KubeRocketCI, even though its pipeline executes in GitLab.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-gitlabci-codebase-c4310aba4c86c0678c7d73b96feb98bf.png\" "\\"The")
Once KubeRocketCI finishes, the injected .gitlab-ci.yml is visible in the GitLab project - the {{.CodebaseName}} placeholder now reads java-gitlabci-app, and the two component includes are wired and ready:
![\".gitlab-ci.yml](\"https://docs.kuberocketci.io/assets/images/gitlab-ci-yml-injected-16c88b282bd1324356c745c6b31a4a37.png\" "\\"The")
The flow mirrors the Tekton path from the previous posts - open a merge request to validate, merge to build and publish - but every job runs in GitLab CI on the Runner.
\n\nIn the GitLab project, both pipelines show green - one triggered by the merge request, one by the merge to main:
![\"GitLab](\"https://docs.kuberocketci.io/assets/images/gitlab-pipelines-list-8698eba9d2b379480a3057bbec373981.png\" "\\"Every")
Opening a merge request triggers a merge_request_event pipeline that runs the review component - validation only, no image push. On the live run it finished green in 91 seconds, 10 jobs across four stages:
review pipeline #4 (merge_request_event) - 91s - GREEN
prepare init-values
test test compile-check lint
test helm-docs helm-lint dockerfile-lint
build build sonar
verify dockerbuild-verify # buildkit builds the image but does NOT push
The sonar job is a real SonarQube quality gate - the same engine the Tekton pipelines use - and dockerbuild-verify proves the image builds without publishing it. GitLab renders the MR with its pipeline result attached:
![\"GitLab](\"https://docs.kuberocketci.io/assets/images/gitlab-merge-request-pipeline-20d220daf06a9e8c328e1d372469bf5f.png\" "\\"The")
Merging the MR pushes to the protected main branch, which trips the second workflow rule and runs the build component. It is the review jobs plus the publishing stages - buildkit-build (build and push), maven-deploy, and git-tag. On the live run it finished green in 100 seconds, 12 jobs:
build pipeline #5 (push, protected main) - 100s - GREEN
prepare init-values
test test compile-check lint
test helm-docs helm-lint dockerfile-lint
build build sonar
package buildkit-build maven-deploy # build+push image, publish artifact
publish git-tag # tag the release
The build pipeline graph in GitLab shows the stages fanning out - the same DAG model you get in Tekton, rendered by GitLab:
\n![\"GitLab](\"https://docs.kuberocketci.io/assets/images/gitlab-build-pipeline-graph-e8063702a5d0b1e6665e72c865ec7f45.png\" "\\"The")
The buildkit-build job builds the container image and pushes it to GitLab's bundled Container Registry using the CI job token - no external registry, no Docker Hub credentials. After the build pipeline, the image is published with a content-addressed tag, and git-tag has created the matching release tag:
# image published by the build pipeline
image: krci/java-gitlabci-app tags: [723b97d8, cee1e98e]
# release tags created by the git-tag job
tag: v0.1.0-cee1e98e
tag: v0.1.0-723b97d8
![\"GitLab](\"https://docs.kuberocketci.io/assets/images/gitlab-container-registry-f85c4c9627bfaf6ddfc5c607cf491511.png\" "\\"The")
From here, the GitOps delivery story is identical to the Tekton path - the published image feeds the same CodebaseImageStream and Argo CD deployment flow covered in part two of this series.
\nBoth engines are first-class. The choice is about where your team already lives and what you want to own.
\n| Dimension | Tekton (default) | GitLab CI (ciTool: gitlab) |
|---|---|---|
| Pipeline definition | Tekton PipelineRun (KRCI-managed) | .gitlab-ci.yml (operator-injected, GitLab-native) |
| Trigger mechanism | Tekton webhook | GitLab workflow rules (no webhook) |
| Where job logs live | KubeRocketCI Portal / Tekton | GitLab CI UI |
| Reusable build logic | Tekton tasks / pipeline library | GitLab CI/CD components (must be on your instance) |
| Image build | kaniko | buildkit |
| Runner needed | No (Tekton bundled) | Yes - install a GitLab Runner |
| Best when | you want a unified, K8s-native CI surface in the Portal | your org standardizes on GitLab CI and its component catalog |
Use Tekton when you want every Codebase to share one Kubernetes-native CI surface inside the Portal, with pipeline history in Tekton Results. Use GitLab CI when your organization has standardized on GitLab CI/CD components and wants pipeline authoring and logs to stay in GitLab - while still getting the KubeRocketCI Codebase lifecycle, Portal, and GitOps deployment around them. And because the choice is per-Codebase, you can migrate one application at a time.
\nciTool: gitlab do in KubeRocketCI?It switches a Codebase's CI engine from Tekton to GitLab CI. Instead of wiring the pipeline into Tekton, KubeRocketCI generates a .gitlab-ci.yml in the repository, and the pipeline runs as native GitLab CI jobs on a GitLab Runner. The only valid values for the field are tekton and gitlab.
It runs on top of it. With GitLab CI integration, KubeRocketCI manages the Codebase lifecycle, owns the injected .gitlab-ci.yml, and provides the Portal and GitOps deployment - but the pipeline itself executes in GitLab CI, and the job logs live in GitLab. There is no Tekton in the pipeline path at all.
Yes. KubeRocketCI bundles Tekton but not a GitLab Runner. With ciTool: gitlab, jobs run as GitLab CI and need a registered runner to execute. The testbed installs the official gitlab/gitlab-runner Helm chart with the Kubernetes executor, registered via a GitLab 17.x runner authentication token. Without a runner, pipelines stay pending.
Because GitLab CI/CD components only resolve on the same instance ($CI_SERVER_FQDN). A reference like $CI_SERVER_FQDN/kuberocketci/ci-java17-mvn/build@0.1.1 is looked up on your GitLab, not gitlab.com. So you must mirror (onboard) the KubeRocketCI components - or your own forks - into your instance and tag them at the version your template pins, before enabling GitLab CI on any Codebase.
The ConfigMap holds the .gitlab-ci.yml template that KubeRocketCI injects. You create one per tech stack (for example gitlab-ci-java-maven), and the Codebase points at it with an annotation. KubeRocketCI substitutes your codebase name and commits the result. The template is thin orchestration - it includes the onboarded CI/CD components and gates them with workflow rules.
GitLab CI integration relies on GitLab's own workflow rules instead of a webhook. The injected .gitlab-ci.yml includes the review component gated on $CI_PIPELINE_SOURCE == \"merge_request_event\" and the build component gated on the protected/default branch. Opening a merge request runs review; merging pushes to the protected branch and runs build. GitLab triggers both natively, so no project webhook is created.
Yes. The choice is per-Codebase, and the same gitlab GitServer is reused for both engines. On the testbed, Tekton codebases (the Go app from parts one and two) run side by side with the GitLab-CI Java app on the same KubeRocketCI platform. You can adopt GitLab CI for one application without touching the rest.
The buildkit-build job builds and pushes the image to GitLab's bundled Container Registry using the CI job token - no external registry or Docker Hub credentials required. On the testbed it pushes to the in-cluster GitLab registry, and the git-tag job creates a matching release tag. From there the image feeds the same CodebaseImageStream and Argo CD deployment flow as the Tekton path.
GitLab CI integration in KubeRocketCI lets a Codebase run its pipeline in GitLab CI instead of Tekton by setting spec.ciTool: gitlab. KubeRocketCI then generates a .gitlab-ci.yml that pulls in reusable GitLab CI/CD components, gated so that a merge request runs a review pipeline and a merge runs a build pipeline. There is no webhook and no Tekton in the path - the proof is zero PipelineRuns for the Codebase.
Before you enable it, set up three things: a GitLab Runner (KubeRocketCI does not bundle one), the onboarded CI/CD components in your own instance (they only resolve on the same GitLab), and the template ConfigMap KubeRocketCI injects. Complete these once, and subsequent GitLab-CI Codebases require no additional setup.
\nI ran the full flow on the local try-kuberocketci testbed: review pipeline green in 91s (10 jobs), build pipeline green in 100s (12 jobs), image pushed to GitLab's Container Registry, release tags created, and zero Tekton PipelineRuns - every command and result above is from that run.
\nThe most useful next steps from here:
\nmake gitlab-ci and make e2e-gitlabci to reproduce this flow.ciTool enum and the Codebase API for the field reference.KubeRocketCI is open source under Apache License 2.0. The platform, Helm charts, and the testbed are all on GitHub.
\n", "url": "https://docs.kuberocketci.io/blog/gitlab-ci-integration-kuberocketci", "title": "GitLab CI Integration in KubeRocketCI", "summary": "How KubeRocketCI runs CI in GitLab CI instead of Tekton: onboard the CI/CD components, create the ConfigMap, add a Runner. A hands-on multi-CI walkthrough.", "date_modified": "2026-06-08T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "GitLab CI", "CI/CD", "Tekton", "Kubernetes", "GitLab Runner", "Multi-CI", "GitOps", "Platform Engineering", "DevOps", "Open Source" ] }, { "id": "https://docs.kuberocketci.io/blog/ephemeral-preview-environments-kubernetes-feature-branch", "content_html": "An ephemeral preview environment is an isolated, temporary Kubernetes deployment created from a single feature branch and torn down when the work is done. Every branch gets its own namespace, its own image, its own URL - and zero of it lingers afterward. Ephemeral environments on Kubernetes make this pattern available on your own cluster - but a hands-on, open-source, portal-native version - feature branch to isolated namespace to one-click destroy, backed by real Tekton CI and Argo CD GitOps - is conspicuously missing from the public record.
\nSo I built one, end to end, on the same local try-kuberocketci testbed from my last post: a kind cluster running KubeRocketCI 3.13.5 with Tekton, Argo CD, and self-hosted GitLab. This post is the full walkthrough - every screenshot, every line of terminal output, captured from a live run. We will take a stable main deployment, branch off it, ship a change that is visible only in the preview environment, inject per-environment config through GitOps, prove the two environments never touch each other, and then destroy the whole thing - leaving the baseline exactly as it was.
An ephemeral preview environment is a short-lived, namespace-isolated copy of your application, provisioned automatically from a feature branch or pull request and destroyed when that branch merges or is no longer needed. Unlike a shared staging environment - where one branch at a time monopolizes the slot - a preview environment is dedicated to a single branch, carries no long-term state, and releases its resources (namespace, pods, ingress) the moment you tear it down.
\nThe terms preview environment and ephemeral environment are used interchangeably. \"Preview\" emphasizes the use case (review a branch before merge); \"ephemeral\" emphasizes the lifecycle (temporary by design). In KubeRocketCI they are the same object: a Deployment Stage with its own isolated Kubernetes namespace, created for a branch and removed on demand.
\nA preview environment lifecycle has five stages:
\n\nA shared staging environment serializes your team: only one branch can occupy it at a time, so parallel feature work cannot be validated simultaneously, and \"who broke staging?\" becomes a recurring standup question. Ephemeral preview environments give every branch its own namespace, so several features can be tested concurrently without interfering - and when a branch merges, its namespace is deleted, so there is no idle staging box quietly accruing cost.
\nThat last point matters more than it looks. Industry surveys consistently find a large share of provisioned Kubernetes capacity sits idle, and the trend is getting worse - CAST AI's 2026 State of Kubernetes Optimization Report measured average CPU utilization at just 8% across roughly 23,000 production clusters (down from 10% a year earlier), and Flexera's 2026 State of the Cloud report pegs self-estimated cloud waste at ~29%, its first rise in five years. Permanent staging environments are a textbook source of that waste. An environment that deletes itself cannot become idle.
\nThere are three common isolation models. Namespace-per-branch reuses one shared control plane, provisions in seconds, and is sufficient for most teams - it is the model used here. vCluster adds a lightweight virtual API server per environment for stronger isolation at higher overhead. A dedicated cluster per branch is maximum isolation but impractical at scale. KubeRocketCI uses namespace-per-branch, with Argo CD managing each namespace's application manifests.
\nA separate namespace scopes names, RBAC, and quotas - but by default pods in different namespaces can still reach each other over the cluster network. If your preview environments need network isolation too, add NetworkPolicy rules; the namespace boundary alone does not provide them.
Before the walkthrough, a quick map of the moving parts. KubeRocketCI wraps a few core concepts that turn a Git branch into a running environment:
\ntest-go-app) and a branch within it (feature-tt-123). Creating a branch in the Portal creates the CodebaseBranch resource and mirrors the branch into Git.Manual, Auto, or Auto-stable. We use Auto: the environment redeploys whenever a new image tag lands in the CBIS, so the preview env always tracks the branch head with no manual step. (See Deployment Strategies.)Here is the full path from a feature-branch build to a live, isolated workload:
\n\nThe crucial detail is the CBIS handoff: Tekton writes the image tag after the image is actually pushed, and the Auto trigger only fires once that tag exists. The image is therefore guaranteed to be present before Argo CD tries to deploy it - which avoids the ImagePullBackOff race that bare deploy-only tooling is prone to.
The starting point is the end state of the previous post: the sample Go/Gin app test-go-app built from main and deployed by the demo Deployment into namespace krci-demo-dev.
$ kubectl get applications -n krci
NAMESPACE NAME SYNC STATUS HEALTH STATUS
krci demo-dev-test-go-app Synced Healthy
$ kubectl -n krci-demo-dev get deploy test-go-app -o jsonpath='{.spec.template.spec.containers[0].image}'
gitlab.127.0.0.1.nip.io:5050/krci/test-go-app:main-20260606-132413@sha256:a39d120b...
One property of main matters for the rest of this post: the Gin app only handles /hello, so the root path returns 404. That 404 is our control - the feature environment will return 200 on the same path, and main will keep returning 404 the entire time.
# main, GET / (no root handler on main)
$ curl -s -o /dev/null -w \"%{http_code}\\n\" http://localhost:18080/
404
In the test-go-app component, Branches → Create branch. I name it feature-tt-123, leave From as main, and keep the default review and build pipelines.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/create-feature-branch-00bc67a73a38bf09854d5840af4df5cd.png\" "\\"Creating")
Clicking Create provisions a CodebaseBranch resource and mirrors the branch into GitLab with an (initially empty) CodebaseImageStream:
$ kubectl -n krci get codebasebranch,codebaseimagestream | grep feature
codebasebranch.v2.edp.epam.com/test-go-app-feature-tt-123-0afaf created feature-tt-123
codebaseimagestream.v2.edp.epam.com/test-go-app-feature-tt-123-0afaf test-go-app
To prove isolation, the feature branch needs to behave differently from main. I add a root / handler that returns 200 and echoes a NAME environment variable (we will set that variable per-environment in Step 7), plus the Helm extraEnv plumbing the override needs. The whole change is 30 lines across four files:
\tr := gin.Default()
\tr.GET(\"/\", func(c *gin.Context) {
\t\tc.JSON(http.StatusOK, gin.H{
\t\t\t\"status\": \"ok\",
\t\t\t\"name\": os.Getenv(\"NAME\"),
\t\t})
\t})
\tr.GET(\"/hello\", func(c *gin.Context) {
ports:
- name: http
containerPort: {{ .Values.service.port }}
protocol: TCP
{{- if .Values.extraEnv }}
env:
{{- toYaml .Values.extraEnv | nindent 12 }}
{{- end }}
The default extraEnv: {} goes into values.yaml, and a matching unit test goes into main_test.go. Crucially, this change lives only on feature-tt-123 - main is never touched.
Feature branches are built on demand: on the Branches tab, the feature-tt-123 row has a Build button. One click starts the gitlab-go-gin-app-build-default pipeline.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/branches-after-build-22fd7a4fdd36af6ff78822f83d95906d.png\" "\\"The")
The build is the familiar Tekton DAG - fetch, version, SonarQube quality gate, kaniko image build, Git tag, and the all-important update-cbis step that records the new tag:
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/build-pipeline-dag-d156ccdec2c671b2677d20d6a5f42fba.png\" "\\"The")
$ kubectl -n krci get pipelinerun | grep build-test-go-app-feature-tt-123-0afaf
build-test-go-app-feature-tt-123-0afaf-2d31 True Completed
With default versioning, the tag is BRANCH-DATETIME. The build writes it to the CBIS:
$ kubectl -n krci get codebaseimagestream test-go-app-feature-tt-123-0afaf \\
-o jsonpath='{.spec.tags[*].name}'
feature-tt-123-20260607-060023
Now the environment. I follow the recommended convention of naming the deployment flow after my initials - sk - so personal preview flows are easy to find. In Deployments → Create Deployment, I select test-go-app and set its branch to feature-tt-123.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/deployment-select-app-branch-502793ac9daabd5688071b9972fefe07.png\" "\\"Selecting")
Then I add an environment named feat with trigger type Auto:
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/environment-auto-trigger-5c5b4469b3a340617e1f085efeb91947.png\" "\\"Choosing")
The namespace is derived as krci-<deployment>-<environment>, which the form pre-fills as krci-sk-feat. The environment overview confirms the wiring - Auto trigger, in-cluster, namespace krci-sk-feat, deploy and clean pipeline templates, quality gate Manual:
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/environment-overview-bbd920cac803ae968d81272ec78b72e8.png\" "\\"The")
Creating the environment before the next build is deliberate: with Auto, the deploy fires on a CBIS update. Arm the environment first, and the build that follows will deploy itself.
\nTriggering one more build updates the CBIS, the Auto trigger fires, and the cd-pipeline-operator creates the deploy run - no clicks. The deploy pipeline runs its four tasks and goes green in 47 seconds:
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/auto-deploy-pipeline-dag-a768a78478d4c919398659821c302a91.png\" "\\"The")
The whole preview environment now shows in one card - the feat Stage, its namespace, the deploy/clean pipelines, and the application Healthy + Synced on the feature tag:
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/preview-environment-card-12aac7b16d3c267ffdd789a543caa297.png\" "\\"The")
The cluster agrees:
\n$ kubectl -n krci get pipelinerun | grep sk-feat
deploy-sk-feat-pjsxx True Succeeded
$ kubectl get applications -n krci
NAMESPACE NAME SYNC STATUS HEALTH STATUS
krci demo-dev-test-go-app Synced Healthy # main, untouched
krci sk-feat-test-go-app Synced Healthy # the new preview env
$ kubectl -n krci-sk-feat get deploy,pods
NAME READY UP-TO-DATE AVAILABLE
deployment.apps/test-go-app 1/1 1 1
NAME READY STATUS
pod/test-go-app-666f6c6994-rltdl 1/1 Running
This is the part no one publishes with real output. Two namespaces, two image tags, two versions of the code, running side by side on the same cluster:
\n$ kubectl -n krci-demo-dev get deploy test-go-app -o jsonpath='{..image}'
...test-go-app:main-20260606-132413@sha256:a39d120b... # main
$ kubectl -n krci-sk-feat get deploy test-go-app -o jsonpath='{..image}'
...test-go-app:feature-tt-123-20260607-060023@sha256:812a57de... # feature
And the behavioral proof - same path, two answers:
\n# feature env (krci-sk-feat) -> GET /
HTTP/1.1 200 OK
{\"name\":\"\",\"status\":\"ok\"}
# main env (krci-demo-dev) -> GET /
HTTP/1.1 404 Not Found
# sanity: both still serve /hello
feature /hello -> 200 {\"message\":\"Hello, World!\"}
main /hello -> 200 {\"message\":\"Hello, World!\"}
The feature branch's new code is live in krci-sk-feat and answers 200. The exact same request to main in krci-demo-dev still returns 404. Nothing on main changed. That is the entire promise of a preview environment, demonstrated rather than asserted.
Preview environments usually need their own configuration - a different feature flag, API endpoint, or, here, a NAME variable. The GitOps way to do this is a values file in the GitOps repository at the path <deployment>/<environment>/<application>-values.yaml, with Values override enabled for the environment.
extraEnv:
- name: NAME
value: \"Hello from the sk/feat preview environment\"
On the environment's Applications tab, I open Configure Deploy, flip the per-app Values override toggle, and Start Deploy:
\n![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/values-override-enabled-a20c53cc852ac95f50839f30c4197b45.png\" "\\"Enabling")
$ kubectl -n krci get pipelinerun | grep sk-feat
deploy-sk-feat-pjsxx True Succeeded
deploy-sk-feat-ec0e True Succeeded
KubeRocketCI pulls the values file from the GitOps repo and applies it to the Argo CD Application at sync time - no image rebuild required. The pod picks up the variable, and because our root handler echoes it, the override is now visible over HTTP too:
\n$ kubectl -n krci-sk-feat exec deploy/test-go-app -- env | grep ^NAME=
NAME=Hello from the sk/feat preview environment
# feature env GET / (now reflects the per-environment value)
{\"name\":\"Hello from the sk/feat preview environment\",\"status\":\"ok\"}
# main pod has no such variable
$ kubectl -n krci-demo-dev exec deploy/test-go-app -- env | grep ^NAME=
(no output)
Teardown is a first-class action, not a side effect of closing a PR. On the deployment, Actions → Delete asks me to type the name to confirm:
\n![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/destroy-environment-confirm-469453922b282df210d0298292b2b6aa.png\" "\\"Destroying")
The cd-pipeline-operator deletes the namespace and its Argo CD Application. In about 5 seconds the preview environment is gone - and the main baseline is exactly as it was:
$ kubectl get ns krci-sk-feat
Error from server (NotFound): namespaces \"krci-sk-feat\" not found
$ kubectl get applications -n krci
NAMESPACE NAME SYNC STATUS HEALTH STATUS
krci demo-dev-test-go-app Synced Healthy # baseline intact
$ kubectl -n krci-demo-dev get deploy test-go-app
NAME READY UP-TO-DATE AVAILABLE
test-go-app 1/1 1 1
One thing to know: destroying the Stage does not delete the branch.
\n$ kubectl -n krci get codebasebranch | grep feature
test-go-app-feature-tt-123-0afaf created feature-tt-123 # still here
The Stage, the CodebaseBranch, the Git branch, and the GitOps values file are independent lifecycle objects. To fully clean up after a feature, delete the branch on the Branches tab and remove the <deployment>/<environment>/ entry from the GitOps repo. That independence is a feature: you can spin a preview environment up and down repeatedly for the same branch without ever touching Git history.
| Capability | KubeRocketCI | Argo CD ApplicationSet (PR generator) | Uffizzi | Okteto / Qovery / Vercel (SaaS) |
|---|---|---|---|---|
| License | Apache-2.0 | Apache-2.0 | Proprietary (SaaS only since 2024) | Proprietary / freemium |
| Self-hosted | Yes | Yes | No | Control plane is SaaS |
| Builds the image | Yes (Tekton) | No - deploy only | Yes | Yes |
| GitOps CD | Yes (Argo CD) | Yes (Argo CD) | No (Compose/Helm) | Varies |
| Developer Portal UI | Yes | No (YAML) | Limited | Yes |
| Per-branch namespace | Yes | Yes | Yes | Yes |
| Per-env values override | Yes (GitOps) | Manual | Limited | Yes |
| One-click destroy | Yes | Manual | Yes | Yes |
| Cost per environment | Compute only | Compute only | Compute only | Per-env / per-seat fees |
The Argo CD ApplicationSet Pull Request generator is the closest pure-OSS pattern, and it is genuinely useful - it watches open PRs and creates an Argo CD Application for each. But it is a deployment tool only: it does not build container images. The CI pipeline must build and push the tagged image first, and if the ApplicationSet reconciles before the image exists, the pods hit ImagePullBackOff. KubeRocketCI sidesteps that ordering problem with the CodebaseImageStream handoff described earlier - Tekton writes the tag, and the Auto trigger only fires once it is there. You also get a Portal, a Build button, and a Destroy button instead of hand-written ApplicationSet YAML.
Vercel and Netlify nail preview deployments for frontend/static workloads, and Qovery/Okteto/Bunnyshell offer polished managed experiences - but they put a SaaS control plane (and a per-environment or per-seat bill) between you and your cluster. Demand is real, but the tooling still frustrates teams: in Port's 2025 State of Internal Developer Portals survey, just 6% of developers were satisfied with the self-service tooling they use to spin up environments on demand. The open question that leaves is how to get that developer experience on your own cluster, with no SaaS bill - exactly the gap an Apache-2.0 IDP like KubeRocketCI fills.
\nThey are used interchangeably. \"Preview environment\" emphasizes the use case - reviewing a feature branch before merge - while \"ephemeral environment\" emphasizes the lifecycle: it is temporary and torn down when done. In KubeRocketCI both refer to the same object: a Deployment Stage with its own isolated Kubernetes namespace, created for a branch and destroyed on demand.
\nNo. KubeRocketCI is Apache-2.0 open source and runs entirely on your own cluster - kind locally, or EKS/GKE/AKS in production. There is no per-environment fee and no SaaS control plane. You bring the cluster; KRCI provides the Portal, CI (Tekton), and GitOps CD (Argo CD) to manage the full preview-environment lifecycle.
\nNot for the day-to-day flow. Creating a branch, building it, and deploying to an isolated namespace are all Portal form actions. The only YAML you write is the optional per-environment values file in the GitOps repo - and only when you actually need to override a value for a specific preview. The CDPipeline and Argo CD Application resources are managed by KRCI operators.
\nYou add a file at <deployment>/<environment>/<application>-values.yaml in the GitOps repository - for example sk/feat/test-go-app-values.yaml - containing Helm values that override the application's defaults. Enable the Values override toggle on the environment, then deploy. KubeRocketCI applies those values to the Argo CD Application at sync time, so the pod reflects them without rebuilding the image.
The cd-pipeline-operator deletes the Kubernetes namespace and the associated Argo CD Application - all pods, services, and configmaps in that namespace are removed. The CodebaseBranch and the Git branch are separate objects, so destroying the Stage does not delete or merge the branch; clean those up separately if you want to.
No. It is a deployment tool that watches open pull requests and creates Argo CD Applications for them. Your CI pipeline (Tekton, GitHub Actions, GitLab CI) must build and push the image first. If the ApplicationSet fires before the image is ready, pods hit ImagePullBackOff. KubeRocketCI avoids this with the CodebaseImageStream handoff: Tekton writes the tag, and the Auto trigger deploys only after it exists.
The software cost is zero - KubeRocketCI is Apache-2.0 with no per-environment fee. The only cost is the compute the environment consumes while it runs, and because preview environments are destroyed when the branch work is done, they do not accumulate idle compute the way permanent staging environments do. On the local kind testbed in this post, the preview environment cost nothing beyond the Docker Desktop resources already allocated.
\nStarting from a stable main deployment, we created a feature branch in the Portal, shipped a change visible only on that branch, built it through Tekton, and let an Auto environment deploy it to its own isolated namespace through Argo CD GitOps. We proved the isolation with real output - feature returns 200, main keeps returning 404 - injected per-environment config through a GitOps values override, and then destroyed the environment in one action, leaving the baseline untouched and zero residual cost behind.
No SaaS bill, no hand-written ApplicationSet YAML, no kubectl required for the happy path - just a feature branch, a few portal clicks, and a real isolated Kubernetes environment that cleans up after itself. The pattern - feature branch deployment on Kubernetes with isolated namespaces - is entirely self-hosted and free. I ran the entire flow on June 7, 2026 on the local try-kuberocketci testbed; every screenshot and command output above is from that run.
The most useful next steps from here:
\nKubeRocketCI is open source under Apache License 2.0. The platform, Helm charts, and the testbed are all on GitHub.
\n", "url": "https://docs.kuberocketci.io/blog/ephemeral-preview-environments-kubernetes-feature-branch", "title": "Ephemeral Environments on Kubernetes: Feature Branch Preview Walkthrough", "summary": "Spin up isolated ephemeral preview environments on Kubernetes from a feature branch with KubeRocketCI, Tekton, and Argo CD. Open source, no SaaS bill.", "date_modified": "2026-06-07T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "Preview Environments", "Ephemeral Environments", "GitOps", "Argo CD", "Tekton", "Kubernetes", "Feature Branch", "CD", "Platform Engineering", "CI/CD", "Open Source" ] }, { "id": "https://docs.kuberocketci.io/blog/try-kuberocketci-locally", "content_html": "Evaluating an internal developer platform without a working instance is like buying a car from a brochure. Every KubeRocketCI install path in the official docs assumes a cluster you already have - AWS EKS, GKE, an on-prem control plane. Today I ran the try-kuberocketci testbed end-to-end on my Apple Silicon Mac using Docker Desktop and two commands: make testbed (approximately 18–20 minutes) and make e2e (approximately 12 minutes). The result is a fully wired KubeRocketCI local install - Tekton, Argo CD, SonarQube, self-hosted GitLab CE, Prometheus, Grafana, Tekton Results, and the Portal - running in a disposable kind cluster. No cloud account. No /etc/hosts edits. No clicking through UIs to trigger pipelines. This post walks through exactly what happened, command by command, screenshot by screenshot.
KubeRocketCI (KRCI) is an open-source, Kubernetes-native internal developer platform for cloud-native CI/CD, developed and maintained under Apache 2.0. It assembles Tekton, Argo CD, SonarQube, and your Git provider into a cohesive, opinionated developer experience - managing the lifecycle of your Codebases (applications, libraries, autotests) from source through review, build, and GitOps-based deployment, exposed through a single Portal UI.
\nKubeRocketCI markets itself as cutting time-from-project-initiation-to-active-development from days to hours. The testbed lets you verify that claim in 30 minutes on a laptop. On our own dogfooding cluster over a recent 90-day window, the platform logged 18,397 pipeline runs with a 93% build success rate - and it runs the same Tekton pipeline stack you are about to stand up locally.
\nThis repository is not KubeRocketCI itself - it is a local installer and test harness that brings the whole platform up on your machine, ready for evaluation, development, and demo preparation.
\nTo run a KubeRocketCI Docker Desktop setup, you need only Docker Desktop - no cloud account, no pre-existing Kubernetes cluster, and no registry account are required.
\n| Requirement | Minimum | Recommended | Notes |
|---|---|---|---|
| Docker Desktop | 4.x+ | Latest | Allocate RAM in Docker Settings → Resources |
| RAM allocation | 8 GB (core only) | 12 GB+ | Full bed with GitLab + SonarQube needs 12 GB+ |
| Disk space | ~20 GB free | ~30 GB | Container images and volumes |
| OS | macOS, Linux, WSL2 | macOS/Linux | Windows via WSL2 supported |
| Apple Silicon | Supported | - | amd64 images run via Docker Desktop Rosetta 2 |
make | Any version | - | Pre-installed on macOS/Linux |
kind, helm, kubectl | Latest stable | - | make tools installs kind via Homebrew |
| Internet access | Required | - | Images pulled from public registries during install |
Docker Desktop with at least 12 GB of RAM allocated is required for the full bed. Below this threshold, GitLab CE or SonarQube will OOM-kill during startup. My live run used ~11.7 GB allocated to the Docker engine - right at the edge, and it completed successfully, but the README's 12 GB+ recommendation is well-founded. Check Docker Settings → Resources → Memory before running make testbed.
On Apple Silicon (M1/M2/M3), Docker Desktop's Rosetta 2 emulation runs the amd64-only images (Portal, GitLab, sonar-operator) transparently. No configuration changes are needed in the testbed - it just works.
\nThe fastest way to try KubeRocketCI locally is two commands on Docker Desktop. The try-kuberocketci testbed spins up a KubeRocketCI kind cluster with the full CI/CD platform - including Tekton, Argo CD, Prometheus/Grafana, Tekton Results, SonarQube, and a self-hosted GitLab CE - in two commands: make testbed (approximately 18–20 minutes) and make e2e (approximately 12 minutes). All versions are pinned through the edp-cluster-add-ons GitOps repository - the same source of truth used in production KubeRocketCI deployments - making the local testbed a faithful reproduction of a real cluster rather than a stripped-down demo.
| Step | Layer | Component | Version | Namespace |
|---|---|---|---|---|
| 1 | Cluster | kind (Kubernetes-in-Docker) | v1.36.1 (kind default; node image not pinned) | - |
| 2 | Ingress | ingress-nginx | controller-v1.11.3 | ingress-nginx |
| 3 | Certs | cert-manager | v1.16.2 | cert-manager |
| 4 | CI engine | Tekton Pipelines / Triggers | v1.6.0 / v0.34.0 | tekton-pipelines |
| 5 | CD engine | Argo CD | chart 9.5.17 | argocd |
| 6 | Observability | kube-prometheus-stack + Grafana | 84.5.0 | monitoring |
| 7 | Run storage | Tekton Results | v0.17.2 | tekton-pipelines |
| 8 | Code quality | SonarQube Community + sonar-operator 3.3.0 | 2025.3.1 (chart) / 25.5-community | sonar |
| 9 | SCM + Registry | GitLab CE + bundled Container Registry | 17.5.1-ce | gitlab |
| 10 | Platform | KubeRocketCI (edp-install) | 3.13.5 | krci |
Why is KubeRocketCI installed last? The edp-install chart renders provider resources - the GitServer CRD, EventListener, Ingress rules - at install time. If GitLab or Argo CD is not already running when the chart applies, the operator's SSH connection check fails and the platform never reaches a healthy state. Installing KubeRocketCI last, after every dependency is ready, is what makes the chart wire itself correctly on first reconcile.
\ngit clone https://github.com/KubeRocketCI/try-kuberocketci
cd try-kuberocketci
make testbed # ~18-20 min
That is the entire KubeRocketCI local install. One clone, one command.
\nBefore running make testbed, open Docker Desktop → Settings → Resources and verify the memory slider is set to 12 GB or higher. This is the single most common reason the install fails, and it takes 30 seconds to check.
make testbed builds in strict dependency order, installing KubeRocketCI last. The sequence:
GitLab CE is the slowest component to initialize - plan for it to take several minutes of the total. Once make testbed completes, run make status to see the live cluster state and print all service URLs with credentials:
NAME STATUS ROLES AGE VERSION
krci-control-plane Ready control-plane 13m v1.36.1
--- krci pods ---
NAME READY STATUS RESTARTS AGE
cd-pipeline-operator-57b96f56ff-x7nlw 1/1 Running 0 84s
codebase-operator-68b7599446-h8cn7 1/1 Running 0 41s
el-edp-gitlab-6cfc7857d9-fnxxd 1/1 Running 0 84s
gitfusion-86cb475dc9-mdbgb 1/1 Running 0 84s
krci-portal-65956587d5-6tvtf 1/1 Running 0 31s
tekton-cache-89846975f-86fx8 1/1 Running 0 84s
tekton-interceptor-6c68789887-88z86 1/1 Running 0 84s
...
================ Tool URLs & credentials (local only) ================
Argo CD UI: http://argocd.127.0.0.1.nip.io
SonarQube UI: http://sonar.127.0.0.1.nip.io
GitLab UI: https://gitlab.127.0.0.1.nip.io
Results API: http://tekton-results.127.0.0.1.nip.io
Grafana UI: http://grafana.127.0.0.1.nip.io
Portal UI: https://portal.127.0.0.1.nip.io
All six services are immediately reachable in a browser. No /etc/hosts edits - I will explain why in the next section.
The try-kuberocketci testbed uses nip.io wildcard DNS so every platform service gets a stable, browser-accessible URL - no /etc/hosts edits, no port-forwards, no local DNS configuration required. Any subdomain of <IP>.nip.io resolves to <IP> via a public DNS server; the testbed generates all ingress hostnames in the *.127.0.0.1.nip.io pattern, so every service is immediately reachable from your browser with zero local DNS configuration.
Every competing local Kubernetes tutorial either requires manual /etc/hosts edits to map ingress hostnames to 127.0.0.1, or skips DNS entirely and uses port-forwards. For a KubeRocketCI Docker Desktop setup that serves six platform UIs simultaneously, manual host-file management would be a non-starter - nip.io eliminates the entire problem class.
| Service | URL |
|---|---|
| KubeRocketCI Portal | https://portal.127.0.0.1.nip.io |
| Argo CD | http://argocd.127.0.0.1.nip.io |
| GitLab CE | https://gitlab.127.0.0.1.nip.io |
| SonarQube | http://sonar.127.0.0.1.nip.io |
| Grafana | http://grafana.127.0.0.1.nip.io |
| Tekton Results API | http://tekton-results.127.0.0.1.nip.io |
The DNS trick works for your browser on the host. Inside the cluster, pods resolve gitlab.127.0.0.1.nip.io to the in-cluster GitLab Service via CoreDNS rewrites, and the kind node's containerd uses a registry mirror config to pull images from GitLab's bundled registry. This split-horizon DNS design is one of the more interesting pieces of the testbed architecture - the full walkthrough is in docs/architecture.md.
make e2e # ~12 min
make e2e Run the Full CI/CD Pipeline Automatically?make e2e automates the complete CI/CD cycle - opening a GitLab Merge Request, triggering a Tekton review pipeline, merging the MR, building and pushing a container image with kaniko to GitLab's bundled registry, and asserting the Go/Gin sample application is live via Argo CD sync - in approximately 12 minutes with zero UI clicks.
Here is the verbatim output from my run today:
\n==> Applying the sample Codebase (test-go-app)
==> Waiting for the Codebase to be provisioned in GitLab (project + template push)
==> Waiting for the codebase-operator to create the project webhook
==> Waiting for the CodebaseImageStream test-go-app-main to exist
==> Creating the demo CDPipeline + dev Stage (triggerType: Auto)
==> Opening a merge request (branch ci-e2e-...) to trigger the review pipeline
merge request !1 opened
==> Waiting for the webhook to create the review PipelineRun(s)
triggered: pipelinerun.tekton.dev/review-test-go-app-main-2g7kd
==> Evaluating per-task results (review)
review-test-go-app-main-2g7kd -> ALL_GREEN
==> Merging merge request !1 (action=merge fires the build trigger)
merge request !1 merged
==> Waiting for the build run(s) to finish (kaniko build+push can take several minutes)
==> Evaluating per-task results (build)
build-test-go-app-main-m8kpm -> ALL_GREEN
==> Reading the built image tag from CodebaseImageStream test-go-app-main
built tag: main-20260606-132413
==> Waiting for the Auto trigger to deploy tag main-20260606-132413
triggered: pipelinerun.tekton.dev/deploy-demo-dev-kkmqg
==> Evaluating per-task results (deploy)
deploy-demo-dev-kkmqg -> ALL_GREEN
==> Verifying the application is deployed in krci-demo-dev on tag main-20260606-132413
OK test-go-app gitlab.127.0.0.1.nip.io:5050/krci/test-go-app:main-20260606-132413@sha256:a39d120b...
E2E RESULT: PASS - review + build + deploy all green; test-go-app:main-20260606-132413 auto-deployed to krci-demo-dev.
The post-run cluster state confirms everything:
\n$ kubectl -n krci get pipelinerun
NAME TYPE SUCCEEDED REASON
build-test-go-app-main-m8kpm build True Completed
deploy-demo-dev-kkmqg deploy True Succeeded
review-test-go-app-main-2g7kd review True Completed
$ kubectl -n krci-demo-dev get deploy,pods
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/test-go-app 1/1 1 1 85s
pod/test-go-app-595fd7f5dc-8sbrc 1/1 Running 0 85s
$ kubectl get applications -A
NAMESPACE NAME SYNC STATUS HEALTH STATUS
krci demo-dev-test-go-app Synced Healthy
The full MR-to-deployed-workload sequence, as a pipeline diagram:
\n\nA common blocker in local CI/CD setups is the container registry: DockerHub rate limits, Harbor setup complexity, credentials management. GitLab CE ships with a built-in Container Registry served on port 5050. The testbed wires kaniko to push images directly to it - eliminating every external registry dependency. Kaniko trusts the self-signed cert via a chart flag (edp-tekton.kaniko.customCert: true), and a group deploy token backs both push and pull. The registry URL is gitlab.127.0.0.1.nip.io:5050/krci/<codebase>, which maps cleanly to each codebase's GitLab project registry. No DockerHub account, no Harbor, no separate registry pod.
A note on the review/build trigger split: the EventListener has two separate Trigger CRs - gitlab-review fires on MR open/reopen/update; gitlab-build fires on MR action=merge. This means merging the MR - not a push to the branch - kicks the build pipeline. It is an intentional design choice that avoids spurious build runs on every force-push. Also worth noting: GitLab can occasionally deliver the MR webhook twice, creating a duplicate review run that fails fast with a harmless HTTP 400 when it tries to post the same commit status context. The e2e script asserts at least one run is fully green - the duplicate does not affect the result.
After make e2e passes, every component has real data in it. Here is what I found navigating each UI - a practical KubeRocketCI getting started tour of each surface.
The Portal signs in with a Kubernetes bearer token rather than a username/password - run make token to mint a 24-hour token, then paste it into the Portal's \"More options → Use Service Account Token\" field. (OIDC is intentionally not wired up in the testbed - there is no identity issuer inside a kind cluster - so the service-account token is the local sign-in path. make status flags the in-cluster Portal's token login as still being wired up; I captured these views through the Portal using that same make token service-account flow.)
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-home-3c13c6e2998281994445f55de34aecab.png\")
The home dashboard shows the pipeline metrics from the e2e run: 3 total runs, 100% success rate, 0 failed, average duration 2m 18s. This is the same observability surface that surfaces 18,397 runs on the production cluster - just seeded with a single e2e cycle.
\n![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-projects-9ad89e9288cb984b6ccba21ea614c428.png\")
The Projects page shows both registered codebases: krci-gitops (the GitOps/Helm system codebase that KubeRocketCI requires) and test-go-app (the Go/Gin application created by the e2e script). Both show status Created.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-pipelineruns-5584590a776e3e351be3b23018ab2d48.png\")
The PipelineRuns list shows all three runs - deploy, build, review - all green, all for test-go-app on PR #1.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-build-diagram-da05a9efceb1d73753d247ecb4d2cd76.png\")
The build pipeline DAG is the most visually satisfying part. Every node in the React Flow graph is green: report-pipeline-start → fetch-repository → get-version → sonar → build → container-build → git-tag → update-cbis → save-cache. The sonar step includes a quality gate wait - the build would have failed here if SonarQube reported issues.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-pipelinerun-dag-44425cb6356770a47e36964825528c8e.png\")
The build run details confirm the pipeline name (gitlab-go-gin-app-build-default) and duration (1m 34s). This is the Helm-templated pipeline library at work - the name encodes the Git provider, language, framework, and pipeline type, as described in the Kubernetes-native CI/CD with Tekton post.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-deployments-aff16ec19eb05875cea6df4fb8c2ab7f.png\")
The Deployments page shows the demo CDPipeline created by the e2e script, with test-go-app as its application.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-metrics-a3d3152d5eb9d9ed82d1274abe75f2b9.png\")
The Observability → Pipeline Metrics view breaks down the three runs: Build 1/100%, Review 1/100%, Deploy 1/100%, average 2m 18s across all types.
\n![\"Argo](\"https://docs.kuberocketci.io/assets/images/argocd-applications-b3793f92ac7fe344b32a895ee85c6397.png\")
Argo CD shows demo-dev-test-go-app as Synced + Healthy, target revision main-20260606-132413, path deploy-templates, namespace krci-demo-dev. This is the GitOps delivery leg: after kaniko pushed the image and the CodebaseImageStream updated, the cd-pipeline-operator created a CDStageDeploy resource, which triggered a deploy PipelineRun, which applied the Helm chart through Argo CD. The full GitOps chain, locally.
![\"Self-hosted](\"https://docs.kuberocketci.io/assets/images/gitlab-project-f24b76f7911eebde46293550cee78627.png\")
The self-hosted GitLab project shows both pipelines as Passed - Tekton's gitlab-set-status task wrote commit statuses back to GitLab after each pipeline run completed. Pipeline #1 is the review run (MR open), pipeline #2 is the build run (MR merge). The Go/Gin app is live at test-go-app in namespace krci-demo-dev - its / route returns 404 by design (no root handler in the Gin app), but the server is live and the deployment is 1/1 Available.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/krci-portal-deploy-dag-44368cb48fa425ba6fa4424e576d5dc9.png\")
The deploy PipelineRun details confirm the full GitOps delivery chain completed in 57 seconds - all four tasks green (pre-deploy → deploy-app → post-deploy → promote-images), the Argo CD sync applied, and the workload live in krci-demo-dev.
To explore Tekton pipelines in KubeRocketCI further, or start customizing pipelines for your own stack, the krci CLI daily use post covers how to drive the platform from the terminal and hand off to AI agents. For the foundational basic concepts, the docs cover Codebases, CDPipelines, CodebaseImageStreams, and Stages in depth.
\nmake down
make down deletes the kind cluster and all associated Kubernetes resources, leaving Docker Desktop in a clean state. Nothing persists outside the kind cluster - no volumes, no registry state, no credentials. The testbed is fully disposable and can be re-run from scratch in under 20 minutes.
This disposability is a first-class design goal, not an afterthought. For full from-zero validation: make down && make testbed && make e2e. The try-kuberocketci repository runs this sequence as part of its own CI regression.
The testbed uses fixed local-only credentials, self-signed TLS, and broad RBAC - all intentionally, for a throwaway kind cluster bound to localhost. It is explicitly not safe to expose or use on any shared, internet-reachable, or production cluster. See SECURITY.md for the details.
The fastest way to try KubeRocketCI locally is also the safest way to evaluate it - no cloud spend, no shared infrastructure, no consequences if something breaks. Here are the four use cases where the testbed pays off immediately.
\nEvaluating KubeRocketCI before adoption. Before committing months of engineering time to an IDP, run make testbed and spend 30 minutes with the real platform - not a demo video or a vendor-configured sandbox. Compare hands-on against Backstage, kubriX, or other IDPs with a working instance under your own fingers. The official platform installation guide covers the cloud path when you are ready to move from local to a real cluster.
Learning platform engineering. The testbed is a coherent, fully-wired example of Tekton, Argo CD, GitOps, SonarQube, and Tekton Results working together. Every piece is independently inspectable with kubectl, helm, and the respective UIs. Productive learning by reading a real system, not a toy demo.
Contributing to KubeRocketCI. The testbed is designed as a contributor sandbox. Run make down && make testbed to reproduce an issue from scratch without a cloud account. Each component can be rebuilt independently (make sonar, make argocd, etc.), so debugging one piece does not require tearing down the rest.
Demo preparation. Spin up a fresh instance in under 20 minutes before a presentation; tear down afterward. The make e2e output gives you a verified, live end-state to present - not a screen recording.
The table below compares try-kuberocketci against the three closest local IDP alternatives across the features that matter most for local evaluation - install time, automated testing, component depth, and Apple Silicon support.
\n| Feature | try-kuberocketci | CNOE idpBuilder | kubriX kind guide | Manual Tekton+ArgoCD |
|---|---|---|---|---|
| Commands to full stack | 2 (make testbed, make e2e) | 1 (idpbuilder create) | 6 manual steps | 15+ manual steps |
| Install time | ~18–20 min | ~5–10 min | ~30 min | 60+ min |
| Automated E2E test | Yes (zero UI clicks) | No | No | No |
| Tekton CI pipelines | Yes | No | No | Manual |
| Self-hosted GitLab CE | Yes | No (Gitea) | No | No |
| SonarQube | Yes | No | No | Optional/manual |
| Tekton Results | Yes | No | No | No |
| Prometheus + Grafana | Yes | No | No | No |
| Apple Silicon support | Explicit (Rosetta) | Yes | Not documented | Not documented |
| nip.io DNS (no /etc/hosts) | Yes | Partial | No | No |
| GitOps-pinned versions | Yes (edp-cluster-add-ons) | Partial | No | No |
| Teardown command | make down | Manual | Manual | Manual |
CNOE idpBuilder is the closest open-source alternative - it installs Argo CD, Gitea, and ingress-nginx in approximately 5–10 minutes with a single command. It is a solid choice for a minimal GitOps sandbox. What it does not have: Tekton CI pipelines, SonarQube quality gates, Tekton Results for pipeline history, Prometheus/Grafana observability, or an automated end-to-end pipeline proof. The try-kuberocketci testbed installs a significantly larger stack and uniquely validates the full MR-to-deployed-workload cycle without any UI interaction. Also note: GitHub integration is fully supported in production KubeRocketCI (integrate GitHub with KubeRocketCI) - the testbed uses GitLab specifically because it can be self-hosted in the kind cluster without a cloud account.
\nKubeRocketCI (KRCI) is an open-source internal developer platform for cloud-native CI/CD on Kubernetes, developed by EPAM and released under Apache 2.0, that integrates Tekton, Argo CD, and GitLab (or GitHub, Bitbucket) into a unified developer workflow platform. It manages Codebases from source through review, build, and GitOps-based deployment, surfacing everything through a single Portal UI and CLI.
\nClone the try-kuberocketci repository and try KubeRocketCI locally by running make testbed - it installs the full KubeRocketCI platform on a local kind cluster on Docker Desktop in approximately 18–20 minutes, with no cloud account or pre-existing Kubernetes cluster required. Run make e2e afterward to validate the full CI/CD pipeline automatically.
Docker Desktop with at least 12 GB of RAM allocated to the Docker engine is required for the full bed (8 GB suffices if you skip GitLab and SonarQube). Approximately 20 GB of free disk space is also needed for container images and volumes. No other cloud or network infrastructure is required.
\nYes. Apple Silicon (M1/M2/M3) is fully supported: Docker Desktop's Rosetta 2 emulation runs the amd64 container images (Portal, GitLab CE, sonar-operator) transparently on ARM64 hardware, with no configuration changes required in the testbed. I ran the entire flow on an Apple Silicon Mac for this post - the testbed explicitly documents and tests ARM64 support.
\nmake testbed installs the full platform in approximately 18–20 minutes; make e2e runs a complete automated pipeline proof in approximately 12 minutes. Total time from zero to a verified live workload is under 35 minutes. GitLab CE is typically the slowest component to initialize - the rest of the stack comes up faster.
make testbed install?In dependency order: a single-node kind cluster, ingress-nginx, cert-manager, Tekton Pipelines/Triggers, Argo CD, Prometheus and Grafana, Tekton Results, SonarQube Community, self-hosted GitLab CE (with bundled container registry), and KubeRocketCI edp-install 3.13.5 - 10 components in a defined sequence, with KubeRocketCI installed last so the chart can wire itself to every running dependency on first reconcile.
\nRun make e2e after make testbed completes. It automates the full cycle: applies a sample Go/Gin Codebase, waits for the codebase-operator to provision the GitLab project and webhook, opens a Merge Request to trigger the Tekton review pipeline, merges the MR to trigger the build pipeline (kaniko pushes the image to GitLab's bundled registry), waits for Argo CD to sync the deployment, and asserts the workload is 1/1 Available - all in approximately 12 minutes with zero UI clicks.
Run make down to delete the kind cluster and all associated Kubernetes resources, leaving Docker Desktop in a clean state. Nothing persists outside the kind cluster. The testbed can be re-run from scratch in under 20 minutes and is designed to be fully disposable - suitable for evaluation, demo preparation, contributor testing, and automated platform CI regression.
The testbed uses nip.io wildcard DNS: any subdomain of <IP>.nip.io resolves to <IP> via public DNS, so all platform services get stable browser-accessible URLs (*.127.0.0.1.nip.io → 127.0.0.1) without any local DNS configuration. Inside the cluster, CoreDNS rewrites handle pod-to-service resolution, and the kind node's containerd uses a registry mirror config for image pulls - no host-level DNS changes at any point.
CNOE idpBuilder spins up a minimal IDP stack (Argo CD + Gitea + ingress-nginx) in approximately 5–10 minutes but ships no Tekton CI pipelines, no SonarQube, no GitLab CE, no Tekton Results, and no automated e2e validation. The try-kuberocketci testbed installs a full production-parity platform with all of these in ~18–20 minutes and uniquely includes a fully automated end-to-end pipeline test that validates a real MR-to-deployed-workload cycle without any UI interaction.
\nThe fastest way to try KubeRocketCI locally is two commands on Docker Desktop. make testbed brings up a complete KubeRocketCI platform - 10 components including Tekton, Argo CD, SonarQube, GitLab CE, Prometheus/Grafana, and Tekton Results - in approximately 18–20 minutes. make e2e validates the full MR-to-deployed-workload pipeline automatically in approximately 12 minutes. Total: under 35 minutes from zero to a verified live workload, on Docker Desktop, with no cloud account. make down leaves nothing behind.
I ran this end-to-end on June 6, 2026 on an Apple Silicon Mac with Docker Desktop. The e2e test passed with 3/3 green runs (review + build + deploy), 100% success rate, average duration 2m 18s, and the Go/Gin sample app deployed at tag main-20260606-132413.
The most useful next steps from here:
\nKubeRocketCI is open-source under Apache License 2.0. The testbed, platform source, and Helm charts are all on GitHub.
\n", "url": "https://docs.kuberocketci.io/blog/try-kuberocketci-locally", "title": "Try KubeRocketCI Locally in 2 Commands", "summary": "Spin up the full KubeRocketCI CI/CD platform on a local kind cluster in 2 commands. No cloud account needed. Try it in under 35 minutes.", "date_modified": "2026-06-06T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "Tutorial", "Getting Started", "CI/CD", "Kubernetes", "kind", "DevOps", "Platform Engineering", "Open Source" ] }, { "id": "https://docs.kuberocketci.io/blog/krci-cli-daily-use", "content_html": "Most of my day-to-day platform work happens in a conversation. I sit in a Claude Code session - or any AI assistant with shell access - and ask plain-language questions about the state of our delivery cluster: what's failing, what's drifting, what's vulnerable, what's stale. The agent answers by calling the krci CLI, the predictable, JSON-emitting client over the KubeRocketCI Portal's tRPC API. I read the answer, decide what to do, and when a question turns into a routine I drop the underlying invocation into a script and let it run on cron or /loop. This post is a snapshot of that workflow with one running example - operator vulnerability status - and a tour of the other questions the same pattern answers.
KubeRocketCI is built so the platform's primitives are reachable from every runtime that matters in modern engineering: the portal, the CLI, Tekton pipelines, GitLab CI, schedulers, and AI agents. A workflow I write once runs everywhere it needs to:
\nkrci invocation that answers a question in my terminal runs unchanged inside a Tekton task or a GitLab CI job. Quality gates and release governance read live platform state without bespoke API clients.krci turns the platform into a tool surface it can call: list codebases, inspect SBOMs, compare branches, summarize changes since the previous run. No MCP server to write, no proprietary protocol to learn, no stale API client to maintain.The portal and the CLI are peers: the portal is the right interface for browsing, comparing, and approving; the CLI is the right interface for composing, scheduling, and handing off to agents. Both are first-class products and ship in lockstep.
\nA short tour of the top-level surface, because this is what the agent has access to:
\n$ krci --help
Available Commands:
auth Authentication commands
deployment Manage deployments (CDPipelines)
env Inspect KRCI environments (Stages)
pipelinerun Manage pipeline runs
project Manage projects (Codebases)
sca Inspect Dependency-Track projects, components, and vulnerability findings
sonar Inspect SonarQube projects, quality gates, and issues
version Print krci CLI version
When you run any of these commands - say, krci deployment list to inspect CD pipelines across your environments-the output follows the same disciplined structure. Columns are consistent, status values are predictable, and the table is human-readable and machine-parseable without any translation. Here's what that looks like in practice:
![\"Example](\"https://docs.kuberocketci.io/assets/images/krci-deployment-example-caf267064ce6a879812ee983987af264.png\")
This table shows exactly what's deployed where. The VERSION column tracks the build artifact (0.5.0-SNAPSHOT.4), the ENV column shows which environment it's in, and the STATUS column tells you health at a glance -healthy or missing. The SYNC column flags when an environment has drifted (OutOfSync) from what GitOps expects. In seconds, you can answer: \"What's actually running in qa? Is it in sync? What version?\" The agent can answer it too, and answer the next question - \"Show me all deployments older than 30 days\" - without any special prompting.
Every group follows the same shape - list, get, sometimes a third verb - and the flags repeat (--branch, --severity, -o json|table). Predictability is the point: an agent can reason about the next command from the previous one, and so can I. Authentication is OIDC against the same Keycloak the portal uses; the agent inherits the existing session, so there is no long-lived API key embedded in any prompt.
Here's a recent question, verbatim, from a Claude Code session:
\n\n\n\"Using krci, give me the current vulnerability status of every operator registered on the platform. Main branch only, critical and high counts, top affected components per operator.\"
\n
What the agent returned:
\nOPERATOR CRIT HIGH TOP COMPONENTS (HIGH+)
cd-pipeline-operator 0 0 clean
codebase-operator 0 2 github.com/tektoncd/pipeline
keycloak-operator 0 0 clean
nexus-operator 0 0 clean
sonar-operator 0 0 clean
One row is doing all the work: codebase-operator master carries two high-severity findings, and both trace back to a single github.com/tektoncd/pipeline cluster. Everything else is clean. That's the kind of answer I can act on without scrolling - one operator, one component, one upgrade to plan.
The command I run by hand to verify the answer is one line:
\n$ krci sca list --page-size 500 -o json \\
| jq -r '.data.items[]
| select(.name | endswith(\"-operator\"))
| select(.version == \"master\")
| [.name, .metrics.critical, .metrics.high] | @tsv'
That's the whole loop. I described what I wanted in the language of the work, the agent shaped a krci invocation, and I can re-run any step independently to validate the result. No prior knowledge of jq flags, subcommand layout, or the platform's internal data model was required on my side.
When a row of the answer needs follow-up, I keep the conversation going:
\n\n\n\"Drill into
\ncodebase-operatormaster - which components are driving those two highs?\"
The agent's reply (verifiable by running the command yourself):
\n$ krci sca components codebase-operator --branch=master --severity=high
COMPONENT VULNS (C/H/M/L)
github.com/tektoncd/pipeline 0/2/4/0
One component, both highs, two natural-language turns, two commands. I never had to remember the flag shape; the agent bridged intent to invocation and the CLI's predictable output bridged invocation to answer.
\nVulnerability status is one of many. The agent + CLI handle the same shape of question across the platform - I describe it in plain language, the agent runs krci, I verify the output against the platform:
krci pipelinerun list -o json filtered on .status.conditions.code-assistant?\" → krci env list -o json joined against the latest tag.krci sonar list -o json filtered by language.krci project list against krci sca list.krci deployment list -o json filtered on .status.lastDeploy.Same pattern every time: ask in language, get an answer the CLI can verify, move on. The agent does the orchestration; the CLI does the work.
\nThe moment a question becomes recurring, it stops belonging in chat. The same krci invocation the agent assembled in the conversation becomes the body of a script:
#!/usr/bin/env bash
# Daily operator vulnerability digest - main branches only.
krci sca list --page-size 500 -o json \\
| jq -r '.data.items[]
| select(.name | endswith(\"-operator\"))
| select(.version == \"master\")
| [.name, .metrics.critical, .metrics.high] | @tsv' \\
| column -t
From there it's the standard fan-out:
\n~/reports/operators-$(date +%F).md.jq, post on threshold./loop for a six-hour heartbeat that reports only what changed:/loop 6h Run cli/scripts/operators-digest.sh and tell me ONLY what
changed since the previous run. Reply in under 60 words.
Same script, same JSON, three runtimes. The CLI is unchanged; only the wrapper changes.
\nThree properties matter, and each one comes from deliberate design rather than accident:
\nkrci ... -o json is shaped consistently across releases. The agent doesn't need a parser; it navigates JSON.list, get, sometimes a third verb, with the same flags everywhere. The agent generalizes from one command to the next, and so do humans.The result is that the conversation with the agent stays in the language of the work - \"vulnerability status of operators\", \"failed runs in the last 24 hours\", \"environments running an out-of-date image\" - and the CLI handles the translation. Both pieces are independently inspectable: I can replay any command myself, the agent can replay it tomorrow, and the script that captures a routine is short enough to review in one sitting.
\nA few things I learned the slightly hard way:
\nproject list but are absent from sca list because no CycloneDX upload has happened on their build pipelines. The CLI surfaces the gap rather than hiding it, which is itself useful, but means agent answers should always cross-check both lists.krci sca list --filter='critical>0' flag yet - native flags are on the roadmap, the agent compensates in the meantime.Last BOM) shows up in krci sca get but not on sca list. If staleness matters to your routine, pin it explicitly in your script.I include this list because tools earn trust by being honest about what they don't do yet.
\nkrci auth login./loop.That's the entire loop: ask in language, get an answer the CLI can verify, schedule it when it matters.
\nThe krci CLI is open-source under Apache License 2.0. Source, issues, and release binaries live on GitHub.
", "url": "https://docs.kuberocketci.io/blog/krci-cli-daily-use", "title": "krci CLI: From Terminal to AI Agents", "summary": "How I use the krci CLI as a tool surface for Claude Code and other AI assistants to answer day-to-day platform questions in plain language.", "date_modified": "2026-05-05T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "CLI", "AI Agents", "DevOps", "SCA", "Claude Code", "Platform Engineering", "Dependency-Track" ] }, { "id": "https://docs.kuberocketci.io/blog/kubernetes-native-cicd-tekton-kuberocketci", "content_html": "Building CI/CD on Kubernetes used to mean running Jenkins or GitLab CI in a pod and calling it done. Tekton changed that by making pipelines first-class Kubernetes objects - Tasks and Pipelines are CRDs, PipelineRuns are namespaced resources, and every step log is a container log. KubeRocketCI goes a step further: it ships a complete, production-grade CI/CD platform on top of Tekton so your team gets sensible defaults, a portal UI, GitOps-managed pipeline definitions, and opinionated quality gates - without the months of plumbing work that comes with assembling those pieces from scratch. I've seen teams go from a bare cluster to a working build-deploy loop in under a day using this stack.
\nHere's how the layering works in practice - from Tekton's native primitives to the Helm-templated pipeline library, the webhook-to-PipelineRun chain, each pipeline type, and the portal UI that surfaces it all.
\nTraditional CI servers are external systems that talk to Kubernetes. They authenticate, schedule jobs, wait for responses, and manage their own scaling independently of the cluster. Tekton turns that model inside out - the cluster is the CI engine. Every pipeline run is a pod, every step is a container, and the Kubernetes control plane handles scheduling, scaling, and secrets injection natively.
\nThe practical consequences:
\nKubeRocketCI is an open-source, cloud-agnostic SaaS/PaaS platform built on Tekton - a CNCF Graduated project - developed and maintained by EPAM Systems. Where Tekton gives you primitives, KubeRocketCI gives you a working system.
\nThe platform deploys and manages the full Tekton component set:
\n| Component | Role |
|---|---|
| Tekton Pipelines | Executes all CI and CD pipeline runs |
| Tekton Triggers | Listens for Git webhook events and fires the matching pipeline |
| Tekton Interceptors | Enriches and filters GitHub, GitLab, and Bitbucket payloads before routing |
| Tekton Chains | Signs pipeline artifacts for supply-chain provenance |
| Tekton Results | Stores run history for audit trails and portal display |
On top of Tekton, KubeRocketCI adds:
\nSee Basic Concepts and the Tekton Overview for the full capability matrix.
\nPipelines in KubeRocketCI are not hand-written one-offs - they are generated by Helm from a structured library in edp-tekton. The naming convention follows:
\n{gitProvider}-{buildTool}-{framework}-app-{pipelineType}-{versioning}
For example, a Java 17 Maven build pipeline triggered from GitHub with default versioning renders as:
\ngithub-maven-java17-app-build-default
The same pipeline for GitLab becomes gitlab-maven-java17-app-build-default. This pattern means every combination of git provider, language, framework, and versioning strategy gets a consistently named, independently configurable pipeline - without duplicating task logic. Shared task sequences live in common Helm templates (e.g., _common_java_maven.yaml) and are included by reference.
For a Java Maven application, the build pipeline executes these tasks in order:
\nget-version
└─ update-build-number
└─ get-cache
└─ compile
└─ test (JaCoCo coverage)
└─ sonar (quality gate: sonar.qualitygate.wait=true)
└─ build (mvn clean package -DskipTests)
└─ push (mvn deploy -DskipTests)
The sonar step blocks with sonar.qualitygate.wait=true - the build fails fast at the quality gate rather than discovering issues downstream. In my experience, this single flag is the difference between catching technical debt in minutes versus after a release candidate is already tagged. Code that doesn't pass SonarQube never produces an artifact.
Each task is a reusable Tekton Task CRD (maven, sonarqube-maven) - the pipeline only sets parameters and runAfter ordering. Swap the maven task image to change the JDK version; the pipeline logic stays the same.
When a pull request is merged on GitHub, the event travels through four Tekton resources before a PipelineRun starts:
\n\nThe Custom Interceptor is the key piece. It enriches the raw GitHub payload with platform-specific extensions that the webhook payload alone doesn't contain:
extensions.codebase - the KubeRocketCI codebase name for this repositoryextensions.codebasebranch - the branch object with its pipeline configurationextensions.pipelines.build - the exact pipeline name to run (e.g., github-maven-java17-app-build-default)extensions.pullRequest.headSha, extensions.pullRequest.author, extensions.pullRequest.urlThe TriggerBinding then extracts these into named parameters: gitrevision, targetBranch, gitsha, codebase, codebasebranch, pipelineName, commitMessagePattern, and Jira integration fields. The TriggerTemplate stamps these into a PipelineRun spec and creates it in the cluster.
This architecture means the decision of which pipeline runs for which codebase is stored in the platform's Kubernetes objects - not hardcoded in webhook configuration.
\nKubeRocketCI defines seven pipeline types, identified by the app.edp.epam.com/pipelinetype label. All are implemented as Tekton Pipelines.
pipelinetype: review)Triggered by a pull request. Runs static analysis, linting, unit tests, and code-quality gates before a merge is allowed. Typically completes in under five minutes.
\nTrigger methods: open a PR against a configured branch, comment /recheck or /ok-to-test, or use the Run Again button in the portal.
pipelinetype: build)Triggered on merge to the target branch. Executes the full task sequence (see above), builds and pushes a container image, and produces a versioned artifact. Versioning follows either BRANCH-[DATETIME] (default) or SemVer (MAJOR.MINOR.PATCH-BUILD_ID) depending on project configuration.
pipelinetype: deploy)Takes a versioned artifact and applies it to a target environment. Trigger modes: manual (via portal), Auto (deploy automatically on new artifact), or Auto-stable (promote only the rebuilt component, keep others at stable versions).
pipelinetype: clean)Tears down an environment on demand. Paired with Auto deploys and dynamic environments, this enables full ephemeral workflows - spin up for a PR, validate, clean up on merge.
pipelinetype: security)A standalone pipeline decoupled from build, purpose-built for vulnerability scanning. Scan results surface in the portal's Results tab and link through to DefectDojo. Decoupling security means scans can run at any cadence without affecting build cycle time.
\npipelinetype: tests)Executes automated test suites against already-deployed environments, independent of the deploy cycle. Teams validate application behavior on demand without triggering a full redeploy.
\npipelinetype: release)Orchestrates approval and publishing for new releases. KubeRocketCI does not ship a pre-built release pipeline - release governance is organization-specific. The full Tekton API surface is available to build custom approval steps, external system integrations, and auditable release flows.
\nThe complete pipeline type reference is in Pipelines Overview and Tekton Overview.
\nThe pre-built library covers most tech stacks, but production workloads always have exceptions. KubeRocketCI supports two customization patterns without forking the platform.
\nDefine a custom pipeline once with a naming pattern, and every project matching that pattern picks it up automatically. The Tekton custom pipelines use case walks through the full authoring flow.
\nWhen different branches need different logic - main with full integration tests, release with image signing - pipelines are defined explicitly per branch. See the custom pipelines flow guide.
Both approaches follow the same Git-first workflow: write Tekton YAML, apply to the cluster to verify, commit, and let Argo CD synchronize the authoritative state.
\nThe KubeRocketCI portal ships a dedicated tekton module with full pipeline management across four page areas: pipeline list, pipeline details, PipelineRun list, and PipelineRun details.
Pipeline list with type filter. The pipeline list filters by app.edp.epam.com/pipelinetype label - select build, review, deploy, or any of the seven types to narrow the view. Each pipeline shows its type, last run status, and a Run with params button.
Run with params. Clicking Run with params fetches the TriggerTemplate linked to the pipeline (via the app.edp.epam.com/triggertemplate label), generates a PipelineRun draft pre-filled with correct parameters, opens a YAML editor for review, and creates the PipelineRun resource via the Kubernetes API on save. No kubectl required.
DAG visualization. The pipeline details page renders the task graph using React Flow - nodes for each task, directed edges from runAfter dependencies, isolated tasks shown separately. Colors map to live status: blue (running), green (succeeded), red (failed), amber (pending). Finally-tasks are distinguished visually from the main execution chain.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/dag-pipeline-visualization-8b8c71a308819a038a39e685720d4ef1.png\")
Live logs and history. The PipelineRun details page streams live container logs while a run is active. After completion, logs are served from Tekton Results - the same view, no separate log aggregation setup needed.
\nInline manual approval. When a pipeline step is an ApprovalTask (a platform-native CRD), the portal renders Approve / Reject buttons directly in the task view - with an optional comment field. The approval decision (spec.action, spec.approve.approvedBy, spec.approve.comment) is written back to the ApprovalTask resource. This is how release gates and environment promotion approvals are implemented as Kubernetes-native objects.
Follow the Quick Start: Install KubeRocketCI guide for a local cluster. For production on AWS, see Deploy on AWS EKS.
\nThe Install Tekton guide covers both vanilla Kubernetes and OKD/OpenShift (Tekton Operator). For the fully automated path, see Add-Ons Overview.
\nWalk through Integrate GitHub or configure GitLab/Bitbucket in the portal under Git Servers.
\nIntegrate DockerHub wires up image push. Integrate SonarQube activates the quality gate step in the build pipeline.
\nCreate Application registers your codebase. The platform provisions a review and build pipeline for the default branch automatically - the Helm-templated library selects the correct pipeline name based on your tech stack.
\nDeploy Application connects Argo CD and configures the first CD pipeline stage. Integrate Argo CD covers the Argo CD setup.
\nFrom a fresh cluster to a working build-and-deploy loop typically takes a few hours.
\nOnce the platform is running, every onboarded application has:
\nThis is what our own dogfooding instance looks like - we run KubeRocketCI on KubeRocketCI itself. Over 90 days, the krci namespace logged 18,397 pipeline runs (~200/day across build, review, and deploy types), with build pipelines hitting a 93% success rate at an average duration of 14 minutes 38 seconds. No external CI server involved.
![\"KubeRocketCI](\"https://docs.kuberocketci.io/assets/images/pipeline-metrics-c39298a912c421e0e581550d8fbbed0d.png\")
The entire path - review pipeline on PR open, build pipeline on merge, artifact versioning, image push, and Argo CD sync - runs without the developer writing a single line of Jenkins Groovy or pipeline YAML. The only required input is declaring the tech stack at onboarding time.
\nNo manual wiring required. The opinionated defaults deliver a production-grade setup from day one, and the full Tekton API surface is available when you need to diverge.
\nKubeRocketCI is open-source under Apache License 2.0. Platform source, Helm charts, and the full Tekton pipeline library are on GitHub.
", "url": "https://docs.kuberocketci.io/blog/kubernetes-native-cicd-tekton-kuberocketci", "title": "Kubernetes-Native CI/CD with Tekton", "summary": "Learn how KubeRocketCI builds Kubernetes-native CI/CD on Tekton - covering pipeline task sequences, webhook trigger chain, and how to author custom pipelines.", "date_modified": "2026-05-04T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "Tekton", "Kubernetes", "CI/CD", "DevOps", "Platform Engineering", "GitOps" ] }, { "id": "https://docs.kuberocketci.io/blog/integrating-oidc-authentication-microsoft-entra-aws-eks", "content_html": "In modern cloud environments, secure and efficient access management is essential, especially for platforms like Amazon EKS. This blog will guide you through integrating OpenID Connect (OIDC) authentication using Microsoft Entra, making it easier to manage access to your EKS clusters and KubeRocketCI Portal. By implementing this approach, you can simplify user authentication while ensuring strong security controls. Whether you're improving compliance or streamlining access for your team, this integration is a practical solution to enhance your cloud-native workflows.
\nBefore you begin, ensure you have the following:
\nIn the context of enhancing digital security and user experience, we prioritize the integration of three key elements: Single Sign-On (SSO), OpenID Connect (OIDC), and Microsoft Entra. Here’s how they connect:
\nSingle Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.
\nOpenID Connect (OIDC) builds on the SSO framework by providing an authentication layer, which uses straightforward identity verification to ensure secure and seamless access across services.
\nMicrosoft Entra (formerly known as Azure Active Directory) is Microsoft's comprehensive identity and access management solution. It supports the implementation of both Single Sign-On (SSO) and OpenID Connect (OIDC), enabling organizations to securely manage user identities and enforce access controls. With its reliable set of tools, Microsoft Entra simplifies authentication, enhances security, and ensures seamless access to applications and services, making it an essential platform for modern identity management.
\nTogether, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.
\nMicrosoft Entra, formerly known as Azure Active Directory (Azure AD), is a modern identity and access management solution designed for secure access to applications and services. It provides features like Single Sign-On (SSO), identity federation, and seamless integration with on-premises directories such as LDAP and Active Directory. Microsoft Entra supports industry-standard protocols, including OpenID Connect (OIDC), OAuth 2.0, and Security Assertion Markup Language (SAML) 2.0, making it a versatile solution for managing user identities. By leveraging Microsoft Entra, organizations can enhance security, simplify user access, and avoid the complexities of building identity management features from scratch. For more details, see the Microsoft Entra official documentation.
\nTo get started with Microsoft Entra, you need to create a new tenant in the Microsoft Entra Admin Center. Follow these steps:
\nLog in to the Microsoft Entra Admin Center using your Microsoft account.
\n![\"Microsoft](\"https://docs.kuberocketci.io/assets/images/microsoft-entra-admin-center-8a597425e8e1e33a8867e316ee37be41.png\")
In the left sidebar menu, select Overview section and then navigate to Manage tenants tab.
\n![\"Manage](\"https://docs.kuberocketci.io/assets/images/manage-tenants-c260f4975163bf0c5cb83eeb99217660.png\")
Click on Create button to create a new tenant.
\n![\"Create](\"https://docs.kuberocketci.io/assets/images/create-tenant-ea455de07150c662e89cc2896be821ff.png\")
Select the configuration type Workforce.
\n![\"Configuration](\"https://docs.kuberocketci.io/assets/images/configuration-type-31ef85a58475500f22b83a05c93b4276.png\")
Fill in the fields for Tenant Name, Domain Name, and Location.
\nThe Tenant Name and Domain Name kuberocketci are used as a demonstration examples. In your case, it is recommended to choose names that align with your organization's specific needs and naming conventions.
![\"Tenant](\"https://docs.kuberocketci.io/assets/images/tenant-details-6753dbbdbe872963be3e49632442654b.png\")
The new tenant will be created, and you can start configuring it for OIDC integration. Ensure you have switched to the new tenant.
\nAfter creating the tenant, you need to set up an OIDC Application in Microsoft Entra. Here's how you can do it:
\nIn the Microsoft Entra Admin Center, in the left sidebar menu, select Applications and then click on App registrations.
\n![\"App](\"https://docs.kuberocketci.io/assets/images/app-registrations-c04b119572cc459069182f6aeab95995.png\")
Click on the New registration button to create a new application.
\n![\"New](\"https://docs.kuberocketci.io/assets/images/new-registration-63846c96d5ff493abbc9903c638fb6cf.png\")
Fill in the details for the application, such as Name, Supported account types, and Redirect URI (http://localhost:8000/).
The Name kuberocketci is used as a demonstration example. In your case, it is recommended to choose a name that aligns with your application's specific needs and naming conventions (e.g. your AWS EKS cluster name).
![\"Application](\"https://docs.kuberocketci.io/assets/images/application-details-b0691226247a0b3f611936922040e4b6.png\")
In the created application, navigate to the Authentication section from the left sidebar menu. In the Implicit grant and hybrid flows section, select ID tokens for the token type. In the Allow public client flows section, set the value to No.
\n![\"Authentication](\"https://docs.kuberocketci.io/assets/images/authentication-settings-b3ad780dbc75b519a96e4138242666dd.png\")
Navigate to the Certificates & secrets section from the left sidebar menu. In the Client secrets tab, click on the New client secret button to create a new secret.
\n![\"Client](\"https://docs.kuberocketci.io/assets/images/client-secret-2adb6894937ed5c8e84c077423b51fbb.png\")
Copy the generated client secret value and store it securely.
\n![\"Client](\"https://docs.kuberocketci.io/assets/images/client-secret-value-26326b1338acafd94f8e5a647f6407f4.png\")
Navigate to the Token configuration section and click on Add group claim button. Choose the group type as Security Groups and for the ID token type, select Group ID.
\n![\"Token](\"https://docs.kuberocketci.io/assets/images/token-configuration-0fa9c3f0e471ac1b1ffcf11f69bee22c.png\")
(Optional) Additionally, add an optional upn claim in the Token configuration section.
\nThis step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.
![\"upn](\"https://docs.kuberocketci.io/assets/images/upn-claim-0ae2415ae51d8eab1bfce10492cbf021.png\")
(Optional) After adding the upn claim, click on the three dots next to it, select Edit, and turn on the Externally authenticated toggle to Yes value.
\nThis step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.
![\"Externally](\"https://docs.kuberocketci.io/assets/images/externally-authenticated-1bfd6efbb519c1633eb00d846fd99dc6.png\")
Navigate to the API permissions section. Ensure that the User.Read permission is added under the Microsoft Graph API. If not, click on the Add a permission button, select Microsoft Graph, and add the User.Read permission. After adding the permission, click on the Grant admin consent for 'Tenant name' button to grant the required permissions.
\n![\"API](\"https://docs.kuberocketci.io/assets/images/api-permissions-ec305b38ce662e114e3e614ceabca58a.png\")
(Optional) Additionally, for Microsoft Graph API, add the OpenId permissions, such as openid, email, and profile.
\nThis step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.
![\"OpenID](\"https://docs.kuberocketci.io/assets/images/openid-permissions-f130d9bd007be3509b7f33b48e6e488d.png\")
The OIDC Application in Microsoft Entra is now configured and ready for integration with AWS EKS.
\nOnly users who are part of the groups configured in the Microsoft Entra Admin Center will be able to authenticate to the AWS EKS cluster using OIDC.
To create users and groups in Microsoft Entra, follow these steps:
\nIn the Microsoft Entra Admin Center, in the left sidebar menu, select Groups and then All groups. Click on New group button to create a new group(s) for users who will have access to the AWS EKS cluster.
\n![\"New](\"https://docs.kuberocketci.io/assets/images/new-group-057769fdc60e88276e453cfe1d13520a.png\")
Fill in the details for the group, such as Group type and Group name. Click on the Create button to create the group.
\n![\"Group](\"https://docs.kuberocketci.io/assets/images/group-details-f699a47eca753f3e4f7fed9bd27ac86d.png\")
The group will be created, and you can start adding users to it.
\nIn the Microsoft Entra Admin Center, in the left sidebar menu, select Users and then click on All users. In the New user tab, click on the Create new user button to create a new user.
\n![\"New](\"https://docs.kuberocketci.io/assets/images/new-user-8d00fa515a4025b42a98f013a37d9a8f.png\")
Fill in the details for the user, such as User principal name, Mail nickname, Display name, and temporary password. In the Properties tab you can set the First name, Last name, and other details.
\n![\"User](\"https://docs.kuberocketci.io/assets/images/user-details-b5f580cd6fe8db3a519fd95a7d42fdc5.png\")
In the Assignment tab, click on the Add group button. In the Select Group window, choose the group(s) you created earlier (e.g., oidc-cluster-admins) and click on the Select button.
![\"Add](\"https://docs.kuberocketci.io/assets/images/add-group-ad90704de9b5399c8ce85605ca530a7d.png\")
Click on the Review + create button to create the user. The user will be created and added to the group(s) you selected.
\nThere are two methods to configure Microsoft Entra as an Identity Provider in AWS EKS: through the AWS Management Console and using Terraform.
\nThe Application data, such as Directory (tenant) ID, Application (client) ID, and Issuer URL, can be found in the Overview section of the OIDC Application in the Microsoft Entra Admin Center.\n![\"Application](\"https://docs.kuberocketci.io/assets/images/application-data-79ef843fc1e677bbbc0597ce1b9c2f50.png\")
Log in to the AWS Management Console and navigate to the Amazon EKS console. Select the EKS cluster you want to configure and click on the Access tab.
\n![\"EKS](\"https://docs.kuberocketci.io/assets/images/eks-cluster-access-tab-707d67886863028877f32b1630411b4e.png\")
In the OIDC identity providers section, click on the Associate identity provider button.
\n![\"Associate](\"https://docs.kuberocketci.io/assets/images/associate-identity-provider-8d81c9b345b76eb0bf49961342edde54.png\")
Fill in the following details:
\nName: Entra
Issuer URL: https://login.microsoftonline.com/<Tenant-ID>/, where <Tenant-ID> is the Directory (tenant) ID. Ensure that the URL ends with /.
Client ID: <Application (client) ID>, which corresponds to the Application (client) ID of the OIDC Application.
Username Claim: upn.
Groups Claim: groups.
![\"Identity](\"https://docs.kuberocketci.io/assets/images/identity-provider-details-43942f4911d1c02742267b8b19d106cb.png\")
The process of applying the changes may take a few minutes. Once completed, the Microsoft Entra OIDC identity provider will be associated with the AWS EKS cluster.
\nTo configure Microsoft Entra as an Identity Provider in AWS EKS using Terraform, you can use AWS EKS Terraform module. Here's an example of how you can do it:
\nvariable \"cluster_identity_providers\" {
description = \"Configuration for OIDC identity provider\"
type = any
default = {}
}
cluster_identity_providers = {
entra = {
client_id = \"<Application (client) ID>\"
issuer_url = \"https://sts.windows.net/<Tenant ID>/\"
groups_claim = \"groups\"
username_claim = \"upn\"
}
}
module \"eks\" {
source = \"terraform-aws-modules/eks/aws\"
version = \"20.14.0\"
...
# OIDC Identity provider
cluster_identity_providers = var.cluster_identity_providers
}
After applying the Terraform configuration, the Microsoft Entra OIDC identity provider will be associated with the AWS EKS cluster.
\nIn this section, user authorization will be configured using Kubernetes Role-Based Access Control (RBAC). Microsoft Entra groups will be linked to Kubernetes ClusterRoles through ClusterRoleBinding resources, enabling precise control over resource access within the EKS cluster. Additionally, Roles and RoleBindings can be used for more granular access control within specific namespaces.
\nThe Object ID of the Microsoft Entra group can be found in the Overview section of the group in the Microsoft Entra Admin Center.\n![\"Group](\"https://docs.kuberocketci.io/assets/images/group-object-id-074d9c1a6ef1ebdd351442b25e07f37d.png\")
Log in to the AWS EKS cluster and create the following ClusterRoleBinding resource, which associates the Microsoft Entra group oidc-cluster-admins with the cluster-admin Kubernetes Cluster Role. Replace <your-microsoft-entra-admin-group-object-id> with the Object ID of the oidc-cluster-admins group, which can be found on the Group overview page in the Microsoft Entra admin center.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: oidc-cluster-admins
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: Group
name: <your-microsoft-entra-admin-group-object-id>
apiGroup: rbac.authorization.k8s.io
Save the above YAML to a file, for example, clusterrolebinding.yaml, and apply it to the EKS cluster using the following command:
kubectl apply -f clusterrolebinding.yaml
The oidc-cluster-admins group will now have cluster-admin permissions within the EKS cluster.
To authenticate to the AWS EKS cluster using Microsoft Entra, you can use the kubectl CLI tool with the kubelogin plugin. The kubelogin plugin simplifies the OIDC authentication process by handling the token exchange and session management. Here's how you can authenticate to the EKS cluster:
Create or update the kubeconfig file with the OIDC configuration. Replace <cluster-name> with the name of your EKS cluster and <region-code> with the AWS region code where the cluster is located.
aws eks update-kubeconfig --region <region-code> --name <cluster-name>
Execute the following command to create a new kubeconfig context using the kubelogin plugin. Replace <cluster-name> with the name of your EKS cluster.
kubectl config set-credentials \"eks\" \\
--exec-api-version=client.authentication.k8s.io/v1beta1 \\
--exec-command=kubelogin \\
--exec-arg=get-token \\
--exec-arg=--oidc-issuer-url \\
--exec-arg=https://sts.windows.net/<Tenant ID>/ \\
--exec-arg=--oidc-client-id \\
--exec-arg=<Application (client) ID> \\
--exec-arg=--oidc-client-secret \\
--exec-arg=<Application (client) Secret>
Replace <Tenant ID>, <Application (client) ID>, and <Application (client) Secret> with the corresponding values from the OIDC Application in the Microsoft Entra Admin Center.
You can test the authentication to the EKS cluster immediately by running the following command:
kubectl --user=eks get nodes
Set the context for the kubeconfig file to use the eks user and the OIDC configuration. Replace <cluster-name> with the name of your EKS cluster.
kubectl config set-context eks --user=eks --cluster=<cluster-name>
To switch to the eks context, execute the following command:
kubectl config use-context eks
Test the authentication by running the following command:
\nkubectl get nodes
Starting from version 3.10, KubeRocketCI platform supports Microsoft Entra as an Identity Provider for OIDC authentication in the Portal UI. To configure Microsoft Entra OIDC authentication, navigate to the edp-install Helm chart repository and set the following values in the values.yaml file:
...
edp-headlamp:
enabled: true
config:
oidc:
enabled: true
issuerUrl: \"https://sts.windows.net/<Tenant ID>/\"
clientID: \"<Application (client) ID>\"
clientSecretName: \"<name of the secret containing the client-secret value>\"
clientSecretKey: \"clientSecret\"
...
Replace <Tenant ID> and <Application (client) ID> with the corresponding values from the OIDC Application in the Microsoft Entra Admin Center. Also, specify the name of the Kubernetes Secret containing the Application Client secret value in the clientSecretName field.
In the Microsoft Entra Admin Center, navigate to the created OIDC Application and select the Authentication section. In the Redirect URIs field, add the URL of the KubeRocketCI Portal, for example, https://portal-<krci-namespace>.<dns-wildcard>/oidc-callback.
![\"Redirect](\"https://docs.kuberocketci.io/assets/images/redirect-uris-7fdaed8d83ca7e79234435a232fce0ec.png\")
After applying the changes, the KubeRocketCI Portal will be configured to use Microsoft Entra OIDC authentication. Users will be able to log in to the Portal using Sign In option.
\n![\"Sign](\"https://docs.kuberocketci.io/assets/images/sign-in-61897514acf347a032e4a3eaa2582c2d.png\")
Integrating OpenID Connect (OIDC) authentication with Microsoft Entra in AWS EKS is a powerful way to enhance security and streamline user access management. By leveraging the capabilities of SSO, OIDC, and Microsoft Entra, organizations can simplify authentication processes, enforce access controls, and ensure secure navigation across cloud-native environments. Whether you're managing user identities, enhancing compliance, or improving user experience, this integration provides a robust solution to meet your identity and access management needs. By following the steps outlined in this guide, you can configure Microsoft Entra as an Identity Provider in AWS EKS, authenticate users using OIDC, and secure access to your EKS clusters and KubeRocketCI Portal effectively.
", "url": "https://docs.kuberocketci.io/blog/integrating-oidc-authentication-microsoft-entra-aws-eks", "title": "Integrating OIDC Authentication with Microsoft Entra in AWS EKS", "summary": "Learn how to implement Single Sign-On (SSO) using OpenID Connect (OIDC) and Microsoft Entra to enhance security and streamline authentication processes in Amazon Elastic Kubernetes Service (AWS EKS).", "date_modified": "2024-12-03T00:00:00.000Z", "author": { "name": "Daniil Nedostup", "url": "https://github.com/daniil-nedostup" }, "tags": [ "KubeRocketCI", "AWS EKS", "SSO", "Microsoft Entra", "OIDC", "Kubernetes", "Security" ] }, { "id": "https://docs.kuberocketci.io/blog/advanced-aws-eks-management-oidc-keycloak", "content_html": "In today's cloud-first world, ensuring seamless and secure access to Amazon Elastic Kubernetes Service (EKS) is essential for IT teams. Our guide helps you enhance EKS security by integrating Single Sign-On (SSO) with OpenID Connect (OIDC) and Keycloak. This integration simplifies authentication and strengthens security measures. We aim to provide you with effective strategies to implement a robust SSO solution that meets your organization's standards, making your EKS environment more secure and compliant. KubeRocketCI leverages this integration to provide Role-Based Access Control (RBAC) for your EKS clusters, ensuring that only authorized users can access platform resources.
\nBefore you begin, ensure you have the following:
\nIn the context of enhancing digital security and user experience, we prioritize the integration of three key elements: Single Sign-On (SSO), OpenID Connect (OIDC), and the Keycloak solution. Here’s how they connect:
\nSingle Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.
\nOpenID Connect (OIDC) builds on the SSO framework by providing an authentication layer, which uses straightforward identity verification to ensure secure and seamless access across services.
\nKeycloak acts as the orchestrator, implementing both SSO and OIDC to manage user identities and security protocols efficiently. It provides a comprehensive platform for securing applications and services with minimal hassle for end-users.
\nTogether, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.
\nSingle sign-on (SSO) is a user authentication method that lets you use one set of login credentials (such as a username and password) to access multiple applications. The primary benefits of SSO include an improved user experience by eliminating the need for multiple passwords and logins, and enhanced security through centralized management of user access. Organizations widely adopt SSO to streamline their authentication processes and reduce the likelihood of password fatigue among users, thereby decreasing the risk of security breaches. For more information, see Single sign-on on Wikipedia.
\n\nThis diagram shows the following steps:
\nThe same process is repeated for Application 2 and Application 3. Since the user's session is already established with the SSO gateway, they do not need to log in again to access these applications.
\nOpenID Connect (OIDC) is an authentication layer on top of the OAuth 2.0 protocol. It lets clients verify the identity of the end user based on authentication by an authorization server and get basic profile information about the end user in an interoperable and REST-like manner. OIDC uses JSON Web Tokens (JWTs) to securely transmit information about an end user from the identity provider to the client. This protocol is essential for modern web applications, providing a more secure and streamlined method for user authentication and authorization. Reference: OIDC Specification
\nOIDC enables single sign-on (SSO) functionality, simplifying the user experience by allowing individuals to use a single set of credentials across multiple applications. The protocol also supports robust security features, including token revocation and introspection, enhancing overall application security.
\nThis diagram simplifies the OIDC flow into its core components:
\n\nThe sequence starts with the user requesting access to the client application, moving through authentication with the authorization server, and ending with the client application accessing protected resources.
\nKeycloak is an open-source identity and access management solution for modern applications and services. It offers features like single sign-on (SSO), social login, and identity brokering, making it a comprehensive solution for managing user identities. Keycloak integrates seamlessly with LDAP (Lightweight Directory Access Protocol) and Active Directory and supports OpenID Connect (OIDC), OAuth 2.0, and Security Assertion Markup Language (SAML) 2.0. By using Keycloak, organizations can enhance their security and provide a better user experience without building complex identity management features from scratch. For more details, see the Keycloak official documentation.
\nThe first step to enable OIDC authentication to the AWS EKS cluster using Keycloak is to set up Keycloak with the necessary configurations, such as realm, client, groups, and other settings. For this purpose, we will use the kuberocketci-rbac Helm chart available in the edp-cluster-add-ons repository.
\nClone the forked edp-cluster-add-ons repository and navigate to the clusters/core/addons/kuberocketci-rbac directory.
In the values.yaml file, set the kubernetes.enabled field to true to enable the creation of the necessary Keycloak resources:
kubernetes:
enabled: true
If you use the External Secrets Operator to manage secrets, ensure the AWS Parameter Store object contains the correct Client Secret value for the keycloak-client-eks-secret secret:
\n{
...
\"keycloak-client-eks-secret\": {
\"clientSecret\": \"<Client_Secret_Value>\"
},
...
}
If you are not using the External Secrets Operator, you can create the keycloak-client-eks-secret secret manually:
\nkubectl create secret generic keycloak-client-eks-secret \\
--from-literal=clientSecret=<Client_Secret_Value>
Install the kuberocketci-rbac Helm chart. You can use the kubectl cli tool or Argo CD for this purpose.
\nEnsure you are in the clusters/core/addons/kuberocketci-rbac directory if you want to install the chart with the kubectl command. For example:
kubectl upgrade --install kuberocketci-rbac -n security .
If you are using Argo CD to deploy charts in the edp-cluster-add-ons repository, ensure that the following fields for the kuberocketci-rbac Helm chart are correctly set in the values.yaml file in the clusters/core/apps directory:
kuberocketci-rbac:
createNamespace: false
enable: true
After the installation is complete, check that the Keycloak resources, such as the realm, client, and groups, have been created successfully.
\nTo manage user access to the AWS EKS cluster, you need to assign users to specific groups in Keycloak. These groups will define the permissions for users accessing the AWS EKS cluster.
\nLog in to the Keycloak admin console and navigate to the shared realm.
\nSelect the Users section from the left sidebar menu and select the user you want to add to a group. Navigate to the Groups tab and click on the Join Group button to add the user to a group.
\n![\"Keycloak](\"https://docs.kuberocketci.io/assets/images/keycloak-add-user-to-group-c578b2c460fee04b308e5555c5c4aaa9.png\")
Select the group you want to add the user to (e.g., oidc-cluster-admins). Click on the Join button to add the user to the selected group.
\n![\"Keycloak](\"https://docs.kuberocketci.io/assets/images/keycloak-join-group-2bd628e00f93dec1d0611ab7d0ebbb38.png\")
Repeat the process of adding users to groups for all users who need access to the AWS EKS cluster.
\nThere are two methods to configure Keycloak as an identity provider in AWS EKS: using the AWS Management Console or Terraform.
\nLog in to the AWS Management Console and navigate to the Amazon EKS service. Select the EKS cluster you want to configure and click on the Access tab.
\n
In the OIDC identity providers section, click on the Associate identity provider button.
\n
Fill in the following details for the Keycloak Identity Provider:
\nName: Keycloak
Issuer URL: https://<keycloak_url>/auth/realms/shared, where <keycloak_url> is the URL of your Keycloak instance.
Client ID: eks.
Groups Claim: groups.
The process of applying the changes may take a few minutes. Once completed, you will see the Keycloak Identity Provider associated with your EKS cluster.
\nTo configure Keycloak as an Identity Provider in AWS EKS cluster using Terraform, you can use the AWS EKS Terraform module. Here's an example of how to define the Keycloak Identity Provider in Terraform configuration files:
\nvariable \"cluster_identity_providers\" {
description = \"Configuration for OIDC identity provider\"
type = any
default = {}
}
cluster_identity_providers = {
keycloak = {
client_id = \"eks\"
issuer_url = \"https://<keycloak_url>/auth/realms/shared\"
groups_claim = \"groups\"
}
}
module \"eks\" {
source = \"terraform-aws-modules/eks/aws\"
version = \"20.14.0\"
...
# OIDC Identity provider
cluster_identity_providers = var.cluster_identity_providers
}
After applying the Terraform configuration, the Keycloak identity provider will be associated with your EKS cluster.
\nConfigure kubeconfig file to use the Keycloak Identity Provider for authentication to the AWS EKS cluster. You can use the following template:
\napiVersion: v1
preferences: {}
kind: Config
clusters:
- cluster:
server: https://<eks_cluster_endpoint>.eks.amazonaws.com
certificate-authority-data: <eks_cluster_ca>
name: eks
contexts:
- context:
cluster: eks
user: <keycloak_user_email>
name: eks
current-context: eks
users:
- name: <keycloak_user_email>
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- -v1
- --oidc-issuer-url=https://<keycloak_url>/auth/realms/shared
- --oidc-client-id=eks
- --oidc-client-secret=<keycloak_client_secret>
Replace the placeholders with the actual values:
\n<eks_cluster_endpoint>: The endpoint of your AWS EKS cluster.<eks_cluster_ca>: The CA certificate of your AWS EKS cluster.<keycloak_user_email>: The email address of the Keycloak user.<keycloak_url>: The URL of your Keycloak instance.<keycloak_client_secret>: The Client secret of the eks Keycloak client (provided during the Keycloak Configuration step).Save the kubeconfig file and set the KUBECONFIG environment variable to point to the file:
export KUBECONFIG=<path_to_kubeconfig_file>
Test the authentication to the AWS EKS cluster by running the following command:
\nkubectl get nodes
After the first command execution, you will be prompted to log in to Keycloak. Enter your credentials to authenticate and access the EKS cluster. If the authentication is successful, you will see the list of nodes in the EKS cluster.
\nThe KubeRocketCI platform natively supports Keycloak as an Identity Provider for OIDC authentication.
\nTo configure the KubeRocketCI Portal with Keycloak OIDC authentication, navigate to the edp-install Helm chart and set the following values in the values.yaml file:
edp-headlamp:
enabled: true
config:
oidc:
enabled: true
issuerUrl: \"https://<keycloak_url>/auth/realms/shared\"
clientID: \"eks\"
clientSecretName: \"keycloak-client-headlamp-secret\"
clientSecretKey: \"clientSecret\"
Replace the keycloak_url with the URL of your Keycloak instance.
\nEnsure the AWS Parameter Store object contains the correct Client Secret value for the keycloak-client-headlamp-secret secret:
\n{
...
\"keycloak-client-headlamp-secret\": \"<Client_Secret_Value>\"
...
}
After setting the values, install the edp-install Helm chart to apply the changes:
\nhelm upgrade --install krci --namespace krci .
After applying the changes, the KubeRocketCI Portal will be configured to use Keycloak OIDC authentication. Users will be able to log in to the Portal using Sign In option.
\n
Integrating OpenID Connect (OIDC) authentication with Keycloak in AWS EKS enhances security and simplifies user access management. By leveraging Keycloak's capabilities, you can implement a reliable Single Sign-On (SSO) solution that meets your organization's security standards. This guide has provided step-by-step instructions to configure Keycloak as an Identity Provider, set up necessary Keycloak resources, and enable OIDC authentication for the KubeRocketCI Portal. By following these steps, you can ensure secure and seamless access to your EKS clusters and KubeRocketCI Portal, improving both security and user experience.
", "url": "https://docs.kuberocketci.io/blog/advanced-aws-eks-management-oidc-keycloak", "title": "Advanced AWS EKS Management: Implementing SSO via OIDC and Keycloak", "summary": "Learn how to implement Single Sign-On (SSO) using OpenID Connect (OIDC) and Keycloak to boost security and streamline authentication processes in Amazon Elastic Kubernetes Service (AWS EKS).", "date_modified": "2024-10-04T00:00:00.000Z", "author": { "name": "Sergiy Kulanov", "url": "https://github.com/sergk" }, "tags": [ "KubeRocketCI", "Keycloak", "AWS EKS", "SSO" ] } ] }