chore: docs

terraform/README.md

@@ -1,28 +1,49 @@
 # Terraform deployment
 
-TODO write this up properly
+This directory contains the terraform files required to deploy the
+malware-scanner service on cloud run.
+
+The deployment is split into 4 stages:
+
+1.  Set up the google cloud project environment and service configuration.
+1.  Use Terraform to set up the required service accounts and deploy required
+    infrastructure.
+1.  Launch cloud build to build the Docker image for the malware-scanner
+    service.
+1.  Use Terraform to deploy the malware-scanner service to cloud run, and
+    connect the service to the infrastructure created in stage 2.
+
+Follow the instructions below to use Terraform to deploy the malware scanner
+service in a demo project.
+
+## Create a project and assign billing
+
+Using the Cloud Console, create a new Cloud project, and assign the billing
+account. Take note of the Project ID of your new project.
 
 ## Clone repo
 
+In Cloud shell, run the following to pull the malware-scanner source code from
+GitHub.
+
 ```bash
 git clone  https://github.com/GoogleCloudPlatform/docker-clamav-malware-scanner.git
 cd docker-clamav-malware-scanner
 ```
 
-## Create a project and assign billing
+## Initialize environment with service configuration
 
-console blah blah blah
+Run the following commands in Cloud Shell to setup your environment and specify
+the parameters of your service for the Terraform deployment.
 
-## Init environment
+Replace `MY_PROJECT_ID` with the ID of your newly created Project.
 
 ```bash
 
 PROJECT_ID=MY_PROJECT_ID
 gcloud config set project $PROJECT_ID
 
 TF_VAR_project_id=$PROJECT_ID
-TF_VAR_region=us-central1
-TF_VAR_bucket_location=us
 TF_VAR_config_json=$(cat <<EOF
 {
   "buckets": [
@@ -37,73 +58,103 @@ TF_VAR_config_json=$(cat <<EOF
 EOF
 )
 TF_VAR_create_buckets=true
+TF_VAR_region=us-central1
+TF_VAR_bucket_location=us
+
 export TF_VAR_project_id TF_VAR_region TF_VAR_bucket_location TF_VAR_config_json TF_VAR_create_buckets
 ```
 
-## Enable core APIs to allow terraform to function
+- `TF_VAR_config_json` contains the configuration of the malware scanner (see
+  [config.json.tmpl](../cloudrun-malware-scanner/config.json.tmpl) for a
+  description of the parameters)
+- `TF_VAR_create_buckets` specifies that you want Terraform to create the
+  unscanned/clean/quarantined buckets specified in your configuration.
+- `TF_VAR_bucket_location` specifies the location of the buckets - required for
+  bucket creation and setting up EventArc triggers.
+- `TF_VAR_region specifies` the region for the remainder of the infrastructure
+  the Cloud Run service, Artifact Registry, and Cloud Scheduler task.
+
+Run the following command to enable the essential APIs for running Terraform.
 
 ```bash
 gcloud services enable cloudresourcemanager.googleapis.com serviceusage.googleapis.com
 ```
 
