[book] Add advanced section to document using kustomize + yaml templates

[CecileRobertMichon]

For some users, clusterctl is not flexible enough to configure clusters past the quickstart experience. Many of the providers provide example "flavor" templates as references. However, for more advanced users that need greater control over the cluster configuration, the templates need to be curated to fit their use case (eg. add custom images, modify cloud provider args, etc.)

In the future, a templating solution might be integrated into clusterctl and fill the gap between the day 0 experience and the flexibility required by advanced users.

In the meantime, we should consider adding an advanced section in the documentation about using kustomize and templates, possibly with a note about the future templating engine in clusterctl. Currently, the Cluster API book only covers clusterctl as UX for cluster API which might make users think that applying yaml templates without using clusterctl config is not supported anymore (and the only other option is the overrides directory which is intended for developers, not users).

See also kubernetes-sigs/cluster-api-provider-azure#776

[CecileRobertMichon]

/kind documentation

[vincepri]

/milestone v0.3.x

[vincepri]

/milestone v0.4.0
/help

[k8s-ci-robot]

@vincepri:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/milestone v0.4.0
/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fabriziopandini]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[CecileRobertMichon]

/remove-lifecycle stale

[vincepri]

/lifecycle frozen

[scottslowe]

I can take this issue. I have some existing content on using kustomize with Cluster API that should be straightforward to adapt and get added to the documentation.

/assign

[vincepri]

@scottslowe Are you still working on this issue?

[scottslowe]

@vincepri Yes, I am. There's a lot here, so I've been trying to figure out just how much to include/exclude. For example, should I include information on customizing the kustomize transformers so they are more Cluster API "aware"?

[vincepri]

Can you provide an example?

[scottslowe]

For example, without customizing the NameReference transformer then the use of the namePrefix and nameSuffix directives won't work properly; the metadata.name field will get updated, but fields like the spec.infrastructureRef.name field that points to an AWSCluster object won't get updated. You then end up with a broken manifest.

This blog post I wrote has some additional information: https://blog.scottlowe.org/2020/03/17/kustomize-transformer-configuration-cluster-api-v1alpha3/

[fabriziopandini]

I think that we can present this by use cases/ complexity:

• Basic
  • Use kustomize to build templates variant (assembling together different templates bits but without applying transformation, something like what we are doing for E2E test)
• Advanced
  • Make name prefix/suffix customisable

This has the advantage that we can start by few use cases and then add more in incrementa follow ups