Skip to content

CLI access

For large-scale jobs, automation, and advanced workflows beyond what JupyterHub offers, you can interact with FLAME from the command line using kubectl, the standard Kubernetes command-line client.

Not sure if you need this?

If you're just getting started with FLAME, we recommend trying JupyterHub first. This is the easiest way to use FLAME. You set up CLI access later if you need it.

Installation

You need to install two pieces of software for command-line access to FLAME:

  1. kubectl: the Kubernetes command-line tool, used to run commands against the cluster
  2. Pinniped: authentication helper that integrates kubectl with the FLAME Authentication system

Install kubectl

Follow the official instructions for your operating system:

Verify the installation:

kubectl version --client

Install the Pinniped CLI

Pinniped is what connects kubectl to Drexel's single sign-on. See the official install instructions for all options; the most common methods are below.

Homebrew

brew install vmware-tanzu/pinniped/pinniped-cli

Direct download

curl -Lo pinniped https://get.pinniped.dev/v0.44.0/pinniped-cli-darwin-arm64
chmod +x pinniped
mkdir -p ~/.local/bin && mv pinniped ~/.local/bin/

curl -Lo pinniped https://get.pinniped.dev/v0.44.0/pinniped-cli-darwin-amd64
chmod +x pinniped
mkdir -p ~/.local/bin && mv pinniped ~/.local/bin/

Add ~/.local/bin to your PATH if needed

On macOS, ~/.local/bin may not be on your PATH by default. If pinniped version doesn't work after installing, add this to your ~/.zshrc or ~/.bash_profile:

export PATH="$HOME/.local/bin:$PATH"

curl -Lo pinniped https://get.pinniped.dev/v0.44.0/pinniped-cli-linux-amd64
chmod +x pinniped
mkdir -p ~/.local/bin && mv pinniped ~/.local/bin/

curl -Lo pinniped https://get.pinniped.dev/v0.44.0/pinniped-cli-linux-arm64
chmod +x pinniped
mkdir -p ~/.local/bin && mv pinniped ~/.local/bin/

Download pinniped-cli-windows-amd64.exe from the Pinniped releases page, rename it to pinniped.exe, and add it to your PATH.

Verify the installation:

pinniped version

Download the FLAME kubeconfig

The kubeconfig file, stored at ~/.kube/config, tells kubectl how to connect and authenticate to a cluster. To use FLAME, you need to create ~/.kube/config with a standard configuration file.

There are three options:

Run the following commands to download the kubeconfig directly:

mkdir -p ~/.kube
curl -Lo ~/.kube/config https://red-ocean-0d7a6d80f.7.azurestaticapps.net/assets/flame-kubeconfig.yaml

Click the button below to download the kubeconfig file, then move it to ~/.kube/config:

Download kubeconfig

mkdir -p ~/.kube
mv ~/Downloads/flame-kubeconfig.yaml ~/.kube/config

Create ~/.kube/config using a text editor and paste the following contents:

apiVersion: v1
clusters:
- cluster:
    server: https://k8s.flamecluster.io
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNCVENDQVl5Z0F3SUJBZ0lVQVpENFpPSnNZUEJRQ09sZXV5ZXdrNGl1U1d3d0NnWUlLb1pJemowRUF3TXcKTWpFVU1CSUdBMVVFQ2d3TFJISmxlR1ZzSUZWU1EwWXhHakFZQmdOVkJBTU1FWFZ5WTJZdGNtOXZkQzFqWVMxdwpjbTlrTUI0WERUSTJNREl4T0RFNU1qa3dORm9YRFRRMk1ESXhNekU1TWprd05Gb3dNakVVTUJJR0ExVUVDZ3dMClJISmxlR1ZzSUZWU1EwWXhHakFZQmdOVkJBTU1FWFZ5WTJZdGNtOXZkQzFqWVMxd2NtOWtNSFl3RUFZSEtvWkkKemowQ0FRWUZLNEVFQUNJRFlnQUU4Q3ZxZ2ZOT0xTZkhBcnM2MW9XOCtOZlhyN3p4aU52TEk3WlJUSU1MdGdmVgpBakJoeWYyODJMWjZaa1VPdjdpZ3NMaGlWSmcrL09QNTY1V0NpeEJ1MThlRmRYYjFBSS8xeFljMkpDa1hSbEwvCngxOGlaTUJuL2JCazlVU3ZhNi9RbzJNd1lUQWRCZ05WSFE0RUZnUVVQMXlqcnNlaE84WHJvYit6UXp4a3IxMXAKeSt3d0h3WURWUjBqQkJnd0ZvQVVQMXlqcnNlaE84WHJvYit6UXp4a3IxMXB5K3d3RHdZRFZSMFRBUUgvQkFVdwpBd0VCL3pBT0JnTlZIUThCQWY4RUJBTUNBWVl3Q2dZSUtvWkl6ajBFQXdNRFp3QXdaQUl3Vmd5KzZqN2VrQTh2CkhNZi9ReHhVTmFmNjRCaW5QZHFMSGJXcGdEMWhQMFlRZkkveVJ6SWo3K3ZZN1hYbGJkamJBakF4S0RTQ0V0YSsKUVhYQ0pEVHR3TEZoRnFTY0REMFMveVh0SlZXcnAweW02UWpDa29Ha1ZKekxwejFORjNTejRqOD0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
  name: flame
