Command-line Client

Installing the SLATE Client

The SLATE Client is a command line interface (CLI) intended to give edge administrators and application administrators a convenient way to work with the platform.

You can get the client executable and credentials from the web portal. To set up the client, first log into the web portal, go to the ‘CLI Access’ section, and run the provided script (note that it’s specific to your account). You can then download and unpack the version of the client executable suitable for your system—Linux and Mac OS are supported.

Basic Use

For help using the client, run it with the –help option:

$ slate --help
SLATE command line interface
Usage: ./slate [OPTIONS] SUBCOMMAND
Options:
-h,--help Print this help message and exit
--no-format Do not use ANSI formatting escape sequences in output
--width UINT The maximum width to use when printing tabular output
--api-endpoint URL (Env:SLATE_API_ENDPOINT)
The endpoint at which to contact the SLATE API server
--api-endpoint-file PATH (Env:SLATE_API_ENDPOINT_PATH)
The path to a file containing the endpoint at which to contact the SLATE API server. The contents of this file are overridden by --api-endpoint if that option is specified. Ignored if the specified file does not exist.
--credential-file PATH (Env:SLATE_CRED_PATH)
The path to a file containing the credentials to be presented to the SLATE API server
--output TEXT The format in which to print output (can be specified as no-headers, json, jsonpointer, jsonpointer-file, custom-columns, or custom-columns-file)
Subcommands:
version Print version information
completion Print a shell completion script
group Manage SLATE groups
cluster Manage SLATE clusters
app View and install SLATE applications
instance Manage SLATE application instances
secret Manage SLATE secrets

In this (abbreviated) output, three edge clusters are listed. Each cluster has name associated with it for convenience, an automatically-generated unique identifier, and a group which administers it (here, all three clusters are administered by the SLATE team). All objects in the SLATE platform have unique IDs, and these must often be specified when using the client to indicate which objects you wish to manipulate. Groups and clusters have globally-unique names as well, though, so, when specifying a group or cluster, you can always use the name instead of the ID.

Creating a Group

To do much on the SLATE platform you must belong to a group, since groups are the foundation of SLATE’s permissions model. You can either join a group by asking a person who is already a member to add you, or you can create a new group with the commandslate group create. Note that newly created groups don’t generally have access to any resources (edge clusters), but they can add resources of their own. A user can also belong to several groups.

If you’re a system administrator at the fictional University of Southern North Dakota at Hoople, and you want to add your Kubernetes cluster to the SLATE platform, you would begin by creating a group:

When creating a group it is required that you specify the science field in which it works, or ‘Resource Provider’ if your group existing mainly to provide computing resources to the platform. For a full list of fields of science currently allowed by SLATE, see this page.

As the creator of the group, you are automatically a member. You can then use the web portal add other users.

Registering a Cluster

The slate cluster create command can register your Kubernetes cluster with the SLATE platform. It will ask your permission to install components which will allow the SLATE platform and its users to access your cluster with limited permissions controlled by Kubernetes Role-Based Access Control (RBAC). Once the registration is completed, the SLATE platform will only be able to access Kubernetes objects within the namespace created during registration and namespaces (prefixed with slate-) that it creates:

$ slate cluster create --group usnd-hoople --org "USND Hoople" hoople
Extracting kubeconfig from /Users/admin/.kube/config...
Checking for privilege level/deployment controller status...
It appears that the nrp-controller is not deployed on this cluster.
The nrp-controller is a utility which allows SLATE to operate with
reduced privileges in your Kubernetes cluster. It grants SLATE access to a
single initial namespace of your choosing and a mechanism to create additional
namespaces, without granting it any access to namespaces it has not created.
This means that you can be certain that SLATE will not interfere with other
uses of your cluster.
See https://gitlab.com/ucsd-prp/nrp-controller for more information on the
controller software and
https://gitlab.com/ucsd-prp/nrp-controller/raw/master/deploy.yaml for the
deployment definition used to install it.
This component is needed for SLATE to use this cluster.
Do you want to install it now? [y]/n: y
Applying https://gitlab.com/ucsd-prp/nrp-controller/raw/master/deploy.yaml
Waiting for Custom Resource Definitions to become active...
Checking for federation ClusterRole...
ClusterRole is defined
SLATE should be granted access using a ServiceAccount created with a Cluster
object by the nrp-controller. Do you want to create such a ServiceAccount
automatically now? [y]/n: y
Please enter the name you would like to give the ServiceAccount and core
SLATE namespace. The default is 'slate-system':
Creating Cluster 'slate-system'...
Locating ServiceAccount credentials...
Extracting CA data...
Determining server address...
Extracting ServiceAccount token...
Done generating config with limited privileges
Sending config to SLATE server...
Successfully created cluster hoople with ID cluster_G23mthSyhWm

