# AwsConnection

How Vulnesis reaches the tenant's AWS estate. Fields, YAML, HCL and CLI samples, and how apply treats it.

How Vulnesis reaches the tenant's AWS estate. One per tenant. sso: IAM Identity Center, which can reach every account the operator's session can; the accounts are AwsAccount documents. iamUser: a long-lived access key, for an estate without Identity Center; the key's own account (from sts:GetCallerIdentity, never from the document) is the connected account. An sso connection starts a device authorization that a person approves in the AWS access portal, so its first apply, and any apply after the session expires, cannot finish unattended. Deleting it disconnects AWS; the stacks deployed in each account stay until removed there.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `AwsConnection` |
| Group | [Cloud](/platform-iac/kinds/catalogue.md#cloud) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | one (`metadata.name: default`) |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Secret fields | `spec.iamUser.secretAccessKey`: read on the client from `valueFrom`, sent once, never exported or shown in a plan |
| Terraform resource | [`vulnetix_aws_connection`](/platform-iac/terraform/resources.md#vulnetix_aws_connection), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.165.1 and later. |
| Pinned schema | [`v1.19.1/AwsConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/AwsConnection.schema.json) |
| Newest schema | [`latest/AwsConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json) |
| First released in | [`v1.3.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.3.0) |
| Print the built-in copy | `vulnetix config schema AwsConnection` |

## Minimal

Only the fields the kind requires. From `examples/AwsConnection/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: ap-southeast-2
  sso:
    startUrl: https://acme.awsapps.com/start
```

**HCL** (resource `vulnetix_aws_connection`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/AwsConnection/minimal.yaml.

resource "vulnetix_aws_connection" "default" {
  region = "ap-southeast-2"
  sso = {
    start_url = "https://acme.awsapps.com/start"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/aws_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/aws_connection.tf) and [`yaml/AwsConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/AwsConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: ap-southeast-2
  sso:
    startUrl: https://acme.awsapps.com/start
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/AwsConnection/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json
# A tenant has one AwsConnection. These are the two forms it can take:
# IAM Identity Center (sso) or a long-lived IAM user key (iamUser).
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
  labels:
    owner: platform
  annotations:
    note: Approve the device authorization in the AWS access portal on first apply.
spec:
  region: ap-southeast-2
  sso:
    startUrl: https://acme.awsapps.com/start
  advancedNetworking: true
---
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: us-east-1
  iamUser:
    accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: { env: VULNESIS_AWS_SECRET_ACCESS_KEY }
  advancedNetworking: false
```

**HCL** (resource `vulnetix_aws_connection`)

```hcl
# Every argument the kind supports. From config-schemas examples/AwsConnection/advanced.yaml.

resource "vulnetix_aws_connection" "default" {
  advanced_networking = true
  region              = "ap-southeast-2"
  sso = {
    start_url = "https://acme.awsapps.com/start"
  }
  labels = {
    owner = "platform"
  }
  annotations = {
    note = "Approve the device authorization in the AWS access portal on first apply."
  }
}

# Or, instead (one per tenant, so declare only one):
#
# variable "default_2_iam_user_secret_access_key" {
#   type      = string
#   sensitive = true
#   ephemeral = true
# }
# resource "vulnetix_aws_connection" "default_2" {
#   advanced_networking = false
#   iam_user = {
#     access_key_id                = "AKIAIOSFODNN7EXAMPLE"
#     secret_access_key_wo         = var.default_2_iam_user_secret_access_key
#     secret_access_key_wo_version = 1
#   }
#   region = "us-east-1"
# }
```

Every field that has a schema default, set to that default: [`terraform/aws_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/aws_connection.tf) and [`yaml/AwsConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/AwsConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
export VULNESIS_AWS_SECRET_ACCESS_KEY=...   # read on this machine by valueFrom, never written to the document
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json
# A tenant has one AwsConnection. These are the two forms it can take:
# IAM Identity Center (sso) or a long-lived IAM user key (iamUser).
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
  labels:
    owner: platform
  annotations:
    note: Approve the device authorization in the AWS access portal on first apply.
spec:
  region: ap-southeast-2
  sso:
    startUrl: https://acme.awsapps.com/start
  advancedNetworking: true
---
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: us-east-1
  iamUser:
    accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: { env: VULNESIS_AWS_SECRET_ACCESS_KEY }
  advancedNetworking: false
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Secret | Description |
|---|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` |  | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `AwsConnection` |  | Always AwsConnection. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  | Metadata for a kind the tenant has exactly one of. The name is fixed to default. |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | exactly `default`; pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` |  | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` |  | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` |  | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) |  | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |  |
| <span id="spec-region"></span>`spec.region` | string | yes |  | `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `eu-west-1`, `eu-west-2`, `eu-west-3`, `eu-central-1`, `eu-central-2`, `eu-north-1`, `eu-south-1`, `eu-south-2`, `ap-southeast-1`, `ap-southeast-2`, `ap-southeast-3`, `ap-southeast-4`, `ap-northeast-1`, `ap-northeast-2`, `ap-northeast-3`, `ap-south-1`, `ap-south-2`, `ap-east-1`, `ca-central-1`, `ca-west-1`, `sa-east-1`, `me-south-1`, `me-central-1`, `af-south-1`, `il-central-1` |  | The Identity Center region for sso; the region calls are made in for iamUser. An allowlist, because the region becomes part of an endpoint host name. |
| <span id="spec-sso"></span>`spec.sso` | object | no |  | no other keys |  |  |
| <span id="spec-sso-startUrl"></span>`spec.sso.startUrl` | string | yes |  | pattern `^https://[a-z0-9-]+\.awsapps\.com(/start)?/?$` |  | The AWS access portal URL. Stored as https://<name>.awsapps.com/start. |
| <span id="spec-iamUser"></span>`spec.iamUser` | object | no |  | no other keys |  |  |
| <span id="spec-iamUser-accessKeyId"></span>`spec.iamUser.accessKeyId` | string | yes |  | pattern `^[A-Z0-9]{16,128}$` |  | An identifier, not a secret: it is in CloudTrail on every call it makes. |
| <span id="spec-iamUser-secretAccessKey"></span>`spec.iamUser.secretAccessKey` | object | yes |  | 1 to 1 keys; no other keys | yes | Where the client reads the secret access key. It is proved with sts:GetCallerIdentity, kept in the tenant's vault, and never exported or shown in a plan. |
| <span id="spec-iamUser-secretAccessKey-env"></span>`spec.iamUser.secretAccessKey.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-iamUser-secretAccessKey-file"></span>`spec.iamUser.secretAccessKey.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |
| <span id="spec-advancedNetworking"></span>`spec.advancedNetworking` | boolean | no | `false` |  |  | Report over the private path from the customer's accounts to Vulnesis instead of the internet. Applies to every account; the next stack deploy fills the parameters. |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `spec` | Exactly one of `sso` or `iamUser` is set. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** With `sso`: phase `AwaitingAuthorization` with `authorizationUrl` and `userCode` while the IAM Identity Center sign-in waits, then `Authorized`, or `AuthorizationRequired` when the code expired. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).
- **Singleton.** There is one per tenant, and its name is always `default`.

## How apply treats it

Every write goes through the AWS drawer's own steps inside the apply transaction. Calls to AWS, KMS and the secrets vault are not transactional: a rolled-back apply can leave an unused OIDC client or a vault version nothing references.

- **`sso`.** Apply starts an IAM Identity Center device authorization when the connection is new or its `startUrl`, `region` or connector changed, and not otherwise. The object's status carries `phase: AwaitingAuthorization`, `authorizationUrl` and `userCode`. The instance that started it polls the device code until the operator approves (`Authorized`) or the code expires (`AuthorizationRequired`, after which the drawer or a new apply starts again). The pending sign-in is held in memory, so another instance reports `AuthorizationRequired` until the token lands.
- **`iamUser`.** Apply proves the key with `sts:GetCallerIdentity` and stores it when the key id is new or a different secret arrives. A new key id without its resolved secret is refused. `secretAccessKey` is write-only, compared by decrypting the stored key, and exported as `{env: ...}`.
- `advancedNetworking` is set on the connection and on every account, as the drawer does.
- Delete removes the row like the drawer's forced disconnect and warns that the CloudFormation stacks stay in each account.

## Terraform and OpenTofu

The resource is `vulnetix_aws_connection` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_aws_connection](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/aws_connection).

Import an object that already exists by its name (`default`):

```shell
# Import an existing AwsConnection by its name (metadata.name).
terraform import vulnetix_aws_connection.default default
```

A secret is two arguments, never stored in the plan or the state: `secret_access_key_wo` (write-only) and `secret_access_key_wo_version`. Change the version number to send a new value. See [Secrets](/platform-iac/terraform.md#secrets).

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

## More examples

`examples/AwsConnection/iam-user.yaml` from `Vulnesis/config-schemas`:

```yaml
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: us-east-1
  iamUser:
    accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: { env: VULNESIS_AWS_SECRET_ACCESS_KEY }
```

`examples/AwsConnection/sso.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AwsConnection.schema.json
apiVersion: vulnetix.com/v1
kind: AwsConnection
metadata:
  name: default
spec:
  region: ap-southeast-2
  sso:
    startUrl: https://acme.awsapps.com/start
  advancedNetworking: false
```

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
