Workflows, Not Sessions​

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:

• Pipelines. A krci 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.
• Schedulers. A short bash wrapper in cron, or a Kubernetes CronJob produces a daily report on a hands-off cadence - same command, same output, same trust boundary.
• Chat and webhooks. JSON output drops straight into Slack, Teams, or PagerDuty without a translation layer.
• AI agents in the SDLC. AI coding agents - Claude Code, Cursor, the Anthropic and OpenAI SDKs - read terminal output natively. Giving an agent shell access to 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.

The krci CLI as a Tool Surface​

A short tour of the top-level surface, because this is what the agent has access to:

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

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.

Asking the Agent: "What's the Vulnerability Status of Our Operators?"​

Here's a recent question, verbatim, from a Claude Code session:

"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."

What the agent returned:

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

$ 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.

Drilling In Stays in Plain Language​

When a row of the answer needs follow-up, I keep the conversation going:

"Drill into codebase-operator master - which components are driving those two highs?"

The agent's reply (verifiable by running the command yourself):

$ 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.

The Same Pattern, Other Questions​

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

• "Which pipeline runs failed in the last 24 hours, grouped by codebase?" → krci pipelinerun list -o json filtered on .status.conditions.
• "Which environments are running an out-of-date image of code-assistant?" → krci env list -o json joined against the latest tag.
• "What's the SonarQube quality gate state of every Java codebase?" → krci sonar list -o json filtered by language.
• "Which projects on the platform haven't produced an SBOM yet?" → diff krci project list against krci sca list.
• "Show me every CD pipeline whose latest deploy is older than 30 days." → 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.

Making It Stick: Schedule, Script, Notify​

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

• Cron or Kubernetes CronJob for a daily markdown digest in ~/reports/operators-$(date +%F).md.
• Slack/Teams webhook for "first new critical on a release branch" alerts. Pipe the JSON through jq, post on threshold.
• Claude Code /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.

Why the krci CLI Works Well as an Agent Tool Surface​

Three properties matter, and each one comes from deliberate design rather than accident:

• Stable, structured output. krci ... -o json is shaped consistently across releases. The agent doesn't need a parser; it navigates JSON.
• Identity is solved upstream. OIDC sessions are inherited from the developer's existing login. No API keys leak into prompts, transcripts, or scripts.
• Predictable verb shape. 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.

Honest Notes Before You Adopt the Pattern​

A few things I learned the slightly hard way:

