Using kubectl

This guide explains how to use kubectl to interact with your PaaS Cloud tenant namespace through OIDC authentication.

Overview

PaaS Cloud uses Keycloak as the OIDC provider for kubectl access. Each tenant has a kubeconfig that invokes the kubectl oidc-login plugin (kubelogin) to obtain a token through your browser before every API request.

For non-interactive automation such as CI/CD pipelines, use service-account tokens instead of the OIDC kubeconfig.

Prerequisites

kubectl installed on your workstation.
The kubectl oidc-login plugin (kubelogin) installed.
A downloaded tenant kubeconfig.

Install kubelogin

Install the plugin using one of the supported methods:

# Krew (macOS, Linux, Windows, ARM)
kubectl krew install oidc-login

# Homebrew (macOS and Linux)
brew install int128/kubelogin/kubelogin

# Chocolatey (Windows)
choco install kubelogin

Verify the installation:

kubectl oidc-login --version

Retrieve Your Tenant Kubeconfig

Download the kubeconfig from the PaaS Cloud dashboard by selecting your tenant and copying the kubeconfig secret from the resource map.

Known Issue: Wrong OIDC Issuer URL

Tenant kubeconfigs generated by Cozystack v1.4 contain a wrong OIDC issuer URL because the info Helm chart builds the URL from the per-tenant _namespace.host value instead of the shared platform _cluster.root-host. Keycloak is deployed as a single shared instance, so the generated URL does not resolve.

Generated (wrong): https://keycloak.cloud.chloe.platform.cloud.e-infra.cz/realms/cozy
Correct: https://keycloak.chloe.platform.cloud.e-infra.cz/realms/cozy

After every download, fix the URL with:

sed -i 's|keycloak.cloud.chloe.platform.cloud.e-infra.cz|keycloak.chloe.platform.cloud.e-infra.cz|g' tenant-cloud.kubeconfig

On macOS, use sed -i '' instead:

sed -i '' 's|keycloak.cloud.chloe.platform.cloud.e-infra.cz|keycloak.chloe.platform.cloud.e-infra.cz|g' tenant-cloud.kubeconfig

Verify the result:

grep oidc-issuer tenant-cloud.kubeconfig

The output should contain:

--oidc-issuer-url=https://keycloak.chloe.platform.cloud.e-infra.cz/realms/cozy

Log In

Run any kubectl command to trigger the login flow:

kubectl --kubeconfig tenant-cloud.kubeconfig get tenant

The terminal prints a URL such as:

Please visit the following URL in your browser: http://localhost:8000/

Open that URL, authenticate through your institutional identity provider, and the command will complete. kubelogin caches the token locally, so subsequent commands do not require re-authentication until the token expires.

Set the Default Namespace

To avoid passing --namespace on every command, set the default context namespace to your tenant:

kubectl --kubeconfig tenant-cloud.kubeconfig config set-context --current --namespace=<tenant-name>

Using virtctl with the Same Kubeconfig

Once kubectl works, virtctl uses the same kubeconfig to access VMs:

export KUBECONFIG=/path/to/tenant-cloud.kubeconfig
virtctl console <vm-name>

See Using virtctl for the full command reference.

Troubleshooting

Problem	Cause / Solution
`kubectl oidc-login: command not found`	kubelogin is not installed or not in your `PATH`. Install it and verify with `kubectl oidc-login --version`.
`Unauthorized` or login loop	The OIDC issuer URL is still wrong. Re-run the `sed` workaround and verify with `grep oidc-issuer`.
Browser does not open	The kubeconfig uses `--skip-open-browser`, so you must copy the printed `http://localhost:8000/` URL into a browser manually.
Token expired / repeated login prompts	kubelogin tokens expire according to Keycloak policy. Re-run any `kubectl` command to refresh the token.
Permission denied on resources	Your Keycloak groups are mapped to tenant RBAC roles. Contact the cloud team if you need a role change.

Tip

If you need non-interactive API access for automation, use a service account token instead of the OIDC kubeconfig. See Identity and Access.

Using kubectl

On this page