Note: You must specify the group which will administer the cluster with --group, since you may belong to more than one group, and the organization which formally owns the cluster with --org. Your cluster is now part of the SLATE platform, but only members of your group can use it. You can verify this by listing the groups allowed access:

Suppose that you also work with the Graphene Radiometry for Unified Multi-Messenger Blockchain Leveraged Exoplanet Searches (GRUMMBLES) project, which makes extensive use of distributed computing, which wants to deploy services with SLATE. We’ll assume that they already have a group, of which you are also a member:

When universal access is granted, individual groups are not listed by slate cluster list-allowed. Granting access to groups individually or universally is mainly dependent on your institution or funding source’s security and resource sharing policies.

Deploying an Application

To run computing jobs efficiently on resources at the Hoople Campus, GRUMMBLES would like to deploy a caching HTTP proxy. To see if SLATE has a suitable application, they need to list the applications in the catalog (add the “–dev” flag to see applications in the development catalog). They might see something like this:

Opening that file with your preferred editor will show something like this:

# Instance to label use case of Frontier Squid deployment
# Generates app name as "osg-frontier-squid-[Instance]"
# Enables unique instances of Frontier Squid in one namespace
Instance: global
Service:
# Port that the service will utilize.
Port: 3128
# Controls how your service is can be accessed. Valid values are:
# - LoadBalancer - This ensures that your service has a unique, externally
# visible IP address
# - NodePort - This will give your service the IP address of the cluster node
# on which it runs. If that address is public, the service will
# be externally accessible. Using this setting allows your
# service to share an IP address with other unrelated services.
# - ClusterIP - Your service will only be accessible on the cluster's internal
# kubernetes network. Use this if you only want to connect to
# your service from other services running on the same cluster.
ExternalVisibility: NodePort
SquidConf:
# The amount of memory (in MB) that Frontier Squid may use on the machine.
# Per Frontier Squid, do not consume more than 1/8 of system memory with Frontier Squid
CacheMem: 128
# The amount of disk space (in MB) that Frontier Squid may use on the machine.
# The default is 10000 MB (10 GB), but more is advisable if the system supports it.
CacheSize: 10000
# The range of incoming IP addresses that will be allowed to use the proxy.
# Multiple ranges can be provided, each seperated by a space.
# Example: 192.168.1.1/32 192.168.2.1/32
# Use 0.0.0.0/0 for open access.
IPRange: 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16

Next, edit the file to set properties like cache sizes and allowed ranges of IP addresses you’ll allow to use the proxy. Save your changes to the file, and you’re ready to deploy the application:

It’s good form to limit instance listings by cluster and group any time you don’t need a broader view, to reduce the load on SLATE infrastructure and the amount of information printed to your terminal.

The service is running, but you still have no way to use it. SLATE has more detailed information to solve this. Note that since you can deploy application instances with the same names on different clusters, to uniquely identify an instance you must specify its full ID:

The ‘Services’ section of the listing shows that your proxy is running, and should be reachable at 96.14.44.108:3128. Only members of the group which deployed an instance (and SLATE platform administrators) can query its information this way, so your services are nominally private (although this should not be relied upon for any serious security).

Application Lifecycle

If you want to stop an application instance, to redeploy it with a new configuration or because you don’t need it anymore, deleting is also simple:

This material is based upon work supported by the National Science Foundation under Grant No. 1724821.Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.