Unique AI Documentation

Phase 1: Prerequisites for AWS

15 min read

Introduction

Scope

This guide focuses on both initial setups and subsequent advanced configurations within AWS environments to prepare for the deployment of Unique AI. It covers prerequisites and configurations essential for ensuring infrastructure, security measures, and operational tools are correctly established.

The checklist includes steps for understanding relevant AWS services, setting up identity and access management, configuring network and compute resources, and implementing monitoring and analytics solutions. The goal is to ensure a smooth, secure, and compliant deployment process for the Unique application.

Audience

This guide is intended for IT operators and cloud architects responsible for setting up and securing the AWS environments for deploying Unique AI. It provides a structured framework to follow, ensuring all necessary infrastructure, security measures, and operational tools are correctly established for a smooth and secure implementation.

Purpose

This guide is designed to assist clients in efficiently preparing their AWS environments for the deployment of the Unique application. It serves to ensure that all necessary preconditions and setups are comprehensively addressed to facilitate a smooth and secure implementation process.

General Understanding and Preparation

This section is designed to ensure that all teams involved in the deployment of Unique AI have a foundational understanding of the necessary preparations and are equipped to handle the complexities associated with setting up Unique in an AWS environment. Proper preparation will minimize potential issues and expedite the deployment process.

note

Support Limitations for ClickOps Configurations

Please note that if ClickOps is utilized instead of Infrastructure as Code (IaC) or automation for setting up Unique environments, support from Unique may be limited. Unique's support is tailored for environments managed through codified and automated configurations, ensuring predictable and reproducible setups. Using ClickOps can lead to configurations that deviate from these standards, thereby restricting our ability to provide effective support or troubleshoot issues. Clients using ClickOps should be aware of these limitations and are encouraged to adopt IaC or automated processes to fully leverage Unique's support capabilities.

Below you can see a summary of required knowledge prerequisites:

Diagram: aws-mindmap

  1. Comprehensive Understanding of AWS Resources

    • AWS Identity and Access Management (IAM), Attribute-Based Access Control (ABAC): Ensure that all team members understand the importance of IAM in managing access to AWS resources. Familiarity with AWS's IAM permissions system is crucial for securing the deployment environment.

    • AWS Resource Management: Proficiency in managing AWS resources through automation is critical. Teams should move away from ClickOps to ensure configurations are reproducible and manageable at scale.

  2. Networking Proficiency

    • AWS Networking Components: Teams must have a strong grasp of AWS networking components such as Elastic IPs (EIPs), Application Load Balancers (ALBs), VPCs, Subnets, and Security Groups. Understanding how these components interact along with NACLs, Route Tables, and Internet/NAT Gateways is key to securing and optimizing the environment.

    • Custom Network Configurations: For clients deploying into existing hub-and-spoke topologies using Transit Gateway, PrivateLink, and Direct Connect, it is important to have detailed documentation and a deep understanding of how these custom setups integrate with the standard deployment architecture.

  3. Security and Compliance

    • Data Security: Understand the implications of using custom certificates and how to integrate them within AWS. This includes managing custom Certificate Authorities and ensuring that all security measures align with organizational policies.

    • Compliance Requirements: Be aware of the compliance requirements that affect the deployment, including those related to data handling, privacy, and interactions with external networks.

  4. Kubernetes and Container Management

  5. Pre-Deployment Checks

    • Infrastructure Audit: Conduct a thorough audit of the existing infrastructure to ensure compatibility with the deployment requirements. This includes checking the configurations of EC2 instances, storage, and networking components.

  6. Training and Documentation

Identity and Access Management (IAM)

This section is designed to guide IT operators and cloud architects through the necessary preparations for implementing Identity and Access Management within AWS environments. A sound understanding of these principles will equip all teams involved in deploying applications to effectively manage access controls and security configurations. Proper setup of IAM, including IAM policies, roles, and identity federation, is crucial to minimize potential security issues and streamline the deployment process within the AWS Landing Zone.

