# 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:

```python
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`:

```python
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

```yaml
# 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:

```bash
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](resource_handlers.md) -- Handler architecture
- [Resource Types (Built-in)](resource_types_builtin.md) -- Built-in types
- [Resources](resources.md) -- Resource model