Running Minishift

See Minishift documentation for a complete list of runtime options. Sections on this page provide a quick reference for starting and running Minishift with Lightbend-recommended parameters.

On public clouds like AWS, it is not possible to use KVM like you do on a local install. If you encounter this issue, follow the instructions at to run on a remote machine.

Start Minishift

To run Lightbend Pipelines or Lightbend Console on Minishift, Lightbend recommends increasing CPUs to 4 and memory to at least 8192. Applications like Spark also require more than the minimum default resources.

  1. Start Minishift, adding any necessary runtime options. For example:

    ./minishift start --cpus=4 --memory=8192

    You’ll see a lot of console output similar to the following example from OpenShift 3.10 This output resulted from using the default options for CPUs and memory and many lines are elided.

    -- Starting profile 'minishift'
    -- Check if deprecated options are used ... OK
    -- Checking if https://github.com is reachable ... OK
    -- Checking if requested OpenShift version 'v3.10.0' is valid ... OK
    ...
    -- Minishift VM will be configured with ...
       Memory:    4 GB
       vCPUs :    2
       Disk size: 20 GB
    
       Downloading ISO 'https://github.com/minishift/minishift-centos-iso/releases/download/v1.12.0/minishift-centos7.iso'
     344.00 MiB / 344.00 MiB [=== ... ===] 100.00% 0s
    -- Starting Minishift VM ................ OK
    ...
    -- OpenShift cluster will be configured with ...
       Version: v3.10.0
    -- Pulling the OpenShift Container Image .......... ... ... OK
    -- Copying oc binary from the OpenShift container image to VM ... OK
    -- Starting OpenShift cluster .............. ... ...
    Getting a Docker client ...
    ...
    Login to server ...
    Creating initial project "myproject" ...
    Server Information ...
    OpenShift server started.
    
    The server is accessible via web console at:
        https://192.168.42.164:8443
    
    You are logged in as:
        User:     developer
        Password: <any value>
    
    To login as administrator:
        oc login -u system:admin
    
    -- Exporting of OpenShift images is occuring in background process with pid 19075.
  2. Once Minishift starts, you can access the OpenShift Web console at https://192.168.42.164:8443 on your machine. The GUI is the same as the one shown by oc cluster up.

  3. Set up your oc CLI command:

    ./minishift oc-env

    It outputs:

    export PATH="`.../.minishift/cache/oc/v{latest-openshift-platform-version}/linux:$PATH"
    # Run this command to configure your shell:
    # eval $(minishift oc-env)
  4. Run the command shown in the comment:

    $ eval $(minishift oc-env)
  5. Run these commands to log in and set the project name to default:

    oc login -u system:admin
    oc project default

With Minishift running, install Helm. Then, you can package and deploy Lightbend Platform applications and install Lightbend Console. You can test and build images directly via the Docker Daemon that runs in Minishift. For more information see this Red Hat documentation.

Stop Minishift

To stop Minishift without deleting the cluster, use the following command. You can then restart Minishift.

Minishift stop

Clean up and start over

If you have issues with Minishift and the VM is not recoverable, clean up and launch Minishift from scratch as follows. This removes the cluster.

  1. Delete the running Minishift instance:

    ./minishift delete
  2. Check whether the VM is still running:

    sudo virsh list --all
    1. If it is running, stop the Minishift VM as follows:

      sudo virsh destroy minishift
  3. Delete the VM:

    sudo virsh undefine minishift
  4. Remove everything under the Minishift directory:

    rm -rf ~/.minishift

Troubleshoot connection and resource issues

The following are some common issues and potential solutions:

  • If you have trouble logging in as system:admin, you can try logging in as user/developer and then try to log in as system:admin, if the problem persists, delete minishift and create a new cluster.

    You can also provide cluster-admin privileges to user developer by executing the following command.

    oc adm policy add-cluster-role-to-user cluster-admin developer
  • If you have trouble accessing the Internet from within Minishift, one option for Ubuntu is to make sure that /run/systemd/resolve/resolv.conf matches /etc/resolv.conf. In general, kubedns uses your host DNS to make things work properly.

  • If you run in a namespace other than the default, use the following command before launching your jobs:

    oc adm policy add-scc-to-user anyuid -z spark-sa -n spark

    Otherwise, you may hit this issue. For more information on security contexts for the containers on OpenShift check this article.

  • When you run Spark jobs in Minishift, if your executors never transition out of the "pending" state, you probably don’t have enough resources.