Skip to content

Latest commit

 

History

History
205 lines (174 loc) · 10 KB

README.md

File metadata and controls

205 lines (174 loc) · 10 KB
Raw

Kubemarine_1280х640_3_JPEG GitHub stars GitHub stars PyPI version

Kubemarine

Kubemarine is an open source, lightweight and powerful management tool built for end-to-end Kubernetes cluster deployment and maintenance. It is applicable for many purposes like simple and quick onboarding Kubernetes on local and production environments in different HA schemes depending on your aims, budget, and capabilities. Together with simplicity, Kubemarine can be a very flexible and customizable tool covering specific configurability cases on both deployment and maintenance stages. This library provides powerful CLI commands, as well as can be customized using a Python extension API.

Highlights

Repository structure

There are following key locations in the repository

Paths Description
.github/workflows/, ci/ Contain GitHub Actions configuration which runs unit/integration tests, builds/publishes artifacts, etc
documentation/, examples/, README.md Contain documentation and examples
kubemarine/ Contains source code for KubeMarine python package
test/ Contains tests
bin/, scripts/ci/ Contains auxiliary scripts used during KubeMarine build
scripts/thirdparties/ Contains auxiliary script used to update KubeMarine thirdparties versions
Dockerfile, kubemarine.spec, MANIFEST.in, pyproject.toml, requirements-pyinstaller.txt, setup.py Different files used to build KubeMarine artifacts (image, binaries, package)

Kubemarine Binary Installation

Proceed the following steps to install Kubemarine on your environment:

  1. Download the binary file for your system from the latest release
  2. Move binary kubemarine to a separate folder
  3. Now you can proceed to run Kubemarine! Try the following: 
    kubemarine help

Kubemarine Package Installation

To install Kubemarine as package on your environment:

  1. Install the latest python.

  2. Upgrade pip.

    Linux / MacOS:

    python3 -m pip install --upgrade pip

    Windows:

    python -m pip install --upgrade pip

  3. Ensure your environment meets the Deployment Node Prerequisites.

  4. Create and activate a virtual environment if necessary.

  5. Install Kubemarine package.

    Linux / MacOS:

    python3 -m pip install kubemarine

    Windows:

    python -m pip install kubemarine

  6. Now you can proceed to run Kubemarine! Try the following:

    kubemarine help

Kubemarine Installation from Sources

Installation of Kubemarine from sources is mostly similar to Kubemarine Package Installation. The exception is instead of installing the package from PyPI, do the following:

  1. Download the latest release or clone the repository:

    git clone https://github.com/netcracker/kubemarine.git

  2. Unpack the project from the archive if required:

    tar xzvf X.X.X.tar.gz

  3. Navigate to the project directory:

    cd kubemarine

  4. Install Kubemarine package from sources.

    Linux / MacOS:

    python3 -m pip install -e .[ansible]

    Windows:

    python -m pip install -e .

  5. Now you can proceed to run Kubemarine. Try the following:

    kubemarine help

Note: Building from Dockerfile is also available.

Note: Kubemarine debugging available via kubemarine/__main__.py.

Running Cluster Installation

To install a Kubernetes cluster using Kubemarine:

  1. Prepare your VMs or bare-metal machines according to Recommended Hardware Requirements and the selected Deployment Scheme. Make sure the nodes meet Cluster Nodes Prerequisites.
  2. Create the cluster.yaml inventory file, and describe your environment. Make sure that all configurations are done. For more information, see inventory configs available and examples. No need to enter all the parameters that are available, it is enough to specify the minimal identification data about the nodes where you want to install the cluster, for example: 
    node_defaults:
  keyfile: "/home/username/.ssh/id_rsa"
  password: '{{ env.PASS }}'     #Either keyfile or password can be used.
  username: "centos"

vrrp_ips:
  - 192.168.0.250

nodes:
  - name: "k8s-control-plane-1"
    internal_address: "10.101.0.1"
    roles: ["balancer", "control-plane", "worker"]
  - name: "k8s-control-plane-2"
    internal_address: "10.101.0.2"
    roles: ["balancer", "control-plane", "worker"]
  - name: "k8s-control-plane-3"
    internal_address: "10.101.0.3"
    roles: ["balancer", "control-plane", "worker"]

cluster_name: "k8s.example.com"
  3. Move cluster.yaml to the directory where Kubemarine is installed.
  4. Verify the infrastructure: 
    kubemarine check_iaas
  5. Start the installation: 
    kubemarine install
  6. Check the health of the newly installed cluster: 
    kubemarine check_paas

For more information, refer to the other Kubemarine guides.

Kubemarine Docker Installation

To start, download the Kubmarine image docker pull ghcr.io/netcracker/kubemarine:main

Run Kubemarine from the container, for example:

docker run -it --mount type=bind,source=/root/cluster.yaml,target=/opt/kubemarine/cluster.yaml --mount type=bind,source=/root/rsa_key,target=/opt/kubemarine/rsa_key kubemarine install -c /opt/kubemarine/cluster.yaml

Note: Do not forget to pass the inventory file and connection key inside the container. For more execution details, refer to "Installation of Kubernetes using CLI" guide on Github.

Documentation

The following documents and tutorials are available:

Also, check out the following inventory examples:

For maintainers and developers there is useful internal documentation, for example:

Issues, Questions

If you have any problems while working with Kubemarine, feel free to open a new issue or even PR with related changes. Please follow the Contribution Guide and the process outlined in the Stack Overflow MCVE document.

In case of security concerns, please follow the Security Reporting Process

Changelog

Detailed changes for each release are documented in the release notes.

License

Apache License 2.0