contexts:
- context:
    cluster: flame
    user: flame
  name: flame
current-context: flame
kind: Config
preferences: {}
users:
- name: flame
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - login
      - oidc
      - --enable-concierge
      - --concierge-authenticator-name=keycloak-authenticator
      - --concierge-authenticator-type=jwt
      - --concierge-endpoint=https://k8s.flamecluster.io
      - --issuer=https://keycloak.flamecluster.io/realms/flame
      - --client-id=pinniped-cli
      - --scopes=openid,email,profile,offline_access
      - --request-audience=pinniped-cli
      command: pinniped
      env: []
      installHint: |
        The pinniped CLI does not appear to be installed.
        See https://pinniped.dev/docs/howto/install-cli/ for installation instructions.
      interactiveMode: IfAvailable
      provideClusterInfo: true

Existing kubeconfig

If you already have a ~/.kube/config for another cluster, back it up first:

cp ~/.kube/config ~/.kube/config.backup

Or keep configs separate with the KUBECONFIG environment variable (substitute the method above accordingly):

export KUBECONFIG=~/.kube/flame-config

Authenticate

Now you're ready to authenticate. Run the following command, which prints info about the machines available in the cluster:

kubectl get nodes

Your browser will open to the Globus Auth login page. Choose "Drexel University" as your institution and sign in with your Drexel username and password (the same process described in Authentication). After login, the browser tab will confirm success and you can close it.

Back in your terminal, the command will complete and show you the cluster nodes. You should see something like this, although the exact contents will vary:

$ kubectl get nodes
NAME            STATUS   ROLES                       AGE     VERSION
prod-cpu01      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-cpu02      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-cpu03      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-cpu04      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-cpu06      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-cpu07      Ready    <none>                      3h35m   v1.33.7+rke2r1
prod-ctrl01     Ready    control-plane,etcd,master   3h41m   v1.33.7+rke2r1
prod-ctrl02     Ready    control-plane,etcd,master   3h39m   v1.33.7+rke2r1
prod-ctrl03     Ready    control-plane,etcd,master   3h39m   v1.33.7+rke2r1
prod-gh200-01   Ready    <none>                      3h29m   v1.33.7+rke2r1
prod-gh200-02   Ready    <none>                      3h29m   v1.33.7+rke2r1

Sessions last a while

After the initial login, Pinniped caches your credentials. You won't need to re-authenticate for every command, only after your session expires.

Set your namespace

Most Kubernetes resources live in a namespace. On FLAME, each workspace has its own namespace.

Not sure what your workspace is?

If you don't know your workspace, email URCF staff and they can tell you.

You can set the namespace for a kubectl command using the -n argument, e.g.:

kubectl get pods -n my-workspace

will list all the pods in my-workspace. However, this gets tedious quickly, so you should set a default namespace as follows:

kubectl config set-context --current --namespace=my-workspace

Now when you run:

kubectl get pods

You'll automatically see only the pods in your workspace namespace.

Getting a shell on the cluster

Rather than SSH, you can get an interactive shell on FLAME by running a pod:

kubectl run my-shell --rm -it --image=ubuntu -- bash

This starts a temporary bash shell in a minimal Ubuntu pod. When you exit, the pod is automatically cleaned up.

Next steps