Identity and Access Management within AWS environments centers on three core components that control and secure access to AWS resources:

  • IAM Policies and Roles define permissions through policy documents and control which principals (users, roles, services) can access specific AWS resources.

  • Certificates managed via ACM or AWS Private CA secure resources through TLS/SSL encryption for data in transit.

  • Kubernetes workload identity: Two alternative mechanisms grant pods access to AWS resources without static credentials:

    • IRSA (IAM Roles for Service Accounts): The established approach (since 2019). Associates IAM roles with Kubernetes service accounts via OIDC federation. Requires per-cluster OIDC provider setup and trust policy management. Works across EKS, EKS Anywhere, ROSA, and self-managed K8s on EC2.

    • EKS Pod Identity: The simplified alternative since 2023. Associates IAM roles with service accounts via AWS-managed API. Uses a single trust principal (pods.eks.amazonaws.com) and node-local agent. No OIDC provider required. Supports session tags for ABAC. EKS-in-AWS only.

    Both deliver temporary STS credentials, support least-privilege scoping, and log to CloudTrail. Unique is transparent to either approach, the choice between IRSA and Pod Identity remains with the client based on their platform requirements and governance preferences.

These components work together to ensure that all access to AWS resources is authorized, authenticated, and encrypted according to organizational security policies.

  1. IAM and Access Control Adoption:

It is recommended to consistently use IAM policies and RBAC for Amazon EKS, AWS Secrets Manager, AWS KMS, and all other AWS resources to ensure a secure and scalable access control environment. The use of outdated access control methods (e.g., long-lived access keys, inline policies) is discouraged as they may pose security risks and impact functionality.

  1. Certificate Management:

Clients utilizing custom certificates or custom Certificate Authorities (CAs) must have a deep understanding of their configurations.

  1. IRSA (IAM Roles for Service Accounts):

EKS Workload Identities, IRSA or EKS Pod Identity, must be properly configured to allow EKS workloads to access necessary AWS services within the Landing Zone. Specifically, service accounts assigned to backend microservices must have IAM roles with appropriate permissions to access Amazon Bedrock or other LLM endpoints.

  1. API Access Management:

Clients must ensure that IRSA roles are granted appropriate permissions for accessing specific AWS APIs (e.g., Bedrock, S3, Secrets Manager), which can be achieved through provided Terraform configurations or by client-led setups.

  1. AWS Organizations and Account Permissions:

Adequate permissions (AdministratorAccess or equivalent scoped policies) must be assigned on the target AWS account(s), including necessary permissions for any shared services accounts involved (e.g., networking, logging). For multi-account deployments, ensure appropriate cross-account roles and SCPs are configured.

  1. Single Sign-On (SSO) Configuration:

Unique uses Zitadel as its identity platform. Clients configure their external Identity Provider to federate with Unique's Zitadel instance via SAML or OIDC protocols, enabling SSO for application-level authentication. Clients must provide Unique with the necessary SAML/OIDC metadata from their IdP. This is independent of AWS IAM Identity Center and pertains solely to application-level authentication.

Microsoft Entra ID (Common Configuration)

In many cases, clients use Microsoft Entra ID as their external IdP. Required setup includes:

  1. Support and Debugging Limitations:

If Unique lacks access to the client's Identity Provider (IdP) or Entra ID tenant, issue resolution will rely heavily on manual efforts such as screen sharing and log analysis, which are resource-intensive.

🕸 Network

This section covers network configurations required for deploying Unique within AWS:

  • Egress traffic management: NAT Gateways, VPC Endpoints, and Security Group egress rules

  • Network security: Security Groups, Network ACLs, and VPC segmentation

  • Ingress and load balancing: Application Load Balancer (ALB), Network Load Balancer (NLB), and AWS Certificate Manager (ACM) for TLS termination

  • DNS configuration: Route 53 hosted zones and record management

The relationships and flows between the critical network components involved in deploying Unique within an AWS environment:

Diagram: Untitled Diagram-1769172001761

AWS Network Configuration Requirements

  1. Egress Traffic Management (Development Phase)

During the initial or development setup phase, egress traffic should not be restricted, even if it appears unnecessary for Unique's operations. Configure NAT Gateways and Security Group egress rules permissively to ensure flexibility and scalability during early stages of deployment.

  1. Security Group Configuration

Security Groups should initially be configured as defined by Unique's Terraform scripts. Customers can later enhance security configurations to suit specific needs.

  1. Custom Gateway Integration

If the default Unique Application Load Balancer (ALB) does not meet client needs, clients are permitted to prepend an upstream gateway (e.g., API Gateway, Network Load Balancer) or deploy a private ingress. Clients are responsible for managing these network customizations and must ensure that they have the necessary concepts, processes, permissions, and implementations in place.

  1. Certificate Management for Ingress Security

It is crucial that the client's practices for securing ingress traffic with certificates are well-established and ready for deployment. AWS Certificate Manager (ACM) is the recommended approach for managing TLS certificates on ALB. If cert-manager is not usable (due to the requirement for internet-reachable clusters), alternatives must be prepared.

