The SLATE Client is a command line interface (CLI) intended to give a convenient way for users of SLATE, primarily edge administrators and application administrators, to work with the platform. Copies of the client executable itself and the credentials necessary for it to carry out actions on your behalf can be obtained from the web portal.
Help information on using the client can be obtained by running it with the
$ slate-client --help SLATE command line interface Usage: ./slate-client [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: vo Manage SLATE VOs cluster Manage SLATE clusters app View and install SLATE applications instance Manage SLATE application instances secret Manage SLATE secrets
--help option can also be used together with any of the client’s subcommands to learn about its particular options and arguments. Additionally, a complete manual of all commands supported by the client is maintained along with its source code at https://github.com/slateci/slate-remote-client.
The simplest uses of the client are to list objects which exist on the SLATE platform. For example, you can list the edge clusters currently participating in the platform:
$ ./slate-client cluster list Name ID Owned By utah-coreos Cluster_3249cb47-7318-4fd0-a61b-0cf99c1aceb8 slate-dev umich Cluster_2426348a-e6cc-4282-a142-4ab60443df42 slate-dev uchicago Cluster_98b60d59-b873-4014-8f1d-f9c259c116b3 slate-dev
In this (abbreviated) output, three edge clusters are listed. Each cluster has name associated with it for convenience, an automatically generated unique identifier, and an owning Virtual Organization (VO) which administers it (in this case 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. VOs and clusters have names which are globally unique as well, though, so when specifying a VO or cluster you can always use the name instead of the ID.
To do very much on the SLATE platform you must belong to a VO, as VOs are the foundation of SLATE’s permissions model. You can either join a VO by asking a person who is already a member to add you, or you can create a new VO with the command
slate-client vo create. Note that newly created VOs do not generally have access to any resources (edge clusters), but they can add resources of their own.
Let’s suppose for the moment that you are 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 can begin by creating a VO:
$ slate-client vo create usnd-hoople Successfully created VO usnd-hoople with ID VO_70dc4426-1f92-4b44-932b-7c4678c30a05
As the creator of the VO, you are automatically a member. You can add other users to the VO through the web portal.
slate-client cluster create command can register your Kubernetes cluster with the SLATE platform. Its behavior is currently rather simplistic: When run it will collect your current kubectl context and send it to the SLATE API server to be used when SLATE accesses your cluster. So, if you want to limit how SLATE accesses your cluster you should first create a suitable
ClusterRole, user account, and
ClusterRoleBinding, switch to a context corresponding to the account, and then run the registration command. Assuming that any preparation is done, you can add your cluster:
$ slate-client cluster create --vo usnd-hoople hoople Successfully created cluster hoople with ID Cluster_44db0317-601a-4d73-9392-4bfddf5cb4a2
Note that you must specify the VO which will own the cluster because you as a user can potentially belong to more than one VO. At this point, your cluster is part of the SLATE platform, but only members of your VO can use it. You can verify this by listing the VOs allowed access:
$ slate-client cluster list-allowed hoople Name ID usnd-hoople VO_70dc4426-1f92-4b44-932b-7c4678c30a05
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, and would like to deploy services with SLATE. We’ll assume that they already have a VO, of which you are also a member:
$ slate-client vo list Name ID grummbles VO_7855a495-cefd-420d-85e3-2a883fed2e44 usnd-hoople VO_70dc4426-1f92-4b44-932b-7c4678c30a05
You can easily grant the GRUMMBLES project access to use the new edge cluster:
$ slate-client cluster allow-vo hoople grummbles Successfully granted VO grummbles access to cluster hoople
In order to run computing jobs efficiently on resources at the Hoople Campus, GRUMMBLES would like to deploy a caching HTTP proxy. To see whether SLATE has an application which suits your needs, you can list the applications in the catalog. You might see something like the following:
$ slate-client app list --dev Name App Version Chart Version Description jupyterhub v0.8.1 v0.7-dev Multi-user Jupyter installation osg-frontier-squid squid-3 0.2.0 Open Science Grid's Frontier Squid application osiris-unis 1.0 0.1.0 Unified Network Information Service (UNIS) perfsonar 1.0 0.1.0 perfSONAR is a network measurement toolkit
--dev flag is needed as only the incubator catalog contains applications.)
osg-frontier-squid is such a proxy. You could just install it with default settings, but in many case you will want to use customized settings. That can be done by first fetching the default configuration into a local file:
$ slate-client app get-conf --dev osg-frontier-squid > grummbles-squid-hoople.yaml
Opening that file with you preferred editor, you should find that it contains something like the following:
# 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 whether the service is accessible from outside of the cluster. # Must be true/false ExternallyVisible: true 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: 0.0.0.0/0
At this point you should edit the file to set properties like the cache sizes and the allowed ranges of IP addresses which you will allow to use the proxy. With your changes save to the file, you are ready to deploy the application:
$ slate-client app install --dev osg-frontier-squid --vo grummbles --cluster hoople --conf grummbles-squid-hoople.yaml Successfully installed application osg-frontier-squid as instance grummbles-osg-frontier-squid-global with ID Instance_d78f3751-4db8-410a-b97c-3d1263c0e344
This message indicates that your application instance has been launched on the Kubernetes cluster. You can double check by listing running instances:
$ slate-client instance list --vo grummbles --cluster hoople Name Started VO Cluster ID grummbles-osg-frontier-squid-global 2018-Aug-23 grummbles hoople Instance_d78f3751-4db8-410a- 21:45:07 UTC b97c-3d1263c0e344
It is good form to limit instance listings by cluster and VO any time you don’t need a broader view, both to reduce load on the SLATE infrastructure and to reduce the amount of information printed to your terminal.
At this point the service should be running, but you have no way to use it. SLATE can provide you with 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:
$ slate-client instance info Instance_d78f3751-4db8-410a-b97c-3d1263c0e344 Name Started VO Cluster ID grummbles-osg-frontier-squid-global 2018-Aug-23 grummbles hoople Instance_d78f3751-4db8-410a-b97c- 21:45:07 UTC 3d1263c0e344 Services: Name Cluster IP External IP Ports osg-frontier-squid-global 10.104.122.170 198.51.100.62 3128:30402/TCP Configuration: Instance: global Service: Port: 3128 ExternallyVisible: true SquidConf: CacheMem: 1024 CacheSize: 20000 IPRange: 192.168.1.1/32
The ‘Services’ section of the listing shows that your proxy is now running, and should (hypothetically) be reachable at 184.108.40.206:3128. Only members of the VO 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).
If you want to stop an application instance, either because you plan to redeploy it with a new configuration or because you simply don’t need it anymore, deleting is also simple:
$ slate-client instance delete Instance_d78f3751-4db8-410a-b97c-3d1263c0e344 Successfully deleted instance Instance_d78f3751-4db8-410a-b97c-3d1263c0e344