Merge branch 'main' into feature/4053

ROADMAP.md

@@ -10,15 +10,15 @@ Our current release plan:
 
 | Version                                                                | Estimated Release |
 |------------------------------------------------------------------------|------------------:|
-| [2.11.0](https://github.com/Azure/azure-service-operator/milestone/30) | Mid November 2024 |
-| [2.12.0](https://github.com/Azure/azure-service-operator/milestone/31) | Mid February 2025 |
 | [2.13.0](https://github.com/Azure/azure-service-operator/milestone/32) |    Mid April 2025 |
+| [2.14.0](https://github.com/Azure/azure-service-operator/milestone/33) |     Mid June 2025 |
+| [2.15.0](https://github.com/Azure/azure-service-operator/milestone/34) |   Mid August 2025 |
 
 Where linked, versions go to a list of feature and bugs that are planned to be included in that release.
 
 Any items note completed in time for one release will be carried over to the next, and may result in us pushing other items to a later release.
 
-Partway through eacha release cycle, we'll review the list of issues assigned to upcoming releases and redistribute issues as needed. This usually involves some issues being moved to later releases.
+Partway through each release cycle, we'll review the list of issues assigned to upcoming releases and redistribute issues as needed. This usually involves some issues being moved to later releases.
 
 If you're waiting on a particular resource or feature to be released, please comment on the relevant issue (or create a new issue if there isn't already one tracking the request) to let us know. We'll do our best to keep you updated on progress.
 
@@ -32,6 +32,8 @@ Prior GA releases of ASO v2:
 
 | Version                                                                        |     Release Date |     |
 |--------------------------------------------------------------------------------|-----------------:|-----|
+| [2.12.0](https://github.com/Azure/azure-service-operator/milestone/v2.12.0)    | 11 February 2025 |     |
+| [2.11.0](https://github.com/Azure/azure-service-operator/milestone/v2.11.0)    | 12 November 2024 |     |
 | [2.10.0](https://github.com/Azure/azure-service-operator/releases/tag/v2.10.0) |  22 October 2024 |     |
 | [2.9.0](https://github.com/Azure/azure-service-operator/releases/tag/v2.9.0)   |   22 August 2024 |     |
 | [2.8.0](https://github.com/Azure/azure-service-operator/releases/tag/v2.8.0)   |     25 June 2024 |     |

Taskfile.yml

@@ -550,7 +550,7 @@ tasks:
     vars:
       VERBOSE:
         sh: if [ $TEST_FILTER ];  then echo "-v"; fi
-      TIMEOUT: '{{default "20m" .TIMEOUT}}'
+      TIMEOUT: '{{default "20m" .TIMEOUT}}'  # Should be kept in sync with the -cover variant below
 
   # This target is intended for local use only
   controller:test-integration-envtest-record:
@@ -588,9 +588,11 @@ tasks:
             INPUT_FILE: '{{.TEST_OUT}}/controller-integration-genericarmclient-tests.json'
             OUTPUT_FILE: '{{.TEST_OUT}}/controller-integration-genericarmclient-tests.md'
       # -race fails at the moment in controller-runtime
-      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-envtest.out' -coverpkg="./..." -json -timeout 15m -run '{{default ".*" .TEST_FILTER}}' ./internal/controllers > '{{.TEST_OUT}}/controller-integration-tests.json'
-      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-genruntime-envtest.out' -coverpkg="./..." -json -timeout 15m -run '{{default ".*" .TEST_FILTER}}' ./pkg/genruntime/test > '{{.TEST_OUT}}/controller-integration-genruntime-tests.json'
-      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-genericarmclient-envtest.out' -coverpkg="./..." -json -timeout 15m -run '{{default ".*" .TEST_FILTER}}' ./internal/genericarmclient > '{{.TEST_OUT}}/controller-integration-genericarmclient-tests.json'
+      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-envtest.out' -coverpkg="./..." -json -timeout {{.TIMEOUT}} -run '{{default ".*" .TEST_FILTER}}' ./internal/controllers > '{{.TEST_OUT}}/controller-integration-tests.json'
+      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-genruntime-envtest.out' -coverpkg="./..." -json -timeout {{.TIMEOUT}} -run '{{default ".*" .TEST_FILTER}}' ./pkg/genruntime/test > '{{.TEST_OUT}}/controller-integration-genruntime-tests.json'
+      - go test -covermode atomic -coverprofile='{{.TEST_OUT}}/coverage-integration-genericarmclient-envtest.out' -coverpkg="./..." -json -timeout {{.TIMEOUT}} -run '{{default ".*" .TEST_FILTER}}' ./internal/genericarmclient > '{{.TEST_OUT}}/controller-integration-genericarmclient-tests.json'
+    vars:
+      TIMEOUT: '20m'  # Should be kept in sync with the non-cover variant above
 
   controller:test-integration-envtest-live:
     desc: Run integration tests with envtest against live data and output coverage.

docs/hugo/.htmltest.yml

@@ -12,11 +12,14 @@ IgnoreURLs:
   - /js/
   - index.xml
   - example.com
-  - "https://stackoverflow.com/questions/53866196/how-best-to-say-a-value-is-required-in-a-helm-chart" # Returns 403, even though valid
-  - "https://stackoverflow.com/questions/55503893/helm-patch-default-service-account" # Returns 403, even though valid
-  - "https://armwiki.azurewebsites.net/api_contracts/guidelines/templatedeployment.html" # Returns 404 even though valid
-  - "https://marketplace.visualstudio.com/items" # Marketplace links return 401 even if valid
-  - "https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md" # Manually checked, not a 404
-  - "https://code.visualstudio.com/docs/devcontainers/containers" # Returns 403 even though valid
-  - "azure-workload-identity" # TODO: Work out why this fails
+  - "https://armwiki.azurewebsites.net/api_contracts/guidelines/templatedeployment.html" # Returns 404 even though valid. Checked 2025-02-14
+  - "https://marketplace.visualstudio.com/items" # Marketplace links return 401 because htmltest strips the itemName parameter. All checked 2025-02-14
+  - "https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md" # Not a 404. Checked 2025-02-14
+  - "/azure-workload-identity/docs/topics/service-account-labels-and-annotations.html#service-account" # Actually starts with 'https://azure.github.io' but gets treated as internal link, which fails. Checked 2025-02-14
+  - "/azure-workload-identity/docs/installation/mutating-admission-webhook.html" # Actually starts with 'https://azure.github.io' but gets treated as internal link, which fails. Checked 2025-02-14
+  - "https://slack.k8s.io/" # Causing timeouts as of 2025-02-14
+  # These suppressions no longer seem to be required, but keeping them here for easy reinstatement if required
+  #  - "https://code.visualstudio.com/docs/devcontainers/containers" # Returns 403 even though valid. Checked 2025-02-14
+  #  - "https://stackoverflow.com/questions/55503893/helm-patch-default-service-account" # Returns 403, even though valid. Checked 2025-02-14
+  #  - "https://stackoverflow.com/questions/53866196/how-best-to-say-a-value-is-required-in-a-helm-chart" # Returns 403, even though valid. Checked 2025-02-14
 LogLevel: 3

docs/hugo/content/_index.md

@@ -37,7 +37,7 @@ If you've got a question, a problem, a request, or just want to chat, here are t
 1. A Kubernetes cluster (at least version 1.16) [created and running](https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/). You can check your cluster version with `kubectl version`. If you want to try it out quickly, spin up a local cluster using [Kind](https://kind.sigs.k8s.io).
 2. An Azure Subscription to provision resources into.
 3. An Azure Service Principal for the operator to use, or the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest) to create one. How to create a Service Principal is covered in [installation](#installation).
-   See the [Azure Workload Identity](https://azure.github.io/azure-service-operator/guide/authentication/credential-format/#azure-workload-identity) setup for how to use managed identity instead. We recommend using workload identity in production.
+   See the [Azure Workload Identity]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) setup for how to use managed identity instead. We recommend using workload identity in production.
 
 ### Installation
 
@@ -118,7 +118,7 @@ You'll need this to grant the identity or Service Principal permissions to creat
 
 {{% alert title="Note" %}}
 We show steps for using a Service Principal below, as it's easiest to get started with, but recommend using a 
-Managed Identity with [Azure Workload Identity]( {{< relref "credential-format#azure-workload-identity" >}} ) for
+Managed Identity with [Azure Workload Identity]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) for
 use-cases other than testing.
 
 See [Security best practices]({{< relref "security" >}}) for the full list of security best practices.

docs/hugo/content/guide/aso-controller-settings-options.md

@@ -23,6 +23,8 @@ credential is specified at the per-resource or per-namespace scope.
 
 **Required**: True
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 This may be set to empty string to configure no global credential.
 
 ### AZURE_TENANT_ID
@@ -37,6 +39,8 @@ credential is specified at the per-resource or per-namespace scope.
 
 **Required**: True
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 This may be set to empty string to configure no global credential.
 
 ### AZURE_CLIENT_ID
@@ -51,6 +55,8 @@ credential is specified at the per-resource or per-namespace scope.
 
 **Required**: True
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 This may be set to empty string to configure no global credential.
 
 ### AZURE_CLIENT_SECRET
@@ -63,6 +69,8 @@ credential is specified at the per-resource or per-namespace scope.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 ### AZURE_CLIENT_CERTIFICATE
 
 AzureClientCertificate is a PEM or PKCS12 certificate string including the private key for 
@@ -73,6 +81,8 @@ If the certificate is password protected,  use `AZURE_CLIENT_CERTIFICATE_PASSWOR
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 ### AZURE_CLIENT_CERTIFICATE_PASSWORD
 
 The password used to protect the `AZURE_CLIENT_CERTIFICATE`.
@@ -81,6 +91,8 @@ The password used to protect the `AZURE_CLIENT_CERTIFICATE`.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 ### AZURE_SYNC_PERIOD
 
 AZURE_SYNC_PERIOD is the frequency at which resources are re-reconciled with Azure when
@@ -97,6 +109,8 @@ Specify the special value `"never"` to stop syncing.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### AZURE_OPERATOR_MODE
 
 AZURE_OPERATOR_MODE determines whether the operator should run _watchers_, _webhooks_ or _both_ (default). An empty string, or any unrecognized value, means _both_.
@@ -107,6 +121,8 @@ AZURE_OPERATOR_MODE determines whether the operator should run _watchers_, _webh
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### AZURE_TARGET_NAMESPACES
 
 AZURE_TARGET_NAMESPACES lists the namespaces the operator will watch for Azure resources (if the mode includes running watchers). 
@@ -120,6 +136,8 @@ Spaces after `,`'s and at the start and end of the string are ignored.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### USE_WORKLOAD_IDENTITY_AUTH
 
 USE_WORKLOAD_IDENTITY_AUTH boolean is used to determine if we're using Workload Identity authentication for global credential.
@@ -130,6 +148,8 @@ USE_WORKLOAD_IDENTITY_AUTH boolean is used to determine if we're using Workload
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### AZURE_AUTHORITY_HOST
 
 AZURE_AUTHORITY_HOST is the URL of the AAD authority. If not specified, the default is the AAD URL for the public cloud: `https://login.microsoftonline.com/`. 
@@ -141,6 +161,8 @@ See https://docs.microsoft.com/azure/active-directory/develop/authentication-nat
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### AZURE_RESOURCE_MANAGER_ENDPOINT
 
 AZURE_RESOURCE_MANAGER_ENDPOINT is the Azure Resource Manager endpoint. If not specified, the default is the Public cloud resource manager endpoint.
@@ -153,6 +175,8 @@ Note that the resource manager endpoint is referred to as "resourceManager" in t
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### AZURE_RESOURCE_MANAGER_AUDIENCE
 
 AZURE_RESOURCE_MANAGER_AUDIENCE is the Azure Resource Manager AAD audience. If not specified, the default is the Public cloud resource manager audience `https://management.core.windows.net/`.
@@ -165,6 +189,22 @@ Note that the resource manager audience is referred to as "activeDirectoryResour
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
+### AZURE_ADDITIONAL_TENANTS
+
+The list of (comma-separated) additional tenants the operator can authenticate with.
+This is required when performing cross-tenant authentication. See the
+[Entra documentation](https://learn.microsoft.com/entra/external-id/cross-tenant-access-overview) for more details.
+
+**Format:** `string` (comma-separated tenant GUIDs - spaces are allowed)
+
+**Example:** `00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002`
+
+**Required**: False
+
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global, namespace, or per-resource
+
 ### AZURE_USER_AGENT_SUFFIX
 
 AZURE_USER_AGENT_SUFFIX is appended to the default User-Agent for Azure HTTP clients.
@@ -175,6 +215,8 @@ AZURE_USER_AGENT_SUFFIX is appended to the default User-Agent for Azure HTTP cli
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### MAX_CONCURRENT_RECONCILES
 
 MAX_CONCURRENT_RECONCILES is the number of threads/goroutines dedicated to reconciling each resource type.
@@ -196,6 +238,8 @@ MAX_CONCURRENT_RECONCILES applies to every registered resource type being watche
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### RATE_LIMIT_MODE
 
 RateLimitMode configures the internal rate-limiting mode.
@@ -223,6 +267,8 @@ RateLimitMode configures the internal rate-limiting mode.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### RATE_LIMIT_QPS
 
 RATE_LIMIT_QPS is the rate (per second) that the bucket is refilled. 
@@ -234,6 +280,8 @@ This value only has an effect if RATE_LIMIT_MODE is 'bucket'.
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### RATE_LIMIT_BUCKET_SIZE
 
 RATE_LIMIT_BUCKET_SIZE is the size of the bucket. This value only has an effect if RATE_LIMIT_MODE is 'bucket'.
@@ -244,6 +292,8 @@ RATE_LIMIT_BUCKET_SIZE is the size of the bucket. This value only has an effect
 
 **Required**: False
 
+**[Allowed scopes]( {{< relref "authentication#credential-scope" >}} )**: Global
+
 ### DEFAULT_RECONCILE_POLICY
 
 DEFAULT_RECONCILE_POLICY specify which reconcile strategy to be used by the operator. If not specified, it is set to 'manage'.

docs/hugo/content/guide/authentication/_index.md

@@ -14,7 +14,7 @@ There are two key topics surrounding authentication in Azure Service Operator: T
 
 Azure Service Operator supports four different styles of authentication today.
 
-1. [Recommended for production] [Azure-Workload-Identity authentication]( {{< relref "credential-format#azure-workload-identity" >}} ) (OIDC + Managed Identity or Service Principal)
+1. [Recommended for production] [Azure Workload Identity]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) (OIDC + Managed Identity or Service Principal)
 2. [Service Principal using a Client Secret]( {{< relref "credential-format#service-principal-using-a-client-secret" >}} )
 3. [Service Principal using a Client Certificate]( {{< relref "credential-format#service-principal-using-a-client-certificate" >}} )
 4. [Deprecated] [aad-pod-identity authentication (Managed Identity)]( {{< relref "credential-format#deprecated-managed-identity-aad-pod-identity" >}} )

docs/hugo/content/guide/authentication/credential-format.md

@@ -8,6 +8,20 @@ Azure Service Operator supports four different styles of authentication today.
 Each section below dives into one of these authentication options, including examples for how to set it up and
 use it at the different [credential scopes]( {{< relref "credential-scope" >}} ).
 
+## Allowed credential fields
+
+These fields are common across all [credential scopes]( {{< relref "credential-scope" >}} ).
+
+- [AZURE_SUBSCRIPTION_ID]( {{< relref "aso-controller-settings-options" >}}/#azure_subscription_id)
+- [AZURE_TENANT_ID]( {{< relref "aso-controller-settings-options" >}}/#azure_tenant_id)
+- [AZURE_CLIENT_ID]( {{< relref "aso-controller-settings-options" >}}/#azure_client_id)
+- [AZURE_CLIENT_SECRET]( {{< relref "aso-controller-settings-options" >}}/#azure_client_secret)
+- [AZURE_CLIENT_CERTIFICATE]( {{< relref "aso-controller-settings-options" >}}/#azure_client_certificate)
+- [AZURE_CLIENT_CERTIFICATE_PASSWORD]( {{< relref "aso-controller-settings-options" >}}/#azure_client_certificate_password)
+- [AZURE_ADDITIONAL_TENANTS]( {{< relref "aso-controller-settings-options" >}}/#azure_additional_tenants)
+
+Note that the global credential scope has fields that can be set in addition to the fields documented above.
+
 ## Managed Identity (via workload identity)
 
 See [Azure Workload Identity](https://github.com/Azure/azure-workload-identity) for details about the workload identity project.

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

@@ -22,7 +22,7 @@ We recommend making use of all 3 of these levers to fully secure a cluster runni
 
 ### General guidance
 
-✅ DO use [Azure Workload Identity]( {{< relref "credential-format#azure-workload-identity" >}} ) for all
+✅ DO use [Azure Workload Identity]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) for all
 credentials. Other supported identity types are called out
 [in the authentication documentation]( {{< relref "authentication#credential-type" >}} ).