mogenius / punq

A slim open-source workload manager for Kubernetes with team collaboration, WebApp, and CLI.

punq

Punq streamlines Kubernetes cluster management through an intuitive WebApp and a user-friendly CLI, designed to simplify the lives of DevOps professionals.

It offers unified team collaboration, comprehensive log access, and a sophisticated workload editor, facilitates seamless oversight and manipulation of clusters spanning various infrastructures.

This project is dedicated to enhancing operational efficiency within Kubernetes environments, with a particular focus on bolstering team-based workflows.

How It Works

Punq offers a self-hosted solution, residing directly within your Kubernetes cluster, to create a dedicated instance for your team. Each instance is composed of:

• An operator, meticulously crafted in Golang, that maintains the core functionalities,
• A dynamic UI, brought to life with Angular, that ensures a smooth user experience.

Punq empowers you to seamlessly oversee multiple Kubernetes clusters. Simply import them from your local kubeconfig, and punq handles the rest, securely tucking away your configurations as secrets within your cluster.

Leveraging these configurations, punq presents a comprehensive view of all workloads and resources through its application. Consequently, every team member using your punq instance gains the capability to monitor and manage clusters, all without the necessity to access the kubeconfig directly. This not only enhances security but also promotes operational efficiency and team collaboration.

Installation

Setting up punq is straightforward and conducted through the command line interface (CLI).

Currently, Homebrew covers installation on macOS and Linux platforms whereas if you are a Windows user you can leverage Scoop.

macOS/Linux

brew tap mogenius/punq
brew install punq

Windows

scoop bucket add mogenius https://github.com/mogenius/punq
scoop install punq

Getting Started

After successfully installing punq, you're just a few steps away from harnessing its full potential. Here's how to get your journey started.

To install punq on your cluster within the current context and set up ingress routing, enabling you to access punq via your custom domain:

Without Ingress (local / not exposed to the internet)

punq install
punq proxy

With Ingress

punq install -i punq.yourdomain.com

And thereafter to finalize your punq setup, configure your domain, and getting started with using punq:

1. Configure DNS Settings:

   • Navigate to your domain's DNS management page,
   • Add a new DNS record for punq. This will typically be a CNAME record pointing punq.yourdomain.com to the address provided by your punq installation or the IP of your ingress controller. The exact setup may depend on your hosting or DNS provider,

2. Access punq Interface:

   • Open your preferred web browser and visit punq.yourdomain.com (replace with your actual subdomain).
   • If you've configured SSL (recommended for security reasons), ensure you're accessing punq over HTTPS (https://punq.yourdomain.com),

3. Admin Login:

   • Log in using the admin credentials provided during the punq installation. These credentials are displayed in your terminal post-installation. It's crucial to save these details securely, as they're shown only once and are necessary for administrative access,

4. Explore Your Default Cluster:

   • The cluster where punq is installed is automatically configured in your punq instance. Begin exploring the interface, reviewing workloads, and getting familiar with the environment,

5. Add Additional Clusters:

   • To manage more clusters, click on the dropdown menu in the top left corner of the punq interface,
   • Follow the on-screen instructions, which will include uploading your kubeconfig files for the additional clusters you want to manage,
   • Ensure each kubeconfig file is correct and up-to-date to avoid connection issues,

6. Get Started:

   • With your clusters added, you're ready to dive into using punq! 🤘 Start monitoring workloads, managing resources, and deploying applications across your clusters from one unified interface,

7. Invite your team

   • punq is great for working with Kubernetes in teams. Start by adding users with the CLI via punq user add together with the required flags.
   • There are three roles that you can assign with the flag -a to set the access level of a user: ADMIN, USER, and READER.

8. Stay Secure:

   • Regularly update your login credentials and review your cluster's security settings to ensure your environment remains secure.

Remember, the punq community and documentation are valuable resources if you encounter any issues or have further questions as you embark on this streamlined Kubernetes management experience.

Managing punq via CLI

Here are some basic punq commands to start with:

# List all available CLI features
punq help

# Install the punq operator in your current kubecontext
punq install -i punq.yourdomain.com

# Manage users and permissions
punq user

# Upgrade your punq instance to the recent version
punq upgrade

# Delete punq from your current kubecontext
punq clean

Development

If you're interested in running the development version of punq, which corresponds to the develop branch of the repository, you can do so by following these instructions:

brew tap mogenius/punq-dev
brew install punq-dev

However, please be aware that you cannot run both the standard (punq) and development (punq-dev) versions on the same cluster at the same time.

To update the documentation please run (in project root):

go install github.com/swaggo/swag/cmd/swag@latest
swag init --parseDependency --parseInternal

FAQ

How to set a default editor for Windows (for example Visual Studio Code):

Open powershell as admin and run:
[System.Environment]::SetEnvironmentVariable("EDITOR", "code -w", [System.EnvironmentVariableTarget]::Machine)

Community

The punq community is on Slack! Check out the workspace to discuss questions and ideas with fellow punq users and the team.
🏠 Join us on Slack

Contribution

Punq is in its nascent stages, brimming with potential, and we're excited to extend an invitation for you to be part of this journey. Your insights, expertise, and contributions can significantly shape its evolution, enhancing this tool for many users and diverse needs. Here's how you can get involved:

1. Explore Open Issues:

   • Visit our repository and delve into the "Issues" section. These are the gateways to the current developmental challenges and enhancements that punq is looking to address,
   • Issues can range from simple documentation fixes, feature enhancements, to complex system builds, allowing you to contribute in areas that match your skills and interest,

2. Choose an Issue:

   • Pick an issue that resonates with your expertise or piques your interest. We recommend starting with "good first issues" if you're new to the project; they're designed to help you get familiar with the codebase and contribution process,

3. Communicate:

   • Before you start working, communicate your interest on the issue's thread. This step ensures transparency and prevents multiple contributors from working on the same issue unknowingly,
   • Feel free to ask for clarification or guidance if needed; our community and maintainers are here to support you,

4. Fork and Branch:

   • Fork the repository and create a new branch in your forked repository to work on the issue. It's a good practice to name your branch something descriptive that reflects the issue you're addressing,

5. Code:

   • Dive into the code and work your magic! Ensure your contributions adhere to the project's coding standards and guidelines, which are typically available in the repository,

6. Test:

   • After coding, rigorously test your changes. Contributions with thorough testing are more reliable and easier to merge,

7. Create a Pull Request (PR):

   • Once you're confident in your contribution, push your branch to your fork and submit a pull request to the original repository. Provide a detailed description of the changes in your PR, and reference the issue number you're addressing,
   • Await feedback or approval from the project maintainers. They may request some changes, improvements, or provide other feedback,

8. Engage and Iterate:

   • Respond to comments on your pull request and make requested changes until your PR is ready to be merged. This process can be a rewarding cycle of review and revision, enriching both your contribution and your expertise,

9. Celebrate: 🥳

   • Once your PR is merged, celebrate your contribution! It's a significant achievement to contribute to open-source projects,

Remember, open-source is not just about code. It's about collaboration, learning, and shared stewardship. Whether you're a seasoned developer or a newbie, your contributions are valuable and appreciated. So, let's shape the future of punq together!

Made with 💜 by the folks at mogenius

punq's Issues

Quick actions to restart, scale, kill, etc.

Apart from deleting services, it should be possible to perform quick actions on pods, deployments, etc., such as:

• Restart
• Kill
• Scale

Punq is incompatible with Ubuntu 20.04

I wanted to test Punq, but it seems it is incompatible with Ubuntu 20.04.

Downloading the binary on Ubuntu 20.04 (in WSL) and running it results in the following errors:

punq
punq: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by punq)
punq: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by punq)

As per my version of Ubuntu 20.04, it has libc6 2.31 installed. Doing a kernel update is not viable.
This could be solved by building the executable on Ubuntu 20.04 instead of 22.04 - that should remove the dependency of libc6 2.32 and 2.34.

Support clusters that require additional authentication

Cluster connections are currently added by uploading a kubeconfig. For some providers, such as AWS, Azure, or GCP, this is not enough. They require additional authentication through service accounts. punq should support these providers by adding an authentication option (+ kubeconfig) when adding a cluster.

Hardcoded call to /usr/local/bin/kubectl fails

I have kubectl installed at /usr/bin/kubectl via dnf

$ punq install -i punq.minikube.local
Do you really want to install punq to 'minikube' context? [Y/n]: y
Creating punq namespace ...
Created punq namespace. ✅
Creating punq RBAC ...
Created punq RBAC. ✅
Creating punq deployment ...
Created punq deployment. ✅
Determining cluster provider ...
Determined cluster provider: 'MINIKUBE'. ✅
Creating new punq-context secret ...
Created new punq-context secret. ✅
Creating punq service ...
Created punq service. ✅
Creating TRAEFIK punq ingress (punq.minikube.local) ...
Created TRAEFIK punq ingress (punq.minikube.local). ✅
Creating TRAEFIK middleware (punq.minikube.local) ...
Error: failed to execute command (/bin/bash -c /usr/local/bin/kubectl apply -f /tmp/traefik-middleware.yaml3688081572): exit status 127
/bin/bash: line 1: /usr/local/bin/kubectl: No such file or directory

A code review revealed there are several places where kubectl is called on ¬Windows using the full path /usr/local/bin/kubectl.
This is fine and desirable, but only when the fully qualified command is resolved, stored and checked.

Using a hardcoded call to /usr/local/bin/kubectl will fail, when the caller doesn't have kubectl installed at /usr/local/bin.
This can be the case if it is installed via a package manager, like dnf in my case, or when a custom location is chosen, e.g. when developing on kubectl.

There are four solutions and a local quick fix:

1. Every call to /usr/local/bin/kubectl should be resolved via path, instead of being hard-coded.
2. On startup, punq checks whether kubectl is available using PATH but only on CLI calls which use kubectl. kubectl is defined once, and referred afterwards.
3. (Like 2. but with a singleton pattern which raises 4.)
4. Instead of relying on an external CLI Tool like kubectl, punq should talk directly with the API server, e.g. by using https://github.com/kubernetes/client-go/. This is already a dependency.

NOTE: 1, 2, 3 will create a mess, when the behaviour ofkubectl is altered during execution, unlikely, but possible: e.g. kubectx or kubens changes.

Quick fix:

ln -s /usr/bin/kubectl /usr/local/bin/kubectl

At last, when one of the install commands fails, I suggest punq should do a clean up itself or reminds to do a clean install.

Error While Configuring and Selecting KUBECONFIG

I have an issue while running the below commands which are for installing punq:

There have been some issues while selecting $Kubeconfig

To resolve this we have to change or Update the documentation of punq which we are using without ingress as per our need.

Drilldown for related resources

Most resources are related to other resources and it should be possible to easily navigate through these relations.

For example:

• From a node, navigate to all pods on this node
• Deployments -> Pod -> Container
• Namespace -> Pod -> Container
• etc.

Add and edit users via UI

Adding and managing users is currently only available via CLI. The section to manage members in a punq instance already exists and we need options to add and edit users.

Since punq doesn't have support to integrate SMTP for transactional emails, invite links and double opt-in are not possible yet. Therefore, when adding a user, admins could set or generate a password that is changed by the user after login.

Shell access on containers

It should be possible to connect to containers via shell in the user interface. Something like xterm.js could be used to open a shell in a tab next to Log, Describe, YAML.