cluster-api-provider-bke Configuration Parameters ​

Common Configuration Scenarios Quick Reference ​

Table 1 Common Configuration Scenarios Quick Reference Table

cluster-api-provider-bke ​

BKEControllerManager Runtime Parameters ​

Table 2 BKEControllerManager command Configuration Items Table

Table 3 BKEControllerManager env Configuration Items Table

BKECluster CRD Configuration ​

When using these configurations via bke init --file/-f <BKECluster YAML>, also refer to the bke init flag descriptions in bkeadm Configuration Parameters.

Note:

• BKECluster (kubectl short name bc) describes the version, repository, network, addons, kubelet/containerd references, etc. of the cluster to be created. Common commands: kubectl get bc -A, kubectl edit bc -n <namespace> <name>, kubectl describe bc -n <namespace> <name>.
• The "Default Value" column in the table below lists the officially recommended configurations for the openFuyao platform (default values filled in by the controller/installer when the CRD is empty). For custom deployments, it is recommended to first follow the recommended values after confirming business constraints, and only override environment-related items such as repository addresses, node networks, and addon parameters as needed.
• Related resources: For the fields and reference methods of KubeletConfig (kct) and ContainerdConfig (cct), see the subsequent sections of this article and Binary Component Custom Configuration.

Table 4 BKECluster CRD Configuration Items Table

addons[].param ​

Addons generated by bkeadm by default:

Table 5 bkeadm Default Addon Parameters Table

Commonly used addon names and parameters:

Table 6 Common Addon Parameters Table

spec.clusterConfig.customExtra{} ​

Table 7 customExtra Configuration Items Table

Port relationships and conflict check: customExtra.imageRepoPort, customExtra.chartRepoPort, and customExtra.yumRepoPort are usually derived from the --imageRepoPort, --chartRepoPort, and --yumRepoPort flags of bke init, corresponding to three independent services: the local image repository, chart repo, and yum/http repo. When customizing, they must be configured as different ports, and must avoid the Kubernetes API, console ports, and ports already occupied on the host. The bke init preflight checks whether ports are already occupied on the host and filters out existing BKE management container ports; however, it does not explicitly check for duplicates among these parameters. If ports are duplicated, failures may occur during service startup or port publishing, and you need to adjust based on the port occupancy information in the logs and retry.

BKENode CRD ​

Table 8 BKENode CRD Configuration Items Table

ContainerdConfig CRD ​

Table 9 ContainerdConfig CRD Configuration Items Table

KubeletConfig CRD ​

Table 10 KubeletConfig CRD Configuration Items Table

KCT and CCT Configuration and References ​

KCT (KubeletConfig) and CCT (ContainerdConfig) are custom resources on the management cluster, used to deliver kubelet and containerd configurations during the node bootstrap phase, without the need to log into nodes and manually edit files.

Table 11 KCT and CCT Comparison Table

Usage Workflow

1. Create KCT/CCT resources on the management cluster (the same cluster as BKECluster) and fill in the spec configuration.
2. Point to the corresponding resources via the reference fields in the BKECluster YAML; the default cluster YAML generated by bke init already contains example references.
3. After running bke create cluster, bkeagent reads and applies the configuration during the node bootstrap phase:
   • KCT: When KubeletConfigRef is not empty, bkeagent pulls the KubeletConfig from the management cluster and processes spec.files[], spec.kubeletConfig (writes to /var/lib/kubelet/config.yaml), spec.kubeletService (generates kubelet.service), and spec.commands[] in order; variable substitution (${EXPR|command|END}) is automatically enabled.
   • CCT: When containerdConfigRef is not empty, bkeagent passes it to the InstallContainerd plugin in namespace:name form, and renders the containerd configuration and restarts the service in the order spec.script → spec.service → spec.main → spec.registry.

KCT/CCT Configuration Example (BKECluster snippet)

spec:
  KubeletConfigRef:
    name: bke-kubelet
    namespace: bke-kubelet
  clusterConfig:
    cluster:
      containerdConfigRef:
        name: bke-containerd
        namespace: bke-containerd

For complete field descriptions, variable substitution examples, and YAML samples, see Binary Component Custom Configuration.

Annotations ​

Configurable Annotations ​

These annotations affect BKECluster behavior

Table 12 Configurable Annotations Table

Example scenarios for using the retry annotation:

1. Pushing the Agent fails during the EnsureBKEAgent phase.

2. The Agent is pushed successfully during the EnsureBKEAgent phase, but bkeagent fails to start on the corresponding node.

3. kubelet installation fails on the corresponding node.

4. The DNS resolution service on the corresponding node fails, causing image pull failures.

When encountering the above scenarios, users can manually fix the issue and then run the following command to add the retry annotation, so that the failed node re-executes the subsequent phases.

# Note: When the value of the retry annotation is empty, all nodes will be retried.
kubectl annotate bc -n <cluster-namespace> <cluster-name>  bke.bocloud.com/retry="<failed-node-ip>"

Non-configurable Annotations ​

BKE Internal State, Process, and Operations Annotations (13) ​

Table 13 BKE Internal State, Process, and Operations Annotations Table

ClusterVersion, Upgrade Path, and ReleaseImage Annotations (6) ​

These keys are protocols between upgrade controllers. For parameter descriptions and collaboration relationships, see Backend Declarative Upgrade Guide#controller-parameters-and-upgrade-annotations.

Table 14 ClusterVersion, Upgrade Path, and ReleaseImage Annotations Table

When the upgrade is completed, cancelled, or cleaned up, the controller removes upgrade-ready, cluster-version, and upgrade-path together.

Cluster API Standard Annotations (8) ​

The semantics of these keys are mainly defined by upstream Cluster API. This repository is responsible for setting, deleting, or consuming them, so they are also part of the actual annotation surface.

Table 15 Cluster API Standard Annotations Table

kubeadm, Kubernetes, and Static Pod Annotations (7) ​

Table 16 kubeadm, Kubernetes, and Static Pod Annotations Table

Deployment Manifest and Generation Tool Annotations (5) ​

Table 17 Deployment Manifest and Generation Tool Annotations Table