Techcle Wiki

Requirements

7 min read

Requirements Document

Introduction

This specification defines the platform-level AWS integration capabilities for k8s-lab using Crossplane and LocalStack. The system enables application teams to deploy AWS resources (API Gateway, Lambda, DynamoDB, etc.) using GitOps workflows with Crossplane, using LocalStack as a local AWS-compatible environment for development and testing.

Glossary

  • Crossplane: Kubernetes-native infrastructure-as-code tool that manages cloud resources as Custom Resource Definitions (CRDs)
  • LocalStack: Local AWS cloud stack that emulates AWS services for development and testing
  • AWS_Provider: Crossplane provider that enables management of AWS resources
  • ProviderConfig: Crossplane resource that configures authentication and endpoint settings for a provider
  • Platform_Service: A cluster-wide service provided by the platform team for application teams to consume
  • Application_Team: Development teams that consume platform services to deploy their applications
  • GitOps: Declarative infrastructure and application management using Git as the source of truth
  • CRD: Custom Resource Definition - Kubernetes extension mechanism for defining custom resources
  • ArgoCD: GitOps continuous delivery tool for Kubernetes

Requirements

Requirement 1: Crossplane Installation and Configuration

User Story: As a platform engineer, I want Crossplane installed and configured in the cluster, so that I can manage cloud infrastructure as Kubernetes resources.

Acceptance Criteria

  1. WHEN Crossplane is deployed, THE Platform_Service SHALL install all core Crossplane components in a dedicated namespace
  2. WHEN Crossplane is installed, THE Platform_Service SHALL configure appropriate RBAC permissions for managing CRDs
  3. WHEN Crossplane components start, THE Platform_Service SHALL verify all pods are running and healthy
  4. WHEN Crossplane is operational, THE Platform_Service SHALL expose metrics for monitoring
  5. THE Platform_Service SHALL persist Crossplane configuration across cluster restarts

Requirement 2: AWS Provider Installation

User Story: As a platform engineer, I want the AWS provider installed in Crossplane, so that application teams can create and manage AWS resources.

Acceptance Criteria

  1. WHEN the AWS provider is installed, THE Platform_Service SHALL deploy the provider package with a specific version
  2. WHEN the AWS provider initializes, THE Platform_Service SHALL verify the provider is healthy and ready
  3. WHEN the AWS provider is ready, THE Platform_Service SHALL make AWS resource CRDs available cluster-wide
  4. WHEN provider updates are available, THE Platform_Service SHALL support version upgrades without disrupting existing resources

Requirement 3: LocalStack Deployment

User Story: As a platform engineer, I want LocalStack deployed as a platform service, so that application teams can test AWS integrations locally without incurring cloud costs.

Acceptance Criteria

  1. WHEN LocalStack is deployed, THE Platform_Service SHALL run LocalStack with support for API Gateway, Lambda, DynamoDB, S3, and IAM services
  2. WHEN LocalStack starts, THE Platform_Service SHALL initialize with a clean state
  3. WHEN LocalStack is running, THE Platform_Service SHALL expose service endpoints within the cluster
  4. WHEN LocalStack is operational, THE Platform_Service SHALL persist data across pod restarts using persistent volumes
  5. THE Platform_Service SHALL configure LocalStack with appropriate resource limits to prevent cluster resource exhaustion

Requirement 4: LocalStack Ingress Configuration

User Story: As a developer, I want external access to LocalStack, so that I can use AWS CLI tools and test integrations from outside the cluster.

Acceptance Criteria

  1. WHEN LocalStack ingress is configured, THE Platform_Service SHALL expose LocalStack endpoints via ingress controller
  2. WHEN external requests arrive, THE Platform_Service SHALL route traffic to the appropriate LocalStack service port
  3. WHEN ingress is active, THE Platform_Service SHALL provide a documented endpoint URL for external access
  4. THE Platform_Service SHALL configure ingress with appropriate timeout settings for long-running operations
  5. WHERE TLS is required, THE Platform_Service SHALL support HTTPS access to LocalStack endpoints

Requirement 5: ProviderConfig for LocalStack

User Story: As a platform engineer, I want a ProviderConfig that points to LocalStack, so that Crossplane resources are created in the local environment during development.

