Setup and Configuration Guide - Jenkins as Code

Step-by-step guide to setting up Jenkins as Code automation framework

Updated Jan 15, 2024
9 min read
Intermediate
tools

Setup and Configuration Guide

Step-by-step guide to setting up Jenkins as Code automation framework

📋 Table of Contents

🔧 Prerequisites

System Requirements

Server Requirements

  • OS: Amazon Linux 2023 / Amazon Linux 2 (ARM64 or x86_64)
  • CPU: Minimum 2 cores, recommended 4+ cores
  • RAM: Minimum 4GB, recommended 8GB+
  • Disk: Minimum 50GB, recommended 100GB+
  • Network: Internet access for plugin downloads

Software Requirements

  • Ansible: 2.9 or higher
  • Python: 3.8 or higher
  • Git: Latest version
  • Docker: For containerized builds (optional)
  • AWS CLI: For ECR/ECS integration (optional)

Access Requirements

  • SSH access to target server
  • Sudo/root privileges
  • Git repository access
  • AWS credentials (if using AWS services)

Network Requirements

  • Outbound HTTPS (443) for plugin downloads
  • Outbound SSH (22) for Git operations
  • Inbound HTTPS (443) for Jenkins web UI
  • Inbound SSH (22) for server management

🚀 Initial Setup

Step 1: Clone Repositories

# Clone mCloud-infra (Ansible automation)
git clone https://github.com/HarryTheDevOpsGuy/mCloud-infra.git
cd mCloud-infra/ansible

# Clone mCloud-Jenkins (Jenkins configs)
git clone https://github.com/HarryTheDevOpsGuy/mCloud-Jenkins.git
cd ../mCloud-Jenkins

Step 2: Configure Ansible Variables

Edit the Ansible group variables file:

cd ../mCloud-infra/ansible
vim group_vars/packer_al2023_aarch64_devops_jenkins.yml

Essential Configuration

# Jenkins Version
jenkins_version: 2.528.2

# Jenkins Home Directory
jenkins_home: "/var/lib/jenkins"

# Jenkins Plugins
jenkins_plugins:
  - docker-slaves
  - docker-workflow
  - ansicolor
  - google-login
  - aws-java-sdk-secretsmanager
  - favorite

# Jenkins URL
jenkins_location:
  url: "https://jenkins.mcloud.com/"
  adminAddress: "mcloud-jenkins@mcloud.com"

# Security Configuration
jenkins_securityRealm:
  local:
    allowsSignup: false
    users:
      - id: "admin"
        name: "admin"
        password: "Admin@123"  # Change this!

Step 3: Configure User Access

Define User Roles

# Read Users
overall_read_users:
  amazon:
    mcloud:
      - user: "dev"
    qa:
      - user: "qa-user"

# Write Users
overall_write_users:
  devops_users: []

# Admin Users
overall_admin_users:
  devops_managers:
    - user: "Harry"
    - user: "admin"

Step 4: Configure Onboarding Projects

jenkins_onboarding:
  amazon:
    common:
      jobs:
        - NAME: "0-JobGenie-Generator"
          PARAMETERS:
            - { name: 'GitBranch', string: 'master', description: 'Dev application git branch.' }
          VARS:
            CONFIG_BRANCH: "master"
            CONFIG_REPO: "https://github.com/HarryTheDevOpsGuy/mCloud-Jenkins.git"
            JENKINS_GIT_KEY: 'jenkins_repo_key'
    mcloud:
      jobs:
        - NAME: "0-mCloud-DevOps"
          PARAMETERS:
            - { name: 'GitBranch', string: 'master', description: 'Dev application git branch.' }
          VARS:
            CONFIG_REPO: "https://github.com/HarryTheDevOpsGuy/mCloud-Jenkins.git"
            JENKINS_GIT_KEY: 'jenkins_repo_key'
      env: ["nonprod", "prod"]

Step 5: Run Ansible Playbook

# Test connection first
ansible-playbook packer.yml \
  -e "target_host=packer_al2023_aarch64_devops_jenkins" \
  --check

# Run full deployment
ansible-playbook packer.yml \
  -e "target_host=packer_al2023_aarch64_devops_jenkins" \
  -t deploy,monitoring

Playbook Tags

  • deploy: Jenkins installation and configuration
  • monitoring: Monitoring stack setup
  • install_stacks: Install specific stacks only

⚙️ Jenkins Configuration

Step 1: Access Jenkins

  1. Open browser: https://jenkins.mcloud.com/
  2. Login with admin credentials
  3. Verify Configuration as Code is loaded

Step 2: Verify Configuration

