Skip to main contentMerative SPM on Kubernetes

Minikube

Minikube runs a single-node Kubernetes cluster inside a virtual machine (VM) on your laptop, for users who want to try out Kubernetes or develop with it. Minikube documentation is available at Installing Kubernetes with Minikube. The following sections are not a substitute for the official documentation but they get you started in a classic configuration.

The following installation steps are described:

  • Installing Minikube
  • Starting Minikube
  • Setting up the Docker® registry
  • Configuring the hosts file for Minikube
  • Enabling Helm for Minikube
  • A summary of some useful Minikube commands

Minikube installation

Minikube installation steps are described in the official documentation for your preferred Operating System: Install Minikube.

Starting Minikube

Minikube can be started with a command as simple as minikube start without any additional parameters. However, the resulting VM will be too small to deploy an instance of Merative Social Program Management (SPM), so several other parameters are required as described in the following sections.

Specifying the resource allocation

You can add properties to specify the resource allocation. For example:

  • --cpus 4 to use 4 CPUs
  • --memory 8G to use 8 GB of RAM
  • --disk-size=30G to use 30 GB of disk space

Specifying the VM driver

Add the --driver= option to the minikube start command to specify the underlying virtual machine driver. The following drivers were tested:

  • VirtualBox (virtualbox) on OSX and Linux
  • VMware Fusion (vmware) on OSX
    • Note: There is an issue running Minikube on macOS Big Sur with VMware Fusion 12. If you are using Big Sur, use an alternative driver.
  • Docker (docker) on Linux
  • KVM (kvm2) on Linux
  • Hyperv (hyperv) on Windows

The Install Minikube page gives you more information on available VM driver options.

Specifying the insecure registry

You must specify the --insecure-registry option to reference the Docker registry that is created. The --insecure-registry value is the same as specified in the daemon.json file.

Note: Because of a limitation in the current version of Minikube, adding the --insecure-registry option works on a new Minikube instance only. If you start Minikube, be sure to run minikube stop and minikube delete before you start it again with the --insecure-registry option.

For Windows see the Minikube handbook for information regarding the --insecure-registry "10.0.0.0/24” setting on the minikube start command.

Specifying the Kubernetes version

You can override the version of Kubernetes that gets installed inside the Minikube VM by using the --kubernetes-version flag. This flag controls the compatibility between the client tools and the Kubernetes specification.

If you override the Kubernetes version, ensure that you download and install the corresponding version of kubectl - this version must be the same version as the Kubernetes cluster.

Note: The kubectl version running locally and on Minikube should be compatible, so it’s possible to use the --kubernetes-version flag to keep them consistent.

Minikube start command

Note: In the following example for Mac and Linux we set the --insecure-registry option passing in a subnet of 192.168.0.0/16. The IP address on your machine may not be on the appropriate network for this subnet to work. Therefore, start a Minikube instance to verify the IP address begins with 192.168.0.X. You need only do this once. See the note in Specifying the insecure registry.

Example minikube start commands based on the recommended settings above:

minikube start --driver=virtualbox --cpus 4 --memory 8G \
               --insecure-registry "192.168.0.0/16" \
               --disk-size='30G' \
               --kubernetes-version v1.20.11

Using Docker inside the Minikube VM

You can use the Docker installed in your local environment or, optionally, the Docker inside the Minikube VM.

The command to use the Docker inside of the Minikube VM is:

minikube docker-env

The output of that command will instruct you how to run the command for your particular shell as illustrated:

eval $(minikube -p minikube docker-env)

Then docker commands will operate against the Minikube VM’s docker, allowing, for example, the likes of docker run for chartmuseum and the docker build commands to work. Don’t forget that if you are using multiple shells you must run the minikube docker-env command in each shell.

Docker Hub download rate limit and Minikube

In November 2020, Docker introduced download rate limits on Docker Hub. Normally, this can be mitigated by providing an Image Pull Secret to the deployment.

For Minikube addons these pull secrets are not exposed, so the solution involves providing a config.json file containing the credentials to the Kubelet process running inside the Minikube environment.

  1. Authenticate your local Docker client with Docker Hub: docker login

  2. Copy the contents of your local Docker secrets:

    cat ~/.docker/config.json && echo
    • The output should look something like below:
    {
      "auths": {
        "https://index.docker.io/v1/": {
          "auth": "<base64 of username:password>"
        }
      }
    }

  3. Open a terminal in your Minikube VM:

    minikube ssh

  4. Paste the contents of the file from step 2 into /var/lib/kubelet/config.json:

    • Edit the command to include the contents of your config.json file first
    cat << EOS | sudo tee /var/lib/kubelet/config.json
    {
      "auths": {
        "https://index.docker.io/v1/": {
          "auth": "<base64 of username:password>"
        }
      }
    }
    EOS

  5. Restart the kubelet process in the Minikube VM:

    sudo systemctl restart kubelet

  6. Exit the Minikube terminal.

