Skip to content

Commit dd1c5f1

Browse files
Danil-GrigorevDanil-Grigorev
committed
Add book content
Signed-off-by: Danil Grigorev <[email protected]>
1 parent 006442f commit dd1c5f1

14 files changed

+391
-0
lines changed

‎docs/book/src/installation/helm-chart-installation.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,35 @@
11
# Using Helm Charts
2+
3+
Alternatively, you can install the Cluster API operator using Helm charts:
4+
5+
```bash
6+
helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
7+
helm repo update
8+
helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system
9+
```
10+
11+
#### Installing cert-manager using Helm chart
12+
13+
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.
14+
15+
#### Installing providers using Helm chart
16+
17+
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):
18+
19+
```bash
20+
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
21+
```
22+
23+
```bash
24+
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
25+
```
26+
27+
```bash
28+
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
29+
```
30+
31+
```bash
32+
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
33+
```
34+
35+
For more complex operations, please refer to our API documentation.

‎docs/book/src/installation/manifest-installation.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
11
# Using Manifests from Release Assets
2+
3+
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:
4+
5+
```bash
6+
kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
7+
```
8+
9+
Wait for cert-manager to be ready before proceeding.
10+
11+
After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets:
12+
13+
```bash
14+
kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml
15+
```

‎docs/book/src/reference/providers.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,83 @@
11
# Provider List
2+
3+
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.
4+
5+
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.
6+
7+
Related Golang structs can be found in the [Cluster API Operator repository](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/api/v1alpha1).
8+
9+
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:
10+
11+
*CoreProvider*
12+
13+
```golang
14+
type CoreProvider struct {
15+
metav1.TypeMeta `json:",inline"`
16+
metav1.ObjectMeta `json:"metadata,omitempty"`
17+
18+
Spec ProviderSpec `json:"spec,omitempty"`
19+
Status ProviderStatus `json:"status,omitempty"`
20+
}
21+
```
22+
23+
*BootstrapProvider*
24+
25+
```golang
26+
type BootstrapProvider struct {
27+
metav1.TypeMeta `json:",inline"`
28+
metav1.ObjectMeta `json:"metadata,omitempty"`
29+
30+
Spec ProviderSpec `json:"spec,omitempty"`
31+
Status ProviderStatus `json:"status,omitempty"`
32+
}
33+
```
34+
35+
*ControlPlaneProvider*
36+
37+
```golang
38+
type ControlPlaneProvider struct {
39+
metav1.TypeMeta `json:",inline"`
40+
metav1.ObjectMeta `json:"metadata,omitempty"`
41+
42+
Spec ProviderSpec `json:"spec,omitempty"`
43+
Status ProviderStatus `json:"status,omitempty"`
44+
}
45+
```
46+
47+
*InfrastructureProvider*
48+
49+
```golang
50+
type InfrastructureProvider struct {
51+
metav1.TypeMeta `json:",inline"`
52+
metav1.ObjectMeta `json:"metadata,omitempty"`
53+
54+
Spec ProviderSpec `json:"spec,omitempty"`
55+
Status ProviderStatus `json:"status,omitempty"`
56+
}
57+
```
58+
59+
*AddonProvider*
60+
61+
```golang
62+
type AddonProvider struct {
63+
metav1.TypeMeta `json:",inline"`
64+
metav1.ObjectMeta `json:"metadata,omitempty"`
65+
66+
Spec AddonProviderSpec `json:"spec,omitempty"`
67+
Status AddonProviderStatus `json:"status,omitempty"`
68+
}
69+
```
70+
71+
*IPAMProvider*
72+
73+
```golang
74+
type IPAMProvider struct {
75+
metav1.TypeMeta `json:",inline"`
76+
metav1.ObjectMeta `json:"metadata,omitempty"`
77+
78+
Spec IPAMProviderSpec `json:"spec,omitempty"`
79+
Status IPAMProviderStatus `json:"status,omitempty"`
80+
}
81+
```
82+
83+
The following sections provide details about `ProviderSpec` and `ProviderStatus`, which are shared among all the provider types.

