Getting Access & LBNL SSO

Access to the Berkelium Kubernetes Cluster is open to all Lawrence Berkeley National Laboratory (LBNL) staff, scientists, postdocs, and affiliated guest researchers.

Prerequisites

1. An active LBNL OneID / LDAP credential (@lbl.gov email address).
2. A principal investigator (PI) or project grant reference (LDRD, DOE Office of Science, NIH, etc.).
3. Installed Kubernetes CLI tools (kubectl and kubelogin).

---

Step 1: Sign in to the User Portal

Navigate to the Berkelium User Portal Login page. You can authenticate using LBNL OneID Single Sign-On (SSO) or your institutional LDAP credentials.

Upon your first sign-in:

• Your identity is verified against Berkeley Lab Shibboleth directory.
• An institutional user profile is initialized for your division.

---

Step 2: Request or Create a Project Namespace

Compute resources on Berkelium are scoped within Namespaces. Each research team or project operates inside an isolated namespace with its own RBAC access controls and shared CephFS storage.

1. Go to the Self-Service Namespace Portal.
2. Click Create Namespace.
3. Choose a custom namespace name adhering to Kubernetes RFC 1123 naming rules (2 to 63 characters, lowercase alphanumeric characters and hyphens, starting and ending with an alphanumeric character, e.g. bio-genomics, materials-sim, or als-beamline). Any unique name is supported provided it is not already taken and does not conflict with reserved system namespaces (kube-*, *-system, *-operator, cert-manager, monitoring, etc.).
4. Submit the form to provision your namespace immediately.

---

Step 3: Configure kubectl and kubelogin

To control workloads from your local terminal or a remote lab server, you need kubectl along with the kubelogin (kubectl oidc-login) plugin.

Install kubelogin First

You must install the kubelogin plugin before running kubectl with your Berkelium configuration. Without it, kubectl will fail to authenticate with LBNL OneID / Authentik.

Installation Options

macOS (via Homebrew)

brew install kubernetes-cli
brew install kubelogin

Linux (Ubuntu / Debian / RHEL / CentOS)

You can install the latest release dynamically for both amd64 (x86_64) and arm64:

# 1. Install kubectl
sudo curl -fsSL -o /usr/local/bin/kubectl https://dl.k8s.io/release/v1.31.0/bin/linux/amd64/kubectl
sudo chmod +x /usr/local/bin/kubectl

# 2. Download and install kubelogin
OS_ARCHITECTURE="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
OS_NAME="linux"

KUBELOGIN_VERSION="$(curl -fsSL "https://api.github.com/repos/int128/kubelogin/releases/latest" | jq -r '.tag_name')"
curl -o kubelogin.zip -fSL "https://github.com/int128/kubelogin/releases/download/${KUBELOGIN_VERSION}/kubelogin_${OS_NAME}_${OS_ARCHITECTURE}.zip"
unzip -o kubelogin.zip kubelogin
chmod +x ./kubelogin

# System-wide installation (requires sudo):
sudo mv ./kubelogin /usr/local/bin/kubectl-oidc_login
sudo chown root: /usr/local/bin/kubectl-oidc_login
rm -f kubelogin.zip

Non-Root / HPC Installation (No sudo)

If you are working on a shared lab cluster, Perlmutter, or a machine where you do not have root access, install kubelogin into your user home directory:

mkdir -p ~/.local/bin
mv ./kubelogin ~/.local/bin/kubectl-oidc_login
chmod +x ~/.local/bin/kubectl-oidc_login
export PATH="$HOME/.local/bin:${PATH}"
rm -f kubelogin.zip

Ensure export PATH="$HOME/.local/bin:${PATH}" is added to your ~/.bashrc or ~/.zshrc.

Windows

You can install kubelogin using package managers:

• Chocolatey: choco install kubelogin
• Scoop: scoop install kubelogin
• Or download the binary zip from the kubelogin GitHub Releases and add it to your Windows PATH.

Via krew (Kubectl Plugin Manager)

kubectl krew install oidc-login

---

Step 4: Download Your Kubeconfig

1. Go to the CLI & Kubeconfig Generator.
2. Select your provisioned namespace from the dropdown.
3. Click Download File and place it in your ~/.kube/config path:

