20862: Merge branch 'main' into 20862-google-api-client
[arvados.git] / doc / admin / cloudtest.html.textile.liquid
1 ---
2 layout: default
3 navsection: admin
4 title: Testing cloud configuration
5 ...
6
7 {% comment %}
8 Copyright (C) The Arvados Authors. All rights reserved.
9
10 SPDX-License-Identifier: CC-BY-SA-3.0
11 {% endcomment %}
12
13 The @arvados-server@ package includes a @cloudtest@ tool that checks compatibility between your Arvados configuration, your cloud driver, your cloud provider's API, your cloud provider's VM instances, and the worker image you use with the "cloud dispatcher":../install/crunch2-cloud/install-dispatch-cloud.html.
14
15 @arvados-server cloudtest@ performs the following steps:
16 # Create a new instance
17 # Wait for it to finish booting
18 # Run a shell command on the new instance (optional)
19 # Pause while you log in to the new instance and do other tests yourself (optional)
20 # Shut down the instance
21
22 This is an easy way to expose problems like these:
23 * Configured cloud credentials don't work
24 * Configured image types don't work
25 * Configured driver is not compatible with your cloud API/region
26 * Newly created instances are not usable due to a network problem or misconfiguration
27 * Newly created instances do not accept the configured SSH private key
28 * Selected machine image does not boot properly
29 * Selected machine image is incompatible with some instance types
30 * Driver has bugs
31
32 h2. Typical uses
33
34 Before bringing up the @arvados-dispatch-cloud@ service for the first time, we recommend running @cloudtest@ to check your configuration:
35
36 <notextile><pre>
37 $ <span class="userinput">arvados-server cloudtest -command "crunch-run --list"</span>
38 </pre></notextile>
39
40 Before updating your configuration to use a new VM image, we recommend running @cloudtest@ with the new image:
41
42 <notextile><pre>
43 $ <span class="userinput">arvados-server cloudtest -image-id <b>new_image_id</b> -command "crunch-run --list"</span>
44 </pre></notextile>
45
46 After adding an instance type to your configuration, we recommend running @cloudtest@ with the new instance type:
47
48 <notextile><pre>
49 $ <span class="userinput">arvados-server cloudtest -instance-type <b>new_instance_type_name</b></span>
50 </pre></notextile>
51
52 For a full list of options, use the @-help@ flag:
53
54 <notextile><pre>
55 $ <span class="userinput">arvados-server cloudtest -help</span>
56 Usage:
57   -command string
58         Run an interactive shell command on the test instance when it boots
59   -config file
60         Site configuration file (default "/etc/arvados/config.yml")
61   -destroy-existing
62         Destroy any existing instances tagged with our InstanceSetID, instead of erroring out
63   -image-id string
64         Image ID to use when creating the test instance (if empty, use cluster config)
65   -instance-set-id value
66         InstanceSetID tag value to use on the test instance (default "cloudtest-user@hostname.example")
67   -instance-type string
68         Instance type to create (if empty, use cheapest type in config)
69   -pause-before-destroy
70         Prompt and wait before destroying the test instance
71 </pre></notextile>