From 83acf7c4f8162acebf0464e78e631cdb032844c0 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:09:54 -0700 Subject: [PATCH 01/11] Update _index.md Shortened the homepage, and moved some of the "Getting Started"-esque info to a separate page. --- docs/hugo/content/_index.md | 363 ------------------------------------ 1 file changed, 363 deletions(-) diff --git a/docs/hugo/content/_index.md b/docs/hugo/content/_index.md index 882b99c34dc..33864edb9c0 100644 --- a/docs/hugo/content/_index.md +++ b/docs/hugo/content/_index.md @@ -30,369 +30,6 @@ If you've got a question, a problem, a request, or just want to chat, here are t * Log an issue on our [GitHub repository](https://github.com/azure/azure-service-operator). * Join us over on the [Kubernetes Slack](https://kubernetes.slack.com) in the [#azure-service-operator](https://kubernetes.slack.com/archives/C046DEVLAQM) channel. (Don't have an account? [Sign up here](https://slack.k8s.io/).) -## Getting Started - -### Prerequisites - -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]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) setup for how to use managed identity instead. We recommend using workload identity in production. - -### Installation - -#### 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 -``` - -Check that the cert-manager pods have started successfully before continuing. - -``` bash -$ kubectl get pods -n cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-5597cff495-lmphj 1/1 Running 0 1m -cert-manager-cainjector-bd5f9c764-gvxm4 1/1 Running 0 1m -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`.) - -#### 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 /%}} -{{% tab header="bash" %}} -``` bash -$ helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts -$ helm upgrade --install aso2 aso2/azure-service-operator \ - --create-namespace \ - --namespace=azureserviceoperator-system \ - --set crdPattern='resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*' -``` -Note: **bash** requires the value for `crdPattern` to be quoted with `'` to avoid expansion of the wildcards. -{{% /tab %}} -{{% tab header="PowerShell" %}} -``` powershell -PS> helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts -PS> helm upgrade --install aso2 aso2/azure-service-operator ` - --create-namespace ` - --namespace=azureserviceoperator-system ` - --set crdPattern=resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/* -``` -{{% /tab %}} -{{% tab header="CMD" %}} -``` cmd -C:\> helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts -C:\> helm upgrade --install aso2 aso2/azure-service-operator ^ - --create-namespace ^ - --namespace=azureserviceoperator-system ^ - --set crdPattern=resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/* -``` -{{% /tab %}} -{{< /tabpane >}} - -{{% alert title="Warning" color="warning" %}} -Make sure to set the `crdPattern` variable to include the CRDs you are interested in using. -You can use `--set crdPattern=*` to install all the CRDs, but be aware of the -[limits of the Kubernetes you are running](https://github.com/Azure/azure-service-operator/issues/2920). `*` is **not** -recommended on AKS Free-tier clusters. -See [CRD management](https://azure.github.io/azure-service-operator/guide/crd-management/) for more details. -{{% /alert %}} - -{{% 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 - -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#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. -{{% /alert %}} - -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 /%}} -{{% tab header="bash" %}} -``` bash -$ export AZURE_TENANT_ID= -$ export AZURE_SUBSCRIPTION_ID= -``` -{{% /tab %}} -{{% tab header="PowerShell" %}} -``` powershell -PS> $AZURE_TENANT_ID= -PS> $AZURE_SUBSCRIPTION_ID= -``` -{{% /tab %}} -{{% tab header="CMD" %}} -``` cmd -C:\> SET AZURE_TENANT_ID= -C:\> SET AZURE_SUBSCRIPTION_ID= -``` -{{% /tab %}} -{{< /tabpane >}} - -You can find these values by using the Azure CLI: `az account show` - -Next, create a service principal with Contributor permissions for your subscription. - -You can optionally use a service principal with a more restricted permission set -(for example contributor to just a Resource Group), but that will restrict what you can -do with ASO. See [using reduced permissions](https://azure.github.io/azure-service-operator/guide/authentication/reducing-access/#using-a-credential-for-aso-with-reduced-permissions) for more details. - -{{< tabpane text=true left=true >}} -{{% tab header="**Shell**:" disabled=true /%}} -{{% tab header="bash" %}} -``` bash -$ az ad sp create-for-rbac -n azure-service-operator --role contributor \ - --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID -``` -{{% /tab %}} -{{% tab header="PowerShell" %}} -``` powershell -PS> az ad sp create-for-rbac -n azure-service-operator --role contributor ` - --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID -``` -{{% /tab %}} -{{% tab header="CMD" %}} -``` cmd -C:\> az ad sp create-for-rbac -n azure-service-operator --role contributor ^ - --scopes /subscriptions/%AZURE_SUBSCRIPTION_ID% -``` -{{% /tab %}} -{{< /tabpane >}} - -This should give you output including the following: - -```bash -"appId": "xxxxxxxxxx", -"displayName": "azure-service-operator", -"name": "http://azure-service-operator", -"password": "xxxxxxxxxxx", -"tenant": "xxxxxxxxxxxxx" -``` - -Once you have created a service principal, set the following variables to your app ID and password values: - -{{< tabpane text=true left=true >}} -{{% tab header="**Shell**:" disabled=true /%}} -{{% tab header="bash" %}} -``` bash -$ export AZURE_CLIENT_ID= # This is the appID from the service principal we created. -$ export AZURE_CLIENT_SECRET= # This is the password from the service principal we created. -``` -{{% /tab %}} -{{% tab header="PowerShell" %}} -``` powershell -PS> $AZURE_CLIENT_ID= # This is the appID from the service principal we created. -PS> $AZURE_CLIENT_SECRET= # This is the password from the service principal we created. -``` -{{% /tab %}} -{{% tab header="CMD" %}} -``` cmd -C:\> :: This is the appID from the service principal we created. -C:\> SET AZURE_CLIENT_ID= -C:\> :: This is the password from the service principal we created. -C:\> SET AZURE_CLIENT_SECRET= -``` -{{% /tab %}} -{{< /tabpane >}} - -#### 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 /%}} -{{% tab header="bash" %}} -```bash -cat <}} - -### Usage - -Once the controller has been installed in your cluster, you should be able to see the ASO pod running. - -``` bash -$ kubectl get pods -n azureserviceoperator-system -NAME READY STATUS RESTARTS AGE -azureserviceoperator-controller-manager-5b4bfc59df-lfpqf 2/2 Running 0 24s -``` - -To view the logs for the running ASO controller, take note of the pod name shown above and then run the following command. - -``` bash -$ kubectl logs -n azureserviceoperator-system azureserviceoperator-controller-manager-5b4bfc59df-lfpqf manager -``` - -Let's create an Azure ResourceGroup in westcentralus with the name "aso-sample-rg". Create a file called `rg.yaml` -with the following contents: - -```yaml -apiVersion: resources.azure.com/v1api20200601 -kind: ResourceGroup -metadata: - name: aso-sample-rg - namespace: default -spec: - location: westcentralus -```` - -Then apply the file to your cluster: - -``` bash -$ kubectl apply -f rg.yaml -# resourcegroup.resources.azure.com/aso-sample-rg created -``` - -Once the resource group has been created, we can see what it looks like. - -``` bash -$ kubectl describe resourcegroups/aso-sample-rg -n default -``` - -The output will be similar to this: -``` yaml -Name: aso-sample-rg -Namespace: default -Labels: -Annotations: serviceoperator.azure.com/operator-namespace: azureserviceoperator-system - serviceoperator.azure.com/resource-id: /subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg -API Version: resources.azure.com/v1beta20200601 -Kind: ResourceGroup -Metadata: - Creation Timestamp: 2023-08-31T01:25:50Z - Finalizers: - serviceoperator.azure.com/finalizer - Generation: 1 - Resource Version: 3198 - UID: 70e2fef1-8c43-452f-8260-ffe5a73470fb -Spec: - Azure Name: aso-sample-rg - Location: westcentralus -Status: - Conditions: - Last Transition Time: 2023-08-31T01:25:58Z - Observed Generation: 1 - Reason: Succeeded - Status: True - Type: Ready - Id: /subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg - Location: westcentralus - Name: aso-sample-rg - Properties: - Provisioning State: Succeeded - Type: Microsoft.Resources/resourceGroups -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal CredentialFrom 42s (x2 over 42s) ResourceGroupController Using credential from "azureserviceoperator-system/aso-controller-settings" - Normal BeginCreateOrUpdate 35s ResourceGroupController Successfully sent resource to Azure with ID "/subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg" -``` - -We can delete the resource group from the cluster. This will also delete it from Azure. - -``` bash -$ kubectl delete resourcegroups/aso-sample-rg -# resourcegroup.resources.azure.com "aso-sample-rg" deleted -``` - -For samples of additional resources, see the [resource samples directory](https://github.com/Azure/azure-service-operator/tree/main/v2/samples). - -### Tearing it down - -{{% alert title="Warning" color="warning" %}} -if you `kubectl delete` an ASO resource from your cluster, ASO will delete the Azure resource. This can -be dangerous if you were to do this with an existing resource group which contains resources you do -not wish to be deleted. -{{% /alert %}} - -If you want to delete the resources you've created, just `kubectl delete` each of the Azure -resources. - -If you want to delete the cluster resource without affecting the Azure resource, apply the annotation `serviceoperator.azure.com/reconcile-policy: skip` first. - -As for deleting controller components, just `kubectl delete -f` the release manifests you created -to get started. For example, creating and deleting cert-manager. - -``` bash -# remove the cert-manager components -$ kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/v1.14.4/cert-manager.yaml -``` - ## How to contribute To get started developing or contributing to the project, follow the instructions in the [contributing guide](https://azure.github.io/azure-service-operator/contributing/). From 054683327b78de8b1b70e58c12eb4a6885ac5765 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:10:40 -0700 Subject: [PATCH 02/11] Create getting started documentation for ASO Moved over the "Getting Started" esque content from the original ASO homepage to here. --- docs/hugo/content/getting-started/_index.md | 367 ++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 docs/hugo/content/getting-started/_index.md diff --git a/docs/hugo/content/getting-started/_index.md b/docs/hugo/content/getting-started/_index.md new file mode 100644 index 00000000000..f2067bc555b --- /dev/null +++ b/docs/hugo/content/getting-started/_index.md @@ -0,0 +1,367 @@ +--- +title: Getting Started +weight: 5 +type: docs +description: "Install and get started with Azure Service Operator" +--- + +## Prerequisites + +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]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) setup for how to use managed identity instead. We recommend using workload identity in production. + +## Installation + +### 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 +``` + +Check that the cert-manager pods have started successfully before continuing. + +``` bash +$ kubectl get pods -n cert-manager +NAME READY STATUS RESTARTS AGE +cert-manager-5597cff495-lmphj 1/1 Running 0 1m +cert-manager-cainjector-bd5f9c764-gvxm4 1/1 Running 0 1m +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`.) + +### 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 /%}} +{{% tab header="bash" %}} +``` bash +$ helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts +$ helm upgrade --install aso2 aso2/azure-service-operator \ + --create-namespace \ + --namespace=azureserviceoperator-system \ + --set crdPattern='resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*' +``` +Note: **bash** requires the value for `crdPattern` to be quoted with `'` to avoid expansion of the wildcards. +{{% /tab %}} +{{% tab header="PowerShell" %}} +``` powershell +PS> helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts +PS> helm upgrade --install aso2 aso2/azure-service-operator ` + --create-namespace ` + --namespace=azureserviceoperator-system ` + --set crdPattern=resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/* +``` +{{% /tab %}} +{{% tab header="CMD" %}} +``` cmd +C:\> helm repo add aso2 https://raw.githubusercontent.com/Azure/azure-service-operator/main/v2/charts +C:\> helm upgrade --install aso2 aso2/azure-service-operator ^ + --create-namespace ^ + --namespace=azureserviceoperator-system ^ + --set crdPattern=resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/* +``` +{{% /tab %}} +{{< /tabpane >}} + +{{% alert title="Warning" color="warning" %}} +Make sure to set the `crdPattern` variable to include the CRDs you are interested in using. +You can use `--set crdPattern=*` to install all the CRDs, but be aware of the +[limits of the Kubernetes you are running](https://github.com/Azure/azure-service-operator/issues/2920). `*` is **not** +recommended on AKS Free-tier clusters. +See [CRD management](https://azure.github.io/azure-service-operator/guide/crd-management/) for more details. +{{% /alert %}} + +{{% 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 + +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#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. +{{% /alert %}} + +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 /%}} +{{% tab header="bash" %}} +``` bash +$ export AZURE_TENANT_ID= # This is the "tenantId", if you have multiple tenants, it will be "homeTenantId" +$ export AZURE_SUBSCRIPTION_ID= # This is the "id" +``` +{{% /tab %}} +{{% tab header="PowerShell" %}} +``` powershell +PS> $AZURE_TENANT_ID= # This is the "tenantId", if you have multiple tenants, it will be "homeTenantId" +PS> $AZURE_SUBSCRIPTION_ID= # This is the "id" +``` +{{% /tab %}} +{{% tab header="CMD" %}} +``` cmd +C:\> SET AZURE_TENANT_ID= # This is the "tenantId", if you have multiple tenants, it will be "homeTenantId" +C:\> SET AZURE_SUBSCRIPTION_ID= # This is the "id" +``` +{{% /tab %}} +{{< /tabpane >}} + +You can find these values by using the Azure CLI: `az account show` + +Next, create a service principal with Contributor permissions for your subscription. + +You can optionally use a service principal with a more restricted permission set +(for example contributor to just a Resource Group), but that will restrict what you can +do with ASO. See [using reduced permissions](https://azure.github.io/azure-service-operator/guide/authentication/reducing-access/#using-a-credential-for-aso-with-reduced-permissions) for more details. + +{{< tabpane text=true left=true >}} +{{% tab header="**Shell**:" disabled=true /%}} +{{% tab header="bash" %}} +``` bash +$ az ad sp create-for-rbac -n azure-service-operator --role contributor \ + --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID +``` +{{% /tab %}} +{{% tab header="PowerShell" %}} +``` powershell +PS> az ad sp create-for-rbac -n azure-service-operator --role contributor ` + --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID +``` +{{% /tab %}} +{{% tab header="CMD" %}} +``` cmd +C:\> az ad sp create-for-rbac -n azure-service-operator --role contributor ^ + --scopes /subscriptions/%AZURE_SUBSCRIPTION_ID% +``` +{{% /tab %}} +{{< /tabpane >}} + +This should give you output including the following: + +```bash +"appId": "xxxxxxxxxx", +"displayName": "azure-service-operator", +"name": "http://azure-service-operator", +"password": "xxxxxxxxxxx", +"tenant": "xxxxxxxxxxxxx" +``` + +Once you have created a service principal, set the following variables to your app ID and password values: + +{{< tabpane text=true left=true >}} +{{% tab header="**Shell**:" disabled=true /%}} +{{% tab header="bash" %}} +``` bash +$ export AZURE_CLIENT_ID= # This is the appID from the service principal we created. +$ export AZURE_CLIENT_SECRET= # This is the password from the service principal we created. +``` +{{% /tab %}} +{{% tab header="PowerShell" %}} +``` powershell +PS> $AZURE_CLIENT_ID= # This is the appID from the service principal we created. +PS> $AZURE_CLIENT_SECRET= # This is the password from the service principal we created. +``` +{{% /tab %}} +{{% tab header="CMD" %}} +``` cmd +C:\> :: This is the appID from the service principal we created. +C:\> SET AZURE_CLIENT_ID= +C:\> :: This is the password from the service principal we created. +C:\> SET AZURE_CLIENT_SECRET= +``` +{{% /tab %}} +{{< /tabpane >}} + +### 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 /%}} +{{% tab header="bash" %}} +```bash +cat <}} + +## Usage + +Once the controller has been installed in your cluster, you should be able to see the ASO pod running. + +``` bash +$ kubectl get pods -n azureserviceoperator-system +NAME READY STATUS RESTARTS AGE +azureserviceoperator-controller-manager-5b4bfc59df-lfpqf 2/2 Running 0 24s +``` + +To view the logs for the running ASO controller, take note of the pod name shown above and then run the following command. + +``` bash +$ kubectl logs -n azureserviceoperator-system azureserviceoperator-controller-manager-5b4bfc59df-lfpqf manager +``` + +Let's create an Azure ResourceGroup in westcentralus with the name "aso-sample-rg". Create a file called `rg.yaml` +with the following contents: + +```yaml +apiVersion: resources.azure.com/v1api20200601 +kind: ResourceGroup +metadata: + name: aso-sample-rg + namespace: default +spec: + location: westcentralus +```` + +Then apply the file to your cluster: + +``` bash +$ kubectl apply -f rg.yaml +# resourcegroup.resources.azure.com/aso-sample-rg created +``` + +Once the resource group has been created, we can see what it looks like. + +``` bash +$ kubectl describe resourcegroups/aso-sample-rg -n default +``` + +The output will be similar to this: +``` yaml +Name: aso-sample-rg +Namespace: default +Labels: +Annotations: serviceoperator.azure.com/operator-namespace: azureserviceoperator-system + serviceoperator.azure.com/resource-id: /subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg +API Version: resources.azure.com/v1beta20200601 +Kind: ResourceGroup +Metadata: + Creation Timestamp: 2023-08-31T01:25:50Z + Finalizers: + serviceoperator.azure.com/finalizer + Generation: 1 + Resource Version: 3198 + UID: 70e2fef1-8c43-452f-8260-ffe5a73470fb +Spec: + Azure Name: aso-sample-rg + Location: westcentralus +Status: + Conditions: + Last Transition Time: 2023-08-31T01:25:58Z + Observed Generation: 1 + Reason: Succeeded + Status: True + Type: Ready + Id: /subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg + Location: westcentralus + Name: aso-sample-rg + Properties: + Provisioning State: Succeeded + Type: Microsoft.Resources/resourceGroups +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal CredentialFrom 42s (x2 over 42s) ResourceGroupController Using credential from "azureserviceoperator-system/aso-controller-settings" + Normal BeginCreateOrUpdate 35s ResourceGroupController Successfully sent resource to Azure with ID "/subscriptions/82acd5bb-4206-47d4-9c12-a65db028483d/resourceGroups/aso-sample-rg" +``` + +We can delete the resource group from the cluster. This will also delete it from Azure. + +``` bash +$ kubectl delete resourcegroups/aso-sample-rg +# resourcegroup.resources.azure.com "aso-sample-rg" deleted +``` + +For samples of additional resources, see the [resource samples directory](https://github.com/Azure/azure-service-operator/tree/main/v2/samples). + +## Tearing it down + +{{% alert title="Warning" color="warning" %}} +if you `kubectl delete` an ASO resource from your cluster, ASO will delete the Azure resource. This can +be dangerous if you were to do this with an existing resource group which contains resources you do +not wish to be deleted. +{{% /alert %}} + +If you want to delete the resources you've created, just `kubectl delete` each of the Azure +resources. + +If you want to delete the cluster resource without affecting the Azure resource, apply the annotation `serviceoperator.azure.com/reconcile-policy: skip` first. + +As for deleting controller components, just `kubectl delete -f` the release manifests you created +to get started. For example, creating and deleting cert-manager. + +``` bash +# remove the cert-manager components +$ kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/v1.14.4/cert-manager.yaml +``` From 9641bf981bb944c92c0afb95f89872b43ac62f76 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:12:06 -0700 Subject: [PATCH 03/11] Add new tutorial cards for ASO resources and manifests Updated the index card page to include the argocd tutorial and the tutorial to create one's own deployment files. --- docs/hugo/content/tutorials/_index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/hugo/content/tutorials/_index.md b/docs/hugo/content/tutorials/_index.md index 9c810e22cf7..c4c87cc128f 100644 --- a/docs/hugo/content/tutorials/_index.md +++ b/docs/hugo/content/tutorials/_index.md @@ -40,3 +40,16 @@ The CosmosDB is hosted in Azure but created easily via `kubectl` and Azure Servi {{% /card %}} {{% /cardpane %}} + +{{% cardpane %}} +{{% card header="Create ASO resources and visuals"%}} + +[Create ASO resources and view them](https://azure-samples.github.io/aks-labs/docs/platform-engineering/aks-capz-aso/#sample-1-create-a-new-aks-cluster-as-an-argo-cd-application) through the Argo CD UI. + +{{% /card %}} +{{% card header="Create Your own Manifest"%}} + +[Create your own deployment manifests](https://github.com/Azure-Samples/azure-service-operator-samples/tree/master/azure-votes-redis) on ASO. + +{{% /card %}} +{{% /cardpane %}} From 58940108300fe66a92ba6077d68ea2feb5d70abb Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:13:17 -0700 Subject: [PATCH 04/11] Remove duplicate ASO resources cardpane Removed duplicate cardpane section for ASO resources. --- docs/hugo/content/tutorials/_index.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/hugo/content/tutorials/_index.md b/docs/hugo/content/tutorials/_index.md index c4c87cc128f..ea23a7f9d87 100644 --- a/docs/hugo/content/tutorials/_index.md +++ b/docs/hugo/content/tutorials/_index.md @@ -11,6 +11,20 @@ cascade: description: Tutorials for using Azure Service Operator --- +{{% cardpane %}} +{{% card header="Create ASO resources and visuals"%}} + +[Create ASO resources and view them](https://azure-samples.github.io/aks-labs/docs/platform-engineering/aks-capz-aso/#sample-1-create-a-new-aks-cluster-as-an-argo-cd-application) through the Argo CD UI. + +{{% /card %}} +{{% card header="Create Your own Manifest"%}} + +[Create your own deployment manifests](https://github.com/Azure-Samples/azure-service-operator-samples/tree/master/azure-votes-redis) on ASO. + +{{% /card %}} +{{% /cardpane %}} + + {{% cardpane %}} {{% card header="CosmosDB to-do List"%}} @@ -40,16 +54,3 @@ The CosmosDB is hosted in Azure but created easily via `kubectl` and Azure Servi {{% /card %}} {{% /cardpane %}} - -{{% cardpane %}} -{{% card header="Create ASO resources and visuals"%}} - -[Create ASO resources and view them](https://azure-samples.github.io/aks-labs/docs/platform-engineering/aks-capz-aso/#sample-1-create-a-new-aks-cluster-as-an-argo-cd-application) through the Argo CD UI. - -{{% /card %}} -{{% card header="Create Your own Manifest"%}} - -[Create your own deployment manifests](https://github.com/Azure-Samples/azure-service-operator-samples/tree/master/azure-votes-redis) on ASO. - -{{% /card %}} -{{% /cardpane %}} From 1ba76633ad0a891341dda8ff6bc35cd69a3a1fbb Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:19:19 -0700 Subject: [PATCH 05/11] Update _index.md Fixing links. --- docs/hugo/content/tutorials/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/tutorials/_index.md b/docs/hugo/content/tutorials/_index.md index ea23a7f9d87..7aed65e5c96 100644 --- a/docs/hugo/content/tutorials/_index.md +++ b/docs/hugo/content/tutorials/_index.md @@ -19,7 +19,7 @@ description: Tutorials for using Azure Service Operator {{% /card %}} {{% card header="Create Your own Manifest"%}} -[Create your own deployment manifests](https://github.com/Azure-Samples/azure-service-operator-samples/tree/master/azure-votes-redis) on ASO. +[Create your own deployment manifests](tutorial-deployment-files) on ASO. {{% /card %}} {{% /cardpane %}} From c0ae384387ff73c59afbda419df9e6d21d8ee8f2 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:20:05 -0700 Subject: [PATCH 06/11] Add tutorial for ASO resources in ArgoCD This tutorial explains how to create ASO resources and view them in ArgoCD, including deploying Argo CD and integrating with Azure. --- docs/hugo/content/tutorials/tutorial-asoargocd.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/hugo/content/tutorials/tutorial-asoargocd.md diff --git a/docs/hugo/content/tutorials/tutorial-asoargocd.md b/docs/hugo/content/tutorials/tutorial-asoargocd.md new file mode 100644 index 00000000000..ccf66e6c1e4 --- /dev/null +++ b/docs/hugo/content/tutorials/tutorial-asoargocd.md @@ -0,0 +1,8 @@ +--- +title: "Tutorial: Create ASO resources and view them in ArgoCD" +--- + +Follow the [guided example](https://azure-samples.github.io/aks-labs/docs/platform-engineering/aks-capz-aso/#sample-1-create-a-new-aks-cluster-as-an-argo-cd-application) +to see how you can deploy Argo CD on your cluster, deploy resources via ASO, and see the resources populated in the Argo CD UI. + +You will learn hwo to declaratively provision a new AKS cluster using Argo CD and Helm, integrating them directly with Azure via the Azure Cluster API. Once you deploy resources on ASO, they will also show up in Argo CD. From f0fb6f3908d05fec364d45a5244838b6d21b9998 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:20:27 -0700 Subject: [PATCH 07/11] Add tutorial on creating deployment manifests This document provides guidance on creating deployment manifests for Azure resources, including an example of an AKS cluster deployment. --- .../tutorials/tutorial-deployment-files.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/hugo/content/tutorials/tutorial-deployment-files.md diff --git a/docs/hugo/content/tutorials/tutorial-deployment-files.md b/docs/hugo/content/tutorials/tutorial-deployment-files.md new file mode 100644 index 00000000000..96b75903e29 --- /dev/null +++ b/docs/hugo/content/tutorials/tutorial-deployment-files.md @@ -0,0 +1,63 @@ +--- +title: Creating deployment manifests +weight: 10 +type: docs +--- + +## Creating your own deployment files + +Typially, a deployment of a specific type of Azure resource is its own CRD; you can tell what type of resource is deployed by looking at its `kind:`. + +The `spec:` field of the deployment file will typically be associated with the parameters you expect when creating the resource in Azure. + +### Example AKS Cluster + +Lets look at an AKS cluster as an example. The [latest sample](https://github.com/Azure/azure-service-operator/blob/main/v2/samples/containerservice/v1api20240901/v1api20240901_managedcluster.yaml) looks like so: + +```yaml +apiVersion: containerservice.azure.com/v1api20240901 +kind: ManagedCluster +metadata: + name: sample-managedcluster-20240901 + namespace: default +spec: + location: westus3 + owner: + name: aso-sample-rg + dnsPrefix: aso + agentPoolProfiles: + - name: pool1 + count: 1 + vmSize: Standard_DS2_v2 + osType: Linux + mode: System + identity: + type: SystemAssigned +``` + +If we wanted to specify our own deployment, we'd replace parameters as we typically fill in for creation in the CLI. Let's say I wanted to create `myAKSCluster` in `eastus`, for instance. It'd look like: + +```yaml +apiVersion: containerservice.azure.com/v1api20240901 +kind: ManagedCluster +metadata: + name: myAKSCluster + namespace: default +spec: + location: eastus + owner: + name: + dnsPrefix: aso + agentPoolProfiles: + - name: agentpool1 + count: 1 + vmSize: + osType: Linux + mode: System + identity: + type: SystemAssigned +``` + +## More Examples + +If you want to create your own deployment files, you can visit our [samples directory](https://github.com/Azure/azure-service-operator/tree/main/v2/samples) to see how different deployments are structured and alter the manifest according to your own specifications. From 25763179ea24bc931ecc1415c6081fb0f9a7ed7a Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Thu, 2 Oct 2025 22:49:47 -0700 Subject: [PATCH 08/11] Update title for deployment manifests tutorial --- docs/hugo/content/tutorials/tutorial-deployment-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/tutorials/tutorial-deployment-files.md b/docs/hugo/content/tutorials/tutorial-deployment-files.md index 96b75903e29..7b38db129af 100644 --- a/docs/hugo/content/tutorials/tutorial-deployment-files.md +++ b/docs/hugo/content/tutorials/tutorial-deployment-files.md @@ -1,5 +1,5 @@ --- -title: Creating deployment manifests +title: "Tutorial: Creating deployment manifests" weight: 10 type: docs --- From 57ddf12be90c2c97b80b470a0959d3302f5fe070 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Mon, 20 Oct 2025 14:44:03 -0700 Subject: [PATCH 09/11] Update docs/hugo/content/getting-started/_index.md Co-authored-by: Bevan Arps --- docs/hugo/content/getting-started/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/getting-started/_index.md b/docs/hugo/content/getting-started/_index.md index f2067bc555b..ddeae517619 100644 --- a/docs/hugo/content/getting-started/_index.md +++ b/docs/hugo/content/getting-started/_index.md @@ -348,7 +348,7 @@ For samples of additional resources, see the [resource samples directory](https: ## Tearing it down {{% alert title="Warning" color="warning" %}} -if you `kubectl delete` an ASO resource from your cluster, ASO will delete the Azure resource. This can +If you `kubectl delete` an ASO resource from your cluster, ASO **will also delete** the Azure resource. This can be dangerous if you were to do this with an existing resource group which contains resources you do not wish to be deleted. {{% /alert %}} From 7b6dc6ac1c86d951e9f997d5162e68fa619a00fe Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Mon, 20 Oct 2025 14:44:11 -0700 Subject: [PATCH 10/11] Update docs/hugo/content/getting-started/_index.md Co-authored-by: Bevan Arps --- docs/hugo/content/getting-started/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/getting-started/_index.md b/docs/hugo/content/getting-started/_index.md index ddeae517619..bc735eb4abe 100644 --- a/docs/hugo/content/getting-started/_index.md +++ b/docs/hugo/content/getting-started/_index.md @@ -7,7 +7,7 @@ description: "Install and get started with Azure Service Operator" ## Prerequisites -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). +1. A Kubernetes cluster (at least version 1.32) [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]( {{< relref "credential-format#managed-identity-via-workload-identity" >}} ) setup for how to use managed identity instead. We recommend using workload identity in production. From 0e389d4fdf7786ab1a6acb8bc5bf9a849798c677 Mon Sep 17 00:00:00 2001 From: Jack Jiang <58266810+jakjang@users.noreply.github.com> Date: Mon, 20 Oct 2025 14:44:17 -0700 Subject: [PATCH 11/11] Update docs/hugo/content/getting-started/_index.md Co-authored-by: Bevan Arps --- docs/hugo/content/getting-started/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hugo/content/getting-started/_index.md b/docs/hugo/content/getting-started/_index.md index bc735eb4abe..b62d649e333 100644 --- a/docs/hugo/content/getting-started/_index.md +++ b/docs/hugo/content/getting-started/_index.md @@ -234,7 +234,7 @@ stringData: {{% tab header="CMD" %}} -Create a file named `secret.yaml` with the following content. Replace each of the variables such as +Create a file named `secret.yaml` with the following content. Manually replace each of the variables such as `%AZURE_SUBSCRIPTION_ID%` with the subscription ID, `%AZURE_CLIENT_SECRET%` with the client secret and so on. ```