|
| 1 | +--- |
| 2 | +title: Add A Cluster |
| 3 | +description: How To Add An Existing Cluster to Your Plural Instance |
| 4 | +--- |
| 5 | + |
| 6 | +Adding a new cluster to Plural is very simple, it's simply a matter of installing our agent onto any end cluster, and usually follows two paths: |
| 7 | + |
| 8 | +1. Leverage our CLI which wraps a full install including registering with your Plural api and helm installing the agent on the cluster |
| 9 | +2. Use our terraform provider to wrap this whole process as Infrastructure as Code |
| 10 | + |
| 11 | +Both are functional and fully supported, and execute equivalent code under the hood. If you set up your install with `plural up` we've already wrapped a ton of fully functional GitOps workflows for you, and those usually are more featureful workflows than doing this manually. If you want to read more about them, feel free to look at the guide here: [Create a Workload Cluster](/getting-started/how-to-use/workload-cluster). |
| 12 | + |
| 13 | +{% callout severity="info" %} |
| 14 | +We strongly recommend leveraging a IaC based pattern, since it'll allow you to export terraform state into Plural for re-use and maximizes reproducibility |
| 15 | +{% /callout %} |
| 16 | + |
| 17 | + |
| 18 | +## Onboard a cluster with our CLI |
| 19 | + |
| 20 | +To add a new cluster simply run with a valid kubeconfig set up locally: |
| 21 | + |
| 22 | +```sh |
| 23 | +plural cd clusters bootstrap --name {your-cluster-name} --tag {tag}={value} --tag {tag2}={value2} |
| 24 | +``` |
| 25 | + |
| 26 | +To see all CLI options, feel free to use: |
| 27 | + |
| 28 | +```sh |
| 29 | +plural cd clusters bootstrap --help |
| 30 | +``` |
| 31 | + |
| 32 | +If you need to reinstall our agent for any reason, just use: |
| 33 | + |
| 34 | +```sh |
| 35 | +plural cd clusters reinstall @{cluster-handle} |
| 36 | +``` |
| 37 | + |
| 38 | +{% callout severity="info" %} |
| 39 | +The `@` character is required, as it allows our CLI to differentiate names from IDs. |
| 40 | + |
| 41 | +You should also address the cluster by handle in the event name is not unique in your system. |
| 42 | +{% /callout %} |
| 43 | + |
| 44 | +## Onboard a cluster with our Terraform Provider |
| 45 | + |
| 46 | +Here is a basic terraform snippet that shows how you can use our Terraform provider to install our agent |
| 47 | + |
| 48 | +```terraform |
| 49 | +resource "plural_cluster" "this" { |
| 50 | + handle = var.cluster |
| 51 | + name = var.cluster |
| 52 | + tags = { |
| 53 | + fleet = var.fleet |
| 54 | + tier = var.tier |
| 55 | + } |
| 56 | +
|
| 57 | + # metadata attaching useful cluster-level state in Plural to use for service templating |
| 58 | + metadata = jsonencode({ |
| 59 | + tier = var.tier |
| 60 | + iam = { |
| 61 | + load_balancer = module.addons.gitops_metadata.aws_load_balancer_controller_iam_role_arn |
| 62 | + cluster_autoscaler = module.addons.gitops_metadata.cluster_autoscaler_iam_role_arn |
| 63 | + external_dns = module.externaldns_irsa_role.iam_role_arn |
| 64 | + cert_manager = module.externaldns_irsa_role.iam_role_arn |
| 65 | + } |
| 66 | +
|
| 67 | + vpc_id = local.vpc.vpc_id |
| 68 | + region = var.region |
| 69 | + }) |
| 70 | +
|
| 71 | + # direct kubeconfig for this cluster |
| 72 | + kubeconfig = { |
| 73 | + host = module.eks.cluster_endpoint |
| 74 | + cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data) |
| 75 | + token = data.aws_eks_cluster_auth.cluster.token |
| 76 | + } |
| 77 | +} |
| 78 | +
|
| 79 | +# optionally can specify kubeconfig at the provider level |
| 80 | +
|
| 81 | +provider "plural" { |
| 82 | + kubeconfig = { |
| 83 | + host = module.eks.cluster_endpoint |
| 84 | + cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data) |
| 85 | + token = data.aws_eks_cluster_auth.cluster.token |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +This makes it easy to wrap Plural setup in existing IaC codebases and ensure full repeatability. |
| 91 | + |
| 92 | +The metadata block is of importance as well, as it drives our helm + yaml templating experience within Plural CD. You can see some guides around that [here](/plural-features/continuous-deployment/service-templating). |
0 commit comments