AWS remote provisioning

Provisioning process overview

This section summarizes the bootstrap process that lets you use Altinity.Cloud Anywhere to create an EKS environment and deploy ClickHouse clusters to it. You’ll go through these steps:

  1. Get an Altinity.Cloud Anywhere account.
  2. Get an Altinity.Cloud Anywhere environment record.
  3. Get a connection token from the Altinity Cloud Manager.
  4. Provision an AWS EKS cluster using EC2 instance running with a user account.
    The EC2 instance is required in order to deploy altinitycloud-connect, which will establish an outbound connection to Altinity.Cloud and start the EKS provisioning process.
    The EC2 instance can be set up in two ways:
    • Automatically by using the AWS Cloud Formation Template to automate the process.
    • Manually set up by a user following Altinity documentation.
  5. In the Altinity Cloud Manager, complete the configuration of EKS resources.

Automatically provisioning EKS using an EC2 instance created from the AWS Cloud Formation Template

An Amazon AWS EC2 instance is required to deploy altinitycloud-connect, which establishes an outbound connection to Altinity.Cloud Anywhere and starts the EKS provisioning process.

In Altinity.Cloud Anywhere

  1. Get an Altinity.Cloud Anywhere account.
  2. Get an Altinity.Cloud Anywhere environment record.
  3. Get a connection token from the Altinity Cloud Manager. The connection token is everything after token= in the “Connect to Altinity.Cloud” text box. In Figure 1, the token is all of the text in red.
    The Altinity.Cloud Anywhere connection token
    Figure 1 - The Altinity.Cloud Anywhere connection token
  4. Go to the URL for Create stack Cloud Formation Stack as shown in Figure 2: NOTE: The URL will be different for other regions.
    AWS CloudFormation Stack
    Figure 2 - AWS CloudFormation Stack

  1. Login to your AWS account then navigate to:
us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/create
  1. From the altinitycloud-connect releases page, download the Cloud Formation YAML file.
altinitycloud-connect-<release-tag>.aws-cloudformation.yaml
  1. Choose Upload a template file and select the Altinity Cloud Formation Template YAML file as shown in Figure 2.

  2. Fill in any missing fields on the Specify Stack Details page:

    • Set ‘Stack Name’ to: altinitycloud-connect-$USER-$ENV_NAME (replace $USER and $ENV_NAME with the correct values)

    • Set ‘Subnets’ where altinitycloud-connect EC2 instance(s) should be launched (Example: subnet-17c1674a, subnet-2d5c8855, subnet-e0d425aa)

    • Set the ‘Token presented by https://acm.altinity.cloud’ with the token value from Step 3.

  3. Important: At the last step of the wizard, checkmark the notice: “I acknowledge that AWS CloudFormation might create IAM resources with custom names

  4. Complete the wizard and submit the form.


EC2 background processing explained

The EC2 instance is processed in the background as follows:

  • EC2 instance gets started from the cloud formation template
  • EC2 gets connected to Altinity.Cloud using altinitycloud-connect
  • EKS cluster gets provisioned
  • EKS cluster gets connected to Altinity.Cloud using altinitycloud-connect

In Altinity.Cloud

  1. Select the ‘Proceed’ button in the connection wizard. NOTE: It is ok to select Proceed more than once, since provisioning takes some time. Once the EKS cluster is provisioned, the wizard switches to the ‘Resources Configuration’ page.

  2. Finish configuration of node pools as described in the Configuring resources section.



Manual provisioning of the EC2 instance

The AWS EC2 instance should meet the following requirements:

EC2 Instance Requirements

  • CPU: t2.micro minimum
  • OS: Ubuntu Server v20.04

Creating a Role with AIM policies

