# ningendo7/cloudctl-operator architecture

> Architecture diagram of the GitHub repository ningendo7/cloudctl-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ningendo7/cloudctl-operator
- Repository: https://github.com/ningendo7/cloudctl-operator

## Overview

cloudctl-operator is a Kubernetes operator that reconciles AppDependencies declarations into AWS resources, access policy, pod connection details, and reported status while correcting drift. Its main workflow begins with a CR change, passes through ordered resource sections, and records managed-resource state; the README documents the supported AWS resource families and sharing behavior. A separate read-only kubectl appdeps CLI reads CRs and presents status, resources, and retained entries. Some section implementations are unsampled, so their links are documented or marked unverified rather than inferred from imports.

Main entry points: [`internal/controller/desiredstate.go`](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/desiredstate.go) (Section orchestration), [`internal/aws/client.go`](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/aws/client.go) (AWS clients), [`internal/cli/cmd/cmd.go`](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/cmd/cmd.go) (CLI commands), [`internal/controller/appdependencies_controller.go`](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/appdependencies_controller.go) (Reconcile loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconcile["Reconciliation"]
  node_app_cr["AppDependencies CR"]
  node_controller["Reconcile loop"]
  node_desired["Section orchestration<br/>[desiredstate.go]"]
  node_predicates["Change predicates<br/>[predicates.go]"]
end

subgraph group_awsresources["AWS Resources"]
  node_aws_clients["AWS clients<br/>[client.go]"]
  node_sqs["Queues<br/>[sqs.go]"]
  node_sns["Topics<br/>[sns.go]"]
  node_s3["Buckets<br/>[s3.go]"]
  node_dynamodb["Tables<br/>[dynamodb.go]"]
  node_rds["Databases<br/>[rds.go]"]
  node_kms["Encryption keys<br/>[kms.go]"]
  node_alarms["CloudWatch alarms<br/>[alarms.go]"]
end

subgraph group_state["Access and State"]
  node_iam["IAM derivation<br/>[derive.go]"]
  node_serviceaccount["IRSA attachment<br/>[serviceaccount.go]"]
  node_configmap["Connection details<br/>[configmap.go]"]
  node_status["Status and ledger<br/>[conditions.go]"]
end

subgraph group_inspection["CLI Inspection"]
  node_cli_entry["appdeps command<br/>[main.go]"]
  node_cli_commands["CLI commands<br/>[cmd.go]"]
  node_kube_reader["Cluster reader<br/>[kube.go]"]
  node_view["Status and ledger views<br/>[view.go]"]
  node_render["Text rendering<br/>[render.go]"]
end

node_kube_user(("Kubernetes user"))
node_aws{{"AWS services"}}
node_workload(("Application pods"))
node_cli_user(("CLI user"))

node_kube_user -->|"declares needs"| node_app_cr
node_app_cr -.->|"triggers reconcile"| node_controller
node_controller -->|"filters changes"| node_predicates
node_controller -.->|"reconciles desired state"| node_desired
node_desired -->|"runs key section first"| node_kms
node_desired -.->|"runs resource section"| node_sqs
node_desired -.->|"runs resource section"| node_sns
node_desired -.->|"runs resource section"| node_s3
node_desired -.->|"runs resource section"| node_dynamodb
node_desired -.->|"runs resource section"| node_rds
node_desired -.->|"runs resource section"| node_alarms
node_desired -->|"runs IAM last"| node_iam
node_sqs -->|"uses AWS clients"| node_aws_clients
node_sns -.->|"uses AWS clients"| node_aws_clients
node_s3 -->|"uses AWS clients"| node_aws_clients
node_dynamodb -->|"uses AWS clients"| node_aws_clients
node_rds -->|"uses AWS clients"| node_aws_clients
node_kms -.->|"uses AWS clients"| node_aws_clients
node_alarms -.->|"uses AWS clients"| node_aws_clients
node_iam -.->|"derives IAM role"| node_aws_clients
node_aws_clients -->|"calls AWS APIs"| node_aws
node_desired -->|"patches ledger"| node_status
node_desired -.->|"writes connections"| node_configmap
node_desired -.->|"attaches role"| node_serviceaccount
node_serviceaccount -->|"enables IRSA"| node_workload
node_configmap -->|"provides connection details"| node_workload
node_cli_user -->|"runs command"| node_cli_entry
node_cli_entry -->|"executes"| node_cli_commands
node_cli_commands -->|"reads cluster CRs"| node_kube_reader
node_cli_commands -->|"builds views"| node_view
node_cli_commands -->|"renders text"| node_render
node_kube_reader -->|"reads status and ledger"| node_app_cr
node_render -->|"renders view"| node_view

click node_app_cr "https://github.com/ningendo7/cloudctl-operator/blob/main/api/v1alpha1/appdependencies_types.go"
click node_controller "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/appdependencies_controller.go"
click node_desired "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/desiredstate.go"
click node_predicates "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/predicates/predicates.go"
click node_aws_clients "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/aws/client.go"
click node_sqs "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/sqs/sqs.go"
click node_sns "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/sns/sns.go"
click node_s3 "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/s3/s3.go"
click node_dynamodb "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/dynamodb/dynamodb.go"
click node_rds "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/rds/rds.go"
click node_kms "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/kms/kms.go"
click node_alarms "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/alarms/alarms.go"
click node_iam "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/iam/derive.go"
click node_serviceaccount "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/serviceaccount/serviceaccount.go"
click node_configmap "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/configmap/configmap.go"
click node_status "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/status/conditions.go"
click node_cli_entry "https://github.com/ningendo7/cloudctl-operator/blob/main/cmd/kubectl-appdeps/main.go"
click node_cli_commands "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/cmd/cmd.go"
click node_kube_reader "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/kube/kube.go"
click node_view "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/view/view.go"
click node_render "https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/render/render.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_cr,node_controller,node_desired,node_predicates,node_kube_user,node_cli_user toneBlue
class node_aws_clients,node_sqs,node_sns,node_s3,node_dynamodb,node_rds,node_kms,node_alarms toneAmber
class node_iam,node_serviceaccount,node_configmap,node_status toneMint
class node_cli_entry,node_cli_commands,node_kube_reader,node_view,node_render toneRose
class node_aws,node_workload toneIndigo
```

## Components

### Reconciliation

- [AppDependencies CR](https://github.com/ningendo7/cloudctl-operator/blob/main/api/v1alpha1/appdependencies_types.go): `api/v1alpha1/appdependencies_types.go`
- [Reconcile loop](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/appdependencies_controller.go): `internal/controller/appdependencies_controller.go`
- [Section orchestration](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/desiredstate.go): `internal/controller/desiredstate.go`
- [Change predicates](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/controller/predicates/predicates.go): `internal/controller/predicates/predicates.go`

### AWS Resources

- [AWS clients](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/aws/client.go): `internal/aws/client.go`
- [Queues](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/sqs/sqs.go): `internal/resources/sqs/sqs.go`
- [Topics](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/sns/sns.go): `internal/resources/sns/sns.go`
- [Buckets](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/s3/s3.go): `internal/resources/s3/s3.go`
- [Tables](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/dynamodb/dynamodb.go): `internal/resources/dynamodb/dynamodb.go`
- [Databases](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/rds/rds.go): `internal/resources/rds/rds.go`
- [Encryption keys](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/kms/kms.go): `internal/resources/kms/kms.go`
- [CloudWatch alarms](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/alarms/alarms.go): `internal/resources/alarms/alarms.go`

### Access and State

- [IAM derivation](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/iam/derive.go): `internal/resources/iam/derive.go`
- [IRSA attachment](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/serviceaccount/serviceaccount.go): `internal/resources/serviceaccount/serviceaccount.go`
- [Connection details](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/resources/configmap/configmap.go): `internal/resources/configmap/configmap.go`
- [Status and ledger](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/status/conditions.go): `internal/status/conditions.go`

### CLI Inspection

- [appdeps command](https://github.com/ningendo7/cloudctl-operator/blob/main/cmd/kubectl-appdeps/main.go): `cmd/kubectl-appdeps/main.go`
- [CLI commands](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/cmd/cmd.go): `internal/cli/cmd/cmd.go`
- [Cluster reader](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/kube/kube.go): `internal/cli/kube/kube.go`
- [Status and ledger views](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/view/view.go): `internal/cli/view/view.go`
- [Text rendering](https://github.com/ningendo7/cloudctl-operator/blob/main/internal/cli/render/render.go): `internal/cli/render/render.go`

### Other components

- **Kubernetes user**
- **AWS services**
- **Application pods**
- **CLI user**

## Connections

- Kubernetes user → AppDependencies CR: declares needs
- AppDependencies CR → Reconcile loop: triggers reconcile
- Reconcile loop → Change predicates: filters changes (evidence: `internal/controller/appdependencies_controller.go`)
- Reconcile loop → Section orchestration: reconciles desired state
- Section orchestration → Encryption keys: runs key section first (evidence: `internal/controller/desiredstate.go`)
- Section orchestration → Queues: runs resource section
- Section orchestration → Topics: runs resource section
- Section orchestration → Buckets: runs resource section
- Section orchestration → Tables: runs resource section
- Section orchestration → Databases: runs resource section
- Section orchestration → CloudWatch alarms: runs resource section
- Section orchestration → IAM derivation: runs IAM last (evidence: `internal/controller/desiredstate.go`)
- Queues → AWS clients: uses AWS clients (evidence: `internal/resources/sqs/sqs.go`)
- Topics → AWS clients: uses AWS clients
- Buckets → AWS clients: uses AWS clients (evidence: `internal/resources/s3/s3.go`)
- Tables → AWS clients: uses AWS clients (evidence: `internal/resources/dynamodb/dynamodb.go`)
- Databases → AWS clients: uses AWS clients (evidence: `internal/resources/rds/rds.go`)
- Encryption keys → AWS clients: uses AWS clients
- CloudWatch alarms → AWS clients: uses AWS clients
- IAM derivation → AWS clients: derives IAM role
- AWS clients → AWS services: calls AWS APIs (evidence: `internal/aws/client.go`)
- Section orchestration → Status and ledger: patches ledger (evidence: `internal/controller/desiredstate.go`)
- Section orchestration → Connection details: writes connections
- Section orchestration → IRSA attachment: attaches role
- IRSA attachment → Application pods: enables IRSA
- Connection details → Application pods: provides connection details
- CLI user → appdeps command: runs command (evidence: `cmd/kubectl-appdeps/main.go`)
- appdeps command → CLI commands: executes (evidence: `cmd/kubectl-appdeps/main.go`)
- CLI commands → Cluster reader: reads cluster CRs (evidence: `internal/cli/cmd/cmd.go`)
- CLI commands → Status and ledger views: builds views (evidence: `internal/cli/cmd/cmd.go`)
- CLI commands → Text rendering: renders text (evidence: `internal/cli/cmd/cmd.go`)
- Cluster reader → AppDependencies CR: reads status and ledger (evidence: `internal/cli/kube/kube.go`)
- Text rendering → Status and ledger views: renders view (evidence: `internal/cli/render/render.go`)