• Not every codebase produces an SBOM yet. Some appear in project 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.
• Cross-project aggregation sometimes still uses a shell loop. There's no krci sca list --filter='critical>0' flag yet - native flags are on the roadmap, the agent compensates in the meantime.
• BOM age (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.

Try It Yourself​

1. Install krci from the release page and run krci auth login.
2. Open your AI assistant of choice, give it shell access, and ask your own version of the question above. Anything along the lines of "using krci, show me the vulnerability status of every operator on the platform, main branch only" will work on day one.
3. When the answer becomes a routine, drop the underlying command into a script and run it on cron, a CronJob, or /loop.

That's the entire loop: ask in language, get an answer the CLI can verify, schedule it when it matters.

Further Reading​

• krci CLI on GitHub - command reference, authentication setup, and release binaries.
• SCA with Dependency-Track - how SBOMs reach the platform.
• Kubernetes-Native CI/CD with Tekton - the pipeline layer that produces those SBOMs.
• CycloneDX SBOM, Dependency-Track, and Claude Code - the upstream tools used in this post.

The krci CLI is open-source under Apache License 2.0. Source, issues, and release binaries live on GitHub.

Here'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.

Why Does Kubernetes-Native CI/CD Matter?​

Traditional 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.

The practical consequences:

• No CI server to maintain. No Jenkins controller HA setup, no separate runner fleet. Tekton scales horizontally with your cluster.
• Uniform RBAC. Pipeline permissions use Kubernetes ServiceAccounts - no separate credential management UI.
• Pipeline as code. Pipeline definitions are YAML manifests, version-controlled alongside application code, and applied to any conformant Kubernetes cluster identically.
• Native secret injection. Tekton Tasks consume Kubernetes Secrets and ConfigMaps directly - no plugin abstraction required.
• Shift-left by default. Code quality, security scanning, and test gates run inside the cluster as ordinary containers, co-located with the workloads they protect.

KubeRocketCI and the Tekton Stack​

KubeRocketCI 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.

The platform deploys and manages the full Tekton component set:

On top of Tekton, KubeRocketCI adds:

• Pipeline library - Helm-packaged Tasks and Pipelines for Java, Go, Node.js, Python, .NET, Helm, Terraform, and more.
• Portal UI - full pipeline management with DAG visualization, live log streaming, and inline manual approval gates.
• Argo CD integration - pipeline definitions are stored in Git and synchronized by Argo CD. Every change to a pipeline is a reviewed, audited commit.

See Basic Concepts and the Tekton Overview for the full capability matrix.

How Are Tekton Pipelines Defined in KubeRocketCI?​

The Helm-Templated Library​

Pipelines in KubeRocketCI are not hand-written one-offs - they are generated by Helm from a structured library in edp-tekton. The naming convention follows:

{gitProvider}-{buildTool}-{framework}-app-{pipelineType}-{versioning}

For example, a Java 17 Maven build pipeline triggered from GitHub with default versioning renders as:

github-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.

The Real Build Task Sequence​

For a Java Maven application, the build pipeline executes these tasks in order:

get-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.

The Webhook-to-PipelineRun Chain​

When a pull request is merged on GitHub, the event travels through four Tekton resources before a PipelineRun starts:

The 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 repository
• extensions.codebasebranch - the branch object with its pipeline configuration
• extensions.pipelines.build - the exact pipeline name to run (e.g., github-maven-java17-app-build-default)
• extensions.pullRequest.headSha, extensions.pullRequest.author, extensions.pullRequest.url

The 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.

Pipeline Types: From Code Review to Release​

KubeRocketCI defines seven pipeline types, identified by the app.edp.epam.com/pipelinetype label. All are implemented as Tekton Pipelines.

Review Pipeline (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.

Trigger methods: open a PR against a configured branch, comment /recheck or /ok-to-test, or use the Run Again button in the portal.

Build Pipeline (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.

Deploy Pipeline (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).

Clean Pipeline (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.

Security Pipeline (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.

Test Pipeline (pipelinetype: 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.

Release Pipeline (pipelinetype: 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.

The complete pipeline type reference is in Pipelines Overview and Tekton Overview.

Customizing Pipelines​

The pre-built library covers most tech stacks, but production workloads always have exceptions. KubeRocketCI supports two customization patterns without forking the platform.

Custom Framework / Build Tool​

Define 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.

Branch-Specific Pipelines​

When 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.

The Portal: Pipeline Management UI​

The 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.

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.

Inline 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.

Getting Started​

Step 1 - Install the platform​

Follow the Quick Start: Install KubeRocketCI guide for a local cluster. For production on AWS, see Deploy on AWS EKS.

Step 2 - Install Tekton components​

The Install Tekton guide covers both vanilla Kubernetes and OKD/OpenShift (Tekton Operator). For the fully automated path, see Add-Ons Overview.

Step 3 - Connect your Git provider​

Walk through Integrate GitHub or configure GitLab/Bitbucket in the portal under Git Servers.

Step 4 - Integrate container registry and code quality​

Integrate DockerHub wires up image push. Integrate SonarQube activates the quality gate step in the build pipeline.

Step 5 - Onboard your first application​

Create 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.

Step 6 - Configure a deployment environment​

Deploy Application connects Argo CD and configures the first CD pipeline stage. Integrate Argo CD covers the Argo CD setup.

From a fresh cluster to a working build-and-deploy loop typically takes a few hours.

What Every Onboarded App Gets Automatically​

Once the platform is running, every onboarded application has:

• A review pipeline on every pull request - compile, test, SonarQube quality gate.
• A build pipeline on every merge - versioned artifact, container image pushed, Tekton Chains provenance attestation.
• A CD pipeline connected to Argo CD - promoting artifacts through configured stages.
• Pipeline definitions in Git - every change to a pipeline goes through code review, synchronized by Argo CD.
• Live + archived logs - streaming during a run, served from Tekton Results after completion.
• Manual approval gates - inline approve/reject in the portal for any pipeline step that requires human sign-off.

This 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.

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.

No 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.

Next Steps​

• Explore the Tekton Overview for the complete pipeline type and trigger reference.
• Try the application scaffolding use case to see the platform generate a project skeleton with a working CI/CD pipeline in minutes.
• Follow autotest as quality gate to promote automatically only when integration tests pass.
• Read deploy application from a feature branch for ephemeral environment patterns.

KubeRocketCI is open-source under Apache License 2.0. Platform source, Helm charts, and the full Tekton pipeline library are on GitHub.

Prerequisites​

Before you begin, ensure you have the following:

• Access to the Microsoft Entra Admin Center with administrative privileges.
• A running AWS EKS cluster with the necessary permissions for access and management.
• The kubelogin plugin installed for authenticating to the EKS cluster using OIDC.
• The kubectl CLI tool installed.
• The aws cli tool installed.

Understanding SSO, OIDC, and Microsoft Entra​

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

• Single Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.

• OpenID 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.

• Microsoft 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.

Together, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.

Microsoft Entra Overview​

Microsoft 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.

Create a new Microsoft Entra Tenant​

To get started with Microsoft Entra, you need to create a new tenant in the Microsoft Entra Admin Center. Follow these steps:

1. Log in to the Microsoft Entra Admin Center using your Microsoft account.

   

2. In the left sidebar menu, select Overview section and then navigate to Manage tenants tab.

   

3. Click on Create button to create a new tenant.

   

4. Select the configuration type Workforce.

   

5. Fill in the fields for Tenant Name, Domain Name, and Location.

   note

   The 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.

   

6. The new tenant will be created, and you can start configuring it for OIDC integration. Ensure you have switched to the new tenant.

Creating and Configuring OIDC Application in Microsoft Entra​

After creating the tenant, you need to set up an OIDC Application in Microsoft Entra. Here's how you can do it:

1. In the Microsoft Entra Admin Center, in the left sidebar menu, select Applications and then click on App registrations.

   

2. Click on the New registration button to create a new application.

   

3. Fill in the details for the application, such as Name, Supported account types, and Redirect URI (http://localhost:8000/).

   note

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

   

4. 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.

   

5. 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.

   

6. Copy the generated client secret value and store it securely.

   

7. 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.

   

8. (Optional) Additionally, add an optional upn claim in the Token configuration section.

   note

   This 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.

   

9. (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.

   note

   This 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.

   

10. 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.

    

11. (Optional) Additionally, for Microsoft Graph API, add the OpenId permissions, such as openid, email, and profile.

    note

    This 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.

    

12. The OIDC Application in Microsoft Entra is now configured and ready for integration with AWS EKS.

Creating Users and Groups in Microsoft Entra​

To create users and groups in Microsoft Entra, follow these steps:

Creating a Group​

1. In 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.

   

2. Fill in the details for the group, such as Group type and Group name. Click on the Create button to create the group.

   

3. The group will be created, and you can start adding users to it.

Adding Users to the Group​

1. In 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.

   

2. 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.

   

3. 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.

   

4. Click on the Review + create button to create the user. The user will be created and added to the group(s) you selected.

Configuring Microsoft Entra as an Identity Provider in AWS EKS​

There are two methods to configure Microsoft Entra as an Identity Provider in AWS EKS: through the AWS Management Console and using Terraform.

Method 1: Using the AWS Management Console​

1. 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.

   

2. In the OIDC identity providers section, click on the Associate identity provider button.

   

3. Fill in the following details:

   • Name: 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.

     

4. 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.

Method 2: Using Terraform​

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

• variables.tf:

variable "cluster_identity_providers" {
  description = "Configuration for OIDC identity provider"
  type        = any
  default     = {}
}

• terraform.tfvars:

cluster_identity_providers = {
  entra = {
    client_id    = "<Application (client) ID>"
    issuer_url   = "https://sts.windows.net/<Tenant ID>/"
    groups_claim = "groups"
    username_claim  = "upn"
  }
}

• main.tf:

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.

Configuring RBAC Resources in AWS EKS cluster for Microsoft Entra User Groups​

In 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.

1. 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.

Authenticating to AWS EKS using Microsoft Entra with kubectl​

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:

1. 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>
   

2. 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.

   note

   You can test the authentication to the EKS cluster immediately by running the following command:

   kubectl --user=eks get nodes
   

3. 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:

   kubectl get nodes
   

Configuring KubeRocketCI Portal with Microsoft Entra OIDC Authentication​

1. 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.

2. 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.

   

3. 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.

   

Conclusion​

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.

Prerequisites​

Before you begin, ensure you have the following:

• A running AWS EKS cluster with the necessary permissions for access and management.
• Forked and cloned the edp-cluster-add-ons repository.
• The kubelogin plugin installed for authenticating to the EKS cluster using OIDC.
• The kubectl cli tool installed.
• The aws cli tool installed.
• Keycloak installed and configured with the kuberocketci-rbac Helm chart, which can be found in the add-ons repository.
• The Keycloak-operator installed.

Understanding SSO, OIDC, and Keycloak​

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

• Single Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.

• OpenID 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.

• Keycloak 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.

Together, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.

What is SSO?​

Single 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.

This diagram shows the following steps:

1. User logs in once at the single sign-on (SSO) gateway by providing their credentials.
2. The SSO gateway authenticates the user, creates a session, and then allows the user to access multiple applications.
3. When the user attempts to access Application 1, the application verifies the user's session with the SSO gateway.
4. The SSO gateway confirms that the session is valid, and Application 1 grants the user access.

The 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.

Understanding OIDC​

OpenID 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

OIDC 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.

This diagram simplifies the OIDC flow into its core components:

1. User (U): The end user who wants to access the client application.
2. Client Application (C): The application requiring authentication from the user.
3. Authorization Server (AS): The server that authenticates the user and issues tokens to the client application.
4. Resource Server (RS): The server hosting protected resources that the client application wants to access on behalf of the user.

The 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.

Keycloak Overview​

Keycloak 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.

Keycloak Configuration​

The 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.

1. Clone the forked edp-cluster-add-ons repository and navigate to the clusters/core/addons/kuberocketci-rbac directory.

2. In the values.yaml file, set the kubernetes.enabled field to true to enable the creation of the necessary Keycloak resources:

   values.yaml

   kubernetes:
     enabled: true
   

3. 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:

   AWS Parameter Store object

   {
     ...
     "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:

   kubectl create secret generic keycloak-client-eks-secret \
     --from-literal=clientSecret=<Client_Secret_Value>
   

4. Install the kuberocketci-rbac Helm chart. You can use the kubectl cli tool or Argo CD for this purpose.

   • kubectl

   Ensure 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 .
   

   • Argo CD

   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:

   values.yaml

   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.

Adding Users to Groups in Keycloak​

To 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.

1. Log in to the Keycloak admin console and navigate to the shared realm.

2. Select 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.

   

3. 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.

   

4. Repeat the process of adding users to groups for all users who need access to the AWS EKS cluster.

Configuring Keycloak as an Identity Provider in AWS EKS​

There are two methods to configure Keycloak as an identity provider in AWS EKS: using the AWS Management Console or Terraform.

Method 1: Using the AWS Management Console​

1. Log 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.

   

2. In the OIDC identity providers section, click on the Associate identity provider button.

   

3. Fill in the following details for the Keycloak Identity Provider:

   • Name: 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.

     

4. 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.

Method 2: Using Terraform​

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

• variables.tf:

variable "cluster_identity_providers" {
  description = "Configuration for OIDC identity provider"
  type        = any
  default     = {}
}

• terraform.tfvars:

cluster_identity_providers = {
  keycloak = {
    client_id    = "eks"
    issuer_url   = "https://<keycloak_url>/auth/realms/shared"
    groups_claim = "groups"
  }
}

• main.tf:

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.

Authenticating to AWS EKS cluster using kubectl​

1. Configure kubeconfig file to use the Keycloak Identity Provider for authentication to the AWS EKS cluster. You can use the following template:

   kubeconfig

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

   • <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).

2. Save the kubeconfig file and set the KUBECONFIG environment variable to point to the file:

   export KUBECONFIG=<path_to_kubeconfig_file>
   

3. Test the authentication to the AWS EKS cluster by running the following command:

   kubectl 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.

Configuring KubeRocketCI Portal with Keycloak OIDC Authentication​

The KubeRocketCI platform natively supports Keycloak as an Identity Provider for OIDC authentication.

1. To 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:

   values.yaml

   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.

2. Ensure the AWS Parameter Store object contains the correct Client Secret value for the keycloak-client-headlamp-secret secret:

   AWS Parameter Store object

   {
     ...
     "keycloak-client-headlamp-secret": "<Client_Secret_Value>"
     ...
   }
   

3. After setting the values, install the edp-install Helm chart to apply the changes:

   helm upgrade --install krci --namespace krci .
   

4. 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.

   

Conclusion​

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.