|
| 1 | +# CloudStack Cluster API Provider (CAPC) Release v.0.4.3 Evaluation Deployment Guide |
| 2 | + |
| 3 | +This document defines a manual deployment process suitable for evaluating this CAPC release. |
| 4 | + |
| 5 | +## Evaluation Environment Pre-Requisites: |
| 6 | + |
| 7 | +### - A running Kubernetes cluster for hosting CAPC |
| 8 | + |
| 9 | +This should be an easily disposable/re-creatable cluster, such as a locally-running kind (Kuberetes in Docker) cluster. |
| 10 | + |
| 11 | +Your KUBECONFIG file's *current-context* must be set to the cluster you want to use. |
| 12 | + |
| 13 | +### - CAPI clusterctl v1.0.1 (https://github.com/kubernetes-sigs/cluster-api/releases/tag/v1.0.1) |
| 14 | + |
| 15 | +This process has been tested with this version of clusterctl. Subsequent 1.0.x versions should work as well. |
| 16 | + |
| 17 | +### - A CloudStack Environment with the following resources defined |
| 18 | +- Zone |
| 19 | +- Network |
| 20 | +- CAPI-compatible QEMU template (i.e., created with https://github.com/kubernetes-sigs/image-builder) |
| 21 | +- Machine Offerings (suitable for running Kubernetes nodes) |
| 22 | +- apikey and secretkey for a CloudStack user having domain administrative privileges |
| 23 | +- Available ACS IP Address for the k8s Control Plane endpoint (Shared network: available IP address in the network range; isolated network: public IP address) |
| 24 | + |
| 25 | +## Deployment Steps |
| 26 | +### Define Identity Environment Variable |
| 27 | + |
| 28 | +An environment variable named CLOUDSTACK_B64ENCODED_SECRET must be defined, containing the base64 encoding of a |
| 29 | +cloud-config properties file. This file is of the form: |
| 30 | + |
| 31 | +``` |
| 32 | +[Global] |
| 33 | +api-url = <urlOfCloudStackAPI> |
| 34 | +api-key = <cloudstackUserApiKey> |
| 35 | +secret-key = <cloudstackUserSecretKey> |
| 36 | +``` |
| 37 | +After defining this in a file named cloud-config, create the environment variable with: |
| 38 | + |
| 39 | +``` |
| 40 | +export CLOUDSTACK_B64ENCODED_SECRET=$(base64 -w0 -i cloud-config 2>/dev/null || base64 -b 0 -i cloud-config) |
| 41 | +``` |
| 42 | + |
| 43 | +For security, delete this cloud-config file after creating this environment variable. |
| 44 | + |
| 45 | +### Deploy the supplied container image archive (.tar.gz) to a suitable image registry. |
| 46 | + |
| 47 | +*We use https://github.com/kubernetes-sigs/cluster-api/blob/main/hack/kind-install-for-capd.sh to launch a local |
| 48 | +docker registry integrated into a kind cluster for lightweight development and testing.* |
| 49 | + |
| 50 | +- On a computer with docker, load the provided cluster-api-provider-capc.tar.gz to docker: |
| 51 | +``` |
| 52 | +docker load --input cluster-api-provider-capc_v0.4.3.tar.gz |
| 53 | +``` |
| 54 | + |
| 55 | +This will create image *localhost:5000/cluster-api-provider-cloudstack:v0.4.3* in your local docker. This is suitable |
| 56 | +for pushing to a local registry. |
| 57 | + |
| 58 | +- (Optional) Tag this image for your registry. |
| 59 | +``` |
| 60 | +docker tag localhost:5000/cluster-api-provider-cloudstack:v0.4.3 <yourRepoFqdn>/cluster-api-provider-cloudstack:v0.4.3 |
| 61 | +``` |
| 62 | + |
| 63 | +Push it to your registry (localhost:5000 if using local registry) |
| 64 | +``` |
| 65 | +docker push <yourRepoFqdn>/cluster-api-provider-cloudstack:v0.4.3 |
| 66 | +``` |
| 67 | + |
| 68 | +### Create clusterctl configuration files |
| 69 | +A cluster-api.zip file has been provided, containing the files and directory structure suitable for configuring |
| 70 | +clusterctl to work with this interim release of CAPC. It should be restored under $HOME/.cluster-api. It contains: |
| 71 | + |
| 72 | +``` |
| 73 | +Archive: /Users/jweite/Dev/cluster-api-cloudstack-v0.4.3-assets/cluster-api.zip |
| 74 | +* clusterctl.yaml |
| 75 | +* dev-repository/ |
| 76 | +* dev-repository/infrastructure-cloudstack/ |
| 77 | +* dev-repository/infrastructure-cloudstack/v0.4.3/ |
| 78 | +* dev-repository/infrastructure-cloudstack/v0.4.3/cluster-template.yaml |
| 79 | +* dev-repository/infrastructure-cloudstack/v0.4.3/cluster-template-managed-ssh.yaml |
| 80 | +* dev-repository/infrastructure-cloudstack/v0.4.3/cluster-template-ssh-material.yaml |
| 81 | +* dev-repository/infrastructure-cloudstack/v0.4.3/infrastructure-components.yaml |
| 82 | +* dev-repository/infrastructure-cloudstack/v0.4.3/metadata.yaml |
| 83 | +``` |
| 84 | + |
| 85 | +*Note: If you already have a $HOME/.cluster-api we strongly suggest you delete or stash it.* |
| 86 | + |
| 87 | +``` |
| 88 | +cd ~ |
| 89 | +mkdir .cluster-api |
| 90 | +cd .cluster-api |
| 91 | +unzip cluster-api.zip |
| 92 | +``` |
| 93 | + |
| 94 | +### Edit the clusterctl configuration files |
| 95 | +- **clusterctl.yaml:** in the *url* attribute replace \<USERID\> with your OS user id to form a valid absolute path to infrastructure-components.yaml. |
| 96 | + |
| 97 | +- **dev-repository/infrastructure-cloudstack/v0.4.3/infrastructure-components.yaml:** if you're not using a local registry modify the capc-controller-manager deployment, changing the spec.template.spec.containers[0].image (line 617) to correctly reflect your container registry. |
| 98 | + |
| 99 | +### Deploy CAPI and CAPC to your bootstrap Kubernetes cluster |
| 100 | +``` |
| 101 | +clusterctl init --infrastructure cloudstack |
| 102 | +``` |
| 103 | + |
| 104 | +### Generate a manifest for the CAPI custom resources needed to allocate a workload cluster. |
| 105 | + |
| 106 | +*Set the below environment variables as appropriate for your CloudStack environment.* |
| 107 | + |
| 108 | +``` |
| 109 | +CLOUDSTACK_ZONE_NAME=<MyZoneName> \ |
| 110 | +CLOUDSTACK_NETWORK_NAME=<MyNetworkName> \ |
| 111 | +CLOUDSTACK_TEMPLATE_NAME=<MyTemplateName> \ |
| 112 | +CLOUDSTACK_CONTROL_PLANE_MACHINE_OFFERING=<MyServiceOfferingName> \ |
| 113 | +CONTROL_PLANE_MACHINE_COUNT=1 \ |
| 114 | +CLOUDSTACK_WORKER_MACHINE_OFFERING=<MyServiceOfferingName> \ |
| 115 | +WORKER_MACHINE_COUNT=1 \ |
| 116 | +CLUSTER_ENDPOINT_IP=<AvailableSharedOrPublicIP> \ |
| 117 | +CLUSTER_ENDPOINT_PORT=6443 \ |
| 118 | +KUBERNETES_VERSION=<KubernetesVersionOnTheImage> \ |
| 119 | +CLUSTER_NAME=<MyClusterName> \ |
| 120 | +clusterctl generate cluster $CLUSTER_NAME --from ~/.cluster-api/dev-repository/infrastructure-cloudstack/v0.4.3/cluster-template.yaml > clusterTemplate.yaml |
| 121 | +``` |
| 122 | + |
| 123 | +### Review the generated clusterTemplate.yaml and adjust as necessary |
| 124 | + |
| 125 | + |
| 126 | +### Provision your workload cluster |
| 127 | + |
| 128 | +``` |
| 129 | +kubectl apply -f clusterTemplate.yaml |
| 130 | +``` |
| 131 | + |
| 132 | +Provisioning can take several minutes to complete. You will see a control plane VM created in CloudStack pretty quickly, |
| 133 | +but it takes a while for it to complete its cloud-init to install Kubernetes and become a functioning control plane. |
| 134 | +Allocation of the worker node(s) (with *md* in their VM names) won't occur until the control plane is operational. |
| 135 | + |
| 136 | +You can monitor the CAPC controller as it conducts the provisioning process with: |
| 137 | +``` |
| 138 | +# Get the full name of the CAPC controller pod |
| 139 | +kubectl -n capc-system get pods |
| 140 | +
|
| 141 | +# Tail its logs |
| 142 | +kubectl -n capc-system log -f <CAPCcontrollerPodFullName> |
| 143 | +``` |
| 144 | + |
| 145 | +### Fetch a kubeconfig to access your cluster |
| 146 | +``` |
| 147 | +clusterctl get kubeconfig <clusterName> > <clusterName>_kubeconfig |
| 148 | +``` |
| 149 | + |
| 150 | +You can then either export a KUBECONFIG environment variable pointing to this file, or use kubectl's --kubeconfig=<filePath> |
| 151 | +flag. |
| 152 | +``` |
| 153 | +export KUBECONFIG=<clusterName>_kubeconfig |
| 154 | +``` |
| 155 | + |
| 156 | +### Examine the provisioned Kubernetes Cluster's nodes |
| 157 | +``` |
| 158 | +kubectl get nodes |
| 159 | +``` |
| 160 | +Expect to see a control plane and a worker node reported by Kubernetes. Neither will report that they are ready |
| 161 | +because no CNI is installed yet. |
| 162 | + |
| 163 | +### Install Cilium CNI |
| 164 | +``` |
| 165 | +cilium install |
| 166 | +``` |
| 167 | +The above command presumes that the cilium installer is present on the local workstation. |
| 168 | + |
| 169 | +It will take a minute while it waits for cilium to become active. |
| 170 | + |
| 171 | +### Confirm that Cluster is Ready for Work |
| 172 | +``` |
| 173 | +kubectl get nodes |
| 174 | +``` |
| 175 | +Expect now to see both nodes list as ready. |
| 176 | + |
| 177 | +### Conclusion |
| 178 | +At this point the workload cluster is ready to accept workloads. Use it in the usual way via the kubeconfig generated |
| 179 | +earlier |
| 180 | + |
| 181 | +### Cluster Deletion |
| 182 | +As mentioned in the preface, CAPC is not yet able to delete workload cluster. To do so manually we recommend |
| 183 | +simply tearing-down the kind bootstrap cluster, and then manually deleting the CloudStack VMs created for it |
| 184 | +using the CloudStack UI, API or similar facilities. |
0 commit comments