Skip to main content
Star us on GitHub Star

Kubernetes Quickstart

minikube quickly sets up a local Kubernetes cluster on macOS, Linux, or Windows (WSL). This quickstart is a great way to explore running your own controller, Router, and Console.

Tools of the Trade​

We'll use the preferred minikube Docker driver for this quickstart. You can run minikube in WSL with Docker Engine or Docker Desktop, but keep an eye out for one extra step to run minikube tunnel at the necessary point in the process.

  1. Install Docker
  2. Install kubectl
  3. Install Helm
  4. Install minikube
  5. Install ziti CLI
  6. Install a tunneler app
  7. Optional: Install curl and jq for testing a service in the terminal.

Make sure these command-line tools are available in your executable search PATH.

Configure DNS​

Your computer running minikube needs to resolve these three domain names. They will all resolve to the same IP address where minikube exposes ingresses on your OS.

  • miniziti-controller.miniziti.internal
  • miniziti-router.miniziti.internal

This step allows you to connect to the minikube ingresses from Windows or WSL. We'll need that connection to the ingresses later when we run the ziti CLI in WSL.

  1. Enable localhost binding in WSL.

    %USERPROFILE%\.wslconfig

    Add localhostforwarding=true to the [wsl2] section like this.

    [wsl2]
    # Turn off default connection to bind WSL 2 localhost to Windows localhost
    localhostforwarding=true

  2. Add the DNS names to the system hosts file. This allows us to resolve the DNS names from both Windows and WSL.

    Edit the system hosts file.

    %SYSTEMROOT%\system32\drivers\etc\hosts

    Add this line to the system hosts file.

    127.0.0.1  miniziti-controller.miniziti.internal  miniziti-router.miniziti.internal

  3. Restart WSL.

    wsl --shutdown

  4. In WSL, verify that Docker restarted successfully.

    docker ps

    If Docker has restarted then you'll see your running containers, if any. If you don't have any running containers then you'll only see the headings, like this. This is a healthy result and you can skip to the next numbered step.

    Example Output
    $ docker ps
    CONTAINER ID   IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES

    If you see an error then you need to restart Docker. If you have Docker Desktop it may be necessary to "Quick Docker Desktop" in the system tray menu (right-click tray icon).

    You can verify that the docker-desktop-data instance is running with this PowerShell command.

    wsl -l -v

    Example output:

    Example Output
    PS C:\Users\w> wsl -l -v
      NAME                   STATE           VERSION
    * Ubuntu                 Running         2
      docker-desktop         Running         2
      docker-desktop-data    Running         2

If Docker Desktop is not running then it may be necessary to start it in WSL, depending on how you have installed Docker Desktop.

  1. In WSL, verify that localhost is bound. You know it's working if you see the *.miniziti.internal DNS names in /etc/hosts duplicated from Windows.

    grep ziti /etc/hosts

    It should look like this.

    Example Output
    $ grep ziti /etc/hosts
    127.0.0.1    miniziti-controller.miniziti.internal miniziti-router.miniziti.internal

  2. In WSL, Run minikube tunnel.

    Keep a separate terminal window open so you can make sure the tunnel is still running and provide your password if prompted. Create a "miniziti" profile if you haven't, and run the tunnel.

    info

    You will likely be prompted by minikube tunnel for your WSL user's password, but this prompt may not occur immediately. This grants permission for the tunnel to add a route to the minikube node IP.

    minikube --profile miniziti start
    minikube --profile miniziti tunnel

miniziti Script​

You can run the miniziti shell script or perform the steps manually yourself. Click the "Manual Steps" tab directly above to switch your view.

It's recommended that you read the script before you run it. It's safe to re-run the script if it encounters a temporary problem.


DOWNLOAD: miniziti.bash


Be sure to complete the DNS setup steps above before running this command.
bash ./miniziti.bash

Add the Client Identity​

Add the client identity you created to your tunneler.

Follow the instructions for your tunneler OS version to add the identity that was saved as filename /tmp/miniziti-client.jwt (or WSL's "tmp" directory, e.g., \\wsl$\Ubuntu\tmp in Desktop Edge for Windows).

As soon as identity enrollment completes you should have a new OpenZiti DNS name available to this device. Let's test that with a DNS query.

this DNS answer is coming from the tunneler, e.g. Ziti Desktop Edge
nslookup httpbin.miniziti.private

Test the Demo API Service​

macOS or Linux, including WSL
curl -sSf -XPOST -d ziti=awesome http://httpbin.miniziti.private/post | jq .data

Visit http://httpbin.miniziti.private/get in your web browser in macOS, Linux, or Windows to see a JSON test response from the demo server.

Explore the Console​

Now that you've successfully tested the service, check out the various entities in your that were created by the script in http://miniziti-controller.miniziti.internal/zac/.

Next Steps​

  1. In the console, try to revoke then restore your permission to acess the demo services.

  2. Deploy a non-Ziti demo application to Kubernetes and securely share it with a Ziti proxy pod

  3. Add a configs, service, and policies to access the Kubernetes apiserver with OpenZiti.

    1. Hint: the apiserver's address is "kubernetes.default.svc:443" inside the cluster.

    2. Hint: After you create the configs, service, and policies, grant "Bind" permission for the service to "miniziti-router" by adding a role.

      the role you add needs to match the bind policy's identity roles
      ziti edge update identity "miniziti-router" \
         --role-attributes k8sapi-hosts

    3. Connect to the K8s apiserver from another computer with kubeztl, the OpenZiti fork of kubectl. kubeztl works by itself without a tunneler.

Cleanup​

  1. Remove the relevant *.miniziti.internal DNS names from the system hosts file.

    Edit the system hosts file.

    %SYSTEMROOT%\system32\drivers\etc\hosts

    Remove this line.

    127.0.0.1  miniziti-controller.miniziti.internal  miniziti-router.miniziti.internal

  1. Delete the cluster.

    minikube --profile miniziti delete

  2. In your tunneler, "Forget" your Identity.

    Try the Wizard