Merge pull request #157 from jweite-amazon/v0.4.7-Docs

Revised doc files for V0.4.7

Author: rejoshed

docs/book/src/clustercloudstack/configuration.md

@@ -1,9 +1,10 @@
 # Required configuration
 
 The cluster configuration file can be generated by using [`clusterctl generate cluster`][clusterctl-generate-cluster] command.
-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.
+This command actually uses [a template file][template-file] and replaces 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.
 
-Note: You can use [the template file][template-file] by manually replacing values.
+Note: You can also use [template files][template-file] by manually replacing values in copies of the template file.
 
 ```bash
 clusterctl generate cluster capi-quickstart \
@@ -13,25 +14,52 @@ clusterctl generate cluster capi-quickstart \
   > capi-quickstart.yaml
 ```
 
+Note: additional template files are provided, offering capabilities beyond the default template file.  These can be
+utilized via the *clusterctl --flavor* parameter.  Additional environment variables are often required by these templates.
+See clusterctl documentation for further details about *flavors*.
+
 In order to fetch the configuration parameters via the terminal, please install [cmk][cmk-download] and [jq][jq-download]
 
 ## Cluster Level Configurations
 
 These configurations are passed while defining the `CloudStackCluster` and apply to the entire cluster.
 
-### Zone
+### Failure Domains
+
+The *Cluster API Provider* offers high-availability clusters deployed across multiple *Failure Domains*, each of which is
+a diverse set of infrastructure that doesn't share required dependencies (such as power source, networking provider)
+with other failure domains.  In the face of a dependency failure, only cluster members deployed on the failed failure
+domain will themselves fail.  The remaining cluster members will continue operation, and the cluster manager will likely
+restore capacity by allocating replacement cluster members in the surviving failure domains.
+
+*CloudStack* implements this concept with *Zones*.  The *Cluster API Provider CloudStack* enables end-users to specify
+the CloudStack Zone for each Failure Domain, as well as the particular network of this Zone to use. 
+
+The templates provided with *ClusterAPI Provider CloudStack* only define a single failure domain, mapped to a specific
+CloudStack Zone and a specific network on that CloudStack Zone.  The below parameters allow the end user to define these.
+No additional parameters are required to use these templates.  
+
+*ClusterAPI Provider CloudStack* additionally supports optional attributes beyond these, allowing each Failure Domain 
+to use a distinct Domain/Account or CloudStack management endpoint. Note that these additional attributes are not 
+utilized in the provided templates.
+
+Advanced users can define cluster templates manually that declare additional Failure Domains, and can utilize the 
+additional failure domain attributes supported by *ClusterAPI Provider CloudStack*.  See the [failure domain API definition][failure-domain-api] 
+for more details.
+
+#### Zone
 
-The Zone must be exposed as an environment variable `CLOUDSTACK_ZONE_NAME` and is a mandatory parameter.
+The Zone must be declared via an environment variable `CLOUDSTACK_ZONE_NAME` and is a mandatory parameter.
 As of now, only advanced zones without security groups is supported.
 
 The list of zones can be fetched using the cmk cli as follows :
 ```
 cmk list zones listall=true | jq '.zone[] | {name, id}'
 ```
 
-### Network
+#### Network
 
-The network must be exposed as an environment variable `CLOUDSTACK_NETWORK_NAME` and is a mandatory parameter.
+The network must be declared as an environment variable `CLOUDSTACK_NETWORK_NAME` and is a mandatory parameter.
 As of now, only isolated and shared networks are supported.
 If the specified network does not exist, a new isolated network will be created.
 
