A [management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/concepts/architecture.md.txt) creates, updates, and
deletes GKE on AWS clusters. This topic explains how to
create a management service inside a dedicated AWS Virtual Private Cloud (VPC).
If you have an existing VPC, see
[Integrating with existing infrastructure](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt)
instead.

## Before you begin


Before you start using GKE on AWS, make sure that
you have performed the following tasks:

- Complete the [prerequisites](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt).
- Authenticate with the Google Cloud CLI.

  ```
  gcloud auth login && \
      gcloud auth application-default login
  ```

### Values you need

To complete this topic, you need the following from the
prerequisites:

- KMS key ARNs or aliases
- Google Cloud service account keys
- Google Cloud project
- The [`aws`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#configuring_aws), [`terraform`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#terraform), and [`anthos-gke`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#anthos_gke_command-line_tool) command-line tools installed and configured.
- The AWS region and availability zones where GKE on AWS creates your management cluster.

## Configure your management service

You configure your GKE on AWS management service with a YAML file.
The file resembles a Kubernetes custom resource configuration, but it is not
a representation of a resource.

1. Open a terminal on the computer where you installed and configured the
   [`aws`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#configuring_aws),
   [`terraform`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#terraform), and
   [`anthos-gke`](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/prerequisites.md.txt#anthos_gke_command-line_tool)
   command-line tools.

2. Create an empty directory for your GKE on AWS configuration and
   change to this directory. GKE on AWS
   documentation uses `anthos-aws` as the example configuration directory.

   > [!NOTE]
   > **Note:** You must use one directory per management service. If you have more than one management service, create another directory.

   ```bash
   mkdir anthos-aws
   cd anthos-aws
   ```
3. 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
      googleCloud:
        projectID: GCP_PROJECT_ID
        serviceAccountKeys:
          managementService: MANAGEMENT_KEY_PATH
          connectAgent: HUB_KEY_PATH
          node: NODE_KEY_PATH
      dedicatedVPC:
        vpcCIDRBlock: VPC_CIDR_BLOCK
        availabilityZones:
        - ZONE_1
        - ZONE_2
        - ZONE_3
        privateSubnetCIDRBlocks:
        - PRIVATE_CIDR_BLOCK_1
        - PRIVATE_CIDR_BLOCK_2
        - PRIVATE_CIDR_BLOCK_3
        publicSubnetCIDRBlocks:
        - PUBLIC_CIDR_BLOCK_1
        - PUBLIC_CIDR_BLOCK_2
        - PUBLIC_CIDR_BLOCK_3
      # Optional
      bastionHost:
        allowedSSHCIDRBlocks:
        - SSH_CIDR_BLOCK
      proxy: PROXY_JSON_FILE # optional
   ```

   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 user
     with [AWS IAM permissions](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/requirements.md.txt) to create a
     management service. To get the ARN of the user authenticated to the
     `aws` tool, run `aws sts get-caller-identity`.

   - <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) or KMS
     key alias that secures your management service's data during creation. For
     example,
     `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`.
     If you do not have the ARN, run `aws kms list-keys` to retrieve a
     list of ARNs.

   - <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) or key
     alias that secures your management service's `etcd` databases---for example,
     `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`.

   - <var translate="no">GCP_PROJECT_ID</var> with the Google Cloud project ID 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.

   - <var translate="no">NODE_KEY_PATH</var> with the location of your GKE on AWS
     node service account key.

   - <var translate="no">VPC_CIDR_BLOCK</var> with the total
     [CIDR](https://wikipedia.org/wiki/Classless_Inter-Domain_Routing)
     range of IP addresses for the AWS VPC that `anthos-gke` creates. For
     example, `10.0.0.0/16`. For more information, see
     [VPC and subnet basics](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#vpc-subnet-basics)
     in the AWS documentation.

   - <var translate="no">ZONE_1</var>, <var translate="no">ZONE_2</var>, and <var translate="no">ZONE_3</var> with the
     AWS EC2
     [availability zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#using-regions-availability-zones-describe)
     where you want to create nodes and control planes. GKE on AWS
     creates subnets in these zones. When you use `anthos-gke` to
     [generate configuration for a user cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/creating-user-cluster.md.txt),
     GKE on AWS creates control planes and node pools in these
     availability zones---for example, `us-east-1a`.  

     If you would like to use `anthos-gke` to create user clusters in only one
     zone, you can remove <var translate="no">ZONE_2</var>, and <var translate="no">ZONE_3</var>.

   - <var translate="no">PRIVATE_CIDR_BLOCK_1</var>, <var translate="no">PRIVATE_CIDR_BLOCK_2</var>, and
     <var translate="no">PRIVATE_CIDR_BLOCK_3</var>, with the CIDR block for your private
     subnet. GKE on AWS components such as the management service run
     in the private subnet. This subnet must be within the VPC's CIDR range
     specified in `vpcCIDRBlock`. You need one subnet for each availability zone---
     for example, `10.0.1.0/24`.

   - <var translate="no">PUBLIC_CIDR_BLOCK_1</var>, <var translate="no">PUBLIC_CIDR_BLOCK_2</var>, and
     <var translate="no">PUBLIC_CIDR_BLOCK_3</var>, with the CIDR blocks for your public subnet.
     You need one subnet for each availability zone. The public subnet exposes
     cluster services such as load balancers to the security groups and address
     ranges specified in AWS
     [network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)
     and
     [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)---
     for example, `10.0.100.0/24`.

   - <var translate="no">SSH_CIDR_BLOCK</var> with the CIDR block that allows inbound SSH to
     your [bastion host](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt#connect)---for example, `203.0.113.0/24`. If you
     want to allow SSH from any IP address, use `0.0.0.0/0`.

   - (optional) <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, delete this line.

4. Run `anthos-gke aws management init` to generate an `anthos-gke.status.yaml`
   file with additional configuration. The `init` command also validates the
   `AWSManagementService` object in your `anthos-gke.yaml` file.

   ```bash
   anthos-gke aws management init
   ```
5. Run `anthos-gke aws management apply` to create the management service on AWS.

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

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

### Optional fields

The `anthos-gke.yaml` file above shows a typical set of fields that most
customers will need. Configuration in `anthos-gke.yaml` also supports
a number of optional fields. These include:

- [spec.bootstrapS3Bucket](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt#specbootstraps3bucket) to specify an AWS S3 bucket for GKE on AWS configuration data
- [spec.tags](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt#spectags) to tag cluster-related AWS resources
- [spec.securityGroupIDs](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt#specsecuritygroupids) to assign additional security group IDs to the management cluster
- [spec.\*Volume](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt#rootvolume) and its sub-fields volumeType, iops, and kmsKeyARN to tune EBS volume parameters
- [spec.terraform.stateGCSBucket](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt#specterraform) to specify a Google Cloud Service bucket for Terraform configuration data

For more information on all fields supported in `anthos-gke.yaml`, see the
[AWS Management Service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/awsmanagementservice.md.txt) reference.

## Connect to the management service

Next, use `anthos-gke` to connect and authenticate to your
GKE on AWS management service.

When you create a management service using the default settings, the
control plane has a private IP address that isn't
accessible from outside the AWS VPC. You can access your management service in
any one of the following three ways:

- through Amazon's [AWS Direct Connect](https://aws.amazon.com/directconnect/) service
- through a [bastion](https://en.wikipedia.org/wiki/Bastion_host) host that proxies connections between the internet and your GKE on AWS subnets
- through a [VPN](https://en.wikipedia.org/wiki/Virtual_private_network)

When you create a management service in a dedicated VPC, GKE on AWS
automatically creates a bastion host in a public subnet. If you're connecting to
your management service through a VPN or AWS Direct Connect, this bastion host
is not needed. Otherwise, to connect to your management service through the
bastion host, perform the following steps:

1. Use the `terraform` tool to generate the script that opens an SSH tunnel to
   the bastion host. Choose your version of Terraform, then run the
   following commands:

   ### Terraform 0.12, 0.13

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

   ### Terraform 0.14.3+

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

   Terraform creates the `bastion-tunnel.sh` script that references the bastion
   host's SSH key at `~/.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 -4
   ```

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

4. 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
   ```
5. Check that you're able to connect to the management service with `kubectl`.

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

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

## 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.