diff --git a/docs/hugo/content/_index.md b/docs/hugo/content/_index.md index 90f4f7d0f54..729b21796ef 100644 --- a/docs/hugo/content/_index.md +++ b/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 diff --git a/docs/hugo/content/guide/best-practices/_index.md b/docs/hugo/content/guide/best-practices/_index.md index be16466957e..0591836f198 100644 --- a/docs/hugo/content/guide/best-practices/_index.md +++ b/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 +``` diff --git a/docs/hugo/content/guide/diagnosing-problems.md b/docs/hugo/content/guide/diagnosing-problems.md index 1d73c129780..87aa453f50f 100644 --- a/docs/hugo/content/guide/diagnosing-problems.md +++ b/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 diff --git a/docs/hugo/content/guide/frequently-asked-questions.md b/docs/hugo/content/guide/frequently-asked-questions.md index 85fd06e4dc1..e05c5f3be36 100644 --- a/docs/hugo/content/guide/frequently-asked-questions.md +++ b/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 diff --git a/v2/charts/azure-service-operator/values.yaml b/v2/charts/azure-service-operator/values.yaml index 92c862b32ed..9d3c6648988 100644 --- a/v2/charts/azure-service-operator/values.yaml +++ b/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.