docs: update Jenkins integration guide with Kubernetes and VM examples

docs/articles/jenkins-ui.mdx

@@ -4,6 +4,12 @@ The Testkube Jenkins integration streamlines the installation of Testkube, enabl
 
 If you're looking to use Pipelines and Groovy scripts, then look at examples from [Testkube Jenkins Pipelines](./jenkins.mdx).
 
+:::warning
+
+Testkube CLI Jenkins Plugin only works with the Cloud-hosted Testkube Control Plane. If you are hosting the Control Plane yourself, please use the Groovy scripts as it's recommended above.
+
+:::
+
 ### Testkube CLI Jenkins Plugin
 
 Install the Testkube CLI plugin by searching for it in the "Available Plugins" section on Jenkins Plugins, or using the following url:

docs/articles/jenkins.mdx

@@ -1,40 +1,61 @@
 # Testkube Jenkins Pipelines
 
-The Testkube Jenkins integration streamlines the installation of Testkube, enabling the execution of any [Testkube CLI](https://docs.testkube.io/cli/testkube) command within Jenkins pipelines. This integration can be effortlessly integrated into your Jenkins setup, enhancing your continuous integration and delivery processes.
-This Jenkins integration offers a versatile solution for managing your pipeline workflows and is compatible with both commercial and open source deployments of Testkube. It allows Jenkins users to effectively utilize Testkube's capabilities within their CI/CD pipelines, providing a robust and flexible framework for test execution and automation.
+The Testkube Jenkins integration enables the execution of any [Testkube CLI](https://docs.testkube.io/cli/testkube) command within Jenkins pipelines. This integration is compatible with both commercial and open source deployments of Testkube, providing a robust and flexible framework for test execution and automation.
 
-### Testkube CLI Jenkins Plugin
+There are multiple ways to integrate Testkube with Jenkins depending on your setup:
 
-Install the Testkube CLI plugin by searching it in the "Available Plugins" section on Jenkins Plugins, or using the following url:
-[https://plugins.jenkins.io/testkube-cli](https://plugins.jenkins.io/testkube-cli)
-
-## Testkube
+- **Jenkins on Kubernetes**: Use the `kubeshop/testkube-cli` Docker image as a container in your pod template.
+- **Jenkins on VMs**: Install the Testkube CLI directly on your Jenkins agents.
+- **Jenkins CLI Plugin**: Use the [Testkube CLI Jenkins Plugin](https://plugins.jenkins.io/testkube-cli) to automatically install and configure the CLI.
 
-### How to configure Testkube CLI action for Testkube and run a Test Workflow
+## Prerequisites
 
 To use Jenkins CI/CD with [Testkube](https://app.testkube.io/), you need to create an [API token](https://docs.testkube.io/articles/organization-management#api-tokens).
 Then, pass the **organization** and **environment** IDs, along with the **token** and other parameters specific for your use case.
 
-If a test is already created, you can run it using the command `testkube run testworkflow TEST_WORKFLOW_NAME -f` . However, if you need to create a test in this workflow, please add a creation command, e.g.: `testkube create testworkflow -f EXAMPLE_FILE.yaml`.
+If a test is already created, you can run it using the command `testkube run testworkflow TEST_WORKFLOW_NAME -f`. However, if you need to create a test in this workflow, please add a creation command, e.g.: `testkube create testworkflow -f EXAMPLE_FILE.yaml`.
+
+## Jenkins on Kubernetes
+
+If your Jenkins instance runs on Kubernetes (using the [Kubernetes plugin](https://plugins.jenkins.io/kubernetes/)), you can use the `kubeshop/testkube-cli` Docker image directly in your pipeline. This avoids the need to install the CLI binary during the pipeline run.
 
-You'll need to create a Jenkinsfile. This Jenkinsfile should define the stages and steps necessary to execute the workflow
+:::info
+The pod template requires `securityContext.runAsUser: 1000` so that both the JNLP agent and the Testkube container share the same UID and can read/write the shared workspace volume. Additionally, the `HOME` environment variable must be set to a writable path (e.g., `/home/jenkins/agent`) so the CLI can store its configuration.
+:::
+
+### Testkube (Cloud)
 
 ```groovy
 pipeline {
-    agent any
-
+    agent {
+        kubernetes {
+            yaml '''
+                apiVersion: v1
+                kind: Pod
+                spec:
+                  securityContext:
+                    runAsUser: 1000
+                  containers:
+                  - name: testkube
+                    image: kubeshop/testkube-cli:<version>
+                    command: ['sleep']
+                    args: ['infinity']
+                    env:
+                    - name: HOME
+                      value: /home/jenkins/agent
+            '''
+        }
+    }
     environment {
         TK_ORG = credentials("TK_ORG")
         TK_ENV = credentials("TK_ENV")
         TK_API_TOKEN = credentials("TK_API_TOKEN")
     }
     stages {
-        stage('Example') {
+        stage('Testing') {
             steps {
-                script {
-                    // Setup the Testkube CLI
-                    setupTestkube()
-                    // Run testkube commands
+                container('testkube') {
+                    sh 'testkube set context --api-key $TK_API_TOKEN --org-id $TK_ORG --env-id $TK_ENV'
                     sh 'testkube run testworkflow TEST_WORKFLOW_NAME -f'
                 }
             }
@@ -43,47 +64,92 @@ pipeline {
 }
 ```
 
-## Testkube Open Source
+Replace `<version>` with the desired Testkube CLI version (e.g., `2.7.1`).
 
-### How to configure Testkube CLI action for TK OSS and run a Test Workflow
+### Testkube (Self-Hosted)
 
-To connect to the self-hosted instance, you need to have **kubectl** configured for accessing your Kubernetes cluster, and pass an optional namespace, if Testkube is not deployed in the default **testkube** namespace.
+For self-hosted Testkube instances running in the same cluster, point `--api-uri-override` to the in-cluster API service:
 
-If a test is already created, you can run it using the command `testkube run testworkflow TEST_WORKFLOW_NAME -f` . However, if you need to create a test in this workflow, please add a creation command, e.g.: `testkube create testworkflow -f EXAMPLE_FILE.yaml`.
+```groovy
+pipeline {
+    agent {
+        kubernetes {
+            yaml '''
+                apiVersion: v1
+                kind: Pod
+                spec:
+                  securityContext:
+                    runAsUser: 1000
+                  containers:
+                  - name: testkube
+                    image: kubeshop/testkube-cli:<version>
+                    command: ['sleep']
+                    args: ['infinity']
+                    env:
+                    - name: HOME
+                      value: /home/jenkins/agent
+            '''
+        }
+    }
+    environment {
+        TK_ORG = credentials("TK_ORG")
+        TK_ENV = credentials("TK_ENV")
+        TK_API_TOKEN = credentials("TK_API_TOKEN")
+        TK_URL = 'https://api.mydomain:443'
+    }
+    stages {
+        stage('Testing') {
+            steps {
+                container('testkube') {
+                    sh 'testkube set context --api-key $TK_API_TOKEN --org-id $TK_ORG --env-id $TK_ENV --api-uri-override $TK_URL'
+                    sh 'testkube run testworkflow TEST_WORKFLOW_NAME -f'
+                }
+            }
+        }
+    }
+}
+```
+
+## Jenkins on VMs
 
-You'll need to create a Jenkinsfile. This Jenkinsfile should define the stages and steps necessary to execute the workflow
+If your Jenkins agents run on virtual machines (or bare metal), you can install the Testkube CLI directly during the pipeline execution. This approach downloads the CLI binary and uses it to configure the context and run tests.
+
+### Testkube (Cloud)
 
 ```groovy
 pipeline {
     agent any
 
     environment {
-        TK_NAMESPACE = 'custom-testkube-namespace'
+        TK_ORG = credentials("TK_ORG")
+        TK_ENV = credentials("TK_ENV")
+        TK_API_TOKEN = credentials("TK_API_TOKEN")
     }
     stages {
-        stage('Example') {
+        stage('Setup and Run') {
             steps {
-                script {
-                    setupTestkube()
-                    sh 'testkube run testworkflow TEST_WORKFLOW_NAME'
-                }
+                sh '''
+                    # Install the Testkube CLI
+                    curl -sSLf https://get.testkube.io | sh
+
+                    # Configure the CLI context
+                    testkube set context --api-key $TK_API_TOKEN --org-id $TK_ORG --env-id $TK_ENV
+
+                    # Run a Test Workflow
+                    testkube run testworkflow TEST_WORKFLOW_NAME -f
+                '''
             }
         }
     }
 }
 ```
 
-The steps to connect to your Kubernetes cluster differ for each provider. You should check the docs of your Cloud provider for how to connect to the Kubernetes cluster from Jenkins CI/CD
+### Testkube with EKS (Amazon Elastic Kubernetes Service)
 
-### How to configure Testkube CLI action for TK OSS and run a Test Workflow
-
-This workflow establishes a connection to EKS cluster and creates and runs a test using TK CLI. In this example we also use variables not
- to reveal sensitive data. Please make sure that the following points are satisfied:
-- The **_AwsAccessKeyId_**, **_AwsSecretAccessKeyId_** secrets should contain your AWS IAM keys with proper permissions to connect to EKS cluster.
-- The **_AwsRegion_** secret should contain AWS region where EKS is
-- The **EksClusterName** secret points to the name of EKS cluster you want to connect.
-
-You'll need to create a Jenkinsfile. This Jenkinsfile should define the stages and steps necessary to execute the workflow
+This workflow establishes a connection to an EKS cluster and runs a Test Workflow using the Testkube CLI. Please make sure that the following points are satisfied:
+- The **_AwsAccessKeyId_**, **_AwsSecretAccessKeyId_** secrets should contain your AWS IAM keys with proper permissions to connect to the EKS cluster.
+- The **_AwsRegion_** secret should contain the AWS region where EKS is deployed.
+- The **_EksClusterName_** secret points to the name of the EKS cluster you want to connect to.
 
 ```groovy
 pipeline {
@@ -95,7 +161,7 @@ pipeline {
         TK_API_TOKEN = credentials("TK_API_TOKEN")
     }
     stages {
-        stage('Setup Testkube') {
+        stage('Setup and Run') {
             steps {
                 script {
                     // Setting up AWS credentials
@@ -110,10 +176,13 @@ pipeline {
                         sh 'aws eks update-kubeconfig --name $EKS_CLUSTER_NAME --region $AWS_REGION'
                     }
 
-                    // Installing and configuring Testkube based on env vars
-                    setupTestkube()
+                    // Install the Testkube CLI
+                    sh 'curl -sSLf https://get.testkube.io | sh'
 
-                    // Running Testkube test
+                    // Configure the CLI context
+                    sh 'testkube set context --api-key $TK_API_TOKEN --org-id $TK_ORG --env-id $TK_ENV'
+
+                    // Run a Test Workflow
                     sh 'testkube run testworkflow TEST_WORKFLOW_NAME -f'
                 }
             }
@@ -122,13 +191,12 @@ pipeline {
 }
 ```
 
-### How to connect to GKE (Google Kubernetes Engine) cluster and run a Test Workflow
+### Testkube with GKE (Google Kubernetes Engine)
 
-This example connects to a k8s cluster in Google Cloud, creates and runs a test using Testkube Jenkins workflow. Please make sure that the following points are satisfied:
+This example connects to a Kubernetes cluster in Google Cloud and runs a Test Workflow using the Testkube CLI. Please make sure that the following points are satisfied:
 
-- The **_GKE Service Account_** should be created prior in Google Cloud and added to Jenkins variables along with **_GKE Project_** value;
-- The **_GKE Cluster Name_** and **_GKE Zone_** can be added as environmental variables in the workflow.
-  you'll need to create a Jenkinsfile. This Jenkinsfile should define the stages and steps necessary to execute the workflow
+- The **_GKE Service Account_** should be created prior in Google Cloud and added to Jenkins credentials along with **_GKE Project_** value.
+- The **_GKE Cluster Name_** and **_GKE Zone_** can be added as credentials in Jenkins.
 
 ```groovy
 pipeline {
@@ -140,7 +208,7 @@ pipeline {
         TK_API_TOKEN = credentials("TK_API_TOKEN")
     }
     stages {
-        stage('Deploy to GKE') {
+        stage('Setup and Run') {
             steps {
                 script {
                     // Activating GKE service account
@@ -164,10 +232,13 @@ pipeline {
                         sh 'gcloud container clusters get-credentials $GKE_CLUSTER_NAME --zone $GKE_ZONE'
                     }
 
-                    // Installing and configuring Testkube based on env vars
-                    setupTestkube()
+                    // Install the Testkube CLI
+                    sh 'curl -sSLf https://get.testkube.io | sh'
+
+                    // Configure the CLI context
+                    sh 'testkube set context --api-key $TK_API_TOKEN --org-id $TK_ORG --env-id $TK_ENV'
 
-                    // Running Testkube test
+                    // Run a Test Workflow
                     sh 'testkube run testworkflow TEST_WORKFLOW_NAME -f'
                 }
             }
@@ -182,3 +253,60 @@ pipeline {
     }
 }
 ```
+
+## Testkube CLI Jenkins Plugin
+
+Alternatively, you can use the Testkube CLI Jenkins Plugin, which automatically downloads, installs, and configures the Testkube CLI within your pipeline.
+
+Install the plugin by searching for it in the "Available Plugins" section on Jenkins, or using the following URL:
+[https://plugins.jenkins.io/testkube-cli](https://plugins.jenkins.io/testkube-cli)
+
+### Testkube (Cloud)
+
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        TK_ORG = credentials("TK_ORG")
+        TK_ENV = credentials("TK_ENV")
+        TK_API_TOKEN = credentials("TK_API_TOKEN")
+    }
+    stages {
+        stage('Example') {
+            steps {
+                script {
+                    // Setup the Testkube CLI
+                    setupTestkube()
+                    // Run testkube commands
+                    sh 'testkube run testworkflow TEST_WORKFLOW_NAME -f'
+                }
+            }
+        }
+    }
+}
+```
+
+### Testkube Open Source
+
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        TK_NAMESPACE = 'custom-testkube-namespace'
+    }
+    stages {
+        stage('Example') {
+            steps {
+                script {
+                    setupTestkube()
+                    sh 'testkube run testworkflow TEST_WORKFLOW_NAME'
+                }
+            }
+        }
+    }
+}
+```
+
+The steps to connect to your Kubernetes cluster differ for each provider. You should check the docs of your Cloud provider for how to connect to the Kubernetes cluster from Jenkins CI/CD.