search

energinet-digitalisering / ksail

A CLI tool for provisioning GitOps enabled K8s clusters in Docker.
MIT License
0 stars 0 forks source link

readme

🛥️🐳 KSail

License: MIT Test codecov

[!NOTE] This is an early release of KSail. I am actively working on the tool, so if you encounter any issues, please let me know 🙏🏻

image

Show/hide folder structure ``` . ├── .github │   └── workflows ├── .vscode ├── images ├── scripts ├── src │   └── KSail │   ├── Arguments │   ├── CLIWrappers │   ├── Commands │   │   ├── Check │   │   │   ├── Handlers │   │   │   └── Options │   │   ├── Down │   │   │   ├── Handlers │   │   │   └── Options │   │   ├── Init │   │   │   ├── Generators │   │   │   └── Handlers │   │   ├── Lint │   │   │   └── Handlers │   │   ├── List │   │   │   └── Handlers │   │   ├── Root │   │   │   └── Handlers │   │   ├── SOPS │   │   │   ├── Handlers │   │   │   └── Options │   │   ├── Start │   │   │   └── Handlers │   │   ├── Stop │   │   │   └── Handlers │   │   ├── Up │   │   │   ├── Handlers │   │   │   └── Options │   │   └── Update │   │   ├── Handlers │   │   └── Options │   ├── Enums │   ├── Extensions │   ├── Models │   │   ├── K3d │   │   ├── KSail │   │   ├── Kubernetes │   │   │   └── FluxKustomization │   │   └── SOPS │   ├── Options │   ├── Provisioners │   │   ├── ContainerEngine │   │   ├── ContainerOrchestrator │   │   ├── GitOps │   │   ├── KubernetesDistribution │   │   └── SecretManager │   ├── TemplateEngine │   └── assets │   ├── binaries │   └── templates │   ├── k3d │   ├── kubernetes │   └── sops └── tests └── KSail.Tests.Integration ├── Commands │   ├── Check │   ├── Down │   ├── Lint │   ├── List │   ├── Root │   ├── SOPS │   ├── Up │   └── Update └── TestUtils 72 directories ```
Show/Hide codebase visualization ![Visualization of the codebase](./diagram.svg)

Getting Started

Prerequisites

Supported OSes:

[!NOTE] On MacOS (darwin) you need to "Allow the default Docker socket to be used (requires password)" in Docker Desktop settings.

Show me how! ![Enable Docker Socket in Docker Desktop](images/enable-docker-socket-in-docker-desktop.png)

Required Tools:

Recommended Tools:

Installation

With Homebrew:

brew tap devantler/formulas
brew install ksail

Manually:

  1. Download the latest release from the releases page.
  2. Make the binary executable: chmod +x ksail.
  3. Move the binary to a directory in your $PATH: mv ksail /usr/local/bin/ksail.

Usage

KSail is built to run as either a local binary, or as a Docker container.

Setting sail for your voyage and navigating beyond the shore with KSail is as straightforward as:

# --- Local Binary ---
ksail init <name-of-cluster>
ksail up <name-of-cluster>

# --- Docker Container ---
docker run --rm \
  -v $(pwd):/app `# Mount working directories` \
  ghcr.io/devantler/ksail:latest init <name-of-cluster>

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock `# Mount Docker socket` \
  -v $(pwd):/app `# Mount working directories` \
  -v $(pwd):/root/.ksail `# Mount KSail config files` \
  --network host `# Allow access to containers on localhost` \
  ghcr.io/devantler/ksail:latest up <name-of-cluster>

For more intricate navigational techniques, consult the global --help flag:

# --- Local Binary ---
ksail --help

# --- Docker Container ---
docker run --rm ghcr.io/devantler/ksail:latest --help

What is KSail?

KSail Architecture

KSail is a CLI tool designed to simplify the management of GitOps-enabled Kubernetes clusters in Docker. It provides a set of commands that allow you to easily create, manage, and dismantle GitOps-enabled clusters. KSail also integrates with SOPS for managing secrets in Git repositories and provides features for validating and verifying your clusters.

KSail provides the following features:

How does it work?

KSail leverages several key technologies to provide its functionality:

Why was it made?

KSail was created to fill a gap in the tooling landscape for managing GitOps-enabled Kubernetes clusters in Docker. There are currently two intended use cases for KSail:

Q&A

Why use KSail instead of e.g. k3d or kind?

KSail is built on top of k3d, so it provides all the same functionality as k3d. However, KSail also provides additional functionality for managing GitOps-enabled Kubernetes clusters in Docker. For a GitOps-enabled cluster to work well in Docker, you need quite a few tools to be installed and configured. KSail aims to simplify this process by providing a set of commands that allow you to easily create, manage, and dismantle GitOps-enabled clusters.

How do I use KSail with CI/CD?

You need to download the KSail binary into your CI/CD environment, and then run the KSail commands as you would locally. For example, if you are using GitHub Actions, you can use the following workflow:

name: KSail

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  ksail:
    runs-on: ubuntu-latest
    steps:
      - name: 📑 Checkout
        uses: actions/checkout@v4
      - name: 🍺 Set up Homebrew
        uses: Homebrew/actions/setup-homebrew@master
      - name: 🛥️🐳 Install KSail
        run: brew install devantler/formulas/ksail
      - name: 🛥️🐳🚀 KSail Up
        run: |
          ksail sops <name-of-cluster> --import "${{ secrets.KSAIL_SOPS_AGE_KEY }}"
          ksail up <name-of-cluster>

How do I use KSail with Cloud Providers?

KSail is purposely designed to work with local Docker clusters. If you want to create clusters in the cloud, I recommend using an Infrastructure as Code (IaC) tool like Terraform or Pulumi to create your clusters and initialize Flux GitOps. You can still use KSail to generate the needed YAML and configuration files, but clusters in the cloud often require additional configuration and dependencies, so do not expect your Docker clusters to work in the cloud without some additional work.

What is next for KSail?

I am currently working on stabilizing the tool, and ensure that it works as expected, and if not that it fails gracefully with informative error messages. I am also working on adding more tests, and improving the test coverage. Once I am happy with the stability of the tool, I will start working on adding more features.

Features in the pipeline:

Features I'm considering:

Contributing

Contributions to KSail are welcome! You can contribute by reporting bugs, requesting features, or submitting pull requests. When creating an issue or pull request, please provide as much detail as possible to help understand the problem or feature. Check out the Contribution Guidelines for more info.