‎docs/book/src/topics/air-gapped-environtment.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,118 @@
11
# Air-gapped Environment
2+
3+
To install Cluster API providers in an air-gapped environment using the operator, address the following issues:
4+
5+
1. Configure the operator for an air-gapped environment:
6+
- Manually fetch and store a helm chart for the operator.
7+
- Provide image overrides for the operator in from an accessible image repository.
8+
2. Configure providers for an air-gapped environment:
9+
- Provide fetch configuration for each provider from an accessible location (e.g., an internal GitHub repository) or from pre-created ConfigMaps within the cluster.
10+
- Provide image overrides for each provider to pull images from an accessible image repository.
11+
12+
**Example Usage:**
13+
14+
As an admin, I need to fetch the Azure provider components from within the cluster because I am working in an air-gapped environment.
15+
16+
In this example, there is a ConfigMap in the `capz-system` namespace that defines the components and metadata of the provider.
17+
18+
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.
19+
20+
```yaml
21+
---
22+
apiVersion: v1
23+
kind: ConfigMap
24+
metadata:
25+
labels:
26+
provider-components: azure
27+
name: v1.9.3
28+
namespace: capz-system
29+
data:
30+
components: |
31+
# Components for v1.9.3 YAML go here
32+
metadata: |
33+
# Metadata information goes here
34+
---
35+
apiVersion: operator.cluster.x-k8s.io/v1alpha2
36+
kind: InfrastructureProvider
37+
metadata:
38+
name: azure
39+
namespace: capz-system
40+
spec:
41+
version: v1.9.3
42+
configSecret:
43+
name: azure-variables
44+
fetchConfig:
45+
selector:
46+
matchLabels:
47+
provider-components: azure
48+
```
49+
50+
### Situation when manifests do not fit into configmap
51+
52+
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.
53+
54+
For example, you have two files: `components.yaml` and `metadata.yaml`. To create a working config map you need:
55+
56+
1. Archive components.yaml using `gzip` cli tool
57+
58+
```sh
59+
gzip -c components.yaml > components.gz
60+
```
61+
62+
2. Create a configmap manifest from the archived data
63+
64+
```sh
65+
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
66+
```
67+
68+
3. Edit the file by adding "provider.cluster.x-k8s.io/compressed: true" annotation
69+
70+
```sh
71+
yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml
72+
```
73+
74+
**Note**: without this annotation operator won't be able to determine if the data is compressed or not.
75+
76+
4. Add labels that will be used to match the configmap in `fetchConfig` section of the provider
77+
78+
```sh
79+
yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml
80+
```
81+
82+
5. Create a configmap in your kubernetes cluster using kubectl
83+
84+
```sh
85+
kubectl create -f configmap.yaml
86+
```
87+
88+
## Patching provider manifests
89+
90+
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
91+
manifests `spec.ResourcePatches` has to be used where an array of patches can be specified:
92+
93+
```yaml
94+
---
95+
apiVersion: operator.cluster.x-k8s.io/v1alpha2
96+
kind: CoreProvider
97+
metadata:
98+
name: cluster-api
99+
namespace: capi-system
100+
spec:
101+
resourcePatches:
102+
- |
103+
apiVersion: v1
104+
kind: Service
105+
metadata:
106+
labels:
107+
test-label: test-value
108+
```
109+
110+
More information about JSON merge patches can be found here <https://datatracker.ietf.org/doc/html/rfc7396>
111+
112+
There are couple of rules for the patch to match a manifest:
113+
114+
- The `kind` field must match the target object.
115+
- If `apiVersion` is specified it will only be applied to matching objects.
116+
- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind.
117+
- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects.
118+
- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace.

‎docs/book/src/topics/basic-capi-provider-installation.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
11
# Basic Cluster API Provider Installation
2+
3+
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:
4+
5+
- CoreProvider
6+
- BootstrapProvider
7+
- ControlPlaneProvider
8+
- InfrastructureProvider
9+
- AddonProvider
10+
- IPAMProvider
11+
12+
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.

‎docs/book/src/topics/capi-provides-lifecycle.md renamed to ‎docs/book/src/topics/capi-providers-lifecycle/capi-provides-lifecycle.md

File renamed without changes.

‎docs/book/src/topics/deleting-provider.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
11
# Deleting a Provider
2+
3+
To remove the installed providers and all related kubernetes objects just delete the following CRs:
4+
5+
```bash
6+
kubectl delete infrastructureprovider azure
7+
kubectl delete coreprovider cluster-api
8+
```

‎docs/book/src/topics/deleting-providers.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
11
# Deleting providers
2+
3+
To remove all installed providers and all related kubernetes objects just delete the following CRs:
4+
5+
```bash
6+
kubectl delete coreprovider --all --all-namespaces
7+
kubectl delete infrastructureprovider --all --all-namespaces
8+
kubectl delete bootstrapprovider --all --all-namespaces
9+
kubectl delete controlplaneprovider --all --all-namespaces
10+
kubectl delete ipamprovider --all --all-namespaces
11+
kubectl delete addonprovider --all --all-namespaces
12+
```

‎docs/book/src/topics/injecting-additional-manifests.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,26 @@
11
# Injecting additional manifests
2+
3+
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.
4+
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`.
5+
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.
6+
7+
```yaml
8+
---
9+
apiVersion: v1
10+
kind: ConfigMap
11+
metadata:
12+
name: additional-manifests
13+
namespace: capi-system
14+
data:
15+
manifests: |
16+
# Additional manifests go here
17+
---
18+
apiVersion: operator.cluster.x-k8s.io/v1alpha2
19+
kind: CoreProvider
20+
metadata:
21+
name: cluster-api
22+
namespace: capi-system
23+
spec:
24+
additionalManifests:
25+
name: additional-manifests
26+
```

‎docs/book/src/topics/installing-capz.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,31 @@
11
# Installing Azure Infrastructure Provider
2+
3+
Next, install [Azure Infrastructure Provider](https://capz.sigs.k8s.io/). Before that ensure that `capz-system` namespace exists.
4+
5+
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.
6+
7+
```yaml
8+
---
9+
apiVersion: v1
10+
kind: Secret
11+
metadata:
12+
name: azure-variables
13+
namespace: capz-system
14+
type: Opaque
15+
stringData:
16+
AZURE_CLIENT_ID_B64: Zm9vCg==
17+
AZURE_CLIENT_SECRET_B64: Zm9vCg==
18+
AZURE_SUBSCRIPTION_ID_B64: Zm9vCg==
19+
AZURE_TENANT_ID_B64: Zm9vCg==
20+
github-token: ghp_fff
21+
---
22+
apiVersion: operator.cluster.x-k8s.io/v1alpha1
23+
kind: InfrastructureProvider
24+
metadata:
25+
name: azure
26+
namespace: capz-system
27+
spec:
28+
version: v1.9.3
29+
configSecret:
30+
name: azure-variables
31+
```

0 commit comments

Comments
 (0)