Using the HPE Kubectl Plugin

The kubectl-hpecp binary is a kubectl plugin that can be installed from a Kubernetes Dashboard screen. For detailed information about kubectl plugins, see the official Kubernetes docs (link opens an external website in a new browser tab or window).

This plugin includes the following commands:

Usage Notes

When you use the kubectl plugin from a headless system, SAML authentication will not work natively. Instead, download the kubeconfig file from the HPE Ezmeral Runtime Enterprise UI and install it on the headless system either one of the following locations:

  • ~/.kube/config
  • A path pointed to by the KUBECONFIG environment variable.

For all OS types, ensure that the kubectl executable and the kubectl-hpecp plugin executable are made available on the user's path.

The sample commands in this topic will vary for Windows users because all commands output by kubectl-hpecp are intended to be run in bash or zsh on the Linux and MacOS operating systems, while all commands for Windows are intended to be run in cmd.exe.

Version Command

The kubectl hpecp version command prints a version-specific string to the console in either a valid JSON or YAML object, as specified by the flags passed in to the command. For example (on MacOS):

 > kubectl hpecp version
{
  "major": "3",
  "minor": "0",
  "gitVersion": "v3.0-159",
  "gitCommit": "15d398acdc03760f0ce269acdf88cc4b5d8cd7e1",
  "gitTreeState": "clean",
  "buildDate": "2020-02-11 00:02:04",
  "goVersion": "go1.13.7",
  "compiler": "gc",
  "platform": "darwin/amd64"
}
>  kubectl hpecp version --output=yaml
major: "3"
minor: "0"
gitversion: v3.0-159
gitcommit: 15d398acdc03760f0ce269acdf88cc4b5d8cd7e1
gittreestate: clean
builddate: "2020-02-11 00:02:04"
goversion: go1.13.7
compiler: gc
platform: darwin/amd64

Refresh Command

The kubectl hpecp refresh command gets the user a new Kubeconfig specific to their needs, as specified by the Kubernetes KUBECONFIG documentation (link opens an external website in a new browser tab or window). This new Kubeconfig contains only contexts that the user can interact with, based on the user's assigned role. See Kubernetes Tenant RBAC.

If HPE Ezmeral Runtime Enterprise is set up for SAML, the user is taken through the SAML login workflow. This requires the user to have a compatible browser. See also Usage Notes.

The semantics for the command are as follows:

>  kubectl hpecp refresh <ip_address-or-host_alias-or-hostname> --insecure --hpecp-user=<new_username> --hpecp-pass=<new_password>
User name with which to authenticate to HPECP:
<username>
Password for user [admin]: <password>
The next step is to send credentials across the network.
Since the TLS connection will not be verified, there is
some risk in this.

Would you like to continue? [y/N]
y
Got a new kubeconfig from the server.

Retrieved new Kube Config from HPECP server at hpe-2:8080.
The KUBECONFIG environment variable HAS NOT been set.
Your current session WILL NOT have the new configuration.
To persist these changes by loading all current Kube Config
values into your default Kube Config file, run the
following command:

    KUBECONFIG="/Users/tom/.kube/.hpecp/hpe-2/config:/Users/tom/.kube/config-backup" kubectl config view --raw > /Users/tom/.kube/config

To persist these changes by changing your local KUBECONFIG
environment variable, run the following command:

    export KUBECONFIG="/Users/tom/.kube/.hpecp/hpe-2/config"

CAUTION - both of these commands will OVERWRITE your current
Kube Config settings. This is probably what you want, but
to confirm that this command will not break your system,
run the following command to view the resulting Kube
Config file:

    KUBECONFIG="/Users/tom/.kube/.hpecp/hpe-2/config:/Users/tom/.kube/config" kubectl config view

Where:

  • <ip_address-or-host_alias-or-hostname> is the IP address, alias, or hostname of the host on which to perform the refresh.
  • <username> is the user name of the current user, assuming that the --hpecp-user flag is not present.
  • <password> is the password of the current user, assuming that the --hpecp-pass flag is not present.
  • --insecure is used when the HPE Ezmeral Runtime Enterprise API is not protected by TLS. This situation is not common.
  • --hpecp-user is optionally used when you want to authenticate to the server as a user (the <new_username>) that is different from the currently logged-in user.
  • --hpecp-pass is optionally used to supply a different password (the <new_password>), such as when using the --hpecp-user flag.

Altering the Kubeconfig for a user is potentially risky, since doing so overwrites any item that has a name conflict. For example, if two kubeconfig files have a user with the name john, only the first kubeconfig to register the name john will show up in the final kubeconfig file.

If a user is expected to interact with more than one HPE Ezmeral Runtime Enterprise deployment, then Hewlett Packard Enterprise recommends configuring each deployment with different custom install names. Custom install names function as a human-readable differentiator between the deployments.

For example, if the user john is expected to interact with two different HPE Ezmeral Runtime Enterprise deployments, and if that user received a different kubeconfig file from each deployment, then that user cannot use both kubeconfigs in the same context, because the user name HPECP-john would not be unique between the kubeconfigs. However, if each deployment has a custom install name (such as test and prod), then john can interact with both systems from the same context, because the user name on each deployment is different. The user from the prod deployment is prod-john, and the user from the test deployment is test-john.

There are some other circumstances that are covered by the kubectl-hpecp refresh command. To view the command-line help, run the kubectl hpecp --help command.

Authenticate Command

This command retrieves the current authentication object from the file system. Plugin users should never need to call this command manually.