To be able to use the Kubernetes cluster set up by Okctl you can run

# Usage
okctl venv -c <path to cluster declaration>

# Example
okctl venv -c cluster.yaml

This will run a subshell with everything you need (hence a "virtual environment") to use  your Kubernetes cluster, such as kubectl.

Verify that everything works by running

kubectl --namespace kube-system get pod


By setting these environment variables before running okctl venv, you can customize its behavior.

Environment variable Default Description
OKCTL_NO_PS1 true If true, disables overriding the PS1. This will keep the exsisting PS1
OKCTL_PS1 not set If set, venvwill use this as the PS1 in the executed subshell.
OKCTL_SHELL true Override which shell to run. For instance /bin/sh

Any occurrence of %env in OKCTL_PS1 will be replaced by the Okctl environment. This makes it possible to get the Okctl environment in your custom OKCTL_PS1. A use case for this can be when combining with the venv_ps1 built-in:

export OKCTL_PS1="\w \$(venv_ps1 %env) $"
okctl venv myenv

The command prompt will then be like this:

/tmp myenv:mynamespace $


When running okctl venv, Okctl does the following things

  • downloads the correct version of kubectl and other binaries needed for your environment
  • runs a subshell with the environment variables from okctl show credentials already set
  • sets the OKCTL_CLUSTER_DECLARATION environment variable. This allows you to omit the --cluster-declaration flag when running context-dependent operations like apply application
  • sets a command prompt like this (example):
~/somepath (myenv:mynamespace) $

where ...

  • myenv will be replaced with the name of your Okctl environment
  • mynamespace will be replaced with the name of the Kubernetes namespace of your current kube context.

This command prompt can be turned off or configured, see below.


Instead of running okctl venv, you can adjust your existing shell. Do this by using  the show credentials command. When running this command, you'll get a bunch of environment variables that need to be set for you to access the cluster.

To be able to set these quickly in a new terminal, you could do something like:

. <(okctl show credentials -c cluster.yaml)

Note: If this hangs, it may be because Okctl is prompting login details, which is hidden when running it like this. Run okctl show credentials  -c cluster.yaml first, if this happens.


As we've seen, venv provides a way of quickly accessing the Kubernetes cluster.