Set up a role with IAM policies to access IAM, EC2, VPC, EKS, S3 & Lambda as follows:

  arn:aws:iam::aws:policy/IAMFullAccess
  arn:aws:iam::aws:policy/AmazonEC2FullAccess
  arn:aws:iam::aws:policy/AmazonVPCFullAccess
  arn:aws:iam::aws:policy/AmazonS3FullAccess
  arn:aws:iam::aws:policy/AWSLambda_FullAccess
  arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

NOTE:


Creating a policy for EKS full access

  1. Create a standard policy for EKS full access as follows:
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "eks  ":"*"
         ],
         "Resource":"*"
      },
      {
         "Effect":"Allow",
         "Action":"iam:PassRole",
         "Resource":"*",
         "Condition":{
            "StringEquals":{
               "iam:PassedToService":"eks.amazonaws.com"
            }
         }
      }
   ]
}
  1. To set this instance to have access to the EC2 metadata and Internet, set the Security group to:

    • deny all inbound traffic
    • allow all outbound traffic

Installing Altinity.Cloud Connect

  1. Download altinitycloud-connect. NOTE: The following example is for an Intel Linux installation. Change the filename to match your machine’s architecture.

    curl -sSL https://github.com/altinity/altinitycloud-connect/releases/download/v0.20.0/altinitycloud-connect-0.20.0-linux-amd64 -o altinitycloud-connect \
    
  2. With the file downloaded, run these commands to make the file executable and put it in your path.

    chmod a+x altinitycloud-connect \
    && sudo mv altinitycloud-connect /usr/local/bin/
    
  3. Login to Altinity.Cloud using a connection token.

    altinitycloud-connect login --token=<registration token>
    

NOTE: altinitycloud-connect creates a cloud-connect.pem file in the current working directory.

  1. Connect to Altinity.Cloud:

    altinitycloud-connect --capability aws
    

Start EKS provisioning

Provide additional configuration data to Altinity Support

  1. The following data is required in order to create the VPC and EKS cluster properly:
  • The CIDR for the Kubernetes VPC (at least /21 recommended, e.g. 10.1.0.0/21) that does not overlap with existing VPCs
  • The Number of Availability Zones (3 are recommended)

Please send this information to your Altinity support representative to start the EKS provisioning process. When completed, the Altinity Cloud Manager (ACM) will be updated then you can create your ClickHouse clusters.

The remainder of the provisioning process is handled by Altinity.Cloud. Users may switch back to ACM and wait for connection to be established in order to finish configuration.


In Altinity.Cloud

  1. Select the Proceed button in the connection wizard. You may repeat this step more than once to see if the connection has completed, since provisioning takes some time. Once the EKS cluster is provisioned, the connection wizard will switch to the Resources Configuration page.

  2. Finish configuration of node pools as described in the Configuring resources section.


Break Glass procedure

The “Break Glass” procedure allows Altinity access to EC2 instance with SSH, using AWS SSM in order to troubleshoot altinitycloud-connect that is running on this instance.

  1. Create an AnywhereAdmin IAM role with trust policy set:

    {
       "Version":"2012-10-17",
       "Statement":[
          {
             "Effect":"Allow",
             "Principal":{
                "AWS":"arn:aws:iam::313342380333:role/AnywhereAdmin"
             },
             "Action":"sts:AssumeRole"
          }
       ]
    }
    
  2. Add a permission policy set:

    {
       "Version":"2012-10-17",
       "Statement":[
          {
             "Effect":"Allow",
             "Action":"ssm:StartSession",
             "Resource":[
                "arn:aws:ec2:$REGION:$ACCOUNT_ID:instance/$INSTANCE_ID",
                "arn:aws:ssm:*:*:document/AWS-StartSSHSession"
             ]
          }
       ]
    }
    
  3. Send the following ARN string to Altinity: NOTE: This is used to revoke the Break Glass Procedure access change, or remove the permission policy.

    arn:aws:ec2:$REGION:$ACCOUNT_ID:instance/$INSTANCE_ID
    
Last modified 2023.09.18: Update aws-remote-provisioning.md