cleveragents-core/docs/reference/cloud_resources.md

Cloud Infrastructure Resources

Cloud infrastructure resource types allow CleverAgents to manage references to cloud provider accounts and their child resources. Types follow a hierarchical model: generic cloud-* base types define provider-agnostic concepts, while provider-specific types (e.g. aws-*) inherit from the base layer.

Note: Cloud resource execution is stubbed. The handler validates configuration and resolves credentials but raises NotImplementedError for actual sandbox provisioning. This is intentional -- cloud SDK integration is planned for a future milestone.

Architecture

cloud-account (abstract base)
├── aws-account (user-addable, carries credentials)
│   └── aws-region
│       ├── aws-vpc → aws-subnet, aws-security-group, ...
│       ├── aws-ec2-instance, aws-s3-bucket, aws-ebs-volume
│       ├── aws-ecs-cluster → aws-ecs-service
│       ├── aws-eks-cluster → aws-eks-nodegroup
│       ├── aws-sqs-queue, aws-sns-topic
│       └── aws-cloudwatch-log-group, aws-cloudwatch-alarm
├── gcp (flat, hierarchy pending)
└── azure (flat, hierarchy pending)

Provider Entry Points

Type	Description	Sandbox Strategy	Inherits
aws-account	Amazon Web Services account	none	cloud-account
gcp	Google Cloud Platform (flat)	none	cloud-account
azure	Microsoft Azure (flat)	none	cloud-account

Generic Cloud Base Types

These abstract types are not user-addable. Provider-specific types inherit from them:

Base Type	AWS Inheritor(s)
cloud-account	aws-account, gcp, azure
cloud-region	aws-region
cloud-network	aws-vpc
cloud-subnet	aws-subnet
cloud-security-group	aws-security-group
cloud-load-balancer	aws-alb, aws-nlb
cloud-compute-instance	aws-ec2-instance
cloud-object-store	aws-s3-bucket
cloud-block-storage	aws-ebs-volume
cloud-identity-principal	aws-iam-user
cloud-role	aws-iam-role
cloud-policy	aws-iam-policy
cloud-log-group	aws-cloudwatch-log-group
cloud-alarm	aws-cloudwatch-alarm
cloud-queue	aws-sqs-queue
cloud-topic	aws-sns-topic
cloud-container-repo	aws-ecr-repo
cloud-container-cluster	aws-ecs-cluster, aws-eks-cluster
cloud-container-service	aws-ecs-service

Configuration

AWS

Field	CLI Arg	Env Var	Required	Sensitive
Access Key ID	--access-key-id	AWS_ACCESS_KEY_ID	Yes*	Yes
Secret Access Key	--secret-access-key	AWS_SECRET_ACCESS_KEY	Yes*	Yes
Session Token	--session-token	AWS_SESSION_TOKEN	No	Yes
Region	--region	AWS_REGION	No	No
Profile	--profile	AWS_PROFILE	No	No

* Required unless a profile name is configured (via --profile or AWS_PROFILE).

GCP

Field	CLI Arg	Env Var	Required	Sensitive
Service Account JSON Path	--service-account-json-path	GOOGLE_APPLICATION_CREDENTIALS	Yes	Yes
Project ID	--project-id	GCLOUD_PROJECT	Yes	No
Region	--region	GCP_REGION	No	No

Azure

Field	CLI Arg	Env Var	Required	Sensitive
Subscription ID	--subscription-id	AZURE_SUBSCRIPTION_ID	Yes	Yes
Tenant ID	--tenant-id	AZURE_TENANT_ID	Yes	Yes
Client ID	--client-id	AZURE_CLIENT_ID	Yes	Yes
Client Secret	--client-secret	AZURE_CLIENT_SECRET	Yes	Yes
Region	--region	AZURE_REGION	No	No

Credential Resolution Order

Credentials are resolved in this priority order:

1. Explicit values -- Passed directly via resource properties
2. Environment variables -- Read from the process environment
3. Profile names (AWS only) -- The AWS_PROFILE environment variable or --profile CLI argument selects a named profile from ~/.aws/credentials

Credential Masking

All credential values are automatically masked in log output and error messages using the existing redaction system (cleveragents.shared.redaction). Sensitive fields are replaced with ***REDACTED***.

Handler

The CloudResourceHandler validates configuration and resolves credentials but does not execute cloud operations:

from cleveragents.resource.handlers.cloud import CloudResourceHandler

handler = CloudResourceHandler()
# handler.resolve(...) raises NotImplementedError after validation

Sandbox Strategy

Cloud resources use sandbox_strategy = "none" because cloud sandbox isolation is not yet implemented. The CloudSandboxStrategy class provides stubbed create, commit, and rollback methods that all raise NotImplementedError:

from cleveragents.resource.handlers.cloud import CloudSandboxStrategy

strategy = CloudSandboxStrategy("aws")
errors = strategy.validate(properties)  # validates config
strategy.create(resource_id, plan_id)   # raises NotImplementedError

Example Usage

# Register an AWS account resource
agents resource add aws-account \
  --access-key-id AKIAIOSFODNN7EXAMPLE \
  --secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  --region us-east-1

Or using environment variables:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=us-east-1

agents resource add aws-account

See Also

• Resource Handlers -- Handler architecture
• Resource Types (Built-in) -- Built-in types
• Resources -- Resource model