Skip to content
h8lio

kubectl

The Kubernetes command line tool kubectl allows you to control your cluster resources.

Installation

Section titled “Installation”

Reference

Section titled “Reference”

Prerequisites

Section titled “Prerequisites”
  • A shell terminal
  • A browser access to authenticate using Kubelogin from the computer where kubectl will be installed.

if you don’t have access to a browser from the computer where kubectl will be installed (example, headless server), you can install it on a computer which does and copy the .kube/config once you have been authenticated

kubectl

Section titled “kubectl”

Example of an installation on a linux computer (more details on the official documentation).

Terminal window
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl version --client
Section titled “Bash completion (recommended)”
Terminal window
apt-get install bash-completion
type _init_completion
kubectl completion bash | sudo tee /etc/bash_completion.d/kubectl > /dev/null

Authentication

Section titled “Authentication”

The OIDC authentication kubectl plugin kubelogin handles the SSO login to the h8lio identity provider.

  1. Get your kubeconfig. The easiest way is to download it from the h8lio dashboard: open your cluster in the Cloud view and use the Access panel to view, copy or download a ready-to-use config - every field, including the credentials, is already filled in. Alternatively, build it from the template below, or merge its clusters, contexts and users entries into an existing ~/.kube/config.
  2. Install kubelogin. The generated kubeconfig invokes the standalone kubelogin binary (command: kubelogin), so make sure it is on your PATH. Install the latest release of int128/kubelogin (GitHub releases, or Homebrew brew install int128/kubelogin/kubelogin); see the setup guide. No minimum version is required - the kubeconfig uses the broadly-compatible client.authentication.k8s.io/v1beta1 contract - but a recent version is recommended for bug fixes and for the --browser-command flag (see below).
  3. Test. Run any kubectl command, for example kubectl get pods. The first call opens your browser to authenticate to h8lio; once you authorize the access, a refresh token renews the session automatically, so you only log in once.

Installed via krew instead? kubectl krew install oidc-login provides the plugin as kubectl oidc-login (it does not install a kubelogin binary). In that case set command: kubectl and prepend oidc-login to the args, before get-token.

.kube/config template

Section titled “.kube/config template”

The following code block mirrors the config file generated by h8lio. It uses the kubelogin exec credential plugin (the current OIDC form; the older auth-provider: oidc style is deprecated and does not perform an interactive login). You need to replace:

  • [username]: name of the user, example: john.doe. It does not have to be an h8lio user - kubelogin only needs an existing member to authenticate against.
  • [namespace]: your namespace (ie. h8lio cluster: [domain]-[cluster]), example: demo-prod
  • [client-id] and [client-secret]: the OIDC client credentials of the h8lio kubernetes application (already filled in when you download the file from the dashboard).
apiVersion: v1
kind: Config
current-context: [username]@h8l.io
clusters:
- name: h8l.io
  cluster:
    server: https://kube-api.h8l.io
contexts:
- name: [username]@h8l.io
  context:
    cluster: h8l.io
    namespace: [namespace]
    user: [username]
users:
- name: [username]
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubelogin
      args:
        - get-token
        - --oidc-issuer-url=https://id.byzaneo.io/
        - --oidc-client-id=[client-id]
        - --oidc-client-secret=[client-secret]
        - --oidc-extra-scope=profile
        - --oidc-extra-scope=email
        - --oidc-extra-scope=offline_access
      interactiveMode: IfAvailable
      installHint: "kubelogin required - https://resources.h8l.io/docs/kubernetes/kubectl/"

Notes on the form above:

  • apiVersion: client.authentication.k8s.io/v1beta1 (not v1): kubelogin returns its ExecCredential in this version, and it is compatible with every kubectl/kubelogin version. A kubeconfig declaring v1 against an older kubelogin fails with exec plugin … returned version …/v1beta1.
  • --oidc-extra-scope does not list openid: kubelogin always requests it on its own. h8lio adds profile, email (the cluster maps the user identity from the email claim) and offline_access (refresh token).

if you already have a ~/.kube/config, merge the clusters, contexts and users entries above into it (and use kubectx to switch contexts). Every h8lio kubeconfig names its cluster h8l.io and its context [username]@h8l.io, so rename them on merge if you keep several namespaces, to avoid collisions.

Authenticate as a different user or choose your browser

Section titled “Authenticate as a different user or choose your browser”

By default kubelogin opens your system browser and reuses any active h8lio SSO session - convenient, but it signs you in as whoever is already logged in. To authenticate as another user (or simply pick the browser), add flags to the exec.args of your kubeconfig:

  • --browser-command=... (kubelogin ≥ v1.28) - open the login URL with a specific browser or profile instead of the default one, e.g. a private window.
  • --skip-open-browser - kubelogin prints the login URL instead of opening a browser; copy it into a private window (or another profile) and sign in there. The http://localhost:8000 redirect completes the flow.
  • --oidc-auth-request-extra-params=prompt=login - force the Auth0 login screen instead of silently reusing the current SSO session.

kubelogin caches tokens in ~/.kube/cache/oidc-login/ (separate from ~/.kube/config). If you already authenticated as another user, run kubelogin clean before retrying - otherwise the cached token is reused and the prompt flags are ignored.

Multiple Context and/or Namespaces (optional)

Section titled “Multiple Context and/or Namespaces (optional)”

If you have multiple Kubernetes Clusters and/or Namespaces, we recommend to install respectively the command tools kubectx and kubens to easily switch between them. Please refer to the project documentation.

Usage

Section titled “Usage”

Check the reference documentation of the kubectl command line: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands

Some useful commands:

Going further…

Section titled “Going further…”

Once kubectl is installed and configured on your local machine or server to access your h8lio clusters, you will be able to install and use more tools and applications such as: