sliderule-provisioner

sliderule-provisioner is a command line tool for managing the lifecycle of SlideRule clusters. It can be used to deploy a stand-alone cluster or dedicated user capacity, extend or destroy a running cluster, check on its status and events, run the test runner against a branch, and obtain temporary AWS credentials for accessing SlideRule’s S3 data.

Quick Start¶

# Deploy user capacity with the typical settings
sliderule-provisioner deploy --node_capacity 5 --ttl 60 --user_service

# Check on it
sliderule-provisioner status --user_service

# Give it another hour
sliderule-provisioner extend --ttl 60 --user_service

# Tear it down when finished
sliderule-provisioner destroy --user_service

Usage¶

sliderule-provisioner <command> [options]

Command	Purpose
`deploy`	Deploy a cluster (stand-alone or as user capacity)
`extend`	Extend the time-to-live of a cluster
`destroy`	Destroy a cluster
`status`	Report the status of a cluster
`events`	List the stack events associated with a cluster
`report`	Report the metadata of all active clusters
`test`	Execute the test runner
`info`	Display information about the provisioner
`s3access`	Output shell commands that set temporary AWS credentials
`authenticate`	Force re-authentication of your user account

Run sliderule-provisioner --help for a list of commands, or sliderule-provisioner <command> --help for the options of a specific command.

Common Options¶

The following options are accepted by every command. They are attached to each subcommand, so they must appear after the command name:

Option	Default	Description
`--domain <domain>`	`slideruleearth.io`	Domain of the SlideRule service to connect to.
`--cluster <cluster>`	`developers`	Name of the cluster to operate on.
`--user_service`	False	Operate on dedicated user capacity rather than a stand-alone cluster.
`--verbose`	False	Turn on verbose log messages. Also causes errors to be raised with a full traceback (see Error Handling).
`--timezone <tz>`	`America/New_York`	IANA time zone name (e.g. `UTC`, `America/Los_Angeles`) used when displaying times in `status` and `report`.

Command Reference¶

`deploy`¶

sliderule-provisioner deploy [options] [common options]

Deploys a cluster, either stand-alone or as user capacity (when --user_service is supplied). The cluster remains running until its time-to-live expires or it is destroyed; use extend to keep it longer.

Option	Default	Description
`--is_public <true\|false>`	`false`	Whether the cluster is publicly accessible. Must be the string `true` to make the cluster public; any other value is treated as `false`.
`--node_capacity <int>`	`1`	Number of nodes to deploy.
`--ttl <int>`	`60`	Time-to-live of the cluster. The default of 60 corresponds to one hour.
`--version <str>`	`unstable`	Version of SlideRule to deploy.

Examples:

# deploy a private, single-node cluster running the unstable version for one hour
sliderule-provisioner deploy

# deploy a 4-node cluster named "mycluster" for two hours
sliderule-provisioner deploy --cluster mycluster --node_capacity 4 --ttl 120

# deploy dedicated user capacity
sliderule-provisioner deploy --user_service

# deploy a public cluster running a specific release
sliderule-provisioner deploy --is_public true --version v4.5.0

`extend`¶

sliderule-provisioner extend [--ttl <int>] [common options]

Extends the time-to-live of a running cluster.

Option	Default	Description
`--ttl <int>`	`60`	Amount of time to extend the cluster by. The default of 60 corresponds to one hour.

Examples:

# extend the "developers" cluster by the default amount
sliderule-provisioner extend

# extend a specific cluster
sliderule-provisioner extend --cluster mycluster --ttl 120

`destroy`¶

sliderule-provisioner destroy [common options]

Destroys a cluster.

Examples:

# destroy the "developers" cluster
sliderule-provisioner destroy

# destroy the user's dedicated capacity
sliderule-provisioner destroy --user_service

`status`¶

sliderule-provisioner status [common options]

Reports the status of a cluster. The output is a concise summary; fields that have no value are omitted, and times are displayed in the time zone given by --timezone.

Field	Description
`error`, `error_description`	Present only if the request failed.
`stack_name`	Name of the cluster’s deployment stack.
`stack_status`	Current status of the deployment stack.
`creation_time`	When the cluster was created.
`auto_shutdown`	When the cluster will shut down automatically (see `extend`).
`current_nodes`	Number of nodes currently running.
`version`	Version of SlideRule running on the cluster.
`is_public`	Whether the cluster is publicly accessible.
`node_capacity`	Number of nodes the cluster was deployed with.
`users`	For user capacity, the users of the service and their individual `auto_shutdown` times.

Examples:

# status of the "developers" cluster, with times shown in UTC
sliderule-provisioner status --timezone UTC

# status of the user's dedicated capacity
sliderule-provisioner status --user_service

`events`¶

sliderule-provisioner events [common options]

Lists the stack events associated with a cluster. This is useful for following the progress of a deployment or diagnosing why one failed.

Examples:

sliderule-provisioner events --cluster mycluster

`report`¶

sliderule-provisioner report [--kind <str>] [common options]

Reports the metadata of all active clusters. Each cluster is displayed using the same concise format as status, keyed by cluster name.

Option	Default	Description
`--kind <str>`	`cluster`	The kind of report: a `cluster` report or a `test` report.

Examples:

# report on all active clusters
sliderule-provisioner report

# report with times shown in Pacific time
sliderule-provisioner report --timezone America/Los_Angeles

`test`¶

sliderule-provisioner test [--branch <str>] [common options]

Executes the test runner against a branch of the SlideRule source.

Option	Default	Description
`--branch <str>`	`main`	Branch to test.

Examples:

# run the tests on the main branch
sliderule-provisioner test

# run the tests on a feature branch
sliderule-provisioner test --branch my-feature

`info`¶

sliderule-provisioner info [common options]

Displays information about the provisioner itself.

Examples:

sliderule-provisioner info

`s3access`¶

sliderule-provisioner s3access [common options]

Obtains temporary AWS credentials and prints them as shell export commands. Rather than reading the output, use eval to set the credentials in your current shell environment:

eval "$(sliderule-provisioner s3access)"

The following environment variables are set:

Variable	Description
`AWS_ACCESS_KEY_ID`	Access key for the temporary credentials.
`AWS_SECRET_ACCESS_KEY`	Secret key for the temporary credentials.
`AWS_SESSION_TOKEN`	Session token for the temporary credentials.
`AWS_CREDENTIAL_EXPIRATION`	When the credentials expire. Run the command again to obtain new ones.

Examples:

# set credentials, then use the AWS CLI
eval "$(sliderule-provisioner s3access)"
aws s3 ls s3://<bucket>/

# just look at what would be set
sliderule-provisioner s3access

`authenticate`¶

sliderule-provisioner authenticate [common options]

Forces a fresh login of your user account, even if you already have valid credentials. Use it when switching accounts or if other commands report authentication errors.

Examples:

sliderule-provisioner authenticate

Additional Topics¶

Output Format¶

Results are printed to standard output as indented JSON. Commands that have nothing to return (for example s3access, which prints shell commands instead) print no JSON.

status and report present a concise summary of the cluster metadata, omitting empty fields and converting times to the --timezone you supply.

Error Handling¶

By default, errors are caught and reported as a single line:

Unhandled error: <message>

Pass --verbose to raise the full exception and traceback instead, which is the best first step when troubleshooting.

Typical Private Cluster Workflow¶

# 1. Deploy
sliderule-provisioner deploy --cluster mycluster --node_capacity 2 --ttl 120

# 2. Watch it come up
sliderule-provisioner events --cluster mycluster
sliderule-provisioner status --cluster mycluster

# 3. Use it (e.g. with sliderule-cluster)
sliderule-cluster whoami --cluster mycluster

# 4. Extend if you need more time
sliderule-provisioner extend --cluster mycluster --ttl 60

# 5. Destroy when finished
sliderule-provisioner destroy --cluster mycluster

sliderule-provisioner

Quick Start¶

Usage¶

Common Options¶

Command Reference¶

deploy¶

extend¶

destroy¶

status¶

events¶

report¶

test¶

info¶

s3access¶

authenticate¶

Additional Topics¶

Output Format¶

Error Handling¶

Typical Private Cluster Workflow¶

`deploy`¶

`extend`¶

`destroy`¶

`status`¶

`events`¶

`report`¶

`test`¶

`info`¶

`s3access`¶

`authenticate`¶