A GKE on AWS *user cluster* hosts your Kubernetes workloads.
This topic shows you how to create a basic user cluster. If you would like to
further configure a user cluster, see
[Creating a custom user cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/high-availability).

You provision a GKE on AWS user cluster with the
[`AWSCluster`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awscluster.md.txt) and
[`AWSNodePool`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/node-pools)
[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

## Before you begin

To create a user cluster, you first need to install a
[management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt).

To connect to your GKE on AWS resources, perform the following
steps. Select if you have an existing AWS VPC (or direct connection to
your VPC) or created a dedicated VPC when creating your management service.

### Existing VPC

If you have a direct or VPN connection to an existing VPC, omit the line
`env HTTP_PROXY=http://localhost:8118` from commands in this topic.

### Dedicated VPC

When you create a management service in a dedicated VPC,
GKE on AWS includes a
[bastion](https://en.wikipedia.org/wiki/Bastion_host) host in a
public subnet.

> [!IMPORTANT]
> **Important:** If you restart your terminal session or the SSH connection is lost, you need to re-launch the `bastion-tunnel.sh` script.

To connect to your management service, perform the following steps:

1. Change to the directory with your GKE on AWS configuration.
   You created this directory when
   [Installing the management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt).

   ```sh
   cd anthos-aws
   ```

   <br />

2. To open the tunnel, run the `bastion-tunnel.sh` script. The tunnel forwards
   to `localhost:8118`.

   To open a tunnel to the bastion host, run the following command:

   ```bash
   ./bastion-tunnel.sh -N
   ```

   Messages from the SSH tunnel appear in this window. When you are ready to
   close the connection, stop the process by using <kbd>Control+C</kbd> or
   closing the window.
3. Open a new terminal and change into your `anthos-aws` directory.

   ```sh
   cd anthos-aws
   ```
4. Check that you're able to connect to the cluster with `kubectl`.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
   kubectl cluster-info
   ```

   The output includes the URL for the management service API server.

### Selecting a control plane instance size

GKE on AWS doesn't support resizing control plane instances. Before
creating your user cluster, select the instance size of your control
planes. Control plane sizes depend on the number of nodes in your cluster. The
following table contains recommended control plane
[instance sizes](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/instance-types.md.txt) for various cluster
sizes.

| Cluster size (nodes) | Control plane instance type |
|---|---|
| 1 -- 10 | m5.large |
| 11 -- 100 | m5.xlarge |
| 101 -- 200 | m5.2xlarge |

## Creating a user cluster

In this example, you use `terraform` to generate a configuration
to create a basic cluster. Then, you apply the configuration with `kubectl apply`.

1. Open your terminal and, if necessary,
   [connect to your bastion host](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/creating-user-cluster.md.txt#before_you_begin).

2. Change directory to the folder you created when
   [Installing the management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt).

3. Use Terraform to generate a manifest configuring an example cluster and
   save it to a YAML file. Choose your version of Terraform, then run the
   following commands:

   ### Terraform 0.12, 0.13

   ```bash
   terraform output cluster_example > cluster-0.yaml
   ```

   ### Terraform 0.14.3+

   ```bash
   terraform output -raw cluster_example > cluster-0.yaml
   ```

   For more information on the contents of this file, see the
   [`AWSCluster`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awscluster.md.txt) and
   [`AWSNodePool`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/node-pools) documentation.

   > [!NOTE]
   > **Note:** Save your the `cluster-0.yaml` file after you have installed your user cluster. Saving the file simplifies [upgrading a user cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/upgrading-user-cluster).

4. Open the file in a text editor and edit it if necessary. By default,
   GKE on AWS creates node pools in each availability zone
   specified in `anthos-gke.yaml`. You can
   [change the size and number of node pools](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/scaling-user-cluster.md.txt)
   to match your desired cluster. You also can make additional changes to your
   configuration. For example, you might change the
   [instance types](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/instance-types.md.txt) of your
   GKE on AWS nodes; you might also enable
   [logging and monitoring](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/logging-and-monitoring.md.txt) on your
   control plane nodes.

   > [!NOTE]
   > **Note:** You must create your user cluster in the same region as your management service.

5. Apply the file to your management service.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl apply -f cluster-0.yaml
   ```

   > [!NOTE]
   > **Note:** Your cluster takes several minutes to start.

### Create a kubeconfig

While your user cluster starts, you can create a `kubeconfig` context for your
new user cluster. You use the context to authenticate to a user or management
cluster.

1. Use `anthos-gke aws clusters get-credentials` to generate a
   [`kubeconfig`](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl.md.txt#kubeconfig)
   for your user cluster in `~/.kube/config`.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     anthos-gke aws clusters get-credentials CLUSTER_NAME
   ```

   Replace <var translate="no">CLUSTER_NAME</var> with your cluster's name. For example,
   `cluster-0`.
2. Use `kubectl` to authenticate to your new user cluster.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl cluster-info
   ```

   If your cluster is ready, the output includes the URLs for Kubernetes
   components within your cluster.

## Viewing your cluster's status

The management service provisions AWS resources when you apply an
`AWSCluster` or `AWSNodePool`.

1. From your `anthos-aws` directory, use
   `anthos-gke` to switch context to your management service.

   ```sh
   cd anthos-aws
   anthos-gke aws management get-credentials
   ```

   > [!NOTE]
   > **Note:** `anthos-gke` uses the credentials you specified when you ran `aws configure`.

   <br />

2. To list your clusters, use `kubectl get AWSClusters`.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl get AWSClusters
   ```

   The output includes each cluster's name, state, age, version, and endpoint.

   For example, the following output includes only one `AWSCluster` named `cluster-0`:

       NAME        STATE          AGE     VERSION         ENDPOINT
       cluster-0   Provisioning   2m41s   1.25.5-gke.2100   gke-xyz.elb.us-east-1.amazonaws.com

### View your cluster's events

To see recent
[Kubernetes Events](https://www.bluematador.com/blog/kubernetes-events-explained)
from your user cluster, use `kubectl get events`.

1. From your `anthos-aws` directory, use
   `anthos-gke` to switch context to your management service.

   ```sh
   cd anthos-aws
   anthos-gke aws management get-credentials
   ```

   > [!NOTE]
   > **Note:** `anthos-gke` uses the credentials you specified when you ran `aws configure`.

   <br />

2. Run `kubectl get events`.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl get events
   ```

The output includes information, warning, and errors related to from your
management service.

### Deleting a user cluster

To delete a user cluster, perform the following steps:

1. From your `anthos-aws` directory, use
   `anthos-gke` to switch context to your management service.

   ```sh
   cd anthos-aws
   anthos-gke aws management get-credentials
   ```

   > [!NOTE]
   > **Note:** `anthos-gke` uses the credentials you specified when you ran `aws configure`.

   <br />

2. Use `kubectl delete` to delete the manifest containing your user clusters.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl delete -f CLUSTER_FILE
   ```

   Replace <var translate="no">CLUSTER_FILE</var> with the name of the manifest containing
   your AWScluster and AWSNodePool objects. For example, `cluster-0.yaml`.

### Deleting all user clusters

To delete all of your user clusters, perform the following steps:

1. From your `anthos-aws` directory, use
   `anthos-gke` to switch context to your management service.

   ```sh
   cd anthos-aws
   anthos-gke aws management get-credentials
   ```

   > [!NOTE]
   > **Note:** `anthos-gke` uses the credentials you specified when you ran `aws configure`.

   <br />

2. Use `kubectl delete` to delete your AWSNodePools and AWSClusters from your
   management service.

   ```bash
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl delete AWSNodePool --all
   env HTTPS_PROXY=http://localhost:8118 \
     kubectl delete AWSCluster --all
   ```

For more information, see
[Uninstalling GKE on AWS](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/uninstalling.md.txt).

## What's next

- [Launch your first workload](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/quickstart.md.txt) on
  GKE on AWS.

- Configure your identity provider with the
  [GKE Identity Service](https://docs.cloud.google.com/anthos/identity).

- [Connect to your user cluster with Cloud console](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/connecting-to-a-cluster.md.txt).

- [Create a custom user cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/creating-custom-user-cluster.md.txt)
  with different settings.

- [Set up AWS networking](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/aws-networking.md.txt) for load balancing
  your workloads.

- Read the specifications for the
  [AWSCluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awscluster.md.txt) and
  [AWSNodePool](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/node-pools)
  Custom Resource Definitions.