Update documentation to be more clear about authentication mode

Be explicit about which mode we're using in the various installation
instructions, and provide links to the detailed authentication
documentation so that users are more easily exposed to other
authentication options (formats and scopes).

Also update devcontainer raw cmdline to map azcli token into container
to reduce number of required az logins

docs/hugo/content/_index.md

@@ -34,7 +34,9 @@ ASO supports more than 150 different Azure resources, with more added every rele
 
 ### Installation
 
-1. Install [cert-manager](https://cert-manager.io/docs/installation/kubernetes/) on the cluster using the following command.
+#### Install cert-manager on the cluster
+
+See [cert-manager](https://cert-manager.io/docs/installation/kubernetes/) if you'd like to learn more about the project.
 
 ``` bash
 $ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.14.1/cert-manager.yaml
@@ -52,7 +54,9 @@ cert-manager-webhook-c4b5687dc-x66bj      1/1     Running   0          1m
 
 (Alternatively, you can wait for cert-manager to be ready with `cmctl check api --wait=2m` - see the [cert-manager documentation](https://cert-manager.io/docs/usage/cmctl/) for more information about `cmctl`.)
 
-2. Install [the latest **v2+** Helm chart](https://github.com/Azure/azure-service-operator/tree/main/v2/charts):
+#### Install the latest **v2+** Helm chart
+
+The latest v2+ Helm chart can be found [here](https://github.com/Azure/azure-service-operator/tree/main/v2/charts)
 
 {{< tabpane text=true left=true >}}
 {{% tab header="**Shell**:" disabled=true /%}}
@@ -96,10 +100,20 @@ See [CRD management](https://azure.github.io/azure-service-operator/guide/crd-ma
 
    Alternatively you can install from the [release YAML directly](https://azure.github.io/azure-service-operator/guide/installing-from-yaml/).
 
-3. Create an Azure Service Principal. You'll need this to grant Azure Service Operator permissions to create resources 
-   in your subscription.
+#### Create a Managed Identity or Service Principal
+
+This identity or service principal will be used by ASO to authenticate with Azure.
+You'll need this to grant the identity or Service Principal permissions to create resources in your subscription.
+
+{{% 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
+use-cases other than testing.
+
+See [Security best practices]({{< relref "security" >}}) for the full list of security best practices.
+{{% /alert %}}
 
-   First, set the following environment variables to your Azure Tenant ID and Subscription ID with your values:
+First, set the following environment variables to your Azure Tenant ID and Subscription ID with your values:
 
 {{< tabpane text=true left=true >}}
 {{% tab header="**Shell**:" disabled=true /%}}
@@ -189,7 +203,14 @@ C:\> SET AZURE_CLIENT_SECRET=<your-client-secret>
 {{% /tab %}}
 {{< /tabpane >}}
 
-Then create a secret named `aso-credential` in the namespace you'd like to create ASO resources in.
+#### Create the Azure Service Operator namespaced secret
+
+The secret must be named `aso-credential` and be created in the namespace you'd like to create ASO resources in.
+
+{{% alert title="Note" %}}
+To learn about the ASO global secret, which works across all namespaces, or per-resource secrets, see
+[authentication documentation](https://azure.github.io/azure-service-operator/guide/authentication/).
+{{% /alert %}}
 
 {{< tabpane text=true left=true >}}
 {{% tab header="**Shell**:" disabled=true /%}}
@@ -250,9 +271,6 @@ Then run: `kubectl apply -f secret.yaml`
 {{% /tab %}}
 {{< /tabpane >}}
 
-To learn more about other authentication options, see the 
-[authentication documentation](https://azure.github.io/azure-service-operator/guide/authentication/).
-
 ### Usage
 
 Once the controller has been installed in your cluster, you should be able to see the ASO pod running.

docs/hugo/content/contributing/create-a-new-release.md

@@ -47,86 +47,102 @@ service Swagger specifications. We must validate each breaking change so that we
 
 Perform a simple smoke test to make sure the new release is capable of starting up and creating some Azure resources.
 
-1. Create a kind cluster
+1. Ensure you have the following environment variables exported:
+   * AZURE_SUBSCRIPTION_ID
+   * AZURE_TENANT_ID
+
+2. Create a kind cluster
    ``` bash
-   task controller:kind-create
+   task controller:kind-create-wi
+   ```
+
+3. Enable workload identity on that cluster:
+   ```
+   task: controller:create-mi-for-workload-identity
    ```
 
-2. Install cert-manager
+4. Install cert-manager
    ``` bash
    task controller:install-cert-manager
    ```
 
-3. Create the namespace for the operator
+5. Create the namespace for the operator
    ``` bash
    kubectl create namespace azureserviceoperator-system
    ```
 
-4. Ensure you have a [Service Principal](https://azure.github.io/azure-service-operator/#installation) and export these environment variables:
-
-   * AZURE_SUBSCRIPTION
-   * AZURE_TENANT_ID
-   * AZURE_CLIENT_ID
-   * AZURE_CLIENT_SECRET
-
-5. Create a secret in your cluster with the Service Principal credentials for ASO to use:
+6. Create a secret in your cluster with the Workload Identity credentials for ASO to use:
    ``` bash
-   task controller:make-sp-secret
+   task controller:make-workload-identity-secret
    ```
 
-6. Download asoctl
+7. Download asoctl
 
    ``` bash 
    curl -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-linux-amd64.gz -o asoctl.gz
    gunzip asoctl.gz
    chmod +x asoctl
    ```
 
-7. Use asoctl to install the new release
+8. Use asoctl to install the new release
 
    ``` bash
    ./asoctl export template --version v2.7.0 --crd-pattern "resources.azure.com/*;network.azure.com/*" | kubectl apply -f -
    ```
 
-8. Watch while ASO starts
+9. Watch while ASO starts
    ``` bash
    kubectl get all -n azureserviceoperator-system
    ```
 
-9. Create a resource group and a vnet in it (the vnet is to check that conversion webhooks are working, since there aren't any for RGs):
+10. Create a resource group and a vnet in it (the vnet is to check that conversion webhooks are working, since there aren't any for RGs):
 
-   ``` bash
-   kubectl apply -f v2/samples/resources/v1api/v1api20200601_resourcegroup.yaml
-   kubectl apply -f v2/samples/network/v1api20201101/v1api20201101_virtualnetwork.yaml
-   ```
-10. Make sure they deploy successfully - check in the portal as well.
+    ``` bash
+    kubectl apply -f v2/samples/resources/v1api/v1api20200601_resourcegroup.yaml
+    kubectl apply -f v2/samples/network/v1api20201101/v1api20201101_virtualnetwork.yaml
+    ```
+11. Make sure they deploy successfully - check in the portal as well.
 
 ## Create and test the Helm chart
 
-> **Note:** A PR that does this should be automatically generated when a new release is published. 
-> These steps are documented here in case that process fails.
+{{% alert title="Note" %}}
+A PR that does this should be automatically generated when a new release is published.
+These steps are documented here in case that process fails.
+{{% /alert %}}
 
 1. Create a new branch from `<NEW_RELEASE_TAG>` HEAD
 2. Generate helm manifest for new release: `task controller:gen-helm-manifest`
 3. Check the version in `/v2/charts/azure-service-operator/Chart.yaml` if matches with the latest release tag.
-4. Install helm chart:
+4. Create a kind cluster
+   ``` bash
+   task controller:kind-create-wi
+   ```
+5. Enable workload identity on that cluster:
+   ```
+   task: controller:create-mi-for-workload-identity
+   ```
+6. Install cert-manager
+   ``` bash
+   task controller:install-cert-manager
+   ```
+7. Install helm chart:
     ```
    helm install --set azureSubscriptionID=$AZURE_SUBSCRIPTION_ID \
    --set azureTenantID=$AZURE_TENANT_ID \
-   --set azureClientSecret=$AZURE_CLIENT_SECRET \
    --set azureClientID=$AZURE_CLIENT_ID \
+   --set useWorkloadIdentityAuth=true \
    asov2 -n azureserviceoperator-system --create-namespace ./v2/charts/azure-service-operator/.
     ```
-5. Wait for the chart installation.
-6. Wait for it to start: `k get all -n azureserviceoperator-system`
-7. Create a resource group and a vnet in it (the vnet is to check that conversion webhooks are working, since there aren't any for RGs):
-   ```
-   k apply -f v2/samples/resources/v1beta/v1beta20200601_resourcegroup.yaml
-   k apply -f v2/samples/network/v1beta/v1beta20201101_virtualnetwork.yaml
-   ```
-8. Make sure they deploy successfully - check in the portal as well.
-9. If installed successfully, commit the files under `v2/charts/azure-service-operator`.
-10. Send a PR.
+8. Wait for the chart installation.
+9. Wait for it to start: `k get all -n azureserviceoperator-system`
+10. Create a resource group and a vnet in it (the vnet is to check that conversion webhooks are working, since there aren't any for RGs):
+    ```
+    k apply -f v2/samples/resources/v1beta/v1beta20200601_resourcegroup.yaml
+    k apply -f v2/samples/network/v1beta/v1beta20201101_virtualnetwork.yaml
+    ```
+11. Make sure they deploy successfully - check in the portal as well.
+12. If installed successfully, commit the files under `v2/charts/azure-service-operator`.
+13. Send a PR.
 
 ## Update Resource Documentation
 

docs/hugo/content/contributing/developer-setup.md

@@ -68,7 +68,7 @@ $ docker build $(git rev-parse --show-toplevel)/.devcontainer -t asodev:latest
 … image will be created …
 
 $ # After that you can start a terminal in the development container with:
-$ docker run --env-file ~/work/envs.env --env HOSTROOT=$(git rev-parse --show-toplevel) -v $(git rev-parse --show-toplevel):/go/src -w /go/src -u $(id -u ${USER}):$(id -g ${USER}) --group-add $(stat -c '%g' /var/run/docker.sock) -v /var/run/docker.sock:/var/run/docker.sock --network=host  -it asodev:latest /bin/bash
+$ docker run --env-file ~/work/envs.env --env HOSTROOT=$(git rev-parse --show-toplevel) -v $(git rev-parse --show-toplevel):/go/src -w /go/src -u $(id -u ${USER}):$(id -g ${USER}) --group-add $(stat -c '%g' /var/run/docker.sock) -v /var/run/docker.sock:/var/run/docker.sock -v $HOME/.kube:/home/vscode/.kube -v $HOME/.azure/:/home/vscode/.azure/ --network=host  -it asodev:latest /bin/bash
 ```
 
 Note: If you mount the source like this from a Windows folder, performance will be poor as file operations between the container and Windows are very slow.

docs/hugo/content/contributing/running-a-development-version.md

@@ -7,13 +7,11 @@ title: Running a Development Version
 If you would like to try something out but do not want to write an integration test, you can run your local version of the
 operator locally in a [kind](https://kind.sigs.k8s.io) cluster.
 
-Before launching `kind`, make sure that your shell has the `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`,
-and `AZURE_CLIENT_SECRET` environment variables set. See [testing](../testing/#recordreplay) for more details about them.
+Before launching `kind`, make sure that your shell has the `AZURE_SUBSCRIPTION_ID` and `AZURE_TENANT_ID`
+environment variables set. See [testing](../testing/#recordreplay) for more details about them.
 
-Once you've set the environment variables above, run one of the following commands to create a `kind` cluster:
-
-1. Service Principal authentication cluster: `task controller:kind-create-with-service-principal`.
-2. AAD Pod Identity authentication enabled cluster (emulates Managed Identity): `controller:kind-create-with-podidentity`.
+Once you've set the environment variables above, create a `kind` cluster:
+- `task controller:kind-create-with-workload-identity`.
 
 You can use `kubectl` to interact with the local `kind` cluster.
 

docs/hugo/content/contributing/testing.md

@@ -17,10 +17,11 @@ To do this, delete the recordings for the failing tests (under `{test-dir}/recor
 include with your change. All authentication and subscription information is removed from the recording.
 
 To run the test and produce a new recording you will need to have set the required authentication environment variables 
-for an Azure Service Principal: `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`. 
-This Service Principal will need access to the subscription to create and delete resources.
+`AZURE_SUBSCRIPTION_ID` and `AZURE_TENANT_ID`, _and_ logged in via `az login` (or you just use the `task` commands 
+mentioned below and it will prompt you to `az login` if needed for that specific command). 
+Note that you must be `Owner` on the subscription to execute some tests in record mode.
 
-A few tests also need the `TEST_BILLING_ID` variable set to a valid Azure Billing ID when running in record mode. 
+A few tests also need the `TEST_BILLING_ID` environment variable set to a valid Azure Billing ID when running in record mode. 
 In replay mode this variable is never required. Note that the billing ID is redacted from all recording files so that 
 the resulting file can be replayed by anybody, even somebody who does not know the Billing ID the test was recorded with.
 
@@ -31,33 +32,11 @@ set `TIMEOUT` to a suitable value when running task. For example, to give your t
 TIMEOUT=60m task controller:test-integration-envtest
 ```
 
-If you need to create a new Azure Service Principal, run the following commands:
-
-```console
-$ az login
-… follow the instructions …
-$ az account set --subscription {the subscription ID you would like to use}
-Creating a role assignment under the scope of "/subscriptions/{subscription ID you chose}"
-…
-$ az ad sp create-for-rbac --role contributor --name {the name you would like to use}
-{
-  "appId": "…",
-  "displayName": "{name you chose}",
-  "name": "{name you chose}",
-  "password": "…",
-  "tenant": "…"
-}
-```
-The output contains `appId` (`AZURE_CLIENT_ID`), `password` (`AZURE_CLIENT_SECRET`), and `tenant` (`AZURE_TENANT_ID`). 
-Store these somewhere safe as the password cannot be viewed again, only reset. The Service Principal will be created as 
-a “contributor” to your subscription which means it can create and delete resources, so 
-**ensure you keep the secrets secure**.
-
 ### Running live tests
 
 If you want to skip all recordings and run all tests directly against live Azure resources, you can use the 
 `controller:test-integration-envtest-live` task. This will also require you to set the authentication environment 
-variables, as detailed above.
+variables and `az login`, as detailed above.
 
 ### Running a single test
 By default `task controller:test-integration-envtest` and its variants run all tests. This is often undesirable 

docs/hugo/content/guide/installing-from-yaml.md

@@ -4,8 +4,8 @@ weight: -4
 ---
 ## Prerequisites
 1. You have installed Cert Manager as per the [installation instructions](../../#installation) up to the "install from Helm" step.
-2. You have the `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET` environment variables set from the
-   [installation instructions](../../#installation).
+2. You have followed the [instructions for creating a Managed Identity or Service Principal](../../#create-a-managed-identity-or-service-principal)
+   and set the appropriate environment variables.
 
 ## Installation (operator)
 
@@ -19,9 +19,9 @@ weight: -4
    `--crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*"`. 
    For more information about what `--crd-pattern` means, see [CRD management in ASO]({{<relref "crd-management">}}).
 
-3. Create the Azure Service Operator v2 secret. This secret contains the identity that Azure Service Operator will run as. 
-   Make sure that you have the 4 environment variables from the [Helm installation instructions](../../#installation) set.
-   To learn more about other authentication options, see the [authentication documentation](../authentication/):
+3. Create the Azure Service Operator v2 global secret. This secret contains the identity that Azure Service Operator will run as. 
+   Make sure that you have the 4 environment variables from the 
+   [create a service principal step of the Helm instructions](../../#create-a-managed-identity-or-service-principal) set.
    ```bash
    cat <<EOF | kubectl apply -f -
    apiVersion: v1
@@ -37,6 +37,9 @@ weight: -4
    EOF
    ```
 
+   Note that unlike the Helm installation instructions, we use the ASO global secret here. To learn more about different
+   secret scopes and formats, see the [authentication documentation](../authentication/).
+
 ## Installation (crds)
 
 The operator manages its own CRDs by default, based on the `--crd-pattern` specified during installation.
@@ -67,5 +70,5 @@ CustomResourceDefinition.apiextensions.k8s.io "storageaccounts.storage.azure.com
 metadata.annotations: Too long: must have at most 262144 bytes
 ```
 
-Why does this happen? ASO CRDs are a complete representation of the Azure Resource surface area, including documentation. This is tremendously useful - but also means they are quite large.
-
+Why does this happen? ASO CRDs are a complete representation of the Azure Resource surface area, including documentation. 
+This is tremendously useful - but also means they are quite large.