Kubectl Plugin
The openunison-cli plugin makes it easier to access your clusters using OpenUnison without having to distribute a kubectl configuration file or logging into the OpenUnison portal first. The plugin is an exec plugin that replaces the Kubernetes standard OIDC integration. When your session expires or you need to re-authenticate, kubectl will pop open a browser window for you, authenticate you, then let you finish the command you wanted to execute. Using this plugin eliminates the need to distribute and update kubectl configuration files to your developers and admins.
Installation
The easiest way to deploy is using the krew plugin manager:
k krew install --manifest-url=https://nexus.tremolo.io/repository/openunison-cli/openunison-cli.yaml
Manual Installation
You can also manually download and install the plugins by adding them to your path and prefixing them with the name "kubectl-". For instance, for MacOS:
wget https://nexus.tremolo.io/repository/openunison-cli/openunison-cli-v1.0.0-macos.zip
unzip openunison-cli-v1.0.0-macos.zip
mv openunison-cli kubectl-openunison-cli
Downloads are available for:
Usage
The openunison-cli plugin has a single user facing command that accepts a single argument: login hostname where hostname is the name of your OpenUnison host. This should be the same as network.openunison_host in your values.yaml:
This will pop open your system browser to log you in to OpenUnison, then generate a kubectl configuration for you. As you use kubectl. the plugin will continue to keep your tokens updated. If your token expires while you're working, the plugin will pop open a new browser window automatically, no need to run the plugin again manually.
FAQ
What is the difference between this plugin and the oidc-login plugin?
The oidc-login plugin is a generic plugin that will work with any OpenID Connect identity provider. It requires that you pre-configure kubectl for use with the OpenID Connect identity provider. The openunison-cli plugin is designed to work with OpenUnison and creates your kubectl configuration for you. There's nothing to pre-configure on the client and no kubectl configuration files to distribute.
Does the openunison-cli plugin use kubectl's OIDC implementation?
No. The openunison-cli plugin is an independent OIDC implementation from kubectl. This allows us to keep the libraries up to date independent of kubectl.
Can I use the kubectl configuration generated by openunison-cli with my scripts?
As of now, the Go lang, Java, Python, and TypeScript SDKs support exec plugins. The .Net SDK does not.
The login process complains about not trusting a certificate, can I use an untrusted cert?
You can use the --cacert-path argument to supply the path to your CA certificate or --cacert-base64 to supply the a base64 encoded PEM of your CA directly from the command line.
Can I Use openunison-cli With Multiple Clusters?
Yes. If you run kubectl openunison-cli login cluster1 it will set your cluster configuration for cluster1. If you then run kubectl openunison-cli login cluster2 if will set your configuration for cluster2. You can then switch clusters using normal kubectl commands.
Legacy Kubectl Plugin
The legacy oulogin plugin is deprecated. We will no longer be publishing new releases and will remove the downloads and documentation on September 1, 2026
This plugin will launch a browser to log you into your Kubernetes cluster from the command line. This plugin requires OpenUnison to be integrated with Kubernetes. One of the Orchestra portals will likely fit your use case (https://github.com/openunison/). This plugin:
- Launches a browser to authenticate you to OpenUnison (and your identity provider)
- Creates a context and user in your kubectl configuration
- Sets the new configuration as your default context
There is no pre-configuration that needs to happen. OpenUnison provides all the configuration for your cluster, just as if logging into OpenUnison and getting the configuration from the token screen and pasting it into your cli window.
Installation
The simplest way to install this plugin is via the krew plugin manager:
Running
The plugin takes one parameter, host, the host of your OpenUnison. There is no need to have an existing kubectl configuration file. If one exists, the cluster configuration will be added to it.
FAQ
What is the difference between this plugin and the oidc-login plugin?
The oidc-login plugin is a generic plugin that will work with any OpenID Connect identity provider. It requires that you pre-configure kubectl for use with the OpenID Connect identity provider. The oulogin plugin is designed to work with OpenUnison and creates your kubectl configuration for you. There's nothing to pre-configure on the client.
The login process complains about not trusting a certificate, can I use an untrusted cert?
The OpenUnison certificate MUST be trusted by your client. The OpenUnison certificate can be obtained by logging into OpenUnison and clicking on the token screen.
Can I Use oulogin With Multiple Clusters?
Yes. If you run kubectl oulogin --host=cluster1 it will set your cluster configuration for cluster1. If you then run kubectl oulogin --host=cluster2 if will set your configuration for cluster2. Running kubectl oulogin --host=cluster1 again will just switch your context.
Will The Plugin Prompt Me To Login, Even With a Valid Session?
No, if your id_token is still OK and your still able to interact with the API server then you aren't prompted to login again.