Docker registry

You need a registry to use docker images with Helm in Minikube. There are different types of registries that can be used. However, this page describes a simple registry option that doesn’t require extra components.

Minikube provides an add-on to run a registry in a container. For more information, see How to access the Docker registry within minikube.

You can use the following command to enable the add-on:

minikube addons enable registry

When enabled, starting Minikube starts two pods on the kube-system namespace, named registry and registry-proxy. Now the registry is active and can be used. The registry points to the Minikube IP address on port 5000.

The containers don’t mount any volumes, so stopping Minikube deletes the registry content.

For Windows, you must follow the steps in the Minikube Handbook and set the value of the DOCKER_REGISTRY environment variable as follows:

$env:DOCKER_REGISTRY = "localhost:5000"

Using the insecure registry on Windows

For more information see the Minikube handbook.

Perform these steps to use the insecure registry on Windows:

  • Confirm the registry service is running in minikube: kubectl get service --namespace kube-system
  • Part one of making the registry port available: kubectl port-forward --namespace kube-system service/registry 5000:80 Note: The port-forward sporadically times out/dies; so, you have to periodically check that it’s running and renter it if needed.
  • Part two of making the registry port available: docker run -d --rm -it --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:5000"
  • Test the registry: curl http://localhost:5000/v2/_catalog This first time it will be empty: {"repositories":[]} Running the same curl command inside Minikube via minikube ssh is also a good check.

Hostname configuration for Minikube

This runbook uses a generic hostname of minikube.local as an example in commands and the configuration files. You should add the Minikube IP address to the hosts file by using the generic hostname, or else modify the usage of minikube.local in this runbook to reflect your local hostname.

Specifying minikube ip in the following command returns the Minikube VM’s IP address that is accessible from your workstation:

echo -e "$(minikube ip)\tminikube.local" | sudo tee -a /etc/hosts

If not using the Docker inside of the Minikube VM [minikube docker-env](Using Docker inside the Minikube VM), the local Docker client configuration must be also be updated with the corresponding IP address.

  • Update the daemon.json docker configuration file with the Minikube IP address. This file is usually located in:
    • ~/.docker/daemon.json on OSX
    • /etc/docker/daemon.json on Linux
    • C:\ProgramData\Docker\config\daemon.json or $env:USERPROFILE\.docker\daemon.json on Windows, depending on your installation.
  • Restart the Docker daemon:
    • On Linux - run: sudo systemctl restart docker
    • On Mac and Windows - use the “Restart Docker” menu option in the Docker Desktop application.

Example of daemon.json:

{
  "insecure-registries": [
    "192.168.0.0/16"
  ]
}

Note: You can provide a specific IP address, or specify a subnet to future-proof the Docker client configuration.

The Minikube IP address might change when you run minikube delete. If it changes, you must repeat these steps.

Therefore, reconfirm the Minikube IP and its setting in the hosts file every time you start Minikube, or after you run minikube delete.

Minikube Ingress

Ingress is a reverse proxy, which sits in front of the application that is deployed in Kubernetes. It facilitates use of a custom domain name to access a deployed application, instead of using service ports. To enable Ingress for Minikube, you must enable the ingress add-on.

minikube addons enable ingress

Create a namespace

Create a namespace for the SPM deployment, again use an environment variable for your convenience when following the guide.

Create the environment variable, you can set to value to anything you like, but it should consist of lower case alphanumeric characters or -, and must start and end with an alphanumeric character (e.g. my-name, or 123-abc):

export PROJECT="dev"

Create the namespace:

kubectl create namespace $PROJECT

Switch to the new namespace:

kubectl config set-context --current --namespace $PROJECT

Useful Minikube commands

Some useful Minikube commands are as follows:

# Sample commands
minikube status       # See if Minikube is running
minikube start        # Create and start Minikube
minikube dashboard    # Access the Kubernetes dashboard running within the Minikube cluster
minikube ssh          # Login into the Minikube VM
minikube addons list  # Show the status of the available add-ons
minikube stop         # Stop Minikube
minikube delete       # Delete the Minikube VM
minikube ip           # Show the Minikube IP

For a full list of commands, see Installing Kubernetes with Minikube.

Previous
Kubernetes: Kubernetes Overview
Next
Kubernetes: Azure Kubernetes Service