diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index a45c431aed55..d959fde4e9e4 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -67,35 +67,36 @@ - [clusterctl Provider Contract](clusterctl/provider-contract.md) - [clusterctl for Developers](clusterctl/developers.md) - [clusterctl Extensions with Plugins](clusterctl/plugins.md) -- [Developer Guide](./developer/guide.md) - - [Repository Layout](./developer/repository-layout.md) - - [Rapid iterative development with Tilt](./developer/tilt.md) - - [Logging](./developer/logging.md) - - [Testing](./developer/testing.md) - - [Developing E2E tests](./developer/e2e.md) - - [Controllers](./developer/architecture/controllers.md) - - [Bootstrap](./developer/architecture/controllers/bootstrap.md) - - [Cluster](./developer/architecture/controllers/cluster.md) - - [Machine](./developer/architecture/controllers/machine.md) - - [MachineSet](./developer/architecture/controllers/machine-set.md) - - [MachineDeployment](./developer/architecture/controllers/machine-deployment.md) - - [MachineHealthCheck](./developer/architecture/controllers/machine-health-check.md) - - [Control Plane](./developer/architecture/controllers/control-plane.md) - - [MachinePool](./developer/architecture/controllers/machine-pool.md) - - [ClusterTopology](./developer/architecture/controllers/cluster-topology.md) - - [ClusterResourceSet](./developer/architecture/controllers/cluster-resource-set.md) - - [Multi-tenancy](./developer/architecture/controllers/multi-tenancy.md) - - [Support multiple instances](./developer/architecture/controllers/support-multiple-instances.md) - - [Tuning controllers](./developer/architecture/controllers/tuning.md) +- [Developer Guide](./developer/getting-started.md) + - [Developing "core" Cluster API](developer/core/overview.md) + - [Rapid iterative development with Tilt](developer/core/tilt.md) + - [Repository Layout](developer/core/repository-layout.md) + - [Controllers](./developer/core/controllers/overview.md) + - [Cluster](./developer/core/controllers/cluster.md) + - [ClusterTopology](./developer/core/controllers/cluster-topology.md) + - [ClusterResourceSet](./developer/core/controllers/cluster-resource-set.md) + - [MachineDeployment](./developer/core/controllers/machine-deployment.md) + - [MachineSet](./developer/core/controllers/machine-set.md) + - [Machine](./developer/core/controllers/machine.md) + - [MachinePool](./developer/core/controllers/machine-pool.md) + - [MachineHealthCheck](./developer/core/controllers/machine-health-check.md) + - [Bootstrap](./developer/core/controllers/bootstrap.md) + - [Control Plane](./developer/core/controllers/control-plane.md) + - [Logging](developer/core/logging.md) + - [Testing](developer/core/testing.md) + - [Developing E2E tests](developer/core/e2e.md) + - [Tuning controllers](./developer/core/tuning.md) + - [Support multiple instances](./developer/core/support-multiple-instances.md) + - [Multi-tenancy](./developer/core/multi-tenancy.md) - [Developing providers](./developer/providers/overview.md) - [Getting started](developer/providers/getting-started/overview.md) - - [Naming](developer/providers/getting-started/naming.md) - - [Initialize Repo and API types](developer/providers/getting-started/initialize-repo-and-api-types.md) - - [Implement API types](developer/providers/getting-started/implement-api-types.md) - - [Webhooks](developer/providers/getting-started/webhooks.md) - - [Controllers and Reconciliation](developer/providers/getting-started/controllers-and-reconciliation.md) - - [Configure the provider manifest](developer/providers/getting-started/configure-the-deployment.md) - - [Building, Running, Testing](developer/providers/getting-started/building-running-and-testing.md) + - [Naming](developer/providers/getting-started/naming.md) + - [Initialize Repo and API types](developer/providers/getting-started/initialize-repo-and-api-types.md) + - [Implement API types](developer/providers/getting-started/implement-api-types.md) + - [Webhooks](developer/providers/getting-started/webhooks.md) + - [Controllers and Reconciliation](developer/providers/getting-started/controllers-and-reconciliation.md) + - [Configure the provider manifest](developer/providers/getting-started/configure-the-deployment.md) + - [Building, Running, Testing](developer/providers/getting-started/building-running-and-testing.md) - [Provider contracts](./developer/providers/contracts.md) - [Cluster Infrastructure](./developer/providers/cluster-infrastructure.md) - [Control Plane](./developer/providers/control-plane.md) diff --git a/docs/book/src/clusterctl/provider-contract.md b/docs/book/src/clusterctl/provider-contract.md index 5904aced2b1f..ec385943907d 100644 --- a/docs/book/src/clusterctl/provider-contract.md +++ b/docs/book/src/clusterctl/provider-contract.md @@ -254,7 +254,7 @@ While defining the Deployment Spec, the container that executes the controller/r For controllers only, the manager MUST support a `--namespace` flag for specifying the namespace where the controller will look for objects to reconcile; however, clusterctl will always install providers watching for all namespaces -(`--namespace=""`); for more details see [support for multiple instances](../developer/architecture/controllers/support-multiple-instances.md) +(`--namespace=""`); for more details see [support for multiple instances](../developer/core/support-multiple-instances.md) for more context. While defining Pods for Deployments, canonical names should be used for images. diff --git a/docs/book/src/developer/architecture/controllers.md b/docs/book/src/developer/architecture/controllers.md deleted file mode 100644 index e6afe348bc87..000000000000 --- a/docs/book/src/developer/architecture/controllers.md +++ /dev/null @@ -1,20 +0,0 @@ -# Controllers - -Cluster API has a number of controllers, both in the core Cluster API and the reference providers, which move the state of the cluster toward some defined desired state. - -Documentation for the CAPI controllers can be found at: -- Bootstrap Provider - - [Bootstrap](./controllers/bootstrap.md) -- ControlPlane Provider - - [ControlPlane](./controllers/control-plane.md) -- Core - - [Cluster](./controllers/cluster.md) - - [Machine](./controllers/machine.md) - - [MachineSet](./controllers/machine-set.md) - - [MachineDeployment](./controllers/machine-deployment.md) - - [MachineHealthCheck](./controllers/machine-health-check.md) - - [MachinePool](./controllers/machine-pool.md) -- ClusterClass - - [Cluster Topology](./controllers/cluster-topology.md) -- AddOns - - [ClusterResourceSet](./controllers/cluster-resource-set.md) diff --git a/docs/book/src/developer/architecture/controllers/bootstrap.md b/docs/book/src/developer/core/controllers/bootstrap.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/bootstrap.md rename to docs/book/src/developer/core/controllers/bootstrap.md diff --git a/docs/book/src/developer/architecture/controllers/cluster-resource-set.md b/docs/book/src/developer/core/controllers/cluster-resource-set.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/cluster-resource-set.md rename to docs/book/src/developer/core/controllers/cluster-resource-set.md diff --git a/docs/book/src/developer/architecture/controllers/cluster-topology.md b/docs/book/src/developer/core/controllers/cluster-topology.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/cluster-topology.md rename to docs/book/src/developer/core/controllers/cluster-topology.md diff --git a/docs/book/src/developer/architecture/controllers/cluster.md b/docs/book/src/developer/core/controllers/cluster.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/cluster.md rename to docs/book/src/developer/core/controllers/cluster.md diff --git a/docs/book/src/developer/architecture/controllers/control-plane.md b/docs/book/src/developer/core/controllers/control-plane.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/control-plane.md rename to docs/book/src/developer/core/controllers/control-plane.md diff --git a/docs/book/src/developer/architecture/controllers/machine-deployment.md b/docs/book/src/developer/core/controllers/machine-deployment.md similarity index 91% rename from docs/book/src/developer/architecture/controllers/machine-deployment.md rename to docs/book/src/developer/core/controllers/machine-deployment.md index 4554e24e48d8..9161e37e2163 100644 --- a/docs/book/src/developer/architecture/controllers/machine-deployment.md +++ b/docs/book/src/developer/core/controllers/machine-deployment.md @@ -1,6 +1,6 @@ # MachineDeployment -A MachineDeployment orchestrates deployments over a fleet of [MachineSets](./machine-set.md). +A MachineDeployment orchestrates deployments over a fleet of MachineSets. Its main responsibilities are: * Adopting matching MachineSets not assigned to a MachineDeployment diff --git a/docs/book/src/developer/architecture/controllers/machine-health-check.md b/docs/book/src/developer/core/controllers/machine-health-check.md similarity index 80% rename from docs/book/src/developer/architecture/controllers/machine-health-check.md rename to docs/book/src/developer/core/controllers/machine-health-check.md index 43f1deb93777..d26eb12c9667 100644 --- a/docs/book/src/developer/architecture/controllers/machine-health-check.md +++ b/docs/book/src/developer/core/controllers/machine-health-check.md @@ -1,6 +1,6 @@ # MachineHealthCheck -A MachineHealthCheck is responsible for remediating unhealthy [Machines](./machine.md). +A MachineHealthCheck is responsible for remediating unhealthy Machines. Its main responsibilities are: * Checking the health of Nodes in the [workload clusters] against a list of unhealthy conditions diff --git a/docs/book/src/developer/architecture/controllers/machine-pool.md b/docs/book/src/developer/core/controllers/machine-pool.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/machine-pool.md rename to docs/book/src/developer/core/controllers/machine-pool.md diff --git a/docs/book/src/developer/architecture/controllers/machine-set.md b/docs/book/src/developer/core/controllers/machine-set.md similarity index 94% rename from docs/book/src/developer/architecture/controllers/machine-set.md rename to docs/book/src/developer/core/controllers/machine-set.md index 58ba11383f1b..52a17c9c5df2 100644 --- a/docs/book/src/developer/architecture/controllers/machine-set.md +++ b/docs/book/src/developer/core/controllers/machine-set.md @@ -1,6 +1,6 @@ # MachineSet -A MachineSet is an abstraction over [Machines](./machine.md). +A MachineSet is an abstraction over Machines. Its main responsibilities are: * Adopting unowned Machines that aren't assigned to a MachineSet diff --git a/docs/book/src/developer/architecture/controllers/machine.md b/docs/book/src/developer/core/controllers/machine.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/machine.md rename to docs/book/src/developer/core/controllers/machine.md diff --git a/docs/book/src/developer/core/controllers/overview.md b/docs/book/src/developer/core/controllers/overview.md new file mode 100644 index 000000000000..1d8e0658ffb6 --- /dev/null +++ b/docs/book/src/developer/core/controllers/overview.md @@ -0,0 +1,18 @@ +# Controllers + +This section of the book provides an overview about "core" controllers in Cluster API. + + diff --git a/docs/book/src/developer/e2e.md b/docs/book/src/developer/core/e2e.md similarity index 96% rename from docs/book/src/developer/e2e.md rename to docs/book/src/developer/core/e2e.md index c5725b22e735..76204f5bd3e9 100644 --- a/docs/book/src/developer/e2e.md +++ b/docs/book/src/developer/core/e2e.md @@ -50,10 +50,10 @@ Using the config file it is possible to: - Define the list of providers to be installed in the management cluster. Most notably, for each provider it is possible to define: - - One or more versions of the providers manifest (built from the sources, or pulled from a - remote location). - - A list of additional files to be added to the provider repository, to be used e.g. - to provide `cluster-templates.yaml` files. + - One or more versions of the providers manifest (built from the sources, or pulled from a + remote location). + - A list of additional files to be added to the provider repository, to be used e.g. + to provide `cluster-templates.yaml` files. - Define the list of variables to be used when doing `clusterctl init` or `clusterctl generate cluster`. - Define a list of intervals to be used in the test specs for defining timeouts for the @@ -135,7 +135,7 @@ defined in the [Cluster API test framework] to check if the operation completed ### Naming the test spec -You can categorize the test with a custom label that can be used to filter a category of E2E tests to be run. Currently, the cluster-api codebase has [these labels](./testing.md#running-specific-tests) which are used to run a focused subset of tests. +You can categorize the test with a custom label that can be used to filter a category of E2E tests to be run. Currently, the cluster-api codebase has [these labels](testing.md#running-specific-tests) which are used to run a focused subset of tests. ## Tear down @@ -189,7 +189,7 @@ The [test E2E package] provides examples of how this can be achieved by implemen test specs for the most common Cluster API use cases. -[Cluster API quick start]: ../user/quick-start.md +[Cluster API quick start]: ../../user/quick-start.md [Cluster API test framework]: https://pkg.go.dev/sigs.k8s.io/cluster-api/test/framework?tab=doc [Apply method]: https://pkg.go.dev/sigs.k8s.io/cluster-api/test/framework?tab=doc#Applier [CAPA E2E tests]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/scripts/ci-e2e.sh diff --git a/docs/book/src/developer/logging.md b/docs/book/src/developer/core/logging.md similarity index 94% rename from docs/book/src/developer/logging.md rename to docs/book/src/developer/core/logging.md index 5ab476189baa..395beb2f0f7f 100644 --- a/docs/book/src/developer/logging.md +++ b/docs/book/src/developer/core/logging.md @@ -16,7 +16,7 @@ In Cluster API we strive to follow three principles while implementing logging: ## Upstream Alignment -Kubernetes defines a set of [logging conventions](https://git.k8s.io/community/contributors/devel/sig-instrumentation/logging.md), +Kubernetes defines a set of [logging conventions](https://git.k8s.io/community/contributors/devel/sig-instrumentation/logging.md), as well as tools and libraries for logging. ## Continuous improvement @@ -28,8 +28,8 @@ The foundational items of Cluster API logging are: - Adding a minimal set of key/value pairs in the logger at the beginning of each reconcile loop, so all the subsequent log entries will inherit them (see [key value pairs](#keyvalue-pairs)). -Starting from the above foundations, then the long tail of small improvements will consist of following activities: - +Starting from the above foundations, then the long tail of small improvements will consist of following activities: + - Improve consistency of additional key/value pairs added by single log entries (see [key value pairs](#keyvalue-pairs)). - Improve log messages (see [log messages](#log-messages)). - Improve consistency of log levels (see [log levels](#log-levels)). @@ -37,7 +37,7 @@ Starting from the above foundations, then the long tail of small improvements wi ## Log Format Controllers MUST provide support for [structured logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) -and for the [JSON output format](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging#json-output-format); +and for the [JSON output format](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging#json-output-format); quoting the Kubernetes documentation, these are the key elements of this approach: - Separate a log message from its arguments. @@ -61,7 +61,7 @@ beginning of the chain are then inherited by all the subsequent log entries crea Contextual logging is also embedded in controller runtime; In Cluster API we use contextual logging via controller runtime's `LoggerFrom(ctx)` and `LoggerInto(ctx, log)` primitives and this ensures that: -- The logger passed to each reconcile call has a unique `reconcileID`, so all the logs being written during a single +- The logger passed to each reconcile call has a unique `reconcileID`, so all the logs being written during a single reconcile call can be easily identified (note: controller runtime also adds other useful key value pairs by default). - The logger has a key value pair identifying the objects being reconciled,e.g. a Machine Deployment, so all the logs impacting this object can be easily identified. @@ -85,10 +85,10 @@ one of the above practices is really important for Cluster API developers - Developers MUST use `klog.KObj` or `klog.KRef` functions when logging key value pairs for Kubernetes objects, thus ensuring a key value pair representing a Kubernetes object is formatted consistently in all the logs. - Developers MUST use consistent log keys: - - kinds should be written in upper camel case, e.g. `MachineDeployment`, `MachineSet` - - Note: we cannot use lower camel case for kinds consistently because there is no way to - automatically calculate the correct log key for provider CRDs like `AWSCluster` - - all other keys should use lower camel case, e.g. `resourceVersion`, `oldReplicas` to align to Kubernetes log conventions + - kinds should be written in upper camel case, e.g. `MachineDeployment`, `MachineSet` + - Note: we cannot use lower camel case for kinds consistently because there is no way to + automatically calculate the correct log key for provider CRDs like `AWSCluster` + - all other keys should use lower camel case, e.g. `resourceVersion`, `oldReplicas` to align to Kubernetes log conventions Please note that, in order to ensure logs can be easily searched it is important to ensure consistency for the following key value pairs (in order of importance): @@ -96,7 +96,7 @@ key value pairs (in order of importance): - Key value pairs identifying the object being reconciled, e.g. a MachineDeployment. - Key value pairs identifying the hierarchy of objects being reconciled, e.g. the Cluster a MachineDeployment belongs to. -- Key value pairs identifying side effects on other objects, e.g. while reconciling a MachineDeployment, the controller +- Key value pairs identifying side effects on other objects, e.g. while reconciling a MachineDeployment, the controller creates a MachineSet. - Other Key value pairs. @@ -117,9 +117,9 @@ for log levels; as a small integration on the above guidelines we would like to - Logs at the lower levels of verbosity (<=3) are meant to document “what happened” by describing how an object status is being changed by controller/reconcilers across subsequent reconciliations; as a rule of thumb, it is reasonable to assume that a person reading those logs has a deep knowledge of how the system works, but it should not be required - for those persons to have knowledge of the codebase. + for those persons to have knowledge of the codebase. - Logs at higher levels of verbosity (>=4) are meant to document “how it happened”, providing insight on thorny parts of - the code; a person reading those logs usually has deep knowledge of the codebase. + the code; a person reading those logs usually has deep knowledge of the codebase. - Don’t use verbosity higher than 5. We are using log level 2 as a default verbosity for all core Cluster API @@ -140,7 +140,7 @@ Our [Tilt](tilt.md) setup offers a batteries-included log suite based on [Promta We are working to continuously improving this experience, allowing Cluster API developers to use logs and improve them as part of their development process. For the best experience exploring the logs using Tilt: -1. Set `--logging-format=json`. +1. Set `--logging-format=json`. 2. Set a high log verbosity, e.g. `v=5`. 3. Enable Promtail, Loki, and Grafana under `deploy_observability`. @@ -168,7 +168,7 @@ extra_args: - "--v=5" - "--logging-format=json" ``` -The above options can be combined with other settings from our [Tilt](tilt.md) setup. Once Tilt is up and running with these settings users will be able to browse logs using the Grafana Explore UI. +The above options can be combined with other settings from our [Tilt](tilt.md) setup. Once Tilt is up and running with these settings users will be able to browse logs using the Grafana Explore UI. This will normally be available on `localhost:3001`. To explore logs from Loki, open the Explore interface for the DataSource 'Loki'. [This link](http://localhost:3001/explore?datasource%22:%22Loki%22) should work as a shortcut with the default Tilt settings. @@ -220,4 +220,3 @@ we encourage providers to adopt and contribute to the guidelines defined in this It is also worth noting that the foundational elements of the approach described in this document are easy to achieve by leveraging default Kubernetes tooling for logging. - diff --git a/docs/book/src/developer/architecture/controllers/multi-tenancy.md b/docs/book/src/developer/core/multi-tenancy.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/multi-tenancy.md rename to docs/book/src/developer/core/multi-tenancy.md diff --git a/docs/book/src/developer/core/overview.md b/docs/book/src/developer/core/overview.md new file mode 100644 index 000000000000..1be8a6ff741b --- /dev/null +++ b/docs/book/src/developer/core/overview.md @@ -0,0 +1,16 @@ +# Developing "core" Cluster API + +This section of the book is about developing "core" Cluster API. + +With "core" Cluster API we refer to the common set of API and controllers that are required to run +any Cluster API provider. + +Please note that in the Cluster API code base, side by side of "core" Cluster API components there +is also a limited number of in-tree providers: + +- Kubeadm bootstrap provider (CAPBK) +- Kubeadm control plane provider (KCP) +- Docker infrastructure provider (CAPD) - The Docker provider is not designed for production use and is intended for development & test only. +- In Memory infrastructure provider (CAPIM) - The In Memory provider is not designed for production use and is intended for development & test only. + +Please refer to [Developing providers](../providers/overview.md) for documentation about in-tree providers (and out of tree providers too). diff --git a/docs/book/src/developer/repository-layout.md b/docs/book/src/developer/core/repository-layout.md similarity index 98% rename from docs/book/src/developer/repository-layout.md rename to docs/book/src/developer/core/repository-layout.md index 69401542c7e1..ae8eed27c1e3 100644 --- a/docs/book/src/developer/repository-layout.md +++ b/docs/book/src/developer/core/repository-layout.md @@ -53,13 +53,13 @@ This folder contains Cluster API bootstrap provider Kubeadm (CABPK) which is a [~/controlplane](https://github.com/kubernetes-sigs/cluster-api/tree/main/controlplane) -This folder contains a reference implementation of a Cluster API Control Plane provider - KubeadmControlPlane. This package contains the API types and controllers required to instantiate and manage a Kubernetes control plane. It is built and deployed as an independent provider alongside the Cluster API controller manager. +This folder contains a reference implementation of a Cluster API Control Plane provider - KubeadmControlPlane. This package contains the API types and controllers required to instantiate and manage a Kubernetes control plane. It is built and deployed as an independent provider alongside the Cluster API controller manager. -### Cluster API Provider Docker +### Cluster API Provider Docker [~/test/infrastructure/docker](https://github.com/kubernetes-sigs/cluster-api/tree/main/test/infrastructure/docker) -This folder contains a reference implementation of an infrastructure provider for the Cluster API project using Docker. This provider is intended for development purposes only. +This folder contains a reference implementation of an infrastructure provider for the Cluster API project using Docker. This provider is intended for development purposes only. ### Clusterctl CLI @@ -77,11 +77,11 @@ Some of the subfolders are: * [~/config/certmanager](https://github.com/kubernetes-sigs/cluster-api/tree/main/config/certmanager) - It contains manifests like self-signed issuer CR and certificate CR useful for cert manager. * [~/config/crd](https://github.com/kubernetes-sigs/cluster-api/tree/main/config/crd) - It contains CRDs generated from types defined in [api](#api) folder - + * [~/config/manager](https://github.com/kubernetes-sigs/cluster-api/tree/main/config/manager) - It contains manifest for the deployment of core Cluster API manager. - + * [~/config/rbac](https://github.com/kubernetes-sigs/cluster-api/tree/main/config/rbac) - Manifests for RBAC resources generated from kubebuilder markers defined in controllers. - + * [~/config/webhook](https://github.com/kubernetes-sigs/cluster-api/tree/main/config/webhook) - Manifest for webhooks generated from the markers defined in the web hook implementations present in [api](#api) folder. Note: Additional `config` containing manifests can be found in the packages for [KubeadmControlPlane](#controlplane), [KubeadmBoostrap](#bootstrap) and [Cluster API Provider Docker](#cluster-api-provider-docker). @@ -148,7 +148,7 @@ The [api](#api) folder contains webhooks consisting of validators and defaults f [~/internal/webhooks](https://github.com/kubernetes-sigs/cluster-api/tree/main/internal/webhooks) -This directory contains the implementation of some of the Cluster API webhooks. The internal implementation means that the methods supplied by this package cannot be imported by external code bases. +This directory contains the implementation of some of the Cluster API webhooks. The internal implementation means that the methods supplied by this package cannot be imported by external code bases. [~/webhooks](https://github.com/kubernetes-sigs/cluster-api/tree/main/webhooks) diff --git a/docs/book/src/developer/architecture/controllers/support-multiple-instances.md b/docs/book/src/developer/core/support-multiple-instances.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/support-multiple-instances.md rename to docs/book/src/developer/core/support-multiple-instances.md diff --git a/docs/book/src/developer/testing.md b/docs/book/src/developer/core/testing.md similarity index 96% rename from docs/book/src/developer/testing.md rename to docs/book/src/developer/core/testing.md index 7c8333566c01..58d1a25d64e2 100644 --- a/docs/book/src/developer/testing.md +++ b/docs/book/src/developer/core/testing.md @@ -27,8 +27,8 @@ if this is not possible, a viable solution is to use mocks (e.g CAPA). ### Generic providers When writing tests core Cluster API contributors should ensure that the code works with any providers, and thus it is required -to not use any specific provider implementation. Instead, the so-called generic providers e.g. "GenericInfrastructureCluster" -should be used because they implement the plain Cluster API contract. This prevents tests from relying on assumptions that +to not use any specific provider implementation. Instead, the so-called generic providers e.g. "GenericInfrastructureCluster" +should be used because they implement the plain Cluster API contract. This prevents tests from relying on assumptions that may not hold true in all cases. Please note that in the long term we would like to improve the implementation of generic providers, centralizing @@ -46,18 +46,18 @@ the test cluster. With this approach it is possible to interact with Cluster API almost like in a real environment, by creating/updating Kubernetes objects and waiting for the controllers to take action. See the [quick reference](#quick-reference) below for more details. -Also in case of integration tests, considerations about [mocking external APIs](#mocking-external-apis) and usage of [generic providers](#generic-providers) apply. +Also in case of integration tests, considerations about [mocking external APIs](#mocking-external-apis) and usage of [generic providers](#generic-providers) apply. ## Fuzzing tests -Fuzzing tests automatically inject randomly generated inputs, often invalid or with unexpected values, into functions to discover vulnerabilities. +Fuzzing tests automatically inject randomly generated inputs, often invalid or with unexpected values, into functions to discover vulnerabilities. Two different types of fuzzing are currently being used on the Cluster API repository: ### Fuzz testing for API conversion Cluster API uses Kubernetes' conversion-gen to automate the generation of functions to convert our API objects between versions. These conversion functions are tested using the [FuzzTestFunc util in our conversion utils package](https://github.com/kubernetes-sigs/cluster-api/blob/1ec0cd6174f1b860dc466db587241ea7edea0b9f/util/conversion/conversion.go#L194). -For more information about these conversions see the API conversion code walkthrough in our [video walkthrough series](./guide.md#videos-explaining-capi-architecture-and-code-walkthroughs). +For more information about these conversions see the API conversion code walkthrough in our [video walkthrough series](../getting-started.md#videos-explaining-capi-architecture-and-code-walkthroughs). ### OSS-Fuzz continuous fuzzing @@ -78,7 +78,7 @@ In light of continuing improving our practice around this ambitious goal, we are Each contribution in growing this set of utilities or their adoption across the codebase is more than welcome! -Another consideration that can help in improving test maintainability is the idea of testing "by layers"; this idea could +Another consideration that can help in improving test maintainability is the idea of testing "by layers"; this idea could apply whenever we are testing "higher-level" functions that internally uses one or more "lower-level" functions; in order to avoid writing/maintaining redundant tests, whenever possible contributors should take care of testing _only_ the logic that is implemented in the "higher-level" function, delegating the test function called internally @@ -149,7 +149,7 @@ The following guidelines should be followed when developing E2E tests: - Use the [Cluster API test framework]. - Define test spec reflecting real user workflow, e.g. [Cluster API quick start]. - Unless you are testing provider specific features, ensure your test can run with - different infrastructure providers (see [Writing Portable Tests](./e2e.md#writing-portable-e2e-tests)). + different infrastructure providers (see [Writing Portable Tests](e2e.md#writing-portable-e2e-tests)). See [e2e development] for more information on developing e2e tests for CAPI and external providers. @@ -243,8 +243,8 @@ Execute the run configuration with `Debug`.

