managing-clusters.html.md.erb

---
title: Managing Kubernetes Clusters for Tanzu Service Manager
owner: Platform Engineering (TSMGR Team)
---

<strong><%= modified_date %></strong>

This topic describes how to register, manage, and deregister Kubernetes clusters
for use with <%= vars.product_full %> (<%= vars.product_short %>).


## <a id='overview'></a> Overview

Before offering a service with <%= vars.product_short %>, you must register the Kubernetes clusters
that service instances use.
For more information about how to register your clusters with <%= vars.product_short %>,
see [Kubernetes Cluster Registration](#registration-management) below.

To register clusters, you must first create a cluster credentials file.
See [Create a Cluster Credentials File](#create-cluster-file) below.

After you have registered your clusters with <%= vars.product_short %>, you can provision each plan
in your <%= vars.product_short %> service offering to a different cluster.
Provisioning to different clusters allows you to require special cluster configurations.
You can also set a default cluster to provision plans to.
See [Set a Default Kubernetes Cluster](#set-default) below.


## <a id='create-cluster-file'></a> Create a Cluster Credentials File

You need a cluster credential file to register Kubernetes clusters with <%= vars.product_short %>.
A valid cluster credentials file has the following structure:

```yaml
token: TOKEN
server: SERVER
caData: CA-DATA
```
Where:

+ `TOKEN` is a valid Kubernetes authentication token.
+ `SERVER` is the server address of the Kubernetes cluster.
+ `CA-DATA` is valid certificate authority (CA) data for the Kubernetes cluster.

To create a cluster credentials file:

1. Get your server and certificate authority by running:

    ```
    cluster=$(kubectl config view -o jsonpath="{.contexts[?(@.name == \"$(kubectl config current-context)\")].context.cluster}")

    server=$(kubectl config view -o jsonpath="{.clusters[?(@.name == \"$cluster\")].cluster.server}")

    certificate=$(kubectl config view --raw --flatten -o jsonpath="{.clusters[?(@.name == \"$cluster\")].cluster.certificate-authority-data}")

    echo "Using cluster $cluster"
    ```

1. To create a dedicated service account for <%= vars.product_short %> with the `cluster-admin` role
in a dedicated namespace:
    1. Create the namespace by running:

        ```
        kubectl create ns <%= vars.product_cli %>-system
        ```

    1. Create a YAML file for the <%= vars.product_short %> service account and `ClusterRoleBinding`
    using the following YAML:

        ```
        ---
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: <%= vars.product_cli %>-admin
          namespace: <%= vars.product_cli %>-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1beta1
        kind: ClusterRoleBinding
        metadata:
          name: <%= vars.product_cli %>-cluster-admin
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cluster-admin
        subjects:
          - kind: ServiceAccount
            name: <%= vars.product_cli %>-admin
            namespace: <%= vars.product_cli %>-system
        ```

        For information about service accounts,
        see [Managing Service Accounts](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin)
        in the Kubernetes documentation.<br>
        For information about `ClusterRoleBinding`,
        see [RoleBinding and ClusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding)
        in the Kubernetes documentation.<br><br>
    1. Create the service account and `ClusterRoleBinding` defined in your YAML file by running:

        ```
        kubectl apply -f SERVICE-ACCOUNT.yml
        ```
        Where `SERVICE-ACCOUNT` is name of the YAML file you created in the previous step.

1. Get your service account token by running:

    ```
    secret_name=$(kubectl get serviceaccount <%= vars.product_cli %>-admin \
     --namespace=<%= vars.product_cli %>-system -o jsonpath='{.secrets[0].name}')

    secret_val=$(kubectl --namespace=<%= vars.product_cli %>-system get secret $secret_name \
     -o jsonpath='{.data.token}')

    secret_val=$(echo ${secret_val} | base64 --decode)
    ```

1. Save your service account token, server, and certificate to a file by running:

    ```
    cat > cluster-creds.yaml << EOF
    token: ${secret_val}
    server: ${server}
    caData: ${certificate}
    EOF
    ```


## <a id="registration-management"></a> Kubernetes Cluster Registration

The following sections describe how to list, register, and deregister Kubernetes clusters.

You can register individual clusters and set a default cluster.

See the following sections:

- **Register clusters individually:** See [Register a Kubernetes Cluster](#registering) below.

- **Set a default registered cluster:** See [Set a Default Kubernetes Cluster](#set-default) below.

- **List clusters that are registered:** See [List Registered Kubernetes Clusters](#listing) below.

- **Deregister a cluster:** See [Deregister a Kubernetes Cluster](#deregistering) below.


### <a id='registering'></a> Register a Kubernetes Cluster

Before creating a plan, you must register the Kubernetes cluster that you want
service instances to use.

To register a cluster with <%= vars.product_short %>:

1. Create a cluster credentials YAML file with the service account token, server, and certificate.
See [Create a Cluster Credentials File](#create-cluster-file).

1. Register the cluster with <%= vars.product_short %> by running:

    ```
    <%= vars.product_cli %> cluster register CLUSTER-NAME PATH-TO-CLUSTER-CREDS.YAML
    ```
    Where:
    + `CLUSTER-NAME` is the name of your cluster.
    <%= vars.product_short %> uses this name to track the cluster.
    Valid characters include lowercase letters, digits, and `-`.
    + `PATH-TO-CLUSTER-CREDS.YAML` is the path to your cluster credentials file
    that you created in [Create a Cluster Credentials File](#create-cluster-file) above.


### <a id='set-default'></a> Set a Default Kubernetes Cluster

If you set a default cluster, you do not need to specify a cluster when you
create plans for a service offering.

To set a default cluster, you must first register the cluster. For more information,
see [Register a Kubernetes Cluster](#registering) above.

To set a default cluster:

1. Set a default cluster by running:

    ```
    <%= vars.product_cli %> cluster set-default CLUSTER-NAME
    ```
    Where `CLUSTER-NAME` is the name of a cluster that is registered with <%= vars.product_short %>.


### <a id='listing'></a> List Registered Kubernetes Clusters

To see a list of registered Kubernetes clusters:

1. List registered clusters by running:

    ```
    <%= vars.product_cli %> cluster list
    ```


### <a id='deregistering'></a> Deregister a Kubernetes Cluster

Before deregistering a cluster, ensure that it is not the default cluster, it does not have any
instances, and the cluster is not associated with any plans in any service offering.

To deregister a cluster:

1. Deregister the cluster by running:

    ```
    <%= vars.product_cli %> cluster deregister CLUSTER-NAME
    ```
    Where `CLUSTER-NAME` is the name of a cluster that is registered with <%= vars.product_short %>.


## <a id='updating'></a> Update Kubernetes Clusters

To update the credentials for an existing cluster that you have already registered with
<%= vars.product_short %>:

1. Create a cluster credentials YAML file with server, token, and caData. See
[Create a Cluster Credentials File](#create-cluster-file) above.

1. Update the Kubernetes cluster credentials by running:

    ```
    <%= vars.product_cli %> cluster register CLUSTER-NAME PATH-TO-CLUSTER-CREDS.YAML --update
    ```
    Where:
    + `CLUSTER-NAME` is the name of a cluster that is registered with <%= vars.product_short %>.
    + `PATH-TO-CLUSTER-CREDS.YAML` is the path to your cluster credentials file
    that you created in the previous step.

<p class="note">
  <strong>Note:</strong> If existing instances are running on the cluster,
  use the <code>--force</code> flag.
</p>