src/docs/user/userguide/almanac.diviner

   1 @title Almanac User Guide
   2 @group userguide
   3
   4 Using Almanac to manage devices and services.
   5
   6 Overview
   7 ========
   8
   9 Almanac is a device and service inventory application. It allows you to create
  10 lists of //devices// and //services// that humans and other applications can
  11 use to keep track of what is running where.
  12
  13 Almanac is an infrastructure application that will normally be used by
  14 administrators to configure advanced Phabricator features. In most cases,
  15 normal users will very rarely interact with Almanac directly.
  16
  17 At a very high level, Almanac can be thought of as a bit like a DNS server.
  18 Callers ask it for information about services, and it responds with details
  19 about which devices host those services. However, it can respond to a broader
  20 range of queries and provide more detailed responses than DNS alone can.
  21
  22 Today, the primary use cases for Almanac are internal to Phabricator:
  23
  24   - Providing a list of build servers to Drydock so it can run build and
  25     integration tasks.
  26   - Configuring Phabricator to operate in a cluster setup.
  27
  28 Beyond internal uses, Almanac is a general-purpose service and device inventory
  29 application and can be used to configure and manage other types of service and
  30 hardware inventories, but these use cases are currently considered experimental
  31 and you should be exercise caution in pursuing them.
  32
  33
  34 Example: Drydock Build Pool
  35 ================================
  36
  37 Here's a quick example of how you might configure Almanac to solve a real-world
  38 problem. This section describes configuration at a high level to give you an
  39 introduction to Almanac concepts and a better idea of how the pieces fit
  40 together.
  41
  42 In this scenario, we want to use Drydock to run some sort of build process. To
  43 do this, Drydock needs hardware to run on. We're going to use Almanac to give
  44 Drydock a list of hosts it should use.
  45
  46 In this scenario, Almanac will work a bit like a DNS server. When we're done,
  47 Drydock will be able to query Almanac for information about a service (like
  48 `build.mycompany.com`) and get back information about which hosts are part of
  49 that service and which addresses/ports it should connect to.
  50
  51 Before getting started, we need to create a **network**. For simplicity, let's
  52 suppose everything will be connected through the public internet. If you
  53 haven't already, you'd create a "Public Internet" network first.
  54
  55 Once we have a network, we create the actual physical or virtual hosts by
  56 launching instances in EC2, or racking and powering on some servers, or already
  57 having some hardware on hand we want to use. We set the hosts up normally and
  58 connect them to the internet (or another network).
  59
  60 After the hosts exist, we add them to Almanac as **devices**, like
  61 `build001.mycompany.com`, `build002.mycompany.com`, and so on. In Almanac,
  62 devices are usually physical or virtual hosts, although you could also use it
  63 to inventory other types of devices and hardware.
  64
  65 For each **device**, we add an **interface**. This is just an address and port
  66 on a particular network. Since we're going to connect to these hosts over
  67 SSH, we'll add interfaces on the standard SSH port 22. An example configuration
  68 might look a little bit like this:
  69
  70 | Device | Network | Address | Port |
  71 |--------|---------|---------|------|
  72 | `build001.mycompany.com` | Public Internet | 58.8.9.10 | 22
  73 | `build002.mycompany.com` | Public Internet | 58.8.9.11 | 22
  74 | ... | Public Internet | ... | 22
  75
  76 Now, we create the **service**. This is what we'll tell Drydock about, and
  77 it can query for information about this service to find connected devices.
  78 Here, we'll call it `build.mycompany.com`.
  79
  80 After creating the service, add **bindings** to the interfaces we configured
  81 above. This will tell Drydock where it should actually connect to.
  82
  83 Once this is complete, we're done in Almanac and can continue configuration in
  84 Drydock, which is outside the scope of this example. Once everything is fully
  85 configured, this is how Almanac will be used by Drydock:
  86
  87   - Drydock will query information about `build.mycompany.com` from Almanac.
  88   - Drydock will get back a list of bound interfaces, among other data.
  89   - The interfaces provide information about addresses and ports that Drydock
  90     can use to connect to the actual devices.
  91
  92 You can now add and remove devices to the pool by binding them and unbinding
  93 them from the service.
  94
  95
  96 Concepts
  97 ========
  98
  99 The major concepts in Almanac are **devices**, **interfaces**, **services**,
 100 **bindings**, **networks**, and **namespaces**.
 101
 102 **Devices**: Almanac devices represent physical or virtual devices.
 103 Usually, they are hosts (like `web001.mycompany.net`), although you could
 104 use devices to keep inventory of any other kind of device or physical asset
 105 (like phones, laptops, or office chairs).
 106
 107 Each device has a name, and may have properties and interfaces.
 108
 109 **Interfaces**: Interfaces are listening address/port combinations on devices.
 110 For example, if you have a webserver host device named `web001.mycompany.net`,
 111 you might add an interface on port `80`.
 112
 113 Interfaces tell users and applications where they should connect to to access
 114 services and devices.
 115
 116 **Services**: These are named services like `build.mycompany.net` that work
 117 a bit like DNS. Humans or other applications can look up a service to find
 118 configuration information and learn which devices are hosting the service.
 119
 120 Each service has a name, and may have properties and bindings.
 121
 122 **Bindings**: Bindings are connections between services and interfaces. They
 123 tell callers which devices host a named service.
 124
 125 **Networks**: Networks allow Almanac to distinguish between addresses on
 126 different networks, like VPNs vs the public internet.
 127
 128 If you have hosts in different VPNs or on private networks, you might have
 129 multiple devices which share the same IP address (like `10.0.0.3`). Networks
 130 allow Almanac to distinguish between devices with the same address on different
 131 sections of the network.
 132
 133 **Namespaces**: Namespaces let you control who is permitted to create devices
 134 and services with particular names. For example, the namespace `mycompany.com`
 135 controls who can create services with names like `a.mycompany.com` and
 136 `b.mycompany.com`.
 137
 138
 139 Namespaces
 140 ==========
 141
 142 Almanac namespaces allow you to control who can create services and devices
 143 with certain names.
 144
 145 If you keep a list of cattle as devices with names like
 146 `cow001.herd.myranch.moo`, `cow002.herd.myranch.moo`, you might have some
 147 applications which query for all devices in `*.herd.myranch.moo`, and thus
 148 want to limit who can create devices there in order to prevent mistakes.
 149
 150 If a namespace like `herd.myranch.moo` exists, users must have permission to
 151 edit the namespace in order to create new services, devices, or namespaces
 152 within it. For example, a user can not create `cow003.herd.myranch.moo` if
 153 they do not have edit permission on the `herd.myranch.moo` namespace.
 154
 155 When you try to create a `cow003.herd.myranch.moo` service (or rename an
 156 existing service to have that name), Almanac looks for these namespaces, then
 157 checks the policy of the first one it finds:
 158
 159 | Namespace |
 160 |----|-----
 161 | `cow003.herd.ranch.moo` | //"Nearest" namespace, considered first.//
 162 | `herd.ranch.moo` | |
 163 | `ranch.moo` | |
 164 | `moo` | //"Farthest" namespace, considered last.//
 165
 166 Note that namespaces treat names as lists of domain parts, not as strict
 167 substrings, so the namespace `herd.myranch.moo` does not prevent
 168 someone from creating `goatherd.myranch.moo` or `goat001.goatherd.myranch.moo`.
 169 The name `goatherd.myranch.moo` is not part of the `herd.myranch.moo` namespace
 170 because the initial subdomain differs.
 171
 172 If a name belongs to multiple namespaces, the policy of the nearest namespace
 173 is controlling. For example, if `myranch.moo` has a very restrictive edit
 174 policy but `shed.myranch.moo` has a more open one, users can create devices and
 175 services like `rake.shed.myranch.moo` as long as they can pass the policy check
 176 for `shed.myranch.moo`, even if they do not have permission under the policy
 177 for `myranch.moo`.
 178
 179 Users can edit services and devices within a namespace if they have edit
 180 permission on the service or device itself, as long as they don't try to rename
 181 the service or device to move it into a namespace they don't have permission
 182 to access.