Certificates should be pre-created in ACM or ready to be deployed and associated with ALB listeners. This includes certificates managed by Unique's Helm charts or other public configurations.

  1. Route 53 and Zone Configuration

Clients must ensure that Route 53 hosted zones and record sets are correctly configured as per the Terraform setup to ensure functionality of URLs such as x.client.com and all associated subdomains.

  1. Application Load Balancer URL Setup

Clients should prepare the specific URL where the ALB will be hosted, ensuring it aligns with network and security configurations.

  1. Subdomain Structure Flexibility

Unique utilizes structured subdomains (e.g., id.x.client.com, gateway.x.client.com). In cases where structured subdomains are not feasible, alternative configurations such as x-id.client.com should be correctly bound via Route 53 alias records to the designated ALB endpoints.

  1. Internal Network Accessibility

Configurations involving internal URLs (such as internal ALBs or Route 53 Private Hosted Zones) that make the cluster inaccessible from the internet should be carefully planned to avoid operational issues that may require extensive troubleshooting.

  1. SharePoint Integration with Power Automate

The SharePoint platform is integrated through Power Automate, which is a component of the Microsoft 365 suite. This integration is essential for the operation and functionality of the Unique solution. It should be noted that this setup operates within a "public" or external domain relative to the "internal" environment of the Unique deployment. Thus, it is critical for stakeholders to understand that the data interactions through Power Automate may traverse environments that are external to the secured internal systems.

10. API Gateway Requirements

Calls from Power Automate to the Unique system must be routed through AWS API Gateway or ALB to ensure seamless integration and security.

11. Compatibility with Private EKS Clusters

The Unique mobile app is incompatible with private EKS clusters (private API server endpoint only) when it comes to functionalities involving recording tenants. This limitation must be considered during the network architecture planning phase.

12. Management of Public IP and Egress Restrictions

Clients are responsible for customizing their network setups to manage or restrict the use of public IPs. For guidance on configuring outbound network rules and required configurations, clients should refer to AWS documentation:

13. Image Retrieval for EKS Nodes

EKS nodes must have the ability to pull images from the internet (via NAT Gateway) or alternatively, clients should provision their own Amazon Elastic Container Registry (ECR). Options include:

  • ECR pull-through cache: Caches images from upstream registries (Docker Hub, GitHub Container Registry, Quay, etc.) on first pull, reducing external dependencies and improving pull latency for subsequent requests

  • ECR replication: Synchronization job or CI/CD pipeline to regularly update with the latest Unique images after their release

  • Cross-region/cross-account replication: For multi-region deployments or centralized image management

  • ECR documentation

  • Pull-through cache rules

14. Certificate Management without Cert-Manager

While cert-manager is typically used for automating the management and issuance of certificates within Kubernetes, clients can opt for using ACM-managed certificates on ALB or their own certificates. Using certificates within the cluster (for pod-to-pod TLS) requires additional configuration on the client's side to manually inject certificates and CA details into every deployment, or use ACM Private CA with cert-manager integration.

15. Limitations of Cert-Manager in Isolated Networks

