freemo
c65e8a5285
CI / benchmark-publish (pull_request) Has been skipped
CI / build (pull_request) Successful in 16s
CI / lint (pull_request) Successful in 17s
CI / quality (pull_request) Successful in 29s
CI / typecheck (pull_request) Successful in 59s
CI / security (pull_request) Successful in 59s
CI / unit_tests (pull_request) Successful in 3m9s
CI / integration_tests (pull_request) Successful in 3m34s
CI / e2e_tests (pull_request) Successful in 3m54s
CI / docker (pull_request) Successful in 55s
CI / coverage (pull_request) Successful in 6m1s
CI / build (push) Successful in 15s
CI / lint (push) Successful in 16s
CI / quality (push) Successful in 27s
CI / typecheck (push) Successful in 38s
CI / benchmark-regression (push) Has been skipped
CI / security (push) Successful in 48s
CI / unit_tests (push) Successful in 3m14s
CI / integration_tests (push) Successful in 3m30s
CI / docker (push) Successful in 56s
CI / e2e_tests (push) Successful in 4m43s
CI / coverage (push) Successful in 6m1s
CI / benchmark-publish (push) Successful in 19m50s
CI / benchmark-regression (pull_request) Successful in 37m17s
Implement cloud resource types (aws, gcp, azure) with credential fields, region/tenant metadata, and stubbed sandbox strategies. Credential resolution uses environment variables and profile names with no secrets logged. Key changes: - Add CloudResourceHandler with aws/gcp/azure type definitions - Add credential resolution from env vars and profile names - Add stubbed sandbox strategies (validate config, raise NotImplementedError) - Register cloud types in bootstrap_builtin_types - Credential masking via existing redaction patterns - Add Behave BDD tests, Robot integration tests, ASV benchmarks ISSUES CLOSED: #343
167 lines
7.2 KiB
Markdown
167 lines
7.2 KiB
Markdown
# 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
|