How To Install KubeSphere on Manjaro

Installing KubeSphere on Manjaro Linux provides developers and system administrators with a powerful enterprise-grade container platform built on Kubernetes. This comprehensive guide walks you through the entire installation process, from initial system preparation to post-deployment configuration and optimization.

KubeSphere stands out as a distributed operating system that simplifies Kubernetes management through its intuitive web console and extensive feature set. When combined with Manjaro’s rolling release model and cutting-edge package availability, it creates an ideal environment for cloud-native application development and deployment.

Whether you’re setting up a development environment or preparing a production-ready container platform, this tutorial covers every aspect of the installation process. You’ll learn how to configure your Manjaro system, handle dependencies, execute the installation, and verify successful deployment. Additionally, we’ll explore troubleshooting techniques specific to Manjaro and optimization strategies for enhanced performance.

Understanding KubeSphere: Features and Capabilities

Core Platform Architecture

KubeSphere operates as a comprehensive container management platform that abstracts the complexity of Kubernetes while providing enterprise-grade features. The platform offers multi-tenant management capabilities with fine-grained role-based access control (RBAC), enabling organizations to securely manage multiple teams and projects within a single cluster.

The architecture includes built-in DevOps pipeline integration through Jenkins, allowing seamless continuous integration and deployment workflows. Service mesh capabilities, powered by Istio, provide advanced traffic management, security policies, and observability features for microservices architectures.

Cloud-native observability remains a cornerstone feature, incorporating comprehensive monitoring, logging, and alerting systems. The platform includes Prometheus for metrics collection, Fluent Bit for log aggregation, and Grafana for visualization, creating a complete observability stack without additional configuration.

Enterprise-Grade Management Features

KubeSphere’s multi-cluster management capabilities enable centralized control of distributed Kubernetes environments across different cloud providers or on-premises infrastructure. This feature proves invaluable for organizations implementing hybrid cloud strategies or managing geographically distributed deployments.

Edge computing integration through KubeEdge extends Kubernetes capabilities to edge devices, supporting Internet of Things (IoT) scenarios and edge computing workloads. The platform handles edge node management, application distribution, and data synchronization between cloud and edge environments automatically.

Resource metering and billing functionality provides detailed tracking of cluster resource consumption, enabling accurate cost allocation and capacity planning. This enterprise feature supports chargeback mechanisms and helps organizations optimize their container infrastructure investments.

System Requirements and Hardware Specifications

Minimum Hardware Configuration

Successfully running KubeSphere on Manjaro requires careful attention to system specifications. The minimum configuration includes a dual-core processor with at least 4GB of RAM and 40GB of available disk space. However, these specifications only support basic functionality and small-scale deployments.

Network connectivity requirements include stable internet access for downloading container images and accessing external repositories. Specific port requirements include TCP port 30880 for web console access, along with standard Kubernetes ports for cluster communication.

Storage considerations extend beyond basic disk space requirements. KubeSphere benefits from fast storage subsystems, particularly SSD-based storage for etcd and container runtime operations. Network-attached storage or distributed storage systems can enhance scalability and reliability for production environments.

Recommended Production Specifications

Production deployments demand significantly more resources for optimal performance and scalability. The recommended configuration includes an 8-core processor with 16GB of RAM and at least 200GB of high-speed storage. These specifications support multiple concurrent users and moderate workloads effectively.

Memory requirements scale based on the number of deployed applications and cluster components. Additional RAM proves beneficial for caching container images and supporting resource-intensive workloads. Consider allocating extra memory for monitoring components and logging aggregation services.

Graphics processing unit (GPU) support considerations become relevant for machine learning workloads or compute-intensive applications. Manjaro’s excellent hardware support extends to NVIDIA and AMD GPUs, enabling acceleration for artificial intelligence and scientific computing applications.

Pre-Installation System Preparation

Updating Manjaro System Components

Begin the preparation process by ensuring your Manjaro system runs the latest packages and kernel updates. Execute the system update command to refresh package databases and install available upgrades:

sudo pacman -Syu

This command updates the entire system, including the kernel, drivers, and all installed packages. Allow the update process to complete fully before proceeding with KubeSphere installation. Reboot the system if kernel updates were installed to ensure proper initialization of new kernel modules.

Install essential development tools and utilities required for container operations. The base-devel package group provides compilation tools and build dependencies:

sudo pacman -S base-devel curl wget socat conntrack-tools ebtables ipset

These packages support container networking, connection tracking, and network bridge operations essential for Kubernetes functionality.

Container Runtime Installation

KubeSphere supports multiple container runtimes, with containerd being the recommended choice for new installations. Install containerd and associated tools using Manjaro’s package manager:

sudo pacman -S containerd runc cni-plugins

Configure containerd by creating the default configuration file and enabling the systemd service:

sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo systemctl enable --now containerd

Verify containerd installation and service status by checking the systemd service and testing basic functionality:

sudo systemctl status containerd
sudo ctr version

Alternative container runtime options include Docker, though containerd provides better integration with recent Kubernetes versions and improved performance characteristics.

User Permission Configuration

Create a dedicated user account for KubeSphere operations to maintain security boundaries and simplify permission management. This approach prevents potential conflicts with system-level operations and provides cleaner audit trails:

sudo useradd -m -s /bin/bash kubesphere
sudo usermod -aG wheel kubesphere

Configure sudo access for the KubeSphere user by editing the sudoers file or adding the user to the wheel group. This configuration enables necessary administrative operations during installation and maintenance procedures.

Set up SSH key authentication if planning to use remote installation or management tools. Generate SSH key pairs and configure appropriate file permissions:

su - kubesphere
ssh-keygen -t ed25519 -C "kubesphere@manjaro"
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Downloading and Configuring KubeKey

Understanding the KubeKey Installation Tool

KubeKey serves as the official installation and lifecycle management tool for KubeSphere deployments. This utility simplifies the complex process of installing Kubernetes and KubeSphere components while providing flexibility for various deployment scenarios.

The tool supports both single-node and multi-node cluster configurations, making it suitable for development environments and production deployments. KubeKey handles dependency management, component installation, and initial configuration automatically, reducing potential configuration errors.

Security considerations include verifying download integrity and ensuring the tool originates from official sources. Always download KubeKey from the official GitHub repository or trusted mirrors to prevent supply chain attacks.

KubeKey Download Process

Download the latest stable version of KubeKey using curl or wget. The official download command retrieves the tool directly from the GitHub releases page:

curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.2 sh -

This command downloads KubeKey version 3.0.2, which provides stable compatibility with recent KubeSphere releases. The script automatically detects your system architecture and downloads the appropriate binary.

Make the downloaded KubeKey binary executable and move it to a directory in your system PATH:

chmod +x kk
sudo mv kk /usr/local/bin/

Verify the installation by checking the KubeKey version and available commands:

kk version
kk --help

Configuration File Creation

Generate an initial configuration file for your KubeSphere installation using KubeKey’s built-in template functionality. This configuration file defines cluster parameters, component selection, and installation options:

kk create config --with-kubesphere v3.3.0 --with-kubernetes v1.24.2

This command creates a configuration file named config-sample.yaml containing default settings for single-node installation. Edit this file to customize your deployment according to specific requirements.

Review and modify key configuration sections including node specifications, network settings, and enabled components. Pay particular attention to storage class configuration and network plugin selection to ensure compatibility with your environment.

Step-by-Step Installation Execution

Pre-Installation Validation

Before executing the main installation, run KubeKey’s built-in preflight checks to identify potential issues and verify system readiness. These checks validate system requirements, network connectivity, and dependency availability:

kk check requirements

The preflight check examines CPU and memory specifications, verifies required packages, and tests network connectivity to external repositories. Address any reported issues before proceeding with the installation to prevent deployment failures.

Verify storage availability and performance characteristics, particularly for etcd data storage. KubeSphere requires reliable, low-latency storage for optimal performance. Test disk I/O performance using tools like fio or dd to ensure adequate storage performance:

sudo dd if=/dev/zero of=/tmp/testfile bs=1G count=1 oflag=direct

Executing the Installation Command

Launch the KubeSphere installation using the all-in-one command for single-node deployments. This command installs Kubernetes, KubeSphere, and all required components automatically:

kk create cluster --with-kubernetes v1.24.2 --with-kubesphere v3.3.0 --container-manager containerd

The installation process typically requires 15 to 30 minutes depending on internet connection speed and system performance. Monitor the installation progress through the console output, which provides detailed information about each installation phase.

Key installation phases include Kubernetes cluster initialization, core component deployment, KubeSphere installation, and system verification. Each phase produces detailed log output indicating progress and any encountered issues.

Monitoring Installation Progress

KubeKey provides comprehensive logging throughout the installation process, enabling real-time monitoring of progress and early detection of potential issues. Installation logs are stored in the local directory and provide valuable troubleshooting information if problems occur.

Monitor system resource utilization during installation using tools like htop, iostat, and netstat. High CPU and memory usage during installation is normal, particularly during container image downloads and compilation phases.

Network activity monitoring helps identify potential connectivity issues or slow download speeds that could extend installation time. Use iftop or nethogs to monitor network utilization and identify bandwidth bottlenecks.

Post-Installation Configuration and Verification

System Component Verification

After successful installation completion, verify that all KubeSphere and Kubernetes components are running correctly. Check pod status across all namespaces to ensure proper system initialization:

kubectl get pods --all-namespaces

This command displays all running pods with their current status. All pods should show “Running” or “Completed” status for successful installation. Pods in “Pending”, “Error”, or “CrashLoopBackOff” states indicate potential configuration issues requiring investigation.

Verify cluster node status and resource availability using kubectl commands:

kubectl get nodes
kubectl top nodes
kubectl get persistentvolumes

These commands confirm node readiness, resource utilization, and storage availability within the cluster.

Web Console Access Configuration

KubeSphere provides a comprehensive web-based management console accessible through your web browser. The default installation configures the console to listen on port 30880 with initial credentials set to username “admin” and password “P@88w0rd”.

Configure your system firewall to allow access to port 30880 if firewall rules are enabled. On Manjaro systems using UFW, execute:

sudo ufw allow 30880/tcp

For systems using iptables directly, add the appropriate rule to allow incoming connections on port 30880.

Access the web console by navigating to http://your-server-ip:30880 in your web browser. Replace “your-server-ip” with the actual IP address of your Manjaro system. Accept any security warnings related to self-signed certificates, as KubeSphere generates self-signed certificates by default.

Initial Security Configuration

Immediately change the default administrative password after first login to enhance security. Navigate to the account settings section and update the password to a strong, unique value following security best practices.

Configure additional authentication methods if required, including LDAP integration or OAuth providers. KubeSphere supports multiple authentication backends for enterprise integration scenarios.

Enable audit logging to track administrative actions and system changes. Navigate to the cluster management section and configure audit logging parameters according to your organization’s compliance requirements.

Comprehensive Testing and Validation

Functional Component Testing

Validate KubeSphere functionality by creating test workloads and verifying system operations. Create a test namespace and deploy a simple application to verify basic cluster functionality:

kubectl create namespace test-deployment
kubectl create deployment nginx-test --image=nginx --namespace=test-deployment
kubectl expose deployment nginx-test --port=80 --type=NodePort --namespace=test-deployment

These commands create a test namespace, deploy an Nginx web server, and expose it through a NodePort service. Verify the deployment status and service accessibility to confirm proper cluster operation.

Test persistent volume functionality by creating a persistent volume claim and mounting it to a test pod. This validation ensures storage subsystem functionality and proper integration with container workloads.

Network Connectivity Validation

Verify network connectivity between pods and external services by executing connectivity tests from deployed containers. Use tools like curl, ping, and nslookup from within containers to test network functionality:

kubectl exec -it nginx-test-pod -- curl -I http://google.com
kubectl exec -it nginx-test-pod -- nslookup kubernetes.default.svc.cluster.local

These tests validate external internet connectivity and internal DNS resolution within the cluster. Successful execution confirms proper network configuration and connectivity.

Test ingress controller functionality if enabled during installation. Create ingress resources and verify external access to deployed applications through configured domain names or IP addresses.

Troubleshooting Common Installation Issues

Dependency and Package Conflicts

Manjaro’s rolling release model occasionally introduces package conflicts or dependency issues that affect KubeSphere installation. Common issues include container runtime conflicts, network configuration problems, and kernel module incompatibilities.

Resolve package conflicts by updating the system package database and resolving dependency issues:

sudo pacman -Scc
sudo pacman -Syyu

If container runtime issues persist, completely remove existing installations and reinstall with clean configurations:

sudo systemctl stop containerd docker
sudo pacman -Rns containerd docker
sudo rm -rf /var/lib/containerd /var/lib/docker
sudo pacman -S containerd
sudo systemctl enable --now containerd

Network and Connectivity Issues

Network connectivity problems frequently manifest as pod networking failures, DNS resolution issues, or external service access problems. Verify network interface configuration and ensure proper bridge networking setup.

Check iptables rules and firewall configurations that might interfere with container networking. Kubernetes and KubeSphere require specific iptables rules for proper pod-to-pod communication.

Validate DNS configuration and ensure proper hostname resolution. Edit /etc/hosts if necessary to include proper hostname mappings for cluster nodes.

Storage Configuration Failures

Storage-related issues typically involve persistent volume provisioning failures or storage class configuration problems. Verify that storage classes are properly configured and available:

kubectl get storageclass
kubectl describe storageclass local-storage

Ensure sufficient disk space is available for persistent volume provisioning and that storage directories have proper permissions. KubeSphere requires adequate storage for etcd, container images, and application data.

Performance Optimization and Tuning

Resource Allocation Optimization

Optimize resource allocation based on your specific workload requirements and system capabilities. Adjust CPU and memory requests and limits for KubeSphere components to prevent resource contention:

resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "500m"

Monitor resource utilization patterns using KubeSphere’s built-in monitoring tools and adjust allocations accordingly. Proper resource allocation prevents system performance degradation and ensures stable operation.

Configure memory management settings to optimize performance for your specific workload patterns. Consider enabling memory compaction and adjusting virtual memory subsystem parameters for improved performance.

Storage Performance Tuning

Optimize storage performance by configuring appropriate storage classes and volume provisioning parameters. Use high-performance storage backends like NVMe SSDs for etcd and frequently accessed data.

Configure storage class parameters to optimize performance for specific workload types:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/no-provisioner
parameters:
  type: pd-ssd
  replication-type: none
volumeBindingMode: WaitForFirstConsumer

Enable storage monitoring to track I/O performance and identify potential bottlenecks. Use tools like iotop and iostat to monitor storage subsystem performance and optimize accordingly.

Maintenance and Lifecycle Management

Regular Maintenance Procedures

Establish regular maintenance schedules to ensure optimal KubeSphere performance and security. Regular tasks include log rotation, resource cleanup, and security updates.

Configure automated log rotation to prevent disk space exhaustion:

sudo logrotate -f /etc/logrotate.conf

Monitor cluster health metrics and establish alerting for critical system conditions. Use KubeSphere’s built-in monitoring capabilities to track resource utilization, pod health, and system performance.

Implement backup strategies for critical cluster data, including etcd snapshots and persistent volume backups. Regular backups ensure rapid recovery in case of system failures or data corruption.

Upgrade Planning and Execution

Plan KubeSphere upgrades carefully to minimize service disruption and ensure compatibility with existing workloads. Review upgrade documentation and test procedures in development environments before applying to production systems.

Execute upgrades using KubeKey’s built-in upgrade functionality:

kk upgrade --with-kubesphere v3.3.1

Monitor upgrade progress and maintain rollback capabilities in case issues arise during the upgrade process. Document upgrade procedures and maintain version compatibility matrices for reference.

Verify system functionality after upgrades by running comprehensive test suites and validating all critical applications and services.

Advanced Configuration and Integration

Multi-Cluster Management Setup

Configure multi-cluster management capabilities to centralize administration of distributed Kubernetes environments. KubeSphere supports host cluster and member cluster architectures for scalable multi-cluster deployments.

Set up cluster networking and authentication for secure multi-cluster communication. Configure appropriate network policies and firewall rules to enable secure cluster-to-cluster communication while maintaining security boundaries.

Implement centralized monitoring and logging aggregation across multiple clusters to maintain comprehensive visibility into distributed environments.

Enterprise Integration Features

Integrate KubeSphere with enterprise authentication systems including Active Directory, LDAP, and OAuth providers. Configure single sign-on (SSO) capabilities to streamline user access management across multiple systems.

Set up enterprise monitoring and alerting integration with existing ITSM and monitoring platforms. Configure webhook notifications and integrate with platforms like Slack, PagerDuty, or ServiceNow.

Implement governance policies and resource quotas to enforce organizational standards and prevent resource abuse in multi-tenant environments.

Congratulations! You have successfully installed KubeSphere. Thanks for using this tutorial for installing the KubeSphere open-source container platform on Manjaro Linux system. For additional help or useful information, we recommend you check the official KubeSphere website.