Add information about authentication and the build and release proces…

…ses (#31)

docs/authentication.md

@@ -8,7 +8,21 @@ against two systems:
 
 ## Authenticate against MQTT brokers
 
-(WIP, to update after we expose authentication configuration)
+The **MQTT <-> Cloud Pub/Sub Connector** supports connecting to MQTT brokers that
+offer:
+
+- non-authenticated access (i.e. public access)
+- password-based authentication
+
+To configure the password-based authentication, you need to provide the necessary configuration
+properties as described [here](https://camel.apache.org/components/latest/paho-mqtt5-component.html).
+
+### SSL/TLS certificates to secure the connection
+
+The **MQTT <-> Cloud Pub/Sub Connector** supports securing a comminication channel using a SSL/TLS
+certificate. For more information about how to provide a certificate and configure the **MQTT <-> Cloud Pub/Sub Connector**
+to use that certificate to secure the connection to the MQTT broker, refer to
+the [Apache Camel Paho MQTT 5 component documentation](https://camel.apache.org/components/latest/paho-mqtt5-component.html).
 
 ## Authenticate against Cloud Pub/Sub
 

docs/build-release-processes.md

@@ -1,3 +1,31 @@
-# MQTT <-> Cloud Pub/Sub Connector build and release process
+# MQTT <-> Cloud Pub/Sub Connector build and release processes
 
-(WIP, to write after we design those processes)
+In this document, we describe the build processes.
+
+At this point, there's no release process defined. This may change in the future
+based on demand.
+
+## Details about the build process
+
+To build this project from the command-line, we use the same dev container that
+we designed to build the project from inside VS Code. For more information about
+the development environment and the dev container, refer to [Development environment](./development-environment.md).
+
+The build process does the following:
+
+1. Runs a dev container instance.
+2. Starts the project build process inside the dev container instance.
+
+The project build process does the following:
+
+1. Runs code linters.
+2. Builds all the project assets.
+3. Runs the unit tests suite.
+4. Runs the containers that the integration tests suite needs.
+5. Runs the integration tests suite.
+6. Finalizes the project build by packaging project assets.
+
+All these container management tools share the same container runtime environment.
+
+For more information about how to start the build process, refer to
+[Development environment](./development-environment.md).

docs/design.md

@@ -5,14 +5,14 @@ In this document, we describe the design of the **MQTT <-> Cloud Pub/Sub connect
 We decided to name this project a connector rather than a message broker to emphasize its generic nature for something
 that connects MQTT brokers and Cloud Pub/Sub, and acts as a thin translation layer.
 
-## Expected deliverables
+## Deliverables
 
 - Source code of all the software components and related release artifacts, hosted in
   publicly accessible repositories (this code repository).
 - [Infrastructure-as-code descriptors to provision the cloud resources for a testing and validation environment](../README.md#provision-a-test-and-validation-runtime-environment-on-google-cloud).
 - [Comprehensive, automated test suites](./development-environment.md).
-- Documentation about the design (this document), [testing](./development-environment.md),
-  how to use ([authentication guide](./authentication.md), [configuration guide](./configuration.md)), and
+- Documentation about the design (this document), how to setup a [development environment](./development-environment.md),
+  how to ([authenticate the Connector](./authentication.md), how to [configure the Connector](./configuration.md)), and
   [how to contribute](../CONTRIBUTING.md) to each component.
 - [Documentation about release and maintenance processes](./build-release-processes.md).
 

docs/development-environment.md

@@ -49,7 +49,7 @@ To run tests from Visual Studio Code:
 2. Open the `Java Projects` panel or open the JUnit test file from `src/test/java`.
 3. Click on the _play_ icon near the test or the test suite that you want to run.
 
-### Run the full test suite from the command-line
+### Build the project and run the test suite from the command-line
 
 To run tests from the command-line, do the following:
 
@@ -90,20 +90,6 @@ All the linters have their configuration stored in the `config/lint` directory.
 Additionally, some linters shipped within `super-linter` also take the
 [EditorConfig configuration file](../.editorconfig) into account.
 
-## Details about the command-line build process
+## Details about the build process
 
-To build this project from the command-line, we use the same dev container that
-we designed to build the project from inside VS Code. The build process does the
-following:
-
-1. Run a dev container instance to build the process.
-2. Run the project build process inside the dev container.
-3. The project build process:
-    1. Runs code linters.
-    2. Builds all the project assets.
-    3. Runs the unit tests suite.
-    4. Runs the containers that the integration tests suite needs.
-    5. Runs the integration tests suite.
-    6. Finalizes the project build by packaging project assets.
-
-All these container management tools share the same container runtime environment.
+For more information about the build process, refer to [Build and release processes](./build-release-processes.md)

docs/provision-deploy-google-cloud-gke.md

@@ -34,6 +34,18 @@ project to create those resources into, and a Cloud Storage bucket to store Terr
 
     The script guides you in providing the necessary configuration data.
 
+### Necessary permissions to provision the environment in a new project
+
+To provision the environment in a new project, you need to authenticate against
+Google Cloud using an account that has the necessary permissions in your Google
+Cloud Organization. For more information about the necessary roles and
+permissions, refer to:
+
+- [Creating a project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)
+- [Enable billing for a project](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+- [Creating a Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets)
+- The permissions listed [in the next section](#necessary-permissions-to-provision-the-environment-in-an-existing-project)
+
 ## Provision the environment on Google Cloud in an existing project
 
 If you provisioned the environment by following the guidance in [Provision the environment on Google Cloud in a new project](#provision-the-environment-on-google-cloud-in-a-new-project),
@@ -51,8 +63,30 @@ If you want to provision a test and validation runtime environment in an existin
 
     The script guides you in providing the necessary configuration data.
 
+### Necessary permissions to provision the environment in an existing project
+
+To provision the environment in an existing project, you need to authenticate
+against Google Cloud using an account that has the necessary permissions in your
+Google Cloud Organization:
+
+- `roles/artifactregistry.admin` to create and manage repositories.
+- `roles/compute.instanceAdmin.v1` to create and manage Compute Engine instances.
+- `roles/compute.networkAdmin` to create and manage network resources, such as Cloud Routers and Cloud Firewall rules.
+- `roles/container.admin` to create and manage GKE clusters.
+- `roles/pubsub.admin` to create Cloud Pub/Sub subscriptions and topics, and to configure IAM.
+
+For more information about the necessary roles and permissions, refer to:
+
+- [Artifact Registry roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions)
+- [Compute Engine roles and permissions](https://cloud.google.com/compute/docs/access/iam)
+- [GKE access control](https://cloud.google.com/kubernetes-engine/docs/concepts/access-control)
+- [GKE IAM roles](https://cloud.google.com/kubernetes-engine/docs/how-to/iam#roles)
+- [Cloud Pub/Sub IAM roles](https://cloud.google.com/pubsub/docs/access-control#roles)
+
 ## Deploy workloads
 
+To deploy workloads in the GKE cluster, do the following:
+
 1. Run the workload build script:
 
     ```sh
@@ -65,6 +99,19 @@ If you want to provision a test and validation runtime environment in an existin
     scripts/deploy-workloads.sh
     ```
 
+### Necessary permissions to deploy workloads
+
+To deploy workloads in the GKE cluster, you need the following, you need to
+authenticate against Google Cloud using an account that has the necessary
+permissions in your Google Cloud Organization:
+
+- `roles/container.developer` to access Kubernetes APIs.
+
+For more information about the necessary roles and permissions, refer to:
+
+- [GKE access control](https://cloud.google.com/kubernetes-engine/docs/concepts/access-control)
+- [GKE IAM rolese](https://cloud.google.com/kubernetes-engine/docs/how-to/iam#roles)
+
 ## Clean up
 
 To delete all the resources and workloads in the environment, run the following command: