src/docs/user/userguide/drydock_hosts.diviner

   1 @title Drydock Blueprints: Hosts
   2 @group userguide
   3
   4 Guide to configuring Drydock host blueprints.
   5
   6
   7 Overview
   8 ========
   9
  10 IMPORTANT: Drydock is not a mature application and may be difficult to
  11 configure and use for now.
  12
  13 To give Drydock access to machines so it can perform work, you'll configure
  14 **host blueprints**. These blueprints tell Drydock where to find machines (or
  15 how to build machines) and how to connect to them.
  16
  17 Once Drydock has access to hosts it can use them to build more interesting and
  18 complex types of resources, like repository working copies.
  19
  20 Drydock currently supports these kinds of host blueprints:
  21
  22   - **Almanac Hosts**: Gives Drydock access to a predefined list of hosts.
  23
  24 Drydock may support additional blueprints in the future.
  25
  26
  27 Security
  28 ========
  29
  30 Drydock can be used to run semi-trusted and untrusted code, and you may want
  31 to isolate specific processes or classes of processes from one another. See
  32 @{article:Drydock User Guide: Security} for discussion of security
  33 concerns and guidance on how to make isolation tradeoffs.
  34
  35
  36 General Considerations
  37 ======================
  38
  39 **You must install software on hosts.** Drydock does not currently handle
  40 installing software on hosts. You'll need to make sure any hosts are configured
  41 properly with any software you need, and have tools like `git`, `hg` or `svn`
  42 that may be required to interact with working copies.
  43
  44 You do **not** need to install PHP, arcanist, or Phabricator on the
  45 hosts unless you are specifically running `arc` commands.
  46
  47 **You must configure authentication.** Drydock also does not handle credentials
  48 for VCS operations. If you're interacting with repositories hosted on
  49 Phabricator, the simplest way to set this up is something like this:
  50
  51   - Create a new bot user in Phabricator.
  52   - In {nav Settings > SSH Public Keys}, add a public key or generate a
  53     keypair.
  54   - Put the private key on your build hosts as `~/.ssh/id_rsa` for whatever
  55     user you're connecting with.
  56
  57 This will let processes on the host access Phabricator as the bot user, and
  58 use the bot user's permissions to pull and push changes.
  59
  60 If you're using hosted repositories from an external service, you can follow
  61 similar steps for that service.
  62
  63 Note that any processes running under the given user account will have access
  64 to the private key, so you should give the bot the smallest acceptable level of
  65 permissions if you're running semi-trusted or untrusted code like unit tests.
  66
  67 **You must create a `/var/drydock` directory.** This is hard-coded in Drydock
  68 for now, so you need to create it on the hosts. This can be a symlink to
  69 a different location if you prefer.
  70
  71
  72 Almanac Hosts
  73 =============
  74
  75 The **Almanac Hosts** blueprint type gives Drydock access to a predefined list
  76 of hosts which you configure in the Almanac application. This is the simplest
  77 type of blueprint to set up.
  78
  79 For more information about Almanac, see @{article:Almanac User Guide}.
  80
  81 For example, suppose you have `build001.mycompany.com` and
  82 `build002.mycompany.com`, and want to configure Drydock to be able to use these
  83 hosts. To do this:
  84
  85 **Create Almanac Devices**: Create a device record in Almanac for each your
  86 hosts.
  87
  88 {nav Almanac > Devices > Create Device}
  89
  90 Enter the device names (like `build001.mycompany.com`). After creating the
  91 devices, use {nav Add Interface} to configure the ports and IP addresses that
  92 Drydock should connect to over SSH (normally, this is port `22`).
  93
  94 **Create an Almanac Service**: In the Almanac application, create a new service
  95 to define the pool of devices you want to use.
  96
  97 {nav Almanac > Services > Create Service}
  98
  99 Choose the service type **Drydock: Resource Pool**. This will allow Drydock
 100 to use the devices that are bound to the service.
 101
 102 Now, use {nav Add Binding} to bind all of the devices to the service.
 103
 104 You can add more hosts to the pool later by binding additional devices, and
 105 Drydock will automatically start using them. Likewise, you can remove bindings
 106 to take hosts out of service.
 107
 108 **Create a Drydock Blueprint**: Now, create a new blueprint in Drydock.
 109
 110 {nav Drydock > Blueprints > New Blueprint}
 111
 112 Choose the **Almanac Hosts** blueprint type.
 113
 114 In **Almanac Services**, select the service you previously created. For
 115 **Credentials**, select an SSH private key you want Drydock to use to connect
 116 to the hosts.
 117
 118 Drydock should now be able to build resources from these hosts.
 119
 120
 121 Next Steps
 122 ==========
 123
 124 Continue by:
 125
 126   - returning to @{article:Drydock Blueprints}.