In this topic, you configure an existing AWS
[Virtual Private Cloud (VPC)](https://aws.amazon.com/vpc/) with
public and private subnets and run `anthos-gke` to complete the installation
of a management service.

### Before you begin

To complete the following steps, you need the following:

- AWS IAM permissions as described in
  [Requirements](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/requirements.md.txt#bring-your-own_vpc_permissions).

- An existing AWS
  [VPC](https://aws.amazon.com/vpc/) with:

  - At least one public subnet.
  - At least one private subnet.
  - An internet gateway with a route to the public subnet.
  - A NAT gateway with a route to the private subnet.
  - [DNS hostnames](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) enabled.
  - No custom value of `domain-name` in your DHCP options sets. For more information, see [Troubleshooting](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/troubleshooting.md.txt). GKE on AWS does not support values other than the [default EC2 domain names](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-hostnames).

  For more information on configuring your AWS VPC, see
  [VPC with public and private subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html).
- Your existing VPC's public and private subnet IDs. For example,
  `subnet-1234567890abcdefg`.

- For cluster versions 1.20 or lower, an AWS
  [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)
  that allows SSH (port 22) inbound from the security groups or IP ranges
  where you will be managing your GKE on AWS installation.

- For cluster versions 1.21 or higher, an AWS
  [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)
  that allows Konnectivity (port 8132) connections outbound from the VPC IP
  ranges housing your GKE on AWS node pools.

## Creating the workspace

1. Create a file named `anthos-gke.yaml` in a text editor. Paste the following
   contents into the file.

   ```yaml
    apiVersion: multicloud.cluster.gke.io/v1
    kind: AWSManagementService
    metadata:
      name: management
    spec:
      version: aws-1.14.1-gke.0
      region: AWS_REGION
      authentication:
        awsIAM:
          adminIdentityARNs:
          - ADMIN_AWS_IAM_ARN
      kmsKeyARN: KMS_KEY_ARN
      databaseEncryption:
        kmsKeyARN: DATABASE_KMS_KEY_ARN
      securityGroupIDs:
      - SECURITY_GROUP_IDS
      googleCloud:
        projectID: GCP_PROJECT_ID
        serviceAccountKeys:
          managementService: MANAGEMENT_KEY_PATH
          connectAgent: HUB_KEY_PATH
          node: NODE_KEY_PATH
      existingVPC:
        subnetID: VPC_SUBNET_ID
        allowedSSHSecurityGroupIDs:
        - SSH_SECURITY_GROUP
      # Optional fields
      rootVolume:
        sizeGiB: ROOT_VOLUME_SIZE
        volumeType: ROOT_VOLUME_TYPE
        iops: ROOT_VOLUME_IOPS
        kmsKeyARN: ROOT_VOLUME_KEY
      bastionHost:
        subnetID: BASTION_HOST_SUBNET_ID
        allowedSSHCIDRBlocks:
        - SSH_CIDR_BLOCK
        rootVolume: # Optional
          kmsKeyARN: BASTION_VOLUME_KEY
      proxy: PROXY_JSON_FILE
   ```

   Replace the following values:
   - <var translate="no">AWS_REGION</var> with the [AWS region](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) to run your cluster in.
   - <var translate="no">ADMIN_AWS_IAM_ARN</var> with the Amazon Resource Name of the admin [AWS IAM key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt).
   - <var translate="no">KMS_KEY_ARN</var> with the Amazon Resource Name of the [AWS KMS key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#creating_a_kms_key) that secures your management service's data when the management service is created.
   - <var translate="no">DATABASE_KMS_KEY_ARN</var> with the Amazon Resource Name of the [AWS KMS key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#creating_a_kms_key) that secures your `etcd` databases.
   - <var translate="no">SECURITY_GROUP_IDS</var> with additional security group IDs allowed access to your management service VMs.
   - <var translate="no">GCP_PROJECT_ID</var> with the Google Cloud project that hosts your GKE on AWS environment.
   - <var translate="no">MANAGEMENT_KEY_PATH</var> with the location of your Google Cloud management [service account key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#create-service-accounts).
   - <var translate="no">HUB_KEY_PATH</var> with the location of your Google Cloud Connect [service account key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#create-service-accounts).
   - <var translate="no">NODE_KEY_PATH</var> with the location of your GKE on AWS node [service account key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#create-service-accounts).
   - <var translate="no">VPC_SUBNET_ID</var> with the subnet ID where the management service runs.
   - <var translate="no">SSH_SECURITY_GROUP</var> with the list of security group IDs allowed SSH access within the management service instances.

   Optional: If you want to encrypt your management service volumes, replace
   the following values:
   - <var translate="no">ROOT_VOLUME_SIZE</var> with the volume size in gigabytes for the management service. For example, `10`.
   - <var translate="no">ROOT_VOLUME_TYPE</var> with the [EBS volume type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html). For example, `gp3`.
   - <var translate="no">ROOT_VOLUME_IOPS</var> with the mount of provisioned IO operations per second (IOPS) for the volume. Only valid when `volumeType` is `GP3`. For more information, see [General Purpose SSD volumes (gp3)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html#gp3-ebs-volume-type).
   - <var translate="no">ROOT_VOLUME_KEY</var> with the Amazon Resource Name of the AWS KMS key that encrypts your management service instance root volumes. For more information, see [Using a customer managed CMK to encrypt volumes](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/using-cmk.md.txt).

   Optional: If you want to create a [bastion host](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt#connect) to access your
   GKE on AWS environment with an SSH tunnel, replace the
   following values:
   - <var translate="no">BASTION_HOST_SUBNET_ID</var> with the subnet ID where the bastion host runs. Make sure <var translate="no">VPC_SUBNET_ID</var> allows inbound connections from <var translate="no">BASTION_HOST_SUBNET_ID</var>.
   - <var translate="no">SSH_CIDR_BLOCK</var> with the CIDR block that your [bastion host](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt#connect) allows inbound SSH connection from. For example, `203.0.113.0/24`. If you want to allow SSH from any IP address, use `0.0.0.0/0`.
   - <var translate="no">BASTION_VOLUME_KEY</var> with the Amazon Resource Name of the [AWS KMS key](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#creating_a_kms_key) that secures your bastion root volume.

   Optional: If you want direct traffic through an
   [HTTP proxy](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/using-a-proxy.md.txt), replace the following
   value:
   - <var translate="no">PROXY_JSON_FILE</var> with the relative path of the [proxy configuration file](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/using-a-proxy.md.txt). If you are not using a proxy, remove this line.
2. Run `anthos-gke aws management init` to create configuration files:

   ```bash
   anthos-gke aws management init
   ```
3. Run `anthos-gke aws management apply` to create the cluster.

   ```bash
   anthos-gke aws management apply
   ```

   The `anthos-gke aws management apply` command might take up to ten minutes to
   complete. When `anthos-gke` finishes, your management service runs on AWS.

### Tag your subnets with your cluster name

If you are using existing AWS subnets with GKE on AWS and want to
create load balancers, you need to tag your VPC and subnets with your management
service's name. If you created your VPC with `anthos-gke` or have already tagged
your subnets, skip this step.

To tag your subnets, 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. Export your cluster ID as the environment variable `$CLUSTER-ID`. Choose
   your version of Terraform, then run the following commands:

   ### Terraform 0.12, 0.13

   ```bash
   export CLUSTER_ID=$(terraform output cluster_id)
   ```

   ### Terraform 0.14.3+

   ```bash
   export CLUSTER_ID=$(terraform output -raw cluster_id)
   ```
3. Export your AWS VPC ID as the environment variable `$VPC_ID`. Choose
   your version of Terraform, then run the following commands:

   ### Terraform 0.12, 0.13

   ```bash
   export VPC_ID=$(terraform output vpc_id)
   ```

   ### Terraform 0.14.3+

   ```bash
   export VPC_ID=$(terraform output -raw vpc_id)
   ```
4. Get your private subnet IDs with the `aws` CLI tool.

   ```bash
     aws ec2 describe-subnets \
         --filters "Name=vpc-id,Values=$VPC_ID" "Name=tag:Name,Values=*private*" \
         --query "Subnets[*].SubnetId" \
         --output text
   ```

   > [!NOTE]
   > **Note:** This command assumes that your subnets have `private` in their name. If your subnets do not include this text, change the parameters of the `--filters` flag. For more information, see [Using filtering](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Filtering.html).

5. Tag your subnets with your cluster ID. Run the following command for
   each of your subnets.

   ```bash
     aws ec2 create-tags \
         --resources SUBNET_IDS \
         --tags Key=gke:multicloud:cluster-id,Value=$CLUSTER_ID
   ```

   Replace <var translate="no">SUBNET_IDS</var> with the list of subnet IDs, separated by
   spaces. For example,
   `subnet-012345678abcdef subnet-abcdef123456789 subnet-123456789abcdef`.

## Connecting to the management service

In this section, you establish a connection to your management service. You can
tunnel your commands through a
[bastion host](https://wikipedia.org/wiki/Bastion_host). If you
have a direct connection to your AWS VPC, skip to
[Generate credentials and connect](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt#generate-creds).

### Connecting with a bastion host

If you use a bastion host to set up the SSH tunnel, first
[configure the host in your `anthos-gke.yaml`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt#create). Next, create a script
to open the tunnel by performing the following steps:

1. Use `terraform` to generate a script that opens an SSH tunnel to the bastion
   host.

   ```bash
   terraform output bastion_tunnel > bastion-tunnel.sh
   chmod 755 bastion-tunnel.sh
   ```

   Terraform creates the `bastion-tunnel.sh` script that uses the bastion
   host's SSH key (`~/.ssh/anthos-gke`).
2. To open the tunnel, run the `bastion-tunnel.sh` script. The tunnel forwards
   from `localhost:8118` to the bastion host.

   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. Change to the directory with your GKE on AWS configuration.

   ```sh
   cd anthos-aws
   ```

   <br />

### Generate credentials and connect

The documentation for GKE on AWS assumes that you use an SSH tunnel
on `localhost` port 8118 to access your cluster. If you use another type of
connection to your VPC, such as a direct interconnect, VPN, or other method, you
can remove the line `env HTTP_PROXY=http://localhost:8118` from commands.

1. Generate a
   [`kubeconfig`](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl.md.txt#kubeconfig)
   for authentication. Use `anthos-gke` to append credentials to your
   configuration stored in `~/.kube/config`.

   ```bash
   anthos-gke aws management get-credentials
   ```
2. Check that you're able to connect to the management service with `kubectl`.

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

   `kubectl` prints the status of the cluster.

## What's next

- [Create a user cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/creating-user-cluster.md.txt).
- [Use a proxy](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/using-a-proxy.md.txt) with GKE on AWS.
- [Change your `kubectl` configuration](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/using-kubectl.md.txt) to connect to GKE on AWS with fewer command-line options.
- See the minimum required [security groups](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/security-groups.md.txt) for your GKE on AWS management service and user clusters.