Check System Configuration

  • Navigate to: Manage Jenkins → System Information
  • Verify:
    • Jenkins version
    • Number of executors
    • Plugin versions

Check Security Configuration

  • Navigate to: Manage Jenkins → Configure Global Security
  • Verify:
    • Security realm configured
    • Authorization strategy (Role-Based)
    • Roles and permissions

Step 3: Configure Credentials

Add Git Credentials

  1. Navigate to: Manage Jenkins → Credentials
  2. Add SSH key credential:
    • Kind: SSH Username with private key
    • ID: jenkins_repo_key
    • Username: git
    • Private Key: Upload or paste SSH key

Add AWS Credentials (if needed)

  1. Add AWS credentials:
    • Kind: AWS Credentials
    • ID: aws_credentials
    • Access Key ID: Your AWS access key
    • Secret Access Key: Your AWS secret key

Step 4: Verify Seed Jobs

  1. Navigate to: amazon/common/0-JobGenie-Generator
  2. Verify job exists and is configured
  3. Run job to generate initial jobs

🎩 JobGenie Setup

Step 1: Create JobGenie Configuration

Create or edit JobGenie file:

cd mCloud-Jenkins
vim amazon/mcloud/nonprod/pipelines/jobs/JobGenie.groovy

Step 2: Define Default Configurations

def defaultConfigs = [
    // Required variables
    EKS_CLUSTER_NAME: "${defaultConfigs.PROJECT_NAME}-eks-${defaultConfigs.PROJECT_ENV}",
    CICD_TEMPLATE_BASE: 'templates/cicd',
    CICD_BASE: "${defaultConfigs.HOME_DIR}/jenkinsfiles",
    VALUES_YMLBASE: "${defaultConfigs.HOME_DIR}/helm-values",
    IMAGE_ECR: "${globalConfigs.awsAccountId}.dkr.ecr.${globalConfigs.region}.amazonaws.com",
    
    // Optional variables
    GROUP: "v2",
    ENV: "stage",
    HOSTED_ZONE: 'example.com',
    APP_PORT: '8080',
    ARGOCD_ENDPOINT: 'argocd.example.com'
]

Step 3: Define JobGenie Map

def jobGenie = [
    "mcloud": [
        [
            APP_REPO: 'my-application',
            APP_BRANCH: 'master',
            appNames: ['my-service']
        ]
    ]
]

Step 4: Commit and Push

git add amazon/mcloud/nonprod/pipelines/jobs/JobGenie.groovy
git commit -m "Initial JobGenie configuration"
git push origin master

Step 5: Run Seed Job

  1. Navigate to: amazon/mcloud/nonprod/0-mCloud-DevOps
  2. Click Build with Parameters
  3. Set GitBranch to your branch
  4. Click Build
  5. Monitor job execution
  6. Verify jobs are created

✅ Verification

Checklist

Infrastructure Verification

  • Jenkins server accessible
  • HTTPS working
  • All plugins installed
  • Monitoring stack running

Configuration Verification

  • Configuration as Code loaded
  • Security configured correctly
  • Credentials added
  • Global libraries configured

Job Generation Verification

  • Seed jobs exist
  • Seed jobs run successfully
  • Jobs generated correctly
  • Job folders created

Access Verification

  • Admin can access all features
  • Users have correct permissions
  • Role-based access working
  • Audit trail enabled

Test Job Execution

  1. Create Test Job 
    def jobGenie = [
 "mcloud": [
     [
         APP_REPO: 'test-app',
         APP_BRANCH: 'master',
         appNames: ['test-service']
     ]
 ]
]
  2. Run Seed Job
  3. Verify Job Created
  4. Run Generated Job
  5. Check Build Logs

🔐 Post-Setup Configuration

1. Configure Monitoring

Verify Monitoring Stack

# Check Telegraf
systemctl status telegraf

# Check Filebeat
systemctl status filebeat

Configure Log Aggregation

  • Set up ELK stack endpoint
  • Configure Filebeat output
  • Verify log shipping

2. Configure Backup

S3 Backup Configuration

jenkins_s3_backup_dir: "s3://bucket-name/path/to/backup"

Automated Backup

  • Set up cron job for backups
  • Configure backup retention
  • Test restore procedure

3. Configure Notifications

Slack Integration

jenkins_slack_notifier:
  botUser: false
  room: "devops-alerts"
  teamDomain: "https://example.slack.com/"
  tokenCredentialId: "SlackToken"

Email Configuration

  • Configure SMTP settings
  • Set up email notifications
  • Test email delivery

4. Configure External Integrations

ArgoCD Integration

  • Configure ArgoCD endpoint
  • Set up credentials
  • Test deployment workflow

ECR Integration

  • Configure AWS credentials
  • Set up ECR repositories
  • Test image push/pull

🔧 Troubleshooting

Issue 1: Ansible Playbook Fails

Symptoms: Playbook execution fails

Solutions:

# Check connectivity
ansible target_host -m ping

# Run with verbose output
ansible-playbook packer.yml -e "target_host=..." -vvv

# Check Ansible version
ansible --version

Issue 2: Jenkins Not Accessible

Symptoms: Cannot access Jenkins web UI

Solutions:

# Check Jenkins service
systemctl status jenkins

# Check port
netstat -tlnp | grep 8080

# Check firewall
firewall-cmd --list-ports

# Check logs
tail -f /var/log/jenkins/jenkins.log

Issue 3: Configuration Not Applied

Symptoms: Changes not reflected in Jenkins

Solutions:

  1. Reload Configuration as Code:
    • Navigate to: amazon/manage-infra/Reload-ConfigAsCode
    • Run job
  2. Check Configuration as Code:
    • Navigate to: Manage Jenkins → Configuration as Code
    • View current configuration
  3. Verify Ansible variables:
    • Check variable file syntax
    • Verify template rendering

Issue 4: Jobs Not Generated

Symptoms: Seed job runs but no jobs created

Solutions:

  1. Check JobGenie syntax: 
    // Verify map structure
def jobGenie = [ /* ... */ ]
  2. Check seed job logs:
    • View console output
    • Look for errors
  3. Verify file paths:
    • Check JobGenie file location
    • Verify file permissions

Issue 5: Permission Denied

Symptoms: Users cannot access jobs

Solutions:

  1. Check role configuration: 
    overall_read_users:
  amazon:
    mcloud:
      - user: "username"
  2. Verify pattern matching:
    • Check job path patterns
    • Verify role patterns
  3. Test permissions:
    • Login as test user
    • Verify access

📚 Next Steps

After setup is complete:

  1. Onboard First Team
    • Create JobGenie configuration
    • Run seed job
    • Verify jobs created
  2. Create Documentation
    • Team-specific guides
    • Runbooks
    • Troubleshooting guides
  3. Set Up Monitoring
    • Configure alerts
    • Set up dashboards
    • Review metrics
  4. Plan Scaling
    • Identify additional teams
    • Plan onboarding schedule
    • Allocate resources

📚 Additional Resources

📖 Related Documentation

🧭 Navigation

Related Topics:

Maintained by the DevOps Team

Tags: #Jenkins #Setup #Configuration #Ansible #CI/CD #Automation

Related Documentation

More from Tools

BG Deployer

Automated blue-green deployment for zero-downtime AWS releases
mCert

SSL certificate monitoring with Slack/email alerts & Telegram

Related by Tags

No related documentation found by tags

Related Blog Posts

OpenResty Production Setup: Supercharge with Lua-Based Metrics and Monitoring

Complete guide to deploying production-ready OpenResty with advanced Lua-based metrics collection...

Oct 16, 2024

KEDA on EKS: Complete Guide to Event-Driven Autoscaling with Real-World Examples

Master KEDA implementation on Amazon EKS with comprehensive examples for multiple scaling scenari...

Oct 15, 2024

AIOps: AI-Powered DevOps Automation and Intelligent Operations

Comprehensive guide to implementing AIOps - using AI and machine learning to transform DevOps pra...

Oct 14, 2024

Related Tools & Projects

BG Deployer

Automated blue-green deployment for zero-downtime AWS releases

AWS Blue-Green

mCert

SSL certificate monitoring with Slack/email alerts & Telegram

SSL Telegram

mTracker

Real-time Linux user activity monitoring with Slack notifications

Linux Monitoring

mWatcher

Server health monitoring for CPU, memory, disk with alerting

Health Alerts

gCrypt

Git-crypt wrapper for secure file encryption & access management

Security Git-crypt

Interactive Tools

AWS VPC Designer, EKS Cost Calculator, and more utilities

Tools Calculator

External Resources

Official Documentation

AWS Documentation

Complete AWS service documentation

Community Resources

GitHub Profile

Open source projects and repositories
LinkedIn

Professional network and updates
Dev.to

Technical articles and tutorials
Contact

Get in touch for questions or collaboration

Quick Actions

All Docs

Browse all documentation

Blog

Latest articles

Tools

DevOps utilities

Portfolio

My work & projects

Found this helpful?

Help us improve this documentation by sharing your feedback or suggesting improvements.

Report Issue Start Discussion