AwsConnection

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

How Vulnetix 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
Status	Served. The config engine plans and applies it.
Objects per tenant	one (`metadata.name: default`)
Token and role	An owner or admin session, or a `vmt_` config management token with the owner or admin role that lists `AwsConnection` in its kinds. See Management tokens.
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`, imported by name (see Terraform and OpenTofu)
CLI	`vulnetix config apply`, CLI v3.165.1 and later.
Pinned schema	`v1.15.0/AwsConnection.schema.json`
Newest schema	`latest/AwsConnection.schema.json`
First released in	`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-language-server: $schema=https://github.com/Vulnetix/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)

# 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"
  }
}

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnetix/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-language-server: $schema=https://github.com/Vulnetix/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: VULNETIX_AWS_SECRET_ACCESS_KEY }
  advancedNetworking: false

HCL (resource vulnetix_aws_connection)

# 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"
# }

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
export VULNETIX_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/Vulnetix/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: VULNETIX_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
`apiVersion`	string	yes		exactly `vulnetix.com/v1`		The document format version. Every kind in this release is vulnetix.com/v1.
`kind`	string	yes		exactly `AwsConnection`		Always AwsConnection.
`metadata`	object	yes		no other keys		Metadata for a kind the tenant has exactly one of. The name is fixed to default.
`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.
`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.
`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.
`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.
`spec`	object	yes		no other keys
`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.
`spec.sso`	object	no		no other keys
`spec.sso.startUrl`	string	yes		pattern `^https://[a-z0-9-]+\.awsapps\.com(/start)?/?$`		The AWS access portal URL. Stored as https://.awsapps.com/start.
`spec.iamUser`	object	no		no other keys
`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.
`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.
`spec.iamUser.secretAccessKey.env`	string	no		pattern `^[A-Za-z_][A-Za-z0-9_]*$`		Name of an environment variable.
`spec.iamUser.secretAccessKey.file`	string	no		length 1 to any		Path to a file holding the value. Trailing newlines are trimmed.
`spec.advancedNetworking`	boolean	no	`false`			Report over the private path from the customer’s accounts to Vulnetix 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: 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 and the config engine.
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.
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.

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

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

Install, authentication and how state is read: Terraform and OpenTofu.

More examples

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

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

examples/AwsConnection/sso.yaml from Vulnetix/config-schemas:

# yaml-language-server: $schema=https://github.com/Vulnetix/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. In an editor, start the file with the schema comment.