74 lines
8.5 KiB
Markdown
74 lines
8.5 KiB
Markdown
# Cloud export fixtures (B15, 2026-10-18)
|
|
|
|
The per-cloud adapters of `sidecar scan` are measured on these files, **not on a live account**: Aere Network holds no AWS, Azure or
|
|
GCP account (a decision of the founder, about money), so what an adapter reads is the output of each CLI **as its vendor documents
|
|
it**. Every file under `surse/` is an exact copy of an example published in that documentation, or, where the documentation
|
|
publishes no example output, a form built from the documented schema and named `din-schema` (from the schema). Everything else in
|
|
this directory is **derived** from those sources by `deriva.mjs`, deterministically; `node deriva.mjs --verifica` compares the files on
|
|
disk with what the code derives now, and `proba-adaptoare-cloud.mjs` does the same at every run.
|
|
|
|
**NOT MEASURED: the output of a real account.** A field a CLI emits only on a live resource and not in its documented example (for
|
|
example the `imageDigest` of an ECS container, the `instanceView` that `az container show` carries and `az container list` may not,
|
|
the `State` that `aws lambda list-functions` does not return) is handled as the documentation describes it, and that handling has not
|
|
been run against a live export. To measure it, a test account at each vendor is needed (a decision of the founder); until then every
|
|
statement about these adapters is a statement about the documented shapes.
|
|
|
|
## Sources (`surse/`), read on 2026-10-18
|
|
|
|
| file | what it is | where it was read |
|
|
| --- | --- | --- |
|
|
| `aws-ecs-describe-tasks.json` | Example 1 of `aws ecs describe-tasks` ("To describe a single task"), copied exactly | docs.aws.amazon.com/cli/latest/reference/ecs/describe-tasks.html, page titled "AWS CLI 2.38.1 Command Reference" |
|
|
| `aws-ecs-describe-task-definition.json` | the example output of `aws ecs describe-task-definition`, copied exactly (it carries a plaintext `MYSQL_ROOT_PASSWORD` value, the vendor's own example; the adapter drops it) | docs.aws.amazon.com/cli/latest/reference/ecs/describe-task-definition.html |
|
|
| `aws-ec2-describe-instances.json` | Example 1 of `aws ec2 describe-instances`, copied exactly (including the vendor's `"PrivateIpAddress": "10-0-0-157"`) | docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html |
|
|
| `aws-lambda-list-functions.json` | the example output of `aws lambda list-functions`, copied exactly; the page's note says `State` and `LastUpdateStatus` are not returned by this call | docs.aws.amazon.com/cli/latest/reference/lambda/list-functions.html |
|
|
| `azure-vm-list-rest-2026-04-01.json` | `VirtualMachine_List_MaximumSet_Gen.json`, the example the REST reference "Virtual Machines - List" is generated from (api-version 2026-04-01), as published in Azure/azure-rest-api-specs | github.com/Azure/azure-rest-api-specs, `specification/compute/resource-manager/Microsoft.Compute/Compute/stable/2026-04-01/examples/virtualMachineExamples/` |
|
|
| `azure-container-groups-list-rest-2026-07-01.json` | the sample response of "Container Groups - List" (api-version 2026-07-01), copied exactly | learn.microsoft.com/en-us/rest/api/container-instances/container-groups/list |
|
|
| `azure-containerapps-list-rest-2026-07-01.json` | `ContainerApps_ListBySubscription.json` (api-version 2026-07-01), as published in Azure/azure-rest-api-specs | github.com/Azure/azure-rest-api-specs, `specification/app/resource-manager/Microsoft.App/ContainerApps/stable/2026-07-01/examples/` |
|
|
| `azure-webapps-list-rest-2024-11-01.json` | the sample response of "Web Apps - List" (api-version 2024-11-01), copied exactly | learn.microsoft.com/en-us/rest/api/appservice/web-apps/list |
|
|
| `gcp-compute-instances-din-schema.json` | **built from the schema**, not a published sample: the Compute Engine API has no example output for `gcloud compute instances list --format=json`; fields and the `status` values are those of the `Instance` resource (compute v1) | docs.cloud.google.com/compute/docs/reference/rest/v1/instances (schema as rendered in the generated client reference), docs.cloud.google.com/compute/docs/instances/instance-lifecycle (states), docs.cloud.google.com/compute/docs/metadata/predefined-metadata-keys |
|
|
| `gcp-run-services-din-schema.json` | **built from the schema**, not a published sample: a `serving.knative.dev/v1` Service as the Cloud Run YAML reference and the Admin API v1 describe it (`cloud.googleapis.com/location` label, `status.conditions[].type == "Ready"`) | docs.cloud.google.com/run/docs/reference/yaml/v1 (last updated 2026-10-13), docs.cloud.google.com/run/docs/reference/rest/v1/namespaces.services, docs.cloud.google.com/run/docs/reference/rest/v1/Container |
|
|
|
|
How the CLI shapes relate to the REST samples (the derivation applies exactly this):
|
|
|
|
- `az vm list -d`: the Azure CLI returns the ARM resource with `properties` flattened into the object; `--show-details` adds
|
|
`powerState` (the `displayStatus` of the `PowerState/*` entry of `instanceView.statuses`, so `"VM running"`), `publicIps`, `fqdns`,
|
|
`privateIps`, `macAddresses`, and removes `instanceView` (read in `src/azure-cli/azure/cli/command_modules/vm/custom.py`,
|
|
`get_vm_details`, github.com/Azure/azure-cli, branch dev, 2026-10-18). The REST sample has no power state, so the derived CLI
|
|
form sets `powerState` itself.
|
|
- `az container list` / `az container show`: `properties` flattened at the group and at each container; the state of a container is
|
|
`containers[].instanceView.currentState.state` (the restart-policy guide reads it exactly so, page dated 2026-07-25). The REST
|
|
list sample has no `instanceView`; the derived CLI form adds it in the shape `ContainerPropertiesInstanceView` documents.
|
|
- `az containerapp list`: the containerapp extension returns the ARM resource with `properties` nested; `runningStatus` is read-only
|
|
with values `Progressing`, `Running`, `Stopped`, `Suspended`, `Ready` (openapi.json 2026-07-01). The adapter counts only `Running`.
|
|
- `az webapp list --show-details`: `properties` flattened; `state` is `Running` or `Stopped` (the command reference's own example is
|
|
`az webapp list --query "[?state=='Running']"`, page dated 2026-09-01). The derived CLI form gives the first site a
|
|
`linuxFxVersion` of the `DOCKER|image` form, which the REST sample leaves empty.
|
|
- `gcloud ... --format=json` "lists the resource in json format" (gcloud topic formats, last updated 2026-10-06): the files are arrays
|
|
of the resource.
|
|
|
|
## Derived files
|
|
|
|
For every source `<src>`: `<src>.json` (the CLI form), `<src>.oprita.json` (the same plus one workload that is **not running**: a
|
|
STOPPED task, a stopped instance, an `Inactive` function, a deallocated VM, a `Terminated` container, a `Stopped` container app, a
|
|
`Stopped` site, a `TERMINATED` instance, a service whose `Ready` condition is `False`), `<src>.secrete.json` (the same with
|
|
environment variables **with values** planted, `AERE-SINTETIC-...`, synthetic by construction: in task definitions and overrides,
|
|
`Environment.Variables`, VM `customData`/`userData`/tags, ACI `environmentVariables` (`value` and `secureValue`), container app `env`
|
|
and `configuration.secrets`, site `appSettings`/`connectionStrings`, instance `metadata` (`user-data`, `startup-script`), Cloud Run `env`).
|
|
`aws-ecs.definitii.json` is the task definition aligned to the task of the ECS example (the vendor's two examples do not share a task
|
|
definition ARN); `azure-vm.fara-d.json` and `azure-container.fara-stare.json` are the exports **without** the field that says whether
|
|
the workload runs, which the adapters refuse by name.
|
|
|
|
The test requires, for each adapter: the running workloads only (the planted stopped one never enters the log), the identities
|
|
exactly, no planted value anywhere in the log or in the descriptors (and the variable **names** present, as the positive control),
|
|
another CLI's export refused by name, every descriptor re-hashing to the digest in its envelope, and every envelope `VALID` for the
|
|
AIP-23 reference verifier.
|
|
|
|
## Declared change to the Microsoft example (2026-10-18)
|
|
|
|
`surse/azure-webapps-list-rest-2024-11-01.json` is the published "Web Apps - List" example with ONE declared change: its four public IP
|
|
addresses in `outboundIpAddresses` / `possibleOutboundIpAddresses` (Microsoft's, not ours, and not read by the adapter) are replaced with
|
|
RFC 5737 documentation addresses (203.0.113.x, 198.51.100.x). Reason: this repository's publication gate refuses any file that lists three
|
|
or more public IP addresses together (it cannot tell a vendor's example from an infrastructure map), and we keep that gate strict rather
|
|
than give a folder an exception. Everything else in the source is byte for byte the published example; the derived fixtures carry the same
|
|
replacement through `deriva.mjs`.
|