Acceptance Criteria

  1. WHEN the LocalStack ProviderConfig is created, THE Platform_Service SHALL configure the AWS provider endpoint to point to LocalStack service
  2. WHEN the ProviderConfig is applied, THE Platform_Service SHALL use LocalStack-compatible credentials
  3. WHEN Crossplane resources reference the LocalStack ProviderConfig, THE Platform_Service SHALL create resources in LocalStack instead of real AWS
  4. THE Platform_Service SHALL validate ProviderConfig connectivity to LocalStack before marking it as ready
  5. WHEN LocalStack is unavailable, THE Platform_Service SHALL report ProviderConfig health status as degraded

Requirement 6: AWS Resource CRD Support

User Story: As an application developer, I want to define AWS resources as Kubernetes CRDs, so that I can manage infrastructure using familiar Kubernetes tools and GitOps workflows.

Acceptance Criteria

  1. WHEN AWS CRDs are available, THE Platform_Service SHALL support API Gateway REST APIs, Lambda functions, DynamoDB tables, S3 buckets, and IAM roles
  2. WHEN a CRD is created, THE Platform_Service SHALL validate the resource specification before attempting creation
  3. WHEN a CRD is applied, THE Platform_Service SHALL create the corresponding AWS resource via Crossplane
  4. WHEN a CRD is updated, THE Platform_Service SHALL update the corresponding AWS resource
  5. WHEN a CRD is deleted, THE Platform_Service SHALL delete the corresponding AWS resource
  6. WHEN resource creation fails, THE Platform_Service SHALL report errors in the CRD status field

Requirement 7: ArgoCD Integration

User Story: As a platform engineer, I want ArgoCD to manage Crossplane resources, so that AWS infrastructure follows the same GitOps workflow as application deployments.

Acceptance Criteria

  1. WHEN Crossplane CRDs are in Git, THE Platform_Service SHALL allow ArgoCD to sync and apply them
  2. WHEN ArgoCD syncs Crossplane resources, THE Platform_Service SHALL respect resource dependencies and creation order
  3. WHEN Crossplane resources are out of sync, THE Platform_Service SHALL allow ArgoCD to detect and report drift
  4. WHEN ArgoCD performs a sync, THE Platform_Service SHALL preserve resource status and external resource state
  5. THE Platform_Service SHALL support ArgoCD health checks for Crossplane resources

Requirement 8: Resource Lifecycle Management

User Story: As an application developer, I want predictable resource lifecycle management, so that I can safely create, update, and delete AWS resources through Kubernetes.

Acceptance Criteria

  1. WHEN a resource is created, THE Platform_Service SHALL track the resource state and report it in the CRD status
  2. WHEN a resource creation is in progress, THE Platform_Service SHALL update the CRD status to reflect the current state
  3. WHEN a resource is ready, THE Platform_Service SHALL mark the CRD status as available and populate output fields
  4. WHEN a resource update is requested, THE Platform_Service SHALL apply changes without recreating the resource unless necessary
  5. WHEN a resource deletion is requested, THE Platform_Service SHALL clean up the AWS resource before removing the CRD
  6. IF resource deletion fails, THEN THE Platform_Service SHALL retry deletion and report errors in the CRD status

Requirement 9: Documentation and Examples

User Story: As an application developer, I want clear documentation and examples, so that I can quickly start using the AWS integration platform.

Acceptance Criteria

  1. THE Platform_Service SHALL provide documentation explaining how to create AWS resources using Crossplane CRDs
  2. THE Platform_Service SHALL provide example manifests for common AWS resources (API Gateway, Lambda, DynamoDB)
  3. THE Platform_Service SHALL document how to reference the LocalStack ProviderConfig in resource manifests
  4. THE Platform_Service SHALL provide troubleshooting guidance for common issues
  5. THE Platform_Service SHALL document the supported AWS services and their CRD schemas

Requirement 10: Monitoring and Observability

User Story: As a platform engineer, I want monitoring and observability for the AWS integration platform, so that I can detect and troubleshoot issues quickly.

Acceptance Criteria

  1. WHEN Crossplane is running, THE Platform_Service SHALL expose Prometheus metrics for resource reconciliation
  2. WHEN resources are created or updated, THE Platform_Service SHALL emit events that can be collected and analyzed
  3. WHEN errors occur, THE Platform_Service SHALL log detailed error messages with context
  4. THE Platform_Service SHALL provide health check endpoints for Crossplane and LocalStack
  5. THE Platform_Service SHALL track resource creation time and success/failure rates

Graph View