Cert-manager will not function with public ACME providers (e.g., Let's Encrypt) if the EKS cluster is completely isolated from the internet. Alternatives include:

  • DNS-01 challenges via Route 53 (requires Route 53 API access, not inbound internet)

  • ACM for ALB-terminated TLS (no cert-manager required)

  • ACM Private CA for internal certificates

If the cluster cannot be exposed to the internet, further investigation and adaptation of the client's standard ingress configurations may be required.

16. IP Address Allocation in EKS

For EKS environments structured based on Unique's Terraform recommendations, it is critical to ensure that there are enough IP addresses available in the VPC subnet CIDR ranges to accommodate all pods at startup. Consider:

  • VPC CNI plugin IP allocation mode (prefix delegation for higher pod density)

  • Sufficient subnet sizing across Availability Zones

  • Secondary CIDR blocks if primary range is exhausted

  • EKS VPC and subnet requirements

Compute

This section outlines the essential steps for configuring and managing the compute resources necessary for deploying Unique within an AWS environment. It covers the setup of Amazon EC2 instances and EKS managed node groups with appropriate IAM roles and instance profiles, tooling requirements for Kubernetes management, and considerations for handling EBS encryption and multi-tenant clusters. A thorough understanding of these elements will ensure that your deployment is secure, compliant, and optimized for performance and scalability.

note

The Kubernetes cluster must support running operators and Custom Resource Definitions (CRDs). This is essential for deploying components like Kong, which relies on CRDs to function properly. Clients must ensure that their cluster allows CRD installation and management, as this is a fundamental requirement for the Unique deployment.

  1. AWS Bastion EC2 Instance:

  • An Amazon EC2 instance should be established with network access to all Unique-provisioned secrets (AWS Secrets Manager, AWS Systems Manager Parameter Store) and the EKS private API server endpoint. The IAM role attached to this instance (via instance profile) must have appropriate read permissions for Secrets Manager and Parameter Store. This setup might involve direct VPC access or via AWS Systems Manager Session Manager for enhanced security (no inbound SSH required).

  1. VM Tooling Requirements:

The EC2 instance must be equipped with essential tooling for deployment and management of Kubernetes resources. This includes:

  • Helm and Helmfile — Package management and deployment orchestration

  • kubectl — Kubernetes cluster management (configured with EKS cluster context via aws eks update-kubeconfig)

  • AWS CLI — Managing AWS services and EKS authentication

  • eksctl (optional) — Simplified EKS cluster and node group management

  • k9s (optional) — Interactive Kubernetes management experience

  1. Access to Helm Charts

The EC2 instance requires internet access (via NAT Gateway) to download public Helm charts from sources like ArtifactHub. Alternatively:

  1. Customization for Encrypted EBS Volumes

If deployments involve Persistent Volumes (PV) or the EKS cluster utilizes encrypted EBS volumes, the Helm charts must be customized on the client's side to correctly reference the specific AWS KMS key used for encryption. This includes configuring the EBS CSI driver StorageClass with the appropriate kmsKeyId parameter.

  1. Installation in Shared/Multi-tenant Clusters

Unique deployments are known to be complex in shared clusters, particularly because of the need to create Custom Resource Definitions (CRDs) for components like Tyk Gateway Open Source (OSS) or cert-manager. Clients must either:

  • Provide a cluster where these CRDs can be freely installed, or

  • Pre-install the CRDs themselves to facilitate the setup

  • Consider namespace isolation, EKS Pod Security Standards, and RBAC boundaries for multi-tenant deployments.

  1. VPC Subnet Sizing and Scaling Considerations

If the VPC subnet CIDR ranges deviate from what is recommended by Unique's infrastructure setup, it could impact the scaling capabilities of the deployment due to IP address exhaustion (EKS VPC CNI assigns a VPC IP to each pod).

Clients are responsible for resolving such issues, including:

Monitor and Analytics

This section focuses on setting up and optimizing the monitoring and observability frameworks essential for maintaining operational visibility and efficiency within your AWS environment. It includes detailed guidance on configuring Amazon CloudWatch for capturing and analyzing EKS cluster and pod logs, as well as integrating Amazon Managed Grafana for advanced visualization of metrics across your systems. These tools are critical for proactive management and ensuring the high availability and performance of your applications.

The configuration and integration process for monitoring and analytics in an AWS environment:

Diagram: aws-observability

Monitoring and Observability Configuration

  1. CloudWatch Logs and Container Insights Configuration

Amazon CloudWatch must be configured to collect and analyze logs from the EKS cluster. This includes:

  • CloudWatch Container Insights: Provides cluster, node, pod, and container-level metrics and logs

  • Fluent Bit or Fluentd: DaemonSet for forwarding pod logs to CloudWatch Logs

  • CloudWatch Log Groups: Organized log retention for application and system logs

  • It is crucial that the logging infrastructure is set up to allow comprehensive visibility into pod logs, ensuring that operational data is readily available for analysis and troubleshooting.

  • CloudWatch Logs documentation

  1. Amazon Managed Grafana for Monitoring

  • An Amazon Managed Grafana workspace should be set up to monitor and visualize all default metrics derived from the EKS environment and any other integrated systems. Configuration includes:

    • Data sources — CloudWatch, Amazon Managed Prometheus, or self-hosted Prometheus

    • Authentication — AWS IAM Identity Center (SSO) or SAML integration

    • Dashboards — Pre-built Kubernetes dashboards or custom visualizations

  • This Grafana instance needs to be accessible and configured to connect seamlessly with the data sources required to retrieve these metrics.

  • Amazon Managed Prometheus (optional) — Managed Prometheus-compatible monitoring for container metrics at scale

Infrastructure requirements/pre-requisites

Last updated