Skip to content
  • ✓ AIP1 Isambard-AI Phase 1 supported
  • ✗ AIP2 Isambard-AI Phase 2 unsupported
  • ✗ I3 Isambard 3 unsupported
  • ✗ BC5 BlueCrystal 5 unsupported

Kubernetes: kubectl Access - Experimental Access Only

Warning

This guide describes the experimental Kubernetes service on Isambard-AI Phase 1, which is invite-only and not designed for production workloads. See the Kubernetes overview for details of the service, the cluster and the policies that apply to it.

You can use kubectl on your own machine to manage resources in your project's namespace on Isambard-AI Phase 1. You log in with OIDC through Keycloak, which grants you the same permissions as your project service account (see Namespaces and service accounts).

kubectl is run from your own machine, not from the Isambard login nodes.

Install kubectl and kubelogin

  1. Install kubectl by following the Kubernetes install instructions for your operating system.

  2. Install kubelogin, which kubectl uses to log you in through Keycloak. kubelogin is a kubectl plugin, and is run as kubectl oidc-login. For example, with Krew or Homebrew:

    # With Krew
kubectl krew install oidc-login

# Or, with Homebrew
brew install kubelogin

    See the kubelogin setup instructions for other installation methods.

    Not Azure kubelogin

    Make sure you install int128/kubelogin. Azure provides a different tool, also called kubelogin, which will not work with Isambard-AI.

  3. Check the plugin is installed:

    kubectl oidc-login --help

Create a kubeconfig file

Save the following to ~/.kube/isambard-ai.yaml, replacing <PROJECT> with your project's short code:

apiVersion: v1
kind: Config
clusters:
  - name: isambard-ai
    cluster:
      server: https://apps.isambard.ac.uk/kubectl-k8s-on-compute
contexts:
  - name: isambard-ai
    context:
      cluster: isambard-ai
      user: isambard-ai-oidc
      namespace: <PROJECT>
current-context: isambard-ai
users:
  - name: isambard-ai-oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://keycloak.isambard.ac.uk/realms/isambard
          - --oidc-client-id=kubectl-k8s-on-compute
          - --grant-type=device-code
        interactiveMode: IfAvailable

Setting namespace in the context means you don't need to pass --namespace to every kubectl command.

Point kubectl at this file:

export KUBECONFIG=~/.kube/isambard-ai.yaml

Add this line to your shell profile (for example ~/.bashrc or ~/.zshrc) to make it permanent. If you already use other clusters, you can instead merge this file into your existing ~/.kube/config and switch between them with kubectl config use-context.

Log in

Run any kubectl command, for example:

kubectl get pods -n <PROJECT>

The first time you run a command, kubelogin prints a URL and a code. Open the URL in your browser, enter the code and log in through Keycloak with your Identity Provider. kubectl then runs the command.

As you have not created anything yet, you should see:

No resources found in <PROJECT> namespace.

To check who you are logged in as:

kubectl auth whoami

ATTRIBUTE   VALUE
Username    <USERNAME>
Groups      [projectuser:<PROJECT>:<USERNAME> system:authenticated]

Your projectuser:<PROJECT>:<USERNAME> group is what gives you access to your project's namespace. You can only see and manage resources in the <PROJECT> namespace.

kubelogin caches your token and logs you in again when it expires. To log out, delete the cache:

kubectl oidc-login clean

To see what you are allowed to do in your namespace:

kubectl auth can-i --list

Next steps