From 809646c8d2e962bea958fcd7e2b2a70034e947cf Mon Sep 17 00:00:00 2001 From: epriestley Date: Fri, 4 Mar 2016 16:33:49 -0800 Subject: [PATCH] Unprototype Almanac Summary: Fixes T10449. Almanac doesn't do a whole lot for the average user, but is in good shape technically and works well, and exposing it in the cluster won't let installs destroy themselves now. Test Plan: Re-read documentation; grepped for `TODO` (there are a couple, but reasonable to push off); browsed around all the UI things (new two-column looks great), called API methods. Reviewers: chad Reviewed By: chad Maniphest Tasks: T10449 Differential Revision: https://secure.phabricator.com/D15400 --- .../PhabricatorAlmanacApplication.php | 4 ---- src/docs/user/userguide/almanac.diviner | 23 +++++++++++-------- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/src/applications/almanac/application/PhabricatorAlmanacApplication.php b/src/applications/almanac/application/PhabricatorAlmanacApplication.php index 2a9ef848ab..76caa3a06b 100644 --- a/src/applications/almanac/application/PhabricatorAlmanacApplication.php +++ b/src/applications/almanac/application/PhabricatorAlmanacApplication.php @@ -35,10 +35,6 @@ final class PhabricatorAlmanacApplication extends PhabricatorApplication { ); } - public function isPrototype() { - return true; - } - public function getRoutes() { return array( '/almanac/' => array( diff --git a/src/docs/user/userguide/almanac.diviner b/src/docs/user/userguide/almanac.diviner index 5a820c6ae2..b7c30cf77a 100644 --- a/src/docs/user/userguide/almanac.diviner +++ b/src/docs/user/userguide/almanac.diviner @@ -6,21 +6,24 @@ Using Almanac to manage devices and services. Overview ======== -IMPORTANT: Almanac is a prototype application. See -@{article:User Guide: Prototype Applications}. - Almanac is a device and service inventory application. It allows you to create lists of //devices// and //services// that humans and other applications can use to keep track of what is running where. +Almanac is an infrastructure application that will normally be used by +administrators to configure advanced Phabricator features. In most cases, +normal users will very rarely interact with Almanac directly. + At a very high level, Almanac can be thought of as a bit like a DNS server. Callers ask it for information about services, and it responds with details about which devices host those services. However, it can respond to a broader range of queries and provide more detailed responses than DNS alone can. -Today, the primary use cases for Almanac involve configuring Phabricator -itself: Almanac is used to configure Phabricator to operate in a cluster setup, -and to expose hardware to Drydock so it can run build and integration tasks. +Today, the primary use cases for Almanac are internal to Phabricator: + + - Providing a list of build servers to Drydock so it can run build and + integration tasks. + - Configuring Phabricator to operate in a cluster setup. Beyond internal uses, Almanac is a general-purpose service and device inventory application and can be used to configure and manage other types of service and @@ -37,13 +40,13 @@ introduction to Almanac concepts and a better idea of how the pieces fit together. In this scenario, we want to use Drydock to run some sort of build process. To -do this, Drydock needs hardware to run on. We're going to use Almanac to tell -Drydock about the hardware it should use. +do this, Drydock needs hardware to run on. We're going to use Almanac to give +Drydock a list of hosts it should use. In this scenario, Almanac will work a bit like a DNS server. When we're done, Drydock will be able to query Almanac for information about a service (like `build.mycompany.com`) and get back information about which hosts are part of -that service and where it should connect to. +that service and which addresses/ports it should connect to. Before getting started, we need to create a **network**. For simplicity, let's suppose everything will be connected through the public internet. If you @@ -52,7 +55,7 @@ haven't already, you'd create a "Public Internet" network first. Once we have a network, we create the actual physical or virtual hosts by launching instances in EC2, or racking and powering on some servers, or already having some hardware on hand we want to use. We set the hosts up normally and -connect them to the internet or network. +connect them to the internet (or another network). After the hosts exist, we add them to Almanac as **devices**, like `build001.mycompany.com`, `build002.mycompany.com`, and so on. In Almanac,