# Understanding the internals of Emp Cloud

Emp Cloud is a platform for building and deploying AI agents and web3 applications.

It is an abstraction layer on top of AWS infrastructure and kubernetes.\
We have developed multiple kubernetes controllers and CRDs to automate and manage the provisioning, lifecycle and perimeter of the infrastructure.

We currently build on the following open source operators:

* [AWS Operator](https://github.com/aws-controllers-k8s/aws-operator)
* [AWS ACK S3](https://github.com/aws-controllers-k8s/s3-controller)
* [AWS ACK Secrets Manager](https://github.com/aws-controllers-k8s/secretsmanager-controller)
* [AWS ACK ECR](https://github.com/aws-controllers-k8s/ecr-controller)
* [AWS ACK IAM](https://github.com/aws-controllers-k8s/iam-controller)
* [AWS ACK DynamoDB](https://github.com/aws-controllers-k8s/dynamodb-controller)
* [AWS ACK SQS](https://github.com/aws-controllers-k8s/sqs-controller)
* [AWS ACK EFS](https://github.com/aws-controllers-k8s/efs-controller)
* [AWS EFS CSI](https://github.com/kubernetes-sigs/aws-efs-csi-driver)
* [Istio Operator](https://github.com/istio/istio-operator)
* [AWS Load Balancer Controller](https://github.com/kubernetes-sigs/aws-load-balancer-controller)
* [External Secrets Operator](https://github.com/external-secrets/kubernetes-external-secrets)

## What happens when you create a new project?

Creating a new project through `empctl` interacts with a series of custom k8s resources that expand into multiple AWS resources on the fly.

The reconciliation logic is implemented as a series of controllers that watch for changes in the custom resources and update the corresponding AWS resources.

The resources are available almost instantly and the will be cleaned up when the project is deleted.

## Understanding the security model

To minimize the attack surface of our infrastructure, users do not have access to the AWS credentials or resources directly.

The provisioning of infrastructure components also creates the necessary IAM roles and policies for them to be accessed only by the project's namespace and the containers that are running on it.

On more complex occasions, like accessing an ECR token to push a docker image or updating secrets we have developed a flow that involves triggering jobs in the namespace to do these operations.

So, for example, for accessing an ECR login token, first `empctl` will create a job in the namespace that will interact with the ECR API and get the login token, then the token will be forwarded to the user's local machine or CI/CD system to be used for pushing the actual image. The process is seamless and doesn't require any additional configuration or elevated permission system.

![ECR Token flow](/files/5DMYd5X0JtgnvDOYm6sd)

On the more complex scenario of updating secrets securely, to avoid exposing credentials or MITM attacks, the flow involves `empctl` uploading the secrets to a presigned URL and then triggering a job in the namespace that accesses the URL and updates the secrets on the AWS Secret Manager secret. Additionally, the actual secrets are being fetched on the cluster securely through the `External Secrets Operator` and stored in a k8s secret that is mounted on the pods running on the namespace.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://empctl.empyrealsdk.com/04-understanding-the-internals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.