From 8e64b6481717ab13137eb46cb5d38b82e7bf172e Mon Sep 17 00:00:00 2001 From: Danil Grigorev Date: Wed, 10 Jan 2024 21:11:51 +0100 Subject: [PATCH] Document the CAPIProvider resource for management of CAPI Operator resources Signed-off-by: Danil Grigorev --- docs/getting-started/install_capi_operator.md | 1 - .../install_turtles_operator.md | 17 +++-- .../rancher-turtles-chart/values.md | 1 - .../add_infrastructure_provider.md | 43 ++++++++++++- ...basic_cluster_api_provider_installation.md | 1 + .../capi-operator/capiprovider_resource.md | 62 +++++++++++++++++++ .../capi-operator/installing_core_provider.md | 33 +++++++--- 7 files changed, 138 insertions(+), 20 deletions(-) create mode 100644 docs/tasks/capi-operator/capiprovider_resource.md diff --git a/docs/getting-started/install_capi_operator.md b/docs/getting-started/install_capi_operator.md index f71e1b1c..a57c1204 100644 --- a/docs/getting-started/install_capi_operator.md +++ b/docs/getting-started/install_capi_operator.md @@ -49,7 +49,6 @@ helm install capi-operator capi-operator/cluster-api-operator --set cert-manager.enabled=true --timeout 90s --secret-name - --secret-namespace --wait ``` diff --git a/docs/getting-started/install_turtles_operator.md b/docs/getting-started/install_turtles_operator.md index 459aeaa4..21d5f8ee 100644 --- a/docs/getting-started/install_turtles_operator.md +++ b/docs/getting-started/install_turtles_operator.md @@ -26,10 +26,10 @@ helm repo update To install `Cluster API Operator` as a dependency to the `Rancher Turtles`, a minimum set of additional helm flags should be specified: ```bash -helm install rancher-turtles turtles/rancher-turtles --version v0.2.0 - -n rancher-turtles-system - --dependency-update - --create-namespace --wait +helm install rancher-turtles turtles/rancher-turtles --version v0.4.0 \ + -n rancher-turtles-system \ + --dependency-update \ + --create-namespace --wait \ --timeout 180s ``` @@ -41,23 +41,22 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.2.0 This is the basic, recommended configuration, which manages the creation of a secret containing the required feature flags (`CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled) in the core provider namespace. -If you need to override the default behavior and use an existing secret (or add custom environment variables), you can pass the secret name and namespace helm flags. In this case, as a user, you are in charge of managing the secret creation and its content, including the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled. +If you need to override the default behavior and use an existing secret (or add custom environment variables), you can pass the secret name helm flag. In this case, as a user, you are in charge of managing the secret creation and its content, including the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled. ```bash helm install ... # Passing secret name and namespace for additional environment variables --set cluster-api-operator.cluster-api.configSecret.name= - --set cluster-api-operator.cluster-api.configSecret.namespace= ``` -The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables`, `cluster-api-operator.cluster-api.configSecret.namespace=default` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable: +The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable: ```yaml title="secret.yaml" apiVersion: v1 kind: Secret metadata: name: variables - namespace: default + namespace: rancher-turtles-system type: Opaque stringData: CLUSTER_TOPOLOGY: "true" @@ -89,7 +88,7 @@ helm repo update and then it can be installed into the `rancher-turtles-system` namespace with: ```bash -helm install rancher-turtles turtles/rancher-turtles --version v0.2.0 +helm install rancher-turtles turtles/rancher-turtles --version v0.4.0 -n rancher-turtles-system --set cluster-api-operator.enabled=false --set cluster-api-operator.cluster-api.enabled=false diff --git a/docs/reference-guides/rancher-turtles-chart/values.md b/docs/reference-guides/rancher-turtles-chart/values.md index 84b6f8cb..4fdc9b87 100644 --- a/docs/reference-guides/rancher-turtles-chart/values.md +++ b/docs/reference-guides/rancher-turtles-chart/values.md @@ -46,7 +46,6 @@ cluster-api-operator: version: v1.4.6 # version of CAPI to install (default: v1.4.6) configSecret: name: "" # (provide only if using a user-managed secret) name of the config secret to use for core CAPI controllers, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#installing-azure-infrastructure-provider docs for more details. - namespace: "" # (provide only if using a user-managed secret) namespace of the config secret to use for core CAPI controllers, used by the CAPI operator. defaultName: "capi-env-variables" # default name for the automatically created secret. core: namespace: capi-system diff --git a/docs/tasks/capi-operator/add_infrastructure_provider.md b/docs/tasks/capi-operator/add_infrastructure_provider.md index 2c23f7d2..8c678be3 100644 --- a/docs/tasks/capi-operator/add_infrastructure_provider.md +++ b/docs/tasks/capi-operator/add_infrastructure_provider.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Add Infrastructure Provider @@ -12,6 +12,45 @@ Next, install [Azure Infrastructure Provider](https://capz.sigs.k8s.io/). Before 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. +## Option 1: CAPIProvider resource + +This section describes how to install the Azure `InfrastructureProvider` via `CAPIProvider`, which is responsible for managing Cluster API Azure CRDs and the Cluster API Azure controller. + +*Example:* + +```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: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: azure + namespace: capz-system +spec: + version: v1.9.3 + type: infrastructure # required + configSecret: + name: azure-variables # This will additionally poulate the default set of feature gates for the provider +``` + +## Option 2: Raw InfrastructureProvider resource + +This section describes how to install the Azure `InfrastructureProvider`, which is responsible for managing the Cluster API Azure CRDs and the Cluster API Azure controller. + +*Example:* + ```yaml --- apiVersion: v1 @@ -27,7 +66,7 @@ stringData: AZURE_TENANT_ID_B64: Zm9vCg== github-token: ghp_fff --- -apiVersion: operator.cluster.x-k8s.io/v1alpha1 +apiVersion: operator.cluster.x-k8s.io/v1alpha2 kind: InfrastructureProvider metadata: name: azure diff --git a/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md b/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md index 384f671c..9e76cda3 100644 --- a/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md +++ b/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md @@ -11,5 +11,6 @@ This section describes the basic process of installing `CAPI` providers using th - `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 are provided in the `Cluster API Operator` [documentation](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#readme) \ No newline at end of file diff --git a/docs/tasks/capi-operator/capiprovider_resource.md b/docs/tasks/capi-operator/capiprovider_resource.md new file mode 100644 index 00000000..2b28f23c --- /dev/null +++ b/docs/tasks/capi-operator/capiprovider_resource.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 2 +--- + +# CAPIProvider Resource + +The `CAPIProvider` resource allows managing Cluster API Operator manifests in a declarative way. It is used to provision and configure Cluster API providers like AWS, vSphere etc. + +`CAPIProvider` follows a GitOps model - the spec fields are declarative user inputs. The controller only updates status. + +[ARD](https://github.com/rancher-sandbox/rancher-turtles/blob/main/docs/adr/0007-rancher-turtles-public-api.md) + +## Usage + +To use the `CAPIProvider` resource: + +1. Create a `CAPIProvider` resource with the desired provider name, type, credentials, configuration, and features. +1. The `CAPIProvider` controller will handle templating the required Cluster API Operator manifests based on the `CAPIProvider` spec. +1. The status field on the `CAPIProvider` resource will reflect the state of the generated manifests. +1. Manage the `CAPIProvider` object declaratively to apply changes to the generated provider manifests. + +Here is an example `CAPIProvider` manifest: + +```yaml +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: aws-infra + namespace: default +spec: + name: aws + type: infrastructure + credentials: + rancherCloudCredential: aws-creds # Rancher credentials secret for AWS + configSecret: + name: aws-config + features: + clusterResourceSet: true +``` + +This will generate an AWS infrastructure provider with the supplied mapping for rancher credential secret and custom enabled features. + +The `CAPIProvider` controller will own all the generated provider resources, allowing garbage collection by deleting the `CAPIProvider` object. + +## Specification + +The key fields in the `CAPIProvider` spec are: + +- `name` - Name of the provider (aws, vsphere etc). Inherited from `metadata.name` if is not specified. +- `type` - Kind of provider resource (infrastructure, controlplane etc) +- `credentials` - Source credentials for provider specification +- `configSecret` - Name of the provider config secret, where the variables and synced credential will be stored. By default if not specified, will inherit the name of the `CAPIProvider` resource +- `features` - Enabled provider features +- `variables` - Variables is a map of environment variables to add to the content of the `configSecret` + +Full documentation on the CAPIProvider resource - [here](https://doc.crds.dev/github.com/rancher-sandbox/rancher-turtles/turtles-capi.cattle.io/CAPIProvider/v1alpha1@v0.4.0). + +## Deletion + +When a `CAPIProvider` resource is deleted, the kubernetes garbage collection will clean up all the generated provider resources that it owns. This includes: +- Cluster API Operator resource instance +- Secret referenced by the `configSecret` \ No newline at end of file diff --git a/docs/tasks/capi-operator/installing_core_provider.md b/docs/tasks/capi-operator/installing_core_provider.md index b6210fca..6bc8bf1a 100644 --- a/docs/tasks/capi-operator/installing_core_provider.md +++ b/docs/tasks/capi-operator/installing_core_provider.md @@ -1,13 +1,36 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Installing the CoreProvider -This section describes how to install the CoreProvider, which is responsible for managing the Cluster API CRDs and the Cluster API controller. - Any existing namespace could be utilized for providers in the Kubernetes cluster. However, before creating a provider object, make sure the specified namespace has been created. In the example below, we use the `capi-system` namespace. To create this namespace through either the Command Line Interface (CLI) by running `kubectl create namespace capi-system`, or the declarative approach described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/#create-new-namespaces) could be used. +:::note +Only one CoreProvider can be installed at the same time on a single cluster. +::: + +## Option 1: CAPIProvider resource + +This section describes how to install the `CoreProvider` via `CAPIProvider`, which is responsible for managing the Cluster API CRDs and the Cluster API controller. + +*Example:* + +```yaml +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: cluster-api + namespace: capi-system +spec: + version: v1.4.6 + type: core # required +``` + +## Option 2: CoreProvider resource + +This section describes how to install the `CoreProvider`, which is responsible for managing the Cluster API CRDs and the Cluster API controller. + *Example:* ```yaml @@ -19,7 +42,3 @@ metadata: spec: version: v1.4.6 ``` - -:::note -Only one CoreProvider can be installed at the same time on a single cluster. -:::