The Cluster API Book

Implementation best practices

Cluster API doesn’t define strict rules about how providers should implement controllers.

However, some best practice are worth to notice:

• Infrastructure objects (e.g. load balancers, VMs etc) generated by the Infra providers SHOULD adopt a naming convention that directly links to the Kubernetes resource that originated those objects. Please note that in most cases external constraints might impact this decision, like e.g.

  • Differences in naming conversions from Kubernetes CRDs and the target infrastructure
  • The fact that the InfraCluster Kubernetes CRD is namespace-scoped while target infrastructure might have different approaches to grouping resources

• The naming convention above should not be used or advertised as a contract for identifying infrastructure objects. More robust mechanisms MUST always be provided and used, such as provider-owned tags or labels, to associate them with their Kubernetes objects.

  • This avoids relying on naming strategies that core controllers or users can change.
  • Do not use a derived infrastructure name as the sole lookup key: transformations can be lossy, external resources can be renamed, and names might not be unique in the target system.

• Provider implementations SHOULD accept every valid Kubernetes resource name and namespace permitted by the applicable Cluster API resource.

  • Names can exceed constraints imposed by an infrastructure platform or by derived fields such as a VM hostname.

• When an external system imposes shorter or narrower naming rules, derive a compliant infrastructure name without changing the Kubernetes resource’s name.

  • Use a deterministic transformation that preserves a readable prefix where useful and incorporates a hash of the full Kubernetes identity (including namespace when needed) to avoid collisions after truncation or normalization.
  • Apply the transformation conditionally when the original name is not accepted, to avoid changing names unnecessarily.
  • Apply the same transformation wherever the name is referenced, and do not assume Kubernetes names are globally unique across namespaces.
  • Report an actionable naming validation error only if a compliant infrastructure name cannot be derived. Do not pass an invalid name to the target platform and rely on it to reject the request during provisioning.

• Test boundary and normalization cases for every infrastructure-specific name.

  • Cover maximum supported lengths, long valid Kubernetes names, punctuation accepted by Kubernetes but restricted by the target system, collisions after normalization or truncation, and identical names in different namespaces.
  • Include provider E2E coverage where the target infrastructure or guest operating system imposes constraints that unit tests cannot exercise.
  • Document provider-specific limits and resulting validation errors in that provider’s documentation.

• Cluster API offers a great development environment based on Tilt, which can be easily extended to work with any provider. Use it! See Rapid iterative development with Tilt

• Cluster API defines a set of best practices and standards that, if adopted, could speed up provider development and improve consistency with core Cluster API. See:

  • Logging
  • Tuning controllers

• Cluster API implements a test framework that, if adopted, could help in ensuring the quality of the provider. See:

  • Testing
  • Developing E2E tests

• While standard security practices for developing Kubernetes controllers apply, it is important to recognize that given that infrastructure provider deal with cloud credentials and cloud infrastructure, there are additional critical security concern that must be addressed to ensure secure operations. See:

  • Infrastructure Provider Security Guidance