Tips

-The e2e tests create a new management cluster with kind on each run. To avoid this and speed up the test execution the tests can -also be run against a management cluster created by [tilt](./tilt.md): +The e2e tests create a new management cluster with kind on each run. To avoid this and speed up the test execution the tests can +also be run against a management cluster created by [tilt](tilt.md): ```bash # Prereqs for e2e testing with tilt make tilt-e2e-prerequisites @@ -254,10 +254,10 @@ make tilt-up Now you can start the e2e test via IDE as described above but with the additional `-e2e.use-existing-cluster=true` flag. -**Note**: This can also be used to debug controllers during e2e tests as described in [Developing Cluster API with Tilt](./tilt.md#wiring-up-debuggers). +**Note**: This can also be used to debug controllers during e2e tests as described in [Developing Cluster API with Tilt](tilt.md#wiring-up-debuggers). -The e2e tests also create a local clusterctl repository. After it has been created on a first test execution this step can also be -skipped by setting `-e2e.clusterctl-config=/repository/clusterctl-config.yaml`. This also works with a clusterctl repository created +The e2e tests also create a local clusterctl repository. After it has been created on a first test execution this step can also be +skipped by setting `-e2e.clusterctl-config=/repository/clusterctl-config.yaml`. This also works with a clusterctl repository created via [Create the local repository](http://localhost:3000/clusterctl/developers.html#create-the-local-repository). **Feature gates**: E2E tests often use features which need to be enabled first. Make sure to enable the feature gates in the tilt settings file: @@ -307,7 +307,7 @@ Furthermore, it's possible to overwrite all env variables specified in `variable Logs of e2e tests can be analyzed with our development environment by pushing logs to Loki and then analyzing them via Grafana. -1. Start the development environment as described in [Developing Cluster API with Tilt](./tilt.md). +1. Start the development environment as described in [Developing Cluster API with Tilt](tilt.md). * Make sure to deploy Loki and Grafana via `deploy_observability`. * If you only want to see imported logs, don't deploy promtail (via `deploy_observability`). * If you want to drop all logs from Loki, just delete the Loki Pod in the `observability` namespace. @@ -351,10 +351,10 @@ As alternative to loki, JSON logs can be visualized with a human readable timest The `(. | tostring)` part could also be customized to only output parts of the JSON logline. E.g.: - - * `(.err)` to only output the error message part. - * `(.msg)` to only output the message part. - * `(.controller + " " + .msg)` to output the controller name and message part. + + * `(.err)` to only output the error message part. + * `(.msg)` to only output the message part. + * `(.controller + " " + .msg)` to output the controller name and message part. ### Known Issues @@ -404,7 +404,7 @@ func TestMain(m *testing.M) { ``` Most notably, [envtest] provides not only a real API server to use during testing, but it offers the opportunity -to configure one or more controllers to run against the test cluster, as well as creating informers index. +to configure one or more controllers to run against the test cluster, as well as creating informers index. ```golang func TestMain(m *testing.M) { @@ -439,8 +439,8 @@ should take care in ensuring each test runs in isolation from the others, by: - Avoiding object name conflict. Developers should also be aware of the fact that the informers cache used to access the [envtest] -depends on actual etcd watches/API calls for updates, and thus it could happen that after creating -or deleting objects the cache takes a few milliseconds to get updated. This can lead to test flakes, +depends on actual etcd watches/API calls for updates, and thus it could happen that after creating +or deleting objects the cache takes a few milliseconds to get updated. This can lead to test flakes, and thus it always recommended to use patterns like create and wait or delete and wait; Cluster API env test provides a set of utils for this scope. @@ -529,7 +529,7 @@ comes with a set of limitations that could hamper the validity of a test, most n of the test objects. - the [fakeclient] does not use a cache based on informers/API calls/etcd watches, so the test written in this way can't help in surfacing race conditions related to how those components behave in real cluster. -- there is no support for cache index/operations using cache indexes. +- there is no support for cache index/operations using cache indexes. Accordingly, using [fakeclient] is not suitable for all the use cases, so in some cases contributors will be required to use [envtest] instead. In case of doubts about which one to use when writing tests, don't hesitate to ask for @@ -551,9 +551,9 @@ which is considered unintuitive. ### `gomega` [Gomega] is a matcher/assertion library. It is usually paired with the Ginkgo BDD test framework, but it can be used with - other test frameworks too. +other test frameworks too. - More specifically, in order to use Gomega with go test you should +More specifically, in order to use Gomega with go test you should ```golang func TestFarmHasCow(t *testing.T) { @@ -570,9 +570,9 @@ In Cluster API all the test MUST use [Gomega] assertions. In Cluster API Unit and integration test MUST use [go test]. -[Cluster API quick start]: ../user/quick-start.md +[Cluster API quick start]: ../../user/quick-start.md [Cluster API test framework]: https://pkg.go.dev/sigs.k8s.io/cluster-api/test/framework?tab=doc -[e2e development]: ./e2e.md +[e2e development]: e2e.md [Ginkgo]: https://onsi.github.io/ginkgo/ [Gomega]: https://onsi.github.io/gomega/ [go test]: https://golang.org/pkg/testing/ diff --git a/docs/book/src/developer/tilt.md b/docs/book/src/developer/core/tilt.md similarity index 84% rename from docs/book/src/developer/tilt.md rename to docs/book/src/developer/core/tilt.md index 14cddeb0a263..656b70dbb12f 100644 --- a/docs/book/src/developer/tilt.md +++ b/docs/book/src/developer/core/tilt.md @@ -46,7 +46,7 @@ enable_providers: - kubeadm-control-plane ``` -To use tilt to launch a provider with its own repo, using Cluster API Provider AWS here, `tilt-settings.yaml` should look like: +To use tilt to launch a provider with its own repo, using Cluster API Provider AWS here, `tilt-settings.yaml` should look like: ```yaml default_registry: gcr.io/your-project-name-here @@ -128,20 +128,20 @@ kustomize_substitutions: An Azure Service Principal is needed for populating the controller manifests. This utilizes [environment-based authentication](https://docs.microsoft.com/en-us/go/azure/azure-sdk-go-authorization#use-environment-based-authentication). - 1. Save your Subscription ID +1. Save your Subscription ID ```bash AZURE_SUBSCRIPTION_ID=$(az account show --query id --output tsv) az account set --subscription $AZURE_SUBSCRIPTION_ID ``` - 2. Set the Service Principal name +2. Set the Service Principal name ```bash AZURE_SERVICE_PRINCIPAL_NAME=ServicePrincipalName ``` - 3. Save your Tenant ID, Client ID, Client Secret +3. Save your Tenant ID, Client ID, Client Secret ```bash AZURE_TENANT_ID=$(az account show --query tenantId --output tsv) @@ -200,15 +200,15 @@ Important! This feature requires the `helm` command to be available in the user' Supported values are: - * `grafana`*: To create dashboards and query `loki`, `prometheus` and `tempo`. - * `kube-state-metrics`: For exposing metrics for Kubernetes and CAPI resources to `prometheus`. - * `loki`: To receive and store logs. - * `metrics-server`: To enable `kubectl top node/pod`. - * `prometheus`*: For collecting metrics from Kubernetes. - * `promtail`: For providing pod logs to `loki`. - * `parca`*: For visualizing profiling data. - * `tempo`: To store traces. - * `visualizer`*: Visualize Cluster API resources for each cluster, provide quick access to the specs and status of any resource. +* `grafana`*: To create dashboards and query `loki`, `prometheus` and `tempo`. +* `kube-state-metrics`: For exposing metrics for Kubernetes and CAPI resources to `prometheus`. +* `loki`: To receive and store logs. +* `metrics-server`: To enable `kubectl top node/pod`. +* `prometheus`*: For collecting metrics from Kubernetes. +* `promtail`: For providing pod logs to `loki`. +* `parca`*: For visualizing profiling data. +* `tempo`: To store traces. +* `visualizer`*: Visualize Cluster API resources for each cluster, provide quick access to the specs and status of any resource. \*: Note: the UI will be accessible via a link in the tilt console @@ -223,63 +223,63 @@ additional_kustomizations: Supported settings: - * **port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will run the provider with delve +* **port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will run the provider with delve and port forward the delve server to localhost on the specified debug port. This can then be used with IDEs such as Visual Studio Code, Goland and IntelliJ. - * **continue** (bool, default=true): By default, Tilt will run delve with `--continue`, such that any provider with - debugging turned on will run normally unless specifically having a breakpoint entered. Change to false if you - do not want the controller to start at all by default. +* **continue** (bool, default=true): By default, Tilt will run delve with `--continue`, such that any provider with + debugging turned on will run normally unless specifically having a breakpoint entered. Change to false if you + do not want the controller to start at all by default. - * **profiler_port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will enable the profiler with +* **profiler_port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will enable the profiler with `--profiler-address` and set up a port forward. A "profiler" link will be visible in the Tilt Web UI for the controller. - * **metrics_port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will port forward to the - default metrics port. A "metrics" link will be visible in the Tilt Web UI for the controller. - - * **race_detector** (bool, default=false) (Linux amd64 only): If enabled, Tilt will compile the specified controller with - cgo and statically compile in the system glibc and enable the race detector. Currently, this is only supported when - building on Linux amd64 systems. You must install glibc-static or have libc.a available for this to work. - - Example: Using the configuration below: - - ```yaml - debug: - core: - continue: false - port: 30000 - profiler_port: 40000 - metrics_port: 40001 - ``` - - ##### Wiring up debuggers - ###### Visual Studio - When using the example above, the core CAPI controller can be debugged in Visual Studio Code using the following launch configuration: - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "name": "Core CAPI Controller", - "type": "go", - "request": "attach", - "mode": "remote", - "remotePath": "", - "port": 30000, - "host": "127.0.0.1", - "showLog": true, - "trace": "log", - "logOutput": "rpc" - } - ] - } - ``` - - ###### Goland / IntelliJ - With the above example, you can configure [a Go Remote run/debug - configuration](https://www.jetbrains.com/help/go/attach-to-running-go-processes-with-debugger.html#step-3-create-the-remote-run-debug-configuration-on-the-client-computer) - pointing at port 30000. +* **metrics_port** (int, default=0 (disabled)): If set to anything other than 0, then Tilt will port forward to the + default metrics port. A "metrics" link will be visible in the Tilt Web UI for the controller. + +* **race_detector** (bool, default=false) (Linux amd64 only): If enabled, Tilt will compile the specified controller with + cgo and statically compile in the system glibc and enable the race detector. Currently, this is only supported when + building on Linux amd64 systems. You must install glibc-static or have libc.a available for this to work. + + Example: Using the configuration below: + + ```yaml + debug: + core: + continue: false + port: 30000 + profiler_port: 40000 + metrics_port: 40001 + ``` + + ##### Wiring up debuggers + ###### Visual Studio + When using the example above, the core CAPI controller can be debugged in Visual Studio Code using the following launch configuration: + + ```json + { + "version": "0.2.0", + "configurations": [ + { + "name": "Core CAPI Controller", + "type": "go", + "request": "attach", + "mode": "remote", + "remotePath": "", + "port": 30000, + "host": "127.0.0.1", + "showLog": true, + "trace": "log", + "logOutput": "rpc" + } + ] + } + ``` + + ###### Goland / IntelliJ + With the above example, you can configure [a Go Remote run/debug + configuration](https://www.jetbrains.com/help/go/attach-to-running-go-processes-with-debugger.html#step-3-create-the-remote-run-debug-configuration-on-the-client-computer) + pointing at port 30000.
@@ -365,7 +365,7 @@ some of the clusterctl commands like clusterctl config won't work. This limitation is an acceptable trade-off while executing fast dev-test iterations on controllers logic. If instead you are interested in testing clusterctl workflows, you should refer to the -[clusterctl developer instructions](../clusterctl/developers.md). +[clusterctl developer instructions](../../clusterctl/developers.md). ## Available providers @@ -407,7 +407,7 @@ build it. **live_reload_deps**: a list of files/directories to watch. If any of them changes, Tilt rebuilds the manager binary for the provider and performs a live update of the running container. -**version**: allows to define the version to be used for the Provider CR. If empty, a default version will +**version**: allows to define the version to be used for the Provider CR. If empty, a default version will be used. **additional_docker_helper_commands** (String, default=""): Additional commands to be run in the helper image @@ -497,12 +497,12 @@ syntax highlighting and auto-formatting. To enable it for Tiltfile a file associ [Podman](https://podman.io) can be used instead of Docker by following these actions: 1. Enable the podman unix socket: - - on Linux/systemd: `systemctl --user enable --now podman.socket` - - on macOS: create a podman machine with `podman machine init` + - on Linux/systemd: `systemctl --user enable --now podman.socket` + - on macOS: create a podman machine with `podman machine init` 1. Set `build_engine` to `podman` in `tilt-settings.yaml` (optional, only if both Docker & podman are installed) 1. Define the env variable `DOCKER_HOST` to the right socket: - - on Linux/systemd: `export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock` - - on macOS: `export DOCKER_HOST=$(podman machine inspect | jq -r '.[0].ConnectionInfo.PodmanSocket.Path')` where `` is the podman machine name + - on Linux/systemd: `export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock` + - on macOS: `export DOCKER_HOST=$(podman machine inspect | jq -r '.[0].ConnectionInfo.PodmanSocket.Path')` where `` is the podman machine name 1. Run `tilt up` NB: The socket defined by `DOCKER_HOST` is used only for the `hack/tools/internal/tilt-prepare` command, the image build is running the `podman build`/`podman push` commands. @@ -549,8 +549,8 @@ Ensure that docker/podman is up and running and your kubernetes cluster is reach - Ensure the docker daemon is running ;) or for podman see [Using Podman](#using-podman) - If a DOCKER_HOST is specified: - - check that the DOCKER_HOST has the correct prefix (usually `unix://`) - - ensure docker/podman is listening on $DOCKER_HOST using `fuser` / `lsof` / `netstat -u` + - check that the DOCKER_HOST has the correct prefix (usually `unix://`) + - ensure docker/podman is listening on $DOCKER_HOST using `fuser` / `lsof` / `netstat -u` ### Errors pulling/pushing to the registry diff --git a/docs/book/src/developer/architecture/controllers/tuning.md b/docs/book/src/developer/core/tuning.md similarity index 100% rename from docs/book/src/developer/architecture/controllers/tuning.md rename to docs/book/src/developer/core/tuning.md diff --git a/docs/book/src/developer/guide.md b/docs/book/src/developer/getting-started.md similarity index 99% rename from docs/book/src/developer/guide.md rename to docs/book/src/developer/getting-started.md index f32ccec6ff95..12b5b07c5604 100644 --- a/docs/book/src/developer/guide.md +++ b/docs/book/src/developer/getting-started.md @@ -103,7 +103,7 @@ Many of the Cluster API engineers use it for quick iteration. Please see our [Ti [tilt]: https://tilt.dev [capi-dev]: https://github.com/chuckha/capi-dev -[Tilt instructions]: ../developer/tilt.md +[Tilt instructions]: core/tilt.md ## Option 2: The Old-fashioned way @@ -126,7 +126,7 @@ kustomize build test/infrastructure/docker/config/default | ./hack/tools/bin/env Cluster API has a number of test suites available for you to run. Please visit the [testing][testing] page for more information on each suite. -[testing]: ./testing.md +[testing]: core/testing.md ## That's it! diff --git a/docs/book/src/developer/providers/contracts.md b/docs/book/src/developer/providers/contracts.md index 1d374c6e25c4..8a81ef599853 100644 --- a/docs/book/src/developer/providers/contracts.md +++ b/docs/book/src/developer/providers/contracts.md @@ -9,7 +9,7 @@ Cluster API defines the following contracts: - [Control Plane provider contract](./control-plane.md) - [Machine provider contract](./machine-infrastructure.md) - [clusterctl provider contract](../../clusterctl/provider-contract.md#clusterctl-provider-contract) -- [Multi tenancy contract](../../developer/architecture/controllers/multi-tenancy.md#contract) +- [Multi tenancy contract](../core/multi-tenancy.md#contract) ## API version labels Providers MUST set `cluster.x-k8s.io/` label on all Custom Resource Definitions related to Cluster API starting with v1alpha3. diff --git a/docs/book/src/developer/providers/control-plane.md b/docs/book/src/developer/providers/control-plane.md index ce5cefcd6861..036d87a8d923 100644 --- a/docs/book/src/developer/providers/control-plane.md +++ b/docs/book/src/developer/providers/control-plane.md @@ -27,7 +27,7 @@ Kubernetes control plane consisting of the following services: The Cluster controller will set an OwnerReference on the Control Plane. The Control Plane controller should normally take no action during reconciliation until it sees the ownerReference. A Control Plane controller implementation must either supply a controlPlaneEndpoint (via its own `spec.controlPlaneEndpoint` field), -or rely on `spec.controlPlaneEndpoint` in its parent [Cluster](../architecture/controllers/cluster.md) object. +or rely on `spec.controlPlaneEndpoint` in its parent Cluster object. If an endpoint is not provided, the implementer should exit reconciliation until it sees `cluster.spec.controlPlaneEndpoint` populated. diff --git a/docs/book/src/developer/providers/getting-started/building-running-and-testing.md b/docs/book/src/developer/providers/getting-started/building-running-and-testing.md index 0ba218307b5f..36e606720b18 100644 --- a/docs/book/src/developer/providers/getting-started/building-running-and-testing.md +++ b/docs/book/src/developer/providers/getting-started/building-running-and-testing.md @@ -90,7 +90,7 @@ Conditions: Cluster API development requires a lot of iteration, and the "build, tag, push, update deployment" workflow can be very tedious. [Tilt](https://tilt.dev) makes this process much simpler by watching for updates, then automatically building and deploying them. -See [Developing Cluster API with Tilt](../../tilt.md) on all details how to develop both Cluster API and your provider at the same time. In short, you need to perform these steps for a basic Tilt-based development environment: +See [Developing Cluster API with Tilt](../../core/tilt.md) on all details how to develop both Cluster API and your provider at the same time. In short, you need to perform these steps for a basic Tilt-based development environment: - Create file `tilt-provider.yaml` in your provider directory: diff --git a/docs/book/src/reference/api/labels-and-annotations.md b/docs/book/src/reference/api/labels-and-annotations.md index 056744de94ae..57c9c77cdebe 100644 --- a/docs/book/src/reference/api/labels-and-annotations.md +++ b/docs/book/src/reference/api/labels-and-annotations.md @@ -31,7 +31,7 @@ | cluster.x-k8s.io/owner-name | It is set on nodes identifying the machine's owner name the node belongs to. | Cluster API | Nodes | | cluster.x-k8s.io/paused | It can be applied to any Cluster API object to prevent a controller from processing a resource. Controllers working with Cluster API objects must check the existence of this annotation on the reconciled object. | User | Any Cluster API resource | | cluster.x-k8s.io/remediate-machine | It can be applied to a machine to manually mark it for remediation by MachineHealthCheck reconciler. | User | Machine | -| cluster.x-k8s.io/replicas-managed-by | It can be applied to MachinePool resources to signify that some external system is managing infrastructure scaling for that pool. See [the MachinePool documentation](../../developer/architecture/controllers/machine-pool.md#externally-managed-autoscaler) for more details. | Infrastructure Providers | MachinePool resources | +| cluster.x-k8s.io/replicas-managed-by | It can be applied to MachinePool resources to signify that some external system is managing infrastructure scaling for that pool. See [the MachinePool documentation](../../developer/core/controllers/machine-pool.md#externally-managed-autoscaler) for more details. | Infrastructure Providers | MachinePool resources | | cluster.x-k8s.io/skip-remediation | It is used to mark the machines that should not be considered for remediation by MachineHealthCheck reconciler. | User | Machines | | clusterctl.cluster.x-k8s.io/block-move | BlockMoveAnnotation prevents the cluster move operation from starting if it is defined on at least one of the objects in scope. Provider controllers are expected to set the annotation on resources that cannot be instantaneously paused and remove the annotation when the resource has been actually paused. | Providers | Any Cluster API resource | | clusterctl.cluster.x-k8s.io/delete-for-move | DeleteForMoveAnnotation will be set to objects that are going to be deleted from the source cluster after being moved to the target cluster during the clusterctl move operation. It will help any validation webhook to take decision based on it. | Cluster API | Any Cluster API resource | diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md index 5f82b88d82ac..93cdf63800bb 100644 --- a/docs/book/src/reference/glossary.md +++ b/docs/book/src/reference/glossary.md @@ -37,7 +37,7 @@ See [CABPK](#cabpk). Cluster API Enhancement Proposal - patterned after [KEP](https://git.k8s.io/enhancements/keps/README.md). See [template](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/YYYYMMDD-template.md) ### CAPI -Core Cluster API +[Core Cluster API](#core-cluster-api) ### CAPA Cluster API Provider AWS @@ -72,6 +72,9 @@ Cluster API Provider Hivelocity ### CAPIBM Cluster API Provider IBM Cloud +### CAPIM +Cluster API Provider In Memory + ### CAPIO Cluster API Operator @@ -141,7 +144,7 @@ Or __Cluster API project__ The Cluster API sub-project of the SIG-cluster-lifecycle. It is also used to refer to the software components, APIs, and community that produce them. -See [core provider](#core-provider) +See [Core Cluster API](#core-cluster-api), [CAPI](#capi) ### Cluster API Runtime @@ -174,13 +177,27 @@ Control plane provider's interaction with Cluster API is based on what is define See [KCP](#kcp). +### Core Cluster API + +With "core" Cluster API we refer to the common set of API and controllers that are required to run +any Cluster API provider. + +Please note that in the Cluster API code base, side by side of "core" Cluster API components there +is also a limited number of in-tree providers: [CABPK](#cabpk), [KCP](#kcp), [CAPD](#capd), [CAPIM](#capim) + +See [Cluster API](#cluster-api), [CAPI](#capi). + ### Core provider -Refers to a [provider](#provider) that implements Cluster API core controllers; if you -consider that the first project that must be deployed in a management Cluster is Cluster API itself, it should be clear why -the Cluster API project is also referred to as the core provider. +Refers to a [provider](#provider) that implements Cluster API [core controllers](#core-controllers) + +See [Cluster API](#cluster-api), [CAPI](#capi). + +### Core controllers + +The set of controllers in [Core Cluster API](#core-cluster-api). -See [CAPI](#cluster-api). +See [Cluster API](#cluster-api), [CAPI](#capi). # D --- @@ -310,7 +327,7 @@ one of them corresponding to an infrastructure tenant. Please note that up until v1alpha3 this concept had a different meaning, referring to the capability to run multiple instances of the same provider, each one with its own credentials; starting from v1alpha4 we are disambiguating the two concepts. -See [Multi-tenancy](../developer/architecture/controllers/multi-tenancy.md) and [Support multiple instances](../developer/architecture/controllers/support-multiple-instances.md). +See [Multi-tenancy](../developer/core/multi-tenancy.md) and [Support multiple instances](../developer/core/support-multiple-instances.md). # N --- diff --git a/docs/book/src/tasks/experimental-features/experimental-features.md b/docs/book/src/tasks/experimental-features/experimental-features.md index ced97b4d2a33..36ee84a14e00 100644 --- a/docs/book/src/tasks/experimental-features/experimental-features.md +++ b/docs/book/src/tasks/experimental-features/experimental-features.md @@ -48,7 +48,7 @@ kustomize_substitutions: EXP_MACHINE_SET_PREFLIGHT_CHECKS: 'true' ``` -For more details on setting up a development environment with `tilt`, see [Developing Cluster API with Tilt](../../developer/tilt.md) +For more details on setting up a development environment with `tilt`, see [Developing Cluster API with Tilt](../../developer/core/tilt.md) ## Enabling Experimental Features on Existing Management Clusters diff --git a/docs/book/src/tasks/experimental-features/machine-pools.md b/docs/book/src/tasks/experimental-features/machine-pools.md index 84c15bfc21ec..e8b7290c4620 100644 --- a/docs/book/src/tasks/experimental-features/machine-pools.md +++ b/docs/book/src/tasks/experimental-features/machine-pools.md @@ -13,7 +13,7 @@ Infrastructure providers can support this feature by implementing their specific More details on `MachinePool` can be found at: [MachinePool CAEP](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20190919-machinepool-api.md) -For developer docs on the MachinePool controller, see [here](./../../developer/architecture/controllers/machine-pool.md). +For developer docs on the MachinePool controller, see [here](./../../developer/core/controllers/machine-pool.md). ## MachinePools vs MachineDeployments diff --git a/docs/book/src/tasks/upgrading-clusters.md b/docs/book/src/tasks/upgrading-clusters.md index 00042bc379e5..1bfbfa29a557 100644 --- a/docs/book/src/tasks/upgrading-clusters.md +++ b/docs/book/src/tasks/upgrading-clusters.md @@ -92,5 +92,5 @@ Only values allowed are of type Int or Strings with an integer and percentage sy Changes are rolled out driven by the user or any entity deleting the old `Machines`. Only when a `Machine` is fully deleted a new one will come up. For a more in-depth look at how `MachineDeployments` manage scaling events, take a look at the [`MachineDeployment` -controller documentation](../developer/architecture/controllers/machine-deployment.md) and the [`MachineSet` controller -documentation](../developer/architecture/controllers/machine-set.md). +controller documentation](../developer/core/controllers/machine-deployment.md) and the [`MachineSet` controller +documentation](../developer/core/controllers/machine-set.md). diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md index d7981acdceae..5d7d4ea75cbd 100644 --- a/docs/book/src/user/quick-start.md +++ b/docs/book/src/user/quick-start.md @@ -1823,7 +1823,7 @@ kind delete cluster [infrastructure provider]: ../reference/glossary.md#infrastructure-provider [ionoscloud provider]: https://github.com/ionos-cloud/cluster-api-provider-ionoscloud [kind]: https://kind.sigs.k8s.io/ -[KubeadmControlPlane]: ../developer/architecture/controllers/control-plane.md +[KubeadmControlPlane]: ../developer/core/controllers/control-plane.md [kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ [management cluster]: ../reference/glossary.md#management-cluster [Metal3 getting started guide]: https://github.com/metal3-io/cluster-api-provider-metal3/blob/master/docs/getting-started.md