Synthesize a cluster

"Synthesize" is the act of making a cluster managed by Project Syn

This how-to will show you how to synthesize a cluster.

Prerequisites

  • cluster-admin permissions on the cluster to synthesize.

  • Write access in the Project Syn "Clusters" view on control.vshn.net.

  • Access to the Lieutenant cluster.

  • The Syn tenant of the cluster to synthesize exists already. If the tenant doesn’t exist yet, see the documentation on creating a tenant.

Procedure

  1. Create a new cluster in control.vshn.net. See section "creating a new cluster on control.vshn.net" of the "Synthesize a cluster" explanation for a more detailed breakdown of the form fields.

  2. Note down the kubectl command shown, you’ll need it later.

    Right now, you need to refresh the page you land on after creating a cluster in order for the command to be shown. We are working on addressing this issue, see Jira ticket PORTAL-50.

  3. Run Commodore to create a local checkout of the new cluster’s configuration. See the Project Syn "compile a catalog" how-to. Use https://api.syn.vshn.net as the value for LIEUTENANT_URL. Skip the "Cleanup" of that tutorial step for now.

  4. Add any required initial configurations to your new cluster in inventory/classes/<tenant-id>/<cluster-id>.yml

  5. Run commodore catalog compile --push <cluster-id> to push the initial cluster catalog to git.vshn.net.

  6. Create any required secrets in Vault. See the section on adding required tokens to Vault for a more detailed explanation on adding secrets.

    If you can’t add secrets to Vault, ask for synroot group privileges in Vault.

  7. Install Steward on the new cluster by executing the kubectl command you noted down in step 2.

    Make sure the kubectl command in this step is executed against the cluster to synthesize
    See the documentation of the bootstrap token and install URL for a more detailed explanation, including instructions on how to fetch the install URL from the Lieutenant API and instructions to reset the bootstrap token.