mkdir -p ~/.kube
mv ~/Downloads/berkelium-bio-genomics-config.yaml ~/.kube/config
chmod 600 ~/.kube/config

4. Test connectivity to Berkelium (substitute your custom namespace name):

kubectl get pods -n bio-genomics

Your browser will automatically open to authenticate your LBNL credentials, confirming cluster access!

Recommended Cluster Tools: Radar & K9s

Once your ~/.kube/config is set up, you can control your namespace without typing verbose kubectl commands:

• Radar (radarhq.io): A modern local web GUI (brew install skyhook-io/tap/radar && kubectl radar) that visualizes your namespace topology, streams live logs, and manages workloads in your browser.
• K9s (k9scli.io): A fast, interactive terminal UI (brew install derailed/k9s/k9s && k9s -n <your-namespace>) ideal for navigating pods, logs, and shells directly in your terminal or over SSH.

See Using Berkelium for details.

---

Cross-Platform kubelogin Fixes (WSL / Linux / Headless / macOS)

If you encounter authentication or connectivity issues when running kubectl, you can customize the exec.args section of your ~/.kube/config file to apply the following fixes:

1. No Local Browser Available (Remote SSH / Headless Server / Perlmutter)

If you are logged into a remote server via SSH without an X11/GUI display, kubelogin cannot open a desktop browser. Add --grant-type=device-code and --skip-open-browser to your config args:

args:
  - oidc-login
  - get-token
  - --grant-type=device-code
  - --skip-open-browser

When you run kubectl, it will output an authentication link and a one-time code in your terminal:

Please visit the following URL in your browser: https://authentik.scs.lbl.gov/device?user_code=XXXX-XXXX

Open the URL in any web browser on your laptop or phone, enter the code, and authenticate via LBNL SSO.

2. Browser Issues in WSL (Windows Subsystem for Linux)

In WSL environments, Linux cannot always automatically launch the host Windows browser. Direct kubelogin to execute the host Windows Chrome or Edge executable:

args:
  - oidc-login
  - get-token
  - --browser-command="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"

(For Microsoft Edge, use /mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe).

3. Port Binding Conflicts (port 8000 already in use)

By default, kubelogin starts a local HTTP listener on port 8000 to receive the OAuth redirect callback. If another application (such as a local dev server or Jupyter notebook) is already listening on port 8000:

args:
  - oidc-login
  - get-token
  - --listen-address=127.0.0.1:18000

(You can select any unused high port, such as 18000 or 28000).

4. Keyring Storage Errors (/run/user/1000/bus not found or DBus errors)

On minimal Linux installations, containers, or headless servers without a running desktop keyring daemon (Secret Service / DBus), kubelogin fails when trying to store tokens in the OS keyring. Switch token caching to disk storage:

args:
  - oidc-login
  - get-token
  - --token-cache-storage=disk

Token Security

On personal desktop workstations (macOS Keychain, Linux GNOME Keyring), using --token-cache-storage=keyring is recommended for encrypted credential storage. On headless remote servers, use --token-cache-storage=disk.

Complete Example ~/.kube/config User Block

Here is how a customized users entry looks in ~/.kube/config with these flags integrated:

users:
- name: oidc@berkelium
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=https://authentik.scs.lbl.gov/application/o/berkelium-k8s/
      - --oidc-client-id=fJViF79iPIMqRFnIojzaatoo8CJNXmHs22lXqBkE
      - --oidc-extra-scope=profile,groups,offline_access
      - --listen-address=127.0.0.1:18000
      - --token-cache-storage=disk
      # Optional: uncomment if working on a remote SSH console without a GUI browser
      # - --grant-type=device-code
      # - --skip-open-browser
      # Optional: uncomment for Windows Subsystem for Linux (WSL)
      # - --browser-command="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"

---

Updating Namespace Membership & Refreshing Tokens

Access tokens are cached locally and typically refresh automatically upon expiration. However, if your permissions, roles, or group memberships have changed (for example, after being added to a new project namespace in the portal) and you need to force an immediate refresh, run:

kubectl oidc-login clean

This clears the cached tokens. Your next kubectl command will prompt you to re-authenticate with LBNL OneID and fetch updated namespace claims immediately.