Skip to content

Instantly share code, notes, and snippets.

@0511Cynthia

0511Cynthia/Jenkins-X-Installation-Manual.md

Last active December 10, 2025 21:28
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save 0511Cynthia/e0a4e3767f8f148c090100246eaa66ca to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save 0511Cynthia/e0a4e3767f8f148c090100246eaa66ca to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Jenkins-X-Installation-Manual.md

Jenkins X Installation Manual

Ubuntu 22.04 – Complete Guide
Version 1.0 | November 2025
Author: Cynthia Vázquez
Status: Production Ready

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Jenkins X CLI Installation
  4. Environment Configuration
  5. Cluster Installation
  6. Troubleshooting
  7. Credentials and Access
  8. Dashboard Configuration
  9. Verification
  10. Quick Command Reference
  11. References

Introduction

Jenkins X is a Kubernetes-native CI/CD automation platform designed to streamline development, build, and deployment workflows. This manual provides a complete installation and configuration guide for deploying Jenkins X on a K3s Kubernetes cluster.

What Jenkins X Provides

  • Automated pipelines
  • Preview environments
  • Automatic promotion between environments
  • GitOps integration
  • Native GitHub support

Prerequisites

System Requirements

  • K3s cluster: 1 master + 2 worker nodes
  • kubectl: Configured and working
  • GitHub account: With admin rights
  • Resources: Minimum 4GB RAM, 20GB disk space
  • Network: Internet connectivity

GitHub Token Setup

Create a Personal Access Token with these permissions:

  • repo (full access)
  • admin:repo_hook (webhooks)
  • admin:org_hook (if using organization)
  • user (profile access)

Go to: GitHub → Settings → Developer settings → Personal access tokens → Generate new token

Jenkins X CLI Installation

Linux

# Download and install
curl -L https://github.com/jenkins-x/jx/releases/latest/download/jx-linux-amd64.tar.gz | tar xzv
sudo mv jx /usr/local/bin/

# Verify installation
jx version

macOS

# Install with Homebrew
brew install jenkins-x/jx/jx

# Verify installation
jx version

Environment Configuration

Set Environment Variables

export GIT_USERNAME="your_github_username"
export GIT_TOKEN="your_personal_access_token"
export GIT_SERVER="https://github.com"
export GIT_KIND="github"
export GIT_ORGANISATION="your_organization_or_username"

Make Permanent (add to ~/.bashrc or ~/.zshrc)

echo 'export GIT_USERNAME="your_github_username"' >> ~/.bashrc
echo 'export GIT_TOKEN="your_token"' >> ~/.bashrc
echo 'export GIT_SERVER="https://github.com"' >> ~/.bashrc
echo 'export GIT_KIND="github"' >> ~/.bashrc
echo 'export GIT_ORGANISATION="your_org"' >> ~/.bashrc

# Apply changes
source ~/.bashrc

Verify Configuration

echo $GIT_USERNAME
echo $GIT_ORGANISATION
# Don't echo $GIT_TOKEN for security

Cluster Installation

Option 1: Basic Installation

jx install --provider=kubernetes

Option 2: With Custom Domain

jx install --provider=kubernetes --domain=your-domain.com

Option 3: Local Development Mode (no domain)

jx install --provider=kubernetes \
  --ingress-service=LoadBalancer \
  --no-default-environments=false

Monitor Installation Progress

# Watch pods in real-time
watch kubectl get pods -n jx

# View specific pod logs
kubectl logs -f <pod-name> -n jx

Troubleshooting

Issue 1: ingress-nginx Pod Stuck in Pending

Symptoms:

  • Pod stays in "Pending" state
  • Installation hangs
  • Endpoints not recognized

Diagnosis:

kubectl get pods -n ingress-nginx
kubectl describe pod <ingress-pod> -n ingress-nginx
kubectl get events -n ingress-nginx --sort-by='.lastTimestamp'

Solutions:

Check Resources:

kubectl top nodes
# If saturated: increase resources or add nodes

Check LoadBalancer:

kubectl get svc -n ingress-nginx
# If EXTERNAL-IP is <pending>, use Traefik instead (K3s default)
kubectl get pods -n kube-system | grep traefik

Issue 2: Webhook and Controller Pods Not Starting

Symptoms:

  • Webhook/controller pods fail to start
  • Dashboard not accessible

Solution:

# Identify problematic pods
kubectl get pods -n jx | grep -E 'webhook|controller'

# Delete them (they'll auto-recreate)
kubectl delete pod <webhook-pod-name> -n jx
kubectl delete pod <controller-pod-name> -n jx

# Monitor recreation
watch kubectl get pods -n jx

# Check new pod logs
kubectl logs -f <new-pod> -n jx

General Status Check

# View all resources
kubectl get all -n jx

# Check ingress status
kubectl get ingress -n jx
kubectl get svc -n jx

# Verify ingress has address
kubectl get ingress -n jx jx-pipelines-visualizer

Credentials and Access

Check if Credentials Exist

kubectl get secret -n jx jx-basic-auth-user-password -o yaml

Retrieve Existing Credentials

Get Username:

kubectl get secret -n jx jx-basic-auth-user-password \
  -o jsonpath='{.data.username}' | base64 -d
echo ""

Get Password:

kubectl get secret -n jx jx-basic-auth-user-password \
  -o jsonpath='{.data.password}' | base64 -d
echo ""

Create New Credentials (if secret doesn't exist)

# Define credentials
USERNAME="admin"
PASSWORD="SecurePassword123!"  # Use a strong password

# Create secret
kubectl create secret generic jx-basic-auth-user-password \
  -n jx \
  --from-literal=username=$USERNAME \
  --from-literal=password=$PASSWORD

# Verify
kubectl get secret -n jx jx-basic-auth-user-password

Update Credentials

# Delete existing secret
kubectl delete secret jx-basic-auth-user-password -n jx

# Create new one
USERNAME="new_admin"
PASSWORD="NewSecurePassword456!"

kubectl create secret generic jx-basic-auth-user-password \
  -n jx \
  --from-literal=username=$USERNAME \
  --from-literal=password=$PASSWORD

Dashboard Configuration

Get Dashboard URL

# Using jx command
jx get urls -n jx

# Or directly from ingress
kubectl get ingress -n jx jx-pipelines-visualizer \
  -o jsonpath='{.spec.rules[0].host}'
echo ""

Access Dashboard Locally (Port-Forward)

# Forward service to local port
kubectl port-forward -n jx svc/jx-pipelines-visualizer 8080:80

# Access at: http://localhost:8080

View Ingress Configuration

# Full configuration
kubectl get ingress -n jx jx-pipelines-visualizer -o yaml

# View annotations
kubectl get ingress -n jx jx-pipelines-visualizer -o yaml \
  | grep -A 5 annotations

Enable HTTPS (Optional)

Install cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

Create Let's Encrypt ClusterIssuer

cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

Configure Basic Auth in Ingress

# Check auth annotations
kubectl get ingress -n jx jx-pipelines-visualizer -o yaml | grep -i auth

# Edit if needed
kubectl edit ingress jx-pipelines-visualizer -n jx

# Required annotations:
# nginx.ingress.kubernetes.io/auth-type: "basic"
# nginx.ingress.kubernetes.io/auth-secret: "jx-basic-auth-user-password"
# nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"

Verification

Check All Pods

kubectl get pods -n jx

# Expected output (all Running):
# NAME                                    READY   STATUS    RESTARTS   AGE
# jx-pipelines-visualizer-xxx             1/1     Running   0          10m
# jx-build-controller-xxx                 1/1     Running   0          10m
# lighthouse-webhooks-xxx                 1/1     Running   0          10m
# lighthouse-keeper-xxx                   1/1     Running   0          10m

Access Dashboard

  1. Get URL: jx get urls -n jx
  2. Open in browser
  3. Enter credentials
  4. Verify you can see pipelines and repositories

Test Basic Pipeline

# Create a quickstart project
jx create quickstart

# Follow wizard:
# - Select language (e.g., golang-http)
# - Enter project name
# - Confirm GitHub organization

# Monitor pipeline
jx get activity -w

# View build logs
jx get build logs

Quick Command Reference

Management Commands

jx version                    # Check version
jx get urls -n jx            # Get service URLs
jx get activity              # View pipeline activity
jx get build logs            # View build logs
jx get applications          # View deployed apps
jx import                    # Import existing project
jx create quickstart         # Create new project

Diagnostic Commands

kubectl get nodes                     # Check cluster nodes
kubectl get pods -n jx               # Check Jenkins X pods
kubectl get svc -n jx                # Check services
kubectl get ingress -n jx            # Check ingress
kubectl logs -f <pod-name> -n jx     # View pod logs
jx get git                           # Check Git config
jx diagnose                          # Run diagnostics

Cleanup Commands

jx uninstall                         # Remove Jenkins X
kubectl delete namespace jx          # Delete namespace
kubectl delete secret -n jx --all    # Delete all secrets

References

Official Documentation

Guides and Tutorials

Community

Final Notes

Important Reminders

  • Store credentials securely
  • Use strong passwords in production
  • Configure HTTPS for public-facing dashboards
  • Regular backups of configuration
  • Monitor cluster resource usage

Next Steps

  1. Configure your first pipeline
  2. Set up GitHub webhooks
  3. Create staging and production environments
  4. Implement deployment strategies (blue-green, canary)
  5. Configure monitoring and alerts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment