DOCSEARCHbyAlgolia
Submit Docs

MicroK8s Documentation

repository·master·Indexed 27 days ago

https://github.com/canonical/microk8s

A lightweight, single-package, fully conformant Kubernetes distribution designed for developers, IoT, edge, and CI/CD environments. Distributed via Snap, it provides a simple way to run Kubernetes on Linux. The documentation covers installation, cluster management via built-in kubectl, enabling add-ons, and detailed instructions for building the snap from source, applying component patches, and creating Windows installers using NSIS.

Tokens
4K
Snippets
14
Records
27
Agent score
94%

What's inside MicroK8s

  1. Generate Kubernetes patches for MicroK8s builds

    master
    MicroK8s applies a kubelite patch to the Kubernetes source code during the build process. These patches are maintained in the kubernetes-dqlite repository. To generate a new patch file, you must clone the kubernetes-dqlite repository, checkout the target Kubernetes branch, identify the relevant patch commits from the git log, and use git format-patch to create the .patch file. The resulting patch file must be copied back into the microk8s source tree under build-scripts/patches/.

  2. Build the MicroK8s Windows installer

    master

    The MicroK8s Windows installer is created using NSIS. To build the installer, you must ensure the following prerequisites are met and the necessary binary files are present in your working directory.

    Prerequisites

    • NSIS 3: Required for the build process.
    • EnVar plug-in: Required for compilation.

    Required Files

    Before running the compilation command, place these two files in your working directory:

    1. microk8s.exe: The executable generated by PyInstaller.
    2. multipass.exe: The Multipass installer executable (used during the installation process).

    Compilation Command

    Run the following command to compile the installer using the NSIS script:

    makensis microk8s.nsi

  3. Run MicroK8s tests locally

    master

    To run MicroK8s tests locally, you must install specific system dependencies (python3, pytest, pip3, docker.io, tox) and Python packages (requests, pyyaml, sh). The testing process involves running static analysis with tox, building/installing the snap locally, and then executing the test suite using pytest.

    # Install dependencies (Ubuntu example)
sudo apt install python3-pip docker.io tox -y
pip3 install -U pytest requests pyyaml sh

# Run static analysis
tox -e lint

# Run test suites
pytest -s tests/test-simple.py
pytest -s tests/test-upgrade.py

    Note on Ingress Tests: If ingress or dashboard-ingress tests fail due to DNS rebinding protection with nip.io, add the following to your /etc/hosts:

    127.0.0.1 kubernetes-dashboard.127.0.0.1.nip.io
127.0.0.1 microbot.127.0.0.1.nip.io

  4. Configure existing kubectl to use MicroK8s

    master

    To use your existing standalone kubectl installation instead of the built-in microk8s kubectl, export the MicroK8s configuration to your local kubeconfig file.

    sudo microk8s kubectl config view --raw > $HOME/.kube/config

  5. Build the MicroK8s snap using LXD

    master

    If you are working in a virtual machine without nested virtualization, you can build the snap inside an LXC container using LXD. This requires installing LXD, initializing it, and adding your user to the lxd group. Use the --use-lxd flag with Snapcraft to trigger this build mode.

    sudo snap install lxd
sudo apt-get remove lxd* -y
sudo apt-get remove lxc* -y
sudo lxd init
sudo usermod -a -G lxd ${USER}

git clone http://github.com/canonical/microk8s
cd ./microk8s/
snapcraft --use-lxd
sudo snap install microk8s_*_amd64.snap --classic --dangerous

  6. Build the MicroK8s snap from source

    master

    To build the MicroK8s snap from source, install Snapcraft and run the snapcraft command in the project root. Snapcraft uses Multipass to spawn a VM for the build process. If Multipass is not installed, Snapcraft will prompt to install it automatically. Once the build is complete, install the resulting .snap file using the --classic and --dangerous flags.

    sudo snap install snapcraft --classic
snapcraft
sudo snap install microk8s_*_amd64.snap --classic --dangerous

  8. Enable Kubernetes add-ons

    master

    MicroK8s starts with a barebones upstream Kubernetes. You can enable additional services (add-ons) like dns or dashboard using the microk8s enable command. Use microk8s status to view a list of currently enabled and available add-ons. Add-on manifests and scripts are located under ${SNAP}/actions/ (typically /snap/microk8s/current/actions/).

    sudo microk8s enable dns
sudo microk8s enable dashboard

  9. Build a custom MicroK8s package with specific component versions

    master

    Available Environment Variables

    • KUBE_VERSION: Kubernetes release to package. Defaults to latest stable.
    • ETCD_VERSION: version of etcd.
    • CNI_VERSION: version of CNI tools.
    • KUBE_TRACK: Kubernetes release series (e.g., 1.10) to package. Defaults to latest stable.
    • ISTIO_VERSION: istio release.
    • KNATIVE_SERVING_VERSION: Knative Serving release.
    • KNATIVE_EVENTING_VERSION: Knative Eventing release.
    • RUNC_COMMIT: the commit hash from which to build runc.
    • CONTAINERD_COMMIT: the commit hash from which to build containerd
    • KUBERNETES_REPOSITORY: build the Kubernetes binaries from this repository instead of getting them from upstream
    • KUBERNETES_COMMIT: commit to be used from KUBERNETES_REPOSITORY for building the Kubernetes binaries
    # 1. Prepare the LXC container
lxc launch ubuntu:16.04 --ephemeral test-build
lxc exec test-build -- snap install snapcraft --classic
lxc exec test-build -- apt update
lxc exec test-build -- git clone https://github.com/canonical/microk8s

# 2. Build with custom KUBE_VERSION
lxc exec test-build -- sh -c "cd microk8s && SNAPCRAFT_BUILD_ENVIRONMENT=host KUBE_VERSION=v1.9.6 snapcraft"

# 3. Pull the snap to the host
lxc file pull test-build/root/microk8s/microk8s_v1.9.6_amd64.snap .

# 4. Install
snap install microk8s_*_amd64.snap --classic --dangerous

  11. Understand the MicroK8s component build structure

    master

    MicroK8s Go components are built using a standardized directory structure within build-scripts/. Each component has its own directory containing the source repository information, versioning logic, build instructions, and patches.

    Directory Structure for a component ($component_name):

    • repository: The git repository to clone.
    • version.sh: A script that prints the specific git tag or commit to checkout.
    • build.sh: The build script. It must accept two arguments: the first is the output directory for binaries, and the second is the component version.
    • pre-patch.sh: (Optional) A script to run any actions required before applying patches.
    • patches/: A directory containing patches applied after checkout.
    • strict-patches/: A directory containing additional patches applied specifically when building a strictly confined snap. These are applied after the standard patches/.

    Main Build Entrypoint: To build a component, run the top-level script:

    ./build-scripts/build-component.sh $component_name

  12. Use MicroK8s kubectl commands

    master

    MicroK8s provides a built-in kubectl command. You can interact with your cluster using microk8s kubectl followed by standard Kubernetes commands.

    sudo microk8s kubectl get nodes
sudo microk8s kubectl get services