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