Skip to content

Commit

Permalink
Update documentation to be more clear about authentication mode
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@matthchr
matthchr committed May 14, 2024
1 parent 96a5948 commit 14f3a17
Show file tree
Hide file tree
Showing 6 changed files with 99 additions and 85 deletions.
36 changes: 27 additions & 9 deletions docs/hugo/content/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 /%}}
Expand Down Expand Up @@ -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 /%}}
Expand Down Expand Up @@ -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 /%}}
Expand Down Expand Up @@ -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.
Expand Down
88 changes: 52 additions & 36 deletions docs/hugo/content/contributing/create-a-new-release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/hugo/content/contributing/developer-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 4 additions & 6 deletions docs/hugo/content/contributing/running-a-development-version.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
31 changes: 5 additions & 26 deletions docs/hugo/content/contributing/testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down
17 changes: 10 additions & 7 deletions docs/hugo/content/guide/installing-from-yaml.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.

0 comments on commit 14f3a17

Please sign in to comment.