Add documentation (openshift#54)

Create documentation for SRE and Developers who want either to
contribute or use the Operator. It adds a "docs" directory
and dumps all the related documents:

 * docs/README          - central TOC overview of the documentation
 * docs/gcpconfig       - instructions for GCP Configuration
 * docs/userstory       - how to use it
 * docs/debug           - tips and tricks
 * docs/api             - api description
 * docs/design          - describes the CRDs
 * docs/building        - instruction for building the project
 * docs/development     - devenv setup
 * docs/troubleshooting - common error during dev cycles
 * docs/analysis        - high-level overview of the code

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+### How to become a GCP Project contributor
+
+## Code of Conduct
+
+As contributors and maintainers of this GCP Project Operator, we do respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. In short, be excellent to each other.
+
+## Finding issues to work on
+
+* ["good-first-issue](https://github.com/openshift/gcp-project-operator/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) - issues where they are easy to complete even for beginners
+
+* ["help wanted"](https://github.com/openshift/gcp-project-operator/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - issues where we currently have no resources to work on them as there are other pressing matters
+
+Once you've discovered an issue to work on:
+
+* Add a comment mentioning that you plan to work on this issue and assign it to yourself.
+* Send a PR out that mentions the issue in the _commit_ message.
+
+## Contributing A Patch
+
+If you are new to open-source contribution, please read the this [guide](https://developers.redhat.com/articles/command-line-heroes-game-pull-request/) to get yourself familiar with the basics.
+
+## Writing tests
+
+As a best practice, the project requires tests to be submitted at the same PR with the code. If you are developing a new feature, please remember writting tests for it as well. See the relevant [testing documenation](./docs/testing.md)

docs/README.md

@@ -0,0 +1,19 @@
+# Documentation
+
+If you like'd to contribute to GCP Project Operator, please be so kind to read our [Contribution Policy](./CONTRIBUTING.md) first.
+
+## For Users
+
+* [Google GCP configuration](./gcpconfig.md) -- The Operator expects a `configmap` and a `secret` to be already present in the cluster before you use it.
+* [How to use it](./userstory.md) -- Tell the Operator to create or delete a new GCP Project for you
+* [Debugging](./debug.md) -- Useful tips and commands
+* [API](./api.md) -- Options you can fine-tune for `ProjectClaim`
+
+## For Developers
+
+* [Design](./design.md) -- describes the interaction between the custom resource definitions
+* [Building](./building.md) -- instructions for building the project
+* [Development](./development.md) -- instructions for developers who want to contribute.
+* [Testing](./testing.md) -- instructions for writing tests
+* [Troubleshooting](./troubleshooting.md) -- Common errors and pitfalls
+* [Code Analysis](./analyze.md) -- A high-level analysis of the code to get yourself familiar with the codebase

docs/api.md

@@ -0,0 +1,42 @@
+# API
+
+## ProjectClaim CR
+
+### Metadata
+
+| Field | Description | Scheme | Required |
+| ----- | ----------- | ------ | -------- |
+| name | ProjectClaim name | string | true |
+| namespace | Namespace of ProjectClaim | string | true |
+
+### Spec
+
+| Field | Description | Scheme | Required |
+| ----- | ----------- | ------ | -------- |
+| region | GCP Region Zone | string | true |
+| gcpProjectID | GCP Project unique identifier | string | true |
+
+#### gcpCredentialSecret
+
+| Field | Description | Scheme | Required |
+| ----- | ----------- | ------ | -------- |
+| name | secret name | string | true |
+| namespace | secret's namespace | string | true |
+
+#### projectReferenceCRLink
+
+| Field | Description | Scheme | Required |
+| ----- | ----------- | ------ | -------- |
+| name | projectReference instance name | string | false |
+| namespace | projectReference instance namespace | string | false |
+
+#### legalEntity
+
+| Field | Description | Scheme | Required |
+| ----- | ----------- | ------ | -------- |
+| name | customer entity name | string | true |
+| id | customer identification number | string | true |
+
+## ProjectReference CR
+
+It is generated and populated by the Operator

docs/building.md

@@ -0,0 +1,25 @@
+# Building the GCP Project Operator
+
+## Prerequisites
+
+* A recent Go distribution (>=1.14) with enabled Go modules
+
+* Docker or Podman
+
+* The `make` binary
+
+## Downloading the source
+
+```zsh
+# inside your $GOPATH/src/*
+$ git clone https://github.com/openshift/gcp-project-operator
+$ cd gcp-project-operator
+```
+
+## Compiling gcp-project-operator
+
+```zsh
+$ make
+```
+
+This will build the binaries (which can then be found in `gcp-project-operator/build/_output/bin`) and run tests.

docs/debug.md

@@ -0,0 +1,103 @@
+# Debugging
+
+Some useful commands:
+
+### ProjectClaim
+
+The `ProjectClaim` is getting deployed onto a namespace defined at the Resource.
+
+```kube
+name="example-projectclaim"
+namespace="example-clusternamespace"
+
+kubectl -n $namespace get projectclaim $name
+NAME                   STATE   GCPPROJECTID           AGE
+example-projectclaim   Ready   example-GCPprojectID   2m33s
+```
+
+If everything worked as expected the **STATE** should be `READY`.
+Some useful information you can extract by passing the `-o yaml` is:
+
+```
+kubectl -n $namespace get projectclaim $name -o yaml
+```
+
+* The `availabilitiZones`:
+
+```yaml
+  availabilityZones:
+  - us-east1-b
+  - us-east1-c
+  - us-east1-d
+```
+
+* The `gcpCredentialSecret`:
+
+```yaml
+  gcpCredentialSecret:
+    name: gcp-secret
+    namespace: example-clusternamespace
+```
+
+Having found the namespace, you can gather even more information:
+
+```
+kubectl -n example-clusternamespace get secrets gcp-secret -o yaml
+```
+
+If the `ProjectClaim` is not in READY state but in **PendingProject** it means the operator is still working on creating a project in GCP.
+
+```kube
+kubectl -n example-clusternamespace get projectclaim example-projectclaim
+NAME                   STATE            GCPPROJECTID           AGE
+example-projectclaim   PendingProject   example-GCPprojectID   82s
+```
+
+### ProjectReference
+
+It gets created automatically by the Operator.
+You can find it in two ways:
+
+1. Looking at the `projectReferenceCRLink` of the `ProjectClaim`. For example if the `projectReferenceCRLink` looks like this:
+
+```yaml
+  projectReferenceCRLink:
+    name: example-clusternamespace-example-projectclaim
+    namespace: gcp-project-operator
+```
+
+then you can query for the `ProjectReference` like this:
+
+```
+kubectl get projectreferences example-clusternamespace-example-projectclaim -o yaml
+```
+
+2. Looking at all the `ProjectReferences` under the `gcp-project-operator` namespace.
+
+```kube
+$ kubectl -n gcp-project-operator get projectreferences
+NAME                                            STATE   CLAIMNAME              CLAIMNAMESPACE             AGE
+example-clusternamespace-example-projectclaim   Ready   example-projectclaim   example-clusternamespace   20m
+```
+
+Here you can find the real name of the GCP Project created at Google side by adding `-o yaml` at the end of the command:
+
+```
+kubectl -n gcp-project-operator get projectreferences example-clusternamespace-example-projectclaim -o yaml
+```
+
+* The `gcpProjectID`
+
+```yaml
+gcpProjectID: o-a68db2ad
+```
+
+* The `projectClaimCRLink`:
+
+```yaml
+  projectClaimCRLink:
+    name: example-projectclaim
+    namespace: example-clusternamespace
+```
+
+Notice that both `ProjectClaim` and `ProjectReference` are cross-referencing each other. That means if you know one of them, you can easily find the other.

docs/design.md

@@ -0,0 +1,27 @@
+# Design
+
+This document describes the design and interaction between the custom resource definitions that the GCP Project Operator introduces.
+
+The custom resources that the GCP Project Operator introduces:
+
+* `ProjectClaim`
+* `ProjectReference`
+
+## ProjectClaim
+
+The `ProjectClaim` custom resource definition (CRD) declaratively defines a desired specification for a GCP Project setup to run a Kubernetes cluster.
+It provides options to configure your cluster's [region and zone](https://cloud.google.com/compute/docs/regions-zones), legal entity and credentials such as the gcp secret.
+
+For each `ProjectClaim` resource, the Operator deploys a properly configured `ProjectReference` in the `gcp-project-operator` namespace.
+It also adds a Finalizer to make sure `ProjectClaim` is not going to get deleted while `ProjectReference` exists.
+
+## ProjectReference
+
+The `ProjectReference` custom resource definition (CRD) defines the actual project setup to run inside Google GCP. It is generated automatically by the Operator instead of the user. 
+
+Since this is generated by the Operator, the tracking of the parent object is done by the `projectClaimCRLink` that includes the `CLAIMNAME` and the `CLAIMNAMESPACE` of the `ProjectClaim` which created this `ProjectReference` resource.
+
+The [creation of a GCP Project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) requires a _unique_ identifier which gets generated by the Operator.
+It can be found in the `gcpProjectID` spec and can be accessed online via the [Google's GCP Resource Manager](https://console.cloud.google.com/cloud-resource-manager).
+
+Before the actual creation of the Project in GCP, the Operator adds a finalizer to make sure this `ProjectReference` cannot be deleted by accident. When the user requests the deletion of the project, the finalizer makes sure the `ProjectReference` is not deleted unless both the actual project in Google GCP and the `gcp-secret` have been deleted as well.

docs/development.md

@@ -0,0 +1,121 @@
+# Development
+
+## Development Environment Setup
+
+* A recent Go distribution (>=1.14) with enabled Go modules
+
+```
+export OPERATOR_NAME=gcp-project-operator
+export GO111MODULE=on
+```
+
+* Code-Ready Containers
+
+Red Hat CodeReady Containers brings a minimal OpenShift 4 cluster to your local computer.
+This cluster provides a minimal environment for development and testing purposes.
+It’s mainly targeted at running on developers' desktops.
+Installation and configuration of CRC is beyond the scope of this document.
+Alternatively you can use `minikube` instead.
+
+* kubectl client (>= version with your kubernetes server)
+
+Make sure kubectl is pointing to your kubernetes cluster you want to test the Operator against.
+
+* Operators SDK
+
+The Operator is being developed based on the [Operators SDK](https://github.com/operator-framework/operator-sdk).
+Make sure you have it installed correctly.
+
+* Docker or Podman
+
+## Run the operator
+
+The operator can run either:
+
+* locally - without building a container and pushing it to your kubernetes cluster. This is the most convenient way.
+* remotely - building a container with podman/docker and pushing to a registry and installing to your k8s cluster along with some RBAC configuration
+
+No matter which option you choose, before running the Operator you have to create the following Custom Resource Definitions on the cluster:
+
+```zsh
+kubectl create -f deploy/crds/gcp_v1alpha1_projectclaim_crd.yaml
+kubectl create -f deploy/crds/gcp_v1alpha1_projectreference_crd.yaml
+```
+
+### Locally
+
+Make sure you have the [operator-sdk](https://github.com/operator-framework/operator-sdk/releases) binary in your `$PATH` and run it locally:
+
+```zsh
+$ operator-sdk run --local --namespace gcp-project-operator
+```
+
+You will see some initialization logs.
+The Operator will remain _idle_ after that, waiting for `ProjectClaim` resources to be present in the cluster.
+
+### Remotely
+
+#### Pushing Image a container registry
+
+Push the image to your container registry of your choice. For example:
+
+```bash
+username="razevedo"
+podman build . -f build/Dockerfile -t "quay.io/$username/gcp-project-operator"
+podman push "quay.io/$username/gcp-project-operator"
+```
+
+#### Deploying code
+
+Update deploy/operator.yaml with image you would like deployed.
+
+```kube
+kubectl apply -f deploy/cluster_role_binding.yaml
+kubectl apply -f deploy/cluster_role.yaml
+kubectl apply -f deploy/service_account.yaml
+kubectl apply -f deploy/operator.yaml
+```
+
+If you need to update to lastest image pushed to quay repo.
+
+```kube
+kubectl scale deployment gcp-project-operator -n gcp-project-operator --replicas=0
+kubectl scale deployment gcp-project-operator -n gcp-project-operator --replicas=1
+```
+
+Otherwise, you can directly upload the image to your kubernetes cluster by hand
+
+```zsh
+# Export the image locally
+docker save $image-name > image-name.tar
+
+# Copy the image to your CRC/Minikube remote cluster. Copy one of the following:
+scp image-name.tar core@`minikube ip`:   # minikube
+scp image-name.tar core@`crc ip`:        # CRC
+
+# SSH into the k8s node and load the image
+minikube ssh # For minikube
+
+# SSH into k8s node (for CRC devenv)
+export CRCIP=$(crc ip)
+alias sshcrc="ssh -o ConnectionAttempts=3 -o ConnectTimeout=10 -o ControlMaster=no -o ControlPath=none -o LogLevel=quiet -o PasswordAuthentication=no -o ServerAliveInterval=60 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null [email protected] -o IdentitiesOnly=yes -i /Users/drpaneas/.crc/machines/crc/id_rsa -p 22"
+
+# Load the image to CRI-O
+cat image-name.tar | podman load
+```
+
+## Configure GCP Cloud
+
+The Operator requires some GCP–related configs to be present on your cluster.
+
+Follow [these instructions](./gcpconfig.md) to create both the `configmap` and the `secret` required.
+
+## Use the Operator
+
+No matter if the operator is running locally or remotely, you can request it to create Google GCP Project for you. So, if you want to actually test the operator, create a `ProjectClaim` resource or apply the example:
+
+```
+kubectl create -f deploy/crds/gcp_v1alpha1_projectclaim_cr.yaml
+```
+
+This will trigger the Operator to start reconciling.