-or
-[via the console](https://console.cloud.google.com/flows/enableapi?apiid=serviceusage.googleapis.com,cloudresourcemanager.googleapis.com).
+## Set up the service accounts and deploy any infrastructure needed
 
-## Create core infra and service accounts
+Run the following commands:
 
 ```bash
 cd terraform/infra
 terraform init
 terraform apply -auto-approve
 ```
 
+This terraform module performs the following:
+
+- Enables require Google Cloud APIs.
+- Creates an Artifact Registry repository for the malware-scanner image.
+- Creates the malware-scanner and malware-scanner-build service accounts and
+  assigns necessary roles.
+- Creates the unscanned, clean and quarantined buckets specified in the
+  configuration, and assigns the malware-scanner service account the admin role
+  on these buckets.
+- Creates the bucket for the ClamAV malware definitions mirror.
+- Performs an initial population of the ClamAV malware definitions mirror.
+
 ## Build the malware scanner service image
 
+Run the following command to launch a build of the malware-scanner image using
+Cloud Build
+
 ```bash
 cd ../../cloudrun-malware-scanner
-gcloud builds submit --region=$TF_VAR_region --config=cloudbuild.yaml  --service-account=projects/$PROJECT_ID/serviceAccounts/malware-scanner-build@$PROJECT_ID.iam.gserviceaccount.com .
+gcloud builds submit --region=$TF_VAR_region --config=cloudbuild.yaml \
+    --service-account=projects/$PROJECT_ID/serviceAccounts/malware-scanner-build@$PROJECT_ID.iam.gserviceaccount.com \
+    .
 ```
 
-## Deploy the service and connect infra to service with eventarc
+## Deploy the malware-scanner service and connect it to the infrastructure
+
+Run the following commands:
 
 ```bash
 cd ../terraform/service/
 terraform init
 terraform apply -auto-approve
 ```
 
-Note: if you get the error:
+This terraform module performs the following:
+
+- Deploys the malware-scanner service to Cloud Run using the image you built.
+- Set up EventArc triggers on the configured unscanned buckets to launch a
+  malware scan when files are uploaded to those buckets.
+- Set up a Cloud Scheduler job to periodically trigger an update of the ClamAV
+  malware definitions mirror.
+
+**Note:** If the deployment fails with the following error, simply retry running
+the `terraform apply -auto-approve` command
 
 > **Error:** Error creating Trigger: googleapi: Error 400: Invalid resource
 > state for "": Permission denied while using the Eventarc Service Agent. If you
 > recently started to use Eventarc, it may take a few minutes before all
 > necessary permissions are propagated to the Service Agent. Otherwise, verify
 > that it has Eventarc Service Agent role.
 
-Simply retry running `terraform apply -auto-approve`
-
-Last line of output should show:
-
-```text
-Outputs:
-
-cloud_run_uri = "https://malware-scanner-xxxxxxx-xx.a.run.app"
-```
-
 ## Test the service
 
 ### Get version info from cloud run
 
-Use that URL in the following command:
+You can query the malware-scanner service for the version information:
 
 ```bash
 MALWARE_SCANNER_URL="$(terraform output -raw cloud_run_uri)"
 curl -H "Authorization: Bearer $(gcloud auth print-identity-token)"  \
    "${MALWARE_SCANNER_URL}"
 ```
 
-Should output lines showing the versions of the malware scanner, ClamAV and the
-current malware definition package database version/date.
+This command will output lines showing the versions of the malware scanner,
+ClamAV and the current malware definitions version/datem for example:
 
 ```text
 gcs-malware-scanner version 3.0.0
@@ -114,42 +165,40 @@ Service to scan GCS documents for the malware and move the analyzed documents to
 
 ### Create and scan a clean file and an simulated infected file
 
+Run the following command to create 2 files in the unscanned bucket, a simple
+`clean.txt` file and an `eicar-infected.txt` file containing a
+[test string which simulates a virus](https://en.wikipedia.org/wiki/EICAR_test_file)
+
 ```bash
 echo -e 'HELLO WORLD!' \
     | gcloud storage cp - "gs://unscanned-${PROJECT_ID}/clean.txt"
 echo -e 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' \
     | gcloud storage cp - "gs://unscanned-${PROJECT_ID}/eicar-infected.txt"
 ```
 
-Check the unscanned bucket
+Check contents of the unscanned bucket
 
 ```bash
 gcloud storage ls gs://unscanned-${PROJECT_ID}/
 ```
 
-Should have no results (if the files still exist, recheck after a couple of
-seconds)
+This should return no results as the files will have been moved by the
+malware-scanner. If the files still exist, re-run the command after a couple of
+seconds.
 
-Check the clean files bucket
+Check contents of the clean files bucket
 
 ```bash
 gcloud storage ls gs://clean-${PROJECT_ID}/
 ```
 
-should show
-
-```text
-gs://clean-PROJECT_ID/clean.txt
-```
+This should show that the clean.txt file has been moved to the clean bucket.
 
-Check the quarantined bucket
+Check contents of the quarantined bucket
 
 ```bash
 gcloud storage ls gs://quarantined-${PROJECT_ID}/
 ```
 
-should show the infected file in quarantined bucket
-
-```text
-gs://clean-PROJECT_ID/eicar-infected.txt
-```
+This should show that the eicar-infected.txt file has been moved to the
+quarantined bucket.