intermediategeneral

How do you implement a Jenkins pipeline for Kubernetes deployments?

⚡

Quick Answer

A Jenkins pipeline for Kubernetes deployments uses stages to build container images, push them to a registry, and apply Kubernetes manifests or Helm charts to target clusters, often using kubectl or Helm commands with proper credential management and rollback strategies.

Detailed Answer

Deploying to Kubernetes through Jenkins is like a shipping company with an automated warehouse system. The factory (build stage) produces goods and packages them in standardized containers (Docker images). The containers are stored in a warehouse (container registry) with tracking labels (image tags). When an order comes in (deployment trigger), the automated system (Jenkins pipeline) retrieves the right container from the warehouse and places it on the correct shipping dock (Kubernetes namespace). If the container is damaged (failed health check), the system automatically swaps it with the previous working container (rollback). The entire process is tracked and auditable through shipping manifests (Kubernetes deployment YAML and Jenkins build logs).

A Jenkins pipeline for Kubernetes deployments typically follows a multi-stage workflow: build the application, run tests, create a Docker image, push the image to a container registry, update Kubernetes manifests with the new image tag, apply the manifests to the cluster, and verify the deployment health. The pipeline interacts with Kubernetes using kubectl commands, Helm chart upgrades, or Kustomize overlays. Authentication to the Kubernetes cluster is handled through kubeconfig files or service account tokens stored as Jenkins credentials. For multi-environment deployments, the pipeline promotes the same Docker image through staging, UAT, and production namespaces, changing only the environment-specific configuration.

Internally, when the pipeline executes a kubectl or helm command, it communicates with the Kubernetes API server over HTTPS. The Kubernetes API server authenticates the request using the provided credentials, authorizes it against RBAC policies, and then processes the resource changes through the admission controller chain. For deployments, Kubernetes creates new ReplicaSets with the updated image tag and performs a rolling update by gradually scaling up new pods while scaling down old pods. The pipeline monitors this process through rollout status commands that track the deployment's progress by querying the Kubernetes API for pod readiness conditions and replica counts. If the rollout stalls, the pipeline can trigger an automatic rollback to the previous revision.

In production environments, teams implement several safety mechanisms in their Kubernetes deployment pipelines. Canary deployments route a small percentage of traffic to the new version before full rollout, using tools like Flagger or Argo Rollouts integrated with the Jenkins pipeline. Blue-green deployments maintain two identical environments and switch traffic atomically using Kubernetes service selectors. The pipeline should include post-deployment verification steps that check application health endpoints, run smoke tests against the deployed service, and validate key metrics from monitoring systems. Namespace-based environment isolation ensures that staging deployments cannot accidentally affect production, and resource quotas prevent runaway deployments from consuming cluster resources.

A critical gotcha is image tag mutability. Using a mutable tag like latest means that Kubernetes might not pull the new image if it believes the tag has not changed, because the image pull policy defaults to IfNotPresent for tags other than latest. Always use immutable, unique tags like Git commit SHAs or build numbers to ensure Kubernetes pulls the correct image. Another common mistake is not setting resource requests and limits in the deployment manifests, which can cause pods to be evicted under resource pressure or to consume excessive cluster resources. Teams should also implement proper RBAC so that the Jenkins service account has only the minimum permissions needed for deployments, never cluster-admin access.

