|
| 1 | +# Required configuration |
| 2 | + |
| 3 | +The cluster configuration file can be generated by using [`clusterctl generate cluster`][clusterctl-generate-cluster] command. |
| 4 | +This command actually uses [the template file][template-file] and replace the values surrounded by `${}` with environment variables. You have to set all required environment variables in advance. The following sections explain some more details about what should be configured. |
| 5 | + |
| 6 | +Note: You can use [the template file][template-file] by manually replacing values. |
| 7 | + |
| 8 | +```bash |
| 9 | +clusterctl generate cluster capi-quickstart \ |
| 10 | + --kubernetes-version v1.21.3 \ |
| 11 | + --control-plane-machine-count=1 \ |
| 12 | + --worker-machine-count=1 \ |
| 13 | + > capi-quickstart.yaml |
| 14 | +``` |
| 15 | + |
| 16 | +In order to fetch the configuration parameters via the terminal, please install [cmk][cmk-download] and [jq][jq-download] |
| 17 | + |
| 18 | +## Cluster Level Configurations |
| 19 | + |
| 20 | +These configurations are passed while defining the `CloudStackCluster` and apply to the entire cluster. |
| 21 | + |
| 22 | +### Zone |
| 23 | + |
| 24 | +The Zone must be exposed as an environment variable `CLOUDSTACK_ZONE_NAME` and is a mandatory parameter. |
| 25 | +As of now, only advanced zones without security groups is supported. |
| 26 | + |
| 27 | +The list of zones can be fetched using the cmk cli as follows : |
| 28 | +``` |
| 29 | +cmk list zones listall=true | jq '.zone[] | {name, id}' |
| 30 | +``` |
| 31 | + |
| 32 | +### Network |
| 33 | + |
| 34 | +The network must be exposed as an environment variable `CLOUDSTACK_NETWORK_NAME` and is a mandatory parameter. |
| 35 | +As of now, only isolated and shared networks are supported. |
| 36 | +If the specified network does not exist, a new isolated network will be created. |
| 37 | + |
| 38 | +The list of networks for the specific zone can be fetched using the cmk cli as follows : |
| 39 | +``` |
| 40 | +cmk list networks listall=true zoneid=<zoneid> | jq '.network[] | {name, id, type}' |
| 41 | +``` |
| 42 | + |
| 43 | + |
| 44 | +### Endpoint |
| 45 | + |
| 46 | +The endpoint of the workload cluster. It can either be an IP or an FQDN which is resolvable from the management cluster |
| 47 | + |
| 48 | +If on an isolated network, and the endpoint is an IP, it must be an IP in the Public IP range. |
| 49 | +The necessary Firewall and LoadBalancing rules will be automatically created on Apache CloudStack for the specified IP. |
| 50 | + |
| 51 | +If on a shared network, and the endpoint is an IP, it must belong to the shared network range and not allocated to any other resource on CloudStack. |
| 52 | + |
| 53 | +The Endpoint is exposed in two parts, as the `CLUSTER_ENDPOINT_IP` and `CLUSTER_ENDPOINT_PORT` environment variables. |
| 54 | + |
| 55 | +The list of Public IPs for the specific zone can be fetched using the cmk cli as follows : |
| 56 | +``` |
| 57 | +cmk list publicipaddresses listall=true zoneid=<zone-id> forvirtualnetwork=true allocatedonly=false | jq '.publicipaddress[] | select(.state == "Free" or .state == "Reserved") | .ipaddress' |
| 58 | +``` |
| 59 | + |
| 60 | +## Machine Level Configurations |
| 61 | + |
| 62 | +These configurations are passed while defining the `CloudStackMachine`. They can differ based on the MachineSet mapped to it. |
| 63 | + |
| 64 | +### Service Offerings |
| 65 | + |
| 66 | +The service offerings for the Control Plane Nodes are specified by the `CLOUDSTACK_CONTROL_PLANE_MACHINE_OFFERING` environment variable. |
| 67 | +It must have a minimum of 2GB RAM and 2 vCPU |
| 68 | + |
| 69 | +The service offerings for the Worker Nodes are specified by the `CLOUDSTACK_WORKER_MACHINE_OFFERING` environment variable. |
| 70 | + |
| 71 | + |
| 72 | +The list of Service offerings for the specific zone can be fetched using the cmk cli as follows : |
| 73 | +``` |
| 74 | +cmk list serviceofferings listall=true zoneid=<zone-id> cpunumber=2 memory=2048 | jq '.serviceoffering[] | {name, id}' |
| 75 | +``` |
| 76 | + |
| 77 | +### Virtual Machine Template |
| 78 | + |
| 79 | +We currently depend on an up-to-date version of cloud-init otherwise the operating system choice is yours. |
| 80 | +The kubeadm bootstrap provider we're using also depends on some pre-installed software like a container runtime, kubelet, kubeadm, etc. |
| 81 | +For an examples how to build such an image take a look at [CloudStack CAPI Images][cloudstack-capi-images]. |
| 82 | + |
| 83 | +Prebuilt images can be found [here][prebuilt-images] |
| 84 | + |
| 85 | +The image can be referenced by exposing it as an environment variable `CLOUDSTACK_TEMPLATE_NAME`. |
| 86 | + |
| 87 | +The list of Templates for the specific zone can be fetched using the cmk cli as follows : |
| 88 | +``` |
| 89 | +cmk list templates zoneid=<zone-id> templatefilter=executable | jq '.template[] | {name, id}' |
| 90 | +``` |
| 91 | + |
| 92 | + |
| 93 | +# Optional Configurations |
| 94 | + |
| 95 | +## Cluster Level Configurations |
| 96 | + |
| 97 | +These configurations are passed while defining the `CloudStackCluster` and apply to the entire cluster. |
| 98 | + |
| 99 | +### Account |
| 100 | + |
| 101 | +The account in which the CAPC cluster resources are to be created. Please note that the credentials of the user passed to CAPC via the |
| 102 | +`CLOUDSTACK_B64ENCODED_SECRET` must have access the the specified account. |
| 103 | + |
| 104 | +The account can be specified by adding the `CloudStackCluster.spec.account` field in the yaml specification |
| 105 | + |
| 106 | +The list of accounts can be fetched using the cmk cli as follows : |
| 107 | +``` |
| 108 | +cmk list accounts listall=true | jq '.account[] | {name, id}' |
| 109 | +``` |
| 110 | + |
| 111 | +> Please note that if the optional configurations of account and domainid are passed, |
| 112 | +> the corresponding account must have access to the specified resources on CloudStack such as the |
| 113 | +> Network, Public IP, VM Template, Service Offering, SSH Key, Affinity Group, etc |
| 114 | +
|
| 115 | +### Domain |
| 116 | + |
| 117 | +The domain / subdomain in which the CAPC cluster resources are to be created. Please note that the credentials of the user passed to CAPC via the |
| 118 | +`CLOUDSTACK_B64ENCODED_SECRET` must have access the the specified domain |
| 119 | + |
| 120 | +The domain can be specified by adding the `CloudStackCluster.spec.domain` field in the yaml specification |
| 121 | + |
| 122 | +The list of domains can be fetched using the cmk cli as follows : |
| 123 | +``` |
| 124 | +cmk list domains listall=true | jq '.domain[] | {name, id, path}' |
| 125 | +``` |
| 126 | + |
| 127 | +> Please note that if the optional configurations of account and domainid are passed, |
| 128 | +> the corresponding account must have access to the specified resources on CloudStack such as the |
| 129 | +> Network, Public IP, VM Template, Service Offering, SSH Key, Affinity Group, etc |
| 130 | +
|
| 131 | +## Machine Level Configurations |
| 132 | + |
| 133 | +These configurations are passed while defining the `CloudStackMachine`. They can differ based on the MachineSet mapped. |
| 134 | + |
| 135 | +### SSH KeyPair |
| 136 | + |
| 137 | +The SSH key pair must be an existing key registered in Apache CloudStack and is exposed as the environment variable `CLOUDSTACK_SSH_KEY_NAME`. |
| 138 | + |
| 139 | +The ssh keypair can be specified by adding the `CloudStackMachine.spec.sshKey` field in the yaml specification |
| 140 | + |
| 141 | +The list of SSH Keypairs can be fetched using the cmk cli as follows : |
| 142 | +``` |
| 143 | +cmk list sshkeypairs listall=true | jq '.sshkeypair[] | {name, id}' |
| 144 | +``` |
| 145 | + |
| 146 | +If the user wishes to pass a public key not registered in CloudStack directly to the node, it can be done by adding the `KubeadmConfigTemplate.spec.template.spec.users` |
| 147 | +spec in the cluster definition yaml. Eg: |
| 148 | + |
| 149 | +```yaml |
| 150 | +apiVersion: bootstrap.cluster.x-k8s.io/v1beta1 |
| 151 | +kind: KubeadmConfigTemplate |
| 152 | +metadata: |
| 153 | + name: ${CLUSTER_NAME}-md-0 |
| 154 | +spec: |
| 155 | + template: |
| 156 | + spec: |
| 157 | + joinConfiguration: |
| 158 | + nodeRegistration: |
| 159 | + kubeletExtraArgs: |
| 160 | + provider-id: "cloudstack:///'{{ ds.meta_data.instance_id }}'" |
| 161 | + name: '{{ local_hostname }}' |
| 162 | + users: |
| 163 | + - name: ${OS_USERID} |
| 164 | + sshAuthorizedKeys: |
| 165 | + - ${SSH_KEY_MATERIAL} |
| 166 | + sudo: ALL=(ALL) NOPASSWD:ALL |
| 167 | +``` |
| 168 | +
|
| 169 | +To learn how to configure the required network access in order to SSH into the node, please see [here](../topics/ssh-access.html) |
| 170 | +
|
| 171 | +### Affinity Groups |
| 172 | +
|
| 173 | +The nodes in the MachineDeployment mapped to a corresponding CloudStackMachine can have a specific host affinity or be assigned to affinity groups. |
| 174 | +The affinity can either be specified `pro` (host affinity) or `anti` (host anti affinity) in the `CloudStackMachine.spec.affinity` field in the yaml specification and the required affinity groups will be created in CloudStack |
| 175 | +If existing affinity groups in CloudStack wish to be used, the group IDs can be passed as a list in the `CloudStackMachine.spec.affinitygroupids` field in the yaml specification |
| 176 | + |
| 177 | +The list of existing affinity groups can be fetched using the cmk cli as follows : |
| 178 | +``` |
| 179 | +cmk list affinitygroups listall=true | jq '.affinitygroup[] | {name, id}' |
| 180 | +``` |
| 181 | + |
| 182 | + |
| 183 | +### VM Details |
| 184 | + |
| 185 | +These are arbitrary key value pairs which are passed as VM details while deploying the nodes. |
| 186 | + |
| 187 | +The VM details can be specified by adding the `CloudStackMachine.spec.details` field in the yaml specification |
| 188 | + |
| 189 | +## Log level |
| 190 | + |
| 191 | +TODO / Maybe add feature ? |
| 192 | + |
| 193 | +## Timeout settings |
| 194 | + |
| 195 | +TODO / Add feature |
| 196 | + |
| 197 | +# Apache CloudStack Credentials |
| 198 | + |
| 199 | + 1. Generate the API and Secret Key for your Apache CloudStack instance either via the UI (Accounts > User > API Key) or the `getUserKeys` API. |
| 200 | + |
| 201 | + 2. Create a file named `cloud-config`, substituting in your own environment's values |
| 202 | + ``` |
| 203 | + [Global] |
| 204 | + api-url = <cloudstackApiUrl> |
| 205 | + api-key = <cloudstackApiKey> |
| 206 | + secret-key = <cloudstackSecretKey> |
| 207 | + ``` |
| 208 | + |
| 209 | + 3. Run the following command to save the above Apache CloudStack connection info into an environment variable : |
| 210 | + ``` |
| 211 | + export CLOUDSTACK_B64ENCODED_SECRET=$(base64 -w0 -i cloud-config) |
| 212 | + ``` |
| 213 | + |
| 214 | + 4. Once exported, the management cluster can be initialized with Apache CloudStack as the underlying infrastructure provider |
| 215 | + ``` |
| 216 | + clusterctl init --infrastructure cloudstack |
| 217 | + ``` |
| 218 | + |
| 219 | +<!-- References --> |
| 220 | + |
| 221 | +[cloudstack-capi-images]: https://image-builder.sigs.k8s.io/capi/providers/cloudstack.html |
| 222 | +[clusterctl-generate-cluster]: https://cluster-api.sigs.k8s.io/user/quick-start.html#generating-the-cluster-configuration |
| 223 | +[cmk-download]: https://github.com/apache/cloudstack-cloudmonkey/releases/ |
| 224 | +[jq-download]: https://stedolan.github.io/jq/ |
| 225 | +[prebuilt-images]: http://packages.shapeblue.com/cluster-api-provider-cloudstack/images/ |
| 226 | +[template-file]: https://github.com/kubernetes-sigs/cluster-api-provider-cloudstack/blob/main/templates/cluster-template.yaml |
0 commit comments