Get started

Config file

By default, the multicluster controlplane would try to find ocmconfig.yaml in the current directory. You can use the customized one by setting the flag --config-file=<config-file.yaml>.

Here is a simple file of config-file.yaml:

configDirectory: ".ocmconfig"
deployToOCP: true
apiserver:
  externalHostname: "http://abcdefg.com"
  port: 9443
  caFile: "ca.crt"
  caKeyFile: "ca.key"
etcd:
  mode: external
  prefix: "/registry"
  servers:
  - http://etcd-1:2379
  - http://etcd-2:2379
  caFile: "etcd-trusted-ca.crt"
  certFile: "etcd-client.crt"
  keyFile: "etcd-client.key"

The yaml content shown above is a config file with all fields filled in. Following this to better understand the config file.

Field configDirectory is a string variable indicating the directory to store generated certs ,embed etcd data and kubeconfig, etc. While this field is missed in the config file, the default value .ocmconfig makes sense.

Field deployToOCP is a boolean variable indicating whether we are deploy the multicluster controlplane while we need to do some modification on generated files.

Field apiserver contains config for the controlplane apiserver:

externalHostname is a string variable indicating the hostname for external access. The value equals to local IP of running environment if the field is empty/missed.
port is a integer variable indicating the binding port of multicluster controlplane apiserver. The default value is 9443.
caFile is a string variable indicating the CA file provided by user to sign all the serving/client certificates.
caKeyFile is a string variable indicating the CA Key file for caFile.

Field etcd contains config for the controlplane etcd:

mode should be embed or external indicating the multicluster controlplane etcd deploy mode. The value would be embed if field mode is missed.
prefix is a string variable indicating controlplane data prefix in etcd. The default value is "/registry".
servers is a string array indicating etcd endpoints. The default value is []string{"http://127.0.0.1:2379"}.
caFile is a string variable indicating an etcd trusted ca file.
certFile is a string variable indicating a client cert file signed by caFile.
keyFile is a string variable indicating client key file for certFile.

NOTE: For apiserver field: If you want to use your own CA pair to sign the certificates, the caFile and caKeyFile should be set together. Which means that if one of the two fields is missed/empty, the controlplane would self-generate CA pair to sign the necessary certificates.

Optional: Deploy etcd on Openshift Cluster

Install etcd

Set environment variables and deploy etcd.

ETCD_NS (optional) is the namespace where the etcd is deployed in. The default is multicluster-controlplane-etcd.

For example:

$ export ETCD_NS=<etcd namespace>
$ make deploy-etcd

Install multicluster-controlplane

Before start the controlplane, we should make sure config file is in path.

Option 1: Deploy multicluster-controlplane on Openshift Cluster

Build image

$ export IMAGE_NAME=<customized image. default is quay.io/open-cluster-management/multicluster-controlplane:latest>
$ make image

Install

Set environment variables firstly and then deploy controlplane.

HUB_NAME (optional) is the namespace where the controlplane is deployed in. The default is multicluster-controlplane.
IMAGE_NAME (optional) is the customized image which can override the default image quay.io/open-cluster-management/multicluster-controlplane:latest.

For example:

$ export HUB_NAME=<hub name>
$ export IMAGE_NAME=<your image>
$ make deploy

Option 2: Run controlplane as a local binary

$ make vendor
$ make build
$ make run

Access the controlplane

The kubeconfig file of the controlplane is in the dir hack/deploy/cert-${HUB_NAME}/kubeconfig.

You can use clusteradm to access and join a cluster.

$ clusteradm --kubeconfig=<kubeconfig file> get token --use-bootstrap-token
$ clusteradm join --hub-token <hub token> --hub-apiserver <hub apiserver> --cluster-name <cluster_name>
$ clusteradm --kubeconfig=<kubeconfig file> accept --clusters <cluster_name>

Warning clusteradm version should be v0.4.1 or later

Install add-on

Currently we support to install work-manager and managed-serviceaccount add-on on the controlplane.

$ make deploy-work-manager-addon
$ make deploy-managed-serviceaccount-addon

Clean up the deploy

$ make destory

Install the multicluster-controlplane and add-ons

$ export HUB_NAME=<hub name>
$ export IMAGE_NAME=<your image>
$ make deploy-all

hchenxa/multicluster-controlplane