// Jenkinsfile for order-service Kubernetes deployment pipeline pipeline { // Run on an agent with Docker and kubectl installed agent { label 'kubernetes-deployer' } // Define environment variables for the pipeline environment { // Name of the microservice being deployed SERVICE = 'order-service' // Container registry URL REGISTRY = 'registry.company.com' // Generate image tag from build number and short commit hash IMAGE_TAG = "${BUILD_NUMBER}-${GIT_COMMIT[0..6]}" // Full image reference used throughout the pipeline IMAGE = "${REGISTRY}/${SERVICE}:${IMAGE_TAG}" // Kubernetes namespace for staging deployments STAGING_NS = 'staging' // Kubernetes namespace for production deployments PROD_NS = 'production' } // Define the deployment pipeline stages stages { // Build the application artifact stage('Build') { steps { // Check out source code from version control checkout scm // Compile the application using Gradle sh './gradlew clean build -x test' } } // Run the full test suite before containerizing stage('Test') { steps { // Execute unit and integration tests sh './gradlew test integrationTest' // Publish test results to Jenkins dashboard junit 'build/test-results/**/*.xml' } } // Build and push the Docker image to the registry stage('Docker Build and Push') { steps { // Build the Docker image with the unique tag sh "docker build -t ${IMAGE} ." // Authenticate with the Docker registry using credentials withCredentials([usernamePassword( credentialsId: 'docker-registry-creds', usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS' )]) { // Log in to the container registry securely sh "echo ${DOCKER_PASS} | docker login ${REGISTRY} -u ${DOCKER_USER} --password-stdin" // Push the tagged image to the registry sh "docker push ${IMAGE}" } } } // Deploy to the staging Kubernetes cluster stage('Deploy to Staging') { steps { // Inject kubeconfig for staging cluster access withCredentials([file(credentialsId: 'staging-kubeconfig', variable: 'KUBECONFIG')]) { // Apply Kubernetes manifests using Kustomize with image override sh "kubectl set image deployment/${SERVICE} ${SERVICE}=${IMAGE} -n ${STAGING_NS}" // Wait for the rollout to complete within timeout sh "kubectl rollout status deployment/${SERVICE} -n ${STAGING_NS} --timeout=300s" // Verify the deployed pods are running and ready sh "kubectl get pods -l app=${SERVICE} -n ${STAGING_NS}" } } } // Run smoke tests against the staging deployment stage('Staging Verification') { steps { // Check the health endpoint of the staged service sh "curl -sf http://order-service.staging.svc.cluster.local/health" // Run API smoke tests against staging sh './gradlew smokeTest -Penv=staging' } } // Require manual approval before production deployment stage('Production Approval') { // Only gate production deploys on main branch when { branch 'main' } steps { // Prompt an authorized user for deployment approval input message: 'Deploy order-service to production?', submitter: 'deploy-approvers' } } // Deploy to the production Kubernetes cluster stage('Deploy to Production') { // Only deploy to production from main branch when { branch 'main' } steps { // Inject kubeconfig for production cluster access withCredentials([file(credentialsId: 'prod-kubeconfig', variable: 'KUBECONFIG')]) { // Use Helm to upgrade the production release sh """ helm upgrade --install ${SERVICE} ./helm/${SERVICE} \\ --namespace ${PROD_NS} \\ --set image.repository=${REGISTRY}/${SERVICE} \\ --set image.tag=${IMAGE_TAG} \\ --set replicaCount=3 \\ --set resources.requests.memory=512Mi \\ --set resources.requests.cpu=250m \\ --set resources.limits.memory=1Gi \\ --set resources.limits.cpu=500m \\ --wait --timeout=600s """ // Verify production pods are healthy after deploy sh "kubectl get pods -l app=${SERVICE} -n ${PROD_NS}" // Run production smoke test to validate the release sh "curl -sf http://order-service.production.svc.cluster.local/health" } } } } // Post-build actions for notification and rollback post { // Handle deployment failure with automatic rollback failure { // Rollback production deployment on failure sh "helm rollback ${SERVICE} 0 --namespace ${PROD_NS} || true" // Notify the team about the failed deployment slackSend channel: '#order-team', message: "${SERVICE} deployment ${IMAGE_TAG} FAILED - rolled back" } // Notify the team on successful deployment success { // Send success notification with deployed version slackSend channel: '#order-team', message: "${SERVICE} ${IMAGE_TAG} deployed to production successfully" } } }

How do you implement a Jenkins pipeline for Kubernetes deployments?

More Jenkins questions