> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localops.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon Web Services (AWS)

To connect your **Amazon Web Service (AWS)** cloud account with your LocalOps account you must create a Connection in
LocalOps.

## Connections

A connection represents LocalOps's access to the target cloud account. All operations performed by LocalOps on a target
cloud account, are done through its corresponding connection.

## Pre-requisites

1. AWS account.
2. You'll need to have console access to the target AWS cloud account with Administrator acccess. If you are connecting
   your client/customer's AWS account, the point of contact in your customer's end must have AWS console access with
   Administrator access.

## Create a new connection

### To your cloud account

1. Sign in to LocalOps.
2. Click on **"Connections"** from the navigation pane on the left side.
3. Click on **"Add connection"** button to create a new connection.
4. In the next screen, click on "Connect AWS account" button.
5. You will be taken to AWS > CloudFormation console. In that screen, scroll down to click on "Create stack". **Please
   do not change any value in Create stack screen you see inside AWS. Each of the values represent your account and they
   must not be changed**. Once you see the stack creation complete, come back to LocalOps to see the connection becoming
   Active.

We create a new cloudformation stack to repesent our acesss. The stack will create a new OIDC provider, IAM role and
attach it with relevant permissions for us to access your AWS account. Please read further below to know how this works.

### To your customer cloud account

1. Sign in to LocalOps.
2. Click on **"Connections"** from the navigation pane on the left side.
3. Click on **"Add connection"** button to create a new connection.
4. In the new connection screen, give the connection a name
5. Find the instructions text below th form. Copy and send those instructions to your point of contact at your customer
   end.
6. Your point of contact or anyone in your customer's end can use the connection link to connect their AWS account with
   LocalOps. They must have AWS console access with Administrator permissions to complete this process. They must be
   logged into their AWS account before they can click on the link sent in instructions. In the AWS console, please ask
   them to click on "Create stack" button.

<Note>
  Please ask them not to change any value in "Create stack" screen inside AWS. Each of the values represent your account
  and they must not be changed
</Note>

Once the stack creation is complete, you can come back to LocalOps connections page to see the connection becoming
Active.

We create a cloudformation stack in the target AWS account to create a new OIDC provider, IAM role and attach it with
necessary permissions. Please read further below to know how this works.

