You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/getting-started/quickstart.rst
+59-43
Original file line number
Diff line number
Diff line change
@@ -20,64 +20,64 @@ Complete the :ref:`installation instructions <installation>` before continuing w
20
20
21
21
Provisioning your first cluster
22
22
--------------------------------
23
-
We'll start by launching our first cluster on Sky using an interactive node.
24
-
Interactive nodes are standalone machines that can be used like any other VM instance,
25
-
but are easy to configure without any additional setup.
23
+
We'll start by launching our first cluster on Sky using an :ref:`interactive
24
+
node <interactive-nodes>`. Interactive nodes are easy-to-spin-up VMs that allow
25
+
for fast development and interactive debugging.
26
26
27
27
Let's provision an instance with a single K80 GPU.
28
28
29
-
.. code-block:: bash
29
+
.. code-block:: console
30
30
31
-
# Provisions/reuses an interactive node with a single K80 GPU.
32
-
sky gpunode -c mygpu --gpus K80
31
+
$ # Provisions/reuses an interactive node with a single K80 GPU.
32
+
$ sky gpunode -c mygpu --gpus K80
33
33
34
-
Provisioning takes a few minutes, after which you're automatically logged in:
34
+
Provisioning should take a few minutes, after which you're automatically logged in:
35
35
36
-
.. code-block:: bash
36
+
.. code-block:: console
37
37
38
38
Last login: Wed Feb 23 22:35:47 2022 from 136.152.143.101
39
39
40
40
ubuntu@ip-172-31-86-108:~$ gpustat
41
+
41
42
ip-172-31-86-108 Wed Feb 23 22:42:43 2022 450.142.00
42
43
[0] Tesla K80 | 31°C, 0 % | 0 / 11441 MB |
43
44
44
-
Press :code:`Ctrl-D` to log out. On your machine, query:code:`sky status` for all provisioned clusters:
45
+
Press :code:`Ctrl-D` to log out. On your machine, use:code:`sky status` to query all provisioned clusters:
45
46
46
-
.. code-block:: bash
47
+
.. code-block:: console
47
48
48
-
sky status
49
+
$ sky status
49
50
50
51
NAME LAUNCHED RESOURCES COMMAND STATUS
51
52
mygpu a few secs ago 1x Azure(Standard_NC6_Promo) sky gpunode -c mygpu --gpus K80 UP
52
53
53
54
To log back in, simply type :code:`ssh mygpu`.
54
55
55
-
After you are done, run :code:`sky down mygpu` to terminate the cluster. Find more commands
56
-
on managing the lifecycle of clusters :ref:`here <interactive-nodes>`.
57
-
58
-
Sky can also provision interactive CPU and TPU nodes with :code:`cpunode` and :code:`tpunode`.
59
-
Please see our :ref:`CLI reference <cli>` for all configuration options. For more information on
60
-
using and managing interactive nodes, check out our :ref:`reference documentation <interactive-nodes>`.
56
+
After you are done, run :code:`sky down mygpu` to terminate the cluster. See
57
+
:ref:`here <interactive-nodes>` for other types of interactive nodes and
58
+
commands that manage the lifecycle of clusters.
61
59
62
60
63
61
Hello, Sky!
64
62
-----------
65
-
You can also define tasks to be executed by Sky. We'll define our very first task
66
-
to be a simple hello world program.
67
-
68
-
We can specify the following task attributes with a YAML file:
63
+
Next, let's define our very first task, a simple hello world program, to be
64
+
executed by Sky. We can specify the following task attributes with a YAML file:
69
65
70
-
- :code:`resources` (optional): what cloud resources the task must be run on (e.g., accelerators, instance type, etc.)
71
-
- :code:`workdir` (optional): specifies working directory containing project code that is synced with the provisioned instance(s)
66
+
- :code:`resources` (optional): cloud resources the task must be run on (e.g., accelerators, instance type, etc.)
67
+
- :code:`workdir` (optional): the working directory containing project code that will be synced to the provisioned instance(s)
72
68
- :code:`setup` (optional): commands that must be run before the task is executed
73
-
- :code:`run` (optional): specifies the commands that must be run as the actual ask
69
+
- :code:`run` (optional): commands that run the actual task
74
70
75
71
.. note::
76
72
77
-
For large, multi-gigabyte workdirs (e.g. large datasets in your working directory), uploading may take time as the files are synced to the remote VM with :code:`rsync`. If you have certain files in your workdir that you would like to have excluded from upload, consider including them in your `.gitignore` file. For large datasets and files, consider using :ref:`Sky Storage <sky-storage>` to speed up transfers.
73
+
For large, multi-gigabyte workdirs (e.g., large datasets in your working
74
+
directory), uploading may be slow the files are synced to the remote VM(s)
75
+
with :code:`rsync`. To exclude large files in your workdir from being uploaded,
76
+
add them to your :code:`.gitignore` file. To upload large datasets and files, consider using :ref:`Sky
77
+
Storage <sky-storage>` to speed up transfers.
78
78
79
79
Below is a minimal task YAML that prints "hello sky!" and shows installed Conda environments,
80
-
requiring an NVIDIA Tesla K80 GPU on AWS. See more example YAML files in the `repo<https://github.com/sky-proj/sky/tree/master/examples>`_, with a fully-complete example documented:ref:`here <yaml-spec>`.
80
+
requiring an NVIDIA Tesla K80 GPU on AWS. See more example YAML files in the `repository<https://github.com/sky-proj/sky/tree/master/examples>`_ and a fully-complete YAML example:ref:`here <yaml-spec>`.
81
81
82
82
.. code-block:: yaml
83
83
@@ -86,8 +86,8 @@ requiring an NVIDIA Tesla K80 GPU on AWS. See more example YAML files in the `re
86
86
resources:
87
87
# Optional; if left out, pick from the available clouds.
88
88
cloud: aws
89
-
90
-
accelerators: V100:1# 1x NVIDIA V100 GPU
89
+
# 1x NVIDIA V100 GPU
90
+
accelerators: V100:1
91
91
92
92
# Working directory (optional) containing the project codebase.
93
93
# This directory will be synced to ~/sky_workdir on the provisioned cluster.
@@ -102,11 +102,13 @@ requiring an NVIDIA Tesla K80 GPU on AWS. See more example YAML files in the `re
102
102
echo "hello sky!"
103
103
conda env list
104
104
105
-
Sky handles selecting an appropriate VM based on user-specified resource
106
-
constraints, launching the cluster on an appropriate cloud provider, and
107
-
executing the task.
108
105
109
-
To launch a task based on our above YAML spec, we can use :code:`sky launch`.
106
+
**To launch a task** based on a YAML spec, use :code:`sky launch`. This command
107
+
performs many heavy-lifting: (1) selects an appropriate cloud and VM based on
108
+
the specified resource constraints, (2) provisions (or reuses) a cluster on that
109
+
cloud,
110
+
(3) uploads the :code:`workdir`, (4) executes the :code:`setup` commands,
111
+
and (5) executes the :code:`run` commands.
110
112
111
113
.. code-block:: console
112
114
@@ -118,7 +120,19 @@ exists, a new cluster with that name will be provisioned. If no cluster name is
118
120
provided, (e.g., :code:`sky launch hello_sky.yaml`), a cluster name will be
119
121
autogenerated.
120
122
121
-
We can view our existing clusters by running :code:`sky status`:
123
+
**To execute a task on an existing cluster**, use :code:`sky exec`:
124
+
125
+
.. code-block:: console
126
+
127
+
$ sky exec mycluster hello_sky.yaml
128
+
129
+
This command is more lightweight: it simply executes the task's :code:`run`
130
+
commands. :code:`workdir` is also synced every time :code:`sky exec` is run, so
131
+
that the task may use updated code. Bash commands are also supported, such as
132
+
:code:`sky exec mycluster htop`.
133
+
134
+
135
+
**To view existing clusters**, use :code:`sky status`:
122
136
123
137
.. code-block:: console
124
138
@@ -130,25 +144,27 @@ This may show multiple clusters, if you have created several:
130
144
131
145
NAME LAUNCHED RESOURCES COMMAND STATUS
132
146
gcp 1 day ago 1x GCP(n1-highmem-8) sky cpunode -c gcp --cloud gcp STOPPED
133
-
mycluster 12 mins ago 1x AWS(p2.xlarge) sky launch -c mycluster hello_sky.yaml UP
147
+
mycluster 12 mins ago 1x AWS(p3.2xlarge) sky launch -c mycluster hello_sky.yaml UP
134
148
135
-
If you would like to log into the a cluster, Sky provides convenient SSH access via :code:`ssh <cluster_name>`:
149
+
**To log into the a cluster**, Sky provides convenient SSH access via :code:`ssh <cluster_name>`:
136
150
137
151
.. code-block:: console
138
152
139
153
$ ssh mycluster
140
154
141
-
If you would like to transfer files to and from the cluster, *rsync* or *scp* can be used:
155
+
**To transfer files to and from the cluster** after a task's execution, use :code:`rsync` (or :code:`scp`) :
142
156
143
157
.. code-block:: console
144
158
145
-
$ rsync -Pavz /local/path/source mycluster:/remote/dest # copy files to remote VM
146
-
$ rsync -Pavz mycluster:/remote/source /local/dest # copy files from remote VM
159
+
$ rsync -Pavz /local/path/source mycluster:/remote/dest # copy to remote VM
160
+
$ rsync -Pavz mycluster:/remote/source /local/dest # copy from remote VM
147
161
148
-
After you are done, run :code:`sky down mycluster` to terminate the cluster. Find more details
149
-
on managing the lifecycle of your cluster :ref:`here <interactive-nodes>`.
162
+
**To terminate (or stop) the cluster**, run :code:`sky down mycluster` (for
163
+
stopping, run :code:`sky stop mycluster`). Find more commands that manage the
164
+
lifecycle of clusters :ref:`here <interactive-nodes>`.
150
165
151
166
Sky is more than a tool for easily provisioning and managing multiple clusters
152
-
on different clouds. It also comes with features for :ref:`storing and moving data <sky-storage>`,
153
-
:ref:`queueing multiple jobs <job-queue>`, :ref:`iterative development <iter-dev>`, and :ref:`interactive nodes <interactive-nodes>` for
154
-
debugging.
167
+
on different clouds. It also comes with features for :ref:`storing and moving
168
+
data <sky-storage>`, :ref:`queueing multiple jobs <job-queue>`, :ref:`iterative
169
+
development <iter-dev>`, and :ref:`interactive nodes <interactive-nodes>`.
170
+
Refer to the :ref:`CLI Reference <cli>` for details of the :code:`sky` CLI.
0 commit comments