From 2e745145fbf69916615d701d14d81edf300eda92 Mon Sep 17 00:00:00 2001 From: Jon Huhn Date: Fri, 3 May 2024 15:54:50 +0000 Subject: [PATCH] ASOAPI: update docs --- docs/book/install-and-build.sh | 1 + docs/book/src/SUMMARY.md | 1 + docs/book/src/reference/v1alpha1-exp-api.md | 1 + docs/book/src/topics/aso.md | 17 ++++++++--------- 4 files changed, 11 insertions(+), 9 deletions(-) create mode 100644 docs/book/src/reference/v1alpha1-exp-api.md diff --git a/docs/book/install-and-build.sh b/docs/book/install-and-build.sh index 4a1214597ac..a454fb76b6f 100755 --- a/docs/book/install-and-build.sh +++ b/docs/book/install-and-build.sh @@ -76,6 +76,7 @@ genCRDAPIReferenceDocs="${genCRDAPIReferenceDocsPath}/gen-crd-api-reference-docs ${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./api/v1beta1 -out-file ./docs/book/src/reference/v1beta1-api-raw.html ${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./exp/api/v1beta1 -out-file ./docs/book/src/reference/v1beta1-exp-api-raw.html +${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./exp/api/v1alpha1 -out-file ./docs/book/src/reference/v1alpha1-exp-api-raw.html # Finally build the book. (cd docs/book && /tmp/mdbook build) diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 23bd77b5ce9..40045ebfa49 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -47,3 +47,4 @@ - [Reference](./reference/reference.md) - [v1beta1 API](./reference/v1beta1-api.md) - [v1beta1 exp API](./reference/v1beta1-exp-api.md) + - [v1alpha1 exp API](./reference/v1alpha1-exp-api.md) diff --git a/docs/book/src/reference/v1alpha1-exp-api.md b/docs/book/src/reference/v1alpha1-exp-api.md new file mode 100644 index 00000000000..50f46f1d2b1 --- /dev/null +++ b/docs/book/src/reference/v1alpha1-exp-api.md @@ -0,0 +1 @@ +{{ #include v1alpha1-exp-api-raw.html }} diff --git a/docs/book/src/topics/aso.md b/docs/book/src/topics/aso.md index 0e435134bcf..20bc151dac4 100644 --- a/docs/book/src/topics/aso.md +++ b/docs/book/src/topics/aso.md @@ -82,7 +82,7 @@ An example configuration file and demo for `Azure Cache for Redis` can be found ## Experimental ASO API -CAPZ has begun to experiment with a new flavor of APIs that attempt to address the following limitations of +New in CAPZ v1.15.0 is a new flavor of APIs that addresses the following limitations of the existing CAPZ APIs for advanced use cases: - A limited set of Azure resource types can be represented. @@ -97,7 +97,7 @@ This new experimental API defines new AzureASOManagedCluster, AzureASOManagedCon AzureASOManagedMachinePool resources. An AzureASOManagedCluster might look like this: ```yaml -apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1 kind: AzureASOManagedCluster metadata: name: my-cluster @@ -112,6 +112,8 @@ spec: location: eastus ``` +See [here](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/main/templates/cluster-template-aks-aso.yaml) for a full AKS example using all the new resources. + The main element of the new API is `spec.resources` in each new resource, which defines arbitrary, literal ASO resources inline to be managed by CAPZ. These inline ASO resource definitions take the place of almost all other configuration currently defined by CAPZ. e.g. Instead of a CAPZ-specific `spec.location` field on the @@ -120,15 +122,12 @@ resource defined in an AzureASOManagedControlPlane's `spec.resources`. This patt full, any ASO-supported version of a resource type in any of these new CAPZ resources. The obvious tradeoff with this new style of API is that CAPZ resource definitions can become more verbose for -basic use cases. To address this, CAPZ will still offer flavor templates that use this API with all of the +basic use cases. To address this, CAPZ still offers flavor templates that use this API with all of the boilerplate predefined to serve as a starting point for customization. The overall theme of this API is to leverage ASO as much as possible for representing Azure resources in the Kubernetes API, thereby making CAPZ the thinnest possible translation layer between ASO and Cluster API. -This experiment will help inform CAPZ whether this pattern may be a candidate for a potential v2 API. If -you're interested in trying this out, stay tuned! This functionality is available, but under heavy -construction and not yet in a usable state, behind the `ASOAPI` feature flag (set by the `EXP_ASO_API` -environment variable). - -Feedback is welcome! +This experiment will help inform CAPZ whether this pattern may be a candidate for a potential v2 API. This +functionality is available behind the `ASOAPI` feature flag (set by the `EXP_ASO_API` environment variable). +Please try it out and offer any feedback!