clusterctl

The clusterctl application manages microservice clusters. You use it to:

You run this application from the command line of one of the servers in the cluster as the root user.

Administration Details

The following list shows the technical details you will need for advanced administration of the application:

Argument Options Description Example
add host --host <host_name> Adds a new host to the cluster. The host must have the Cluster.Master or Cluster.Worker role installed on it. You can include multiple --host options to add multiple hosts. clusterctl add host --host host1.example.com --host host2.example.com
add namespace --namespace <namespace_name> Adds a new namespace to the cluster. Default namespaces are created automatically when you create the cluster and when you add zones, but you can use this option to add any additional required namespaces, such as when you install Vision. clusterctl add namespace --namespace a1-vision
add zone One of the following options is required:
  • --zone <N>: By default, adds the zone to the primary cluster.
  • --zone <N> --secondary: Adds the zone to the secondary cluster.
  • --zone <N> --primary: Adds the zone to the primary cluster.
 Adds a new zone to the cluster. You can include multiple --zone options to add multiple zones. If you include the --secondary or --primary option, the specified zones cannot already be members of other clusters.
When you add a zone, a corresponding namespace is created in the form a1-zone<zonedId>-pri or a1-zone<zonedId>-sec.		 Add zone 6 to the secondary cluster, creating the a1-zone6-sec namespace:
clusterctl add zone --zone 6 --secondary
create All of the following options are optional:
  • <cluster_name>: The name of the cluster. If not specified, defaults to cluster-<N>, where <N> is the next available ID.
  • --zone <N>: The zone for the cluster. If not specified, defaults to 1, for the a1-zone1-pri zone.
  • --no-zone: Use for clusters where zones are not needed, such as for Vision.
  • --secondary: Required if creating a secondary cluster. Without this option, a primary cluster is created.
  • --host <host_FQDN>: A host to include in the cluster. Include this option multiple times to include multiple hosts. If you do not include it, all hosts with the Cluster.Master and Cluster.Worker role are included.
  • --clusterfqdn <cluster_FQDN>: The cluster-level FQDN to use for high availability. If not specified, the first host FQDN is used.
  • --enable-load-balancer: Whether to enable the load balancer. Not supported if you do not specify --clusterfqdn, or if --clusterfqdn is the same as one of the hosts.
 Creates a new cluster. Each cluster can have either one or three servers with the Cluster.Master role. If clusterctl detects anything other than one or three Cluster.Master servers, it will not create the cluster. Create a primary cluster with default values (default name and zone, use all hosts with cluster roles, use the first host FQDN as the cluster FQDN, and do not enable the load balancer):
clusterctl create

Create a secondary cluster called SecondaryCluster, with zone 2, include the specified hosts, use the specified cluster FQDN, and enable the load balancer:
clusterctl create SecondaryCluster --zone 2 --secondary --host host1.example.com --host host2.example.com --host host3.example.com --clusterfqdn cluster.example.com --enable-load-balancer
delete N/A Deletes the current cluster.
After deleting the cluster, you may need to clean up some cluster artifacts from the server before reusing it. See Deleting Clusters for more information.		 clusterctl delete
detach N/A If the current host is part of a redundant cluster, detaches the redundant cluster. clusterctl detach
drop host --host <host_FQDN> Removes the specified host from the current cluster. You can include multiple --host options to drop multiple hosts.
When dropping a host, you must run additional the a1k commands shown in the example to cordon off and drain the associated node, then delete the node.		 Run all of the following commands in sequence:
a1k cordon <node>
a1k drain <node> --ignore-daemonsets --delete-emptydir-data
clusterctl drop host --host <host_FQDN>
a1k delete node <node>
where <node> is the node where the host was deployed. You can find the nodes in your cluster by running the a1k get nodes command.
drop namespace --namespace Removes the specified namespace from the current cluster. You can include multiple --namespace options to drop multiple namespaces. clusterctl drop namespace --namespace a1-vision
drop zone One of the following options is required:
  • --zone <N>: Remove the zone. By default, the zone is removed from the primary cluster.
  • --zone <N> --secondary: Removes the zone from the secondary cluster.
  • --zone <N> --primary: Remove the zone from the primary cluster.
 Removes the specified zone from the cluster. You can include multiple --zone options to drop multiple zones. Remove zone 6 from the secondary cluster:
clusterctl drop zone --zone 6 --secondary
join
  • --primaryCluster <primary_cluster_name_or_host> --secondaryCluster <secondary_cluster_name_or_host>: Required. You can use the cluster name, the cluster FQDN, or any host FQDN in the cluster.
  • --repo <repository_host_FQDN>: Optional. The host FQDN to pull images from. Defaults to the primary cluster's host. If you are running the command from a server outside of the cluster, use the primary presentation server's web FQDN.
 Joins the specified clusters. You can run this command from any server in the target primary or secondary cluster, or from a server outside of the cluster if you set the --repo option. clusterctl join --primaryCluster host1.example.com --secondaryCluster host2.example.com
update N/A NOT SUPPORTED
Primarily used to update from one master node to three master nodes, which is not currently supported on Unified Assurance. If you use this option, the following error appears: This command is currently disabled in this version		 clusterctl update
update-config N/A Updates the configuration (configmap) of the current cluster. Use this argument after installing new servers with the Cluster.Master or Cluster.Worker role, or, when you are using the Historical database, after creating a cluster. clusterctl update-config
upgrade N/A Primarily used to upgrade an existing cluster after making customizations to the configuration file, or after updating Unified Assurance. clusterctl upgrade