address PR comments

README.md

@@ -2,9 +2,9 @@
 
 [![Build Status](https://dev.azure.com/azure/azure-service-operator/_apis/build/status/Azure.azure-service-operator?branchName=master)](https://dev.azure.com/azure/azure-service-operator/_build/latest?definitionId=36&branchName=master)
 
-> This project is experimental. Expect the API to change. It is not recommended for production environments.
+> This project is experimental. The API is expected to change (while adhering to semantic versioning). It is not recommended for production environments.
 
-Azure Service Operator helps you provision Azure resources from within Kubernetes.
+The Azure Service Operator helps you provision Azure resources and connect your applications to them from within Kubernetes.
 
 ## Overview
 
@@ -21,25 +21,27 @@ For more details on the control flow of the Azure Service operator, refer to the
 
 ## Azure Services supported
 
-1. [Resource Group](/docs/services/resourcegroup/resourcegroup.md)
-2. [EventHub](/docs/services/eventhub/eventhub.md)
-3. [Azure SQL](/docs/services/azuresql/azuresql.md)
-4. [Azure Database for PostgreSQL](/docs/services/postgresql/postgresql.md)
-5. [Azure Database for MySQL](/docs/services/mysql/mysql.md)
-6. [Azure Keyvault](/docs/services/keyvault/keyvault.md)
-7. [Azure Rediscache](/docs/services/rediscache/rediscache.md)
-8. [Storage Account](/docs/services/storage/storageaccount.md)
-9. [Blob container](/docs/services/storage/blobcontainer.md)
-10. [Virtual Network](/docs/services/virtualnetwork/virtualnetwork.md)
-11. [Application Insights](/docs/services/appinsights/appinsights.md)
-12. [API Management](/docs/services/apimgmt/apimgmt.md)
-13. [Cosmos DB](/docs/services/cosmosdb/cosmosdb.md)
+- [Resource Group](/docs/services/resourcegroup/resourcegroup.md)
+- [EventHub](/docs/services/eventhub/eventhub.md)
+- [Azure SQL](/docs/services/azuresql/azuresql.md)
+- [Azure Database for PostgreSQL](/docs/services/postgresql/postgresql.md)
+- [Azure Database for MySQL](/docs/services/mysql/mysql.md)
+- [Azure Keyvault](/docs/services/keyvault/keyvault.md)
+- [Azure Rediscache](/docs/services/rediscache/rediscache.md)
+- [Storage Account](/docs/services/storage/storageaccount.md)
+- [Blob container](/docs/services/storage/blobcontainer.md)
+- [Virtual Network](/docs/services/virtualnetwork/virtualnetwork.md)
+- [Application Insights](/docs/services/appinsights/appinsights.md)
+- [API Management](/docs/services/apimgmt/apimgmt.md)
+- [Cosmos DB](/docs/services/cosmosdb/cosmosdb.md)
+- [Virtual Machine](/docs/services/virtualmachine/virtualmachine.md)
+- [Virtual Machine Scale Set](/docs/services/vmscaleset/vmscaleset.md)
 
 ## Getting started
 
 This project maintains [releases of the Azure Service Operator](https://github.com/Azure/azure-service-operator/releases) that you can deploy via a [configurable Helm chart](/charts/azure-service-operator).
 
-For detailed instructions on getting started, refer [here](docs/howto/contents.md).
+For detailed instructions on getting started, go [here](docs/howto/contents.md).
 
 Please see the [FAQ][docs/faq.md] for answers to commonly asked questions about the Azure Service Operator
 

docs/faq.md

@@ -2,6 +2,14 @@
 
 This page provides help with the most common questions about Azure Service Operators
 
-## FAQ1
+### Do I have to order the creation of resources through the operator? For instance, do I need to first create the EventHub namespace before creating the EventHub?
+No, you can issue the creation of all resources at the same time. The operator will take care of waiting and requeing the requests until the parent resource is ready and all resources will eventually be ready.
 
-## FAQ2
+### If I need to add a new field to the spec of an existing CRD, do I need to increment the version of the CRD?
+Yes, we follow semantic versioning to preserve backward compatibility. Please follow Kubebuilder's versioning [mechanism](https://book.kubebuilder.io/multiversion-tutorial/conversion-concepts.html) for this.
+
+### Is there a guide that talks about how to develop an operator for a new Azure service?
+There is a step-by-step guide that walks you through this process [here](/howto/newoperatorguide.md)
+
+### Are there any sample apps that demonstrate how to utilize the Azure Service Operators?
+We have some samples that illustrate how to use Azure Service Operators along with your application [here](https://github.com/Azure-Samples/azure-service-operator-samples). The samples also show how to utilize post-deployment-secrets from the Azure Service Operator.

docs/howto/deploy.md

@@ -14,16 +14,16 @@ The easiest way to deploy the Azure Service Operator is to use Helm charts. Foll
     export GO111MODULE=on
     ```
 
-3. Log into Docker Hub and then build the image and push it to Docker Hub.
+3. Log in to your container registry, set the IMG env var, and then build and push the image.
 
     ```shell
     docker login
-    IMG=<dockerhubusername>/<imagename>:<tag> make build-and-push
+    IMG=<container_registry>/<username>/<image_name>:<tag> make build-and-push
     ```
 
 ### Deploy the operator
 
-**Note** You should already have a Kubernetes cluster prerequisites [here](prereqs.md) for information on creating a Kubernetes cluster.
+**Note** You should already have a Kubernetes cluster. See prerequisites [here](prereqs.md) for information on creating a Kubernetes cluster.
 
 1. Set up the Cluster
 

docs/howto/helmdeploy.md

@@ -12,6 +12,12 @@ kubectl label namespace cert-manager cert-manager.io/disable-validation=true
 kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.12.0/cert-manager.yaml
 ```
 
+You can use the below command to check if the cert manager pods are ready. The cert manager pods should be running before proceeding to the next step.
+
+```
+kubectl rollout status -n cert-manager deploy/cert-manager-webhook
+```
+
 #### Helm
 
 Install the latest (3.x+) [Helm](https://helm.sh/docs/intro/install/) on your machine.

docs/howto/newoperatorguide.md

@@ -9,7 +9,7 @@ This project utilizes a generic async controller that separates out the Kubernet
 ```
 kubebuilder create api --group azure --version v1alpha1 --kind <AzureNewType>
 
-kubebuilder create api --group azure --version v1alpha1 --kind AzureSQLServer
+# e.g. kubebuilder create api --group azure --version v1alpha1 --kind AzureSQLServer
 ```
 
 4. When you run this command, you will be prompted with two questions. Answer yes to both of these.
@@ -78,11 +78,16 @@ go build -o bin/manager main.go
     You can refer to the other types in this repo as examples to do this.
 
     c. Add the Kubebuilder directive to indicate that you want to treat `Status` as a subresource of the CRD. This allows for more efficient updates and the generic controller assumes that this is enabled for all the types.
+    Also add the Kubebuilder directives to designate short names for the CRD and to add additional columns to the output of `kubectl get`.
 
     ```go
     // +kubebuilder:object:root=true
     // +kubebuilder:subresource:status   <--- This is the line we need to add
 
+    // +kubebuilder:resource:shortName=[shortnamehere],path=[crdpath]
+    // +kubebuilder:printcolumn:name="Provisioned",type="string",JSONPath=".status.provisioned"
+    // +kubebuilder:printcolumn:name="Message",type="string",JSONPath=".status.message"
+
     // AzureNewType is the Schema for the azurenewtypes API
     type AzureNewType struct {
         metav1.TypeMeta   `json:",inline"`
@@ -164,17 +169,17 @@ go build -o bin/manager main.go
         }
     ```
 
-    e. The `azurenewtype_reconcile.go` file implements the  following functions in the ARMClient interface: 
+    e. The `azurenewtype_reconcile.go` file implements the  following functions in the `ARMClient` interface:
        -  `Ensure`, `Delete`, `GetParents`, `GetStatus`
        - It would also have a `convert` function to convert the runtime object into the appropriate type
 
     Some key points to note:
     (i) The Ensure and Delete functions return as the first return value, a bool which indicates if the resource was found in Azure. So Ensure() if successful would return `true` and Delete() if successful would return `false`
 
     (ii) On successful provisioning in `Ensure()`, 
-    - set instance.Status.Message to the constant `SuccessMsg` in the `resourcemanager` package to be consistent across all controllers.
-    - set instance.Status.ResourceID to the full Azure Resource ID of the resource
-    - set instance.Status.Provisioned to `true` and instance.Status.Provisioning to `false`
+    - set `instance.Status.Message` to the constant `SuccessMsg` in the `resourcemanager` package to be consistent across all controllers.
+    - set `instance.Status.ResourceID` to the full Azure Resource ID of the resource
+    - set `instance.Status.Provisioned` to `true` and `instance.Status.Provisioning` to `false`
 
     ```go
     func (p *AzureNewTypeClient) Ensure(ctx context.Context, obj runtime.Object) (found bool, err error) {