Keycloak Environment with Kind & Crossplane

This project demonstrates modern identity management deployment using Kubernetes, showcasing Keycloak deployment with Crossplane for infrastructure as code.

🏗️ Project Structure

keycloak-presentation/
├── .kubernetes/              # Kubernetes manifests with Kustomize
│   ├── base/
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── postgres/
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   └── kustomization.yaml
│   │   └── keycloak/
│   │       ├── crossplane-release.yaml
│   │       ├── ingress.yaml
│   │       └── kustomization.yaml
│   ├── overlays/
│   │   ├── development/
│   │   │   ├── kustomization.yaml
│   │   │   └── keycloak-dev-config.yaml
│   │   └── production/
│   │       ├── kustomization.yaml
│   │       └── keycloak-prod-config.yaml
│   └── cluster-setup/
│       ├── kind-config.yaml
│       ├── crossplane-config.yaml
│       └── ingress-nginx.yaml
├── Makefile                  # Automation commands
└── README.md                 # This file

🚀 Technologies Used

Core Infrastructure

Kind - Kubernetes in Docker for local development
Kubernetes - Container orchestration platform
Kustomize - Kubernetes configuration management
Helm - Kubernetes package manager

Identity Management

Keycloak - Open-source identity and access management
PostgreSQL - Database for Keycloak

Infrastructure as Code

Crossplane - Kubernetes-native infrastructure management
Crossplane Provider Helm - Helm chart deployment via Crossplane

Networking

NGINX Ingress Controller - Ingress controller for Kind

📋 Prerequisites

System Requirements

Docker 20.10+
8GB+ RAM
20GB+ free disk space
Linux, macOS, or Windows with WSL2

Required Tools

Install all tools automatically:

make install-tools

Or install manually:

Docker
Kind
kubectl
Helm
Node.js 18+
npm

🎯 Quick Start

1. Complete Setup (Recommended)

# Setup everything for presentation
make presentation-ready

2. Verification

# Check all components
make status

# Test Keycloak accessibility
make test-keycloak

# View logs if needed
make logs

🔧 Available Commands

Cluster Management

make create-cluster          # Create Kind cluster
make delete-cluster          # Delete Kind cluster
make cluster-info           # Show cluster information
make install-ingress        # Install NGINX Ingress Controller

Crossplane Operations

make install-crossplane      # Install Crossplane
make configure-crossplane    # Configure Crossplane providers
make uninstall-crossplane    # Remove Crossplane
make test-crossplane        # Test Crossplane resources

Keycloak Deployment

make create-namespace       # Create keycloak namespace
make deploy-postgres        # Deploy PostgreSQL database
make deploy-keycloak        # Deploy Keycloak via Crossplane
make setup-hosts           # Add keycloak.local to /etc/hosts
make port-forward          # Port forward Keycloak service
make reset-keycloak        # Reset Keycloak deployment

Monitoring & Debugging

make status                # Show status of all components
make logs                  # Show Keycloak logs
make describe-keycloak     # Describe Keycloak release
make troubleshoot          # Run troubleshooting checks
make versions              # Show tool versions

Cleanup

make cleanup-keycloak      # Remove Keycloak resources
make cleanup-configs       # Remove generated config files
make cleanup-all           # Complete cleanup

Quick Commands

make quick-setup           # Setup cluster, ingress, Crossplane
make full-demo            # Complete demo environment
make presentation-ready    # Everything ready for presentation

🎨 Kustomize Structure

Base Configuration

Located in .kubernetes/base/, contains:

namespace.yaml - Keycloak namespace definition
postgres/ - PostgreSQL deployment and service
keycloak/ - Keycloak Crossplane release and ingress

Overlays

development/ - Development-specific configurations
production/ - Production-ready configurations

Usage

# Apply development configuration
kubectl apply -k .kubernetes/overlays/development

# Apply production configuration
kubectl apply -k .kubernetes/overlays/production

# Apply base configuration
kubectl apply -k .kubernetes/base

🌐 Access Points

Keycloak

URL: https://keycloak.local:8443
Admin Console: https://keycloak.local:8443/admin/master/console
Username: admin
Password: admin

📊 Presentation Structure (30 minutes)

https://gamma.app/docs/Bring-Your-Own-Identity-System-Boardwalk-Bytes-2025-fh76lhzu0gnqj8p

🔍 Troubleshooting

Common Issues

Cluster Not Accessible

# Check cluster status
make cluster-info

# Verify context
kubectl config current-context

# Should be: kind-keycloak-demo
kubectl config use-context kind-keycloak-demo

Ingress Not Working

# Check ingress controller
kubectl get pods -n ingress-nginx

# Check ingress resources
kubectl get ingress -n keycloak

# Use port-forward as alternative
make port-forward

Crossplane Issues

# Check Crossplane status
make test-crossplane

# Check provider health
kubectl get providers

# View provider details
kubectl describe provider provider-helm

Keycloak Not Starting

# Check pod status
kubectl get pods -n keycloak

# View logs
make logs

# Check database connection
kubectl exec -it -n keycloak deployment/postgres -- psql -U keycloak -d keycloak -c '\l'

Debug Commands

# Comprehensive troubleshooting
make troubleshoot

# Monitor all resources
watch kubectl get all -n keycloak

# Check events
kubectl get events -n keycloak --sort-by=.metadata.creationTimestamp

🔐 Security Considerations

Development Environment

Default passwords for demo purposes
No TLS encryption
Local cluster only

Production Recommendations

Use strong, unique passwords
Enable TLS with proper certificates
Implement network policies
Regular security updates
Backup and disaster recovery procedures

📚 Learning Resources

Official Documentation

Tutorials & Guides

🤝 Contributing

Development Workflow

Fork the repository
Create feature branch
Make changes
Test with make presentation-ready
Submit pull request

Testing Changes

# Clean environment
make cleanup-all

# Test full setup
make presentation-ready

# Verify all components
make status
make test-keycloak

📄 License

This project is for educational and demonstration purposes. Individual components are licensed under their respective licenses:

Keycloak: Apache License 2.0
Crossplane: Apache License 2.0
Kubernetes: Apache License 2.0

Ready to get started? Run make presentation-ready to set up everything for your presentation!

For questions or issues, please check the troubleshooting section or open an issue in the repository.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.kubernetes		.kubernetes
scripts		scripts
Makefile		Makefile
README.md		README.md

cmaenner/keycloak-getting-started

Folders and files

Latest commit

History

Repository files navigation