Improve documentation (#4202)

- Add AKS installation best practices, fixes #3828.
- Add problem diagnostics for Argo Helm installation issues, fixes
  #4184.
- Add FAQ entry around data output from one resource being input to the
  next.

docs/hugo/content/_index.md

@@ -105,7 +105,11 @@ recommended on AKS Free-tier clusters.
 See [CRD management](https://azure.github.io/azure-service-operator/guide/crd-management/) for more details.
 {{% /alert %}}
 
-   Alternatively you can install from the [release YAML directly](https://azure.github.io/azure-service-operator/guide/installing-from-yaml/).
+{{% alert title="Note" %}}
+When installing ASO in an AKS cluster, see [AKS Best Practices]({{< relref "best-practices#aks-best-practices" >}}).
+{{% /alert %}}
+
+Alternatively you can install from the [release YAML directly](https://azure.github.io/azure-service-operator/guide/installing-from-yaml/).
 
 #### Create a Managed Identity or Service Principal
 

docs/hugo/content/guide/best-practices/_index.md

@@ -54,3 +54,27 @@ has an `aso-credential` with permissions to manage the environment in question.
 A variant on this is **namespace per developer**, where each developer gets their own `dev-alice` or `dev-bob` namespace,
 rather than the whole team sharing a single `dev` namespace. Each `dev` namespace can point to a separate dev
 subscription or share the same dev subscription. 
+
+## AKS Best Practices
+
+### CRDPattern
+
+As described in the [CRD Management]({{< relref "crd-management" >}}) section, avoid installing a large number of CRDs 
+into a Free tier AKS cluster.
+
+### Affinity
+
+If ASO is critical to your cluster/service operation, consider forcing the ASO pods to the `System` node pool which can
+often be less CPU/memory loaded than the `User` pools. This can be done with the following modification to the Helm
+`values.yaml` prior to installation:
+```yaml
+affinity:
+  nodeAffinity:
+    requiredDuringSchedulingIgnoredDuringExecution:
+      nodeSelectorTerms:
+        - matchExpressions:
+          - key: kubernetes.azure.com/mode
+            operator: In
+            values:
+              - system
+```

docs/hugo/content/guide/diagnosing-problems.md

@@ -26,6 +26,40 @@ Events:
   ...
 ```
 
+### Helm installation via Argo missing ClusterRole and other resources
+
+See reference issue [#4184](https://github.com/Azure/azure-service-operator/issues/4184).
+
+When using Argo to install the ASO Helm chart, make sure to specify the `raw` GitHub URL to the chart, rather than
+the URL to the ASO git repo. The chart `.tgz` file contains what you need to install ASO, not everything is in the
+[v2/charts/azure-service-operator](https://github.com/Azure/azure-service-operator/tree/main/v2/charts/azure-service-operator) 
+folder. In particular, some files are autogenerated as part of the build and aren't checked in, attempting to install
+from the checked in templates will miss these autogenerated files.
+
+Correct:
+
+```
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+spec:
+  source:
+    repoURL: https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts
+    targetRevision: v2.8.0
+    chart: azure-service-operator
+```
+
+Incorrect:
+
+```
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+spec:
+  source:
+    repoURL: https://github.com/Azure/azure-service-operator.git
+    targetRevision: v2.8.0
+    path: v2/charts/azure-service-operator
+```
+
 ## Problems with resources
 
 ### Resource with no Ready condition set

docs/hugo/content/guide/frequently-asked-questions.md

@@ -172,6 +172,31 @@ env:
         name: identity-details
 ```
 
+### How can I feed the output of one resource into a parameter for the next?
+
+The answer changes a bit depending on the nature of the parameter.
+
+For resource ownership: Set the `spec.owner.name` field of the dependent resource to be "owned by" the owning resource.
+This will inform ASO that the owning resource needs to be deployed first.
+
+For cross-resource-relationships: A resource referring to another resource will have a field like 
+[diskEncryptionSetReference](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231001/#containerservice.azure.com/v1api20231001.ManagedCluster_Spec).
+Set the reference to point to the resource you want:
+```yaml
+diskEncryptionSetReference:
+  group: compute.azure.com
+  kind: DiskEncryptionSet
+  name: my-disk-encryption-set
+```
+
+For other fields: Not every field can be exported/imported. ASO does not have general purpose DAG support, nor does it have a
+general-purpose templating language to describe such relationships. Instead, important properties can be imported/exported
+from `ConfigMaps` or `Secrets`. See [setting UMI details on pods](#when-using-workload-identity-how-can-i-easily-inject-the-aso-created-user-managed-identity-details-onto-the-service-account)
+above for one example of this. Another example can be found in 
+[the authorization samples](https://github.com/Azure/azure-service-operator/blob/fe248787385af1b7b813e7bc2c8dbc595b8b4006/v2/samples/authorization/v1api20220401/v1api20220401_roleassignment.yaml#L12-L15), 
+which reads the `principalId` from the `ConfigMap` written by 
+[the associated identity](https://github.com/Azure/azure-service-operator/blob/main/v2/samples/authorization/v1api20220401/refs/v1api20181130_userassignedidentity.yaml).
+
 ### What should I know about RoleAssignment naming in ASO?
 
 The `RoleAssignment` resource is required to have a name in Azure which is a UUID. Since it's difficult to make a 

v2/charts/azure-service-operator/values.yaml

@@ -164,6 +164,7 @@ tolerations: []
 # Node affinity functions like the nodeSelector field but is more expressive and allows you to specify soft rules.
 # Inter-pod affinity/anti-affinity allows you to constrain Pods against labels on other Pods.
 # For more information, see https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
+# For specific affinity best practices on AKS clusters, see https://azure.github.io/azure-service-operator/guide/best-practices/#affinity
 affinity: {}
 
 # MaxConcurrentReconciles is the number of threads/goroutines dedicated to reconciling each resource type.