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 OpenZiti 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 an OpenZiti Tunneler app
  7. Optional: Install curl and jq for testing an OpenZiti 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.

  • minicontroller.ziti
  • miniconsole.ziti
  • minirouter.ziti

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.

    # miniziti
    127.0.0.1  minicontroller.ziti  minirouter.ziti  miniconsole.ziti

  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.

    $ 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:

    % wsl -l -v
    FIXME: paste output here showing WSL, docker-desktop, docker-desktop-data running

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

    grep ziti /etc/hosts

    It should look like this.

    $ grep ziti /etc/hosts
    127.0.0.1    minicontroller.ziti  minirouter.ziti  miniconsole.ziti

  6. 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

BASH Script​

You can run this 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.

To run the script you'll need to download the file and run it like this:

bash ./miniziti.bash

Add the Client Identity​

Add the client identity you created to your OpenZiti Tunneler.

Follow the instructions for your tunneler OS version to add the OpenZiti 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 OpenZiti Tunneler, e.g. Ziti Desktop Edge
nslookup testapi.ziti

Test the Demo API Service​

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

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

Explore the OpenZiti Console​

Now that you've successfully tested the OpenZiti Service, check out the various entities in your that were created by the script in http://miniconsole.ziti/.

Next Steps​

  1. In the OpenZiti 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 "minirouter" by adding a role.

      # the role you add needs to match the bind policy's identity roles
      ziti edge update identity "minirouter" \
         --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 an OpenZiti Tunneler.

Cleanup​

  1. Remove the mini*.ziti DNS names from the system hosts file.

    Edit the system hosts file.

    %SYSTEMROOT%\system32\drivers\etc\hosts

    Remove this line.

    # miniziti
    127.0.0.1  minicontroller.ziti  minirouter.ziti  miniconsole.ziti

  1. Delete the cluster.

    minikube --profile miniziti delete

  2. In your OpenZiti Tunneler, "Forget" your Identity.

minikube ingress-dns nameserver​

This option configures your host to use use the DNS addon we enabled earlier for DNS names like *.ziti. If you do this then you don't need to edit the /etc/hosts file at all.

  1. Make sure the DNS addon is working. Send a DNS query to the address where the ingress nameserver is running.

    nslookup minicontroller.ziti $(minikube --profile miniziti ip)

    You know it's working if you see the same IP address in the response as when you run minikube --profile miniziti ip.

  2. Configure your computer to always send certain DNS queries to the ingress-dns nameserver. Follow the steps in the minikube web site to configure macOS, Windows, or Linux's DNS resolver.

    Now that your computer is set up to use the minikube DNS server for DNS names that end in *.ziti, you can test it again without specifying where to send the DNS query.

    # test your DNS configuration
    nslookup minicontroller.ziti

    You know it's working if you see the same IP address in the response as when you run minikube --profile miniziti ip.