@@ -40,17 +68,41 @@ The list of networks for the specific zone can be fetched using the cmk cli as f
 cmk list networks listall=true zoneid=<zoneid> | jq '.network[] | {name, id, type}'
 ```
 
+#### CloudStack Endpoint Credentials Secret (*optional for provided templates when used with provided getting-started process*)
+
+A reference to a Kubernetes Secret containing a YAML object containing credentials for accessing a particular CloudStack 
+management endpoint.  The YAML object is of the form:
+
+```
+         api-url: <cloudstackApiUrl>
+         api-key: <cloudstackApiKey>
+         secret-key: <cloudstackSecretKey>
+         verify-ssl: true|false
+```
+
+Optional environment Variables `CLOUDSTACK_FD1_SECRET_NAME` and `CLOUDSTACK_FD1_SECRET_NAMESPACE` allow the end-user
+to override the template's default settings, utilizing a differently named secret.
+
+#### CloudStack Failure Domain Name (*optional for provided templates*)
+
+When using multiple Failure Domains each requires a distinct name.  The provided templates *do not* configure multiple
+Failure Domains, and only utilize a default name.  This name can be changed by defining environment variable 
+`CLOUDSTACK_FD1_NAME`.  Doing so has no effect on the operation of clusters defined with the templates.  This
+option is included mainly to convey the need and mechanism for naming failure domains when multiple failure
+domains are defined via custom-authored templates.
 
-### Endpoint
+### Cluster Endpoint
 
-The endpoint of the workload cluster. It can either be an IP or an FQDN which is resolvable from the management cluster
+The endpoint of the workload cluster that will be provisioned. It can either be an IP or an FQDN, resolvable 
+from the management cluster.
 
 If on an isolated network, and the endpoint is an IP, it must be an IP in the Public IP range.
 The necessary Firewall and LoadBalancing rules will be automatically created on Apache CloudStack for the specified IP.
 
 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.
 
 The Endpoint is exposed in two parts, as the `CLUSTER_ENDPOINT_IP` and `CLUSTER_ENDPOINT_PORT` environment variables.
+`CLUSTER_ENDPOINT_PORT` is optional, and defaults to *6443*.
 
 The list of Public IPs for the specific zone can be fetched using the cmk cli as follows :
 ```
@@ -224,3 +276,4 @@ TODO / Add feature
 [jq-download]: https://stedolan.github.io/jq/
 [prebuilt-images]: http://packages.shapeblue.com/cluster-api-provider-cloudstack/images/
 [template-file]: https://github.com/kubernetes-sigs/cluster-api-provider-cloudstack/blob/main/templates/cluster-template.yaml
+[failure-domain-api]: https://github.com/kubernetes-sigs/cluster-api-provider-cloudstack/blob/main/api/v1beta2/cloudstackfailuredomain_types.go

docs/book/src/development/common.md

@@ -31,7 +31,7 @@
     # Referring to a prerequisite capi-compatible image you've loaded into Apache CloudStack
     export CLOUDSTACK_TEMPLATE_NAME=kube-v1.20.10/ubuntu-2004
 
-    # The SSH KeyPair to log into the VM (Optional)
+    # The SSH KeyPair to log into the VM (Optional: use flavor *managed-ssh*)
     export CLOUDSTACK_SSH_KEY_NAME=CAPCKeyPair6
     ```
 

docs/book/src/getting-started.md

@@ -9,32 +9,40 @@
     Optional if you do not have an existing Kubernetes cluster
     - [kind][kind-install]
     - [Docker][docker-install]
-
-2. Set up Apache CloudStack credentials
-    - Create a file named `cloud-config` in the repo's root directory, substituting in your own environment's values
-        ```
-        [Global]
-        api-url = <cloudstackApiUrl>
-        api-key = <cloudstackApiKey>
-        secret-key = <cloudstackSecretKey>
-        ```
-
-    - Run the following command to save the above Apache CloudStack connection info into an environment variable, to be used by clusterctl, where it gets passed to CAPC:
-        ```
-        export CLOUDSTACK_B64ENCODED_SECRET=$(base64 -w0 -i cloud-config)
-        ```
-
-3. Register the capi-compatible templates in your Apache CloudStack installation.
+    
+2. Register the capi-compatible templates in your Apache CloudStack installation.
     - Prebuilt images can be found [here][prebuilt-images]
     - To build a compatible image see [CloudStack CAPI Images][cloudstack-capi-images]
 
-4. Create a management cluster. This can either be :
-    - An existing Kubernetes cluster : For production use-cases a "real" Kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. The Kubernetes cluster must be at least v1.19.1.
+3. Create a management cluster. This can either be :
+    - An existing Kubernetes cluster: For production use-cases a "real" Kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. The Kubernetes cluster must be at least v1.19.1.
 
     - A local cluster created with `kind`, for non production use
         ```
         kind create cluster
         ```
+4. Set up Apache CloudStack credentials as a secret in the management cluster
+   - Create a file named `cloud-config.yaml` in the repo's root directory, substituting in your own environment's values
+       ```
+       apiVersion: v1
+       kind: Secret
+       metadata:
+         name: cloudstack-credentials
+         namespace: default
+       type: Opaque
+       stringData:
+         api-key: <cloudstackApiKey>
+         secret-key: <cloudstackSecretKey>
+         api-url: <cloudstackApiUrl>
+         verify-ssl: "false"
+
+       ```
+   - Apply this secret to the management cluster:
+     - With the management cluster's KUBECONFIG in effect:
+        ```
+       kubectl apply -f cloud-config.yaml
+       ```
+   - Delete cloud-config.yaml when done, for security
 
 
 ### Initialize the management cluster