01/01: cdn: Update the README.org file.

[Chris Marusich]

marusich pushed a commit to branch master
in repository maintenance.

commit 5ad1f66c6386a501d9d8897e931b6210e7e02310
Author: Chris Marusich <address@hidden>
Date:   Sun Apr 21 17:26:47 2019 -0700

    cdn: Update the README.org file.
    
    * cdn/README.org: Fix/remove various stale statements.
---
 cdn/README.org | 69 ++++++++++++++++++++++++++--------------------------------
 1 file changed, 31 insertions(+), 38 deletions(-)

diff --git a/cdn/README.org b/cdn/README.org
index 8462209..dbe2712 100644
--- a/cdn/README.org
+++ b/cdn/README.org
@@ -1,7 +1,8 @@
 * Overview
 
-The Guix project maintains an [[https://aws.amazon.com/][AWS]] account to 
provide a [[https://en.wikipedia.org/wiki/Content_delivery_network][CDN]] for 
the
-berlin build farm.  Our CDN is built using 
[[https://aws.amazon.com/cloudfront/][Amazon CloudFront]].
+The Guix project maintains an Amazon Web Services 
([[https://aws.amazon.com/][AWS]]) account to
+provide a Content Distribution Network 
([[https://en.wikipedia.org/wiki/Content_delivery_network][CDN]]) for the 
berlin build
+farm.  Our CDN is built using [[https://aws.amazon.com/cloudfront/][Amazon 
CloudFront]].
 
 We practice 
[[https://en.wikipedia.org/wiki/Infrastructure_as_code]["Infrastructure as 
Code"]].  Nearly all aspects of our AWS
 account are managed via [[https://www.terraform.io/][Terraform]].  The 
"terraform" directory contains
@@ -107,12 +108,12 @@ Account.  Here is the recommended way to do that:
   down in this document.  This just makes it smaller.
 - Add a new entry for Alice's PGP key to terraform/variables.tf, of
   the same form as the others.
-- Add a new IAM user for Alice to terraform/main.tf.  You can just
-  copy and modify the "resource" and "output" blocks from an existing
+- Add a new IAM user for Alice to terraform/iam.tf.  You can just copy
+  and modify the "resource" and "output" blocks from an existing
   administrator user.
 - Add Alice's IAM user to the "administrators" IAM group by adding an
   entry for the user in the "administrators-membership" resource (also
-  in terraform/main.tf).
+  in terraform/iam.tf).
 - Run "AWS_PROFILE=guix terraform apply" to see what will change.
 - To actually make the changes, enter "yes" at the Terraform prompt.
   You will see output like the following:
@@ -144,15 +145,15 @@ section titled "IAM Login URL" elsewhere in this 
document).
 *** Remove an administrator
 
 To revoke Alice's access by deleting her IAM user, just delete the
-configuration from terraform/main.tf and terraform/variables.tf, and
-then run "AWS_PROFILE=guix terraform apply".  When you say "yes" to
-the prompt, it will delete Alice's IAM user, which means Alice will no
-longer be able to use her access key or password.
+configuration for her user that you added above, and then run
+"AWS_PROFILE=guix terraform apply".  When you say "yes" to the prompt,
+it will delete Alice's IAM user, and Alice will no longer be able to
+use her access key or password.
 
 *** Update the CloudFront distribution
 
-Make a change to the configuration in terraform/main.tf.  Then run
-"AWS_PROFILE=guix terraform apply" and say "yes" at the prompt.
+Make a change to the configuration in terraform/cloudfront.tf.  Then
+run "AWS_PROFILE=guix terraform apply" and say "yes" at the prompt.
 Terraform will make the changes.
 
 It might take a while (minutes) for the update to actually complete,
@@ -164,8 +165,9 @@ check on the distribution's status.
 
 In AWS, usually an alarm works like this.  When a CloudWatch metric,
 such as "total estimated charges for the month", exceeds an alarm
-threshold, CloudWatch will send a message to an SNS topic.  To receive
-the message, you must be subscribed to the topic.
+threshold, CloudWatch will send a message to a Simple Notification
+Service ([[https://docs.aws.amazon.com/sns/latest/dg/welcome.html][SNS]]) 
topic.  To receive the message, you must be subscribed
+to the topic.
 
 Terraform doesn't manage email subscriptions to SNS topics.
 Therefore, if you want to receive an alert via email, you must
@@ -1391,9 +1393,12 @@ Configuration files can contain things like this:
 - variable(s)
 - output(s)
 
-For now, we have a file called "main.tf" that describes all the
-Terraform-managed resources, and another file named "variables.tf"
-that contains variables that are referenced by resources in "main.tf".
+For now, we have a file called "main.tf", which configures some
+high-level aspects of Terraform (e.g., the region to use).
+Service-specific configuration is split into service-specific files;
+for example, the "iam.tf" file contains IAM-specific
+configuration. Finally, the file "variables.tf" contains variables
+that are referenced by resources in the other files.
 
 See:
 https://learn.hashicorp.com/terraform/getting-started/variables
@@ -1434,25 +1439,10 @@ 
https://learn.hashicorp.com/terraform/getting-started/build
 By default, "terraform init" downloads and installs "plugin" binaries.
 It would be better if they were packaged individually in Guix.
 
-*** Needs to keep track of some state
-
-https://learn.hashicorp.com/terraform/getting-started/build
-
-"Terraform also wrote some data into the terraform.tfstate file. This
-state file is extremely important; it keeps track of the IDs of
-created resources so that Terraform knows what it is managing. This
-file must be saved and distributed to anyone who might run
-Terraform. It is generally recommended to setup remote state when
-working with Terraform, to share the state automatically, but this is
-not necessary for simple situations like this Getting Started guide."
-
-consider using s3 backend for remote state
-https://www.terraform.io/docs/backends/
-https://www.terraform.io/docs/state/remote.html
-
 *** terraform registry
 
-a collection of 'modules':
+A collection of 'modules':
+
 https://registry.terraform.io/
 
 ** Questions
@@ -1462,21 +1452,23 @@ https://registry.terraform.io/
 - Does it ever return 3xx (e.g. redirects)?  Will those be interpreted
   as redirects to the CloudFront distribution, or will it cause
   clients to send requests directly to the build farm (which would be
-  undesirable)?
+  undesirable)?  I think the asnwer is "no", it doesn't return
+  redirects.
 - Are there any URLs that are not returning a Cache-Control (or
   Expires) header but should be?  The CloudFront distribution is
   currently configured to cache a response for 24 hours if it omits
-  such a header.
+  such a header.  There are no such URLs as far as I can tell.
 - Are there any URLs that are returning a Cache-Control (or Expires)
   header but either (1) should actually omit the header or (2) is
-  specifying an unreasonable value?
+  specifying an unreasonable value?  There are no such URLs as far as
+  I can tell.
 - Should we include "Cache-Control: max-age" or "Cache-Control:
   s-maxage" in responses we want to be cached?  It seems the
   difference only matters when caching results in a web browser.  For
   our use case, I don't think we need to bother using s-maxage at all.
 - Is it OK to ignore query parameters, headers, and cookies when
-  deciding whether or not to cache?  This might be a problem if
-  something, such as Cuirass, depends on their presence.
+  deciding whether or not to cache?  We don't cache anything that
+  needs these, so it's OK to ignore them.
 
 *** Terraform
 
@@ -1495,3 +1487,4 @@ https://registry.terraform.io/
 - Use origin failover to serve requests via the CDN from berlin first,
   and hydra second?
   
https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/high_availability_origin_failover.html
+- Support HTTPS only (i.e., drop support for HTTP without TLS).