Using the Rancher CLI¶

In addition to the Rancher GUI, your software in Spin can also be managed via the Rancher CLI, using a tool called rancher. You might already be familiar with the native Kubernetes CLI tool kubectl, which is actually used by the rancher kubectl subcommand. However, kubectl by itself will not work with Spin due to security and Role Based Access Controls (RBAC) built into Rancher.

Accessing the tool¶

There are two ways to use the Rancher CLI: From a NERSC login node such as perlmutter.nersc.gov or from your laptop.

Either way, you will need to obtain an API key from the Rancher GUI and store it for use with the CLI.

Using the CLI from perlmutter¶

Log into a login node, and load the Spin 2 module:

elvis@perlmutter:login23:~> $ module load spin/2.0
elvis@perlmutter:login23:~> $ which rancher
/global/common/shared/isg/spin/2.0/bin/rancher
elvis@perlmutter:login23:~> $ rancher --version
rancher version v2.4.3
elvis@perlmutter:login23:~> $ 

Then, proceed with obtaining your API credentials below.

Using the CLI from your laptop¶

You will need:

1. An operating system with a good command-line terminal, such as macOS, Linux, or Windows 10 with WSL2.
2. An account on Spin.
3. The kubectl CLI. This is normally provided by Docker for Mac and Docker for Windows, or from the standard package management system on Linux.
4. The rancher CLI. This can be downloaded by logging into https://rancher2.spin.nersc.gov, clicking the menu button in the top left of the page, clicking the version number at the bottom of the panel, and selecting the CLI version you need.

Both rancher & kubectl must be in your $PATH.

$ kubectl version --short
Client Version: v1.17.3
Server Version: v1.16.8

Generate the API credentials & login¶

You will need:

1. A terminal window which is logged in to a NERSC login node, or a terminal window open on your laptop
2. A working Rancher CLI

First, we will generate the API Key (token):

1. Login to https://rancher2.spin.nersc.gov/
2. Browse to the API credential menu at User Icon (Upper right) -> Account and API & Keys

3. Create a key with the following settings

   • Automatically Expire -> 1 year from now. If you're just testing, set the expiration to be 1 month from now. (Expiration dates are good for security)
   • Name = Whatever (Pro Tip: Put the expiration date in the name)
   • Leave Scope as "no scope" (Important)
   • Hit the Create button
   • You are now on a screen that says "A new API Key has been created"
   • Don't click Done until you have saved the key
   • Make note of the important fields Endpoint: and Bearer Token:
     • Ignore the fields Access Key (username) and Secret Key (password). They are combined into the Bearer Token.
   • Keep the browser window open for now

Now, head over to your terminal window, and use the API Key to log in to Rancher. Use the values of the Endpoint (Including the /v3 at the end) and Bearer Token (including the part before and after the :), like so:

rancher login --token <Bearer Token> <Endpoint URL>

You will see something similar to this:

elvis@perlmutter:login23::~> $ rancher login --token a1b2c3:AAAABBBBCCCCDDDDEEEE https://rancher2.spin.nersc.gov/v3
INFO[0000] Only 1 project available: spinup
INFO[0000] Saving config to /global/homes/e/elvis/.rancher/cli2.json
elvis@perlmutter:login23::~> $

And now, test that your token is valid. You will see a list of projects that you have access too:

elvis@perlmutter:login23:~> $ rancher project
ID                NAME      STATE     DESCRIPTION
c-fwj56:p-6q5dd   spinup    active
elvis@perlmutter:login23:~> $

Rancher CLI highlights¶

The rancher CLI supports Rancher-specific commands as well as Kubernetes-specific subcommands via rancher kubectl. Each style of commands has its own help:

• rancher --help for help with the Rancher-specific commands
• rancher kubectl --help for help with the Kubernetes-specific commands.

Some examples are:

• rancher ps - Show workloads in projects
• rancher namespaces - Create/remove/move namespaces within a project

See other Rancher CLI examples at https://rancher.com/docs/rancher/v2.x/en/cli/

Kubernetes examples would be:

• rancher kubectl apply -f my-deployment.yml - Update a Kubernetes resource with the configuration specified in my-deployment.yaml.
• rancher kubectl annotate ... - Apply an annotation to a Kubernetes resource

See other Kubectl examples at https://kubernetes.io/docs/reference/kubectl/overview/ . Remember these must all called as rancher kubectl.

Advanced¶

Multiple projects¶

If you have multiple projects (also called "contexts"), Rancher will prompt you to select a context:

elvis@perlmutter:login23:~> $ rancher login https://rancher2.spin.nersc.gov/v3 --token token-lsw5b:123468734878473897189789127389127
NUMBER    CLUSTER NAME   PROJECT ID        PROJECT NAME   PROJECT DESCRIPTION
1         development    c-fwj56:p-2tlth   elvis        
2         development    c-fwj56:p-4qjxn   spintest       
Select a Project:

More than one token? Use --name¶

elvis@perlmutter:login23:~> $ rancher login --name foo --token token-nql59:lkasjdklsljaskldjaskljasdljsa https://rancher2.spin.nersc.gov/v3
INFO[0000] Only 1 project available: spinup
INFO[0000] Saving config to /global/homes/e/elvis/.rancher/cli2.json
elvis@perlmutter:login23:~> $

To see multiple tokens¶

elvis@perlmutter:login23:~> $ cat /global/homes/e/elvis/.rancher/cli2.json  | jq
{
  "Servers": {
      "foo": {
      "accessKey": "token-EFG59",
      "secretKey": "lkasjdklsljaskldjaskljasdljsa",
      "tokenKey": "token-nql59:lkasjdklsljaskldjaskljasdljsa",
      "url": "https://rancher2.spin.nersc.gov",
      "project": "c-fwj56:p-6q5dd",
      "cacert": ""
    },
    "rancherDefault": {
      "accessKey": "token-ABC79",
      "secretKey": "lkasjdklsljaskldjaskljasdljsa",
      "tokenKey": "token-nql59:lkasjdklsljaskldjaskljasdljsa",
      "url": "https://rancher2.spin.nersc.gov",
      "project": "c-fwj56:p-6q5dd",
      "cacert": ""
    }
  },
  "CurrentServer": "foo"
}
elvis@perlmutter:login23:~> $