improve docs

Author: JoshuaFox

ARCHITECTURE.md

@@ -0,0 +1,31 @@
+# Architecture
+
+For the main documentation, See [README](./README.md).
+
+## Iris' architecture
+* Iris runs in Google App Engine Standard Environment (Python 3).
+* It has Organization-level and project-level elements
+  * Note that Iris's design makes it focused on labeling resources across an  organization.
+  * You can filter using the config file, so that Iris labels only some of the   projects in an org 
+  * Iris has architecture components which are deployed to  the org, and others which are deployed to  the project.
+  * If you want a person with all permissions to deploy the org-level elements and a person without org-level permissions to redeploy only the project-level elements (e.g. when you change configuration), you can split the deployment in this way  with flags on the script. Run `deploy.sh -h`.
+* The Cloud Scheduler "cron" job triggers Iris at configured intervals. See `cron_full.yaml` for config. The GCP Console view for this is in a separate App Engine tab in the Cloud Scheduler view.
+* For newly created resources, a Log Sink on the organization level sends all logs for resource creation to a PubSub topic.
+    * The Log Sink is filtered to include only supported resource types.
+    * If you edit the configuration file so that only specific projects are to be labeled, the Log Sink only captures these.
+* PubSub topics:
+*  
+
+iris_deadletter_topic	 
+    * `iris_logs_topic`  receives the resource-creation logs from the Log Sink
+    * `iris_schedulelabeling_topic`  receives messages sent by the `/schedule` endpoint in `main.py` (after the `/schedule` endpoint was triggered by the Cloud Scheduler). Each message goes to endpoint `/do_label` to trigger the labeling of a given resource type in a given project.
+    * Messages to `iris_label_all_types_topic` triggers the labeling of all resources regardless of type.
+    * Another topic is a dead-letter topic.
+* PubSub subscriptions
+    * There are subscriptions that that  direct the messages to  endpoints  in `main.py`: `/label_one`, `/do_label` and `label_all_types`.
+    * For security, the endpoints hit by these PubSub subscriptions [use JWT auth](https://cloud.google.com/pubsub/docs/authenticate-push-subscriptions), where the JWT token is verified in the Iris webapp.
+    * A dead-letter subscription. This is a pull subscription. By default, it just accumulates the messages. You can use it to see statistics, or you can pull messages from it.
+
+# Development and Testing
+Please see [HACKING](./HACKING.md).
+ 

HACKING.md

@@ -1,7 +1,6 @@
-# Iris: How to develop and test  
+# How to develop and test in this codebase
 
-## For the main documentation
-See [README](./README.md).
+For the main documentation, see [README](./README.md).
 
 ## Development tools
 

INSTALL.md

@@ -1,14 +1,12 @@
 # How to Install
 
-(For the main documentation, see [README](./README.md).)
+For the main documentation, See [README](./README.md).
 
 ## Before deploying
-
-### In which Project 
-### In which Project 
+### Selecting a  Project 
 
 * You can deploy Iris in any one project within your Google Cloud organization, but we recommend using a [new project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project) just for this.
-* The script will deploy Iris (an App Engine service) into this project. That does not mean that Iris is focused on labeling this project. (See [README](./README.md).)
+* The script will deploy Iris (an App Engine service) into this project. That does not mean that Iris is focused on labeling this project. Rather, Iris is always focused on labeling across an organization (though you can filter that to specific projects). See [README](./README.md).
 
 ### Needed roles for deployment
 #### Organization-level roles
@@ -55,10 +53,10 @@
 
 # Configuration
 
-* Iris' config file is `config*.yaml`.
+* Iris' config file is `config.yaml`.
     * All values are optional.
     * `config.yaml.orig` has detailed documentation of the fields.
-* Alternatively, you can have `config-test.yaml`. It takes priority if both it and `config-test.yaml` are present.
+* Alternatively, you can have `config-test.yaml`. It takes priority if both it and `config.yaml` are present.
 * `app.yaml` lets you configure App Engine, for example, to set a maximum number of instances. See App Engine documentation.
 * Editing `cron_full.yaml` lets you optionally change the timing for the Cloud Scheduler scheduled labelings, e.g. to do it more frequently. See Google App Engine documentation.
 
@@ -68,7 +66,7 @@
 * Use `uninstall.sh -h` for help.
 
 # Architecture
-Please see [README_architecture](README_architecture.md).
+Please see [ARCHITECTURE](./ARCHITECTURE.md).
 
 # Development and Testing
 Please see [HACKING](./HACKING.md).

README.md

@@ -1,6 +1,7 @@
 # Iris
 
 In Greek mythology, Iris(Ἶρις) is the personification of the rainbow and messenger of the gods. She was the handmaiden to Hera.
+
 ![Iris](./iris.jpg "Iris") 
 # Blog post
 
@@ -14,43 +15,45 @@ Iris automatically assigns labels to Google Cloud Platform resources for easier
 Resources of all supported types in all or some of the projects in the GCP organization will get automatically-generated labels with keys like `iris_zone` (the prefix is configurable), and a value copied from the resource. For example, a Google Compute Engine instance would get labels like
 `[iris_name:nginx]`, `[iris_region:us-central1]` and `[iris_zone:us-central1-a]`. This behavior can be configured in various ways; see below.
 
-## Note: Organization focus
+##  Organization focus
 
-Note that Iris is designed to serve the organization. 
-* It is designed to label all projects in the organization (though you can configure that).
-* The organization focus was chosen because labels are used for billing analysis which is typically done on the organization level (even though projects can in fact be associated arbitrarily with billing accounts). 
+Note that Iris is designed to serve the organization.
+* Iris is designed to label all projects in the organization (though you can filter that down).
+* Iris does not have a project-focused design, where you launch it in a project, and it labels just that project. 
+* The organization focus was chosen because labels are used for billing analysis, which is typically done on the organization level. (But this is not mandatory: Projects can be associated arbitrarily with any billing accounts). 
 
 ## Iris doesn't add new information
 
-Iris does not *add* information, only *copy* values that already exist. For example, it can label a VM instance with its zone; but it cannot add a "business unit" label because it does not know a resource's business unit. For that, you should label all resources when creating them, e.g., in your Terraform scripts. (Indeed, iris can be made extraneous in this way.)
+Iris does not *add* information, only *copy* values that already exist. For example, it can label a VM instance with its zone; but it cannot add a "business unit" label because it does not know a resource's business unit. 
+
+For that, you should label all resources when creating them, e.g., in your Terraform scripts. In fact, I recommend doing that (and making Iris extraneous.)
 
 ## Labeling existing resources when you deploy Iris
 
 If you want to label the resources -- virtual machines, PubSub topics etc. -- that *already exist* when you deploy Iris, see section "[Labeling existing resources](#labeling-existing-resources)" below.
 
 # Open source
 
-Iris is open-source;it is not an official DoiT product. Feel free to send Pull Requests with  new functionality and add new types of labels. See the `TODO.md` file and Github
-issues for features and fixes you might do.
+Iris is open-source; it is not an official DoiT product. Feel free to send Pull Requests with  new functionality and add new types of labels. See the `TODO.md` file and Github issues for features and fixes you might do.
 
 # When Iris adds labels
 
 ## On resource creation
 
-Iris labels newly-created resources by listening to Google Cloud Operations   Logs. You can disable this: See [INSTALL](INSTALL.md) or run `deploy.sh -h`.
+Iris labels most types of newly-created resources by listening to Google Cloud Operations Logs. You can disable this: See [INSTALL](INSTALL.md) or run `deploy.sh -h`.  
 
 ## On schedule
 
-Iris labels resources periodically on a Cloud Scheduler "cron" job. By default, only some types of resources are labeled on  these Cloud Scheduler runs, while most types are not labeled on schedule,  , to save the costs of relabeling with the same label every day.
+Iris labels a few types of resources periodically on a Cloud Scheduler "cron" job. By default, Iris does not label all types of resources  on these cron runs, to save the costs of relabeling -- with the same label -- every day.
 
-You can change that in configuration. Set `label_all_on_cron` to `True` in the configuration file.
+You can have Iris relabel everything on every cron run, See `label_all_on_cron` to `True` in the configuration file.
 
-You can also  disable the scheduled labeling. See Deployment below or run `./deploy.sh -h`
+You can also disable the scheduled labeling entirely. See Deployment below or run `./deploy.sh -h`
 
 ## Labeling existing resources
 
-* When you first use Iris, you may want to label all existing resources. Iris does not do this by default.
-* Publish a PubSub message (the content doesn't matter) to `iris_label_all_types_topic`, for example with `gcloud pubsub topics publish iris_label_all_types_topic --message=does_not_matter --project $PROJECT_ID` and a full labeling will be triggered.
+* When you first use Iris, you may want to label all existing resources. Iris *does not* do this by default.
+* To do this, publish a PubSub message (the content doesn't matter) to `iris_label_all_types_topic`, and a full labeling will be triggered. For example, run with `gcloud pubsub topics publish iris_label_all_types_topic --message=does_not_matter --project $PROJECT_ID` where `$PROJECT_ID` is where Iris is deployed.
 
 # Supported Google Cloud resources
 
@@ -63,7 +66,7 @@ names start `_gcp_`. The part of the function name after `_gcp_` is used for the
     * Including preemptible instances and instances created by Managed Instance Groups.
     * Including instances used as GKE Nodes
 * Compute Engine Disks (Labels name, zone, region)
-    * Disks are labeld on creation and on schedule.
+    * Disks are labeled on creation and on schedule.
     * But disks created along with an Instance are not labeled on creation. They are labeled with the Cloud Scheduler cron job.
     * The label indicating whether a disk is attached will change, if the state changed, on the scheduled labeling.
 * Compute Engine Snapshots (Labels name, zone, region)
@@ -81,8 +84,7 @@ names start `_gcp_`. The part of the function name after `_gcp_` is used for the
 # Installing
 Please see [INSTALL](./INSTALL.md).
 # Architecture
-Please see [README_architecture](./README_architecture.md).
-
+Please see [ARCHITECTURE](./ARCHITECTURE.md).
 # Development and Testing
 Please see [HACKING](./HACKING.md).
 

README_architecture.md

@@ -53,19 +53,21 @@ while getopts 'cepoh' opt; do
       Usage deploy.sh PROJECT_ID
           Argument:
                   The project to which Iris will be deployed
-          Advancd options, to be given before project ID. These are  not to be used except in advanced schenarios.
+          Flags: Advanced options. Not to be used in most cases.
                   A. Labeling only on-creation or on-schedule:
                   -c: Label on Cloud Scheduler cron only
                   -e: Label on-creation-event only
                   The default, if neither -c or -e are given, is to enable both; equivalent to -c -e
 
-                  B. Project/Org level with -p or -o. If neither -p nor -o is given,
-                  the default behavior is to do both; equivalent to -p -o
+                  B. Project/Org level elements with -p or -o. If neither -p nor -o is given,
+                  the default behavior is to do both; equivalent to -p -o.
+                  Note that Iris is always focused on labeling in an org. See README. These flags
+                  are just about limiting the components that are installed when some already are installed.
                   -o: Deploy org-level elements like Log Sink
                   -p: Deploy project-level elements.  Org-level elements are a pre-requisite.
                   This is useful for redeploying to the same project, e.g., to change config.
-                  If you want to deploy to a *different* project,
-                  then you have to deploy the org-level elements.
+                  If you want to deploy to a *different* project, then you have to deploy the
+                  org-level elements.
 
           Environment variable:
                   IRIS_CUSTOM_ROLE (Optional, default is iris3) An identifier for the Iris custom role,