<Tip>
  If you are deploying your app(s) on your customer's cloud environment, we recommend asking your customer to
  create a brand new AWS sub-account to connect with LocalOps. This is a best practice to isolate other resources they may
  have in their existing AWS account. You can connect resources/services from any two AWS accounts via VPC peering, later
  when required.

  If you have a pre-existing AWS Organization setup, follow
  [these instructions](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_create.html) to
  create a new AWS sub-account. If not, sign up for a new AWS account here -
  [AWS Signup](https://signin.aws.amazon.com/signup?request_type=register).
</Tip>

## How does this access work?

LocalOps connects to the target AWS account through a *secure key-less role-based method* recommended by AWS. This
method is secure because there are no long-term access keys generated/used during the access. All access is powered by
short term keys generated by AWS and given to LocalOps at the specific time of access, every single time.

For this to work:

1. A new OIDC provider pointing at LocalOps OIDC server, is created in your AWS account establishing a trust between
   LocalOps servers and your AWS account.
2. A new IAM role is also created with specific permissions (see below) to let identities outside your AWS account (in
   this case, LocalOps server) to assume later and get relevant access.
3. Whenever LocalOps wants to connect to your AWS account and perform any operation (say a new deployment), LocalOps
   would assume the above IAM role by using an identity authorised via the OIDC provider and requests short term keys
   from AWS sessions service. Your AWS account would generate short term access keys and hands them off to LocalOps
   servers to use. These access keys are configured to expire in roughly 60-mins or less.
4. Using these keys, LocalOps will access your AWS account to perform any action that you may trigger from LocalOps
   console.

In the steps outlined in "Create a new connection" section, a cloudformation stack is created. This stack does #1 and #2
above to establish a connection with your AWS account.

<Warning>
  After connecting the AWS account, DO NOT:

  Remove/modify the cloudformation stack. It holds the OIDC provider, IAM policy and IAM role to keep the cloud connection
  alive.

  Remove/modify the IAM role or policy. Again, changes here will break the connection LocalOps has with the target aws
  account.
</Warning>

## Permissions required

It is ideal to give LocalOps Administrator access in the AWS account you connect. This is automatically setup when you
follow the 1-click setup process outlined above.

If you require LocalOps to work with lesser permissions, contact us at [support@localops.co](mailto:support@localops.co) to discuss your next steps. You
may have to manually set up LocalOps in your cloud with a specific set of permissions, although we don't see this as
future proof as we would expand our automation capabilities at LocalOps continuously.

### Required

At a minimum, the following permissions are needed in the AWS account to bring up and operate the
[core environment](/environment/inside).

| AWS Service             | Access     | Purpose                                                                                                                                                                           |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **VPC**                 | Read+Write | Network isolation for the environment (VPC, public/private Subnets, Internet Gateway, NAT Gateway, Elastic IPs, Route Tables)                                                     |
| **EC2**                 | Read+Write | Compute and storage backing the Kubernetes nodes (Security Groups, Launch Templates, EBS volumes, Instances via EKS-managed node groups)                                          |
| **EKS**                 | Read+Write | Managed Kubernetes cluster that runs your services (Cluster, Node Groups, Addons — vpc-cni, coredns, kube-proxy, aws-ebs-csi-driver — Access Entries, Access Policy Associations) |
| **IAM**                 | Read+Write | Roles and policies used by the cluster, nodes and workloads (Roles, Policies, RolePolicyAttachments, OpenID Connect Provider, PassRole)                                           |
| **STS**                 | Read       | Issue short-term credentials for LocalOps and IRSA workloads (`AssumeRole`, `AssumeRoleWithWebIdentity`)                                                                          |
| **KMS**                 | Read+Write | Encryption key for EKS secrets at rest (customer-managed key, ENCRYPT\_DECRYPT)                                                                                                   |
| **SSM Parameter Store** | Read+Write | Stores service secrets consumed by your workloads (Parameters)                                                                                                                    |

<Note>
  **You're in full control**

  You are in full control of LocalOps's access to the AWS account. You can disconnect access at any time by deleting
  the CloudFormation stack (see [Deleting connections](#deleting-connections)) and reconnect it only when changes need
  to be made to the environment. While disconnected, your already-deployed workloads continue to run untouched —
  LocalOps simply cannot make any further changes to the AWS account until access is restored.
</Note>

### Optional

These permissions are only required if the corresponding service is declared as a
[cloud dependency in `ops.json`](/environment/services/ops-json#automatic-provisioning-of-cloud-resources).

| AWS Service     | Access     | Purpose                                                                                                                              |
| --------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **S3**          | Read+Write | Object storage for service assets and data (Buckets and objects — Get/Put/Delete/List)                                               |
| **RDS**         | Read+Write | Managed relational databases for services (DB Instances — Postgres/MySQL — Subnet Groups, enhanced-monitoring Role, final snapshots) |
| **ElastiCache** | Read+Write | Managed in-memory cache for services (Redis / Memcache Clusters, Subnet Groups)                                                      |
| **SNS**         | Read+Write | Pub/sub messaging for services (Topics — create, publish, subscribe)                                                                 |
| **SQS**         | Read+Write | Message queues for services (standard + FIFO Queues — Send/Receive/Delete/GetAttr)                                                   |

## Deleting connections

You can sign in to LocalOps and delete a connection any time.

When you delete a connection, we permanently delete all credentials we hold for that specific cloud account. In
addition, you can ensure a full disconnect by deleting the CloudFormation stack we created earlier when setting up the
connection.

To delete CloudFormation stack in the target AWS account:

1. Sign in to AWS console
2. Go to CloudFormation console in us-east-1 region
3. Select the stack with the name with prefix `Ops-..`, This is the stack we created earlier.
4. Delete the stack

This will in turn delete all AWS resources created by the CloudFormation stack. Including IAM role, IAM policy and the
OIDC provider, which we used earlier to get access to your AWS account.