Add Azure generated secrets section in user docs
@@ -118,10 +118,51 @@ type NetworkSecurityGroup struct {
Look over the `Spec` and `Status` types and their properties (and the properties of their properties and so-on).
The Azure REST API specs and ARM template JSON schemas which these types were derived from are not perfect. Sometimes they mark a `readonly` property as mutable or have another error or mistake.
-If you do identify properties which should be removed or changed, you can make customizations to the resource in the `typeTransformers` section of the code generation config. The most common issues have their own sections:
+### Common issues
+This is a non-exhaustive list of common issues which may need to be fixed in our configuration file.
-1. `# Deal with readonly properties that were not properly pruned in the JSON schema`
-2. `# Deal with properties that should have been marked readOnly but weren't`
+#### Properties that should have been marked read-only but weren't
+
+There is a section in the config detailing a number of these errors which have been fixed. Look for "Deal with properties that should have been marked readOnly but weren't".
+
+Here's an example, where DocumentDB missed setting the `provisioningState` property to read-only. We override it in the config:
+```yaml
+ - group: documentdb
+ name: Location # This type is subsequently flattened into NamespacesTopics_Spec
+ property: ProvisioningState
+ remove: true
+ because: This property should have been marked readonly but wasn't.
+```
+
+## Determine if the resource has secrets generated by Azure
+
+Some resources, such as `microsoft.storage/accounts` and `microsoft.documentdb/databaseAccounts`, have keys and endpoints generated by
+Azure. Unfortunately, there is no good way to automatically detect these in the specs which the code generator runs on.
+
+**You must manually identify if the resource you are adding has keys (or endpoints) which users will want exported to a secret store**.
+If the resource in question _does_ have Azure generated secrets or endpoints, identify those endpoints in the configuration file
+by specifying `$azureGeneratedSecrets`.
+
+Our example resource above does not have any Azure generated secrets. As mentioned above, `microsoft.documentdb/databaseAccounts` has
+Azure generated secrets. Here is the snippet from the configuration file showing how they were configured.
+```yaml
+ documentdb:
+ 2021-05-15:
+ DatabaseAccount:
+ $export: true
+ $azureGeneratedSecrets:
+ - PrimaryMasterKey
+ - SecondaryMasterKey
+ - PrimaryReadonlyMasterKey
+ - SecondaryReadonlyMasterKey
+ - DocumentEndpoint
+```
+
+Since these properties are manually configured, they must also be retrieved from Azure manually. This can be done using
+the extension framework supported by the operator. Use the [documentdb secrets extension](https://github.com/Azure/azure-service-operator/blob/main/v2/api/documentdb/customizations/database_account_extensions.go)
+as a template for authoring an extension for your resource.
+
+<!-- TODO: Do we have a link to give more details about extensions and how they work? -->
## Write a CRUD test for the resource
The best way to do this is to start from an [existing test](https://github.com/Azure/azure-service-operator/blob/main/v2/internal/controllers/crd_cosmosdb_mongodb_test.go) and modify it to work for your resource. It can also be helpful to refer to examples in the [ARM templates GitHub repo](https://github.com/Azure/azure-quickstart-templates).
