AWS remote provisioning

Configuring your AWS account

Altinity.Cloud Anywhere operates inside a user’s cloud account.

Altinity technical support can remotely provision AWS SKS clusters with an Altinity.Cloud Anywhere environment in your AWS account. Instructions on this page describe how to configure your AWS account to give Altinity permission to provision ClickHouse clusters to your AWS Kubernetes environment.

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:

Get an Altinity.Cloud Anywhere account.
Get an Altinity.Cloud Anywhere environment record.
Get a connection token from the Altinity Cloud Manager.
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.
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

Get an Altinity.Cloud Anywhere account.
Get an Altinity.Cloud Anywhere environment record.
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.

Figure 1 - The Altinity.Cloud Anywhere connection token
Login to your AWS account and navigate to Cloud Formation and click the Create Stack button.
Go to the altinitycloud-connect releases page and download the latest Cloud Formation YAML file, altinitycloud-connect-x.xx.x.aws-cloudformation.yaml. (That’s currently version 0.61.0.) The link to the YAML file is at the bottom of the page.
In the Create Stack panel, choose Upload a template file and select the Altinity Cloud Formation Template YAML file as shown in Figure 2. Click Next to continue:

Figure 2 - Selecting a template file
Fill in any missing fields on the Specify Stack Details page (Figure 3):
- Set Stack Name to altinitycloud-connect-$ENV_NAME (if your environment name is maddie-byok, the stack name should be altinity-connect-maddie-byok.)
- Select the Subnets where the altinitycloud-connect EC2 instance(s) should be launched. At least one subnet is required.
  NOTE: The subnet(s) must have the “Auto-assign public IPv4 address” property set to yes.
- Set the Token presented by https://acm.altinity.cloud/ to the token value from Step 3.
- Click Next to continue.
Figure 3 - AWS CloudFormation Stack details panel
Take the defaults on the Configure stack options panel (Figure 4). Click Next to continue.

Figure 4 - AWS CloudFormation Configure stock options panel
On the Review panel, check the box to allow CloudFormation to create resources as shown in Figure 5. The process will not work unless you click this button. Click Submit to start provisioning the new stack.

Figure 5 - Granting permissions on the AWS CloudFormation Review panel
You’ll see the main CloudFormation panel (Figure 6), which will include your new stack. You can follow its progress in the Events list.

Figure 6 - AWS CloudFormation stack list

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 Manager

Once your new stack is created, click the ‘Proceed’ button in the connection wizard. Altinity Cloud Manager will connect to the stack named altinitycloud-connect-$ENV_NAME where $ENV_NAME is the name of your environment. 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.
Finish configuring your cluster 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:

AmazonSSMManagedInstanceCore is used for the Break Glass Procedure over AWS SSM.

Creating a policy for EKS full access

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"
            }
         }
      }
   ]
}

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

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 \

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/
```
Login to Altinity.Cloud using a connection token as shown in Figure 1 above.
```
altinitycloud-connect login --token=<registration token>
```

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

Connect to Altinity.Cloud:
```
altinitycloud-connect --capability aws
```

Start EKS provisioning

Provide additional configuration data to Altinity Support

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, such as 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. At that point, 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

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

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"
          }
       ]
    }

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"
             ]
          }
       ]
    }

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