Merge pull request #1185 from Azure/docs-update

Docs update

README.md

@@ -4,7 +4,7 @@
 
 > This project is experimental. The API is expected to change (while adhering to semantic versioning). Alpha and Beta resources are generally not recommended for production environments.
 
-The Azure Service Operator helps you provision Azure resources and connect your applications to them from within Kubernetes.
+The **Azure Service Operator** helps you provision Azure resources and connect your applications to them from within Kubernetes.
 
 ## Overview
 
@@ -15,19 +15,19 @@ The Azure Service Operator comprises of:
 
 The project was built using [Kubebuilder](https://book.kubebuilder.io/).
 
-For more details on the control flow of the Azure Service operator, refer to [Azure Service Operator control flow](/docs/design/controlflow.md)
+Curious to see how it all works? Check out our [control flow diagrams](/docs/design/controlflow.md).
 
 ## Supported Azure Services
 
 - [Resource Group](/docs/services/resourcegroup/resourcegroup.md)
-- [EventHub](/docs/services/eventhub/eventhub.md)
+- [Event Hubs](/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)
+- [Azure Key Vault](/docs/services/keyvault/keyvault.md)
+- [Azure Cache for Redis](/docs/services/rediscache/rediscache.md)
 - [Storage Account](/docs/services/storage/storageaccount.md)
-- [Blob container](/docs/services/storage/blobcontainer.md)
+- [Blob Storage](/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)
@@ -39,9 +39,9 @@ For more details on the control flow of the Azure Service operator, refer to [Az
 
 ![Deploying ASO](/docs/images/asodeploy.gif)
 
-Do you want to quickly deploy the latest version of Azure Service Operator on your Kubernetes cluster and start exploring? Follow these steps.
+Ready to quickly deploy the latest version of Azure Service Operator on your Kubernetes cluster and start exploring? Follow these steps.
 
-1. Make sure `kubectl` is configured to connect to the Kubernetes cluster you want to deploy Azure Service Operators to.
+1. Make sure `kubectl` is configured to connect to the Kubernetes cluster you want to deploy Azure Service Operator to.
 
     To connect to an Azure Kubernetes Service cluster, you can use the below command:
 
@@ -63,7 +63,7 @@ Do you want to quickly deploy the latest version of Azure Service Operator on yo
     kubectl rollout status -n cert-manager deploy/cert-manager-webhook
     ```
 
-3. Download the latest Helm chart for Azure Service Operators locally to your machine. Run the following commands.
+3. Download the latest Helm chart for Azure Service Operator locally to your machine. Run the following commands.
 
     ```console
     mkdir install-aso

docs/design/controlflow.md

@@ -1,47 +1,41 @@
-## Deploying the operator - How it works
+## Deploying the operator - how it works
 
-![](/docs/images/DeployFlow.png)
+![](/docs/images/Deploy%20Flow.png)
 
 1. The user provisions the Managed Identity (or service principal) in their environment for the Azure Service Operator to use.
+2. The user then deploys cert-manager for the Azure Service Operator to use when deployed.
 
-2. The user then uses the Helm chart to deploy the operator.
+3. The user then uses the Helm chart to deploy the operator. This includes the controller pod and the manager pod, created from images stored in the public Microsoft Container Registry. The Helm chart also deploys dependencies like [aad-pod-identity](https://github.com/Azure/aad-pod-identity) in addition to the Azure Service Operator. This deployment also configures the needed Kubernetes RBAC rules.
 
-3. The Helm chart uses the images from the public Container Registry.
 
-4. It deploys dependencies like [aad-pod-identity](https://github.com/Azure/aad-pod-identity) in addition to the Azure Service Operator.
+## Resource provisioning - how it works
 
-5. This deployment takes care of deploying the operator while also configuring the needed Kubernetes RBAC rules.
+![](/docs/images/ASO%20flow.png)
 
-6. Due to ordering of deployment, currently, cert-manager needs to be deployed manually before using the Helm chart to deploy the Operator.
+1. The user deploys an application that includes the custom resource manifest for installing a Azure service that the app depends on.
 
-## Resource provisioning - How it works
+2. The application is deployed using its manifest. However, the deployment does not yet succeed as it waits on the Azure service to be successfully created. The application references a secret that provides the information required to consume the Azure service, and the secret does not exist yet.
 
-![](/docs/images/ProvisionFlow.png)
+3. The Azure Service Operator continously watches the custom resource definitions (CRDs) corresponding to the Azure services and recognizes the request for a custom resource.
 
-1. The developer deploys an application that includes the manifest for installing a Azure service that the app depends on.
+4. The Azure Service Operator then updates the Kubernetes instance for the requested resource with the correct status and events.
 
-2. The application is deployed using its manifest, however the deployment does not succeed yet as it is waiting for the Azure Service that it depends on. The application references a secret that provides the information required to consume the Azure service, and the secret does not exist yet.
+5. The Azure Service Operator requests an authorizer from Azure Active Directory for the Azure resource management endpoint, as the identity it is running as and receives an authorizer token.
 
-3. The Azure Service Operator that watches the custom resource definitions (CRDs) corresponding to the Azure services recognizes the request for a custom resource.
-
-4. The Azure Service Operator updates the Kubernetes instance for the requested resource with the correct Status and events.
-
-5. The Azure Service Operator requests an authorizer from Azure Active Directory for the Azure resource management endpoint, as the identity it is running as.
-
-6. The Azure Service Operator then sends the provisioning request to Azure API, along with the authorizer in the request.
+6. The Azure Service Operator then sends the provisioning request to Azure API, along with the authorizer token in the request.
 
 7. Azure API provisions/deprovisions the resource and returns the Resource object to the Service Operator.
 
-8. The Azure Service Operator retrieves the information required to access/consume the Azure resource from the Resource objecrt and stores it in a Kubernetes secret or as a secret in a specified Azure KeyVault.
+8. The Azure Service Operator retrieves the information required to access/consume the Azure resource from the Resource object and stores it in a Kubernetes secret, or as a secret in a pre-specified Azure KeyVault.
 
 9. The app is deployed successfully now that the Azure service it depends on is provisioned, and the secret it references exists.
 
 ## Security considerations
 
 1. The Azure Service Operator requests the authorizer from AAD for every provision/deprovision request. There is no caching of security tokens.
 
-2. Running the Azure Service Operator under a Managed Identity is recommended for security reasons. There is support to use Service Principals if needed, but not recommended.
+2. Running the Azure Service Operator under a Managed Identity is recommended for security reasons. Azure Service Operator can also be run using service principals, but this is not recommended.
 
-3. It is recommended to use Azure KeyVault to store connection information, keys that are an output of the provisioning process. There is support to store as Kubernetes secrets but not recommended.
+3. It is recommended to use Azure KeyVault to store connection information, AKA keys that are an output of the provisioning process. These connection strings can be stored as Kubernetes secrets, but this is not recommended.
 
 4. There is no implicit deletion of resources. Resources will be deprovisioned/deleted only on an explicit delete operation.

docs/faq.md

@@ -1,15 +1,15 @@
 # Azure Service Operator FAQ
 
-This page provides help with the most common questions about Azure Service Operators
+This page provides help with the most common questions about Azure Service Operators.
 
 ### 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.
+No, you can issue the creation of all resources at the same time. The operator will take care of waiting and requeuing the requests until the parent resource is ready and all resources will eventually be ready.
 
 ### 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)
+There is a [step-by-step guide](/howto/newoperatorguide.md) that walks you through this process.
 
 ### 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.
+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/services/azuresql/azuresql.md

@@ -4,7 +4,7 @@
 
 The Azure SQL operator suite consists of the following operators.
 
-1. Azure SQL server - Deploys an Azure SQL server given the location and Resource group
+1. Azure SQL server - Deploys an Azure SQL server given the location and resource group
 2. Azure SQL database - Deploys an SQL database given the SQL server
 3. Azure SQL firewall rule - Deploys a firewall rule to allow access to the SQL server from specific IPs
 4. Azure SQL VirtualNetwork rule - Deploys a VirtualNetwork rule to allow access to the SQL server from specific VNets
@@ -196,6 +196,6 @@ You can follow the steps [here](/docs/topics/resourceprovision.md) to deploy, vi
 
 ## Demo
 
-Watch this demo <https://bit.ly/2lUIX6Y> to observe how you would you use the Azure SQL Operator from a real application.
+Check out this demo <https://bit.ly/2lUIX6Y> to see how you could use the Azure SQL Operator from a real application.
 
-In this demo, we use YAML to deploy the application and the SQL server. Once the SQL server is provisioned, the connection details are stored as secrets which the application can use to access the SQL server.
+In this demo, we use YAML to deploy the application and the SQL server. Once the SQL server is provisioned, the connection details are stored as Kubernetes secrets, which the application can use to access the SQL server.

docs/services/eventhub/eventhub.md

@@ -1,18 +1,18 @@
-# Eventhub Operator
+# Event Hubs Operator
 
 ## Resources supported
 
-The Eventhub operator can be used to provision the following resources.
+The Event Hubs operator can be used to provision the following resources.
 
-1. Eventhub - Deploys an EventHub instance given the Eventhub namespace, Resource Group and Location.
+1. Event Hubs - Deploys an Event Hubs instance given the Event Hubs namespace, Resource Group and Location.
 
-2. Eventhub namespace - Deploys an EventHub namespace given the Resource Group and Location. Also has the ability to configure Sku, Properties and Network rule.
+2. Event Hubs namespace - Deploys an Event Hubs namespace given the resource group and location. Also has the ability to configure SKU, properties, and network rules.
 
-3. Consumer groups - Deploys a consumer group given the Eventhub, Eventhub namespace and Resource Group.
+3. Consumer groups - Deploys a consumer group given the event hub, Event Hubs namespace and resource group.
 
-### Eventhub - Deployment output
+### Event Hubs - Deployment output
 
-The Eventhub operator deploys an Eventhub in the specified namespace according to the Spec.
+The Event Hubs operator deploys an event hub in the specified namespace according to the spec.
 
 As an output of deployment, the operator stores a JSON formatted secret with the following fields. For more details on where the secrets are stored, look [here](/docs/secrets.md)
 
@@ -28,6 +28,6 @@ As an output of deployment, the operator stores a JSON formatted secret with the
 
 You can follow the steps [here](/docs/topics/resourceprovision.md) to deploy, view and delete resources.
 
-## How would you use the Eventhub Operator from a real application
+<!-- ## How would you use the Event Hubs Operator to support a real application?
 
-TODO: Demo app
+TODO: Demo app -->

docs/services/storage/storageaccount.md

@@ -10,8 +10,8 @@ The spec is comprised of the following fields:
 
 * Location
 * ResourceGroup
-* Sku
-    * Name
+* SKU
+* Name
 * Kind
 * AccessTier
 * SupportsHttpsTrafficOnly