From dd1c5f1d402f22c6ad8fc7b4a9bfa1fe776b7533 Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Tue, 5 Mar 2024 12:53:13 +0100 Subject: [PATCH 1/4] Add book content Signed-off-by: Danil Grigorev --- .../installation/helm-chart-installation.md | 34 +++++ .../src/installation/manifest-installation.md | 14 +++ docs/book/src/reference/providers.md | 82 ++++++++++++ .../src/topics/air-gapped-environtment.md | 117 ++++++++++++++++++ .../basic-capi-provider-installation.md | 11 ++ .../capi-provides-lifecycle.md | 0 docs/book/src/topics/deleting-provider.md | 7 ++ docs/book/src/topics/deleting-providers.md | 11 ++ .../topics/injecting-additional-manifests.md | 25 ++++ docs/book/src/topics/installing-capz.md | 30 +++++ .../src/topics/installing-core-provider.md | 18 +++ docs/book/src/topics/installing-provider.md | 24 ++++ docs/book/src/topics/modifying-provider.md | 6 + docs/book/src/topics/upgrading-provider.md | 12 ++ 14 files changed, 391 insertions(+) rename docs/book/src/topics/{ => capi-providers-lifecycle}/capi-provides-lifecycle.md (100%) diff --git a/docs/book/src/installation/helm-chart-installation.md b/docs/book/src/installation/helm-chart-installation.md index 639325eb7..fe5ca7e4f 100644 --- a/docs/book/src/installation/helm-chart-installation.md +++ b/docs/book/src/installation/helm-chart-installation.md @@ -1 +1,35 @@ # Using Helm Charts + +Alternatively, you can install the Cluster API operator using Helm charts: + +```bash +helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator +helm repo update +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system +``` + +#### Installing cert-manager using Helm chart + +CAPI operator Helm chart supports provisioning of cert-manager as a dependency. It is disabled by default, but you can enable it with `--set cert-manager.enabled=true` option to `helm install` command or inside of `cert-manager` section in [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml) file. Additionally you can define other [parameters](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration) provided by the cert-manager chart. + +#### Installing providers using Helm chart + +The operator Helm chart supports a "quickstart" option for bootstrapping a management cluster. The user experience is relatively similar to [clusterctl init](https://cluster-api.sigs.k8s.io/clusterctl/commands/init.html?highlight=init#clusterctl-init): + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker:v1.4.2 --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed +``` + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system —set infrastructure="docker;azure" --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed +``` + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system —set infrastructure="capd-custom-ns:docker:v1.4.2;capz-custom-ns:azure:v1.10.0" --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed +``` + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set core=cluster-api:v1.4.2 --set controlPlane=kubeadm:v1.4.2 --set bootstrap=kubeadm:v1.4.2 --set infrastructure=docker:v1.4.2 --wait --timeout 90s +``` + +For more complex operations, please refer to our API documentation. diff --git a/docs/book/src/installation/manifest-installation.md b/docs/book/src/installation/manifest-installation.md index f0def43c7..c30b8c853 100644 --- a/docs/book/src/installation/manifest-installation.md +++ b/docs/book/src/installation/manifest-installation.md @@ -1 +1,15 @@ # Using Manifests from Release Assets + +Before installing the Cluster API Operator this way, you must first ensure that cert-manager is installed, as the operator does not manage cert-manager installations. To install cert-manager, run the following command: + +```bash +kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml +``` + +Wait for cert-manager to be ready before proceeding. + +After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets: + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml +``` diff --git a/docs/book/src/reference/providers.md b/docs/book/src/reference/providers.md index cd5844f79..d35d2e457 100644 --- a/docs/book/src/reference/providers.md +++ b/docs/book/src/reference/providers.md @@ -1 +1,83 @@ # Provider List + +The Cluster API Operator introduces new API types: `CoreProvider`, `BootstrapProvider`, `ControlPlaneProvider`, `InfrastructureProvider`, `AddonProvider` and `IPAMProvider`. These five provider types share common Spec and Status types, `ProviderSpec` and `ProviderStatus`, respectively. + +The CRDs are scoped to be namespaced, allowing RBAC restrictions to be enforced if needed. This scoping also enables the installation of multiple versions of controllers (grouped within namespaces) in the same management cluster. + +Related Golang structs can be found in the [Cluster API Operator repository](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/api/v1alpha1). + +Below are the new API types being defined, with shared types used for Spec and Status among the different provider types—Core, Bootstrap, ControlPlane, and Infrastructure: + +*CoreProvider* + +```golang +type CoreProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ProviderSpec `json:"spec,omitempty"` + Status ProviderStatus `json:"status,omitempty"` +} +``` + +*BootstrapProvider* + +```golang +type BootstrapProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ProviderSpec `json:"spec,omitempty"` + Status ProviderStatus `json:"status,omitempty"` +} +``` + +*ControlPlaneProvider* + +```golang +type ControlPlaneProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ProviderSpec `json:"spec,omitempty"` + Status ProviderStatus `json:"status,omitempty"` +} +``` + +*InfrastructureProvider* + +```golang +type InfrastructureProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ProviderSpec `json:"spec,omitempty"` + Status ProviderStatus `json:"status,omitempty"` +} +``` + +*AddonProvider* + +```golang +type AddonProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec AddonProviderSpec `json:"spec,omitempty"` + Status AddonProviderStatus `json:"status,omitempty"` +} +``` + +*IPAMProvider* + +```golang +type IPAMProvider struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec IPAMProviderSpec `json:"spec,omitempty"` + Status IPAMProviderStatus `json:"status,omitempty"` +} +``` + +The following sections provide details about `ProviderSpec` and `ProviderStatus`, which are shared among all the provider types. diff --git a/docs/book/src/topics/air-gapped-environtment.md b/docs/book/src/topics/air-gapped-environtment.md index c7f70b313..11dfafa36 100644 --- a/docs/book/src/topics/air-gapped-environtment.md +++ b/docs/book/src/topics/air-gapped-environtment.md @@ -1 +1,118 @@ # Air-gapped Environment + +To install Cluster API providers in an air-gapped environment using the operator, address the following issues: + +1. Configure the operator for an air-gapped environment: + - Manually fetch and store a helm chart for the operator. + - Provide image overrides for the operator in from an accessible image repository. +2. Configure providers for an air-gapped environment: + - Provide fetch configuration for each provider from an accessible location (e.g., an internal GitHub repository) or from pre-created ConfigMaps within the cluster. + - Provide image overrides for each provider to pull images from an accessible image repository. + +**Example Usage:** + +As an admin, I need to fetch the Azure provider components from within the cluster because I am working in an air-gapped environment. + +In this example, there is a ConfigMap in the `capz-system` namespace that defines the components and metadata of the provider. + +The Azure InfrastructureProvider is configured with a `fetchConfig` specifying the label selector, allowing the operator to determine the available versions of the Azure provider. Since the provider's version is marked as `v1.9.3`, the operator uses the components information from the ConfigMap with matching label to install the Azure provider. + +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + provider-components: azure + name: v1.9.3 + namespace: capz-system +data: + components: | + # Components for v1.9.3 YAML go here + metadata: | + # Metadata information goes here +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: azure + namespace: capz-system +spec: + version: v1.9.3 + configSecret: + name: azure-variables + fetchConfig: + selector: + matchLabels: + provider-components: azure +``` + +### Situation when manifests do not fit into configmap + +There is a limit on the [maximum size](https://kubernetes.io/docs/concepts/configuration/configmap/#motivation) of a configmap - 1MiB. If the manifests do not fit into this size, Kubernetes will generate an error and provider installation fail. To avoid this, you can archive the manifests and put them in the configmap that way. + +For example, you have two files: `components.yaml` and `metadata.yaml`. To create a working config map you need: + +1. Archive components.yaml using `gzip` cli tool + +```sh +gzip -c components.yaml > components.gz +``` + +2. Create a configmap manifest from the archived data + +```sh +kubectl create configmap v1.9.3 --namespace=capz-system --from-file=components=components.gz --from-file=metadata=metadata.yaml --dry-run=client -o yaml > configmap.yaml +``` + +3. Edit the file by adding "provider.cluster.x-k8s.io/compressed: true" annotation + +```sh +yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml +``` + +**Note**: without this annotation operator won't be able to determine if the data is compressed or not. + +4. Add labels that will be used to match the configmap in `fetchConfig` section of the provider + +```sh +yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml +``` + +5. Create a configmap in your kubernetes cluster using kubectl + +```sh +kubectl create -f configmap.yaml +``` + +## Patching provider manifests + +Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider +manifests `spec.ResourcePatches` has to be used where an array of patches can be specified: + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system +spec: + resourcePatches: + - | +apiVersion: v1 +kind: Service +metadata: +labels: + test-label: test-value +``` + +More information about JSON merge patches can be found here + +There are couple of rules for the patch to match a manifest: + +- The `kind` field must match the target object. +- If `apiVersion` is specified it will only be applied to matching objects. +- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind. +- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects. +- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace. diff --git a/docs/book/src/topics/basic-capi-provider-installation.md b/docs/book/src/topics/basic-capi-provider-installation.md index d73c9988a..09ad2ac95 100644 --- a/docs/book/src/topics/basic-capi-provider-installation.md +++ b/docs/book/src/topics/basic-capi-provider-installation.md @@ -1 +1,12 @@ # Basic Cluster API Provider Installation + +In this section, we will walk you through the basic process of installing Cluster API providers using the operator. The Cluster API operator manages six types of objects: + +- CoreProvider +- BootstrapProvider +- ControlPlaneProvider +- InfrastructureProvider +- AddonProvider +- IPAMProvider + +Please note that this example provides a basic configuration of Azure Infrastructure provider for getting started. More detailed examples and CRD descriptions will be provided in subsequent sections of this document. diff --git a/docs/book/src/topics/capi-provides-lifecycle.md b/docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md similarity index 100% rename from docs/book/src/topics/capi-provides-lifecycle.md rename to docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md diff --git a/docs/book/src/topics/deleting-provider.md b/docs/book/src/topics/deleting-provider.md index f37f1465a..2687a0701 100644 --- a/docs/book/src/topics/deleting-provider.md +++ b/docs/book/src/topics/deleting-provider.md @@ -1 +1,8 @@ # Deleting a Provider + +To remove the installed providers and all related kubernetes objects just delete the following CRs: + +```bash +kubectl delete infrastructureprovider azure +kubectl delete coreprovider cluster-api +``` diff --git a/docs/book/src/topics/deleting-providers.md b/docs/book/src/topics/deleting-providers.md index 5039f1a85..e1f89075c 100644 --- a/docs/book/src/topics/deleting-providers.md +++ b/docs/book/src/topics/deleting-providers.md @@ -1 +1,12 @@ # Deleting providers + +To remove all installed providers and all related kubernetes objects just delete the following CRs: + +```bash +kubectl delete coreprovider --all --all-namespaces +kubectl delete infrastructureprovider --all --all-namespaces +kubectl delete bootstrapprovider --all --all-namespaces +kubectl delete controlplaneprovider --all --all-namespaces +kubectl delete ipamprovider --all --all-namespaces +kubectl delete addonprovider --all --all-namespaces +``` diff --git a/docs/book/src/topics/injecting-additional-manifests.md b/docs/book/src/topics/injecting-additional-manifests.md index 56498f2d0..836ce049c 100644 --- a/docs/book/src/topics/injecting-additional-manifests.md +++ b/docs/book/src/topics/injecting-additional-manifests.md @@ -1 +1,26 @@ # Injecting additional manifests + +It is possible to inject additional manifests when installing/upgrading a provider. This can be useful when you need to add extra RBAC resources to the provider controller, for example. +The field `AdditionalManifests` is a reference to a ConfigMap that contains additional manifests, which will be applied together with the provider components. The key for storing these manifests has to be `manifests`. +The manifests are applied only once when a certain release is installed/upgraded. If the namespace is not specified, the namespace of the provider will be used. There is no validation of the YAML content inside the ConfigMap. + +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: additional-manifests + namespace: capi-system +data: + manifests: | + # Additional manifests go here +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system +spec: + additionalManifests: + name: additional-manifests +``` diff --git a/docs/book/src/topics/installing-capz.md b/docs/book/src/topics/installing-capz.md index a29dc41aa..6fd60d748 100644 --- a/docs/book/src/topics/installing-capz.md +++ b/docs/book/src/topics/installing-capz.md @@ -1 +1,31 @@ # Installing Azure Infrastructure Provider + +Next, install [Azure Infrastructure Provider](https://capz.sigs.k8s.io/). Before that ensure that `capz-system` namespace exists. + +Since the provider requires variables to be set, create a secret containing them in the same namespace as the provider. It is also recommended to include a `github-token` in the secret. This token is used to fetch the provider repository, and it is required for the provider to be installed. The operator may exceed the rate limit of the GitHub API without the token. Like [clusterctl](https://cluster-api.sigs.k8s.io/clusterctl/overview.html?highlight=github_token#avoiding-github-rate-limiting), the token needs only the `repo` scope. + +```yaml +--- +apiVersion: v1 +kind: Secret +metadata: + name: azure-variables + namespace: capz-system +type: Opaque +stringData: + AZURE_CLIENT_ID_B64: Zm9vCg== + AZURE_CLIENT_SECRET_B64: Zm9vCg== + AZURE_SUBSCRIPTION_ID_B64: Zm9vCg== + AZURE_TENANT_ID_B64: Zm9vCg== + github-token: ghp_fff +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha1 +kind: InfrastructureProvider +metadata: + name: azure + namespace: capz-system +spec: + version: v1.9.3 + configSecret: + name: azure-variables +``` diff --git a/docs/book/src/topics/installing-core-provider.md b/docs/book/src/topics/installing-core-provider.md index b01fe9f45..fc9e1134b 100644 --- a/docs/book/src/topics/installing-core-provider.md +++ b/docs/book/src/topics/installing-core-provider.md @@ -1 +1,19 @@ # Installing the CoreProvider + +The first step is to install the CoreProvider, which is responsible for managing the Cluster API CRDs and the Cluster API controller. + +You can utilize any existing namespace for providers in your Kubernetes operator. However, before creating a provider object, make sure the specified namespace has been created. In the example below, we use the `capi-system` namespace. You can create this namespace through either the Command Line Interface (CLI) by running `kubectl create namespace capi-system`, or by using the declarative approach described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/#create-new-namespaces). + +*Example:* + +```yaml +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system +spec: + version: v1.4.3 +``` + +**Note:** Only one CoreProvider can be installed at the same time on a single cluster. diff --git a/docs/book/src/topics/installing-provider.md b/docs/book/src/topics/installing-provider.md index d4169de44..e74d58682 100644 --- a/docs/book/src/topics/installing-provider.md +++ b/docs/book/src/topics/installing-provider.md @@ -1 +1,25 @@ # Installing a Provider + +To install a new Cluster API provider with the Cluster API Operator, create a provider object as shown in the first example API usage for creating the secret with variables and the provider itself. + +The operator processes a provider object by applying the following rules: + +- The CoreProvider is installed first; other providers will be requeued until the core provider exists. +- Before installing any provider, the following pre-flight checks are executed: +- No other instance of the same provider (same Kind, same name) should exist in any namespace. +- The Cluster API contract (e.g., v1beta1) must match the contract of the core provider. +- The operator sets conditions on the provider object to surface any installation issues, including pre-flight checks and/or order of installation. +- If the FetchConfiguration is not defined, the operator applies the embedded fetch configuration for the given kind and `ObjectMeta.Name` specified in the [Cluster API code](https://github.com/kubernetes-sigs/cluster-api/blob/main/cmd/clusterctl/client/config/providers_client.go). + +The installation process, managed by the operator, aligns with the implementation underlying the `clusterctl init` command and includes these steps: + +- Fetching provider artifacts (the components.yaml and metadata.yaml files). +- Applying image overrides, if any. +- Replacing variables in the infrastructure-components from EnvVar and Secret. +- Applying the resulting YAML to the cluster. + +Differences between the operator and `clusterctl init` include: + +- The operator installs one provider at a time while `clusterctl init` installs a group of providers in a single operation. +- The operator stores fetched artifacts in a config map for reuse during subsequent reconciliations. +- The operator uses a Secret, while `clusterctl init` relies on environment variables and a local configuration file. diff --git a/docs/book/src/topics/modifying-provider.md b/docs/book/src/topics/modifying-provider.md index b156e8675..4a1846234 100644 --- a/docs/book/src/topics/modifying-provider.md +++ b/docs/book/src/topics/modifying-provider.md @@ -1 +1,7 @@ # Modifying a Provider + +In addition to changing a provider version (upgrades), the operator supports modifying other provider fields such as controller flags and variables. This can be achieved through `kubectl edit` or `kubectl apply` to the provider object. + +The operation works similarly to upgrades: The current provider instance is deleted while preserving CRDs, namespaces, and user objects. Then, a new provider instance with the updated flags/variables is installed. + +**Note**: `clusterctl` currently does not support this operation. diff --git a/docs/book/src/topics/upgrading-provider.md b/docs/book/src/topics/upgrading-provider.md index af55ff5a6..37dd152ff 100644 --- a/docs/book/src/topics/upgrading-provider.md +++ b/docs/book/src/topics/upgrading-provider.md @@ -1 +1,13 @@ # Upgrading a Provider + +To trigger an upgrade for a Cluster API provider, change the `spec.Version` field. All providers must follow the golden rule of respecting the same Cluster API contract supported by the core provider. + +The operator performs the upgrade by: + +1. Deleting the current provider components, while preserving CRDs, namespaces, and user objects. +2. Installing the new provider components. + +Differences between the operator and `clusterctl upgrade apply` include: + +- The operator upgrades one provider at a time while `clusterctl upgrade apply` upgrades a group of providers in a single operation. +- With the declarative approach, users are responsible for manually editing the Provider objects' YAML, while `clusterctl upgrade apply --contract` automatically determines the latest available versions for each provider. From 065c2b8f50a65e7bc4369d6b609c7a3569b79c76 Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Tue, 5 Mar 2024 13:26:33 +0100 Subject: [PATCH 2/4] Add a configuration section Signed-off-by: Danil Grigorev --- docs/book/src/reference/providers.md | 23 +++ .../basic-capi-provider-installation.md | 12 -- .../deleting-provider.md | 0 .../installing-capz.md | 0 .../installing-core-provider.md | 0 .../installing-provider.md | 0 .../modifying-provider.md | 0 .../upgrading-provider.md | 0 .../air-gapped-environtment.md | 32 ---- .../src/topics/configuration/configuration.md | 153 ++++++++++++++++++ .../configuration/examples-of-api-usage.md | 122 ++++++++++++++ .../injecting-additional-manifests.md | 0 .../patching-provider-manifests.md | 31 ++++ 13 files changed, 329 insertions(+), 44 deletions(-) delete mode 100644 docs/book/src/topics/basic-capi-provider-installation.md rename docs/book/src/topics/{ => capi-providers-lifecycle}/deleting-provider.md (100%) rename docs/book/src/topics/{ => capi-providers-lifecycle}/installing-capz.md (100%) rename docs/book/src/topics/{ => capi-providers-lifecycle}/installing-core-provider.md (100%) rename docs/book/src/topics/{ => capi-providers-lifecycle}/installing-provider.md (100%) rename docs/book/src/topics/{ => capi-providers-lifecycle}/modifying-provider.md (100%) rename docs/book/src/topics/{ => capi-providers-lifecycle}/upgrading-provider.md (100%) rename docs/book/src/topics/{ => configuration}/air-gapped-environtment.md (72%) create mode 100644 docs/book/src/topics/configuration/configuration.md create mode 100644 docs/book/src/topics/configuration/examples-of-api-usage.md rename docs/book/src/topics/{ => configuration}/injecting-additional-manifests.md (100%) create mode 100644 docs/book/src/topics/configuration/patching-provider-manifests.md diff --git a/docs/book/src/reference/providers.md b/docs/book/src/reference/providers.md index d35d2e457..d4836b98e 100644 --- a/docs/book/src/reference/providers.md +++ b/docs/book/src/reference/providers.md @@ -81,3 +81,26 @@ type IPAMProvider struct { ``` The following sections provide details about `ProviderSpec` and `ProviderStatus`, which are shared among all the provider types. + +## Provider Status + +`ProviderStatus`: observed state of the Provider, consisting of: + +- Contract (optional string): core provider contract being adhered to (e.g., "v1beta1") +- Conditions (optional clusterv1.Conditions): current service state of the provider +- ObservedGeneration (optional int64): latest generation observed by the controller +- InstalledVersion (optional string): version of the provider that is installed + + YAML example: + + ```yaml + status: + contract: "v1beta1" + conditions: + - type: "Ready" + status: "True" + reason: "ProviderAvailable" + message: "Provider is available and ready" + observedGeneration: 1 + installedVersion: "v0.1.0" + ``` diff --git a/docs/book/src/topics/basic-capi-provider-installation.md b/docs/book/src/topics/basic-capi-provider-installation.md deleted file mode 100644 index 09ad2ac95..000000000 --- a/docs/book/src/topics/basic-capi-provider-installation.md +++ /dev/null @@ -1,12 +0,0 @@ -# Basic Cluster API Provider Installation - -In this section, we will walk you through the basic process of installing Cluster API providers using the operator. The Cluster API operator manages six types of objects: - -- CoreProvider -- BootstrapProvider -- ControlPlaneProvider -- InfrastructureProvider -- AddonProvider -- IPAMProvider - -Please note that this example provides a basic configuration of Azure Infrastructure provider for getting started. More detailed examples and CRD descriptions will be provided in subsequent sections of this document. diff --git a/docs/book/src/topics/deleting-provider.md b/docs/book/src/topics/capi-providers-lifecycle/deleting-provider.md similarity index 100% rename from docs/book/src/topics/deleting-provider.md rename to docs/book/src/topics/capi-providers-lifecycle/deleting-provider.md diff --git a/docs/book/src/topics/installing-capz.md b/docs/book/src/topics/capi-providers-lifecycle/installing-capz.md similarity index 100% rename from docs/book/src/topics/installing-capz.md rename to docs/book/src/topics/capi-providers-lifecycle/installing-capz.md diff --git a/docs/book/src/topics/installing-core-provider.md b/docs/book/src/topics/capi-providers-lifecycle/installing-core-provider.md similarity index 100% rename from docs/book/src/topics/installing-core-provider.md rename to docs/book/src/topics/capi-providers-lifecycle/installing-core-provider.md diff --git a/docs/book/src/topics/installing-provider.md b/docs/book/src/topics/capi-providers-lifecycle/installing-provider.md similarity index 100% rename from docs/book/src/topics/installing-provider.md rename to docs/book/src/topics/capi-providers-lifecycle/installing-provider.md diff --git a/docs/book/src/topics/modifying-provider.md b/docs/book/src/topics/capi-providers-lifecycle/modifying-provider.md similarity index 100% rename from docs/book/src/topics/modifying-provider.md rename to docs/book/src/topics/capi-providers-lifecycle/modifying-provider.md diff --git a/docs/book/src/topics/upgrading-provider.md b/docs/book/src/topics/capi-providers-lifecycle/upgrading-provider.md similarity index 100% rename from docs/book/src/topics/upgrading-provider.md rename to docs/book/src/topics/capi-providers-lifecycle/upgrading-provider.md diff --git a/docs/book/src/topics/air-gapped-environtment.md b/docs/book/src/topics/configuration/air-gapped-environtment.md similarity index 72% rename from docs/book/src/topics/air-gapped-environtment.md rename to docs/book/src/topics/configuration/air-gapped-environtment.md index 11dfafa36..e9da828f9 100644 --- a/docs/book/src/topics/air-gapped-environtment.md +++ b/docs/book/src/topics/configuration/air-gapped-environtment.md @@ -84,35 +84,3 @@ yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml ```sh kubectl create -f configmap.yaml ``` - -## Patching provider manifests - -Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider -manifests `spec.ResourcePatches` has to be used where an array of patches can be specified: - -```yaml ---- -apiVersion: operator.cluster.x-k8s.io/v1alpha2 -kind: CoreProvider -metadata: - name: cluster-api - namespace: capi-system -spec: - resourcePatches: - - | -apiVersion: v1 -kind: Service -metadata: -labels: - test-label: test-value -``` - -More information about JSON merge patches can be found here - -There are couple of rules for the patch to match a manifest: - -- The `kind` field must match the target object. -- If `apiVersion` is specified it will only be applied to matching objects. -- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind. -- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects. -- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace. diff --git a/docs/book/src/topics/configuration/configuration.md b/docs/book/src/topics/configuration/configuration.md new file mode 100644 index 000000000..2c5acb39e --- /dev/null +++ b/docs/book/src/topics/configuration/configuration.md @@ -0,0 +1,153 @@ +# Configuration + +## Provider Spec + +1. `ProviderSpec`: desired state of the Provider, consisting of: + - Version (string): provider version (e.g., "v0.1.0") + - Manager (optional ManagerSpec): controller manager properties for the provider + - Deployment (optional DeploymentSpec): deployment properties for the provider + - ConfigSecret (optional SecretReference): reference to the config secret + - FetchConfig (optional FetchConfiguration): how the operator will fetch components and metadata + + YAML example: + + ```yaml + ... + spec: + version: "v0.1.0" + manager: + maxConcurrentReconciles: 5 + deployment: + replicas: 1 + configSecret: + name: "provider-secret" + fetchConfig: + url: "https://github.com/owner/repo/releases" + ... + ``` + +2. `ManagerSpec`: controller manager properties for the provider, consisting of: + - ProfilerAddress (optional string): pprof profiler bind address (e.g., "localhost:6060") + - MaxConcurrentReconciles (optional int): maximum number of concurrent reconciles + - Verbosity (optional int): logs verbosity + - FeatureGates (optional map[string]bool): provider specific feature flags + + YAML example: + + ```yaml + ... + spec: + manager: + profilerAddress: "localhost:6060" + maxConcurrentReconciles: 5 + verbosity: 1 + featureGates: + FeatureA: true + FeatureB: false + ... + ``` + +3. `DeploymentSpec`: deployment properties for the provider, consisting of: + - Replicas (optional int): number of desired pods + - NodeSelector (optional map[string]string): node label selector + - Tolerations (optional []corev1.Toleration): pod tolerations + - Affinity (optional corev1.Affinity): pod scheduling constraints + - Containers (optional []ContainerSpec): list of deployment containers + - ServiceAccountName (optional string): pod service account + - ImagePullSecrets (optional []corev1.LocalObjectReference): list of image pull secrets specified in the Deployment + + YAML example: + + ```yaml + ... + spec: + deployment: + replicas: 2 + nodeSelector: + disktype: ssd + tolerations: + - key: "example" + operator: "Exists" + effect: "NoSchedule" + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: "example" + operator: "In" + values: + - "true" + containers: + - name: "containerA" + imageUrl: "example.com/repo/image-name:v1.0.0" + args: + exampleArg: "value" + ... + ``` + +4. `ContainerSpec`: container properties for the provider, consisting of: + - Name (string): container name + - ImageURL (optional string): container image URL + - Args (optional map[string]string): extra provider specific flags + - Env (optional []corev1.EnvVar): environment variables + - Resources (optional corev1.ResourceRequirements): compute resources + - Command (optional []string): override container's entrypoint array + + YAML example: + + ```yaml + ... + spec: + deployment: + containers: + - name: "example-container" + imageUrl: "example.com/repo/image-name:v1.0.0" + args: + exampleArg: "value" + env: + - name: "EXAMPLE_ENV" + value: "example-value" + resources: + limits: + cpu: "1" + memory: "1Gi" + requests: + cpu: "500m" + memory: "500Mi" + command: + - "/bin/bash" + ... + ``` + +5. `FetchConfiguration`: components and metadata fetch options, consisting of: + - URL (optional string): URL for remote Github repository releases (e.g., "") + - Selector (optional metav1.LabelSelector): label selector to use for fetching provider components and metadata from ConfigMaps stored in the cluster + + YAML example: + + ```yaml + ... + spec: + fetchConfig: + url: "https://github.com/owner/repo/releases" + selector: + matchLabels: + ... + ``` + +6. `SecretReference`: pointer to a secret object, consisting of: + +- Name (string): name of the secret +- Namespace (optional string): namespace of the secret, defaults to the provider object namespace + + YAML example: + + ```yaml + ... + spec: + configSecret: + name: capa-secret + namespace: capa-system + ... + ``` diff --git a/docs/book/src/topics/configuration/examples-of-api-usage.md b/docs/book/src/topics/configuration/examples-of-api-usage.md new file mode 100644 index 000000000..0ada1c31f --- /dev/null +++ b/docs/book/src/topics/configuration/examples-of-api-usage.md @@ -0,0 +1,122 @@ +# Examples of API Usage + +In this section we provide some concrete examples of CAPI Operator API usage for various use-cases. + +1. As an admin, I want to install the aws infrastructure provider with specific controller flags. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: aws-variables + namespace: capa-system +type: Opaque +data: + AWS_B64ENCODED_CREDENTIALS: ... +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: aws + namespace: capa-system +spec: + version: v2.1.4 + configSecret: + name: aws-variables + manager: + # These top level controller manager flags, supported by all the providers. + # These flags come with sensible defaults, thus requiring no or minimal + # changes for the most common scenarios. + metrics: + bindAddress: ":8181" + syncPeriod: "500s" + fetchConfig: + url: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases + deployment: + containers: + - name: manager + args: + # These are controller flags that are specific to a provider; usage + # is reserved for advanced scenarios only. + "--awscluster-concurrency": "12" + "--awsmachine-concurrency": "11" +``` + +2. As an admin, I want to install aws infrastructure provider but override the container image of the CAPA deployment. + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: aws + namespace: capa-system +spec: + version: v2.1.4 + configSecret: + name: aws-variables + deployment: + containers: + - name: manager + imageUrl: "gcr.io/myregistry/capa-controller:v2.1.4-foo" +``` + +3. As an admin, I want to change the resource limits for the manager pod in my control plane provider deployment. + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: ControlPlaneProvider +metadata: + name: kubeadm + namespace: capi-kubeadm-control-plane-system +spec: + version: v1.4.3 + configSecret: + name: capi-variables + deployment: + containers: + - name: manager + resources: + limits: + cpu: 100m + memory: 30Mi + requests: + cpu: 100m + memory: 20Mi +``` + +4. As an admin, I would like to fetch my azure provider components from a specific repository which is not the default. + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: myazure + namespace: capz-system +spec: + version: v1.9.3 + configSecret: + name: azure-variables + fetchConfig: + url: https://github.com/myorg/awesome-azure-provider/releases + +``` + +5. As an admin, I would like to use the default fetch configurations by simply specifying the expected Cluster API provider names such as `aws`, `vsphere`, `azure`, `kubeadm`, `talos`, or `cluster-api` instead of having to explicitly specify the fetch configuration. In the example below, since we are using 'vsphere' as the name of the InfrastructureProvider the operator will fetch it's configuration from `url: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases` by default. + +See more examples in the [air-gapped environment section](#air-gapped-environment) + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: vsphere + namespace: capv-system +spec: + version: v1.6.1 + configSecret: + name: vsphere-variables +``` diff --git a/docs/book/src/topics/injecting-additional-manifests.md b/docs/book/src/topics/configuration/injecting-additional-manifests.md similarity index 100% rename from docs/book/src/topics/injecting-additional-manifests.md rename to docs/book/src/topics/configuration/injecting-additional-manifests.md diff --git a/docs/book/src/topics/configuration/patching-provider-manifests.md b/docs/book/src/topics/configuration/patching-provider-manifests.md new file mode 100644 index 000000000..37832c94a --- /dev/null +++ b/docs/book/src/topics/configuration/patching-provider-manifests.md @@ -0,0 +1,31 @@ +# Patching provider manifests + +Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider +manifests `spec.ResourcePatches` has to be used where an array of patches can be specified: + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system +spec: + resourcePatches: + - | +apiVersion: v1 +kind: Service +metadata: +labels: + test-label: test-value +``` + +More information about JSON merge patches can be found here + +There are couple of rules for the patch to match a manifest: + +- The `kind` field must match the target object. +- If `apiVersion` is specified it will only be applied to matching objects. +- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind. +- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects. +- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace. From 978da7fd0cbb5feca21affc777e76aa6a500b6d3 Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Wed, 6 Mar 2024 14:55:49 +0100 Subject: [PATCH 3/4] Re-add fs-summary and toc to pre-processors Signed-off-by: Danil Grigorev --- docs/book/Makefile | 3 ++- docs/book/book.toml | 15 ++++++++++++++- scripts/ci-install-mdbook.sh | 2 ++ 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/book/Makefile b/docs/book/Makefile index 6492910b0..25ec8e842 100644 --- a/docs/book/Makefile +++ b/docs/book/Makefile @@ -22,10 +22,11 @@ TABULATE := $(TOOLS_BIN_DIR)/mdbook-tabulate EMBED := $(TOOLS_BIN_DIR)/mdbook-embed RELEASELINK := $(TOOLS_BIN_DIR)/mdbook-releaselink MDBOOK := $(TOOLS_BIN_DIR)/bin/mdbook +FS_SUMMARY := $(TOOLS_BIN_DIR)/bin/mdbook-fs-summary export PATH := $(abspath $(TOOLS_BIN_DIR)/bin):$(PATH) -BOOK_DEPS := $(MDBOOK) $(TABULATE) $(EMBED) $(RELEASELINK) +BOOK_DEPS := $(MDBOOK) $(TABULATE) $(EMBED) $(RELEASELINK) $(FS_SUMMARY) $(TOOLS_BIN_DIR)/%: $(TOOLS_DIR_DEPS) make -C $(TOOLS_DIR) $(subst $(TOOLS_DIR)/,,$@) diff --git a/docs/book/book.toml b/docs/book/book.toml index 8744ff7a4..69ffd45c8 100644 --- a/docs/book/book.toml +++ b/docs/book/book.toml @@ -5,6 +5,19 @@ src = "src" title = "Cluster API Operator" description = "Cluster API Operator" +[preprocessor.toc] +command = "mdbook-toc" +marker = "[[_TOC_]]" + +[preprocessor.fs-summary] +# (default: true) +clean-paths = false + +# other preprocessors will naturally need to +# run after the summary has been generated +[preprocessor.links] +after = ["fs-summary"] + [output.html] mathjax-support = true git-repository-url = "https://github.com/kubernetes-sigs/cluster-api-operator" @@ -22,4 +35,4 @@ command = "./util-tabulate.sh" command = "./util-embed.sh" [preprocessor.releaselink] -command = "./util-releaselink.sh" \ No newline at end of file +command = "./util-releaselink.sh" diff --git a/scripts/ci-install-mdbook.sh b/scripts/ci-install-mdbook.sh index e6ae73137..f86563c5f 100755 --- a/scripts/ci-install-mdbook.sh +++ b/scripts/ci-install-mdbook.sh @@ -30,3 +30,5 @@ curl https://sh.rustup.rs -sSf | sh -s -- -y # Install mdbook and dependencies cargo install mdbook --version "$VERSION" --root "$OUTPUT_PATH" +cargo install mdbook-fs-summary --root "$OUTPUT_PATH" +cargo install mdbook-toc --root "$OUTPUT_PATH" \ No newline at end of file From 9f992a350db6dc625c33e566cc5258b5113a7523 Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Wed, 6 Mar 2024 15:40:29 +0100 Subject: [PATCH 4/4] Move content to correct sections for generated summary Signed-off-by: Danil Grigorev --- .../{introduction.md => 00_introduction.md} | 0 docs/book/src/01_user/00.md | 3 + .../concepts.md => 01_user/01_concepts.md} | 0 .../02_quick-start.md} | 57 +++++++++++-------- .../installation.md => 02_installation/00.md} | 0 .../01_plugin-installation.md} | 0 .../02_manifest-installation.md} | 0 .../03_helm-chart-installation.md} | 0 .../src/{topics/topics.md => 03_topics/00.md} | 0 .../01_capi-providers-lifecycle/00.md | 7 +++ .../01_installing-provider.md} | 0 .../02_upgrading-provider.md} | 0 .../03_modifying-provider.md} | 0 .../04_deleting-provider.md} | 0 .../book/src/03_topics/02_configuration/00.md | 3 + .../01_air-gapped-environtment.md} | 0 .../02_injecting-additional-manifests.md} | 0 .../03_examples-of-api-usage.md} | 2 +- .../04_patching-provider-manifests.md} | 0 .../05_provider-spec-configuration.md} | 4 +- .../06_deleting-providers.md} | 0 .../00.md | 3 + .../01_installing-core-provider.md} | 0 .../02_installing-capz.md} | 0 docs/book/src/04_developer/00.md | 6 ++ .../release.md => 04_developer/01_release.md} | 0 .../guide.md => 04_developer/02_guide.md} | 0 .../03_v1alpha1-to-v1alpha2.md} | 0 docs/book/src/05_reference/00.md | 8 +++ .../01_api_reference.md} | 0 .../02_glossary.md} | 0 .../src/05_reference/03_code-of-conduct.md | 3 + docs/book/src/05_reference/04_contributing.md | 3 + .../ci-jobs.md => 05_reference/05_ci-jobs.md} | 0 .../06_providers.md} | 0 docs/book/src/CONTRIBUTING.MD | 1 - docs/book/src/SUMMARY.md | 30 ---------- docs/book/src/code-of-conduct.md | 3 - docs/book/src/reference/reference.md | 1 - .../capi-provides-lifecycle.md | 1 - 40 files changed, 70 insertions(+), 65 deletions(-) rename docs/book/src/{introduction.md => 00_introduction.md} (100%) create mode 100644 docs/book/src/01_user/00.md rename docs/book/src/{user/concepts.md => 01_user/01_concepts.md} (100%) rename docs/book/src/{user/quick-start.md => 01_user/02_quick-start.md} (54%) rename docs/book/src/{installation/installation.md => 02_installation/00.md} (100%) rename docs/book/src/{installation/plugin-installation.md => 02_installation/01_plugin-installation.md} (100%) rename docs/book/src/{installation/manifest-installation.md => 02_installation/02_manifest-installation.md} (100%) rename docs/book/src/{installation/helm-chart-installation.md => 02_installation/03_helm-chart-installation.md} (100%) rename docs/book/src/{topics/topics.md => 03_topics/00.md} (100%) create mode 100644 docs/book/src/03_topics/01_capi-providers-lifecycle/00.md rename docs/book/src/{topics/capi-providers-lifecycle/installing-provider.md => 03_topics/01_capi-providers-lifecycle/01_installing-provider.md} (100%) rename docs/book/src/{topics/capi-providers-lifecycle/upgrading-provider.md => 03_topics/01_capi-providers-lifecycle/02_upgrading-provider.md} (100%) rename docs/book/src/{topics/capi-providers-lifecycle/modifying-provider.md => 03_topics/01_capi-providers-lifecycle/03_modifying-provider.md} (100%) rename docs/book/src/{topics/capi-providers-lifecycle/deleting-provider.md => 03_topics/01_capi-providers-lifecycle/04_deleting-provider.md} (100%) create mode 100644 docs/book/src/03_topics/02_configuration/00.md rename docs/book/src/{topics/configuration/air-gapped-environtment.md => 03_topics/02_configuration/01_air-gapped-environtment.md} (100%) rename docs/book/src/{topics/configuration/injecting-additional-manifests.md => 03_topics/02_configuration/02_injecting-additional-manifests.md} (100%) rename docs/book/src/{topics/configuration/examples-of-api-usage.md => 03_topics/02_configuration/03_examples-of-api-usage.md} (97%) rename docs/book/src/{topics/configuration/patching-provider-manifests.md => 03_topics/02_configuration/04_patching-provider-manifests.md} (100%) rename docs/book/src/{topics/configuration/configuration.md => 03_topics/02_configuration/05_provider-spec-configuration.md} (99%) rename docs/book/src/{topics/deleting-providers.md => 03_topics/02_configuration/06_deleting-providers.md} (100%) create mode 100644 docs/book/src/03_topics/03_basic-cluster-api-provider-installation/00.md rename docs/book/src/{topics/capi-providers-lifecycle/installing-core-provider.md => 03_topics/03_basic-cluster-api-provider-installation/01_installing-core-provider.md} (100%) rename docs/book/src/{topics/capi-providers-lifecycle/installing-capz.md => 03_topics/03_basic-cluster-api-provider-installation/02_installing-capz.md} (100%) create mode 100644 docs/book/src/04_developer/00.md rename docs/book/src/{developer/release.md => 04_developer/01_release.md} (100%) rename docs/book/src/{developer/guide.md => 04_developer/02_guide.md} (100%) rename docs/book/src/{developer/v1alpha1-to-v1alpha2.md => 04_developer/03_v1alpha1-to-v1alpha2.md} (100%) create mode 100644 docs/book/src/05_reference/00.md rename docs/book/src/{reference/api_reference.md => 05_reference/01_api_reference.md} (100%) rename docs/book/src/{reference/glossary.md => 05_reference/02_glossary.md} (100%) create mode 100644 docs/book/src/05_reference/03_code-of-conduct.md create mode 100644 docs/book/src/05_reference/04_contributing.md rename docs/book/src/{reference/ci-jobs.md => 05_reference/05_ci-jobs.md} (100%) rename docs/book/src/{reference/providers.md => 05_reference/06_providers.md} (100%) delete mode 100644 docs/book/src/CONTRIBUTING.MD delete mode 100644 docs/book/src/code-of-conduct.md delete mode 100644 docs/book/src/reference/reference.md delete mode 100644 docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md diff --git a/docs/book/src/introduction.md b/docs/book/src/00_introduction.md similarity index 100% rename from docs/book/src/introduction.md rename to docs/book/src/00_introduction.md diff --git a/docs/book/src/01_user/00.md b/docs/book/src/01_user/00.md new file mode 100644 index 000000000..e0cd08887 --- /dev/null +++ b/docs/book/src/01_user/00.md @@ -0,0 +1,3 @@ +# User guide + +This section contains quick start and concepts relevant to a new operator user. \ No newline at end of file diff --git a/docs/book/src/user/concepts.md b/docs/book/src/01_user/01_concepts.md similarity index 100% rename from docs/book/src/user/concepts.md rename to docs/book/src/01_user/01_concepts.md diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/01_user/02_quick-start.md similarity index 54% rename from docs/book/src/user/quick-start.md rename to docs/book/src/01_user/02_quick-start.md index 0de75e66e..5101804aa 100644 --- a/docs/book/src/user/quick-start.md +++ b/docs/book/src/01_user/02_quick-start.md @@ -2,6 +2,8 @@ This is a quickstart guide for getting Cluster API Operator up and running on your Kubernetes cluster. +For more detailed information, please refer to the full documentation. + ## Prerequisites - [Running Kubernetes cluster](https://cluster-api.sigs.k8s.io/user/quick-start#install-andor-configure-a-kubernetes-cluster). @@ -25,42 +27,47 @@ kubectl create secret generic "${CREDENTIALS_SECRET_NAME}" --from-literal=AWS_B6 ### Installing Cluster API Operator -#### Method 1: Apply Manifests from Release Assets - -Before installing the Cluster API Operator this way, you must first ensure that cert-manager is installed, as the operator does not manage cert-manager installations. To install cert-manager, run the following command: - -```bash -kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml -``` - -Wait for cert-manager to be ready before proceeding. - -After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets: +Add helm repository: ```bash -kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml +helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator +helm repo update ``` -#### Method 2: Use Helm Charts - -Alternatively, you can install the Cluster API operator using Helm charts: +Deploy Cluster API components with docker provider using a single command during operator installation ```bash -helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator -helm repo update -helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE} --wait --timeout 90s ``` -##### Installing cert-manager using Helm chart +Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure). -CAPI operator Helm chart supports provisioning of cert-manager as a dependency. It is disabled by default, but you can enable it with `--set cert-manager.enabled=true` option to `helm install` command or inside of `cert-manager` section in [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml) file. Additionally you can define other [parameters](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration) provided by the cert-manager chart. +Other options for installing Cluster API Operator are described in [installation documentation](../02_installation/). + +# Example API Usage -##### Installing providers using Helm chart +Deploy latest version of core Cluster API components: -Deploy Cluster API components with docker provider using a single command during operator installation: +```yaml +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system -```bash -helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE} --wait --timeout 90s ``` -Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure). \ No newline at end of file +Deploy Cluster API AWS provider with specific version, custom manager options and flags: + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: aws + namespace: capa-system +spec: + version: v2.1.4 + configSecret: + name: aws-variables +``` diff --git a/docs/book/src/installation/installation.md b/docs/book/src/02_installation/00.md similarity index 100% rename from docs/book/src/installation/installation.md rename to docs/book/src/02_installation/00.md diff --git a/docs/book/src/installation/plugin-installation.md b/docs/book/src/02_installation/01_plugin-installation.md similarity index 100% rename from docs/book/src/installation/plugin-installation.md rename to docs/book/src/02_installation/01_plugin-installation.md diff --git a/docs/book/src/installation/manifest-installation.md b/docs/book/src/02_installation/02_manifest-installation.md similarity index 100% rename from docs/book/src/installation/manifest-installation.md rename to docs/book/src/02_installation/02_manifest-installation.md diff --git a/docs/book/src/installation/helm-chart-installation.md b/docs/book/src/02_installation/03_helm-chart-installation.md similarity index 100% rename from docs/book/src/installation/helm-chart-installation.md rename to docs/book/src/02_installation/03_helm-chart-installation.md diff --git a/docs/book/src/topics/topics.md b/docs/book/src/03_topics/00.md similarity index 100% rename from docs/book/src/topics/topics.md rename to docs/book/src/03_topics/00.md diff --git a/docs/book/src/03_topics/01_capi-providers-lifecycle/00.md b/docs/book/src/03_topics/01_capi-providers-lifecycle/00.md new file mode 100644 index 000000000..afb1393b6 --- /dev/null +++ b/docs/book/src/03_topics/01_capi-providers-lifecycle/00.md @@ -0,0 +1,7 @@ +# Cluster API Provider Lifecycle + +This section contains lifecycle operations a user can perform on a provider manifest, such as: +- Install +- Upgrade +- Modify +- Delete \ No newline at end of file diff --git a/docs/book/src/topics/capi-providers-lifecycle/installing-provider.md b/docs/book/src/03_topics/01_capi-providers-lifecycle/01_installing-provider.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/installing-provider.md rename to docs/book/src/03_topics/01_capi-providers-lifecycle/01_installing-provider.md diff --git a/docs/book/src/topics/capi-providers-lifecycle/upgrading-provider.md b/docs/book/src/03_topics/01_capi-providers-lifecycle/02_upgrading-provider.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/upgrading-provider.md rename to docs/book/src/03_topics/01_capi-providers-lifecycle/02_upgrading-provider.md diff --git a/docs/book/src/topics/capi-providers-lifecycle/modifying-provider.md b/docs/book/src/03_topics/01_capi-providers-lifecycle/03_modifying-provider.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/modifying-provider.md rename to docs/book/src/03_topics/01_capi-providers-lifecycle/03_modifying-provider.md diff --git a/docs/book/src/topics/capi-providers-lifecycle/deleting-provider.md b/docs/book/src/03_topics/01_capi-providers-lifecycle/04_deleting-provider.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/deleting-provider.md rename to docs/book/src/03_topics/01_capi-providers-lifecycle/04_deleting-provider.md diff --git a/docs/book/src/03_topics/02_configuration/00.md b/docs/book/src/03_topics/02_configuration/00.md new file mode 100644 index 000000000..24c3dac9f --- /dev/null +++ b/docs/book/src/03_topics/02_configuration/00.md @@ -0,0 +1,3 @@ +# Configuration + +This section contains a list of frequent configuration tasks for CAPI Operator providers. \ No newline at end of file diff --git a/docs/book/src/topics/configuration/air-gapped-environtment.md b/docs/book/src/03_topics/02_configuration/01_air-gapped-environtment.md similarity index 100% rename from docs/book/src/topics/configuration/air-gapped-environtment.md rename to docs/book/src/03_topics/02_configuration/01_air-gapped-environtment.md diff --git a/docs/book/src/topics/configuration/injecting-additional-manifests.md b/docs/book/src/03_topics/02_configuration/02_injecting-additional-manifests.md similarity index 100% rename from docs/book/src/topics/configuration/injecting-additional-manifests.md rename to docs/book/src/03_topics/02_configuration/02_injecting-additional-manifests.md diff --git a/docs/book/src/topics/configuration/examples-of-api-usage.md b/docs/book/src/03_topics/02_configuration/03_examples-of-api-usage.md similarity index 97% rename from docs/book/src/topics/configuration/examples-of-api-usage.md rename to docs/book/src/03_topics/02_configuration/03_examples-of-api-usage.md index 0ada1c31f..859d01c03 100644 --- a/docs/book/src/topics/configuration/examples-of-api-usage.md +++ b/docs/book/src/03_topics/02_configuration/03_examples-of-api-usage.md @@ -106,7 +106,7 @@ spec: 5. As an admin, I would like to use the default fetch configurations by simply specifying the expected Cluster API provider names such as `aws`, `vsphere`, `azure`, `kubeadm`, `talos`, or `cluster-api` instead of having to explicitly specify the fetch configuration. In the example below, since we are using 'vsphere' as the name of the InfrastructureProvider the operator will fetch it's configuration from `url: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases` by default. -See more examples in the [air-gapped environment section](#air-gapped-environment) +See more examples in the [air-gapped environment section](./01_air-gapped-environtment.md) ```yaml --- diff --git a/docs/book/src/topics/configuration/patching-provider-manifests.md b/docs/book/src/03_topics/02_configuration/04_patching-provider-manifests.md similarity index 100% rename from docs/book/src/topics/configuration/patching-provider-manifests.md rename to docs/book/src/03_topics/02_configuration/04_patching-provider-manifests.md diff --git a/docs/book/src/topics/configuration/configuration.md b/docs/book/src/03_topics/02_configuration/05_provider-spec-configuration.md similarity index 99% rename from docs/book/src/topics/configuration/configuration.md rename to docs/book/src/03_topics/02_configuration/05_provider-spec-configuration.md index 2c5acb39e..8d87672bf 100644 --- a/docs/book/src/topics/configuration/configuration.md +++ b/docs/book/src/03_topics/02_configuration/05_provider-spec-configuration.md @@ -1,6 +1,4 @@ -# Configuration - -## Provider Spec +# Provider Spec 1. `ProviderSpec`: desired state of the Provider, consisting of: - Version (string): provider version (e.g., "v0.1.0") diff --git a/docs/book/src/topics/deleting-providers.md b/docs/book/src/03_topics/02_configuration/06_deleting-providers.md similarity index 100% rename from docs/book/src/topics/deleting-providers.md rename to docs/book/src/03_topics/02_configuration/06_deleting-providers.md diff --git a/docs/book/src/03_topics/03_basic-cluster-api-provider-installation/00.md b/docs/book/src/03_topics/03_basic-cluster-api-provider-installation/00.md new file mode 100644 index 000000000..949ba8ed8 --- /dev/null +++ b/docs/book/src/03_topics/03_basic-cluster-api-provider-installation/00.md @@ -0,0 +1,3 @@ +# Basic Cluster API provider installation + +This section provides an example to a CAPZ provider installation. \ No newline at end of file diff --git a/docs/book/src/topics/capi-providers-lifecycle/installing-core-provider.md b/docs/book/src/03_topics/03_basic-cluster-api-provider-installation/01_installing-core-provider.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/installing-core-provider.md rename to docs/book/src/03_topics/03_basic-cluster-api-provider-installation/01_installing-core-provider.md diff --git a/docs/book/src/topics/capi-providers-lifecycle/installing-capz.md b/docs/book/src/03_topics/03_basic-cluster-api-provider-installation/02_installing-capz.md similarity index 100% rename from docs/book/src/topics/capi-providers-lifecycle/installing-capz.md rename to docs/book/src/03_topics/03_basic-cluster-api-provider-installation/02_installing-capz.md diff --git a/docs/book/src/04_developer/00.md b/docs/book/src/04_developer/00.md new file mode 100644 index 000000000..d144dff56 --- /dev/null +++ b/docs/book/src/04_developer/00.md @@ -0,0 +1,6 @@ +# Developer + +This section contains regular developer tasks, such as: +- Release +- Development guide +- Migration guide \ No newline at end of file diff --git a/docs/book/src/developer/release.md b/docs/book/src/04_developer/01_release.md similarity index 100% rename from docs/book/src/developer/release.md rename to docs/book/src/04_developer/01_release.md diff --git a/docs/book/src/developer/guide.md b/docs/book/src/04_developer/02_guide.md similarity index 100% rename from docs/book/src/developer/guide.md rename to docs/book/src/04_developer/02_guide.md diff --git a/docs/book/src/developer/v1alpha1-to-v1alpha2.md b/docs/book/src/04_developer/03_v1alpha1-to-v1alpha2.md similarity index 100% rename from docs/book/src/developer/v1alpha1-to-v1alpha2.md rename to docs/book/src/04_developer/03_v1alpha1-to-v1alpha2.md diff --git a/docs/book/src/05_reference/00.md b/docs/book/src/05_reference/00.md new file mode 100644 index 000000000..542ba5121 --- /dev/null +++ b/docs/book/src/05_reference/00.md @@ -0,0 +1,8 @@ +# Reference + +- [API reference](./01_api_reference.md) +- [Glossary](./02_glossary.md) +- [Code of Conduct](./03_code-of-conduct.md) +- [Contributing](./04_contributing.md) +- [CI Jobs](./05_ci-jobs.md) +- [Providers](./06_providers.md) \ No newline at end of file diff --git a/docs/book/src/reference/api_reference.md b/docs/book/src/05_reference/01_api_reference.md similarity index 100% rename from docs/book/src/reference/api_reference.md rename to docs/book/src/05_reference/01_api_reference.md diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/05_reference/02_glossary.md similarity index 100% rename from docs/book/src/reference/glossary.md rename to docs/book/src/05_reference/02_glossary.md diff --git a/docs/book/src/05_reference/03_code-of-conduct.md b/docs/book/src/05_reference/03_code-of-conduct.md new file mode 100644 index 000000000..790596315 --- /dev/null +++ b/docs/book/src/05_reference/03_code-of-conduct.md @@ -0,0 +1,3 @@ +# Code of Conduct + +{{#include ../../../../code-of-conduct.md}} \ No newline at end of file diff --git a/docs/book/src/05_reference/04_contributing.md b/docs/book/src/05_reference/04_contributing.md new file mode 100644 index 000000000..ac9d66933 --- /dev/null +++ b/docs/book/src/05_reference/04_contributing.md @@ -0,0 +1,3 @@ +# Contributing + +{{#include ../../../../CONTRIBUTING.md}} \ No newline at end of file diff --git a/docs/book/src/reference/ci-jobs.md b/docs/book/src/05_reference/05_ci-jobs.md similarity index 100% rename from docs/book/src/reference/ci-jobs.md rename to docs/book/src/05_reference/05_ci-jobs.md diff --git a/docs/book/src/reference/providers.md b/docs/book/src/05_reference/06_providers.md similarity index 100% rename from docs/book/src/reference/providers.md rename to docs/book/src/05_reference/06_providers.md diff --git a/docs/book/src/CONTRIBUTING.MD b/docs/book/src/CONTRIBUTING.MD deleted file mode 100644 index d05eb6229..000000000 --- a/docs/book/src/CONTRIBUTING.MD +++ /dev/null @@ -1 +0,0 @@ -{{#include ../../../CONTRIBUTING.md}} \ No newline at end of file diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index e929730c4..e69de29bb 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -1,30 +0,0 @@ -# Summary - -[Introduction](./introduction.md) -[Quick Start](./user/quick-start.md) -- [Installation](./installation/installation.md) - - [Using plugin](./installation/plugin-installation.md) - - [Using Manifests from Release Assets](./installation/manifest-installation.md) - - [Using Helm Charts](./installation/helm-chart-installation.md) -[Concepts](./user/concepts.md) -- [Topics](./topics/topics.md) - - [Cluster API Provider Lifecycle](./topics/capi-provides-lifecycle.md) - - [Installing a Provider](./topics/installing-provider.md) - - [Upgrading a Provider](./topics/upgrading-provider.md) - - [Modifying a Provider](./topics/modifying-provider.md) - - [Deleting a Provider](./topics/deleting-provider.md) - - [Basic Cluster API Provider Installation](./topics/basic-capi-provider-installation.md) - - [Installing the CoreProvider](./topics/installing-core-provider.md) - - [Installing Azure Infrastructure Provider](./topics/installing-capz.md) - - [Deleting providers](./topics/deleting-providers.md) - - [Air-gapped Environment](./topics/air-gapped-environtment.md) - - [Injecting additional manifests](./topics/injecting-additional-manifests.md) -- [Developer Guide](./developer/guide.md) - - [Releasing](./developer/release.md) - - [Version migration](./developer/v1alpha1-to-v1alpha2.md) -- [Reference](./reference/reference.md) - - [API Reference](./reference/api_reference.md) - - [Glossary](./reference/glossary.md) - - [Code of Conduct](./code-of-conduct.md) - - [Contributing](./CONTRIBUTING.md) - - [CI Jobs](./reference/ci-jobs.md) \ No newline at end of file diff --git a/docs/book/src/code-of-conduct.md b/docs/book/src/code-of-conduct.md deleted file mode 100644 index e28dbc062..000000000 --- a/docs/book/src/code-of-conduct.md +++ /dev/null @@ -1,3 +0,0 @@ -# Code of Conduct - -{{#include ../../../code-of-conduct.md}} \ No newline at end of file diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md deleted file mode 100644 index cf5aa0741..000000000 --- a/docs/book/src/reference/reference.md +++ /dev/null @@ -1 +0,0 @@ -# Reference diff --git a/docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md b/docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md deleted file mode 100644 index 0e56a0c60..000000000 --- a/docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md +++ /dev/null @@ -1 +0,0 @@ -# Cluster API Provider Lifecycle